跳转至

上传与发送图标主题化

意图

让主题自行选择 FileInput 上传控件和 ChatSendButton 发送操作的图标素材,而无需重绘任何其他图标。upload 是一个共享语义图标:任何执行上传的表面都可以渲染它,每个主题都以自己的风格绘制它。send 是 ChatSendButton 的一个角色,主题会将其映射到某个共享图标。

非目标

  • 添加共享的 send 名称。
  • 更改共享 arrowUp 图标的意义或素材。
  • 更改 FileInput 或 ChatSendButton 的交互、布局、尺寸或无障碍特性。
  • 移除或更改 ChatSendButton 现有的 sendIcon 属性。
  • 更改 ChatSendButton 停止状态的图标。
  • 规定某种特定的 upload、send 或方向性图形。
  • 选择哪些其他组件渲染 upload;这由每个组件自身的契约决定。

需求

  • FR1 — upload 是共享图标。 IconName MUST 包含 upload,即从用户设备发送文件或内容的共享含义。FileInput 的上传控件 MUST 在 input 和 dropzone 两种模式下都渲染 upload。
  • FR2 — send 是 ChatSendButton 的角色。 ComponentIconSlotMap MUST 包含 chat-send-button-send。ChatSendButton 的发送状态 MUST 以 arrowUp 作为该插槽的回退来解析它。
  • FR3 — 现有实例配置保持优先。 显式的 ChatSendButton.sendIcon MUST 继续优先于当前主题的组件插槽映射。FileInput 不为其上传图标暴露任何实例属性。
  • FR4 — 主题独立绘制 upload 并映射 send。 主题可以像绘制任何共享名称一样,通过其 icons 映射绘制 upload,并可以通过 componentIcons 将 chat-send-button-send 映射到现有共享 IconName 或映射到 null。绘制 upload MUST 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