feat(Rate): set Value to default to TwoWay binding with data validation support

This commit is contained in:
chinboy
2026-07-06 08:38:02 +08:00
parent fdefbfd928
commit 2c695d54bb
15 changed files with 264 additions and 6 deletions
@@ -2,6 +2,14 @@
本文档记录 Rate 控件级设计、API、主题契约、Token 和实现结构的变化。它不替代仓库根目录 `CHANGELOG.md`,也不作为正式版本发布说明。
## 2026-07-06
- Behavior
- Make `Rate.Value` default to TwoWay binding and enable Avalonia data validation.
- Keep user rating, Form value and ViewModel state on the same `Value` source of truth.
- Gallery
- Add a `v6.0.8` Rate binding example showing user selection and ViewModel updates staying synchronized.
## 2026-06-26
- Docs
@@ -72,6 +72,8 @@ Public API / ItemsSource / Command / Event
- 伪类和 internal state 必须从单一 owner 推导,避免双向同步导致循环更新。
- Gallery API 表中的状态说明应与源码实际状态流一致。
`AbstractRate.Value` 是评分控件的 Form value 和当前评分 source of truth。属性注册默认 `BindingMode.TwoWay` 并启用 Avalonia data validation;pointer、keyboard 和 Form set/clear 都应更新 `Value`,再由 `Value` 回放到 `EffectiveValue` 和 `RateItem.SelectedState`。
## 5. 生命周期与模板接入
生命周期规则:
@@ -106,6 +108,7 @@ Rate 的交互事件应从输入源收敛到控件级语义事件:
- Template part 重新应用时的状态回放。
- 主题资源、Token 和 SharedToken 计算后的视觉更新。
- 内容、命令和视觉状态在模板节点之间的同步。
- `Value` 的 ViewModel 更新、用户评分、Form set/get/clear、`ValueChanged` 和 hover 状态通知。
- 动效启停、初始加载阶段 transition 抑制和卸载取消。
实现文档不逐行解释私有方法。若某个私有算法成为稳定维护入口,应在本节补充算法不变量,而不是把代码复述为说明书。
@@ -78,6 +78,7 @@ Public API / inherited command / item source / user input
- Disabled 或不可交互状态优先屏蔽 pointer、keyboard、motion 和提交类反馈。
- selection/checked/active、input/value、motion、visual option 状态由控件实例或明确的数据 owner 推导,不能在 template part 之间双向竞争。
- `Rate.Value` 是评分控件的外部值 owner,默认 `BindingMode.TwoWay` 并启用 Avalonia data validation;用户评分、键盘调整、Form value 和 ViewModel 更新必须收敛到同一份数值状态。
- 模板重套用时必须把 public API 对应状态回放到新的 part、伪类和主题变量。
- 集合、弹层、异步、动效或窗口相关状态必须能处理 reset、close、cancel、detach 和 owner 释放。
@@ -138,6 +139,8 @@ Rate 与同分类控件共享尺寸、状态、Token、Gallery 展示和验证
Rate 的当前项状态必须由单一 owner 推导。public 选择属性、集合项容器和伪类之间只能做单向同步,集合替换、清空和模板重套用时必须回放当前状态。
`Value` 作为 Form value 和受控评分值暴露给用户。控件从 `Value` 同步 `EffectiveValue` 与每个 `RateItem.SelectedState`,也会在 pointer 或 keyboard 交互后更新 `Value`,默认绑定模式负责把该值回写到 ViewModel。
### 8.2 动效模型
Rate 的动效只表达状态变化反馈,不应改变 public API 语义。初始加载、禁用态和卸载路径应能抑制或取消动效,避免保留旧控件实例。