Code 组件契约¶
契约概览¶
| 区域 | 契约 |
|---|---|
| 公共契约 | Code 从 @astryxdesign/core/Code 导出;它要求 children,默认将 color 设为 primary,可选接受 secondary 或 inherit,并接受 size="inherit"。 |
| 行为 | Code 渲染一个语义化的 <code> 元素,默认使用代码类型尺度,并可通过显式 props 继承周围环境的颜色或排版。 |
| 最终用户影响 | 读者获得可识别的行内代码,它会换行而不是迫使正文容器变宽。 |
| 构建者影响 | 无;该记录描述已发布的行为。简短的行内引用使用 Code;独立或多行代码片段使用 CodeBlock。 |
| 兼容性/就绪状态 | 已发布的行为记录为当前状态;无 API、默认值或输出变更。 |
| 审查检查 | 拒绝非 code 根元素、丢弃的内容或根 props、未指向根元素的 ref、未反映在 code 目标上的视觉 prop、未记录的已发布 props/默认值,或将行内组件变成块级代码替代品的变更。 |
| 治理规则 | architecture:public-component-api/INV1,INV5,INV6,INV8–INV9;architecture:component-theming-surface/INV3–INV7;architecture:component-test-sufficiency/INV1–INV7,INV10–INV11。 |
此表是审查预览;以下正文具有权威性。
意图¶
在正文中以原生代码语义呈现简短的技术引用,并提供紧凑、可主题化的行内处理方式。
兼容性与迁移¶
- 已发布的默认值保留:是
- 兼容性类别:记录已发布的行为;无运行时、类型、默认值、样式、目标或导出变更
- 受控/非受控行为:不适用;Code 不拥有任何状态
- 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 语义化的行内代码根元素、代码排版与换行、primary/secondary/inherited 文本颜色、可选的继承字号、受支持的根 props 和 ref,以及
code主题目标。
不拥有 / 非目标
- 语法高亮、行号、复制行为、标题、围栏或多行呈现 — 由
component:CodeBlock拥有。 - 调用方提供的代码内容的含义、本地化或双向排序 — 由产品调用点和平台文本引擎拥有。
- 交互操作或导航契约 — 构建者在 Code 之外组合适当的 Button 或 Link。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| color | primary、secondary、inherit |
选择行内代码文本颜色的来源。 | 每次渲染 | primary |
component:Code |
稳定 | 被公共类型拒绝 |
| size | 代码尺度、继承 | 省略时使用代码类型尺度,继承时使用周围环境的排版。 | 每次渲染 | 代码尺度 | component:Code |
稳定 | 被公共类型拒绝 |
| code content | 调用方提供的 React 内容 | 提供语义化 code 元素内部的内容。 | 每次渲染 | 必需 | 产品调用点 | 稳定 | 普通 React 渲染 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | Code 渲染一个包含调用方内容的语义化 <code> 根元素。 |
已发布的源码、测试、文档和 HTML 语义 |
| FR2 | 根元素使用代码字体族,当省略 size 时,使用 --text-code-size 及周围环境的行高;size="inherit" 还会继承周围环境的字号。color 选择主文本(默认)、次要文本或继承的颜色。 |
已发布的公共类型、源码、测试和 stories |
| FR3 | 根元素以 --radius-inner 圆角绘制 --color-background-muted,内联方向使用逻辑 --spacing-1、块方向使用 --spacing-0 内边距;长内联内容断行换行,而不是加宽其正文容器。 |
已发布源码与代表性正文故事 |
| FR4 | 受支持的 DOM props、className、style 和 xstyle 组合于根元素上,且公共 ref 可达该根元素。code 目标与 data-color 反射在调用方 DOM props 之后应用;xstyle、className 和 style 按 ORD1 规定的顺序组合。 |
architecture:public-component-api/INV5,INV6,INV8;已发布源码与测试 |
| FR5 | 已绘制的根元素承载公共 code 目标并反映 color 视觉轴。已发布表面不包含任何内部目标或独立状态目标。 |
architecture:component-theming-surface/INV3–INV7;源码与目标清单 |
允许的变化¶
- AV1 — 主题绘制。
code目标可变更受支持的排版、颜色、背景、内边距、圆角及其他可接受的绘制,而不改变语义内容或内联归属。 - AV2 — 调用方内容。 Code 内容可包含已发布
children类型接受的任何 React 内容;其含义仍归调用方所有。 - AV3 — 周围排版。 构建者可显式继承周围颜色或字号;省略时保留组件默认值。
代表性状态¶
| 状态 | 必需不变式 | 允许的变化 |
|---|---|---|
| 默认 | 语义化代码根元素、主色、代码字阶字号。 | 调用方内容与主题绘制。 |
| 次要颜色 | 相同根元素与布局,使用次要文本颜色来源。 | 调用方内容与主题绘制。 |
| 继承颜色 | 相同根元素与布局,使用周围文本颜色。 | 周围颜色与调用方内容。 |
| 继承字号 | 相同根元素与绘制,使用周围字体大小与行高。 | 周围排版与调用方内容。 |
| 长内联内容 | 内容换行,不依赖组件自有的物理方向几何。 | 调用方内容中的可断行位置。 |
转换与优先级顺序¶
- ORD1 — 根元素 props。 受支持的调用方 DOM props → 组件目标与视觉轴反射 → base/color/size/xstyle 类 → 使用方 class 与内联样式组合。
- ORD2 — 排版。 省略 size → 代码字阶字号;显式
inherit→ 周围字体大小与行高。
性能与资源¶
- PR1 — 纯渲染。 Code 不拥有任何状态、Effect、监听器、观察器、定时器、外部资源或异步工作。
无障碍契约¶
- AR1 — 原生语义。 根元素保持为语义化
<code>元素,不添加任何交互角色、焦点目标或组件撰写的可访问名称。 - AR2 — 调用方内容。 调用方提供的内容保持为可访问内容;Code 不翻译、隐藏或复制它。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 容器 | 通过代码排版与紧凑背景处理区分短技术文本。 | 已观察到的发布表现 | 内联技术内容 | FR1–FR5, AR1–AR2 |
当前没有设计记录规定 Code 的具体像素;精确调优保留在代码与视觉证据中。
主题解剖结构¶
家族与系统关系¶
architecture:public-component-api负责导出可达性、受支持的根元素 props、样式组合、ref 可达性、已发布默认值与使用方文档。architecture:component-theming-surface负责目标限定、目标放置、视觉轴反射与元数据归属。architecture:component-test-sufficiency负责合理证据集。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, AR1, AR2 | Code.test.tsx 渲染测试 |
默认 | 非 code 根元素或内容缺失会失败。缺口:当包装器成为根元素时渲染测试仍然通过,并且如果 Code 添加了角色、Tab 停靠点或名称,没有测试会失败,同时也没有无障碍树检查来证明暴露的内容(spec:AST-009 FR3)。 |
audit:Code/a11y |
| FR2, ORD2 | Code.test.tsx 颜色测试;Code.stories.tsx 的 Colors 和 TextSizes 在故事播放守卫中的播放检查 |
主色、次色、继承色;四种文本大小下的继承尺寸 | 缺少 data-color 反射、次色与主色相同、继承的颜色或尺寸与父级不匹配,或所有继承尺寸都坍缩为同一个值,都会失败。缺口:代码字体族和默认 --text-code-size 除视觉基线外没有自动化检查。 |
audit:Code/behavior |
| FR3 | Code.stories.tsx 的 LongInlineContent 播放检查;稳定的视觉基线 core-code--default |
受约束的散文文本中含有一个不间断的标识符;默认 | 如果 Code 停止换行或撑宽其容器,播放检查会失败;背景、圆角或内边距发生变化时会以变更后的状态返回以供审查。缺口:没有单元测试对绘制或内边距进行断言。 | audit:Code/responsive |
| FR4, ORD1 | Code.test.tsx 的 ref 与透传测试 |
Ref;aria-label、className、style、xstyle |
ref 丢失,或调用方的 prop、类、内联样式或 xstyle 类丢失,都会失败。缺口:当包装器接收到 ref 时 ref 测试仍然通过,并且没有测试断言 target 和 data-color 会覆盖调用方的 DOM props,或断言调用方的 xstyle 遵循基础样式。 |
audit:Code/api |
| FR5 | themingTargets.test.ts;Code.test.tsx 颜色测试 |
每个颜色值 | 缺少 target 或 data-color 反射会失败。 |
audit:Code/theming |
| RTL 不适用 | @astryx/no-physical-properties lint 规则;apps/storybook/rtl-audit/verified-not-applicable.json 条目 |
每个故事 | 该 lint 规则会使 Code 样式中的物理 left/right 属性或值失败。缺口:没有浏览器从右到左检查覆盖 Code;该条目记录了这一决定。 | audit:Code/rtl |
| PR1 | 源码审查 | 每个状态 | 缺口:如果 Code 添加了状态、副作用或监听器,没有自动化检查会失败。 | audit:Code/behavior |
决策日志¶
无记录。该记录描述的是已发布的行为。
未决问题¶
无。
内容边界¶
本文件不重复使用方示例、当前审计得分、实施步骤、CodeBlock 行为或排版策略草案。它链接到各自的所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx