开发 Figma 插件或管理设计系统时，用 Figma…

适用于基于 Figma Plugin API 开发插件、自动化设计工作流、构建设计系统或组件库的场景。

适用场景

解决思路

1. 理解 Figma 文档为节点树：DocumentNode 为根，包含 PageNode，PageNode 下可有 FrameNode、TextNode、RectangleNode、ComponentNode、SectionNode 等；通过 figma.currentPage 访问当前页。
2. 识别关键节点类型：FRAME（支持自动布局的容器）、COMPONENT（可复用主组件）、INSTANCE（组件实例）、TEXT（可编辑文本层）、RECTANGLE/ELLIPSE/POLYGON/STAR/LINE（基础形状）、SECTION（组织容器）、GROUP（非布局容器）。
3. 创建组件：调用 figma.createComponent()，设置 name，调用 resize(120, 40)；添加视觉元素时使用 figma.createRectangle()，设置 resize(120, 40)、cornerRadius=8、fills=[{ type: 'SOLID', color: { r: 0.2, g: 0.5, b: 1 } }]，再 button.appendChild(bg)。
4. 创建实例：调用 button.createInstance()，设置实例的 x=200、y=100。
5. 使用组件属性类型：BOOLEAN 切换可见性或状态，TEXT 自定义文本内容，INSTANCE_SWAP 交换嵌套组件，VARIANT 表示组件变体。
6. 实现自动布局：设置 layoutMode 为 'HORIZONTAL'、'VERTICAL' 或 'NONE'；设置 primaryAxisSizingMode 和 counterAxisSizingMode 为 'FIXED' 或 'AUTO'；设置 paddingLeft、paddingRight、paddingTop、paddingBottom；设置 itemSpacing；设置 primaryAxisAlignItems 和 counterAxisAlignItems。
7. 为自动布局子项设置约束：使用 minWidth、maxWidth、minHeight、maxHeight 限制尺寸；设置 layoutAlign 为 'MIN'、'CENTER'、'MAX'、'STRETCH'；设置 layoutGrow 为 0（固定）或 1（填充容器）。
8. 创建自动布局框架示例：figma.createFrame()；frame.layoutMode='VERTICAL'；frame.primaryAxisSizingMode='AUTO'；frame.counterAxisSizingMode='FIXED'；frame.resize(300, 0)；frame.itemSpacing=16；四个方向 padding 为 24；添加子元素后设置 child.layoutAlign='STRETCH'、child.minHeight=100、child.maxHeight=200。
9. 使用约束控制节点随父级缩放：设置 node.constraints = { horizontal: 'MIN'|'CENTER'|'MAX'|'STRETCH'|'SCALE', vertical: ... }；MIN 固定左/上，CENTER 居中，MAX 固定右/下，STRETCH 随父级双向缩放，SCALE 保持比例位置和尺寸。
10. 创建变量集合和颜色变量：figma.variables.createVariableCollection('Design Tokens')；figma.variables.createVariable('color/primary', collection, 'COLOR')；使用 collection.modes[0].modeId 和 primaryColor.setValueForMode 设置默认模式值；使用 collection.addMode('Dark') 添加暗色模式并调用 setValueForMode。
11. 创建变量别名并绑定到节点：使用 figma.variables.createVariableAlias(primaryColor) 创建别名，再 setValueForMode 设置到 accentColor；对矩形 fill 使用 figma.variables.setBoundVariableForPaint(fill, 'color', primaryColor)，然后 rect.fills = [boundFill]。
12. 使用变量类型：COLOR（RGB/RGBA）、FLOAT（数值，如间距和尺寸）、BOOLEAN（真/假）、STRING（文本）。
13. 创建和应用样式：使用 figma.createPaintStyle() 设置 name 和 paints；使用 figma.createTextStyle() 设置 name、fontSize、fontName、lineHeight、letterSpacing；使用 figma.createEffectStyle() 设置 name 和 effects（如 DROP_SHADOW）；通过 rect.fillStyleId = paintStyle.id、text.textStyleId = textStyle.id、frame.effectStyleId = effectStyle.id 应用。
14. 设置原型反应：调用 await node.setReactionsAsync([...])，在 action 中设置 type:'NODE'、destinationId、navigation、transition（如 SMART_ANIMATE、easing、duration）、preserveScrollPosition；在 trigger 中设置类型。
15. 选择原型触发类型：ON_CLICK、ON_HOVER、ON_PRESS、ON_DRAG、MOUSE_ENTER、MOUSE_LEAVE、MOUSE_UP、MOUSE_DOWN、AFTER_TIMEOUT。
16. 选择原型导航类型：NAVIGATE、SWAP、OVERLAY、SCROLL_TO、CHANGE_TO。
17. 配置覆盖层：设置 frame.overlayPositionType（如 'CENTER'、'TOP_LEFT'、'TOP_CENTER' 等）、frame.overlayBackground、frame.overlayBackgroundInteraction。
18. 配置滚动帧：设置 frame.overflowDirection='VERTICAL_SCROLLING' 或 'HORIZONTAL_SCROLLING'；设置 frame.numberOfFixedChildren 指定滚动时保持固定的前 N 个子元素。
19. 搭建插件结构：创建 my-plugin/ 目录，包含 manifest.json、code.ts、ui.html；manifest.json 中设置 name、id、api、main、ui、editorType（如 ['figma', 'figjam']）、documentAccess:'dynamic-page'、networkAccess.allowedDomains。
20. 实现插件生命周期：编写 async function init()；调用 figma.showUI(__html__, { width:400, height:500, title:'My Plugin', themeColors:true })；用 await figma.clientStorage.getAsync('preferences') 读取偏好；用 figma.ui.postMessage 向 UI 发送初始数据；设置 figma.ui.onmessage 处理 UI 消息；用 figma.on('close', ...) 清理；最后调用 init()。
21. 实现插件与 UI 通信：插件侧用 figma.ui.postMessage({ type:'selection-changed', count, nodes }) 发送消息；ui.html 中用 window.onmessage 接收 event.data.pluginMessage 并更新 DOM；UI 侧用 parent.postMessage({ pluginMessage:{ type:'create-shapes', count:5, color:{...} } }, '*') 向插件发送消息。
22. 监听 Figma 事件：使用 figma.on('selectionchange', ...) 监听选择变化；使用 figma.on('documentchange', event => ...) 遍历 event.documentChanges，处理 CREATE、DELETE、PROPERTY_CHANGE；使用 figma.on('currentpagechange', ...) 监听当前页变化。
23. 存储插件私有数据：用 node.setPluginData('status','approved') 和 node.setPluginData('metadata', JSON.stringify(...)) 存储；用 node.getPluginData('status') 读取；用 node.getPluginDataKeys() 列出键。
24. 存储共享插件数据：用 node.setSharedPluginData('com.example.plugin','version','2.0') 存储；用 node.getSharedPluginData('com.example.plugin','version') 读取；用 node.getSharedPluginDataKeys('com.example.plugin') 列出键。
25. 使用客户端存储：用 await figma.clientStorage.setAsync('preferences', {...}) 保存；用 await figma.clientStorage.getAsync('preferences') 读取；用 await figma.clientStorage.deleteAsync('preferences') 删除；用 await figma.clientStorage.keysAsync() 列出所有键。
26. 优化查找节点：设置 figma.skipInvisibleInstanceChildren = true；使用 figma.currentPage.findAllWithCriteria({ types: ['TEXT'] }) 按类型查找；使用多类型数组如 ['RECTANGLE','ELLIPSE','POLYGON']；使用 pluginData.keys 查找带插件数据的节点；使用 sharedPluginData.namespace 和 keys 查找共享数据节点；组合 types 和 pluginData 条件。
27. 使用传统查找方法：使用 figma.currentPage.findAll(node => node.type === 'FRAME')；使用 figma.currentPage.findOne(node => node.name.startsWith('Template'))；使用 await figma.getNodeByIdAsync('123:456') 按 ID 查找；编写 walkTree(node) 递归遍历，检查 'children' in node 后遍历 node.children。
28. 导出节点：使用 await node.exportAsync({ format:'PNG', constraint:{ type:'SCALE', value:2 } }) 导出 PNG；JPG 可设置 contentsOnly；SVG 可设置 svgIdAttribute、svgOutlineText、svgSimplifyStroke；固定尺寸使用 constraint:{ type:'WIDTH', value:200 } 或 { type:'HEIGHT', value:400 }。
29. 加载图片：使用 await figma.createImageAsync('https://example.com/image.png')，用 await image.getSizeAsync() 获取尺寸；创建矩形并设置 fills=[{ type:'IMAGE', imageHash:image.hash, scaleMode:'FILL' }]，scaleMode 可为 'FILL'、'FIT'、'CROP'、'TILE'；用 figma.createImage(bytes) 从字节加载；用 figma.createNodeFromSvg(svgString) 从 SVG 字符串创建节点。
30. 处理文本：创建文本用 figma.createText()；修改前必须 await figma.loadFontAsync(text.fontName)；设置 text.characters；更改字体前先 await figma.loadFontAsync({ family:'Inter', style:'Bold' }) 再设置 text.fontName；设置 fontSize、lineHeight、letterSpacing、textAlignHorizontal、textAlignVertical、textCase、textDecoration。
31. 处理富文本：使用 text.setRangeFontSize(0, 5, 32) 设置前 5 个字符字号；使用 text.setRangeFills(0, 5, [{ type:'SOLID', color:{...} }]) 设置填充；使用 text.getRangeFontName(0,1) 和 text.getRangeFontSize(0,1) 读取范围字体和字号。
32. 调整大小和变换：使用 node.resize(300, 200) 应用约束调整；使用 node.resizeWithoutConstraints(300, 200) 忽略约束；使用 node.rescale(1.5) 按比例缩放；设置 node.x 和 node.y 定位；读取 node.relativeTransform、node.absoluteTransform、node.absoluteBoundingBox。
33. 处理协作功能：插件不能通过 API 直接创建评论，但可导航到带评论的帧、通过 REST API 读取评论元数据、触发通知；用插件数据跟踪自定义版本，如 node.setPluginData('version','2.1.0')、'lastModified'、'modifiedBy'；检查 INSTANCE 的 node.mainComponent 和 component.parent?.type === 'PAGE' 判断是否来自团队库。
34. 性能优化：优先使用 figma.currentPage.findAllWithCriteria 而非 findAll；启用 figma.skipInvisibleInstanceChildren = true；批量创建节点后一次性设置 figma.currentPage.selection = nodes 并调用 figma.viewport.scrollAndZoomIntoView(nodes)；避免在循环中逐个调用 scrollAndZoomIntoView。
35. 字体加载最佳实践：修改文本内容前始终 await figma.loadFontAsync(text.fontName)；更改 fontName 前先 await figma.loadFontAsync({ family:'Roboto', style:'Bold' })；未加载字体就设置 text.characters 会报错。
36. 错误处理：用 try/catch 包裹可能失败的操作；用 await figma.getNodeByIdAsync(id) 查找节点；若 !node 则 figma.notify('Node not found', { error:true })；catch 中 figma.notify(`Error: ${error.message}`, { error:true }) 并 console.error(error)。
37. 内存管理：在 figma.on('close', () => { cache.clear() }) 中清理大型缓存；处理大数组时用 async 循环，每 100 项 await new Promise(resolve => setTimeout(resolve, 0)) 让出 UI。
38. 类型安全：使用类型守卫，如 if (node.type === 'TEXT') 后访问 node.characters；使用 if ('children' in node) 判断子节点；为函数使用具体类型如 function processText(node: TextNode)；避免使用 any。
39. 执行设计系统设置工作流：编写 setupDesignSystem()，创建变量集合 'Design Tokens'，创建颜色变量（color/primary、color/secondary、color/success、color/error），创建 spacing/0 到 spacing/7 的 FLOAT 变量，创建 'Color/Primary' 的 paint style，最后 figma.notify('Design system created!')。
40. 创建组件库工作流：编写 createButtonLibrary()，使用 figma.createComponentSet() 并设置 name='Button'；创建变体 figma.createComponent()，命名如 'Type=Primary, Size=Medium'、'Type=Secondary, Size=Medium'、'Type=Primary, Size=Large'；分别 resize 后 appendChild 到 component set。
41. 执行批量导出工作流：编写 exportAllFrames()，用 findAllWithCriteria({ types:['FRAME'] }) 查找所有帧；循环每个帧分别导出 1x 和 2x PNG（constraint:{ type:'SCALE', value:1/2 }）；收集为 { name, '1x': bytes1x, '2x': bytes2x }；用 figma.ui.postMessage({ type:'exports-ready', exports }) 发送给 UI。
42. 执行样式同步工作流：编写 syncStyles()，用 await figma.getLocalPaintStylesAsync() 和 await figma.getLocalTextStylesAsync() 获取本地样式；用 findAllWithCriteria({ types:['RECTANGLE','TEXT'] }) 查找节点；对 RECTANGLE 查找 name='Brand/Primary' 的样式并设置 node.fillStyleId；对 TEXT 查找 name='Body/Regular' 的样式并设置 node.textStyleId；最后 figma.notify('Styles synced!')。
43. 创建主题感知插件 UI：在 ui.html 的 CSS 中使用 Figma CSS 变量，如 --figma-color-bg、--figma-color-text、--figma-color-bg-brand、--figma-color-text-onbrand、--figma-color-bg-brand-hover、--figma-color-border；按钮和输入框使用这些变量设置背景色、文字色、边框色。
44. 实现加载状态：在 ui.html 中添加 status 元素和 spinner；用 showLoading() 显示、hideLoading() 隐藏；process() 中先 showLoading()，再 parent.postMessage({ pluginMessage:{ type:'process' } }, '*')；在 window.onmessage 中监听 event.data.pluginMessage.type === 'complete' 后调用 hideLoading()。
45. 实现 FigJam 特定功能：判断 if (figma.editorType === 'figjam')；用 figma.createSticky() 创建便签并设置 x、y；await figma.loadFontAsync({ family:'Roboto', style:'Regular' }) 后设置 sticky.text.characters；用 figma.createConnector() 创建连接线并设置 connectorStart.endpointNodeId、position；用 figma.createShape() 创建形状并设置 resize、fills。
46. 实现智能组件替换：编写 swapComponents(oldComponent, newComponent)，用 findAllWithCriteria({ types:['INSTANCE'] }) 查找实例；若 instance.mainComponent?.id === oldComponent.id，则 await instance.swapAsync(newComponent) 并计数；最后 figma.notify(`Swapped ${swapCount} instances`)。
47. 实现自动布局迁移：编写 convertToAutoLayout(frame)，先保存子元素原始位置；设置 frame.layoutMode='VERTICAL'、primaryAxisSizingMode='AUTO'、counterAxisSizingMode='FIXED'、itemSpacing=16、四边 padding=24；遍历 frame.children，若 'layoutAlign' in child 则设置 child.layoutAlign='STRETCH'。
48. 实现响应式调整：编写 makeResponsive(frame)，设置 frame.layoutMode='VERTICAL'、primaryAxisSizingMode='AUTO'、counterAxisSizingMode='FIXED'；遍历 frame.children，若 'resize' in child，则设置 child.layoutAlign='STRETCH'、child.layoutGrow=0、child.minWidth=200、child.maxWidth=800。
49. 测试和调试：使用 console.log 输出选择、节点信息；使用 console.error 输出错误；使用 figma.notify('Success!', { timeout:2000 }) 或 figma.notify('Error occurred', { error:true })；编写 debugNode(node) 打印类型、名称、ID、位置，并在存在 width 时打印尺寸、在存在 children 时打印子节点数量。
50. 参考资源：官方 Figma Plugin API（https://www.figma.com/plugin-docs/）、Context7 库 /figma/plugin-typings（Trust Score 9.8）、插件示例 https://github.com/figma/plugin-samples、社区论坛 https://forum.figma.com/、Widget API https://www.figma.com/widget-docs/、REST API https://www.figma.com/developers/api。

适用边界 · 注意事项

• 不适用于不使用 Figma 或 FigJam 的项目。
• 无法脱离 Figma 运行环境使用，必须先在 Figma 中运行插件或具备 Figma 账号/桌面端或网页端环境。
• 插件 API 不能直接创建评论等部分操作，需改用 REST API 或其他外部方案。