github-actions[bot]
ad3291f4b4
Created by Github action <!-- This is an auto-generated description by cubic. --> <a href="https://cubic.dev/pr/twentyhq/twenty/pull/23338?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. --> Co-authored-by: github-actions <github-actions@twenty.com>
124 lines
7.8 KiB
Plaintext
124 lines
7.8 KiB
Plaintext
---
|
||
title: 应用程序配置
|
||
description: 使用 defineApplication 声明应用的身份、默认角色、变量和应用市场元数据。
|
||
icon: rocket
|
||
---
|
||
|
||
每个应用必须且只能有一个 `defineApplication` 调用。 它声明：
|
||
|
||
* **应用的身份** — 通用标识符、显示名称、描述。
|
||
* **权限** — 其逻辑函数和前端组件在何种角色下运行。
|
||
* **变量**（可选）— 以环境变量形式暴露给代码的键值对。
|
||
* **安装前/安装后/卸载函数**（可选）— 参见 [逻辑函数](/l/zh/developers/extend/apps/logic/logic-functions)。
|
||
|
||
```ts src/application-config.ts
|
||
import { defineApplication } from 'twenty-sdk/define';
|
||
|
||
export default defineApplication({
|
||
universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
|
||
displayName: 'My Twenty App',
|
||
description: 'My first Twenty app',
|
||
applicationVariables: {
|
||
DEFAULT_RECIPIENT_NAME: {
|
||
universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
|
||
description: 'Default recipient name for postcards',
|
||
value: 'Jane Doe',
|
||
isSecret: false,
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
备注：
|
||
|
||
* `universalIdentifier` 字段是你拥有的确定性 ID。 只需生成一次，并在多次同步过程中保持稳定不变。
|
||
* `applicationVariables` 会变成你的函数和前端组件可用的环境变量。 在逻辑函数（服务端）中，可以通过 `process.env.VARIABLE_NAME` 使用它们。 在前端组件中，使用 `twenty-sdk/front-component` 中的 `getApplicationVariable('VARIABLE_NAME')`。 标记为 `isSecret: true` 的变量只会注入到逻辑函数中。 前端组件只会接收非机密变量。
|
||
* 默认角色会根据使用 [`defineApplicationRole()`](/l/zh/developers/extend/apps/config/roles) 标记的角色文件自动检测——你不需要在 `defineApplication()` 中引用它。
|
||
* 在构建清单时会自动检测安装前、安装后和卸载函数——无需在 `defineApplication()` 中引用它们。
|
||
* 显式传递 `defaultRoleUniversalIdentifier` 仍然受支持以保持向后兼容性，但已弃用，推荐改用 `defineApplicationRole()`。
|
||
* `serverVariables` 是实例级的配置和机密信息（例如 API 密钥）。 与 `applicationVariables` 不同，它们不会在 manifest 中声明具体值——工作区运维人员会在应用设置中填写这些值，并且它们只有在被设置后才会被注入到逻辑函数中。
|
||
* 要在应用的 **Settings** 选项卡中渲染自定义配置界面（替换默认的变量配置部分），请在其独立文件中使用 [`defineSettingsFrontComponent()`](/l/zh/developers/extend/apps/layout/front-components#custom-settings-component) 声明一个前端组件。 每个应用只允许有一个。 系统管理的部分（自动升级、App URL、连接）将始终保持可见。
|
||
|
||
## 变量类型
|
||
|
||
`applicationVariables` 和 `serverVariables` 都接受一个可选的 `type`（且对于 `SELECT` / `MULTI_SELECT`，还可以接受一个 `options` 列表）。 支持的类型：`TEXT`（默认）、`BOOLEAN`、`NUMBER`、`NUMERIC`、`DATE`、`DATE_TIME`、`SELECT`、`MULTI_SELECT`、`ARRAY`、`RAW_JSON`、`RICH_TEXT`。
|
||
|
||
```ts src/application-config.ts
|
||
import { defineApplication, FieldType } from 'twenty-sdk/define';
|
||
|
||
export default defineApplication({
|
||
// ...identity, role...
|
||
applicationVariables: {
|
||
MAX_POSTCARDS: {
|
||
universalIdentifier: '5f4497e4-9030-4085-85eb-2c48b8d53713',
|
||
description: 'Maximum postcards per batch',
|
||
type: FieldType.NUMBER,
|
||
value: 10,
|
||
},
|
||
DEFAULT_REGION: {
|
||
universalIdentifier: '76c5c321-b6b6-46eb-b4fc-f9f04bb04227',
|
||
description: 'Default shipping region',
|
||
type: FieldType.SELECT,
|
||
options: [
|
||
{ label: 'Europe', value: 'eu' },
|
||
{ label: 'United States', value: 'us' },
|
||
],
|
||
value: 'eu',
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
`type` 只影响**展示和校验**——它会在工作区设置界面中选择匹配的输入控件（开关、数字字段、下拉框、日期选择器、JSON 编辑器等）。 并让构建过程校验你的配置（例如，`SELECT` / `MULTI_SELECT` 必须声明非空的 `options`）。 它**不会**改变该值到达你代码的方式。
|
||
|
||
值**始终以字符串注入**——这是环境变量固有的特性（`process.env.*` 只能是字符串）。 当你的逻辑函数运行时，执行器会在构建 `process.env` 时按声明的 `type` 序列化每个值，因此无论该值是如何设置的（清单默认值、设置界面或先前的版本），字符串格式都是一致的：
|
||
|
||
| 类型 | `process.env` 字符串 |
|
||
| ---------------------------------- | --------------------------------- |
|
||
| `TEXT`、`SELECT`、`DATE`、`DATE_TIME` | 原始值（`"eu"`、`"2026-01-01"`） |
|
||
| `BOOLEAN` | `"true"` / `"false"` |
|
||
| `NUMBER`、`NUMERIC` | 十进制字符串（`"10"`、`"2.5"`） |
|
||
| `MULTI_SELECT`、`ARRAY` | JSON 数组（`'["email","postcard"]'`） |
|
||
| `RAW_JSON`、`RICH_TEXT` | JSON 对象（`'{"retries":3}'`） |
|
||
|
||
将该字符串再解析回你所期望的类型：
|
||
|
||
```ts
|
||
const maxCards = Number(process.env.MAX_POSTCARDS); // "10" -> 10
|
||
const enabled = process.env.ENABLE_TRACKING === 'true'; // "true" -> true
|
||
const channels = JSON.parse(process.env.ENABLED_CHANNELS ?? '[]'); // '["email"]' -> ["email"]
|
||
const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3}' -> { retries: 3 }
|
||
```
|
||
|
||
同样适用于通过 `getApplicationVariable('VARIABLE_NAME')` 读取值的前端组件——返回值是字符串；按需进行解析。
|
||
|
||
## 默认函数角色
|
||
|
||
使用 [`defineApplicationRole()`](/l/zh/developers/extend/apps/config/roles) 声明的角色控制应用的逻辑函数和前端组件可以访问的内容：
|
||
|
||
* 作为 `TWENTY_APP_ACCESS_TOKEN` 注入的运行时令牌来源于该角色。
|
||
* 类型化 API 客户端将受限于授予该角色的权限。
|
||
* 遵循最小权限原则：只声明你的函数所需的权限。
|
||
|
||
当你使用脚手架创建新应用时，CLI 会在 `src/roles/default-role.ts` 中创建一个入门角色文件。 完整参考请参见 [角色与权限](/l/zh/developers/extend/apps/config/roles)。
|
||
|
||
## 应用市场元数据
|
||
|
||
如果你计划[发布你的应用](/l/zh/developers/extend/apps/operations/publishing)，这些可选字段将控制你的应用在应用市场中的展示：
|
||
|
||
| 字段 | 描述 |
|
||
| ------------------ | -------------------------------------------------------------- |
|
||
| `作者` | 作者或公司名称 |
|
||
| `类别` | 用于应用市场筛选的应用类别 |
|
||
| `logo` | 捆绑在`public/`中的应用徽标的路径(例如`public/logo.png`) |
|
||
| `galleryImages` | 在`public/`中捆绑的相册图像路径数组(例如`public/screenshot-1.png`) |
|
||
| `aboutDescription` | 用于“关于”选项卡的更长的 Markdown 描述。 如果省略，市场将使用该软件包在 npm 上的 `README.md`。 |
|
||
| `websiteUrl` | 你的网站链接 |
|
||
| `termsUrl` | 服务条款链接 |
|
||
| `emailSupport` | 支持电子邮件地址 |
|
||
| `issueReportUrl` | 问题跟踪器链接 |
|
||
|
||
<Note>
|
||
`logoUrl`和`screshots`被废弃的 `logo` 和 `GalleryImages` 的别名。 这些字段不支持外部绝对链接 (`http://` 或 `https://`) 。它们会在构建时被丢弃，并附有警告。 将图像捆绑在你的应用的 "public/" 文件夹中。
|
||
</Note>
|