Blockquote 组件契约¶
契约一览¶
| 区域 | 契约 |
|---|---|
| 公开契约 | 一个语义化的 blockquote,承载 children,并带有可选的 cite 出处标注。 |
| 行为 | 引用具有内联起始规则线和次要文本;可渲染的 cite 以裸 cite 元素形式跟随内容。 |
| 最终用户影响 | 读者看到被区隔开的引用文本;屏幕阅读器用户获得原生的 blockquote,且不会因出处标注产生多余的地标。 |
| 构建者影响 | 无;该记录描述的是已发布行为。 |
| 兼容性/就绪状态 | 已发布行为被记录为当前行为;无 API、默认值或输出变更。 |
| 审查检查 | 拒绝物理左侧规则线、围绕出处标注的 footer,或非 blockquote 的根元素。 |
| 管理规则 | design:bidirectionality/DR3;architecture:public-component-api/INV5,INV6,INV8;architecture:component-theming-surface/INV2。 |
此表是审查投影;以下正文具有权威性。
意图¶
Blockquote 通过原生引用语义将引用内容与周围文本区隔开。它拥有引用的规则线、内边距和颜色,以及可选出处标注的放置位置。
兼容性与迁移¶
- 已发布默认值保留:
yes - 兼容性类别:记录已发布行为;无公共 prop、默认值、DOM 或样式输出变更
- 受控/非受控行为:不适用
- 迁移决策:无
使用方的迁移说明属于使用方文档和发布说明。
所有权边界¶
拥有
blockquote根元素、其规则线、内边距、颜色以及归零的边距。- Attribution(出处标注)元素及其在引用之后的位置。
不拥有 / 非目标
- 引用内容与出处文本——由调用方拥有。
- 引号(如需要)——由调用方的内容拥有。
- Markdown 块引用——由
component:Markdown拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 拥有方 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| Attribution(出处标注) | present(存在);absent(不存在) | 在引用之后渲染引用的来源。 | 始终 | 不存在 | component:Blockquote |
稳定 | false、true、null、undefined 和 '' 均不渲染任何内容。 |
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | 根元素是承载 blockquote 目标的 blockquote;其内联起始边缘具有 --color-border-emphasized 颜色的实线 --spacing-0-5 规则线、--spacing-4 内联起始内边距、次要文本颜色、长单词词内断行,且所有边距为零。 |
当前源码与测试 |
| FR2 | children 首先在根元素内渲染。可渲染的 cite 在它们之后以裸 cite 元素渲染——绝不包裹在 footer 中——以块级显示,带有 --spacing-2 顶部边距、辅助文本样式和正常字体样式。 |
当前源码与测试 |
| FR3 | 在从右到左区域中,规则线及其内边距位于右边缘:根元素使用逻辑内联起始边框和内边距,绝不使用物理左侧边框和内边距。 | 当前源码与文档 |
| FR4 | ref 指向 blockquote。受支持的 DOM、ARIA、data 和事件 props 均传递到该元素;xstyle、className 和 style 按该顺序在组件样式之后合并。Blockquote 在服务器端渲染。 |
当前源码与测试 |
允许的变体¶
- AV1 — 主题绘制。 主题可以重新设计
blockquote的样式,包括规则线,而不改变语义或出处标注的位置。
代表性状态¶
| 状态 | 必需不变式 | 允许的变体 |
|---|---|---|
| 仅引用 | 带有规则线和次要文本的 blockquote;无 cite。 |
内容。 |
| 带出处标注 | cite 跟随内容;无 footer 或地标。 |
出处标注。 |
| 从右到左 | 规则线和内边距位于右边缘。 | — |
转换与优先级顺序¶
- ORD1 — 样式输入。 组件类 → 组件样式 →
xstyle→className→style→ 其余调用方 props。
性能与资源¶
- PR1 — 静态渲染。 Blockquote 不持有状态,也不使用 hooks。
无障碍契约¶
- AR1 — 原生引用。 根元素是一个原生
blockquote。 - AR2 — 无多余地标。 来源署名是一个裸露的
cite;它绝不会被包裹在footer中,因为在分区根元素内部,footer会作为内容信息地标呈现。
设计关系¶
| 构成或状态 | 设计需求 | 表现依据 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Rule | 内联起始边缘上的一条强调线。 | 当前源代码和文档 | 辅助 | FR1, FR3 |
| Quotation | 以次要文本呈现的引用内容。 | 当前源代码和文档 | 突出 | FR1, FR2 |
| Attribution | 来源署名,以辅助字体显示在引用内容下方。 | 当前源代码和文档 | 辅助 | FR2, AR2 |
主题化结构¶
{
"Rule": {"target": "blockquote"},
"Quotation": {"inherits": "blockquote"},
"Attribution": {"inherits": "blockquote"}
}
Rule 是根元素的一条边框,因此它共享根元素的 blockquote 目标。
家族与系统关系¶
design:bidirectionalityDR3 负责内联起始和内联结束的位置;FR3 将其应用于 Rule。architecture:public-component-api负责 ref、透传和样式输入规则;FR4 将它们应用于根元素。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, FR4 | Blockquote.test.tsx 渲染、class、ref、透传和服务端测试 |
仅引用 | 非 blockquote 根元素、目标丢失、ref 或调用方 prop 丢失,或服务端渲染失败,均会导致测试失败。稳定的视觉基线 core-blockquote--default(中性、浅色和深色)会返回发生变化的 Rule、内边距、颜色或外边距以供审查。差距:没有单元测试断言这些样式、断词行为或样式输入的合并顺序。 |
audit:Blockquote/behavior |
| FR2, AR2 | Blockquote.test.tsx cite 测试 |
有/无来源署名 | 缺少 cite 或存在地标包装元素会导致测试失败。差距:没有测试断言来源署名位于内容之后;其块级显示、外边距、字体类型和字体样式没有自动化检查;视觉基线也未渲染来源署名。 |
audit:Blockquote/a11y |
| FR3 | @astryx/no-physical-properties lint 规则;Blockquote.stories.tsx |
RTL | Blockquote 样式中若出现物理左边框或左内边距,则 lint 失败。差距:没有渲染后的 RTL 检查来确认 Rule 位于右边缘。 | audit:Blockquote/i18n-rtl |
| Theming anatomy map | scripts/check-knowledge.mjs |
使用方结构及当前目标 | 缺失、多余或过时的映射会使仓库验证失败。 | audit:Blockquote/theming |
| AR1 | Blockquote.test.tsx 渲染测试 |
仅引用 | 非 blockquote 根元素会导致失败。 |
audit:Blockquote/a11y |
| PR1 | Blockquote.test.tsx 服务端渲染测试 |
仅引用 | 服务端渲染失败会导致测试失败。差距:如果 Blockquote 添加了状态或 hooks,目前没有任何测试会失败。 | audit:Blockquote/behavior |
| AR1, AR2 | 无障碍树证据(spec:AST-009 FR3) |
带来源署名的引用 | 差距:没有无障碍树检查来证明 blockquote 角色或不存在地标;单元测试查询的是 DOM。 | audit:Blockquote/a11y |
| RTL 关联 | RTL 审计在 Blockquote / Default 上精选的 D8 目标(apps/storybook/rtl-audit/targets.json) |
Inline-start 内边距;LTR 和 RTL | 若逻辑起始内边距在 RTL 中保持在同一物理侧,则无法通过 D8。 | audit:Blockquote/i18n-rtl |
决策日志¶
无记录。该记录描述的是已发布行为。
未决问题¶
无。
内容边界¶
本文件不重复消费者属性表/示例、当前审计结果、实施步骤或族/系统规则。它链接到其所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx