UI 视觉设计 / 系统课时

用 Alias 建立跨层级引用

用 Alias 建立跨层级引用

这一课把基础色、语义色和按钮背景连成可追踪的 Token 引用链,并用一个可运行的解析脚本验证:只修改基础颜色,两个下游别名就能取得新值,同时掌握整值引用与 JSON Pointer 的边界。

学习目标

  • 正确编写 DTCG 花括号 Alias,并判断何时需要 JSON Pointer。
  • 建立基础、语义、组件三层颜色引用,避免重复硬编码。
  • 运行解析检查,验证值传播并识别断链、循环和类型不匹配。

分清两种引用的目标

按 DTCG Format 2025.10,$value 中的 {base.blue.500} 是整值别名:路径按点号分段,解析器自动读取目标 Token 的整个 $value。颜色 Token 的值是包含 colorSpace 和 components 的对象,而不只是十六进制字符串。

当需要读取对象内部属性时,使用 $ref 搭配 JSON Pointer。下表对应同一份文件里的基础色:

引用写法 实际读取 合适场景
{base.blue.500} 基础色的完整 $value 语义色、按钮背景
#/base/blue/500/$value 完整颜色对象 需要显式文档路径
#/base/blue/500/$value/components/0 components 的第一个数字,即红色通道 复用复合值内的单个属性

花括号不能写成 {base.blue.500.components.0} 来读取数组元素;JSON Pointer 使用 / 分段,对数组用从 0 开始的索引。属性名若包含 / 或 ~,分别转义为 ~1 和 ~0。

基础色经语义别名与组件别名解析,并联动更新红色分量

编写三层 Token JSON

新建 tokens.tokens.json,填入以下有效 JSON。base 保存实际颜色,semantic.action.primary 表达交互主色的用途,component.button.background 只引用语义层;额外的 redChannel 专门演示属性级 Pointer。

json
{
  "base": {
    "blue": {
      "500": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0, 0.4, 0.8],
          "hex": "#0066CC"
        }
      }
    }
  },
  "semantic": {
    "action": {
      "primary": {
        "$type": "color",
        "$value": "{base.blue.500}"
      },
      "redChannel": {
        "$type": "number",
        "$ref": "#/base/blue/500/$value/components/0"
      }
    }
  },
  "component": {
    "button": {
      "background": {
        "$type": "color",
        "$value": "{semantic.action.primary}"
      }
    }
  }
}

这里 base.blue.500 是唯一持有颜色数值的 Token,$type: "color" 明确其类型;redChannel 取到数字,因此声明为 number。在 2025.10 格式中,sRGB 颜色使用结构化对象;hex 是可选辅助表示,本例的 #0066CC 与 [0, 0.4, 0.8] 对应。不要把两个 Alias 改成独立的 #0066CC,否则基础色更新不会传递。

运行解析并验证基础色变更

使用 Node.js 18 或更新版本。将下面脚本保存为同目录的 resolve.mjs;它读取 JSON,并递归处理本例的整值 Alias 与文档内 JSON Pointer,保留访问路径检查循环。这个最小解析器用于理解解析过程,不是完整 DTCG 合规校验器。

js
import { readFileSync } from "node:fs";
import assert from "node:assert/strict";

const tokens = JSON.parse(readFileSync("tokens.tokens.json", "utf8"));

function resolve(path, stack = []) {
  const id = path.join("/");
  if (stack.includes(id)) throw new Error(`循环引用:${id}`);
  const visited = [...stack, id];

  const node = path.reduce((value, segment) => {
    if (value === null || typeof value !== "object" || !(segment in value)) {
      throw new Error(`引用路径不存在:${id}`);
    }
    return value[segment];
  }, tokens);

  // 整值别名沿路径寻找目标的 $value
  if (typeof node === "string" && /^\{[^{}]+\}$/.test(node)) {
    return resolve([...node.slice(1, -1).split("."), "$value"], visited);
  }
  if (node !== null && typeof node === "object") {
    if (typeof node.$ref === "string") {
      if (!node.$ref.startsWith("#/")) throw new Error("仅支持文档内 Pointer");
      // JSON Pointer 路径需要还原 ~1(斜杠)与 ~0(波浪号)
      const target = node.$ref.slice(2).split("/")
        .map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"));
      return resolve(target, visited);
    }
    if (Object.hasOwn(node, "$value")) {
      return resolve([...path, "$value"], visited);
    }
  }
  return node;
}

function report(stage) {
  const color = resolve(["component", "button", "background"]);
  const red = resolve(["semantic", "action", "redChannel"]);
  // 检查属性引用与组件整色引用取到同一基础值
  assert.equal(color.components[0], red);
  console.log(`${stage}: ${color.hex}, red=${red}`);
}

report("修改前");
tokens.base.blue["500"].$value = {
  colorSpace: "srgb",
  components: [0.2, 0.4, 0.8],
  hex: "#3366CC"
};
report("修改后");
console.log(`源引用: ${tokens.semantic.action.primary.$value}`);

在两个文件所在目录执行:

bash
node resolve.mjs

预期输出:

text
修改前: #0066CC, red=0
修改后: #3366CC, red=0.2
源引用: {base.blue.500}

第一次解析时,按钮背景沿 component.button.background、semantic.action.primary 找到基础色。脚本随后仅改变内存中的 base.blue.500.$value,第二次解析就取到 #3366CC;磁盘上的源文件没有被改写,Alias 字符串也始终不变。实际构建时应在输入发生变更后重新解析并生成目标平台变量,不能期望已导出的静态 CSS 自动变化。

排除断链、循环与类型错误

可以对这份示例做三次独立检查,每次改完恢复原值再继续:

  1. 把 semantic.action.primary.$value 临时改成 {base.blue.600},脚本会因目标不存在而报错。修改 Token 名称或路径时,必须同步更新全部引用。
  2. 把它改成 {component.button.background},会形成按钮背景与主色的循环;示例脚本会抛出循环引用错误。应恢复单向的基础色到语义色再到组件色关系。
  3. 把 component.button.background 的定义替换为 {"$type":"color","$ref":"#/base/blue/500/$value/components/0"},解析结果会变成数字而非颜色对象,示例脚本在访问颜色分量时会报错。生产构建还需要用符合 DTCG 的校验器检查引用结果与声明的 $type 是否匹配。

可对照 DTCG Format 2025.10 的 Aliases / References 章节 核对引用规则;交付时同时检查三件事:源别名未被展开、解析后类型正确、基础值变化能传递到组件。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Alias 建立跨层级引用

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通