aitable-workflow-cli 0.1.13-beta.1

package/templates/support-qa/profiles/aitable/wiki/faq-support/.kb/wiki/references/TextField /346/226/207/346/234/254/345/255/227/346/256/265.md"

@@ -0,0 +1,64 @@
+---
+title: TextField 文本字段
+category: reference
+sources: [18-开发者指南/AI表格对象模型API参考文档/Field 模块/TextField 文本字段.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [TextField, 文本字段, Field API]
+aliases: [文本字段, text]
+confidence: high
+summary: TextField 是 AI 表格对象模型中最基础的文本字段类型，用于存储和管理纯文本数据。提供简洁的读写接口。
+---
+
+> TextField 是最基础的字段类型之一，用于处理纯文本数据。提供简洁的 getValueAsync 和 setValueAsync 接口进行文本的读写操作。
+
+## 核心特性
+
+- 继承自基础 Field 类
+- 存储纯文本字符串
+- 提供标准的读写操作
+
+## 字段特有方法
+
+### getValueAsync
+
+获取指定记录的文本值。
+
+```typescript
+getValueAsync: (recordId: string) => Promise<string | null>
+```
+
+**返回值**
+
+- `Promise<string | null>` - 文本值；记录不存在或值为空时返回 `null`
+
+### setValueAsync
+
+设置指定记录的文本值。
+
+```typescript
+setValueAsync: (recordId: string, text: string) => Promise<boolean>
+```
+
+**示例**
+
+```typescript
+const textField = sheet.getField<TextField>('备注');
+if (textField) {
+  const text = await textField.getValueAsync('rec123456');
+  console.log(`备注内容: ${text || '无'}`);
+
+  const success = await textField.setValueAsync('rec123456', '这是一条新的备注内容');
+}
+```
+
+## See Also
+
+- [Field 模块](./Field%20模块.md)
+- [RichTextField 富文本字段](./RichTextField%20富文本字段.md)
+- [PrimaryField 主键文档字段](./PrimaryField%20主键文档字段.md)
+- [TelephoneField 电话字段](./TelephoneField%20电话字段.md)
+
+## Sources
+
+- [TextField 文本字段](https://alidocs.dingtalk.com/i/nodes/np9zOoBVBy2AdzEju0z93rx2W1DK0g6l?utm_scene=person_space)

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

@@ -0,0 +1,169 @@
+---
+title: UI 模块 API 参考
+category: reference
+sources: [18-开发者指南/AI表格对象模型API参考文档/UI 模块.md, 18-开发者指南/AI表格脚本插件 开发指南/UI 模块.md, 18-开发者指南/AI表格边栏插件 开发指南/UI 模块.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [UI, 用户界面, 选区, 高亮, toast, API]
+aliases: [UI API, 界面交互模块]
+confidence: high
+summary: UI 模块提供与用户界面交互的能力，包括消息提示（toast）、选区管理（getSelection/setSelection）、区域高亮、记录详情展示，适用于边栏插件和脚本插件。
+---
+
+> UI 模块是 AI 表格插件中处理用户界面交互的核心模块，提供消息提示、选区操作、区域高亮和记录详情展示等功能，帮助插件与用户进行可视化交互。
+
+## 获取 UI 实例
+
+```typescript
+// 边栏插件
+const ui = DingdocsScript.base.ui;
+
+// 脚本插件
+const ui = Base.ui;
+```
+
+## toast — 消息提示
+
+显示消息提示，支持四种类型和自定义持续时间。
+
+```typescript
+toast: (toastOptions: ToastOptions) => Promise<{ success: boolean }>;
+```
+
+### 消息类型与背景色
+
+| 类型 | 背景色 |
+|------|--------|
+| `ToastType.SUCCESS` | 绿色 |
+| `ToastType.ERROR` | 红色 |
+| `ToastType.WARNING` | 黄色 |
+| `ToastType.INFO` | 蓝色 |
+
+### 持续时间控制
+
+- `keepAlive: 'long'` — 持续 5 秒
+- `keepAlive: 'always'` — 常驻显示（自动设置 `closeable: true`）
+
+```typescript
+// 成功提示
+await ui.toast({ type: ToastType.SUCCESS, message: '操作成功！' });
+
+// 常驻提示
+await ui.toast({ type: ToastType.INFO, message: '系统维护通知', keepAlive: 'always' });
+
+// 可关闭的提示（带回调）
+await ui.toast({
+  type: ToastType.INFO,
+  message: '处理中...',
+  closeable: true,
+  onClose: () => { /* 关闭回调 */ },
+});
+```
+
+## getSelection — 获取选区
+
+返回当前激活区域信息，包含 sheetId、viewId、fieldId、recordId。
+
+```typescript
+getSelection: () => Promise<Position>;
+```
+
+根据返回字段判断选中类型：
+- `fieldId` + `recordId` 都有 → 选中单元格
+- 仅 `recordId` → 选中整行（`fieldId` 为 `undefined`）
+- 仅 `fieldId` → 选中整列（`recordId` 为 `undefined`）
+
+## setSelection — 设置选区
+
+通过代码控制选中状态，`sheetId` 和 `viewId` 必需。位置无效时返回 `false`。
+
+```typescript
+setSelection: (position: Position) => Promise<boolean>;
+```
+
+```typescript
+// 选中单元格
+await ui.setSelection({ sheetId: 'sheet123', viewId: 'view456', fieldId: 'field789', recordId: 'record001' });
+
+// 选中整行（不设置 fieldId）
+await ui.setSelection({ sheetId: 'sheet123', viewId: 'view456', recordId: 'record001' });
+
+// 选中整列（不设置 recordId）
+await ui.setSelection({ sheetId: 'sheet123', viewId: 'view456', fieldId: 'field789' });
+```
+
+## highlightSelection — 高亮区域
+
+临时标记指定区域，支持多个位置同时高亮。高亮信息不会存入文档，刷新或退出编辑态后消失。
+
+```typescript
+highlightSelection: (highlightOptions: HighlightOptions) => Promise<boolean>;
+```
+
+```typescript
+await ui.highlightSelection({
+  type: HighlightType.WARNING,
+  message: '数据异常',
+  positions: [
+    { sheetId: 'sheet123', viewId: 'view456', fieldId: 'field789', recordId: 'record001' },
+    { sheetId: 'sheet123', viewId: 'view456', fieldId: 'field789', recordId: 'record002' },
+  ],
+});
+
+// 高亮整行（不设置 fieldId）
+await ui.highlightSelection({
+  type: HighlightType.ERROR,
+  message: '此行数据有误',
+  positions: [{ sheetId: 'sheet123', viewId: 'view456', recordId: 'record001' }],
+});
+```
+
+## clearHighlightSelection — 清除高亮
+
+清除所有高亮区域，返回 `Promise<boolean>`。
+
+```typescript
+await ui.clearHighlightSelection();
+```
+
+## showRecordDetail — 记录详情
+
+在侧边栏或弹窗中显示指定记录详情。`sheetId`、`viewId` 和 `recordId` 均为必需。
+
+```typescript
+showRecordDetail: (info: RecordDetailInfo, config?: RecordDetailConfig) => Promise<boolean>;
+```
+
+- `RecordDetailType.SIDEBAR` — 侧边栏形式（默认）
+- `RecordDetailType.MODAL` — 弹窗形式
+
+```typescript
+// 侧边栏显示
+await ui.showRecordDetail({ sheetId: 'sheet123', viewId: 'view456', recordId: 'record001' });
+
+// 弹窗显示
+await ui.showRecordDetail(
+  { sheetId: 'sheet123', viewId: 'view456', recordId: 'record001' },
+  { type: RecordDetailType.MODAL }
+);
+
+// 配合选区使用
+const position = await ui.getSelection();
+if (position.recordId) {
+  await ui.showRecordDetail({
+    sheetId: position.sheetId!,
+    viewId: position.viewId!,
+    recordId: position.recordId,
+  });
+}
+```
+
+## See Also
+
+- [Base 模块](../references/Base%20模块.md)
+- [Sheet 模块](../references/Sheet%20模块.md)
+- [View 模块](../references/View%20模块.md)
+
+## Sources
+
+- [UI 模块](https://alidocs.dingtalk.com/notable/record?dentryUuid=GZLxjv9VGGDA9Ro2u05KgqMnV6EDybno&rowId=oiQFHSd1w8&sheetId=hERWDMS&viewId=qvGDAH2)

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

@@ -0,0 +1,99 @@
+---
+title: UnidirectionalLinkFields 单向关联字段
+category: reference
+sources: [18-开发者指南/AI表格对象模型API参考文档/Field 模块/UnidirectionalLinkFields 单向关联字段.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [UnidirectionalLinkField, 单向关联, Field API, 跨表关联]
+aliases: [单向关联字段, unidirectionalLink]
+confidence: high
+summary: UnidirectionalLinkField 是 AI 表格对象模型中的单向关联字段类型，用于从当前表向目标表建立单向关联关系。支持设置目标表、多选模式以及关联记录的读写。
+---
+
+> UnidirectionalLinkField 用于从当前表向目标表建立单向关联关系。与双向关联不同，单向关联只在当前表记录关联信息，不会在目标表创建反向关联。
+
+## 核心特性
+
+- 继承自基础 Field 类
+- 单向关联：只在当前表记录关联信息
+- 支持单选/多选模式
+- 可配置关联的目标数据表
+
+## 字段特有方法
+
+### getValueAsync
+
+获取指定记录的关联值。
+
+```typescript
+getValueAsync: (recordId: string) => Promise<AssociationsValue | null>
+```
+
+**返回值**
+
+- `Promise<AssociationsValue | null>` - 关联值对象，包含 `linkedRecordIds` 数组；未设置时返回 `null`
+
+**示例**
+
+```typescript
+const linkField = sheet.getField<UnidirectionalLinkField>('参考方案');
+if (linkField) {
+  const linkValue = await linkField.getValueAsync('rec_project_123');
+  if (linkValue) {
+    console.log(`关联的记录数量: ${linkValue.linkedRecordIds.length}`);
+    linkValue.linkedRecordIds.forEach((recordId, index) => {
+      console.log(`参考方案${index + 1}: ${recordId}`);
+    });
+  }
+}
+```
+
+### setValueAsync
+
+设置指定记录的关联值。
+
+```typescript
+setValueAsync: (recordId: string, value: AssociationsValue) => Promise<boolean>
+```
+
+**示例**
+
+```typescript
+const success = await linkField.setValueAsync('rec_123', {
+  linkedRecordIds: ['rec_1', 'rec_2'],
+});
+```
+
+### setLinkedSheetId / getLinkedSheetId
+
+设置或获取关联的目标数据表 ID。
+
+```typescript
+setLinkedSheetId: (linkedSheetId: string) => string
+getLinkedSheetId: () => string
+```
+
+### setMultiple / getMultiple
+
+设置或获取是否允许关联多条记录。
+
+```typescript
+setMultiple(multiple: boolean): string
+getMultiple(): boolean
+```
+
+**示例**
+
+```typescript
+linkField.setMultiple(true);   // 允许关联多条记录
+linkField.setMultiple(false);  // 只允许关联一条记录
+```
+
+## See Also
+
+- [Field 模块](./Field%20模块.md)
+- [LookupField 关联引用字段](./LookupField%20关联引用字段.md)
+
+## Sources
+
+- [UnidirectionalLinkFields 单向关联字段](https://alidocs.dingtalk.com/i/nodes/np9zOoBVBy2AdzEju0z93rx2W1DK0g6l?utm_scene=person_space)

package/templates/support-qa/profiles/aitable/wiki/faq-support/.kb/wiki/references/UrlField /351/223/276/346/216/245/345/255/227/346/256/265.md"

@@ -0,0 +1,86 @@
+---
+title: UrlField 链接字段
+category: reference
+sources: [18-开发者指南/AI表格对象模型API参考文档/Field 模块/UrlField 链接字段.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [UrlField, 链接字段, Field API, URL]
+aliases: [链接字段, url]
+confidence: high
+summary: UrlField 是 AI 表格对象模型中的链接字段类型，用于存储 URL 链接，支持设置显示文本和实际链接地址。适用于网站链接、资源地址等场景。
+---
+
+> UrlField 用于存储和管理 URL 链接，每个链接可包含显示文本（text）和实际链接地址（link）。适合存储网站链接、资源地址等需要跳转的信息。
+
+## 核心特性
+
+- 继承自基础 Field 类
+- 支持纯 URL 字符串或带显示文本的链接对象
+- 返回 LinkValue 对象，包含 `text` 和 `link` 属性
+
+## 字段特有方法
+
+### getValueAsync
+
+获取指定记录的 URL 值。
+
+```typescript
+getValueAsync: (recordId: string) => Promise<LinkValue | null>
+```
+
+**返回值**
+
+- `Promise<LinkValue | null>` - URL 对象，包含 `text`（显示文本）和 `link`（链接地址）属性；为空时返回 `null`
+
+### setValueAsync
+
+设置指定记录的 URL 值，支持字符串或 LinkValue 对象。
+
+```typescript
+setValueAsync: (recordId: string, url: LinkValue | string) => Promise<boolean>
+```
+
+**示例**
+
+```typescript
+const websiteField = sheet.getField<UrlField>('网站');
+if (websiteField) {
+  // 方式1：直接设置链接地址
+  await websiteField.setValueAsync('rec123456', 'https://www.example.com');
+
+  // 方式2：设置带显示文本的链接
+  await websiteField.setValueAsync('rec234567', {
+    link: 'https://www.example.org',
+    text: '示例网站'
+  });
+}
+```
+
+## 完整使用示例
+
+```typescript
+async function manageWebsiteLinks() {
+  const sheet = base.getSheet('合作伙伴');
+  const websiteField = sheet.getField<UrlField>('官网链接');
+
+  if (websiteField && websiteField.getType() === 'url') {
+    const partners = await sheet.getRecordsAsync({ pageSize: 50 });
+    for (const partner of partners.records) {
+      const website = await websiteField.getValueAsync(partner.getId());
+      if (website && website.link) {
+        console.log(`${partner.getCellValue('公司名称')}: ${website.text || website.link}`);
+      }
+    }
+  }
+}
+```
+
+## See Also
+
+- [Field 模块](./Field%20模块.md)
+- [TextField 文本字段](./TextField%20文本字段.md)
+- [TelephoneField 电话字段](./TelephoneField%20电话字段.md)
+
+## Sources
+
+- [UrlField 链接字段](https://alidocs.dingtalk.com/i/nodes/np9zOoBVBy2AdzEju0z93rx2W1DK0g6l?utm_scene=person_space)

package/templates/support-qa/profiles/aitable/wiki/faq-support/.kb/wiki/references/UserField /344/272/272/345/221/230/345/255/227/346/256/265.md"

@@ -0,0 +1,103 @@
+---
+title: UserField 人员字段
+category: reference
+sources: [18-开发者指南/AI表格对象模型API参考文档/Field 模块/UserField 人员字段.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [UserField, 人员字段, Field API, 钉钉用户]
+aliases: [人员字段, user]
+confidence: high
+summary: UserField 是 AI 表格对象模型中的人员字段类型，用于关联钉钉用户。支持通过 userId、unionId、jobNumber 或 extContactUserId 标识用户，提供读写和最佳实践示例。
+---
+
+> UserField 用于处理人员类型数据，可将钉钉用户与数据表记录关联。支持多种用户标识方式（userId、unionId、jobNumber、extContactUserId），返回用户名和 unionId。
+
+## 前置概念
+
+在使用 UserField 前，需了解以下钉钉用户标识：
+
+| 标识 | 说明 | 唯一性 |
+|------|------|--------|
+| **userId** | 员工在所属组织中的标识 | 组织内唯一 |
+| **unionId** | 员工在开发者企业范围内的标识 | 开发者企业范围内唯一 |
+| **jobNumber** | 员工工号 | 不保证唯一 |
+| **extContactUserId** | 外部联系人在组织中的标识 | 组织内唯一 |
+
+## 字段特有方法
+
+### getValueAsync
+
+获取指定记录中选择的人员。
+
+```typescript
+getValueAsync: (recordId: string) => Promise<UserCellValue[] | null>
+```
+
+**返回值**
+
+- `Promise<UserCellValue[] | null>` - 人员数组，包含用户名和 unionId
+
+**示例**
+
+```typescript
+const userField = sheet.getField<UserField>('人员');
+if (userField) {
+  const users = await userField.getValueAsync('rec123456');
+  console.log('查询到用户：', users.map(u => `${u.name}|${u.unionId}`).join('\n'));
+}
+```
+
+### setValueAsync
+
+设置指定记录的人员值，支持多种标识方式。
+
+```typescript
+setValueAsync: (recordId: string, value: UserCellValue[]) => Promise<boolean>
+```
+
+**示例**
+
+```typescript
+const success = await userField.setValueAsync('rec123456', [
+  { userId: 'user123' },
+  { unionId: 'xxxxx' },
+  { jobNumber: 'staff123' },
+  { extContactUserId: 'xxxxx' },
+]);
+```
+
+## 最佳实践：新增人员字段并写入当前用户
+
+```typescript
+async function addUserFieldWithCurrentUser() {
+  const currentUser = await Base.getCurrentUser();
+  const activeSheet = Base.getActiveSheet();
+  if (!currentUser || !activeSheet) return;
+
+  let userField = activeSheet.getField('负责人');
+  if (!userField) {
+    userField = activeSheet.insertField('负责人', 'user');
+  }
+
+  const newRecords = await activeSheet.insertRecordsAsync([{
+    fields: { '负责人': [{ unionId: currentUser.unionId }] }
+  }]);
+}
+```
+
+**关键点**：
+
+- 使用 `Base.getCurrentUser()` 获取当前登录用户
+- 使用 `getActiveSheet()` 获取当前激活数据表
+- 创建字段前先检查是否已存在同名字段
+- 人员字段值为数组格式，支持通过 userId 或 unionId 指定用户
+
+## See Also
+
+- [Field 模块](./Field%20模块.md)
+- [GroupField 群组字段](./GroupField%20群组字段.md)
+- [Record 模块](./Record%20模块.md)
+
+## Sources
+
+- [UserField 人员字段](https://alidocs.dingtalk.com/i/nodes/np9zOoBVBy2AdzEju0z93rx2W1DK0g6l?utm_scene=person_space)

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

@@ -0,0 +1,112 @@
+---
+title: View 模块 API 参考
+category: reference
+sources: [18-开发者指南/AI表格对象模型API参考文档/View 模块.md, 18-开发者指南/AI表格脚本插件 开发指南/View 模块.md, 18-开发者指南/AI表格边栏插件 开发指南/View 模块.md]
+created: 2026-07-20
+updated: 2026-07-20
+tags: [View, 视图, GridView, 筛选, FilterOperator, API]
+aliases: [视图模块, View API]
+confidence: high
+summary: View 模块是所有视图类型（如 GridView）的基类，提供视图 ID、类型、所属数据表查询及类型转换方法，同时定义了筛选条件（Filter）的核心数据结构。
+---
+
+> View 表示数据表中的视图，是数据表的呈现方式。View 是所有具体视图类型（如 GridView、KanbanView 等）的基础类，提供统一的基础接口和视图类型转换方法。
+
+## 基本信息方法
+
+### getId
+
+获取视图 ID，返回 `string`。
+
+```typescript
+const viewId = view.getId();
+```
+
+### getType
+
+获取视图类型，返回 `ViewType | undefined`。不支持插件调用的视图类型返回 `undefined`。
+
+```typescript
+const viewType = view.getType();
+```
+
+### getSheetId
+
+获取视图所属数据表 ID，返回 `string`。
+
+```typescript
+const sheetId = view.getSheetId();
+```
+
+## 视图类型转换
+
+### asGridView
+
+将当前视图转换为表格视图对象。如果视图类型不是 Grid 则返回 `null`。
+
+```typescript
+asGridView: () => GridView | null
+```
+
+```typescript
+const gridView = view.asGridView();
+if (gridView) {
+  const visibleFields = await gridView.getVisibleFieldIdList();
+  const filterInfo = await gridView.getFilterInfo();
+  console.log(`可见字段数量: ${visibleFields.length}`);
+  console.log(`筛选条件数量: ${filterInfo?.conditions.length || 0}`);
+}
+```
+
+## 支持的视图类型
+
+目前支持以下视图类型：
+
+- **GridView（表格视图）** — 以表格形式展示数据，详见 [GridView 表格视图](../references/GridView%20表格视图.md)
+
+每种视图类型都有其特定的功能和 API，View 基类提供统一的基础接口。
+
+## 筛选（Filter）数据结构
+
+视图根据筛选条件过滤记录，主要由条件和连接方式组成：
+
+```typescript
+interface IFilterInfo {
+  conjunction: FilterConjunction;    // 条件间关系
+  conditions: FilterInfoCondition[]; // 具体的筛选条件
+}
+
+interface FilterInfoCondition {
+  fieldId: string;        // 字段 ID
+  conditionId?: string;   // 条件 ID（可选）
+  value: any;             // 匹配值
+  operator: FilterOperator; // 操作符
+}
+```
+
+### FilterConjunction 枚举
+
+| 值 | 含义 |
+|----|------|
+| `'and'` | 满足所有条件 |
+| `'or'` | 满足任一条件 |
+
+### FilterOperator 枚举
+
+| 操作符 | 含义 |
+|--------|------|
+| `is` / `isNot` | 等于 / 不等于 |
+| `contains` / `doesNotContain` | 包含 / 不包含 |
+| `isEmpty` / `isNotEmpty` | 为空 / 不为空 |
+| `isGreater` / `isGreaterEqual` | 大于 / 大于或等于 |
+| `isLess` / `isLessEqual` | 小于 / 小于或等于 |
+
+## See Also
+
+- [GridView 表格视图](../references/GridView%20表格视图.md)
+- [Sheet 模块](../references/Sheet%20模块.md)
+- [核心知识](../concepts/核心知识.md)
+
+## Sources
+
+- [View 模块](https://alidocs.dingtalk.com/i/nodes/1R7q3QmWeljPoM5BSzo3RnAY8xkXOEP2?iframeQuery=anchorId%3DX02mev4my6gw6k5byorvrm&utm_scene=team_space)