跳转至

ChartAxis 组件契约

契约概览

领域 契约
公共契约 无 API 形状或默认值更改。截断和自动水平密度现在按照客观的 Unicode 文本分段标准统计完整的字素簇。
行为 所选物理绘图边缘决定比例尺、位置、标签方向和默认边缘线;显式格式化和密度输入可细化标签。
最终用户影响 图表阅读者会获得完整的刻度标签字符,同样短的 Unicode 标签不再比 ASCII 标签更激进地抽稀。
构建方影响 无。现有调用点保持有效,并为当前界面获得直接 CLI 文档。
兼容性/就绪状态 canary API 和默认值均被保留。此记录是草稿观察证据;渲染和可访问性树证据仍不完整。
审查检查 若出现以下情况则拒绝:公共形状/默认值被更改、坐标轴使用了错误的 Chart 比例尺、物理边缘放置损坏、字素标签被拆分、或线/刻度优先级被隐藏。
约束规则 spec:AST-029/FR3–FR7、architecture:component-test-sufficiency/INV1–INV9,以及 Unicode 文本分段。

此表为评审概览;下方正文具有权威性。

意图

ChartAxis 在 Chart 内部渲染带标签的笛卡尔 x 或 y 比例尺输出。它负责物理边缘放置、刻度选择和格式化、可选刻度标记以及可选坐标轴边缘线,而 Chart 负责比例尺域和绘图几何。

兼容性与迁移

  • 已发布默认值保留:是;该包仅限 canary,尚无稳定版本。
  • 兼容性类别:无公共 API 或默认值更改;Unicode 截断和自动抽稀仅有意更改包含多码元字素的标签,而具有代表性的 ASCII 行为得以保留。
  • 受控/非受控行为:不适用。
  • 迁移决策:无;本草案不授权公共 API 变更。

消费者迁移说明属于消费者文档和发布说明。

所有权边界

拥有

  • 为一条物理绘图边缘选择 Chart 提供的 x 或 y 比例尺。
  • 生成、格式化、抽稀、截断、定位和隐藏刻度标签。
  • 渲染其可选的边缘线和可选向外刻度标记。
  • 为刻度位置和可见性变化应用可选的过渡样式。

不拥有 / 非目标

  • 数据、域、比例尺构建或绘图尺寸 — 由 component:Chart 拥有。
  • 网格线 — 由 component:ChartGrid 拥有。
  • 产品特定的单位、区域设置选择或通过 tickFormat 提供的标签措辞 — 由产品调用点拥有。
  • 独立图表数据替代方案 — 由 component:Chart 及其周围的产品内容拥有。

公共概念

概念 闭合值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
物理边缘 top、right、bottom、left 选择绘图边缘、比例尺轴、变换和向外标签侧。 每个坐标轴必需。 无 component:ChartAxis 实验性 未知值会被 TypeScript 拒绝。
刻度目标 有限数值 向 d3 请求近似的连续比例尺刻度数量。 连续比例尺;同时配置自动格式化器。 5 component:ChartAxis 实验性 负值/非有限值回退到 5;小数向下取整;值上限为 1000。
标签上限 数字或缺失 当生成的标签集合超出请求的上限时,均匀跳过标签。 所有比例尺。 根据可用空间自动设置 component:ChartAxis 实验性 超出预期正整数数量范围之外的值未作规定。
标签格式化器 (value: unknown) => string 或缺失 替换 band 字符串或 d3 连续比例尺格式化器。 每个刻度。 适合比例尺的内置格式化器 component:ChartAxis 实验性 消费者格式化器抛出的异常会向上传播。
标签截断 正字符数或缺失 保留那么多用户感知的字符,然后追加省略号。 每个已格式化标签。 缺失 component:ChartAxis 实验性 零/省略时禁用截断;其他无效值未作规定。
边缘线 显示或隐藏 沿所选坐标轴边缘渲染一条线。 每个边缘;刻度标记强制启用。 仅对 bottom 显示 component:ChartAxis 实验性 不适用。
刻度线 显示或隐藏 在每个可见刻度标签旁渲染一条向外垂直的标记。 每条边。 隐藏 component:ChartAxis 实验性 不适用。
刻度过渡 动画或即时 在比例尺变化期间对刻度变换和透明度进行动画处理。 生成的刻度。 动画 component:ChartAxis 实验性 不适用。

行为与布局契约

草稿需求会标明其依据,以免观察到的代码被误认为是有意设计。

ID 候选不变式 依据 草稿评审状态
FR1 顶部或底部坐标轴 MUST 使用 Chart 的 x 比例尺;左侧或右侧坐标轴在存在分类 y 比例尺时 MUST 使用它,否则使用线性 y 比例尺。 实现、类型和聚焦测试 待验证
FR2 连续刻度生成 MUST 在 d3 刻度生成及其默认格式化器中使用同一个经过清理的计数;带状比例尺 MUST 在抽稀之前使用其完整定义域。 实现 待验证
FR3 提供的 tickFormat MUST 优先生效;否则连续比例尺使用 d3 格式化,带状值使用 String。 实现和聚焦测试 待验证
FR4 显式 maxTicks MUST 优先于由尺寸推导出的上限。 实现和聚焦测试 待验证
FR5 截断 MUST 保留完整的 Unicode 字素簇,同时保持文档所述的“内容计数加省略号”输出。 聚焦的红/绿测试和 Unicode Standard Annex #29 已确定
FR6 自动水平密度 MUST 以用户感知的字符数而非 UTF-16 存储单元来估算格式化标签的长度。 聚焦的红/绿等价测试和 Unicode 分段 已确定
FR7 底部 MUST 默认显示边缘线,其他边缘 MUST 默认隐藏它。showTicks MUST 强制启用边缘线,并为每个保留的刻度渲染一个标记。 实现、JSDoc、聚焦测试和 Storybook 待验证
FR8 底部和右侧坐标轴 MUST 平移到对应的绘图边缘。顶部和左侧保持在绘图原点。标签和刻度线从该物理边缘向外延伸。 实现和聚焦测试 待验证
FR9 在正负混合的线性 y 定义域上,底部边缘线 MUST 与 y=0 对齐;分类 y 将其留在绘图边缘。 实现 待验证
FR10 当 animated 为 true 时,刻度移动和可见性可以过渡;为 false 时 MUST 立即生效。更新期间,超出范围的刻度保持挂载状态且透明度为零。 实现和流式示例;动效意图尚未确定 人工决策

允许的变化

  • AV1 — 刻度数。 d3 可以选择更接近的连续刻度数,而不是请求的数量。
  • AV2 — 标签集合。 自动和显式的密度限制可以省略等距标签,同时保持其比例尺顺序。
  • AV3 — 提供的文本。 产品调用点可以通过 tickFormat 使用自己的单位和区域设置来格式化值。

代表性状态

状态 必需的不变式 允许的变化
底部分类轴 带状标签居中;默认显示边缘线。 自动密度可以省略标签。
顶部分类轴 带状标签在顶部边缘外侧渲染。 除非被请求,否则边缘线保持隐藏。
左侧连续轴 d3 标签在左侧边缘外侧渲染。 d3 选择合适的刻度值。
右侧连续轴 坐标轴平移到右侧边缘,标签在其外侧渲染。 d3 选择合适的刻度值。
垂直分类型 行标签使用 yBandScale 并与条带中心对齐。 自动密度可能省略标签。
显式格式化 每个保留的标签都使用所提供的格式化器。 消费者自行决定措辞和单位。
截断的标签 完整的字素簇位于附加的省略号之前。 调用方选择内容字符限制。
显示刻度线 每个保留的标签都有一个向外的标记和一条边缘线。 边缘线可见性输入被并入此状态。
混合符号线性 y 数据 底部线条表示 y=0,而不是绘图边界。 精确像素位置依据所提供的域。
流式/变化的域 刻度位置和可见性更新;动画遵循 animated。 刻度标识依据原始值。

转换与优先级顺序

  • ORD1 — 比例尺。 解析物理方向 → 选择 Chart 比例尺 → 生成并格式化每个刻度一次 → 推导出字素感知的密度上限 → 均匀过滤标签。
  • ORD2 — 标签。 应用所提供的格式化器或比例尺默认值 → 截断时保留完整的字素簇 → 渲染结果。
  • ORD3 — 边缘线。 解析位置默认值 → 应用 showAxisLine → 当 showTicks 为真时强制显示线条。

性能与资源

  • PR1 — 有界连续刻度。 清理机制将 d3 请求限制在 1000,因此消费者值无法分配无界刻度数组。
  • PR2 — 派生刻度状态。 刻度生成和格式化保持渲染派生且已记忆化;每个生成的标签只格式化一次,并在密度和渲染之间共享;ChartAxis 不拥有任何监听器、观察器、定时器或持久资源。

无障碍契约

  • AR1 — 可见文本完整性。 截断的刻度标签 MUST 在 Unicode 字素簇边界下保留完整的用户感知字符。
  • AR2 — Chart 级替代内容。 ChartAxis 在 Chart 的命名图像内渲染。Chart 拥有无障碍图表名称和支持的小数据表;轴标签和指针内容不会取代该替代内容。
  • AR3 — 嵌套轴语义缺口。 该实现当前输出一个带位置标签的 role="group"。该组是否应在 Chart 的 role="img" 之下被独立暴露和定位,仍未得到验证,需要所有者评审。

设计关系

解剖结构或状态 设计需求 表征权威 层级角色 组件契约
轴边缘线 在存在时确立物理绘图边缘的基准。 未定;未链接任何当前设计记录 支撑 FR7, FR9
刻度线 将保留的标签与比例尺上的位置关联。 未定;未链接任何当前设计记录 支撑 FR7
刻度标签 在绘图四周保留可读的值/类别文本。 Unicode 字素边界确定文本完整性 支撑 FR3, FR5, FR6, AR1
刻度过渡 在比例尺变化期间显示连续性。 未定;design:motion 仍处于草稿状态 支撑 FR10

主题化解剖

{
  "Axis edge line": {
    "none": {
      "reason": "unsettled: ChartAxis consumes semantic color tokens but no current component or family contract decides whether the line is a public theme target."
    }
  },
  "Tick marks": {
    "none": {
      "reason": "unsettled: ChartAxis consumes semantic color tokens but no current component or family contract decides whether tick marks are a public theme target."
    }
  },
  "Tick labels": {
    "none": {
      "reason": "unsettled: ChartAxis consumes semantic color tokens but no current component or family contract decides whether labels are a public theme target."
    }
  }
}

族与系统关系

  • 当前没有族或设计记录管辖 ChartAxis。
  • architecture:component-test-sufficiency 负责合理的公共状态划分、可观察的断言,以及先失败后成功的审计修复。
  • architecture:component-theming-surface 负责解剖结构到目标的映射安排;仅消费 token 本身并不会使 ChartAxis 被纳入公共组件主题化。
  • spec:AST-002 负责公共 API 准入,并禁止审计将新的公共选择偷偷带入修复中。
  • spec:AST-029 负责本次观察性回填、封闭证据接收、安全修复和 fail-closed 资格报告。

验证映射

契约 验证 代表性状态 变更或失败预期 审计部分
FR1, FR8 ChartAxis.test.tsx;ChartAxis.stories.tsx 上、右、下、左;带状和线性 边缘使用了错误的比例尺、变换或向外的标签侧。 audit:ChartAxis/behavior-layout
FR2, FR3 ChartAxis.test.tsx 默认计数;band、linear 和自定义格式化 生成与格式化不一致,或提供的格式化器被忽略。 audit:ChartAxis/behavior
FR4 ChartAxis.test.tsx 自动上限和显式 maxTicks 显式上限不再优先于基于尺寸的抽稀。 audit:ChartAxis/behavior
FR5, FR6, AR1 红-绿字素回归测试;密度测试;浏览器故事 ASCII、emoji、旗帜和 ZWJ 标签;被截断的宽/窄绘图区 可见标签拆分字素,或感知宽度相等的标签保留了不同的刻度。 audit:ChartAxis/i18n-testing
FR7 ChartAxis.test.tsx;Axes & Grids Storybook fixture 默认状态;请求线条;请求刻度 刻度标记丢失其边缘线,或线条默认值发生改变。 audit:ChartAxis/behavior
FR9 源码审查;浏览器证据仍待确认 仅正值、仅负值、混合符号、y-band 混合符号的零线移动到边缘,或分类轴穿过绘图区。 audit:ChartAxis/behavior-design
FR10 流式故事;exact-head 浏览器证据仍待确认 动画、即时、进入/离开的刻度 禁用动画后仍保留过渡效果,或移动中的标签跳转到陈旧几何位置。 audit:ChartAxis/design-testing
AR2, AR3 图表无障碍测试;axe 包;无障碍树审查 标题/副标题、小数据表、嵌套轴组 图表失去其替代文本,或未经审查的嵌套语义声明被当作事实。 audit:ChartAxis/accessibility

决策日志

无。本草案记录了观察到的行为和一处客观的 Unicode 修正;它不批准新的 ChartAxis 策略。

开放问题

  • OQ1 — 轴语义。 ChartAxis 应继续作为 Chart 单个命名图像中的纯视觉内容,还是将每个轴暴露为独立本地化的无障碍组?(human-api)

内容边界

本文件不重复使用方的 prop 表格/示例、当前审计结果、实施步骤或共享系统规则;它链接到各自的归属文档。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx