ChatTokenizedText 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | ChatTokenizedText 需要必填字符串 children,可选的 tokens(ChatComposerToken 形状)、ref、xstyle、className、style 以及根 span 属性;目标为 chat-tokenized-text。 |
| 行为 | 未匹配的文本会被保留。非空 token 值从左到右按字面匹配。结构化 token 委托给 Badge,自定义 token 委托给调用方。 |
| 最终用户影响 | 读者在已发送消息中看到提及和其他 token,与他们在 composer 中看到的 chips 相同,位置不变,其余文本保持不变。 |
| 构建者影响 | 无。 |
| 兼容性/就绪性 | 记录已发布行为;无公开变更。有一个所有者问题仍未解决;对于标记为从源代码读取的声明,证据仍待补充。 |
| 审查检查 | 拒绝零宽度匹配、未匹配文本丢失、在无匹配时执行自定义渲染器、根输入被丢弃,或对调用方拥有内容的声明。 |
| 治理规则 | architecture:public-component-api/INV1, INV5–INV6, INV8–INV9;architecture:component-test-sufficiency/INV1–INV7;ECMAScript RegExp 进度语义。 |
此表为审查投影;以下正文才具有权威性。
意图¶
ChatTokenizedText 将普通聊天消息中嵌入的序列化 token 值投影为内联的结构化 Badge 内容或调用方渲染的内容,同时保留周围文本。
兼容性与迁移¶
- 已发布的默认行为保留:
yes - 兼容性类别:记录已发布行为;无公开变更
- 受控/非受控行为:不适用;该组件不拥有状态
- 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
当前状态影响¶
- 较短的 token 可以拆分较长的 token。 当一个 token 的值是另一个 token 的前缀,并且排在前面的定义时,较短的值获胜:对于 tokens
@u1然后是@u12,文本@u12会渲染出@u1chip,后面跟着一个游离的2。当两个 token 共享同一个值时,后面的定义生效(OQ1)。
所有权边界¶
拥有
- 将序列化 token 值与提供的消息文本进行字面匹配。
- 保留未匹配的文本和原始顺序。
- 为每个匹配选择现有的结构化 Badge 或自定义渲染分支。
- 根 span、其
chat-tokenized-text目标、接受的 BaseProps 组合以及 ref。
不拥有 / 非目标
- token 值语法、身份、验证或产品语义。
- Badge 颜色、图标、尺寸或无障碍语义。
- 调用方提供的自定义 token 内容内部的语义和交互。
- Composer 插入、序列化、删除、选择或 token 元素对齐。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 消息文本 | 任意字符串 | 其字面 token 值可能被内联投影的普通文本。 | 每次渲染 | 必需 | component:ChatTokenizedText |
稳定 | 空文本渲染一个空 span。 |
| Token 集合 | 省略;空;非空 | 候选的序列化值及其结构化或自定义呈现。 | 每次渲染 | 省略 | 调用方和组件 | 稳定 | 空的 token 值会被忽略。 |
| Token 形式 | 结构化 Badge 配置;自定义渲染函数 | 选择委托的 Badge 内容或调用方渲染的内容。 | 匹配非空值 | 无 | 调用方和委托组件 | 稳定 | 类型无效的形式会被拒绝。 |
| 根表面 | ref;支持的 DOM/data/ARIA/class/style/xstyle |
扩展内联根而不替换其拥有的目标。 | 每次渲染 | 省略 | architecture:public-component-api |
稳定 | 不支持的输入仍保持不支持。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 组件 MUST 精确保留未匹配的文本,并在其原始阅读顺序位置上替换每个匹配的非空序列化值。重叠或重复值如何解析由 OQ1 决定。 | 当前源代码、测试和文档 |
| FR2 | 空令牌值 MUST 被忽略,以便渲染器始终取得进展,且永远不会进入零宽全局匹配循环。 | 当前源码与测试 |
| FR3 | 结构化匹配 MUST 将标签、变体和图标渲染委托给 Badge;自定义匹配 MUST 仅在实际匹配时调用调用方渲染器。 | 当前源码、测试与文档 |
| FR4 | 受支持的 ref、DOM/data/ARIA、className、style 和 xstyle 输入 MUST 到达或组合到根 span 上,同时 chat-tokenized-text 目标保持完整。 |
architecture:public-component-api/INV5–INV6, INV8 |
| FR5 | 组件 MUST 保持仅渲染,不包含任何状态、Effect、监听器、观察器、定时器或自有的异步资源。 | 当前源码 |
允许的变化¶
- AV1 — 调用方令牌。 标签、变体、图标、自定义内容和序列化值均由调用方提供。
- AV2 — 调用方样式。 受支持的根样式输入可以扩展组件,但不得替换其公共目标。
- AV3 — 未匹配输入。 不包含任何匹配的非空值的文本保持不变。
代表性状态¶
| 状态 | 必需不变式 | 允许的变化 |
|---|---|---|
| 纯文本 | 原文文本保持可见。 | 任意字符串内容。 |
| 结构化匹配 | 匹配文本被替换为委托给 Badge 的内容。 | 标签、变体和图标。 |
| 自定义匹配 | 匹配文本被替换为调用方渲染的内容。 | 任意调用方拥有的 React 节点。 |
| 重复匹配 | 每一次出现均按阅读顺序被替换。 | 出现次数与位置。 |
| 空令牌值 | 该值被忽略,渲染在保留文本的情况下结束。 | 可出现在有效令牌旁边。 |
| 窄屏 / RTL 上下文 | 行内内容保持可读,并遵循周围文本的方向。 | 主题、方向与消息长度。 |
转换与优先级顺序¶
- ORD1 — 规范化候选。 移除空的序列化值,同时保留调用方顺序。
- ORD2 — 按字面匹配。 对 RegExp 语法中的值进行转义,并从左到右扫描消息。
- ORD3 — 渲染。 保留未匹配的片段,并将每个匹配的令牌委托给 Badge 或调用方渲染器。
- ORD4 — 组合根节点。 应用组件目标和样式,然后合并已接受的使用方样式与根属性。
性能与资源¶
- PR1 — 有限进展。 每次成功匹配至少消耗一个 UTF-16 代码单元;空值无法进入匹配器。
- PR2 — 仅渲染投影。 匹配过程每次渲染分配一个候选列表、一个查找映射和一个结果列表,且不持有任何持久资源。
无障碍契约¶
- AR1 — 阅读顺序。 未匹配文本和令牌内容保持在同一个行内文本包装器内的源码阅读顺序。
- AR2 — 委托内容。 结构化令牌语义仍由 Badge 拥有;自定义令牌语义仍由调用方拥有。
- AR3 — 非交互式根节点。 组件不引入任何 role、焦点目标、键盘命令、指针操作或 live-region 行为。
设计关系¶
| 结构或状态 | 设计需求 | 表示权威来源 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 令牌化文本 | 行内根节点保持周围文本流。 | 当前源码与已发布文档 | 支持 | FR1, FR5 |
| 已渲染令牌 | 将绘制委托给 Badge 或调用方内容。 | component:Badge 或调用方 |
支持 | FR4, AR2 |
未记录任何组件本地设计决策。
主题所有权¶
Chat 家族文档拥有该子组件所继承的共享结构与目标清单。现有 chat-tokenized-text 目标仍保留在行内根节点上。结构化令牌绘制委托给 Badge,而自定义渲染的令牌内容仍由调用方拥有。尚未记录结构主题映射;迁移期间该块为可选,因此该映射被推迟。
家族与系统关系¶
component:Badge拥有结构化令牌绘制、变体、图标和标签语义。component:ChatComposerInput拥有令牌插入、序列化、删除和 composer 选择行为。architecture:public-component-api拥有已发布的导出、BaseProps 可达性、样式组合和 refs。architecture:component-theming-surface拥有目标/结构映射。architecture:component-test-sufficiency拥有有界且对变异敏感的验证证据。spec:AST-029拥有本记录验证映射所遵循的审计证据清单。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变异或失败预期 | 审计章节 |
|---|---|---|---|---|
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------ |
| FR1–FR3, PR1 | ChatTokenizedText.test.tsx 纯文本、单个、多个、重复、特殊字符、周围文本、空值和自定义匹配测试 |
纯文本、结构化、自定义、重复、空 | 丢失文本、零宽度不终止或错误分支失败。 | audit:ChatTokenizedText/behavior |
| FR4 | ChatTokenizedText.test.tsx ref 和 rest-prop 测试 |
纯文本和 Token 化根节点 | 丢失 ref 或 prop 则失败。 | audit:ChatTokenizedText/public-api |
| FR1–FR4 | ChatTokenizedText.a11y.chromium.spec.ts 渲染状态 |
纯文本、结构化、自定义 | 缺少或重复的 chat-tokenized-text 目标会失败。 |
audit:ChatTokenizedText/theming |
| RTL 关系 | apps/storybook/rtl-audit/verified-not-applicable.json |
所有 stories | — | audit:ChatTokenizedText/i18n-rtl |
从源代码读取,尚无针对性测试:
- ORD2: 包含 RegExp 元字符的值按字面匹配。
- FR3:
variant和icon到达 Badge。 - FR4:
className、style和xstyle的组合。 - FR5, AR3: 组件自身没有状态、Effect 或交互。
决策日志¶
未记录任何组件本地的决策。
未决问题¶
- OQ1 — 重叠或重复的 Token 值应如何解析?
(
human-api) 目前,在某个位置,最先列出的值优先,因此较短的前缀会拆分较长的值,而两个相同值中后出现者会渲染。匹配是否应优先选择最长的值,以及重复值如何解析,将改变读者看到的内容。
内容边界¶
本文件不重复消费者示例、Badge 策略、Token 语法或 composer 编辑行为。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx