上传与发送图标主题化¶
意图¶
让主题自行选择 FileInput 上传控件和 ChatSendButton 发送操作的图标素材,而无需重绘任何其他图标。upload 是一个共享语义图标:任何执行上传的表面都可以渲染它,每个主题都以自己的风格绘制它。send 是 ChatSendButton 的一个角色,主题会将其映射到某个共享图标。
非目标¶
- 添加共享的
send名称。 - 更改共享
arrowUp图标的意义或素材。 - 更改 FileInput 或 ChatSendButton 的交互、布局、尺寸或无障碍特性。
- 移除或更改 ChatSendButton 现有的
sendIcon属性。 - 更改 ChatSendButton 停止状态的图标。
- 规定某种特定的 upload、send 或方向性图形。
- 选择哪些其他组件渲染
upload;这由每个组件自身的契约决定。
需求¶
- FR1 — upload 是共享图标。
IconNameMUST 包含upload,即从用户设备发送文件或内容的共享含义。FileInput 的上传控件 MUST 在 input 和 dropzone 两种模式下都渲染upload。 - FR2 — send 是 ChatSendButton 的角色。
ComponentIconSlotMapMUST 包含chat-send-button-send。ChatSendButton 的发送状态 MUST 以arrowUp作为该插槽的回退来解析它。 - FR3 — 现有实例配置保持优先。 显式的
ChatSendButton.sendIconMUST 继续优先于当前主题的组件插槽映射。FileInput 不为其上传图标暴露任何实例属性。 - FR4 — 主题独立绘制 upload 并映射 send。 主题可以像绘制任何共享名称一样,通过其
icons映射绘制upload,并可以通过componentIcons将chat-send-button-send映射到现有共享IconName或映射到null。绘制uploadMUST NOT 更改arrowUp或任何其他共享名称,映射 send 插槽 MUST NOT 更改upload。 - FR5 — 默认行为保持几何与无障碍特性。 当主题没有为
upload提供素材时,FileInput MUST 以现有的尺寸、位置、颜色和无障碍行为渲染默认的upload素材。该默认素材 MUST 描绘上传动作,且 MUST 能与arrowUp区分。当没有插槽映射且没有sendIcon时,ChatSendButton MUST 以现有的尺寸、位置和无障碍行为渲染arrowUp。Sortable Table 及所有其他arrowUp使用方 MUST 保持不变。 - FR6 — 每个随附的注册表都绘制 upload。 默认注册表、每个捆绑主题以及每个 CLI 主题模板 MUST 以该注册表自身的风格提供
upload素材。公共IconRegistry类型描述一个完整的注册表,且 MUST 像对待其他共享名称一样要求包含upload。使用者通过添加一个以其注册表风格绘制的upload条目来完成迁移。 - IR1 — 相关表面保持同步。 对于 upload:
IconName、默认注册表、每个捆绑主题和 CLI 主题模板、已记录的共享图标名称列表、FileInput 源码与文档,以及聚焦的注册表和 FileInput 测试 MUST 一起变更。对于 send:公共组件插槽映射、ChatSendButton 源码、其组件文档与当前契约,以及聚焦的解析器和组件测试 MUST 一起变更。
平台支持¶
- 支持的功能/引擎下限:与当前图标解析器保持不变。
- 不支持的行为:保持不变;没有
upload素材或 send 插槽映射的主题使用默认素材或组件回退。 - 浏览器证据:FileInput 的默认字形会改变,因此真实浏览器视觉证据 MUST 展示随附主题中 FileInput 的两种模式都以不变的几何渲染 upload 素材。ChatSendButton 的默认行为无需证据,因为其素材和几何均不改变;解析器和组件测试覆盖插槽优先级与回退。
当前状态影响¶
当前 main 分支对这两种角色都直接渲染共享的 arrowUp 图标:
| 所有者 | 实例覆盖 | 主题控制 | 默认 |
|---|---|---|---|
| FileInput 上传控件 | 无 | icons.upload |
默认 upload 素材 |
| ChatSendButton 发送状态 | sendIcon |
chat-send-button-send 插槽 |
arrowUp |
FileInput 的默认字形从方向箭头变为 upload 素材;其尺寸、位置、颜色和无障碍行为保持不变。FileInput 不再跟随主题的 arrowUp 素材:主题通过 upload 重新设计其样式,而没有 upload 素材的主题在该处显示默认的 upload 素材。ChatSendButton 保留其默认素材,并在该插槽实现后解析自己的插槽。每个 Astryx 随附的注册表都会新增 upload 条目,完整注册表要求包含 upload(FR6)。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1 | 图标公共类型与注册表测试;渲染后的 FileInput 测试 | 默认注册表、主题 icons.upload、input 与 dropzone 模式 |
若 IconName 缺少 upload、FileInput 读取其他名称,或主题 upload 素材未到达 FileInput,则失败。 |
| FR2–FR3 | 组件槽位类型与解析器测试;渲染后的 ChatSendButton 优先级测试 | 默认主题、映射名称、显式 null、显式 sendIcon |
缺失或拼写错误的槽位、直接查找 arrowUp、忽略映射,或主题覆盖了调用方内容,均失败。 |
| FR4 | 使用独立主题覆盖的注册表解析测试 | 主题仅绘制 upload;主题仅映射发送槽位 |
主题 upload 美术资源改变了 arrowUp 或其他名称,或发送映射改变了 upload,均失败。 |
| FR5 | 聚焦的 FileInput 和 ChatSendButton 测试;现有 Table 测试;真实浏览器可视化证据 | 无主题与随附主题;浅色与深色;输入、拖放区、发送与排序 | 几何形状或无障碍输出发生变化,upload 默认值与 arrowUp 相同,或任何 arrowUp 使用方发生变化,均失败。 |
| FR6 | 公开类型测试;对默认注册表、随附主题和 CLI 主题模板的注册表完整性测试;主题回退测试 | 完整注册表;没有 upload 美术资源的主题 |
随附注册表缺少 upload、完整注册表缺少 upload 却仍能编译,或省略的 upload 渲染为空,均失败。 |
| IR1 | pnpm check:knowledge、聚焦的文档/源码一致性断言 |
共享图标名称列表、组件文档、当前合约、公开类型 | 过时的属主表面或未记录的共享名称会阻止实现。 |
决策日志¶
DEC-1 — Send 是 ChatSendButton 的角色¶
参考: spec:AST-032/DEC-1
决策人: cixzhang,2026-09-22;修订于 2026-10-05
ChatSendButton 的发送动作是组件自有的角色。在当前组件图标架构下,它接收
chat-send-button-send 槽位,以 arrowUp 作为兼容性回退,且现有 sendIcon
prop 仍是最高优先级的选项。
已拒绝:继续直接读取 arrowUp,因为那样主题将无法在不重绘每个 arrowUp 的情况下选择发送图标。
DEC-2 — Upload 是共享图标¶
参考: spec:AST-032/DEC-2
决策人: cixzhang,2026-10-05
上传是一种通用动作,其常规字形与方向箭头不同。作为共享名称,upload 在
每个主题中以该主题的风格绘制一次,且每个执行上传的表面都渲染相同的主题绘制
字形。共享名称是永久的公开词汇,因此应依据属主的设计方向添加,而非依据当前
使用方的数量。upload 符合这一标准:设计师需要绘制真正的上传字形,而现有
共享名称均无法承载它。
已拒绝:file-input-upload 组件槽位,因为槽位只能映射到现有共享名称,因此
无法拥有自己的上传美术资源。
DEC-3 — 完整注册表必须包含 upload¶
参考: spec:AST-032/DEC-3
决策人: cixzhang,2026-10-05
完整注册表列出每个共享名称,因此 IconRegistry 与其他名称一样要求 upload:
一个能通过类型检查的完整主题注册表会以自身风格绘制 upload,而不是静默借用
默认美术资源。
已拒绝:永久可选的 upload,因为那将是唯一一个完整注册表可以省略的共享名称。
弃用与清理记录¶
DEP-0012 — 弃用省略 upload 的完整 IconRegistry 类型¶
| 字段 | 值 |
|---|---|
| id | DEP-0012 |
| cleanup | CLN-0021 |
| package | @astryxdesign/core |
| surface | 公开的 IconRegistry 类型,接受省略 upload 的完整注册表 |
| old contract | 被类型化为 IconRegistry 的完整注册表可省略 upload;被省略的条目解析为默认美术资源 |
| replacement | 在注册表中以自身风格添加 upload 条目;IconRegistry 已接受该条目 |
| direct authority | FR6 和 DEC-3。属主:spec:AST-032:cixzhang、imdreamrunner |
| warning | 消费者文档和发布说明中提及 DEP-0012。无运行时警告(spec:AST-017 FR29) |
| migration | 非机械性:以注册表风格绘制 upload 美术资源 |
| codemod | 无:图标美术资源对每个主题都是定制的,无法自动合成 |
| 下游 | 默认注册表、所有内置主题以及所有 CLI 主题模板均提供 upload |
| 过渡 | 无先前过渡 |
| 状态 | deprecated |
| 开放决策 | 除在次要版本计划中列出 CLN-0021 外,无其他 |
| 目标计划 | 按照 FR6 的安排,在下一个次要版本中落地 CLN-0021 |
CLN-0021 — IconRegistry 要求提供 upload¶
| 字段 | 值 |
|---|---|
| ID | CLN-0021 |
| 生命周期 | DEP-0012 |
| 变更 | IconRegistry 是 Record<IconName, ReactNode>:缺少 upload 的完整注册表将无法通过类型检查 |
| 回滚 | 从最终补丁基线中恢复过渡期的可选 upload |
| 状态 | pending — 在声明的次要版本中落地,并附带其 [breaking] Changeset |
未决问题¶
无。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx