AtomUI/docs/Desktop.Controls/Rate/RateUsage.md

Rate 使用文档

本文档介绍 AtomUI Rate 控件的各种使用方式，示例代码摘自 Gallery 演示程序。

📖 Gallery 源码位置：controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/RateShowCase.axaml

---

前置准备

在 AXAML 中使用 Rate，需要引入以下命名空间：

xmlns:atom="https://atomui.net"
xmlns:antdicons="https://atomui.net/icons/antdesign"

在 C# 代码中引入：

using AtomUI.Desktop.Controls;   // Rate
using AtomUI.Controls;            // RateValueChangedEventArgs, SizeType

---

1. 基本用法

最简单的评分，默认 5 颗星，默认值 0：

<atom:Rate />

设置默认值：

<atom:Rate DefaultValue="3" />

📖 参考：Gallery 中 "Basic" 示例。

---

2. 半星评分

通过 IsAllowHalf="True" 启用半星精度，支持 0.5 步长的评分：

<atom:Rate DefaultValue="3.5" IsAllowHalf="True" />

半星模式下：

• 鼠标位于星星左半区域时，评分为 index + 0.5
• 鼠标位于星星右半区域时，评分为 index + 1
• 键盘操作步长变为 0.5

📖 参考：Gallery 中 "Half star" 示例。

---

3. 提示文案

通过 ToolTips 属性为每颗星设置悬浮提示文案，结合 ValueChanged 事件显示当前评价描述：

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:Rate Name="ToolTipRate" ValueChanged="HandleValueChanged" />
    <TextBlock Text="{Binding ActiveTooltip}" />
</StackPanel>

// Code-behind
public partial class RateShowCase : ReactiveUserControl<RateViewModel>
{
    public RateShowCase()
    {
        this.WhenActivated(disposables =>
        {
            if (DataContext is RateViewModel viewModel)
            {
                viewModel.Tooltips = new List<string>
                {
                    "terrible", "bad", "normal", "good", "wonderful"
                };
                this.OneWayBind(viewModel, vm => vm.Tooltips, v => v.ToolTipRate.ToolTips)
                    .DisposeWith(disposables);
            }
        });
        InitializeComponent();
    }

    private void HandleValueChanged(object? sender, RateValueChangedEventArgs e)
    {
        if (DataContext is RateViewModel viewModel)
        {
            var index = (int)Math.Round(e.NewValue, MidpointRounding.AwayFromZero) - 1;
            if (viewModel.Tooltips?.Count > 0 && index >= 0)
            {
                viewModel.ActiveTooltip = viewModel.Tooltips[index];
            }
            else
            {
                viewModel.ActiveTooltip = null;
            }
        }
    }
}

📖 参考：Gallery 中 "Show copywriting" 示例 及 RateShowCase.axmal.cs。

---

4. 只读模式

设置 IsEnabled="False" 禁止交互，常用于展示已有评分：

<atom:Rate DefaultValue="2" IsEnabled="False" />

只读模式下：

• 鼠标不会变为手型
• 不响应点击和悬浮
• 不响应键盘操作
• 星星不会显示悬浮缩放效果

📖 参考：Gallery 中 "Read only" 示例。

---

5. 清除行为控制

IsAllowClear 控制是否允许再次点击相同值清除评分：

<StackPanel Spacing="20">
    <!-- 允许清除（默认） -->
    <StackPanel Orientation="Horizontal" Spacing="10">
        <atom:Rate DefaultValue="3" IsAllowClear="True" />
        <TextBlock>IsAllowClear: true</TextBlock>
    </StackPanel>
    
    <!-- 禁止清除 -->
    <StackPanel Orientation="Horizontal" Spacing="10">
        <atom:Rate DefaultValue="3" IsAllowClear="False" />
        <TextBlock>IsAllowClear: false</TextBlock>
    </StackPanel>
</StackPanel>

清除行为说明：

• IsAllowClear = true：再次点击当前评分的星星，评分清零
• IsAllowClear = false：再次点击不会改变评分，最低保持当前值

📖 参考：Gallery 中 "Clear star" 示例。

---

6. 自定义字符

通过 Character 属性替换默认星星，支持图标、字母、汉字等三种类型：

图标字符

<atom:Rate IsAllowHalf="True" IsAllowClear="True"
           Character="{antdicons:AntDesignIconProvider HeartOutlined}" />

字母字符

<atom:Rate IsAllowHalf="True" IsAllowClear="True" Character="A" />

汉字字符

<atom:Rate IsAllowHalf="True" IsAllowClear="True" Character="秦" />

📖 参考：Gallery 中 "Other Character" 示例。

---

7. 尺寸控制

通过 SizeType 属性控制星星大小，支持三种尺寸：

<!-- 大号 -->
<atom:Rate SizeType="Large" DefaultValue="3" />

<!-- 中号（默认） -->
<atom:Rate SizeType="Middle" DefaultValue="3" />

<!-- 小号 -->
<atom:Rate SizeType="Small" DefaultValue="3" />

---

8. 键盘操作

Rate 默认支持键盘操作（IsKeyboardEnabled = true）。先点击一颗星获取焦点，然后使用方向键：

• ← 左方向键：减少评分
• → 右方向键：增加评分
• 半星模式下步长为 0.5，整星模式下步长为 1

禁用键盘操作：

<atom:Rate IsKeyboardEnabled="False" />

---

9. 监听事件

监听评分值变化

myRate.ValueChanged += (sender, args) =>
{
    Console.WriteLine($"评分从 {args.OldValue} 变为 {args.NewValue}");
};

监听悬浮值变化

myRate.HoverValueChanged += (sender, args) =>
{
    Console.WriteLine($"悬浮预览: {args.NewValue}");
};

---

10. 控制动画行为

<!-- 禁用悬浮缩放动画 -->
<atom:Rate IsMotionEnabled="False" DefaultValue="3" />

---

常见组合模式

表单中的评分

<atom:FormItem Label="服务评分">
    <atom:Rate DefaultValue="3" />
</atom:FormItem>

带数值展示的评分

<StackPanel Orientation="Horizontal" Spacing="8">
    <atom:Rate Name="DisplayRate" DefaultValue="3" />
    <TextBlock Text="{Binding #DisplayRate.Value, StringFormat={}{0:0.0}}"
               VerticalAlignment="Center" />
</StackPanel>

带文案描述的评分

<StackPanel Orientation="Horizontal" Spacing="8">
    <atom:Rate Name="DescRate" DefaultValue="3"
               ValueChanged="HandleDescValueChanged" />
    <TextBlock Name="DescText" VerticalAlignment="Center" />
</StackPanel>

private readonly string[] _descriptions = { "terrible", "bad", "normal", "good", "wonderful" };

private void HandleDescValueChanged(object? sender, RateValueChangedEventArgs e)
{
    var index = (int)Math.Round(e.NewValue, MidpointRounding.AwayFromZero) - 1;
    DescText.Text = index >= 0 && index < _descriptions.Length ? _descriptions[index] : "";
}

自定义颜色的爱心评分

<atom:Rate Character="{antdicons:AntDesignIconProvider HeartOutlined}"
           StarColor="Red"
           IsAllowHalf="True"
           DefaultValue="3.5" />

MVVM 数据绑定

<atom:Rate Value="{Binding Rating, Mode=TwoWay}"
           IsAllowHalf="{Binding AllowHalf}"
           Count="{Binding MaxStars}" />

// ViewModel
[Reactive]
public double Rating { get; set; } = 3;

[Reactive]
public bool AllowHalf { get; set; } = true;

[Reactive]
public int MaxStars { get; set; } = 5;