---
title: 字段映射
description: 数据导入期间字段映射的工作原理。
---
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
## 字段映射的工作原理
当您上传文件时，Twenty 会分析您的列，并尝试将其与现有字段匹配。
### 自动映射
Twenty 将根据以下内容尝试匹配列：
* 列标题名称（精确或相似匹配）
* 数据类型检测（日期、数字、电子邮件）
* 常见字段模式
**快速提示：** 从您要导入的对象中导出几行数据。 导出的文件将包含 Twenty 期望的精确列名，从而在导入时实现无缝的自动映射。
### 手动映射选项
对于每一列，您可以：
* **映射到字段**：从下拉列表中选择匹配的 Twenty 字段
* **不进行映射**：完全跳过该列（不会导入数据）
**字段必须在导入前已存在。** 导入会创建记录，而不是创建字段。 请在导入前于 **设置 → 数据模型** 中创建自定义字段。
## 字段类型兼容性
数据模型中可用的所有字段类型都支持导入。
您也可以导入 `id` 值，以便为新记录指定特定 ID，或更新现有记录。
## 数据格式要求
**某些字段有特殊语法。** 我们建议在准备导入之前下载示例文件，以查看每种字段类型的预期语法。
### 地址字段
地址是一个嵌套字段，包含多个列。 其中一些可以留空。
* **Address / Address 1**：街道地址第 1 行
* **Address / Address 2**：街道地址第 2 行
* **Address / City**：城市名称
* **Address / State**：州或省
* **Address / Country**：国家名称
* **Address / Post Code**：邮政/ZIP 编码
### 数组字段
使用以下格式：
```
["value1","value2"]
```
### 布尔字段
使用 `TRUE` 或 `FALSE`（大写），不要使用 `true` 或 `false`
### 货币字段
货币是一个**嵌套字段**，需要两列，且**两列都必须填写**：
* **Amount / Amount**：数值（例如，`1234.56`）
* **Amount / Currency**：货币代码（例如，`USD`、`EUR`）
### 日期字段
支持的格式：
* `YYYY-MM-DD`（推荐）
* `MM/DD/YYYY`
* `DD/MM/YYYY`
* ISO 8601 格式
### 域名字段
* 建议使用 `https://domain.com` 格式以避免创建重复，因为通过邮箱和日历同步创建的公司会使用该格式
* 可以填写 `Domain Label` 和 `Domain URL`：最佳做法是在标签中填写 `domain.com`，在 url 中填写 `https://domain.com`
* 在 Companies 对象内，域名必须唯一
* **待导入文件中的域名必须唯一**
### 电子邮件字段
* 必须为有效的电子邮件格式
* 在 People 对象内，电子邮件必须唯一
* **待导入文件中的电子邮件必须唯一**
* 对于附加邮箱：主邮箱请使用 **Emails / Primary Email**，附加邮箱请使用 **Emails / Additional Emails**，并采用以下格式：
```
["jane@twenty.com","jane.doe@twenty.com"]
```
### ID 字段
在导入过程中指定 `id` 是可选的。 如未提供，Twenty 将自动生成 ID。
映射 `id` 列的用例：
* **设置特定 ID**：为新创建的记录选择 UUID
* **更新现有记录**：与现有记录进行匹配以更新它们，而不是创建重复项。 在这种情况下，建议不要映射其他唯一字段：仅映射一个唯一字段可确保导入更顺畅。
如果您提供 `id`，其必须为 UUID 格式（例如，`c776ee49-f608-4a77-8cc8-6fe96ae1e43f`）。
### JSON 字段
使用有效的 JSON 格式：
```
{"key":"value","key2":"value2"}
```
### 链接字段
与域名字段类似：
* 同时填写标签和 URL 两列：**Links / Link URL** 和 **Links / Link Label**
* 使用完整的 URL 格式：`https://example.com`
* 对于次要链接，请使用 **Links / Secondary Links** 列，并采用以下格式：
```
[{"url":"https://twenty.com","label":"Twenty"}]
```
### 多选字段
使用**API 名称**（而非显示标签），格式如下：
```
["VALUE1","VALUE2"]
```
请参见[此处](#finding-api-names-for-select-fields)了解如何查找 API 名称。
新的选择项不会通过导入自动创建。 请在导入前于 **设置 → 数据模型** 中添加它们。
**导入会覆盖，不会追加。**
如果一条记录已选择了 `VALUE2` 和 `VALUE3`，而您导入了 `["VALUE1"]`，则导入后该记录将只保留 `VALUE1`。 之前的选择会被替换，而不是合并。
### 数字字段
* 仅限数字
* 小数使用点号：`1234.56`
* 不使用千位分隔符
### 电话字段
电话是一个包含多列的嵌套字段，且**必须填写**
* **Phones / Primary Phone Number**：电话号码（例如，`4159095555`）
* **Phones / Primary Phone Country Code**：国家代码（例如，`US`）
* **Phones / Primary Phone Calling Code**：拨号代码（例如，`+1`）
### 评分字段
使用 API 名称格式：`RATING_1`、`RATING_2`、`RATING_3`、`RATING_4`、`RATING_5`
### 关系字段
请参阅我们的专门文章：[在对象之间导入关联](/l/zh/user-guide/data-migration/capabilities/import-relations)
### 选择字段
使用选项的**API 名称**（而不是显示标签）：
```
VALUE1
```
请参见[此处](#finding-api-names-for-select-fields)了解如何查找 API 名称。
新的选择项不会通过导入自动创建。 请在导入前于 **设置 → 数据模型** 中添加它们。
### 文本字段
* 无需特殊格式
* 首尾空格会被移除
## 查找 API 名称
对于具有预定义选项的 Select、Multi-Select 和 Array 字段，必须使用 **API 名称**，而不是显示标签。
### 如何查找 API 名称
1. 进入 **设置 → 数据模型**
2. 选择对象和字段
3. 启用 **高级模式**（在设置页面右下角切换）
4. 查看每个选项的 API 名称