跳转至

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:bidirectionality DR3 负责内联起始和内联结束的位置;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