# 自定义控件参考

# 先确定结构

自定义前先决定控件是按钮、容器、弹窗、折叠区、进度条、数字输入、滑动条还是开关。类型决定可用字段和子控件结构。

# 配置层次

层次	字段/操作	注意
内容	名称、别名、简介、按钮文字、提示、详情	固定文案应可翻译
资源	图标、图片、音效	使用项目资源 ID
布局	控件类型、子控件、子菜单、位置	先结构后细节
样式槽位	目标区域、样式规则、状态样式	不要把全局规则复制到每个控件
反馈	成功/失败文本、结果弹窗、关闭弹窗	与规则结果一致
高级	隐藏、始终显示、冷却、确认、脚本	明确触发和清理

# 从语义到表现逐层搭建

1. 命名语义动作或展示责任。
2. 选择控件类型以及权威数值/动作所有者。
3. 建立父子关系、重复对象上下文和弹窗边界。
4. 绑定需求、花费/获得、输入范围或插件行为。
5. 固定文案接入项目翻译，并选择真实项目资源。
6. 配置样式槽和交互状态。
7. 成功/失败逻辑正确后，再添加特效和音频。

顺序反过来会让样式遮住不完整的动作合同。一个外观精致的自定义控件，如果键盘焦点、取消路径、对象身份或重复提交没有定义，依然是不完整的。

# 结构与交互合同

控件类型	必须定义
按钮/动作	需求、事务所有者、重复锁、成功/失败反馈
容器	子项归属、顺序、溢出和响应式行为
弹窗/子弹窗	打开者、焦点、确认/取消、关闭与清理
折叠区	初始状态、可访问切换、状态保存边界
进度显示	权威值、最大/最小和空/无效回退
数字输入/滑动条	可写目标、范围、步长和验证时机
开关	布尔映射、写入拒绝回滚和可见标签
重复对象行	类、稳定对象 ID、空列表/销毁行为

# 对象控件

对象列表项应绑定类和当前对象，显示对象名、描述和指定属性。列表重排后不要用数组下标保存身份；操作目标使用对象 ID。

# 样式执行顺序

基础页面样式先应用，控件样式槽位再覆盖，状态样式最后根据显示、禁用和悬停状态切换。移动端需要单独验证长文本、按钮宽度和弹窗滚动。

# 可访问性与响应式证据

• 键盘焦点能按合理顺序到达控件。
• 标签无需只依赖颜色或图标就能描述动作。
• 禁用外观与运行时可用性一致。
• 触摸目标在窄屏不重叠且容易操作。
• 长翻译能换行，不会意外改变动作点击区。
• 弹窗从所有支持路径都能关闭并恢复焦点。
• 加载和异步提交不会推挤邻近布局或重新开放重复操作。

# 常见失败

现象	原因
样式作用到错误区域	选错样式槽或选择器责任重复
对象行操作指向另一项	复用 key/下标而不是稳定对象 ID
隐藏内容仍可交互	可见性样式没有禁用语义动作
报错后弹窗无法关闭	只在成功路径执行清理
移动端按钮文字溢出	固定宽度无法容纳翻译

# 迁移风险与验收

不要用详情文本承载规则状态；不要在样式脚本里修改存档。替换控件类型前保存版本并检查子控件引用。验收默认、悬停、禁用、成功、失败、对象为空、弹窗关闭和窄屏。

下一页：重置功能。