RatingView

2025-04-14

.NET MAUI 社区工具包 RatingView 旨在 ItemTemplate 为开发人员提供灵活且可自定义的分级机制，类似于在常用评审和反馈平台上使用的机制。

语法

包括 XAML 命名空间

若要在 XAML 中使用工具包，需要将以下 xmlns 添加到页面或视图中：

xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"

因此，以下内容：

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">

</ContentPage>

将被修改为包括 xmlns，如下所示：

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">

</ContentPage>

使用 RatingView

下面的示例演示如何创建一个 RatingView：

RatingView 示例的屏幕截图

<ContentPage
	x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
	xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
	xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
	xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">
	<VerticalStackLayout>
		<toolkit:RatingView
			EmptyShapeColor="White"
			FillColor="Blue"
			FillOption ="Shape"
			IsReadOnly="False"
			ShapePadding="3,7,7,3"
			ShapeDiameter="37"
			MaximumRating="5"
			Rating="4.5"
			Shape="Star"
			ShapeBorderColor="Red"
			ShapeBorderThickness="1"
			Spacing="3" />
	</VerticalStackLayout>
</ContentPage>

等效的 C# 代码为：

using CommunityToolkit.Maui.Views;

partial class MyPage : ContentPage
{
	public MyPage()
	{
		RatingView ratingView = new()
		{
			EmptyShapeColor = Colors.White,
			FillColor = Colors.Blue,
			FillOption = RatingViewFillOption.Shape,
			IsReadOnly = false,
			ShapePadding = new Thickness(3,7,7,3),
			ShapeDiameter = 37,
			MaximumRating = 5,
			Rating = 4.5,
			Shape = RatingViewShape.Star,
			ShapeBorderColor = Colors.Red,
			ShapeBorderThickness = 1,
			Spacing = 3,
		};

		Content = ratingView;
	}
}

性能

财产	类型	说明
CustomShapePath	`string`	获取或设置自定义分级视图形状的 SVG 路径。这是一种可绑定属性。
EmptyShapeColor	`Color`	获取或设置应用于未填充（空）评分形状的颜色。默认值为透明。这是一种可绑定属性。
FillColor	`Color`	获取或设置用于显示当前评分的填充颜色。设置为 `FillOption` 可将此颜色应用于 `RatingViewFillOption.Background` 或 `RatingViewFillOption.Shape`。默认值为 Yellow。这是一种可绑定属性。
IsReadOnly	`bool`	获取此布局是否为只读。默认值为 false。这是一种可绑定属性。
形状	`RatingViewShape`	获取或设置评分项形状。属性的类型是`RatingViewShape`，并且它是一个枚举。默认值为 Star。这是一种可绑定属性。
ShapeDiameter	`double`	获取或设置形状直径（以磅为单位）。默认值为 20。
最高评分	`int`	获取或设置最大评分数。此值的范围为 1 到 25;默认值为 5。这是一种可绑定属性。
评分已改变	`EventHandler<RatingChangedEventArgs>`	更改分级时发生事件。
FillOption	`RatingViewFillOption`	获取或设置评分时要填充的元素。该属性的类型是 `RatingViewFillOption`，并且是一个枚举。此属性的默认值为 `RatingViewFillOption.Shape`。这是一种可绑定属性。
评级	`double`	获取或设置一个值，该值指示当前分级值，以便在用户与控件交互时同时允许预定义的分级（例如，来自以前的用户输入或存储的数据）和更新。默认值为 0。这是一种可绑定属性。
ShapeBorderColor	`Color`	获取或设置评分项形状的边框颜色。默认值为灰色。这是一种可绑定属性。
ShapeBorderThickness	`Thickness`	获取或设置评分项形状的边框粗细。默认值为粗细，所有值都设置为 1。这是一种可绑定属性。

小提示

可以在 HorizontalStackLayout 类中找到其他基类属性。

设置自定义形状路径

CustomShapePath 属性是允许定义自定义 SVG 路径的 string。此功能使开发人员能够实现独特的 SVG 形状，如特殊符号，作为评分项目。

重要

CustomShapePath 仅在 Shape 属性设置为 Shape.Custom 时使用。如果 CustomShapePath 为 null，则设置 Shape.Custom 将会引发异常 InvalidOperationException：无法绘制 RatingViewShape.Custom，因为 CustomShapePath 为 null。请提供 CustomShapePath 的 SVG 路径。

以下示例设置自定义属性和形状属性：

RatingView 自定义形状示例的屏幕截图

<toolkit:RatingView
	CustomShapePath ="M 12 0C5.388 0 0 5.388 0 12s5.388 12 12 12 12-5.38 12-12c0-6.612-5.38-12-12-12z"
	Shape="Custom" />

等效的 C# 代码为：

RatingView ratingView = new()
{
	CustomShapePath = "M 12 0C5.388 0 0 5.388 0 12s5.388 12 12 12 12-5.38 12-12c0-6.612-5.38-12-12-12z",
	Shape = RatingViewShape.Custom,
};

有关自定义形状的详细信息，请参阅 Shapes.Path。

设置空形状颜色

EmptyShapeColor 属性是未填充（空）评分形状的 Color。这使得可以在分级形状和未分级形状之间进行清晰的视觉上的区分。

以下示例设置空颜色属性：

<toolkit:RatingView
	EmptyShapeColor="Grey" />

等效的 C# 代码为：

RatingView ratingView = new()
{
	EmptyShapeColor = Colors.Grey,
};

设置填充（评分）颜色

该 FillColor 属性 Color 将应用于每个形状的填充（分级）部分，从而在用户选择时灵活地定义分级项的视觉美学。使用FillOption将此颜色应用于RatingViewFillOption.Background或RatingViewFillOption.Shape。

以下示例设置填充的颜色属性：

<toolkit:RatingView
	FillColor="Green" />

等效的 C# 代码为：

RatingView ratingView = new()
{
	FillColor = Colors.Green,
};

设置是只读的

IsReadOnly 属性是一个 bool，将允许或禁止用户通过点按 RatingView 修改 Rating 值。

以下示例设置只读属性：

<toolkit:RatingView
	IsReadOnly="True" />

等效的 C# 代码为：

RatingView readOnlyRatingView = new()
{
	IsReadOnly = True,
};

设置形状填充

ShapePadding 属性是一个 Thickness，用于设置评分控件及其相关形状之间的填充，从而实现对评分形状外观和布局的精细调整。

以下示例设置项填充属性：

<toolkit:RatingView
	ShapePadding="3, 7, 7, 3" />

等效的 C# 代码为：

RatingView ratingView = new()
{
	ShapePadding = new Tickness(3, 7, 7, 3),
};

设置形状直径

该 ShapeDiameter 属性自定义 double 形状大小以适应应用程序的整体设计，从而灵活地将控件调整到各种 UI 布局。

以下示例设置项填充属性：

<toolkit:RatingView
	ShapeDiameter="37" />

等效的 C# 代码为：

RatingView ratingView = new()
{
	ShapeDiameter = 37,
};

设置最大分级

MaximumRating 属性是一个 int，用于设置可用于评分的项总数（例如星形、心形等或自定义形状）。这允许任何规模的分级，例如 5 星或 10 星系统，具体取决于应用程序的需求。此值的范围为 1 到 25;默认值为 5。

注释

如果该值设置为 1，则单击/点击时，控件会将分级切换为 0 到 1。如果该值设置为低于当前 Rating值，则会相应地调整分级。

以下示例设置最大分级属性：

<toolkit:RatingView
	MaximumRating="7" />

等效的 C# 代码为：

RatingView ratingView = new()
{
	MaximumRating = 7,
};

设置填充选项

FillOption 属性是 RatingViewFillOption 类型的 enum，用于设置在设置或点击 Rating 时如何应用填充，从而实现更细致的视觉表现，例如仅填充形状的内部或整个项。可用选项包括：

Shape - （默认值）填充 RatingView 形状。
Background - 在形状后面填充背景

以下示例设置评分填充属性：

RatingView 分级填充示例的屏幕截图

<toolkit:RatingView
	FillOption="Shape" />
<toolkit:RatingView
	FillOption ="Background" />

等效的 C# 代码为：

RatingView shapeFillRatingView = new()
{
	FillOption = RatingViewFillOption.Shape,
};
RatingView itemFillRatingView = new()
{
	FillOption = RatingViewFillOption.Background,
};

设置分级

该 Rating 属性 double 用于设置当前分级值，允许在用户与控件交互时同时设置预定义的分级（例如，来自以前的用户输入或存储的数据）和更新。

以下示例设置评级属性：

<toolkit:RatingView
	Rating="3.73" />

等效的 C# 代码为：

RatingView ratingView = new()
{
	Rating = 3.73,
};

处理评分更改事件

事件 RatingChanged 具有参数类型 RatingChangedEventArgs。当 Rating 属性发生更改且元素 IsReadOnly 为 false 时，将引发该事件。

RatingChangedEventArgs 会公开一个属性：

Rating - 新的分级值。

以下示例演示如何附加事件：

<toolkit:RatingView
	RatingChanged="RatingView_RatingChanged" />

等效的 C# 代码为：

	RatingView ratingView = new();
	ratingView.RatingChanged += RatingView_RatingChanged;

以下示例是用于处理事件的后台代码：

void RatingView_RatingChanged(object sender, RatingChangedEventArgs e)
{
	double newRating = e.Rating;
	// The developer can then perform further actions (such as save to DB).
}

设置形状

该 Shape 属性是类型为 RatingViewShape 的 enum ，用于设置评分项的形状，例如星形、圆圈、喜欢、不喜欢或任何其他常用的评分图标。可用选项包括：

Star - （默认值）
Heart
Circle
Like
Dislike
Custom - 需要CustomShapePath首先定义；如果CustomShapePath为null，将抛出InvalidOperationException

以下示例设置评分填充属性：

RatingView 形状示例屏幕截图

<toolkit:RatingView
	Shape="Star" />
<toolkit:RatingView
	Shape="Heart" />
<toolkit:RatingView
	Shape="Circle" />
<toolkit:RatingView
	Shape="Like" />
<toolkit:RatingView
	Shape="Dislike" />
<toolkit:RatingView
    CustomShapePath="M 12 0C5.388 0 0 5.388 0 12s5.388 12 12 12 12-5.38 12-12c0-6.612-5.38-12-12-12z"
	Shape="Custom" />

等效的 C# 代码为：

RatingView starRatingView = new()
{
	Shape = RatingViewShape.Star,
};
RatingView heartRatingView = new()
{
	Shape = RatingViewShape.Heart,
};
RatingView circleRatingView = new()
{
	Shape = RatingViewShape.Circle,
};
RatingView likeRatingView = new()
{
	Shape = RatingViewShape.Like,
};
RatingView dislikeRatingView = new()
{
	Shape = RatingViewShape.Dislike,
};
RatingView customRatingView = new()
{
    CustomShapePath = "M 12 0C5.388 0 0 5.388 0 12s5.388 12 12 12 12-5.38 12-12c0-6.612-5.38-12-12-12z",
	Shape = RatingViewShape.Custom,
};

设置形状边框颜色

ShapeBorderColor 是用于设置评分项形状边框颜色的 Color。这样，便可以灵活地使用自定义边框创建视觉上不同的分级形状和风格化分级形状。

以下示例设置形状边框颜色属性：

<toolkit:RatingView
	ShapeBorderColor="Grey" />

等效的 C# 代码为：

RatingView ratingView = new()
{
	ShapeBorderColor = Colors.Grey,
};

设置形状边框粗细

ShapeBorderThickness 是用于设置形状边框粗细的 double。这样，便可以灵活地使用自定义边框创建视觉上不同的分级形状和风格化分级形状。

以下示例设置形状边框粗细属性：

<toolkit:RatingView
	ShapeBorderThickness="3" />

等效的 C# 代码为：

RatingView ratingView = new()
{
	ShapeBorderThickness = 3,
};

例子

可以在 .NET MAUI 社区工具包示例应用程序中查找此控件的示例：

应用程序编程接口 (API)

可以在 RatingView中找到的源代码。

通过

RatingView

语法

包括 XAML 命名空间

使用 RatingView

性能

设置自定义形状路径

设置空形状颜色

设置填充（评分）颜色

设置是只读的

设置形状填充

设置形状直径

设置最大分级

设置填充选项

设置分级

处理评分更改事件

设置形状

设置形状边框颜色

设置形状边框粗细

例子

应用程序编程接口 (API)

反馈

其他资源