跳转至

FileInput 组件契约

意图

FileInput 以紧凑的输入框或拖放区形式呈现一个带标签的文件选择字段。本契约记录其当前的消费者结构,并批准 FileInput 通过 Icon 绘制的上传操作元素获得独立的主题所有权。

兼容性与迁移

  • 已发布默认值保留:no;在拖放区模式中,未设置的 statusVariant 解析为 detached(FR6, DEC-2)
  • 兼容性类别:新增的公开主题化目标;不改变任何现有目标、DOM、prop、交互或无障碍行为
  • 受控/非受控行为:不变;FileInput 保持受控
  • 迁移决策:component:FileInput/DEC-1
  • 拖放区状态放置(FR6):拖放区默认为 detached;显式 statusVariant="attached" 在下一个次要版本之前保留已发布的 attached 渲染(DEC-2)

消费者迁移说明应放在消费者文档和发布说明中。

所有权边界

拥有

  • 可见的文件选择表面及其输入/拖放区模式。
  • 上传操作元素是否出现、出现位置及其默认大小。
  • 在其本地拥有的主题目标上反映 FileInput 的模式。

不拥有 / 非目标

  • 上传图形或 Icon 的基础颜色、大小和无障碍语义 — 由 component:Icon 拥有。
  • 标签、描述、清除控件和验证消息的呈现 — 由 component:Field 和 component:FieldStatus 拥有。
  • 加载指示器的呈现 — 由 component:Spinner 拥有。
  • 新 prop、变体、图标插槽或自定义属性。

公共概念

无消费者属性变更。file-input-icon 目标为上传图标提供了同一元素上的接缝,并反映现有的 mode 轴。现有的 file-input 目标仍位于可见的选择表面上,并保留其 mode 和 status 轴。

行为与布局契约

ID 候选不变量 依据 审查状态
FR1 可见的选择表面带有 file-input 并反映现有的 mode 和解析后的状态。 当前源码、公共文档和针对性测试 已验证当前行为
FR2 未加载时,输入模式以 Icon 小尺寸渲染上传操作元素。拖放区模式仅在未选择文件时以 Icon 中尺寸渲染该元素。 当前源码和针对性测试 已验证当前行为
FR3 Icon 拥有所渲染字形的基础大小、颜色和无障碍语义;FileInput 拥有该操作元素的模式相关放置位置和默认大小。 当前组合和组件边界 已验证当前组合
FR4 渲染出的上传操作元素 MUST 携带 file-input-icon 并反映现有 mode,这样主题无需结构选择器,也无需更改每一个使用相同图形的 Icon,即可重设字形框的样式。 所有者批准的目标契约 已批准的新增契约
FR5 添加该目标 MUST NOT 更改默认图形、计算后的布局、交互、文件选择行为、无障碍名称或装饰性 Icon 语义。 兼容性策略和针对性回归测试 必需的兼容行为
FR6 Dropzone 模式不提供 attached 状态放置:其高而自定义的表面无法满足 family:input-fields FR8 的 attached 条件,因此在 AV6 下它提供 detached 和 tooltip。Dropzone 默认使用 detached;显式 attached 会保留已发布的 attached 渲染,直到下一个次要版本,届时 dropzone 会将 attached 解析为 detached。输入模式继续以 attached 作为默认值。 所有者指示 2026-11-10:默认值在补丁中更改;attached 清理等待次要版本。 已批准;默认值随补丁发布,显式 attached 在下一个次要版本中解析(所有者指示 2026-11-10)

允许变化

  • AV1 — 主题绘制。 主题可通过 file-input-icon 更改标准视觉属性,例如上传字形的大小或颜色;FileInput 仍然拥有该操作提示是否渲染以及在何处渲染的决定权。
  • AV2 — 图稿。 图标注册表和未来的 icon-slot 决策可以更改图稿,而不改变此 CSS 目标对已绘制字形框的所有权。

代表性状态

状态 必需不变量 允许变化
输入,空或已选择 未加载时,输入表面上会渲染小型上传操作提示。 文件、占位符、状态、主题绘制
Dropzone,空 未加载时,占位符上方会渲染中型上传操作提示。 拖拽状态、占位符、主题绘制
Dropzone,已选择 文件名会取代上传操作提示。 文件名与状态
加载中 Spinner 会取代上传操作提示。 模式与加载呈现

转换与优先级顺序

  • ORD1 — 内容选择。 确定加载与已选文件状态,选择输入或 dropzone 内容,然后仅在 FR2 记录的状态中渲染按模式调整大小的上传操作提示。
  • ORD2 — 主题组合。 图标先应用其基础尺寸和颜色,然后同元素的 FileInput 目标参与现有主题层和标准 Icon 样式的合并顺序。

性能与资源

  • PR1 — 无新增工作。 该新增目标不执行测量、监听、观察、状态更新或额外的渲染过程。

无障碍契约

上传操作提示保持装饰性。现有的可聚焦文件选择触发器、标签、描述、必填/无效状态、禁用说明和选择公告保持不变。

设计关系

解剖结构或状态 设计需求 表示权威 层级角色 组件契约
拖放区 以输入或 dropzone 形式呈现可见的文件选择表面。 当前源代码与公开文档 突出 FR1
上传图标 提示上传操作,并根据所选模式改变默认大小。 当前源代码与所有者批准的目标 辅助 FR2, FR3, FR4
共享反馈 使用 Field、FieldStatus 和 Spinner 处理标签、验证和加载状态。 当前共享组合 辅助 FR5

主题化结构

{
  "Label": {
    "delegatesTo": {"owner": "component:Field", "target": "field-label"}
  },
  "Description": {
    "none": {
      "reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"
    }
  },
  "Drop zone": {"target": "file-input"},
  "Upload icon": {"target": "file-input-icon"},
  "Placeholder": {"inherits": "file-input"},
  "File name display": {"inherits": "file-input"},
  "Clear button": {
    "delegatesTo": {
      "owner": "component:Field",
      "target": "input-clear-button"
    }
  },
  "Spinner": {
    "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
  },
  "Status message": {
    "delegatesTo": {
      "owner": "component:FieldStatus",
      "target": "field-status"
    }
  }
}

file-input-icon 条目记录了已批准的目标状态。Icon 仍拥有通用的 icon 目标与基础字形语义;FileInput 的更窄目标仅拥有这个稳定的上传位置及其现有的模式区分。

组件族与系统关系

  • family:input-fields 负责共享的带标签字段与验证行为。
  • architecture:component-theming-surface 负责目标限定、解剖结构映射,以及公共目标必须位于稳定绘制部件上的要求。
  • Field、FieldStatus、Icon 和 Spinner 在被 FileInput 组合时保留其现有的公共目标契约。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1、FR2 FileInput.test.tsx 渲染与目标测试套件 输入/拖放区;空/已选择/加载中 移动根目标或更改可供性渲染的时机/尺寸,会破坏聚焦断言。 audit:FileInput/theming
FR3、FR4、FR5 FileInput.test.tsx、themingTargets.test.ts、探针主题检查 两种模式及同元素 Icon 目标 缺少目标、反映错误的模式,或将目标移出字形,都会导致源码/文档/探针覆盖失败。 audit:FileInput/theming
FR6 FileInput.test.tsx 中的 "defaults a dropzone status to detached" 和 "keeps an explicit attached on a dropzone until the next minor release";FileInput.doc.mjs 中的 statusVariant 条目以及 FileInput.tsx 中该 prop 的 JSDoc 拖放区未设置和显式 attached;输入模式 如果拖放区未设置时的放置状态不是 detached,拖放区在次版本之前丢弃显式 attached,或文档/JSDoc 将 attached 作为拖放区默认值提供或将其从输入模式中移除,则失败。 —
主题解剖结构映射 scripts/check-knowledge.mjs 九个解剖结构条目和两个本地拥有的目标 缺失、多余、带前缀、过期或未被认领的当前映射均无法通过验证。 audit:FileInput/anatomy

决策日志

DEC-1 — 上传图标是 FileInput 主题中稳定的解剖结构

参考: component:FileInput/DEC-1 决策者: cixzhang,2026-09-14

上传图标是一种稳定的、使用方可识别的 FileInput 可供性,其随模式变化的放置位置和默认尺寸归属于 FileInput。它在绘制字形的同一 Icon 元素上接收 file-input-icon 目标,而 Icon 保留其通用目标和基础字形语义。

DEC-2 — 拖放区默认值在补丁版本中更改;attached 的清理等待次版本

参考: component:FileInput/DEC-2 决策者: cixzhang,2026-11-10

拖放区默认使用 detached。显式的 attached 在下一个次版本之前保持其已发布的渲染效果;该次版本会将其解析为 detached。所有者问道:“9259,我们能不能出一个非破坏性版本,只更新默认值,然后把 attached 版本的清理留到次版本?”

已否决:在下一个次版本中同时针对默认值和显式 attached 做一次破坏性更改。

未决问题

无。

内容边界

本文件不重复使用方 prop 表格、示例、实现步骤或共享组件契约,而是链接到它们的所有者。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx