【技术干货】如何在Vaadin应用程序中使用自定义Figma组件

Vaadin 是一个面向企业级应用的现代 Web 开发框架，专注于 Java 全栈开发、组件化 UI 构建，并提供丰富的开箱即用 Web Components。Vaadin 的优势包括：

Java 到前端的统一开发体验
企业级安全性与长生命周期支持
高质量 UI 组件库与设计系统
与 Figma 无缝衔接的 Copilot AI 辅助开发能力

在最新版本中，Vaadin Copilot 新增了 Figma Importer API，实现"从设计到代码"的自动化，让开发者可以直接将 Figma 组件复制并粘贴到 Vaadin 项目中，生成 Java 或 React 代码。

本文基于 Vaadin 官方示例并由慧都整理改写，帮助国内开发者快速上手。

获取Vaadin产品试用>>>

1. 功能概览：从 Figma 复制、到 Vaadin 自动生成代码

通过Vaadin Copilot 的 Figma Importer API，你可以做到：

从 Figma 复制组件或实例（如卡片、按钮）
在 Vaadin 项目中直接粘贴
自动生成对应的 Java（Flow） 或 React（Hilla） 组件代码

Figma Importer API 用于将 Simple Design System Card 映射到 Java SDSCard 组件。

官方项目基于：

Demo 项目
Figma 组件与实例示例

2. 使用前准备

启用 Vite 热重载（推荐）

在 Spring Bootapplication.properties中加入：

复制代码

vaadin.frontend.hotdeploy=true

3. Figma 组件体系与 Importer API 原理

许多公司（包括 Vaadin）都有自己的 Figma 设计系统，也可使用公开设计系统（如 Simple Design System）。
Vaadin Copilot 24.9 引入的 Figma Importer API 用于将这些组件映射为真实代码。

Figma → Vaadin 的映射关系：

Figma 的 Component ≈ Java/TS 中的 class
Figma 的 Instance ≈ Java/TS 中的 object
属性可被实例覆盖
通过"标记属性（marker property）"来区分组件类型

例如，Figma 中 Card 组件的属性：

复制代码

type = SDSCard

Importer 仅匹配带有此属性的组件。

4. 目标 Java / React 组件示例

以 SDSCard 与 SDSButton 为例：

若手动创建 Java 组件：

复制代码

var sdscard = new SDSCard();
sdscard.setTitle("Great news!");
sdscard.setBody(sayHello);

var sdsbutton = new SDSButton();
sdsbutton.setLabel("Sure!");
sdscard.add(sdsbutton);

若使用 React：

复制代码

<SDSCard title="Great news!">
   <span slot="body">Did you know that Vaadin Copilot can import Figma components?</span>
   <SDSButton label="Sure!" />
</SDSCard>

示例工程已包含这些组件。

5. 编写 Importer：从 Figma 转换为 Java/React

Importer 是一个 TypeScript 函数：

输入 FigmaNode
输出 ComponentDefinition
根据目标语言（Java 或 React）生成代码结构

5.1 SDSCard Java Importer 示例

文件：frontend/sdscard-java-importer.ts

复制代码

function sdsCardJavaImporter(node, metadata) {
  if (node.properties.type === 'SDSCard' && metadata.target === 'java') {
    return {
      tag: 'SDSCard',
      props: {
        title: node.properties.title,
        body: {
          tag: 'Span',
          props: { text: node.properties.body },
          javaClass: 'com.vaadin.flow.component.html.Span',
        },
      },
      children: createChildrenDefinitions(node, metadata, n => {
        return n.properties.type === 'SDSButton';
      }),
      javaClass: 'test.vaadin.copilot.flow.testviews.ui.customcomponents.components.SDSCard',
    };
  }
}
registerImporter(sdsCardJavaImporter);

核心点说明：

匹配type: SDSCard
生成 Java 组件结构
子组件过滤以查找 Button

5.2 SDSButton Java Importer

文件：frontend/sdsbutton-java-importer.ts

复制代码

function sdsButtonJavaImporter(node, metadata) {
  if (node.properties.type === 'SDSButton' && metadata.target === 'java') {
    return {
      tag: 'SDSButton',
      props: { label: node.properties.label },
      children: [],
      javaClass: 'test.vaadin.copilot.flow.testviews.ui.customcomponents.components.SDSButton',
    };
  }
}
registerImporter(sdsButtonJavaImporter);

5.3 SDSCard React Importer

文件：frontend/sdscard-react-importer.ts

复制代码

function sdsCardReactImporter(node, metadata) {
  if (node.properties.type === 'SDSCard' && metadata.target === 'react') {
    return {
      tag: 'SDSCard',
      props: { title: node.properties.title },
      children: [
        {
          tag: 'span',
          props: { slot: 'body' },
          children: [node.properties.body.toString()],
        },
        ...createChildrenDefinitions(node, metadata, n => n.properties.type === 'SDSButton'),
      ],
      reactImports: { SDSCard: 'Frontend/components/SDSCard' },
    };
  }
}
registerImporter(sdsCardReactImporter);

5.4 SDSButton React Importer

文件：frontend/sdsbutton-react-importer.ts

复制代码

function sdsButtonReactImporter(node, metadata) {
  if (node.properties.type === 'SDSButton' && metadata.target === 'react') {
    return {
      tag: 'SDSButton',
      props: { label: node.properties.label },
      children: [],
      reactImports: { SDSButton: 'Frontend/components/SDSButton' },
    };
  }
}
registerImporter(sdsButtonReactImporter);

6. 在项目中启用 Importer

Flow（Java）项目中：

复制代码

@SpringBootApplication
@JsModule(value = "./sdscard-java-importer.ts", developmentOnly = true)
@JsModule(value = "./sdsbutton-java-importer.ts", developmentOnly = true)
@JsModule(value = "./sdscard-react-importer.ts", developmentOnly = true)
@JsModule(value = "./sdsbutton-react-importer.ts", developmentOnly = true)
public class Application implements AppShellConfigurator {}

React 项目：index.tsx

复制代码

if (import.meta.env.DEV) {
  import('./sdscard-java-importer');
  import('./sdsbutton-java-importer');
  import('./sdscard-react-importer');
  import('./sdsbutton-react-importer');
}

7. 自动生成的代码示例

Java 生成代码：

复制代码

SDSCard sdscard = new SDSCard();
sdscard.setTitle("Great news!");
Span didYouKnowThatVaadin = new Span("Did you know that Vaadin Copilot can import Figma components?");
sdscard.setBody(didYouKnowThatVaadin);

SDSButton sure = new SDSButton();
sure.setLabel("Sure!");
sdscard.add(sure);

add(sdscard);

React 生成代码：

复制代码

<SDSCard title="Great news!">
   <span slot="body">
      Did you know that Vaadin Copilot can import Figma components?
   </span>
   <SDSButton label="Sure!" />
</SDSCard>

Vaadin 25 版本更新提醒

在 Vaadin 25 中：

_registerImporter→registerImporter
_createChildrenDefinitions→createChildrenDefinitions

请注意 API 名称变更。