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