跳转至

图标变体、主题尺寸与组件图标插槽系统规范

意图

主题决定图标的外观:

  • Icon 接受可选的 variant。主题一次性列出其支持的变体名称,主题图标条目可以是最终尺寸与该变体的纯函数,因此主题可将两者映射到其图标库自身的图形或属性。
  • 主题通过 Icon 样式表目标设置每个 Icon 尺寸的维度。
  • 组件将可主题化的图标暴露为 componentIcons 插槽,插槽条目可依据组件的类型化状态解析,因此主题可决定按下、选中或禁用状态下的图标外观。

非目标

  • 外观或字重轴、按图标的能力声明、自适应变体树,或由 Astryx 定义的变体名称。
  • 新的 Icon 尺寸名称。
  • 额外的组件图标映射、图标角色概念、嵌套的按状态映射,或复合状态键。
  • 直接传递给 Icon 的图标组件的变体。它们按原样渲染,永远不会收到 variant;Icon 的目标、尺寸和颜色仍适用于它们。
  • 替换组件通过指示器绘制的有状态控件标记。这些仍由 defineTheme({indicators})(FR15)负责。
  • 组件拥有的图标框如何跟随主题尺寸,以及哪些组件字形通过 Icon 渲染。
  • DOM 或 SVG 测量、SVG 合成,或为单个请求混合两个来源的图形。
  • 满足此契约的等效内部实现仍然有效。

需求

变体与主题条目

FR1 — 主题图标条目是节点或请求的函数。 对于语义化或命名空间键,DefineThemeInput.icons 和进程级注册接受 React 节点或接收 {size, variant} 的函数,其中 size 是最终的 Icon 尺寸,variant 是活动主题列出的变体,或 undefined。概念上:

type IconRequest<Variant extends string = IconVariant> = Readonly<{
  size: 'xsm' | 'sm' | 'md' | 'lg';
  variant?: Variant;
}>;

type IconEntry<Variant extends string = IconVariant> =
  React.ReactNode | ((request: IconRequest<Variant>) => React.ReactNode);

主题将尺寸和变体映射到其库自身的属性或图形:

defineTheme({
  name: 'brand',
  iconVariants: ['outline', 'filled'],
  icons: {
    info: ({size, variant}) => (
      <InfoIcon
        weight={
          variant === 'filled' ? 'fill' : size === 'sm' ? 'bold' : 'regular'
        }
      />
    ),
  },
});

FR2 — 主题一次性列出其变体名称。 DefineThemeInput.iconVariants 是适用于整个主题的变体名称列表,绝不针对单个图标。设置了 iconVariants 的子主题会替换继承的列表;省略它的子主题则继承该列表。

FR3 — 该列表对主题和请求进行类型化。 在 defineTheme 内部,条目函数接收 variant,静态插槽请求和插槽解析器返回它,类型为主题列出的名称。Icon 的 variant 属性使用 IconVariant,即公开、可增强的 IconVariantMap 中的名称。主题构建会根据其构建的主题写入该映射的增强,方式与增强自定义组件值相同,应用程序也可以自行增强该映射。Astryx 永远不会从多个主题的列表派生变体类型;当应用程序加载多个已构建的主题时,TypeScript 会合并它们的增强,并且 FR4 会在活动主题未列出请求名称的任何地方渲染普通图标。

FR4 — 未列出的变体渲染普通图标。 只有当活动主题列出了请求的 variant,并且对于主题提供的条目,定义该条目的主题也列出了它时,Icon 才会将请求的 variant 传递给所选条目;子主题继承的条目保留定义它的主题的列表。否则,条目接收 undefined 并渲染其普通图形:省略的变体、未列出的变体,以及没有活动主题列表的请求,都以这种方式运行。进程级注册接收活动主题列出的变体。节点条目为每个变体渲染相同的节点。

FR5 — 变体适用于注册表图标。 直接传递给 Icon 的图标组件按原样渲染,不会收到 variant;Icon 不会将 variant 转发给它或 DOM。variant 仅选择图形:icon 主题化目标不反映它,因此它没有样式选择器。

FR6 — 源在请求之前解析。 主题条目优先于进程级注册,进程级注册优先于内置默认值;空值静态条目会回退到下一个源。所选函数的结果对该次解析是最终结果:空值结果不渲染任何字形,也绝不会回退到另一个源。

FR7 — 条目和解析器是纯函数且同步的。 它们仅根据输入计算结果,不使用钩子、DOM 或 SVG 测量、浏览器全局对象、网络访问、可变模块状态或副作用。

FR8 — 构建工具可以枚举主题的图标。 主题条目可能接收的每个请求都由其键与四种尺寸之一构成,并且要么没有变体,要么是该条目在 FR4 下可接收的一种变体。生成或子集化图标图形的构建工具可以精确地针对该集合调用每个条目;结果与条目在运行时返回的内容一致。

尺寸

FR9 — 条目接收解析后的尺寸。 Icon 通过 component:Icon ORD1(xsm、sm、md、lg)解析其尺寸,并将其传递给条目,条目为该尺寸选择图形。

FR10 — 主题在样式表中设置每个尺寸的维度。 Icon 主题化目标保证其尺寸选择器上的 width 和 height,因此 components.icon['size:sm'] 设置 sm 维度。没有主题样式时,尺寸在 16px 根字号下为 12、16、20 和 24px,并随根字号缩放。

组件图标插槽

  • FR11 — 组件图标是 componentIcons 插槽。 组件拥有的可主题化图标是 ComponentIconSlotMap 中的插槽,通过 componentIcons 映射,如 architecture:icon-resolution-and-component-slots 所述。true 值声明一个无状态插槽;对象类型声明插槽的只读状态字段。
  • FR12 — 插槽值可以是名称、null、静态请求或状态解析器。 componentIcons 接受 IconName、null、静态部分请求,或一个接收插槽状态并返回部分请求的纯同步函数。概念上:
type ComponentIconRequest = Readonly<{
  icon?: IconName | null;
  variant?: IconVariant;
  size?: 'xsm' | 'sm' | 'md' | 'lg';
}>;

type ComponentIconValue<State> =
  | IconName
  | null
  | ComponentIconRequest
  | ((state: Readonly<State>) => ComponentIconRequest | null | undefined);

无状态插槽接受除函数以外的所有形式。组件提供其状态;主题在普通解析器代码中处理状态组合:

componentIcons: {
  'example-nav-item-leading': ({selected}) => ({
    variant: selected ? 'filled' : 'outline',
  }),
}
  • FR13 — 部分结果逐字段回退。 调用方传入的图标内容优先于插槽。否则,请求中的 icon 替换组件的回退名称,variant 和 size 应用于最终渲染的名称。缺少 icon 时保留组件原本会渲染的名称,缺少 variant 时保留组件原本会请求的变体(或没有),缺少 size 时保留组件的大小。null、null 结果或 icon: null 隐藏图标;undefined 结果不改变任何内容。
  • FR14 — 插槽大小仅改变图标的大小。 解析后的 size 替换该插槽图标在组件中的大小。控件的高度、触摸目标、位置、颜色、交互和无障碍特性仍由组件决定,包括族群契约在各状态间固定的任何外部尺寸。
  • FR15 — 主题通过插槽设置状态相关图标。 将状态相关图标作为 componentIcons 插槽暴露的组件,会将该状态通过插槽传递,以便主题解析。组件若在没有插槽的情况下从自身状态选择共享图标名称,则在其契约添加插槽前继续保持此行为。调用方传入的按状态图标属性(如 pressedIcon 或 selectedIcon)作为调用方提供的图标内容。组件通过指示器绘制的有状态控件标记(如选中勾选、单选按钮或复选框框)仍是指示器:指示器接收其族群的状态,主题通过 defineTheme({indicators}) 按名称替换它。一个视觉元素绝不会同时是指示器和 componentIcons 插槽。
  • FR16 — 插槽状态是有文档记录的主题元数据。 插槽的状态字段与其插槽元数据一起,列在所属组件的文档中,以及 CLI 和文档站点的发现结果中。更改已发布的状态字段属于兼容性变更。

读取、构建的主题与服务器渲染

  • FR17 — 插槽解析是插槽函数的唯一调用方。 组件(包括在扩展 ComponentIconSlotMap 的包中的组件)将其插槽状态传递给 architecture:icon-resolution-and-component-slots 拥有的共享插槽解析逻辑。该解析调用主题的函数,并通过 Icon 渲染结果。任何公开的主题读取都不会调用或返回插槽函数。
  • FR18 — 公开读取返回节点和静态值。 注册表、扩展、快照和钩子读取,IconRegistry、DefinedTheme['icons'] 以及构建主题的图标导出返回 React 节点;函数条目在 {size: 'md'} 下读取。DefinedTheme['componentIcons'] 和构建主题的插槽导出是静态视图:按编写时的名称、null 和静态请求,解析器插槽被省略。DefinedTheme['iconVariants'] 是主题的列表。产品通过 Icon 请求大小或变体。
  • FR19 — 运行时、构建和服务器主题保持一致。 运行时主题、extends、构建输出、服务器渲染和水合解析为相同的节点。子主题的条目替换继承的相同键的条目。构建无法承载的函数会导致构建失败。服务器代码可以使用包含函数的主题解析图标;客户端代码将该主题传递给 Theme。
  • FR20 — 格式错误的解析器输出视为缺失。 未知的 icon、主题未列出的变体,或请求中四个名称之外的大小,会逐字段被忽略,并附带一条仅开发环境可见的警告。

平台支持

  • 支持下限:Astryx Core 支持的每个 React、服务器渲染和浏览器目标。
  • 不支持的行为:异步解析器,以及将包含函数的主题作为属性从服务器组件传递给客户端组件。
  • 浏览器验证:主题切换、嵌套主题、组件状态、已列出和未列出的变体,以及每种图标大小,都在主题的尺寸下渲染预期节点并水合到该节点。

当前状态影响

现有节点条目、直接图标组件、命名空间键、实例属性和读取继续正常工作。没有 iconVariants、函数条目或大小样式的主题渲染相同的图标。以下属主承担此变更:

  • component:Icon — 注册表模式接受 variant(FR4、FR5),使用 ORD1 解析的大小选择图稿(FR9),其目标保证大小选择器上的 width 和 height(FR10)。
  • architecture:component-theming-surface — INV14 将 Icon.variant 视为可主题扩展的轴向,其回退是不带变体的请求(FR3、FR4)。
  • architecture:icon-resolution-and-component-slots — 条目是节点或函数,所选函数的结果是最终的(FR1、FR6);从未发布的 selector-selected-option 插槽从 ComponentIconSlotMap 中移除,因为 Selector 通过 check 指示器绘制其选中选项标记(FR15);插槽值为 true 或状态形状,INV3 承认静态请求和状态解析器(FR11、FR12);INV8 允许插槽请求设置插槽的图标大小和变体(FR13、FR14);指示器保持独立(FR15);插槽解析是插槽函数的唯一调用方(FR17)。
  • architecture:theme-authoring-contract — iconVariants、函数条目和插槽函数被规范化和继承,公开读取保持节点值或静态值(FR2、FR18、FR19)。
  • architecture:theme-compilation — 构建输出再现函数条目、插槽解析器和变体列表,构建工具可以枚举主题的请求(FR8、FR19)。
  • architecture:theme-application — 客户端代码将包含函数的主题传递给 Theme(FR19)。
  • 消费者 theme 和 Icon 文档描述 iconVariants、函数条目、variant、大小样式和插槽解析器。

验证

契约 验证 代表性状态 变更或失败预期
FR1–FR7 注册表类型、解析器和 Icon 渲染测试 节点;函数;null;省略、已列出和未列出的 variant;无活动列表;被替换列表下的继承条目;主题、全局、默认;直接 来源混合、未列出的 variant 到达条目、variant 到达组件或 DOM
FR2–FR3 类型测试和主题构建扩充夹具 条目和解析器中列出的名称;子级替换列表;构建后的扩充;未知名称 条目遇到未列出的名称类型、子级合并列表,或 Astryx 从两个主题的列表推导出一个类型
FR8 针对运行时解析的构建枚举测试 每个键 × 四种尺寸 × 无 variant,以及条目能接收的每个 variant;被替换列表下的继承条目 枚举请求与运行时输出不同,或条目无法接收的 variant 被枚举
FR9–FR10 主题样式和尺寸测试 每种尺寸在有无主题样式两种情况下 带样式的尺寸不会改变字形尺寸,或未带样式的尺寸发生了改变
FR11–FR16 插槽类型、状态、回退、指示器、几何和元数据测试 true 插槽;状态插槽;静态请求;部分和完整结果;null;调用者内容;已记录状态 回退顺序改变、null 停止隐藏、插槽尺寸改变控件,或一个标记同时属于两种类型
FR17–FR19 公共读取、SSR、水合以及运行时/构建/扩展测试 单参数读取;静态视图;嵌套主题;子级替换;构建后的函数条目;客户端主题 公共读取返回函数,或构建结果与运行时结果不同
FR20 类型和返回字段测试 无效状态形状;未知图标;未列出的 variant;无效尺寸 格式错误的字段改变回退,或生产环境发出警告

决策日志

DEC-1 — 单一 variant 请求

参考: spec:AST-087/DEC-1 决策者: cixzhang, 2026-10-22

variant 系统在设计系统中是标准做法。Icon 携带一个可选的 variant,而较重或较轻的笔画是主题条目对最终尺寸的调整。

已拒绝:外观轴和字重轴,因为它们是产品特定的。

DEC-2 — 主题条目是尺寸和 variant 的函数

参考: spec:AST-087/DEC-2 决策者: cixzhang, 2026-10-22

主题条目是一个节点,或一个以最终尺寸和可选 variant 为参数的纯同步函数,返回提供的图形资源,因此主题拥有其图标库特有的一切。

已拒绝:逐图标能力声明和自适应 variant 树。

DEC-3 — 样式表设置图标尺寸

参考: spec:AST-087/DEC-3 决策者: cixzhang, 2026-10-22

主题通过 Icon 样式表目标设置每种 Icon 尺寸的维度。

已拒绝:主题新增的尺寸名称,因为使用该尺寸名称的组件在缺少主题时没有任何价值。

DEC-4 — componentIcons 保存组件图标

参考: spec:AST-087/DEC-4 决策者: cixzhang, 2026-10-22

全局图标映射表指明每个图标的用途,componentIcons 按组件插槽覆盖它。插槽可以在普通解析器代码中从带类型的组件状态解析其请求。

已拒绝:第二个组件图标映射表、图标角色概念、嵌套的按状态映射表,以及复合状态键。

DEC-5 — 主题设置依赖状态的图标

参考: spec:AST-087/DEC-5 决策者: cixzhang, 2026-10-22

组件以插槽形式暴露的依赖状态的图标,是主题通过其解析器做出的决定,因此每个实例都遵循同一规则。指示器保留有状态的控件标记,因为它们绘制的是家族状态,而非选择图标。

DEC-6 — 所选函数的结果即为最终结果

参考: spec:AST-087/DEC-6 决策者: cixzhang, 2026-10-22

一旦选中某个函数条目,其结果即对该请求的应答,因此图形资源永远不会混用两个来源,主题也可以故意不绘制任何内容。

DEC-7 — 产品通过 Icon 请求尺寸和 variant

参考: spec:AST-087/DEC-7 决策者: cixzhang, 2026-10-22

感知尺寸和 variant 的解析服务于 Astryx 组件和工具。公共读取返回 React 节点;在 {size: 'md'}(独立 Icon 的默认值)下读取函数条目。

DEC-8 — 解析器中格式错误的输出按字段逐个忽略

参考: spec:AST-087/DEC-8 决策者: cixzhang, 2026-10-22

解析器结果中的无效字段会被视为缺失,因此回退仍然会渲染,并只产生一条开发环境专用警告。

DEC-9 — 主题一次性列出其 variants

参考: spec:AST-087/DEC-9 决策者: cixzhang, 2026-10-22

一个主题级别的列表为调用者提供类型化名称,为构建工具提供一组有限的、可枚举的请求,并为未列出的 variant 提供一个不依赖主题的回退:不带 variant 的请求。

已否决:使用开放的 string,因为它无法为调用方提供类型,也无法为工具链提供有限集合;Astryx 从多个主题的列表中派生出一个变体类型。

DEC-10 — 插槽函数保留在插槽解析内部

参考: spec:AST-087/DEC-10 决策者: cixzhang,2026-10-22

只有共享的插槽解析会调用主题的插槽函数,并以组件传递的状态作为参数。公开的主题数据展示的是静态视图,因此读取方永远不会处理函数,也无需自行构造状态。

未决问题

无。

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