RatingView

O .NET MAUI Community Toolkit RatingView é um ItemTemplate projetado para fornecer aos desenvolvedores um mecanismo de classificação flexível e personalizável, semelhante àqueles usados em plataformas de revisão e comentários populares.

Sintaxe

Incluindo o namespace XAML

Para usar o kit de ferramentas no XAML, o xmlns a seguir precisa ser adicionado à sua página ou exibição:

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

Portanto, o seguinte:

<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>

Seria modificado para incluir o xmlns da seguinte maneira:

<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>

Usando o RatingView

O exemplo a seguir mostra como criar um 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>

O código C# equivalente é:

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;
	}
}

Propriedades

Definir caminho de formato personalizado

A CustomShapePath propriedade é uma string que permite a definição de caminhos SVG personalizados. Esse recurso permite que os desenvolvedores implementem formas SVG exclusivas, como símbolos distintos, como itens de classificação.

O exemplo a seguir define as propriedades personalizadas e de formato:

<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" />

O código C# equivalente é:

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,
};

Para obter mais informações sobre formas personalizadas, consulte Shapes.Path.

Definir cor de forma vazia

A EmptyShapeColor propriedade é uma Color para as formas de classificação não preenchidas (vazias). Isso permite uma diferenciação visual clara entre formas classificadas e não avaliadas.

O exemplo a seguir define a propriedade de cor vazia:

<toolkit:RatingView
	EmptyShapeColor="Grey" />

O código C# equivalente é:

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

Definir cor de preenchimento (avaliada)

A propriedade FillColor é uma Color que será aplicada à parte preenchida (avaliada) de cada forma, oferecendo flexibilidade para definir a estética visual dos itens de avaliação quando selecionados pelo usuário. Use FillOption para aplicar essa cor ao RatingViewFillOption.Background .RatingViewFillOption.Shape

O exemplo a seguir define a propriedade de cor de preenchimento:

<toolkit:RatingView
	FillColor="Green" />

O código C# equivalente é:

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

O conjunto é somente leitura

A propriedade IsReadOnly é uma bool que permitirá ou impedirá que o usuário modifique o valor Rating ao tocar em RatingView.

O exemplo a seguir define a propriedade is read-only:

<toolkit:RatingView
	IsReadOnly="True" />

O código C# equivalente é:

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

Definir preenchimento de forma

A propriedade ShapePadding é um Thickness para o espaçamento entre o controle de avaliação e as formas correspondentes, permitindo um controle mais preciso sobre a aparência e o layout dessas formas.

O exemplo a seguir define a propriedade de preenchimento do item:

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

O código C# equivalente é:

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

Definir o diâmetro da forma

A propriedade ShapeDiameter é um(a) double que personaliza o tamanho da forma para se adequar ao design geral do aplicativo, oferecendo flexibilidade para adaptar o controle a vários layouts de interface do usuário.

O exemplo a seguir define a propriedade padding do item:

<toolkit:RatingView
	ShapeDiameter="37" />

O código C# equivalente é:

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

Definir classificação máxima

A MaximumRating propriedade é uma int para definir o número total de itens (por exemplo, estrelas, corações, etc., ou formas personalizadas) disponíveis para classificação. Isso permite classificações de qualquer escala, como um sistema 5 estrelas ou 10 estrelas, dependendo das necessidades do aplicativo. O intervalo desse valor é de 1 a 25; o valor padrão é 5.

O exemplo a seguir define a propriedade de classificação máxima:

<toolkit:RatingView
	MaximumRating="7" />

O código C# equivalente é:

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

Definir opção de preenchimento

A propriedade FillOption é um(a) enum do tipo RatingViewFillOption para definir como o preenchimento é aplicado quando Rating é definido ou tocado, permitindo uma apresentação visual mais refinada, como preencher apenas o interior das formas ou o item inteiro. As opções disponíveis são:

• Shape - (padrão) Preencha a forma RatingView.
• Background - Preencha o plano de fundo atrás da forma

O exemplo a seguir define a propriedade de preenchimento de classificação:

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

O código C# equivalente é:

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

Definir classificação

A propriedade Rating é uma double usada para definir o valor atual da classificação, permitindo tanto classificações predefinidas (por exemplo, com base em entrada anterior do usuário ou em dados armazenados) quanto atualizações em tempo de execução, à medida que o usuário interage com o controle.

O exemplo a seguir define a propriedade de classificação:

<toolkit:RatingView
	Rating="3.73" />

O código C# equivalente é:

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

Tratar evento de alteração de avaliação

O evento RatingChanged tem o tipo de argumento RatingChangedEventArgs. O evento é gerado quando a Rating propriedade é alterada e o elemento IsReadOnly é falso.

A RatingChangedEventArgs expõe uma única propriedade:

• Rating - O novo valor de classificação.

O exemplo a seguir mostra como anexar o evento:

<toolkit:RatingView
	RatingChanged="RatingView_RatingChanged" />

O código C# equivalente é:

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

O exemplo a seguir é o código subjacente para tratar o evento:

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

Definir forma

A propriedade Shape é um(a) enum do tipo RatingViewShape para definir o formato do item de avaliação das avaliações, como estrelas, círculos, curtir, não curtir ou quaisquer outros ícones de avaliação comumente usados. As opções disponíveis são:

• Star - (padrão)
• Heart
• Circle
• Like
• Dislike
• Custom - Exige que CustomShapePath seja definido primeiro; lançará InvalidOperationException se CustomShapePath for null

O exemplo a seguir define a propriedade de preenchimento de classificação:

<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" />

O código C# equivalente é:

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,
};

Definir cor da borda da forma

O ShapeBorderColor é um Color para definir a cor da borda do formato do item de avaliação. Isso fornece flexibilidade adicional para criar formas de classificação visualmente distintas e estilizadas com bordas personalizadas.

O exemplo a seguir define a propriedade de cor da borda da forma:

<toolkit:RatingView
	ShapeBorderColor="Grey" />

O código C# equivalente é:

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

Definir espessura da borda da forma

O ShapeBorderThickness é um double para definir a espessura da borda da forma. Isso fornece flexibilidade adicional para criar formas de classificação visualmente distintas e estilizadas com bordas personalizadas.

O exemplo a seguir define a propriedade de espessura da borda da forma:

<toolkit:RatingView
	ShapeBorderThickness="3" />

O código C# equivalente é:

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

Exemplos

Você pode encontrar exemplos desse controle em ação no aplicativo de exemplo do Kit de Ferramentas da Comunidade .NET MAUI:

• Sintaxe XAML
• Sintaxe de C#
• Mostrar

API

O código-fonte do RatingView pode ser encontrado no repositório GitHub do .NET MAUI Community Toolkit.