aitable-workflow-cli 0.1.13-beta.1

package/templates/support-qa/profiles/aitable/wiki/faq-support/.kb/wiki/references/Base /346/250/241/345/235/227.md"

@@ -0,0 +1,158 @@
+---
+title: Base 模块 API 参考
+category: reference
+sources: [18-开发者指南/AI表格脚本插件 开发指南/Base 模块.md, 18-开发者指南/AI表格边栏插件 开发指南/Base 模块.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [Base, AI表格, 顶级对象, 权限, API, JSAPI]
+aliases: [Base API, AI表格顶级对象, DingdocsScript.base]
+confidence: high
+summary: Base 模块是 AI 表格 API 的主入口，提供数据表管理（获取/插入/更新/删除）、字段类型判断、选区获取、文档信息查询、用户信息获取和权限检查等方法。
+---
+
+> Base 是 AI 表格对象模型的顶级入口，代表当前打开的 AI 表格实例。所有数据表操作均从 Base 开始，它是边栏插件和脚本插件中最先接触的对象。
+
+## 获取 Base 实例
+
+```typescript
+// 边栏插件
+const base = DingdocsScript.base;
+
+// 脚本插件（全局变量）
+const base = Base;
+```
+
+## 数据表管理方法
+
+### getActiveSheet
+
+获取当前激活的数据表，返回 `Sheet | null`。
+
+```typescript
+const sheet = Base.getActiveSheet();
+```
+
+### getSheet
+
+按 ID 或名称获取指定数据表，返回 `Sheet | null`。
+
+```typescript
+const sheet = Base.getSheet('产品清单');
+const sheet = Base.getSheet('sht123456');
+```
+
+### getSheets
+
+获取当前用户可见的所有数据表，返回 `Sheet[]`。
+
+```typescript
+const allSheets = Base.getSheets();
+```
+
+### insertSheet
+
+插入新数据表，可选传入字段配置，返回 `Sheet`。
+
+```typescript
+const sheet = Base.insertSheet('客户信息', [
+  { name: '客户名称', type: 'text' },
+  { name: '注册日期', type: 'date' },
+]);
+```
+
+### updateSheet
+
+按 ID 更新数据表名称和描述，返回 `Sheet`。
+
+```typescript
+Base.updateSheet('sht123', { name: '新名称', desc: '新描述' });
+```
+
+### deleteSheet
+
+按 ID 或名称删除数据表，返回 Base 自身（链式调用）。不能删除最后一张数据表。
+
+```typescript
+Base.deleteSheet('临时数据表');
+```
+
+## 字段类型判断
+
+### isFieldOfType
+
+判断字段是否为指定类型，返回类型守卫 `boolean`。
+
+```typescript
+const field = sheet.getField('数字');
+if (Base.isFieldOfType(field, 'number')) {
+  // field 被推断为 Field<'number'>
+}
+```
+
+## 选区与文档信息
+
+### getSelection
+
+获取当前 AI 表格激活区域信息，返回 `Selection` 对象。
+
+```typescript
+const selection = Base.getSelection();
+```
+
+### getDentryUuid
+
+获取文档的 dentryUuid，返回 `string`。
+
+```typescript
+const uuid = Base.getDentryUuid();
+```
+
+### getCorpId
+
+获取文档所属企业的 CorpId。**仅脚本插件可用**。
+
+```typescript
+const corpId = Base.getCorpId();
+```
+
+### getCurrentUser
+
+获取当前用户信息。**仅脚本插件可用**，返回 `Promise<UserCellValue | null>`。
+
+```typescript
+const user = await Base.getCurrentUser();
+if (user) {
+  Output.log(`用户: ${user.name}, ID: ${user.unionId}`);
+}
+```
+
+## 权限检查
+
+### getPermissionAsync
+
+检查文档权限，返回 `Promise<boolean>`。
+
+```typescript
+const hasPermission = await Base.getPermissionAsync({
+  scope: PermissionScope.BASE,
+  permissionType: PermissionType.MANAGE,
+});
+```
+
+## 注意事项
+
+- `insertSheet` 时第一个字段类型必须支持作为主字段，字段名称不能重复
+- 不能删除最后一张数据表
+- 部分操作受权限限制，建议执行前通过 `getPermissionAsync` 检查
+- `getCorpId` 和 `getCurrentUser` 仅在脚本插件中可用，边栏插件需使用 getAuthCode API
+
+## See Also
+
+- [Sheet 模块](../references/Sheet%20模块.md)
+- [读写AI 表格模型](../concepts/读写AI%20表格模型.md)
+- [Field 模块](../references/Field%20模块.md)
+
+## Sources
+
+- [Base 模块](https://alidocs.dingtalk.com/i/nodes/LeBq413JAOyAdGBMsBo1lRd3WDOnGvpb?iframeQuery=anchorId%3DX02mk15wsqsz7clll7zlo)
+- [Base 模块](https://alidocs.dingtalk.com/i/nodes/pGBa2Lm8aeP35vxdtDBqQ1Xx8gN7R35y?iframeQuery=anchorId%3DX02mk15wsqsz7clll7zlo)

package/templates/support-qa/profiles/aitable/wiki/faq-support/.kb/wiki/references/BidirectionalLinkField /345/217/214/345/220/221/345/205/263/350/201/224/345/255/227/346/256/265.md"

@@ -0,0 +1,69 @@
+---
+title: BidirectionalLinkField 双向关联字段 API
+category: reference
+sources: [18-开发者指南/AI表格对象模型API参考文档/Field 模块/BidirectionalLinkField 双向关联字段.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [API, Field模块, 双向关联, BidirectionalLinkField, 数据关联]
+aliases: [双向关联字段API, BidirectionalLinkField]
+confidence: high
+summary: BidirectionalLinkField 双向关联字段的 API 参考，用于在两个表之间建立双向关联关系，支持获取/设置关联值、目标表配置及单选/多选模式切换。
+---
+
+> BidirectionalLinkField 用于在两个数据表之间建立双向关联关系。在当前表中设置关联时，目标表中也会自动创建反向关联。
+
+## API 方法
+
+### getValueAsync / setValueAsync
+
+获取或设置指定记录的关联值。
+
+```typescript
+getValueAsync(recordId: string): Promise<AssociationsValue | null>
+setValueAsync(recordId: string, value: AssociationsValue): Promise<boolean>
+```
+
+`AssociationsValue` 包含 `linkedRecordIds` 属性，为关联的记录 ID 数组。
+
+### setLinkedSheetId / getLinkedSheetId
+
+设置或获取关联的目标数据表 ID。
+
+```typescript
+setLinkedSheetId(linkedSheetId: string): string
+getLinkedSheetId(): string
+```
+
+### setMultiple / getMultiple
+
+设置或获取是否允许关联多条记录。
+
+```typescript
+setMultiple(multiple: boolean): string
+getMultiple(): boolean
+```
+
+- `true` — 允许关联多条记录
+- `false` — 只能关联一条记录
+
+## 使用示例
+
+```typescript
+const linkField = sheet.getField('关联项目');
+if (Base.isFieldOfType(linkField, 'bidirectionalLink')) {
+  // 设置关联
+  await linkField.setValueAsync('rec_123', {
+    linkedRecordIds: ['rec_project_1', 'rec_project_2']
+  });
+  // 目标表中的相关记录会自动建立反向关联
+}
+```
+
+## See Also
+
+- [Base 模块 API 参考](../references/Base%20模块.md)
+- [CheckboxField 复选框字段 API](../references/CheckboxField%20复选框字段.md)
+
+## Sources
+
+- [BidirectionalLinkField 双向关联字段](https://alidocs.dingtalk.com/i/nodes/np9zOoBVBy2AdzEju0z93rx2W1DK0g6l?utm_scene=person_space)

package/templates/support-qa/profiles/aitable/wiki/faq-support/.kb/wiki/references/CheckboxField /345/244/215/351/200/211/346/241/206/345/255/227/346/256/265.md"

@@ -0,0 +1,51 @@
+---
+title: CheckboxField 复选框字段 API
+category: reference
+sources: [18-开发者指南/AI表格对象模型API参考文档/Field 模块/CheckboxField 复选框字段.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [API, Field模块, 复选框, CheckboxField, 布尔值]
+aliases: [复选框字段API, CheckboxField]
+confidence: high
+summary: CheckboxField 复选框字段的 API 参考，用于处理是/否、启用/禁用等二元状态数据，支持布尔值的读取和设置。
+---
+
+> CheckboxField 用于处理开关类型的复选框字段数据，表示是/否、启用/禁用等二元状态，值为布尔类型。
+
+## API 方法
+
+### getValueAsync
+
+获取指定记录的复选框值。
+
+```typescript
+getValueAsync(recordId: string): Promise<boolean | null>
+```
+
+返回 `true`/`false`，字段值为空时返回 null。
+
+### setValueAsync
+
+设置指定记录的复选框值。
+
+```typescript
+setValueAsync(recordId: string, val: boolean): Promise<boolean>
+```
+
+**示例**:
+
+```typescript
+const checkboxField = sheet.getField('已完成');
+if (Base.isFieldOfType(checkboxField, 'checkbox')) {
+  await checkboxField.setValueAsync('rec123456', true);
+}
+```
+
+## See Also
+
+- [Base 模块 API 参考](../references/Base%20模块.md)
+- [BidirectionalLinkField 双向关联字段 API](../references/BidirectionalLinkField%20双向关联字段.md)
+
+## Sources
+
+- [CheckboxField 复选框字段](https://alidocs.dingtalk.com/i/nodes/np9zOoBVBy2AdzEju0z93rx2W1DK0g6l?utm_scene=person_space)

package/templates/support-qa/profiles/aitable/wiki/faq-support/.kb/wiki/references/CreatedTimeField /345/210/233/345/273/272/346/227/266/351/227/264/345/255/227/346/256/265.md"

@@ -0,0 +1,55 @@
+---
+title: CreatedTimeField 创建时间字段 API
+category: reference
+sources: [18-开发者指南/AI表格对象模型API参考文档/Field 模块/CreatedTimeField 创建时间字段.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [API, Field模块, 创建时间, CreatedTimeField, 只读字段]
+aliases: [创建时间字段API, CreatedTimeField]
+confidence: high
+summary: CreatedTimeField 创建时间字段的 API 参考，系统自动记录数据行创建时间（毫秒级 Unix 时间戳），是只读字段，支持日期格式的获取和设置。
+---
+
+> CreatedTimeField 是系统自动记录数据行创建时间的只读字段，以毫秒级 Unix 时间戳形式存储，不能手动设置值。
+
+## API 方法
+
+### getValueAsync
+
+获取指定记录的创建时间值。
+
+```typescript
+getValueAsync(recordId: string): Promise<DateCellValue | null>
+```
+
+返回毫秒级时间戳，字段值为空时返回 null。
+
+**示例**:
+
+```typescript
+const createdTimeField = sheet.getField('创建时间');
+if (Base.isFieldOfType(createdTimeField, 'createdTime')) {
+  const timestamp = await createdTimeField.getValueAsync('rec123456');
+  if (timestamp !== null) {
+    Output.log(`创建时间: ${new Date(timestamp).toLocaleString()}`);
+  }
+}
+```
+
+### getDateFormat / setDateFormat
+
+获取或设置创建时间字段的日期格式。
+
+```typescript
+getDateFormat(): DateFormatter
+setDateFormat(format: DateFormatter): string
+```
+
+## See Also
+
+- [DateField 日期字段 API](../references/DateField%20日期字段.md)
+- [Base 模块 API 参考](../references/Base%20模块.md)
+
+## Sources
+
+- [CreatedTimeField 创建时间字段](https://alidocs.dingtalk.com/i/nodes/np9zOoBVBy2AdzEju0z93rx2W1DK0g6l?utm_scene=person_space)

package/templates/support-qa/profiles/aitable/wiki/faq-support/.kb/wiki/references/CurrencyField /350/264/247/345/270/201/345/255/227/346/256/265.md"

@@ -0,0 +1,66 @@
+---
+title: CurrencyField 货币字段 API
+category: reference
+sources: [18-开发者指南/AI表格对象模型API参考文档/Field 模块/CurrencyField 货币字段.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [API, Field模块, 货币字段, CurrencyField, 金额]
+aliases: [货币字段API, CurrencyField]
+confidence: high
+summary: CurrencyField 货币字段的 API 参考，支持不同货币类型（人民币、美元、欧元等）和精度设置，提供货币值的读写及格式化配置方法。
+---
+
+> CurrencyField 专门处理货币值，支持不同货币类型（CNY、USD、EUR 等）和 0-4 位小数精度，提供货币格式化和显示功能。
+
+## API 方法
+
+### getValueAsync / setValueAsync
+
+读写货币字段值。
+
+```typescript
+getValueAsync(recordId: string): Promise<number | null>
+setValueAsync(recordId: string, num: number | string): Promise<boolean>
+```
+
+`setValueAsync` 支持传入数字或可转换为数字的字符串。
+
+### getDecimalDigits / setDecimalDigits
+
+获取或设置小数位数（0-4）。
+
+```typescript
+getDecimalDigits(): number
+setDecimalDigits(decimalDigits: number): string
+```
+
+### getCurrencyType / setCurrencyType
+
+获取或设置货币类型。
+
+```typescript
+getCurrencyType(): CurrencyType
+setCurrencyType(currencyType: CurrencyType): string
+```
+
+支持 CNY（人民币）、USD（美元）等货币类型。
+
+**示例**:
+
+```typescript
+const priceField = sheet.getField('价格');
+if (Base.isFieldOfType(priceField, 'currency')) {
+  priceField.setCurrencyType('CNY');
+  priceField.setDecimalDigits(2);
+  await priceField.setValueAsync('rec123456', 299.99);
+}
+```
+
+## See Also
+
+- [Base 模块 API 参考](../references/Base%20模块.md)
+- [DateField 日期字段 API](../references/DateField%20日期字段.md)
+
+## Sources
+
+- [CurrencyField 货币字段](https://alidocs.dingtalk.com/i/nodes/GZLxjv9VGGDA9Ro2u05KgqMnV6EDybno?iframeQuery=record%3DhERWDMS_qvGDAH2_hHpVgVFkY3)

package/templates/support-qa/profiles/aitable/wiki/faq-support/.kb/wiki/references/DateField /346/227/245/346/234/237/345/255/227/346/256/265.md"

@@ -0,0 +1,63 @@
+---
+title: DateField 日期字段 API
+category: reference
+sources: [18-开发者指南/AI表格对象模型API参考文档/Field 模块/DateField 日期字段.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [API, Field模块, 日期字段, DateField, 时间戳]
+aliases: [日期字段API, DateField]
+confidence: high
+summary: DateField 日期字段的 API 参考，以毫秒级 Unix 时间戳存储日期时间数据，支持日期值的读写和格式化设置，适用于截止日期、开始/结束时间等场景。
+---
+
+> DateField 用于处理日期和时间类型数据，以毫秒级 Unix 时间戳形式存储，支持不同的日期格式化选项，适用于截止日期、开始/结束时间等场景。
+
+## API 方法
+
+### getValueAsync / setValueAsync
+
+读写日期字段值。
+
+```typescript
+getValueAsync(recordId: string): Promise<DateCellValue | null>
+setValueAsync(recordId: string, timestamp: DateCellValue): Promise<boolean>
+```
+
+值为毫秒级 Unix 时间戳。
+
+**示例**:
+
+```typescript
+const dueDateField = sheet.getField('截止日期');
+if (Base.isFieldOfType(dueDateField, 'date')) {
+  // 设置为明天
+  const tomorrow = new Date();
+  tomorrow.setDate(tomorrow.getDate() + 1);
+  await dueDateField.setValueAsync('rec123456', tomorrow.getTime());
+}
+```
+
+### getDateFormat / setDateFormat
+
+获取或设置日期格式。
+
+```typescript
+getDateFormat(): DateFormatter
+setDateFormat(formatter: DateFormatter): string
+```
+
+**示例**:
+
+```typescript
+dueDateField.setDateFormat('YYYY/MM/DD HH:mm');
+```
+
+## See Also
+
+- [CreatedTimeField 创建时间字段 API](../references/CreatedTimeField%20创建时间字段.md)
+- [CurrencyField 货币字段 API](../references/CurrencyField%20货币字段.md)
+- [Base 模块 API 参考](../references/Base%20模块.md)
+
+## Sources
+
+- [DateField 日期字段](https://alidocs.dingtalk.com/i/nodes/np9zOoBVBy2AdzEju0z93rx2W1DK0g6l?utm_scene=person_space)

package/templates/support-qa/profiles/aitable/wiki/faq-support/.kb/wiki/references/DepartmentField /351/203/250/351/227/250/345/255/227/346/256/265.md"

@@ -0,0 +1,60 @@
+---
+title: DepartmentField 部门字段 API
+category: reference
+sources: [18-开发者指南/AI表格对象模型API参考文档/Field 模块/DepartmentField 部门字段.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [API, Field模块, 部门字段, DepartmentField, 钉钉组织]
+aliases: [部门字段API, DepartmentField]
+confidence: high
+summary: DepartmentField 部门字段的 API 参考，用于处理钉钉组织部门类型数据，支持通过 deptId 读写部门信息，需了解钉钉部门 deptId 概念。
+---
+
+> DepartmentField 用于处理钉钉组织部门类型数据，通过 deptId 唯一识别组织部门，支持部门值的读取和设置。
+
+## 前置知识
+
+**deptId**: 钉钉中用于唯一识别组织部门的标识。参考[钉钉部门相关操作文档](https://open.dingtalk.com/document/development/operations-related-to-address-book-departments)。
+
+## API 方法
+
+### getValueAsync
+
+获取指定记录的部门值。
+
+```typescript
+getValueAsync(recordId: string): Promise<DepartmentCellValue[] | null>
+```
+
+返回部门数组，包含部门名称和 ID。
+
+### setValueAsync
+
+设置指定记录的部门值。
+
+```typescript
+setValueAsync(recordId: string, value: DepartmentCellValue[]): Promise<boolean>
+```
+
+通过 `deptId` 设置部门。
+
+**示例**:
+
+```typescript
+const departmentField = sheet.getField('部门');
+if (Base.isFieldOfType(departmentField, 'department')) {
+  await departmentField.setValueAsync('rec123456', [
+    { deptId: '1234' },
+    { deptId: '5678' }
+  ]);
+}
+```
+
+## See Also
+
+- [Base 模块 API 参考](../references/Base%20模块.md)
+- [EmailField 邮箱字段 API](../references/EmailField%20邮箱字段.md)
+
+## Sources
+
+- [DepartmentField 部门字段](https://alidocs.dingtalk.com/i/nodes/np9zOoBVBy2AdzEju0z93rx2W1DK0g6l?utm_scene=person_space)

package/templates/support-qa/profiles/aitable/wiki/faq-support/.kb/wiki/references/EmailField /351/202/256/347/256/261/345/255/227/346/256/265.md"

@@ -0,0 +1,54 @@
+---
+title: EmailField 邮箱字段 API
+category: reference
+sources: [18-开发者指南/AI表格对象模型API参考文档/Field 模块/EmailField 邮箱字段.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [API, Field模块, 邮箱字段, EmailField, 联系信息]
+aliases: [邮箱字段API, EmailField]
+confidence: high
+summary: EmailField 邮箱字段的 API 参考，用于存储和验证邮箱地址信息，支持邮箱地址的读取和设置，设置时需确保地址格式合法。
+---
+
+> EmailField 用于存储和验证邮箱地址信息，支持邮箱地址的读取和设置操作。设置时需确保邮箱地址格式合法，否则更新将失败。
+
+## API 方法
+
+### getValueAsync
+
+获取指定记录的邮箱值。
+
+```typescript
+getValueAsync(recordId: string): Promise<string | null>
+```
+
+返回邮箱地址字符串，字段值为空时返回 null。
+
+### setValueAsync
+
+设置指定记录的邮箱值。
+
+```typescript
+setValueAsync(recordId: string, text: string): Promise<boolean>
+```
+
+**重要**: 请确保邮箱地址为合法格式，否则更新数据将失败。
+
+**示例**:
+
+```typescript
+const emailField = sheet.getField('联系邮箱');
+if (Base.isFieldOfType(emailField, 'email')) {
+  await emailField.setValueAsync('rec123456', 'example@company.com');
+}
+```
+
+## See Also
+
+- [Base 模块 API 参考](../references/Base%20模块.md)
+- [DepartmentField 部门字段 API](../references/DepartmentField%20部门字段.md)
+- [BarcodeField 条码字段 API](../references/BarcodeField%20条码字段.md)
+
+## Sources
+
+- [EmailField 邮箱字段](https://alidocs.dingtalk.com/i/nodes/np9zOoBVBy2AdzEju0z93rx2W1DK0g6l?utm_scene=person_space)

package/templates/support-qa/profiles/aitable/wiki/faq-support/.kb/wiki/references/Event/344/272/213/344/273/266/346/250/241/345/235/227.md

@@ -0,0 +1,113 @@
+---
+title: Event 事件模块 API 参考
+category: reference
+sources: [18-开发者指南/AI表格边栏插件 开发指南/Event事件模块.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [Event, 事件监听, 回调, Sheet, Field, Record, 按钮字段, API]
+aliases: [事件模块, Event API]
+confidence: high
+summary: Event 事件模块为边栏插件提供数据变更和用户交互的监听能力，支持 Sheet/Field/Record 的增删改事件、选区变更事件和按钮字段点击事件。
+---
+
+> Event 事件模块是边栏插件专有的能力，通过 `Dingdocs.base.event` 访问。开发者可以监听数据表、字段、记录的增删改事件以及用户的选区变更和按钮点击，实现响应式的插件交互。
+
+## 访问方式
+
+```typescript
+const event = Dingdocs.base.event;
+```
+
+所有事件监听方法返回一个取消监听函数 `OffListener`，调用即可解除监听。
+
+## Sheet 事件
+
+### onSheetInserted / onSheetDeleted
+
+监听数据表的添加/删除事件。
+
+```typescript
+const off = Dingdocs.base.event.onSheetInserted((event) => {
+  console.log('sheet inserted', event.baseId);
+});
+// 取消监听
+off();
+```
+
+回调参数：`{ baseId: string }`
+
+## Field 事件
+
+### onFieldInserted / onFieldModified / onFieldDeleted
+
+监听字段的添加/修改/删除事件。
+
+```typescript
+const off = Dingdocs.base.event.onFieldInserted((event) => {
+  console.log('field inserted', event.sheetId);
+});
+```
+
+回调参数：`{ baseId: string; sheetId: string }`
+
+## Record 事件
+
+### onRecordInserted / onRecordModified / onRecordDeleted
+
+监听记录的添加/修改/删除事件。
+
+```typescript
+const off = Dingdocs.base.event.onRecordModified((event) => {
+  console.log('record modified', event.recordId);
+});
+```
+
+回调参数：`{ baseId: string; sheetId: string; recordId: string }`
+
+## 选区变更事件
+
+### onSelectionChanged
+
+监听当前选中区域（数据表、单元格、视图）的变更。
+
+```typescript
+const off = Dingdocs.base.event.onSelectionChanged((selection) => {
+  console.log('current selection', selection);
+});
+```
+
+回调参数 `Selection`：
+
+```typescript
+interface Selection {
+  baseId: string;
+  sheetId: string | null;
+  viewId: string | null;
+  fieldId: string | null;
+  recordId: string | null;
+}
+```
+
+## 按钮字段点击事件
+
+### onButtonFieldClicked
+
+监听按钮字段被点击事件。当用户点击按钮并绑定边栏插件后，若插件未打开会自动唤起，事件会暂存直到插件初始化并完成事件监听注册后才发出。
+
+```typescript
+const off = Dingdocs.base.event.onButtonFieldClicked((event) => {
+  console.log('button clicked', event.recordId);
+});
+```
+
+回调参数：`{ baseId: string; sheetId: string; viewId: string; recordId: string }`
+
+## See Also
+
+- [Base 模块](../references/Base%20模块.md)
+- [Sheet 模块](../references/Sheet%20模块.md)
+- [UI 模块](../references/UI%20模块.md)
+
+## Sources
+
+- Event事件模块