UI 视觉设计 / 系统课时

用 Code Connect 映射属性

用 Code Connect 映射属性

目标是让开发者选中 Figma 的 Button 实例时,Dev Mode 显示项目真正使用的 React Button 写法,并让尺寸、外观、禁用和文字随设计属性变化。下面用一个四属性组件完成权限检查、映射、预览和发布,不改动组件运行时代码。

学习目标

  • 核对 Code Connect 所需权限、Figma 属性名与 React Props。
  • 使用当前推荐的 .figma.ts 模板将变体值转换为组件参数。
  • 在本地验证不同属性组合,再发布到 Dev Mode 检查。

对齐 Figma 属性与 React 接口

先在组件库选中 Button 主组件集,确认右侧属性面板中的名称和选项。示例假定代码仓库已存在 src/components/Button.tsx,其接口使用 size: 'sm' | 'md' | 'lg'、variant: 'primary' | 'secondary'、disabled?: boolean 与 children。实际接入时必须按真实组件签名调整,不能因为 Figma 叫 Type 就给 React 传 type。

Figma 属性及类型 设计端取值 React 对应值
Size,变体 Small / Medium / Large size: sm / md / lg
Type,变体 Primary / Secondary variant: primary / secondary
Disabled,布尔 true / false disabled: true / false
Label,文本 保存、取消等 children: 实例文字

权限检查:需要包含主组件的 Figma 设计库、可访问该文件的账号,以及支持 Code Connect 的 Dev 或 Full 席位。按当前官方 CLI 指南,Professional、Organization、Enterprise 方案可用,但具体额度受方案限制;个人访问令牌需授予 Code Connect: Write 和 File content: Read。没有这些条件时可先维护映射表,不能假设发布命令会成功。

安装并配置 Code Connect

在已有 React 项目根目录执行以下命令,先确保 node --version 为 v18 或更新版本。

bash
npm install --save-dev @figma/code-connect@latest
npx figma connect --version

预期结果:安装成功,第二条命令输出当前 CLI 的版本号(因安装时间不同而变化),且不会提示找不到命令。

创建项目根目录的 figma.config.json;这里使用维护中的模板格式,而不是旧版 React 专用 .figma.tsx 解析器。

json
{
  "codeConnect": {
    "include": ["**/*.figma.ts"],
    "label": "React",
    "language": "jsx"
  }
}

配置生效后,CLI 会查找仓库中的 .figma.ts 模板;label 是 Dev Mode 代码示例标签,language 指定代码高亮语言。已有配置文件时合并 codeConnect 字段,不要覆盖其他项目设置。TypeScript 编辑器若缺少模板类型,可在现有 tsconfig.json 的 compilerOptions.types 中补充 @figma/code-connect/figma-types。

映射变体、布尔值和文本

在 Figma 对 Button 主组件集右键选择 Copy link to selection。在 src/components/ 新建 Button.figma.ts,将首行的 <FIGMA_COMPONENT_URL> 换成刚复制的真实节点 URL。以下为依赖项目内 Button.tsx 的模板文件示例,不是在浏览器运行的 React 组件。

ts
// url=<FIGMA_COMPONENT_URL>
import figma from 'figma'

const instance = figma.selectedInstance
// 把设计端可读选项转换为 ButtonProps 接受的代码值
// 属性名必须与 Figma 面板一致;枚举键区分大小写
const size = instance.getEnum('Size', {
  Small: 'sm',
  Medium: 'md',
  Large: 'lg',
})
const variant = instance.getEnum('Type', {
  Primary: 'primary',
  Secondary: 'secondary',
})
const disabled = instance.getBoolean('Disabled')
const label = instance.getString('Label')

export default {
  example: figma.code`
    <Button size={${size}} variant={${variant}} disabled={${disabled}}>
      ${label}
    </Button>
  `,
  imports: ['import { Button } from "./Button"'],
  id: 'button',
}

getEnum 把 Figma 变体转换为真实的 React 联合类型取值;getBoolean 保留禁用布尔值;getString 将文本属性放进 children。imports 要改成项目消费者真正使用的导入语句。若设计稿只有可覆盖文本图层、没有 Label 文本属性,应先检查 模板 API 中适合该图层的访问方式,而不是臆造一个属性。

Figma Button 属性经 Code Connect 模板映射到 React 参数的关系

预览映射后再发布

先用本地预览检查属性名称和一个确定的组合;这些命令需从仓库根目录执行,且模板首行已经换成真实 URL。

bash
npx figma connect preview src/components/Button.figma.ts --inspect
npx figma connect preview src/components/Button.figma.ts --props Size=Medium Type=Primary Disabled=false

预期结果:--inspect 能列出模板对应的属性及可选变体;第二条命令展示 React Button 代码,其中 size 对应 md、variant 对应 primary、disabled 对应 false,具体 JSX 格式以 CLI 实际预览为准。再把 Size 改为 Large、Type 改为 Secondary,检查是否切换成 lg 与 secondary。

确认无误后,在当前终端或 CI 密钥环境中设置 FIGMA_ACCESS_TOKEN,不要把令牌写入仓库或提交日志。先试运行,再正式发布:

bash
npx figma connect publish --file src/components/Button.figma.ts --dry-run
npx figma connect publish --file src/components/Button.figma.ts

预期结果:试运行通过校验但不真正发布;正式发布返回组件及 Figma 节点信息。打开对应组件的实例,切到 Dev Mode → Inspect,检查显示的 React 代码与当前选中的尺寸、样式、禁用状态和文字一致。Code Connect 只生成展示用代码,不会在 Figma 中运行 React 组件。

处理最常见的映射失败

现象 核查与修正
CLI 报属性不存在或预览值不对 核对 Size、Type、Disabled、Label 的拼写、大小写和实际属性类型;getEnum 的键必须与变体选项完全一致。
发布通过但 Dev Mode 没显示映射 检查模板首行是否链接 主组件/组件集 而非随意一个实例;确认查看的是该组件的实例和正确代码标签。
发布提示权限不足 核查令牌作用域、文件读取权限、工作区方案和席位;不通过校验时不要加 --force 碰运气。
显示代码与项目不一致 检查 imports、React Prop 的真实名称及枚举映射;更新模板后重新预览、发布。

若团队还在使用 figma.connect() 的旧版 React 解析器,先核对 官方迁移和模板指南;新集成优先采用 .figma.ts 模板。验收时应覆盖 3 × 2 × 2 = 12 种尺寸、外观与禁用组合,并抽查各类边界状态,确保显示的 JSX 参数都符合真实 Button API。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 Code Connect 映射属性

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

登录哪都通