> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Figma 插件

> 从一个示例构建付费 Figma 插件，在解锁插件功能前验证并激活 Dodo Payments 许可证密钥。

Dodo Payments Figma 示例是一个 boilerplate 插件，仅为拥有有效 Dodo Payments [许可证密钥](/features/license-keys)的用户解锁其功能。将其作为高级 Figma 插件的起点：它包含许可证密钥输入、通过 Dodo Payments API 进行验证和激活的功能，以及一个用于高级功能的组件。

## 特性

* **License Key Validation**：根据 Dodo Payments API 验证许可证密钥。
* **License Key Activation**：为具有激活次数限制的许可证密钥设置实例名称并激活密钥。
* **Environment Support**：可配置为测试模式和正式模式。
* **TypeScript Support**：提供完整的类型定义和错误处理。

## 开始使用

开始之前，你需要 Figma 桌面应用和一个可签发许可证密钥的 Dodo Payments 产品。

**1. Create Base Plugin**

使用 [Figma 插件快速入门指南](https://www.figma.com/plugin-docs/plugin-quickstart-guide/)创建你自己的 Figma 插件项目。Figma 会生成一个脚手架，其中包含一个 `manifest.json` 文件。

> [!TIP]
>
> 你只需执行此步骤即可为插件获取唯一的名称和 ID。在下一步将名称和 ID 复制到示例的 `manifest.json` 中，并将其提交到 Git 仓库后，就可以删除生成的文件。

**2. Clone the Example Implementation**

克隆 [dodopayments-figma 仓库](https://github.com/dodopayments/dodopayments-figma)：

```bash theme={null}
git clone https://github.com/dodopayments/dodopayments-figma.git
cd dodopayments-figma
```

在克隆的 `manifest.json` 中，将 `name` 和 `id` 替换为生成的插件的 `manifest.json` 中的值。此示例就是你的集成起点。

> [!TIP]
>
> 将远程 origin URL 更改为你自己的版本控制仓库，例如使用 `git remote set-url origin <your-repository-url>`。

**3. Install Dependencies**

在项目根目录中运行：

```bash theme={null}
npm install
```

**4. Configure Environment**

在 `src/ui/api.ts` 中设置 `API_MODE`：

```typescript theme={null}
const API_MODE: "test_mode" | "live_mode" = "test_mode"; // for development
// const API_MODE: "test_mode" | "live_mode" = "live_mode"; // for production
```

`API_MODE` 选择 API 主机：对于 `test_mode`，使用 `https://test.dodopayments.com`；对于 `live_mode`，使用 `https://live.dodopayments.com`。

> [!WARNING]
>
> 开发期间使用 `test_mode`，以避免处理真实付款。

**5. Customize Components**

在 `src/ui/components/` 中自定义插件组件，以满足你的需求：

* 更新 `Authenticated.tsx`，为拥有有效许可证密钥的用户提供功能。
* 自定义 `LicenseKeyInput.tsx`，以匹配你的设计。

> [!NOTE]
>
> `Authenticated.tsx` 用于添加插件的高级功能。只有在许可证密钥验证或激活后，插件才会显示这些功能。

## 配置

**1. Configure Network Access**

该示例会通过位于 `https://dodo-payments-proxy.aagarwal9782.workers.dev` 的 CORS 代理发送每个许可证密钥请求，其 `manifest.json` 仅允许访问该代理。该代理不可用，因此请直接调用 Dodo Payments API。该 API 接受来自任何来源的跨源请求，包括插件 UI 的 `null` 来源。

在你的 `manifest.json` 中，将代理域名替换为 Dodo Payments API 主机：

```json theme={null}
{
  "networkAccess": {
    "allowedDomains": ["https://test.dodopayments.com", "https://live.dodopayments.com"]
  }
}
```

在 `src/ui/api.ts` 中，将 `fetch(proxyReq)` 替换为 `fetch(req)`，位置在 `validateLicenseKey` 和 `activateLicenseKey` 中，以便每个请求都直接发送到 API。

这样，插件就可以通过 Dodo Payments API 验证和激活许可证密钥。

**2. Configure API Mode**

在 `src/ui/api.ts` 中配置 API 模式：

```typescript theme={null}
const API_MODE: "test_mode" | "live_mode" = "test_mode"; // or "live_mode"
```

> [!TIP]
>
> 只有在准备投入生产并已在测试模式下完成充分测试后，才切换到 `live_mode`。

## 开发

**1. Import Plugin**

将插件导入 Figma 桌面应用：

1. 打开一个设计文件。
2. 打开 Figma 菜单并选择 **Plugins**。
3. 在 **Development** 下，选择 **Import new plugin from manifest...**，然后在项目根目录中选择 `manifest.json` 文件。

清单会从 `dist/` 中的构建文件加载插件，因此请在运行插件前启动开发服务器或运行 `npm run build`。

> [!NOTE]
>
> 你需要使用 Figma 桌面应用在本地开发和测试插件，因为 Figma 会从本地文件读取插件代码。

**2. Start Development Server**

```bash theme={null}
npm run dev
```

这会启动带文件监视功能的开发服务器，以便自动重新构建。同时，它还会在你修改代码时检查类型。

> [!TIP]
>
> 修改源代码后，插件会自动重新构建。

## 构建命令

项目包含以下 npm 脚本：

| 命令 | 说明 |
| - | - |
| `npm run build` | 为生产环境构建插件 |
| `npm run dev` | 启动带文件监视功能的开发服务器 |
| `npm run lint` | 检查代码风格和错误 |
| `npm run format` | 使用 Prettier 格式化代码 |

## 许可证密钥集成

示例实现会在解锁插件前检查许可证密钥。你可以自定义每个步骤：

1. **用户输入**：用户在插件 UI 中输入许可证密钥。
2. **验证**：默认情况下，插件使用 [Validate License](/api-reference/licenses/validate-license)（`POST /licenses/validate`）验证密钥。
3. **激活**：如果你的许可证密钥具有激活次数限制，请在 `src/ui/components/Unauthenticated.tsx` 中将 `needsActivation` 设置为 `true`。然后，插件会使用 [Activate License](/api-reference/licenses/activate-license)（`POST /licenses/activate`）激活密钥，而不是验证密钥，并将实例命名为 `Figma Plugin`。
4. **访问控制**：对于有效密钥，插件会使用 `figma.clientStorage` 保存密钥，并显示 `Authenticated.tsx`。下次打开插件时，它会再次验证已保存的密钥。

## 发布

插件准备就绪后：

1. 为生产环境构建：`npm run build`
2. 在测试模式和正式模式下进行充分测试。
3. 遵循 [Figma 的插件发布指南](https://developers.figma.com/docs/plugins/publishing/)。
4. 通过 Figma Community 提交插件以供审核。

## 仓库

完整的示例实现位于 [github.com/dodopayments/dodopayments-figma](https://github.com/dodopayments/dodopayments-figma)。

以此为起点，使用 Dodo Payments 许可证密钥构建高级 Figma 插件。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.