跳转至

ChartLegend 组件契约

契约概览

领域 契约
公共契约 无 API 形状或默认值变更。本草案记录当前的条目、逻辑位置、对齐方式、列表语义和空输出表面。
行为 非空条目按顺序以命名列表渲染;顶部/底部使用换行行,起始/结束使用列,对齐保持逻辑性,省略或空条目不渲染任何内容。
最终用户影响 图表阅读者获得可见的系列名称,并配以装饰性标记形状的颜色键;本次审计不改变任何渲染行为。
构建者影响 现有调用点保持有效,并为已发布的 props、默认值、组合和可访问性边界获得直接的 CLI 文档。
兼容性/就绪状态 该包仍仅为 canary 版本。本观察性草案不具有权威性;通过任意调用者颜色区分系列的问题仍未解决。
审查检查 拒绝公共形状/默认值的变更、列表语义或本地化的丢失、条目重排序、错误的方向,或任何声称仅凭颜色就足够的新主张。
治理规则 spec:AST-029/FR3–FR7, architecture:component-test-sufficiency/INV1–INV11, architecture:component-theming-surface/INV1–INV6, 以及 spec:AST-002。

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

意图

ChartLegend 展示图表系列的可见图例。它负责有序的图例列表、条目布局、标记形状的装饰性色块、系列标签以及空渲染。父级 Chart 可以派生其条目并将生成的图例放置在绘图区域周围;调用者也可以直接渲染该组件。

兼容性与迁移

  • 已发布的默认值保留:在 canary 层面为是;该包没有稳定版本。
  • 兼容性类别:无公共 API、默认值或渲染行为变更。
  • 受控/非受控行为:不适用。
  • 迁移决策:无;本草案不授权公共 API 变更。

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

所有权边界

拥有

  • 按调用者顺序渲染非空图例条目。
  • 根据逻辑位置选择水平或垂直布局。
  • 沿相关逻辑轴对齐条目集合。
  • 将每个可见系列标签与装饰性色块形状和调用者颜色配对。
  • 本地化并暴露图例列表名称。

不拥有 / 非目标

  • 系列派生、调色板分配、绘图放置或图表渲染顺序——由 component:Chart 及其系列工具拥有。
  • 图表的可访问名称、数据替代或产品摘要——由 component:Chart 和产品调用点拥有。
  • 自定义图例交互、选择、筛选或可见性控制。
  • 保证任意调用者提供的颜色单独即可区分每个系列。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
图例条目 有序数组或空 提供每个条目的标签、颜色和可选标记类型。 每个 ChartLegend [] component:ChartLegend 实验性 省略和空数组不渲染任何内容。
逻辑位置 top, bottom, start, end 给出 Chart 放置意图并选择行或列方向。 非空 bottom component:ChartLegend 实验性 由导出的 TypeScript 联合类型封闭。
对齐方式 start, center, end 在水平行内分布条目,或在垂直列表中水平对齐条目。 非空 start component:ChartLegend 实验性 由导出的 TypeScript 联合类型封闭。
色块形状 bar 为方形;其他所有类型为线形 在视觉上呼应条目的标记类别,而不添加 AT 内容。 每个渲染条目 line component:ChartSwatch 实验性 未知和省略的类型使用线形。
列表语义 每个条目一项的本地化列表 将可见标签分组为一个命名的图例。 非空 内置 component:ChartLegend 实验性 不适用。

行为与布局契约

草案需求会标明其依据,以免观察到的代码被误认为是有意为之的决策。

ID 候选不变量 依据 草案审查状态
FR1 ChartLegend 在 items 被省略或为空时 MUST 不渲染任何内容,否则 MUST 保持条目顺序并保留重复标签。 实现和针对性测试 验证
FR2 每个渲染项 MUST 保持为一个可见标签,外加一个对辅助技术隐藏的 ChartSwatch,放在一个列表项内。 实现、针对性测试和浏览器无障碍检查 验证
FR3 根元素 MUST 保持为本地化的具名列表,每个提供的条目恰好对应一个列表项。 实现、本地化目录、针对性测试和 axe 验证
FR4 top 和 bottom MUST 使用可换行的水平行;start 和 end MUST 使用垂直列。 实现和已实测确认的浏览器矩阵 验证
FR5 对齐方式 MUST 保持逻辑语义:对于 top 和 bottom,它沿内联轴分布行;对于 start 和 end,它在垂直列表内水平对齐条目,包括在 RTL 下。 实现和已实测确认的 LTR/RTL 浏览器证据 验证
FR6 Swatch 形状对于 bar MUST 为正方形,对于所有其他类型或省略类型 MUST 为短线条;调用方颜色负责其着色。 ChartSwatch 实现和针对性测试 验证
FR7 长标签 MUST 在 320 CSS 像素宽度下换行且不产生水平视口溢出;当前未暴露固定宽度截断约定。 已实测确认的浏览器证据 验证

允许的变化

  • AV1 — 可用空间。 水平条目随容器宽度变窄而换行到更多行;垂直条目标签可在可用内联尺寸内换行。
  • AV2 — 系列绘制。 Swatch 颜色由调用方拥有,并可能因图表调色板和渲染表面而异,但受下面未解决的可区分性要求约束。

代表性状态

状态 必需不变量 允许的变化
省略 / 空条目 不渲染任何图例 DOM。 周围的 Chart 布局可以省略其图例槽位。
底部或顶部 条目形成一个可换行的水平列表。 逻辑对齐和换行取决于可用宽度。
起始或结束 条目形成一个垂直列表。 对齐会改变每个条目在列表中的水平位置。
重复标签 每个提供的条目仍然存在且保持顺序。 内部 React key 可以消除相同标签的歧义。
长而窄的标签 标签换行,页面保持无水平溢出。 条目和列表高度随内容增长。
RTL 逻辑 start/end 行为遵循计算出的文档方向。 视觉条目顺序遵循 flex 和方向模型。

转换与优先级顺序

  • ORD1 — 渲染。 默认省略的 props → 零条目时返回空 → 从逻辑位置推导方向 → 按调用方顺序映射条目 → 将逻辑对齐应用于列表根元素。
  • ORD2 — 条目。 将标记类型映射为 Swatch 形状 → 使用调用方颜色绘制 Swatch → 将调用方标签作为辅助文本渲染。

性能与资源

  • PR1 — 派生输出。 ChartLegend 保持为渲染派生组件。它不拥有任何 state、Effect、监听器、观察器、计时器、请求或持久资源。

无障碍契约

  • AR1 — 具名结构。 非空图例会暴露一个本地化的具名列表,并为每个可见系列标签提供一个列表项。
  • AR2 — 装饰性 Swatch。 系列 Swatch 对辅助技术保持隐藏;相邻的可见文本提供每个条目的名称。
  • AR3 — 图例级替代。 图例补充而非替换父级 Chart 的无障碍名称和等效数据表示。
  • AR4 — 组合关联证据。 独立的 ChartLegend 证据不能确立读者如何将图例条目与渲染的图表标记关联起来。在决定是否需要额外的视觉提示以及由哪一层负责之前,请在组合后的 Chart 或产品调用点中评估相同标记形状的系列。

设计关系

解剖部位或状态 设计需求 呈现权属 层级角色 组件契约
图例列表 将相关系列条目分组,而不添加交互状态。 未定;当前未关联任何设计记录 支持 FR1, FR3–FR5
图例条目 让每个标签与一个系列键保持关联。 未定;当前未关联任何设计记录 支持 FR1–FR3
系列色块 呼应图表标记,同时对 AT 保持装饰性。 未定;当前行为是调用方提供颜色 支持 FR2, FR6, AR2–AR4
系列标签 将系列命名为可读的支持性文本。 委托给 Text 支持 FR2, AR1–AR2

主题化解剖

{
  "Legend list": {
    "delegatesTo": {"owner": "component:Stack", "target": "stack"}
  },
  "Legend entry": {
    "delegatesTo": {"owner": "component:Stack", "target": "stack"}
  },
  "Series swatch": {
    "none": {
      "reason": "unsettled: ChartSwatch owns the visible painter but exposes no current public target; this draft does not decide future reachability."
    }
  },
  "Series label": {
    "delegatesTo": {"owner": "component:Text", "target": "text"}
  }
}

ChartLegend 将列表和条目的布局委托给 Stack 的现有目标,将系列标签委托给 Text。ChartSwatch 是可见色块的绘制器,但目前不暴露公共主题目标。该解剖部位是否应具有可达性,仍由 ChartSwatch 与主题化负责人决定。

家族与系统关系

  • 目前没有家族或设计记录管辖 ChartLegend。
  • architecture:component-test-sufficiency 负责合理的公共状态划分、可观测断言和审计证据质量。
  • architecture:component-theming-surface 负责解剖部位到目标的分配;由主题化原语组合并不会使 ChartLegend 纳入公共组件主题化。
  • spec:AST-002 负责公共 API 准入,并阻止本次审计新增或重新解释公共选择。
  • spec:AST-029 负责本次观察性回填、封闭式证据接收、安全修复和 fail-closed 资格报告。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1–FR3 ChartLegend.test.tsx;聚焦的 axe 运行 省略、空、非空、本地化、重复 空输出从 DOM 中移除、条目消失,或列表语义/名称丢失。 audit:ChartLegend/accessibility-behavior
FR4–FR5, FR7 附凭据的 Storybook 浏览器矩阵;RTL 几何凭据 行、列、所有对齐方式、320px 长文本、RTL 方向、逻辑对齐、换行或视口包含关系发生变化。 audit:ChartLegend/layout-responsive-rtl
FR6 ChartLegend.test.tsx;ChartSwatch.test.tsx 柱状、线状、省略和未知类型 柱状类型失去方形、其他类型获得方形,或色块绘制不再跟随颜色。 audit:ChartLegend/behavior-design
AR1–AR3 role/name DOM 断言;聚焦的 axe 运行;Chart 测试 独立图例与 Chart 组合图例 标签离开命名列表,或图例取代 Chart 的替代方案。 audit:ChartLegend/accessibility
AR4 未来组合 Chart/调用点的浏览器证据 至少两个相同标记形状的系列及其渲染的标记 在记录缺陷或指定负责人之前,关联证据必须覆盖图例和绘制出的标记。 audit:ChartLegend/unscored-evidence-gap

决策日志

无。本草案只记录观察到的行为和证据缺口。

待解决问题

  • OQ1 — 组合系列关联。 在组合的 Chart 或产品调用点中,包含两个或更多相同标记形状系列的证据是否表明读者需要额外的视觉关联提示?如果是,由哪一层负责:ChartLegend、父级 Chart/系列定义,还是产品调用点?(human-design)
  • OQ2 — 色块主题可达性。 系列色块是否应成为公共的 ChartSwatch 主题目标,还是其绘制样式应继续由调用方所有?(human-api)

内容边界

本文件不重复使用方 prop 表/示例、当前审计结果、实现步骤或共享系统规则。它链接到这些内容的负责人。

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