跳转至

样式库兼容性系统规格

{
  "paths": [
    "packages/core/src/**",
    "packages/lab/src/**",
    "packages/charts/src/**",
    "packages/richtext/src/**",
    "packages/vega/src/**"
  ]
}

意图

产品使用其代码库中已有的任何方案来对 Astryx 组件进行样式化:StyleX、类名 CSS(CSS 模块、工具类、全局样式表)或内联样式。组件接受的每一个样式输入都会从以上每种方案中到达其元素,因此组件的任何部分都不能仅通过 StyleX 来设置样式。

非目标

  • 组件是否为某个部分提供样式入口。部件输入是一个新的公开 prop,需根据 spec:AST-002/DEC-1 准入;本规格对已准入的部件输入进行约束。
  • 样式输入在单个元素上的组合顺序,由 architecture:public-component-api INV6 负责。
  • 主题令牌和主题目标,由 architecture:theme-tokens 和主题记录负责。
  • 满足本契约的等价内部实现仍然有效。

需求

  • FR1 — 一个部件的样式输入以集合形式提供。 为除根元素之外的某个元素接受样式输入的组件,MUST 同时为该元素接受 <part>Xstyle、<part>ClassName 和 <part>Style 三种输入,且三者的 <part> 词必须相同。三者 MUST 到达同一个元素,并像根元素的 xstyle、className 和 style 一样在该元素上组合。
  • FR2 — 不允许仅限 StyleX 的样式输入。 为元素设置样式的公开 prop MUST NOT 仅接受 StyleX 样式,除非同一元素也通过公开 prop 接受类名和内联样式。

平台支持

  • 支持的功能/引擎基线:不变;本契约不新增任何 CSS 特性。
  • 不支持的行为:无;类名和内联样式在所有受支持的引擎中均可工作。
  • 浏览器验证:不需要;FR1 和 FR2 在声明层和渲染层得到证明。

当前状态影响

  • architecture:public-component-api 新增一条不变量:部件的样式输入以集合形式提供,由 spec:AST-071/DEC-1 决定。
  • 已发布但不符合 FR1 和 FR2 的公开 prop 为 ComplexSelector.contentXstyle、ContextMenu.triggerXstyle 和 BaseTypeahead.inputXStyle。它们是已知缺口,而非先例:不得引用它们来准入任何新的部件输入。

验证

契约 验证 代表性状态 变更或失败预期
FR1 对生成的声明清单进行 Public-API 审查;组件渲染测试 分别通过 StyleX、类名和内联样式设置样式的部件输入 缺少 <part>ClassName和Style 的 <part>Xstyle`,或其落在其他元素上,则失败
FR2 对每个使用 StyleX 样式类型化的导出 prop 进行 Public-API 审查 跨导出组件的根输入和部件输入 某 StyleX 类型化的 prop 在其元素上没有类名和内联样式对应项,则失败

已知验证缺口:没有自动化检查强制实施 FR1 或 FR2;通过 Public-API 审查来应用它们。

决策日志

DEC-1 — 每种样式输入均可从每种样式方案中工作

参考: spec:AST-071/DEC-1 决策人: cixzhang, 2026-10-09

Astryx 被不使用 StyleX 的产品所采用。一个仅能通过 xstyle 访问的部件,会让使用类名或内联样式进行样式化的代码库无法访问该部件,而且每一个这样的 prop 都会成为下一个部件复制的先例。因此,一个部件的样式输入要么是根元素已接受的完整集合,要么就不被准入。

已否决:仅准入部件的 xstyle,并在有请求时再补充其对应项——非 StyleX 调用方在有人提出需求之前始终被排除在外。

开放问题

  • OQ1 — 已知不合规的 prop 如何达到合规 (human-api): ComplexSelector.contentXstyle、ContextMenu.triggerXstyle 和 BaseTypeahead.inputXStyle。

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