Edytuj

Udostępnij za pośrednictwem

Rating control

  • Artykuł

The rating control allows users to view and set ratings that reflect degrees of satisfaction with content and services. Users can interact with the rating control with touch, pen, mouse, gamepad, or keyboard. The follow guidance shows how to use the rating control's features to provide flexibility and customization.

Example of Rating Control

Overview

The rating control can be used to enter a rating, or made read-only to display a rating.

Editable rating with placeholder value

Perhaps the most common way to use the rating control is to display an average rating while still allowing the user to enter their own rating value. In this scenario, the rating control is initially set to reflect the average satisfaction rating of all users of a particular service or type of content (such as a music, videos, books, etc.). It remains in this state until a user interacts with the control with the goal of individually rating an item. This interaction changes the state of the ratings control to reflect the user's personal satisfaction rating.

Initial average rating state

Initial Average Rating State

Representation of user rating once set

Representation of User Rating Once Set

Read-only rating mode

Sometimes you need to show ratings of secondary content, such as that displayed in recommended content or when displaying a list of comments and their corresponding ratings. In this case, the user shouldn't be able to edit the rating, so you can make the control read-only. The read only mode is also the recommended way of using the rating control when it is used in very large virtualized lists of content, for both UI design and performance reasons.

Read-Only Long List

Create a rating control

Open the WinUI 3 Gallery app and see RatingControl in action

The WinUI 3 Gallery app includes interactive examples of most WinUI 3 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub

Editable rating control

This code shows how to create an editable rating control with a placeholder value.

<RatingControl x:Name="MyRating" ValueChanged="RatingChanged"/>

private void RatingChanged(RatingControl sender, object args)
{
    if (sender.Value == null)
    {
        MyRating.Caption = "(" + SomeWebService.HowManyPreviousRatings() + ")";
    }
    else
    {
        MyRating.Caption = "Your rating";
    }
}

Read-only rating control

This code shows how to create a read-only rating control.

<RatingControl IsReadOnly="True"/>

Additional functionality

The rating control has many additional features which can be used. Details for using these features can be found in our reference documentation. Here is a non-comprehensive list of additional functionality:

  • Great long list performance
  • Compact sizing for tight UI scenarios
  • Continuous value fill and rating
  • Spacing customization
  • Disable growth animations
  • Customization of the number of stars

UWP and WinUI 2

Important

The information and examples in this article are optimized for apps that use the Windows App SDK and WinUI 3, but are generally applicable to UWP apps that use WinUI 2. See the UWP API reference for platform specific information and examples.

This section contains information you need to use the control in a UWP or WinUI 2 app.

The RatingControl for UWP apps is included as part of WinUI 2. For more info, including installation instructions, see WinUI 2. APIs for this control exist in both the Windows.UI.Xaml.Controls and Microsoft.UI.Xaml.Controls namespaces.

We recommend using the latest WinUI 2 to get the most current styles, templates, and features for all controls.

To use the code in this article with WinUI 2, use an alias in XAML (we use muxc) to represent the Windows UI Library APIs that are included in your project. See Get Started with WinUI 2 for more info.

xmlns:muxc="using:Microsoft.UI.Xaml.Controls"

<muxc:RatingControl />