FigJam 插件开发实战：从零构建协作式白板工具

FigJam 嵌入方案怎么选？我折腾了三天后决定用这个

最近项目里要嵌入 FigJam 板块，让团队能直接在内部系统里协作白板。说实话，一开始我以为就一个 iframe 搞定的事，结果踩了一堆坑。FigJam 官方没给太多前端集成文档，社区方案也五花八门。我试了三种主流方式：纯 iframe、官方 embed API、以及自己封装的 postMessage 通信方案。今天就来聊聊这仨谁更靠谱。

最省事的：iframe 直接上

新手第一反应肯定是这样：

<iframe 
  src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2Fxxx%2FMy-Board"
  width="100%"
  height="600"
  allow="clipboard-read; clipboard-write"
></iframe>

确实，几行代码就能跑起来，连登录都不用（如果文件是公开的）。但问题很快来了：无法控制权限、不能动态切换文件、用户操作完全黑盒。我们有个需求是“根据当前项目自动加载对应白板”，iframe 里的 URL 是死的，改一次就得重写整个 src，还得处理跨域缓存问题。而且移动端体验极差——缩放、滚动全乱套，用户经常点不到按钮。

我一开始图快用了这个，结果产品说“能不能加个保存提示”“能不能禁止导出”，我直接傻眼。iframe 里头是 FigJam 的完整 UI，你没法干预任何行为。所以，除非你只是临时展示一个静态白板，否则别用。

官方 Embed API：看起来很美，用起来很痛

FigJam 其实有隐藏的 embed API，文档藏得深，但能实现基础交互。比如监听用户是否退出、是否完成编辑等。用法大概是这样：

const figmaEmbed = window.FigmaEmbed;
const board = figmaEmbed.create({
  container: document.getElementById('figjam-container'),
  url: 'https://www.figma.com/file/xxx/My-Board',
  width: '100%',
  height: 600,
  onMessage: (event) => {
    if (event.type === 'CLOSE') {
      console.log('用户关闭了白板');
    }
  }
});

看起来挺高级对吧？但实际开发中我发现几个大坑：

• 必须提前在 Figma 后台开启“允许嵌入”，而且只对特定域名生效。我们测试环境、预发环境、生产环境三个域名，得挨个配，运维差点骂我。
• onMessage 事件极其有限，只有 CLOSE、ERROR 这种，想监听“用户添加了便签”“移动了元素”？没门。官方说未来会支持，但等了半年没动静。
• 移动端兼容性差，iOS Safari 经常白屏，调试时发现是 CSP 策略冲突，改了 N 次 meta 标签才勉强跑通。

我折腾了两天，最后发现它和 iframe 本质没区别——只是多了一层 JS 包装，核心还是 iframe。如果你不需要深度交互，它比裸 iframe 多点控制权；但一旦要定制行为，立刻卡住。

自己搞 postMessage：麻烦但自由

被前两个方案折磨够了，我决定自己封装一层。思路很简单：用 iframe 嵌入，但通过 postMessage 和父页面通信。FigJam 虽然不开放内部事件，但你可以监听页面的 message 事件，反向推断用户行为（比如 URL hash 变化、窗口尺寸变化）。

核心代码其实就这些：

// 父页面
const figjamFrame = document.getElementById('figjam-iframe');
let currentFileId = 'xxx';

// 发送指令（比如切换文件）
function switchBoard(newFileId) {
  figjamFrame.contentWindow.postMessage({
    type: 'SWITCH_BOARD',
    fileId: newFileId
  }, 'https://www.figma.com');
}

// 监听来自 FigJam 的消息
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://www.figma.com') return;
  
  const { data } = event;
  if (data.type === 'USER_ACTION') {
    // 这里其实是模拟的 —— FigJam 不会主动发 USER_ACTION
    // 但我们可以通过轮询或 hash 变化间接判断
    console.log('用户可能做了操作');
  }
});

// iframe 页面（需要你控制的一个中间页）
// 注意：你不能直接监听 FigJam 内部，但可以做个 proxy page

等等，这里有个关键点：**你不能直接从 FigJam iframe 里收消息**，因为人家没发。所以我搞了个 trick：先跳转到一个你自己控制的中间页，比如 https://jztheme.com/figjam-proxy?file=xxx，这个页面再嵌入真正的 FigJam，并在中间页里加一层 postMessage 转发逻辑。

虽然绕了点，但好处是：你可以完全控制通信协议。比如我在中间页监听了 hashchange，当用户点击“保存”时，FigJam 会把状态写进 URL hash，我就立刻发个消息给父页面：“保存成功”。再比如，用户缩放画布时，iframe 高度会变，我通过 ResizeObserver 捕获后通知父页面自适应高度。

代码量多了不少，但换来的是完全可控的交互能力。我们现在能实现：

• 动态切换白板文件（不用刷新页面）
• 用户离开时自动保存草稿
• 禁用右键菜单、导出按钮（通过 CSS 覆盖）
• 移动端手势优化（配合 touch-action: none）

当然，代价是维护成本高。每次 Figma 更新 UI，我的中间页可能就得调整。但比起被官方方案限制死，我宁愿多写点代码。

我的选型逻辑：看场景，别贪方便

总结一下我的建议：

• 临时展示、只读场景：直接用 iframe，5 分钟搞定，别想太多。
• 需要基础交互（比如关闭回调）且环境可控：试试官方 embed API，但做好兼容性兜底。
• 产品级集成、需要深度控制：老老实实用 postMessage + 中间页方案。虽然前期多花 2 天，后期少掉 10 斤头发。

我现在的项目选了第三种。虽然每次上线都得测三遍（Chrome、Safari、移动端），但至少产品经理提需求时，我能说“这个可以做”，而不是“Figma 不支持”。

另外提醒一点：FigJam 的嵌入性能其实一般，尤其文件大了之后，iframe 初始化要 3~5 秒。我们加了 loading skeleton + 缓存策略，体验才好点。别指望它像本地应用一样快。

结尾：没有银弹，只有权衡

以上是我踩坑后的总结。FigJam 作为协作工具很香，但前端集成确实不够友好。官方如果能开放更多 postMessage 事件，或者提供 React 组件，那就好了。可惜现在只能自己造轮子。

如果你有更好的方案，比如用 Web Component 封装，或者发现我没提到的 API，欢迎评论区交流。这个技巧的拓展用法还有很多（比如结合 WebSocket 实现实时同步状态），后续我会继续分享这类实战博客。