ChatComposerInput 组件契约¶
契约概览¶
| 方面 | 契约 |
|---|---|
| 公共契约 | ChatComposerInput 仍是 ChatComposer 的可选富编辑表面,提供受控的草稿、触发、历史、粘贴、文件和命令式接缝。每个触发定义可选择启用多词查询 hasMultiWordQuery,默认 false。enterKeyHint(EnterKeyHint,默认 send)标记触摸键盘的 Return 键(FR17)。 |
| 行为 | 每条编辑路径都保持序列化草稿可观察。粘贴或拖放的文件到达 onFiles;消费者的 onPaste 对纯文本拥有优先否决权,之后才进行可选的粘贴即 token 转换。 |
| 终端用户影响 | 听写或以其他方式以编程方式插入的文本可发送,且绝不会隐藏在空占位符后面;拖放的文件进入产品附件流。在手机上,Return 键显示 Send(发送),这正是 Enter 的作用。 |
| 构建方影响 | 现有 props、回调签名、导出和 token 序列化保持不变。依赖于已文档化的 onPaste 和 onFiles 路径的构建方会收到这些回调,除非 FR5 和 FR6 记录了实现缺口;hasMultiWordQuery 是一个新增的可选触发字段,enterKeyHint 是一个新增的可选 prop,其 send 默认值由让 Enter 插入换行的编辑器替换为 enter(FR17)。每个触发都会收到兼容性与迁移部分中列出的触发键修正(FR10、FR13、FR15、FR16)。 |
| 兼容性/就绪度 | 补丁兼容。一个新增的可选触发字段(DEC-1),一个带有键盘提示默认值的新增可选 prop(DEC-2,属于 spec:AST-017 FR5、FR7 下的补丁 [feat]),以及适用于每个触发的触发键修正(FR10、FR13、FR15、FR16);无视觉决策。实现缺口已内联记录于 FR5、FR6、FR10 和 PR2。 |
| 审查检查 | 拒绝以下情况:某条编辑路径在未更新序列化草稿的情况下变更 DOM;文件拖放可能导航离开或绕过 onFiles;文本粘贴绕过消费者拦截;更改提交/token 语义;触发查询改动已输入的文本;某个键从较早触发查询结果中选取一行;菜单在发送后重新打开;Return 键标签改变 Enter 的实际行为;enterKeyHint 类型接受任意字符串。 |
| 治理规则 | architecture:public-component-api/INV1、INV2–INV4、INV25;architecture:interaction-modality/INV1–INV4;architecture:knowledge-contracts/INV11, INV16;spec:AST-002;spec:AST-029;component:TextInput/FR16, DEC-1;rubric B15。 |
此表是审查投影;下文正文为权威内容。
意图¶
ChatComposerInput 为 ChatComposer 提供富编辑表面,适用于普通自定义 textarea 不够用的情况。它负责 contenteditable 文本和选区、序列化内联 token、触发菜单、历史召回、粘贴与文件接收,以及命令式编辑句柄。
兼容性与迁移¶
- 发布的默认值保留:是
- 兼容性类别:补丁兼容;一个新增的可选触发字段,一个新增的可选 prop
enterKeyHint,其send默认值是触摸键盘提示,不改变 Enter 的实际行为(补丁[feat],spec:AST-017FR5、FR7;enterKeyHint="enter"保留普通 Return 键),以及适用于每个触发的触发键修正 - 受控与组合行为:不变
- 迁移决策:无
- 触发查询形态:
hasMultiWordQuery是一个新增的可选触发字段;省略它则保持单 token 查询 - 每个触发,无论是否选择加入,也都会收到这些补丁兼容的修正:
- FR13,修正:某个键绝不会选中为较早查询返回的行;在发送、清除、选中或关闭后到达的结果会被丢弃,而不是重新打开菜单。
- FR15,修正:IME 组合键绝不会选中某一行或移动高亮行。
- FR16,修正:按 Escape 后,在同一查询继续增长时菜单保持隐藏,而不是在下次按键时重新打开。
- FR10,修正:触发字符前的 Tab 是一个边界,就像空格或换行一样。
所有权边界¶
拥有
- contenteditable 编辑区表面、其可访问的编辑语义及序列化。
- 编辑器内的触发器菜单调用和 Token 插入。
- Enter 提交、历史记录导航、粘贴优先级、文件接收及命令式编辑可观察性。
- 向 ChatComposer 注册编辑焦点控件。
- 编辑器上触屏键盘的 Return 键标签(FR17)。
不拥有 / 非目标
- ChatComposer 布局、发送按钮状态、状态位或外壳层级。
- 文件的产品级校验、上传、进度或错误处理。
- 由调用方提供的搜索结果数据、自定义 Token 含义或自定义 Token 交互语义。
- 为编辑器、Token、菜单或放置目标提供新的视觉表现。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 草稿存储 | DOM 所有;value 受控;ChatComposer 上下文受控 |
选择序列化的草稿来源与可观察的变更通道。 | 每个编辑器 | 上下文或空 DOM | component:ChatComposerInput |
稳定 | 显式 value 优先;不支持的值会被 TypeScript 拒绝。 |
| 提交 | Enter;Shift+Enter;IME Enter;消费者取消的 Enter | 仅在未取消、不带 Shift 且非组合输入的 Enter 上提交一份去除首尾空白后的非空草稿。 | 启用的编辑器 | Enter 提交 | component:ChatComposerInput |
稳定 | 空提交或组合输入中的提交会被忽略。 |
| 触发器菜单 | 省略;一个或多个触发器定义 | 在配置的字符处打开建议,并插入文本或序列化 Token。 | 当配置了触发器时 | 省略 | component:ChatComposerInput |
稳定 | 未知的触发字符仍作为普通文本。 |
| 触发器查询 | 单 Token;多词 | 设定活动触发器查询的结束位置,如 FR10 和 FR11 所述。 | 当触发器处于激活状态时 | 单 Token | component:ChatComposerInput |
稳定 | 省略 hasMultiWordQuery 则保持单 Token 查询。 |
| 历史记录 | 启用;禁用 | 在文本边界处通过 ArrowUp 和 ArrowDown 回退已提交的草稿。 | 当启用且存在历史记录时 | 启用 | component:ChatComposerInput |
稳定 | 文本中间的箭头键保留原生光标行为。 |
| 文本粘贴 | 消费者处理;作为 Token 粘贴;纯文本 | 先让 onPaste 获得优先处理权,然后可选进行 Token 转换,最后插入纯文本。 |
启用的编辑器 | 长粘贴 Token 转换 | component:ChatComposerInput |
稳定 | 已处理的回调会阻止后续的插入路径。 |
| 文件接收 | 粘贴;拖放 | 阻止浏览器导航并将文件传递给 onFiles。 |
当提供了文件时 | 无回调 | component:ChatComposerInput |
稳定 | 空拖放不执行任何操作;禁用状态下的输入不会发出文件。 |
| 命令式编辑 | 插入 Token;展开 Token;插入文本;聚焦;获取值 | 允许诸如听写之类的组合功能通过编辑器自身的行为运作。 | 挂载期间 | 无 | component:ChatComposerInput |
稳定 | 编辑器未挂载时的调用为无效操作(no-op)或返回空值。 |
| Return 键标签 | EnterKeyHint:enter、done、go、next、previous、search、send |
触屏键盘的 Return 键所显示的文本;它不会改变 Enter 的行为。 | 每个编辑器 | send |
component:ChatComposerInput |
稳定 | TypeScript 会拒绝其他值。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 每次用户或命令式编辑更改序列化内容时,MUST 更新空状态,并通过活动的 onChange 通道发出有效值。命令式 handleRef.insertToken 与输入一样只发出一次。 |
已发布的 onChange 契约、命令式句柄及 ChatDictation 调用点。 |
| FR2 | 不带 Shift 的 Enter MUST 提交一条修剪后的非空草稿并清除它,除非事件处于组合状态、触发菜单消费了该事件,或消费者阻止了默认行为。 | 已发布的实现和消费者文档。 |
| FR3 | Shift+Enter 和文本中间的历史箭头 MUST 保留原生多行编辑行为。 | 已发布的实现和针对性测试。 |
| FR4 | 直接提供给 ChatComposerInput 的 value MUST 优先于 ChatComposer 上下文,而发出的回显 MUST NOT 重建 DOM 或移动光标。 |
已发布的受控优先级和回归测试。 |
| FR5 | 纯文本粘贴优先级 MUST 为:消费者 onPaste → 配置/默认的粘贴为 token → 普通插入。实现差距:当选区起始于某个 token 内时,粘贴会在该 token 之后插入文本,且不会调用 onPaste。 |
公共回调含义与客观回调组合方式。 |
| FR6 | 文件粘贴和文件拖放 MUST 阻止原生插入/导航,并向 onFiles 传递相同的、有序的 File[];禁用的编辑器 MUST NOT 发出文件回调。实现差距:当选区起始于某个 token 内时,文件粘贴永远不会到达 onFiles。 |
已发布的公共 onFiles 契约和消费者文档。 |
| FR7 | 触发菜单的键盘处理 MUST 在消费者和内置编辑器处理之前运行;IME 组合 MUST 永不提交。 | 已发布的交互契约和测试。 |
| FR8 | 历史召回 MUST 仅在草稿边界操作,并在步进越过最新项后 MUST 恢复待处理草稿。 | 已发布的行为和测试。 |
| FR9 | 根组件 MUST 继续转发其 ref、BaseProps 属性和样式接缝;命令式句柄在 handleRef 中保持独立。 |
已发布的公共 API 和 architecture:public-component-api。 |
| FR10 | 当触发器的字符位于文本开头,或位于空格、制表符或换行符之后时,该触发器激活,其查询范围从该字符之后延伸到光标处。在处于激活状态的多词查询内部,FR11 限制了哪些字符可以激活。不间断空格(例如插入 token 之后的那个)不是边界。单 token 查询以空格、制表符或换行符结束。实现差距:位于文本节点开头的触发器字符会激活其前面的内容,例如直接键入在插入 token 之后、且在其尾部不间断空格之前的 @。 |
已发布的触发器检测;DEC-1。 |
| FR11 | 具有 hasMultiWordQuery: true 的触发器会使其查询跨越空格和标点符号继续。查询仅在遇到换行符、超过实现自有的长度界限(至少 64 个字符),或同一触发器的字符在空格、制表符或换行符之后开始新查询时结束;不适用任何单词计数、标点列表或终止回调。在处于激活状态的多词查询内部,根据 FR10,另一个触发器的字符不会激活,因此查询会继续穿过该字符。 |
DEC-1。 |
| FR12 | 触发器查询结束时 MUST 保持已键入的文本不变。只有显式选择当前行才会替换从触发器字符到光标之间的范围。 | DEC-1。 |
| FR13 | 当针对活动查询的较新搜索仍在进行中时,不带 Shift 的 Enter 会按键入内容提交草稿,并且 MUST NOT 选择任何行;没有任何键会选择为较早查询返回的行。被取代查询的结果,或在选择、关闭、提交或查询结束之后才到达的结果,都会被丢弃,因此菜单绝不会在已发送或已清空的草稿上重新打开。这适用于每个触发器。 | DEC-1;参考聊天输入框行为。 |
| FR14 | 当多词查询结束且没有匹配项时,菜单会隐藏,除非触发器提供了 emptySearchText。没有匹配项的单 token 查询会显示空消息。 |
DEC-1。 |
| FR15 | 在 IME 组合期间按下的键 MUST NOT 选择行或移动高亮行。 | DEC-1;FR7。 |
| FR16 | 在可见菜单上按 Escape 会将其关闭,并且当同一查询从同一触发器继续增长时,菜单保持隐藏。在打开状态下,点击编辑器或菜单内部时菜单保持打开,点击其他位置时菜单关闭(architecture:layer-runtime)。 |
DEC-1。 |
| FR17 | 编辑器携带 enterkeyhint:当设置了 enterKeyHint 时使用其值,否则使用 send,因为 Enter 发送消息(FR2)。enterKeyHint 接受封闭联合类型 EnterKeyHint(component:TextInput FR16),因此 TypeScript 会拒绝任何其他值。该提示仅标记按键:无论提示内容如何,FR2 和 FR3 决定 Enter 和 Shift+Enter 的行为,因此一个 onKeyDown 让 Enter 插入换行的 composer 会传入 enter。ChatComposer 的默认输入携带相同的默认值。 |
DEC-2;component:TextInput DEC-1 |
| FR18 | 当光标位于 token 尾随空格的内部或紧接其后,且该空格后没有文本时,按退格键会一步删除该 token 和该空格,使文本恢复到插入 token 之前的状态,且不产生额外换行;被清空的最后一行保留浏览器的占位符。 | 当前源代码和测试 |
允许的变体¶
- AV1 — 搜索内容。 构建者拥有触发器字符、搜索源、项目渲染和插入值。
- AV2 — Token 内容。 构建者可以使用结构化 Badge 形式或自定义渲染逃逸口,并拥有自定义语义。
- AV3 — 产品文件工作流。 构建者拥有接受的文件类型、验证、上传、进度,以及
onFiles收到文件之后的错误处理。
代表性状态¶
| 状态 | 必需不变量 | 允许的变体 |
|---|---|---|
| 空 | 占位符可见,序列化值为空。 | 占位符文案。 |
| 已输入或以命令方式插入的文本 | 占位符不存在,ChatComposer 和回调可观察到相同的序列化值,包括以命令方式插入的 token(FR1)。 | 草稿内容。 |
| 受控更新 | 外部值被反映,而不会破坏活动光标,也不会将过期的回显视为权威。 | 父组件更新时机。 |
| 触发器菜单打开 | 公开组合框语义和活动选项接线;菜单交互拥有其按键。 | 搜索源和项目渲染。 |
| 触发器搜索等待中 | Enter 按原样提交草稿;无法选中先前查询的行。 | 加载文案和源延迟。 |
| 触发器菜单隐藏 | 编辑器报告一个折叠的组合框,且菜单不消费任何按键。 | 菜单隐藏的原因。 |
| 文件粘贴或拖放 | 阻止原生插入/导航,文件一次性到达 onFiles(FR6 记录了一个实现缺口)。 |
文件类型和产品处理。 |
| 禁用 | 编辑和文件回调不可用,并暴露禁用状态。 | 产品原因和周围状态。 |
转换和优先级顺序¶
- ORD1 — 草稿来源。 显式
value→ ChatComposer 上下文值 → 编辑器 DOM。 - ORD2 — 变更通道。 当
value为显式时,显式受控输入回调 → ChatComposer 上下文回调 → 独立的局部回调。 - ORD3 — 按键处理。 触发器菜单 → 消费者
onKeyDown→ IME/提交/历史行为。 - ORD4 — 普通粘贴。 消费者
onPaste→ 粘贴为 token 的行为 → 普通插入(FR5 记录了一个实现缺口)。 - ORD5 — 文件接收。 剪贴板或数据传输中的文件 → 阻止原生行为 → 启用时发出
onFiles(FR6 记录了一个实现缺口)。
性能和资源¶
- PR1 — 选区操作。 选区读写限定在已挂载的可编辑区域内,且只针对直接编辑操作或受控同步执行。
- PR2 — 异步触发器操作。 搜索取消通过提供的
SearchSource及其可选的cancel进行,debounceMs设置异步搜索开始前的延迟。实现缺口:每次改变查询的按键都会立即调用一次search('')来检测源是否为异步,因此异步源会收到一次未延迟的搜索。 - PR3 — Portal 清理。 当内容更改或卸载时,通过现有的 token 钩子清理 token Portal。
无障碍契约¶
- AR1 — 编辑语义。 在无触发器的情况下,表面是一个命名的多行文本框;有触发器时,它暴露所采用的 combobox 语义,而不产生无效的多行 ARIA。
- AR2 — 禁用状态。 禁用编辑通过
aria-disabled暴露,并且不能接受内容或文件回调。 - AR3 — 键盘所有权。 IME、触发器菜单按键、使用方取消、Enter 提交以及仅边界历史不会相互抢占按键。
- AR4 — 焦点可见性。 当在 ChatComposer 中组合时,语义编辑器焦点所有者驱动外壳的共享键盘焦点指示器。
- AR5 — 折叠的建议。 当菜单隐藏时,编辑器报告
aria-expanded="false",不暴露活动后代,并且箭头键、Enter 和 Escape 可到达编辑器及其周围环境。
设计关系¶
| 结构或状态 | 设计需求 | 呈现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 输入根 | 现有的主题化目标 | 观察到的实现 | 辅助 | FR9 |
| 可编辑表面 | 常规编辑器编辑表面 | ChatComposer 家族 | 突出 | FR1–FR4、AR1–AR4 |
| 占位符 | 空时的次要文本 | 当前 Token 角色 | 辅助 | FR1 |
| 触发器菜单 | 委托的 Typeahead 行为 | Typeahead 所有者 | 浮动 | FR7、FR10–FR16、AR5 |
| 内联 Token | 结构化的 Badge 或调用方内容 | Badge 或调用方所有者 | 辅助 | AV2 |
现有的 chat-composer-input 目标保留在根节点上。本条记录不添加主题化目标,也不决定新的视觉状态。
家族与系统关系¶
component:ChatComposer拥有布局、提交编排、发送状态和外壳焦点环;本组件拥有编辑表面及其变更通道。- Typeahead 和 SearchSource 拥有结果收集行为;ChatComposerInput 决定触发器菜单何时参与编辑器按键优先级。
architecture:interaction-modality拥有共享的焦点可见性机制。spec:AST-029拥有观察性审计回填边界。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, ORD1–ORD2 | 针对命令式插入(文本和 Token)和受控同步的聚焦测试;ImperativeInsertion 演练 |
空 → 插入文本;受控回显;外部覆盖 | 文本仅出现在 DOM 中、占位符仍旧存在、回调过期,或光标跳动。 | audit:ChatComposerInput/behavior |
| FR2–FR3, FR7–FR8, AR3 | 聚焦的键盘、IME、触发器和历史测试 | Enter;Shift+Enter;组合输入;被取消的按键;边界处和文本中间的箭头键 | 某个按键提交两次、在组合输入期间提交,或抢占原生编辑。 | audit:ChatComposerInput/interaction |
| FR10–FR16, AR5 | 聚焦的触发器查询和触发器键盘测试;“在编辑器或菜单中按下时保持触发器菜单打开,在其它位置按下时将其关闭” | 单个 Token;多词;换行;长度限制;待定搜索;无匹配;IME;Escape | 查询过早结束或更改文本,Enter 选中先前查询的行或在搜索进行中时无法提交,迟到的结果在发送后重新打开菜单,或者隐藏的菜单消耗按键。 | audit:ChatComposerInput/interaction |
| FR5, ORD4 | 聚焦的长粘贴拦截测试 | 消费者已处理;token 转换;普通插入 | 消费者拦截被跳过,或多个插入路径同时运行。 | audit:ChatComposerInput/behavior |
| FR6, ORD5, AR2 | 聚焦的粘贴/拖放测试及 FileDrop 演练 |
粘贴;拖放;禁用 | 文件被导航离开、插入到编辑器中、绕过 onFiles,或在禁用状态下触发事件。 |
audit:ChatComposerInput/behavior |
| AR1, AR4 | 角色/名称/ARIA 测试,以及精确头部可访问性和视觉门禁 | 文本框;组合框;禁用;键盘焦点 | 名称、角色、多行、展开、禁用或可见焦点语义发生回归。 | audit:ChatComposerInput/accessibility |
| FR9 | ref、target、package 及 repository 检查 | ref;BaseProps;xstyle;className;style | 根节点所有权或样式接缝移动或消失。 | audit:ChatComposerInput/api |
| FR17 | ChatComposerInput.test.tsx 触屏键盘 Return 键测试套件(默认 send、设置的值、ChatComposer 默认输入框内的 send,且每个标签下 Enter 均提交);ChatComposerInput.public.test.ts(由 pnpm typecheck 运行)用于验证 EnterKeyHint 拒绝任意或未收窄的字符串;ChatComposerReturnKey.a11y.chromium.spec.ts 用于验证轻点聚焦时编辑器上的该属性 |
默认;enter;ChatComposer 内部;带触摸模拟的手机视口 |
缺少或错误的 enterkeyhint、阻止 Enter 提交的标签,或接受 string 的类型,均会导致失败。 |
audit:ChatComposerInput/api |
| FR18 | ChatComposerInput.test.tsx “在一个 token 后按一次 Backspace 会移除该 token 及其空格”和“在起始最后一行的 token 上按一次 Backspace 会为插入符保留该行”;ChatComposerImeCaret.a11y.chromium.spec.ts |
在插入的 token 之后且其空格后没有文本;token 位于最后一行的开头 | 一次 Backspace 后 token 或其尾随空格残留、在 token 前的文本之外添加了换行,或已清空的最后一行丢失其行,均会导致失败。 | audit:ChatComposerInput/interaction |
决策日志¶
DEC-1 — 触发查询是非破坏性的,仅作用于当前结果¶
引用: component:ChatComposerInput/DEC-1
决策者: cixzhang,2026-10-06;搜索待处理时的 Enter 行为,2026-10-14;跨触发器延续采用与参考编辑器相同的方向,2026-10-14
只有调用者知道其建议是否包含空格,因此多词查询是每个触发器的选择加入(opt-in),而单 token 触发器(如命令)仍然在空白处结束。多词查询永远不会改变用户输入的内容:它按 FR11 所述结束,只有显式选择才会替换文本。建议仅作用于当前查询:当搜索处于待处理状态时,Enter 按输入原样发送消息,绝不会从较早的查询中选取一行;发送后到达的结果会被丢弃,因此菜单绝不会在已清空的编辑器上重新打开。这与参考聊天编辑器一致,消息可以简单地从触发器开始。未匹配的多词短语会隐藏菜单,而不是用空面板覆盖正在输入的文本。在活动的多词查询中,另一个触发器的字符不会启动新查询,因此 @Jordan / 保持提及查询,而相同触发器的字符会按 FR11 所述启动新查询;两者都与参考聊天编辑器一致。
已否决:词数上限、标点终止符或终止回调;它们会截断真实姓名并依赖语言。
已否决:按住 Enter 直到待处理的搜索完成;这会阻止发送仅以触发器开头的消息。
DEC-2 — Return 键显示为 Send¶
引用: component:ChatComposerInput/DEC-2
决策者: cixzhang,2026-11-01
Enter 发送草稿(FR2),因此编辑器自行将触摸键盘的 Return 键标注为 Send,因为组件可以决定它能推导出的内容(architecture:public-component-api INV4)。如果调用者的 Enter 有其他行为,则传入自己的 enterKeyHint。
未解决的问题¶
无。
内容边界¶
本文件不会重复使用方属性表、示例、当前审计分数或视觉设计原理。它记录已发布的行为、客观修正以及 DEC-1 中的触发器查询契约,而不决定新的视觉表示。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx