Figma插件开发：如何将组件属性绑定到文本节点？

问题背景 #

我正在开发一款用于文档化颜色样式的Figma插件，在搭建颜色令牌（Token）卡片组件时遇到问题。已掌握为组件添加组件属性的方法，但不清楚如何将这些属性应用到textNode上。

现有代码 #

组件创建代码

// Create tile component
const cardTokenComponent = figma.createComponent();
cardTokenComponent.name = "Card Token";
cardTokenComponent.resize(206,176);

cardTokenComponent.addComponentProperty("TokenName", "TEXT", "");
cardTokenComponent.addComponentProperty("TokenColor", "TEXT", "");

const tokenNameNode = figma.createText();
tokenNameNode.characters = "";
cardTokenComponent.appendChild(tokenNameNode);


const tokenHexNode = figma.createText();
tokenHexNode.characters = "";
cardTokenComponent.appendChild(tokenHexNode);

实例创建循环代码

for (const category in groupedStyles) {
  const categoryFrame = figma.createFrame();
  categoryFrame.layoutMode = "HORIZONTAL";
  categoryFrame.itemSpacing = 48;

  for (let i = 0; i < groupedStyles[category].length; i++) {
    const style = groupedStyles[category][i];

    // Create instance for each item
    const componentInstance = cardTokenComponent.createInstance();

    // Fill component properties
    componentInstance.setProperties({TokenName: style.name, TokenColor: style.color})

  }

  parentFrame.appendChild(categoryFrame);
}

解决方案 #

要实现组件属性与文本节点的绑定，核心是把文本节点的内容属性关联到对应的组件TEXT属性上，具体修改如下：

1. 修改组件创建代码，绑定文本节点与组件属性 #

在创建文本节点后，调用setComponentPropertyReference方法，将文本节点的characters属性和组件的TEXT属性绑定：

// Create tile component
const cardTokenComponent = figma.createComponent();
cardTokenComponent.name = "Card Token";
cardTokenComponent.resize(206,176);

// 添加组件属性
cardTokenComponent.addComponentProperty("TokenName", "TEXT", "");
cardTokenComponent.addComponentProperty("TokenColor", "TEXT", "");

// 创建TokenName文本节点并绑定属性
const tokenNameNode = figma.createText();
tokenNameNode.characters = "";
// 将文本内容绑定到组件的TokenName属性
tokenNameNode.setComponentPropertyReference("characters", "TokenName");
cardTokenComponent.appendChild(tokenNameNode);

// 创建TokenColor文本节点并绑定属性
const tokenHexNode = figma.createText();
tokenHexNode.characters = "";
// 将文本内容绑定到组件的TokenColor属性
tokenHexNode.setComponentPropertyReference("characters", "TokenColor");
cardTokenComponent.appendChild(tokenHexNode);

2. 修改实例循环代码，处理颜色格式并补全实例添加逻辑 #

原代码里style.color返回的是RGBA对象，需要转成十六进制字符串才能正常显示；另外要记得把创建好的实例添加到分类帧中：

// 辅助函数：把RGBA对象转成十六进制颜色码
function rgbaToHex(rgba) {
  const r = Math.round(rgba.r * 255).toString(16).padStart(2, '0');
  const g = Math.round(rgba.g * 255).toString(16).padStart(2, '0');
  const b = Math.round(rgba.b * 255).toString(16).padStart(2, '0');
  return `#${r}${g}${b}`;
}

for (const category in groupedStyles) {
  const categoryFrame = figma.createFrame();
  categoryFrame.layoutMode = "HORIZONTAL";
  categoryFrame.itemSpacing = 48;

  for (let i = 0; i < groupedStyles[category].length; i++) {
    const style = groupedStyles[category][i];

    // 创建组件实例
    const componentInstance = cardTokenComponent.createInstance();

    // 设置组件属性，转换颜色为十六进制
    componentInstance.setProperties({
      TokenName: style.name,
      TokenColor: rgbaToHex(style.color)
    });

    // 把实例添加到分类帧中（原代码遗漏了这一步）
    categoryFrame.appendChild(componentInstance);
  }

  parentFrame.appendChild(categoryFrame);
}

注意点 #

• setComponentPropertyReference是核心：它能让文本节点的内容和组件属性联动，实例属性更新时，文本会自动同步。
• 颜色格式转换：Figma的颜色样式返回的是0-1范围的RGBA值，必须转成十六进制才能作为颜色码显示。
• 实例添加：一定要把创建好的组件实例添加到父容器里，否则画布上看不到效果。

内容的提问来源于stack exchange，提问作者Raccoon