本文详解如何使用 Figma Plugin API 将组件属性（如 TokenName、TokenColor）正确绑定到内部 TextNode 的 characters 字段，实现组件实例化后自动填充内容，避免手动遍历节点赋值。
本文详解如何使用 figma plugin api 将组件属性（如 tokenname、tokencolor）正确绑定到内部 textnode 的 `characters` 字段，实现组件实例化后自动填充内容，避免手动遍历节点赋值。
在 Figma 插件开发中，创建可复用的文档化组件（如颜色令牌卡片）时，仅调用 addComponentProperty() 并不足以让子文本节点响应属性变化——必须通过 componentPropertyReferences 显式建立「属性 ID → 节点字段」的映射关系。否则，即使调用 setProperties() 设置值，文本内容也不会自动更新。
关键在于：addComponentProperty() 返回的是一个唯一字符串 ID（而非属性名），该 ID 必须被精确用于两处：
- 绑定到 TextNode 的
componentPropertyReferences.characters - 在实例上调用
setProperties()时作为键名
以下是修正后的完整实践代码：
// ✅ 正确创建带绑定的组件
const cardTokenComponent = figma.createComponent();
cardTokenComponent.name = "Card Token";
cardTokenComponent.resize(206, 176);
// 获取属性 ID（必须保存！）
const tokenNamePropId = cardTokenComponent.addComponentProperty("TokenName", "TEXT", "");
const tokenColorPropId = cardTokenComponent.addComponentProperty("TokenColor", "TEXT", "");
const tokenNameNode = figma.createText();
tokenNameNode.characters = ""; // 初始值不影响绑定
// ⚠️ 核心：将属性 ID 绑定到 characters 字段
tokenNameNode.componentPropertyReferences = { characters: tokenNamePropId };
const tokenHexNode = figma.createText();
tokenHexNode.characters = "";
tokenHexNode.componentPropertyReferences = { characters: tokenColorPropId };
cardTokenComponent.appendChild(tokenNameNode);
cardTokenComponent.appendChild(tokenHexNode);
在批量生成实例时，使用返回的属性 ID 进行赋值：
for (const category in groupedStyles) {
const categoryFrame = figma.createFrame();
categoryFrame.layoutMode = "HORIZONTAL";
categoryFrame.itemSpacing = 48;
for (const style of groupedStyles[category]) {
const instance = cardTokenComponent.createInstance();
// ✅ 使用属性 ID 作为 key（不是字符串名！）
instance.setProperties({
[tokenNamePropId]: style.name,
[tokenColorPropId]: toHex(style.color) // 假设已实现 RGB→HEX 转换
});
categoryFrame.appendChild(instance);
}
parentFrame.appendChild(categoryFrame);
}
? 注意事项：
componentPropertyReferences仅支持characters字段（对 TextNode），不支持fontSize、fills等其他属性；- 属性 ID 是一次性生成的字符串（如
"prop_abc123"），不可硬编码或猜测；- 若组件结构复杂（含嵌套帧/组），确保目标 TextNode 是直接子节点或使用
findChildren()精确定位后再绑定；- 所有绑定操作必须在
createComponent()后、createInstance()前完成。
掌握这一机制后，你就能构建真正「数据驱动」的 Figma 组件库——无论是颜色令牌、文字样式卡，还是设计系统变量面板，均可通过属性注入实现一键同步与批量维护。
