跳转至

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-017 FR5、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