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。
{
"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 合规校验器。
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}`);在两个文件所在目录执行:
node resolve.mjs预期输出:
修改前: #0066CC, red=0
修改后: #3366CC, red=0.2
源引用: {base.blue.500}第一次解析时,按钮背景沿 component.button.background、semantic.action.primary 找到基础色。脚本随后仅改变内存中的 base.blue.500.$value,第二次解析就取到 #3366CC;磁盘上的源文件没有被改写,Alias 字符串也始终不变。实际构建时应在输入发生变更后重新解析并生成目标平台变量,不能期望已导出的静态 CSS 自动变化。
排除断链、循环与类型错误
可以对这份示例做三次独立检查,每次改完恢复原值再继续:
- 把
semantic.action.primary.$value临时改成{base.blue.600},脚本会因目标不存在而报错。修改 Token 名称或路径时,必须同步更新全部引用。 - 把它改成
{component.button.background},会形成按钮背景与主色的循环;示例脚本会抛出循环引用错误。应恢复单向的基础色到语义色再到组件色关系。 - 把
component.button.background的定义替换为{"$type":"color","$ref":"#/base/blue/500/$value/components/0"},解析结果会变成数字而非颜色对象,示例脚本在访问颜色分量时会报错。生产构建还需要用符合 DTCG 的校验器检查引用结果与声明的$type是否匹配。
可对照 DTCG Format 2025.10 的 Aliases / References 章节 核对引用规则;交付时同时检查三件事:源别名未被展开、解析后类型正确、基础值变化能传递到组件。