aitable-workflow-cli 0.1.13-beta.1

package/templates/support-qa/profiles/aitable/wiki/faq-support/18-/345/274/200/345/217/221/350/200/205/346/214/207/345/215/227/AI/350/241/250/346/240/274/345/257/271/350/261/241/346/250/241/345/236/213API/345/217/202/350/200/203/346/226/207/346/241/243/Field /346/250/241/345/235/227/UserField /344/272/272/345/221/230/345/255/227/346/256/265.md"

@@ -0,0 +1,266 @@
+# UserField 人员字段
+
+`UserField` 继承自基础 [`Field`](https://alidocs.dingtalk.com/i/nodes/np9zOoBVBy2AdzEju0z93rx2W1DK0g6l?utm_scene=person_space)类，专门用于处理人员类型数据。
+
+在读写人员字段前，请先了解钉钉用户unionId和userId概念：
+
+:::
+**UserId**
+
+UserId是员工在其所属组织中的唯一标识，仅在所属组织内是唯一标识符。同一个用户在不同组织中可以拥有不同的UserId。
+
+[https://open.dingtalk.com/document/development/query-the-list-of-department-userids: https://open.dingtalk.com/document/development/query-the-list-of-department-userids](https://open.dingtalk.com/document/development/query-the-list-of-department-userids)
+:::
+:::
+**Unionid**
+
+UnionId是员工在当前开发者企业范围内的唯一标识，由系统生成。
+
+对于开发边栏插件的用户而言，uniondId为插件所属企业范围内的唯一标识，同一个员工在不同的组织的企业内/三方插件下，unionid是不相同的。在同一个开发者企业账号下，unionid是唯一且不变的。
+
+对于开发脚本插件的用户而言，unionId始终返回文档所属企业下的唯一标识。
+
+[https://open.dingtalk.com/document/development/query-a-user-by-the-union-id: https://open.dingtalk.com/document/development/query-a-user-by-the-union-id](https://open.dingtalk.com/document/development/query-a-user-by-the-union-id)
+:::
+:::
+**JobNumber**
+
+JobNumber是员工在其所属组织中的工号。企业内员工的工号可以不唯一，所以不能作为员工在企业内的唯一标识。
+
+[https://open.dingtalk.com/document/development/contacts-overview#title-r7e-f1c-inp: https://open.dingtalk.com/document/development/contacts-overview#title-r7e-f1c-inp](https://open.dingtalk.com/document/development/contacts-overview#title-r7e-f1c-inp)
+:::
+:::
+**ExtContactUserId**
+
+ExtContactUserId是外部联系人在组织中的唯一标识，尽在所属组织内是唯一标识符。客户信息可作为外部联系人统一管理，避免员工离职带走客户信息。
+
+[https://open.dingtalk.com/document/development/add-enterprise-external-contacts: https://open.dingtalk.com/document/development/add-enterprise-external-contacts](https://open.dingtalk.com/document/development/add-enterprise-external-contacts)
+:::
+
+## 字段特有方法
+
+### getValueAsync
+
+获取指定记录在该人员字段中选择的人员。
+
+```typescript
+getValueAsync: (recordId: string) => Promise<UserCellValue[] | null>
+
+```
+
+**参数**
+
+*   `recordId`: `string` - 记录ID
+    
+
+**返回值**
+
+*   [`Promise<UserCellValue[] | null>`](https://alidocs.dingtalk.com/notable/record?dentryUuid=GZLxjv9VGGDA9Ro2u05KgqMnV6EDybno&rowId=udEx7tlPxG&sheetId=hERWDMS&viewId=qvGDAH2)\- 选中的人员，返回用户名和用户unionId
+    
+
+**示例**
+
+```typescript
+// 获取记录的人员值
+const userField = sheet.getField<UserField>('人员');
+if (userField) {
+  const users = await userField.getValueAsync('rec123456');
+  console.log('查询到用户：', users.map((user) => (`用户名：${user.name}|用户unionId: ${user.unionId}`)).join('\n'));
+}
+```
+```typescript
+const userField = sheet.getField('人员');
+if (Base.isFieldOfType(userField, 'user')) {
+  const users = await userField.getValueAsync('rec123456');
+  Output.log('查询到用户：\n', users.map((user) => (`用户名：${user.name}|用户unionId: ${user.unionId}`)).join('\n'));
+}
+```
+
+### setValueAsync
+
+设置指定记录在该人员字段中的人员值。
+
+```typescript
+setValueAsync: (recordId: string, value: UserCellValue[]) => Promise<boolean>
+```
+
+**参数**
+
+*   `recordId`: `string` - 记录ID
+    
+*   `value`: [`UserCellValue[]`](https://alidocs.dingtalk.com/notable/record?dentryUuid=GZLxjv9VGGDA9Ro2u05KgqMnV6EDybno&rowId=udEx7tlPxG&sheetId=hERWDMS&viewId=qvGDAH2) - 人员值，支持传入用户的userId或unionId
+    
+
+**返回值**
+
+*   `Promise<boolean>`\- 操作是否成功
+    
+
+**示例**
+
+```typescript
+// 设置记录的选项值
+const userField = sheet.getField<UserField>('人员');
+if (userField) {
+  const success = await userField.setValueAsync('rec123456', [{
+    userId: 'user123',
+  }, {
+    unionId: 'xxxxx',
+  }, {
+    jobNumber: 'staff123',
+  }, {
+    extContactUserId: 'xxxxx',
+  }]);
+  if (success) {
+    console.log('向记录中更新了两名人员');
+  } else {
+    console.log('记录更新失败');
+  }
+}
+
+```
+```typescript
+// 设置记录的选项值
+const userField = sheet.getField('人员');
+if (Base.isFieldOfType(userField, 'user')) {
+  const success = await userField.setValueAsync('rec123456', [{
+    userId: 'user123',
+  }, {
+    unionId: 'xxxxx',
+  }, {
+    jobNumber: 'staff123',
+  }, {
+    extContactUserId: 'xxxxx',
+  }]);
+  if (success) {
+    Output.log('向记录中更新了两名人员');
+  } else {
+    Output.log('记录更新失败');
+  }
+}
+
+```
+
+### 最佳实践
+
+以下示例展示如何在当前激活的数据表中新增一个人员字段，并创建一条记录写入当前用户信息。
+
+```typescript
+// script.ts - 服务层脚本
+async function addUserFieldWithCurrentUser() {
+  try {
+    const base = DingdocsScript.base;
+    
+    // 1. 获取当前用户信息
+    const currentUser = await base.getCurrentUser();
+    if (!currentUser) {
+      console.error('无法获取当前用户信息');
+      return { success: false, message: '无法获取当前用户信息' };
+    }
+    console.log(`当前用户: ${currentUser.name}`);
+
+    // 2. 获取当前激活的数据表
+    const activeSheet = base.getActiveSheet();
+    if (!activeSheet) {
+      console.error('当前没有激活的数据表，请先选中一个数据表');
+      return { success: false, message: '当前没有激活的数据表，请先选中一个数据表' };
+    }
+    console.log(`当前数据表: ${activeSheet.getName()}`);
+
+    // 3. 新增人员字段
+    const userFieldName = '负责人';
+    let userField = activeSheet.getField(userFieldName);
+    if (!userField) {
+      userField = activeSheet.insertField(userFieldName, 'user');
+      console.log(`已创建人员字段: ${userFieldName}`);
+    } else {
+      console.log(`人员字段已存在: ${userFieldName}`);
+    }
+
+    // 4. 插入一条记录，写入当前用户信息
+    const newRecords = await activeSheet.insertRecordsAsync([
+      {
+        fields: {
+          [userFieldName]: [{ unionId: currentUser.unionId }]
+        }
+      }
+    ]);
+
+    if (newRecords && newRecords.length > 0) {
+      console.log(`成功创建记录，ID: ${newRecords[0].getId()}`);
+      return { 
+        success: true, 
+        message: `已将当前用户 ${currentUser.name} 写入人员字段`,
+        recordId: newRecords[0].getId()
+      };
+    }
+    return { success: false, message: '创建记录失败' };
+  } catch (error) {
+    console.error(`执行失败: ${error instanceof Error ? error.message : '未知错误'}`);
+    return { success: false, message: error instanceof Error ? error.message : '未知错误' };
+  }
+}
+
+// 注册脚本函数
+DingdocsScript.registerScript('addUserFieldWithCurrentUser', addUserFieldWithCurrentUser);
+
+```
+```typescript
+async function addUserFieldWithCurrentUser() {
+  try {
+    // 1. 获取当前用户信息
+    const currentUser = await Base.getCurrentUser();
+    if (!currentUser) {
+      Output.error('无法获取当前用户信息');
+      return;
+    }
+    Output.log(`当前用户: ${currentUser.name}`);
+
+    // 2. 获取当前激活的数据表
+    const activeSheet = Base.getActiveSheet();
+    if (!activeSheet) {
+      Output.error('当前没有激活的数据表，请先选中一个数据表');
+      return;
+    }
+    Output.log(`当前数据表: ${activeSheet.getName()}`);
+
+    // 3. 新增人员字段
+    const userFieldName = '负责人';
+    let userField = activeSheet.getField(userFieldName);
+    if (!userField) {
+      userField = activeSheet.insertField(userFieldName, 'user');
+      Output.log(`已创建人员字段: ${userFieldName}`);
+    } else {
+      Output.log(`人员字段已存在: ${userFieldName}`);
+    }
+
+    // 4. 插入一条记录，写入当前用户信息
+    const newRecords = await activeSheet.insertRecordsAsync([
+      {
+        fields: {
+          [userFieldName]: [{ unionId: currentUser.unionId }]
+        }
+      }
+    ]);
+
+    if (newRecords && newRecords.length > 0) {
+      Output.log(`成功创建记录，ID: ${newRecords[0].getId()}`);
+      Output.log(`已将当前用户 ${currentUser.name} 写入人员字段`);
+    }
+  } catch (error) {
+    Output.error(`执行失败: ${error instanceof Error ? error.message : '未知错误'}`);
+  }
+}
+
+await addUserFieldWithCurrentUser();
+```
+
+**关键点说明**：
+
+*   **获取当前用户**：使用 `Base.getCurrentUser()` 或 `base.getCurrentUser()` 获取当前登录用户信息，返回 `UserCellValue` 对象
+    
+*   **检查激活表**：使用 `getActiveSheet()` 获取当前激活的数据表，若返回 `null` 则表示没有激活的表
+    
+*   **字段去重**：在创建字段前先检查是否已存在同名字段，避免重复创建
+    
+*   **写入用户值**：人员字段值为数组格式，支持通过 `userId` 或 `unionId` 指定用户

package/templates/support-qa/profiles/aitable/wiki/faq-support/18-/345/274/200/345/217/221/350/200/205/346/214/207/345/215/227/AI/350/241/250/346/240/274/345/257/271/350/261/241/346/250/241/345/236/213API/345/217/202/350/200/203/346/226/207/346/241/243/Field /346/250/241/345/235/227.md"

@@ -0,0 +1,379 @@
+# Field 模块
+
+Field 接口提供了操作数据表字段的方法，包括获取字段基本信息、修改字段属性以及操作字段值等功能。
+
+通常我们通过 [Sheet 模块](https://alidocs.dingtalk.com/i/nodes/y20BglGWOGQgpOj6uYQeAA3EWA7depqY?utm_scene=person_space) 创建或获取字段，如下所示：
+
+```typescript
+const singleSelectField = sheet.getField<SingleSelectField>(fieldNameOrId);
+```
+
+值得注意的是，我们在调用 `getField` 方法时传入了指定的类型 `<SingleSelectField>`，我们非常推荐这样的用法，通过这样的方法获取的 `Field`，会有足够的类型提示，例如我们可以很方便地为这个单选字段新增选项:
+
+```typescript
+singleSelectField.addOption('Option1');
+```
+
+除了设置字段的属性之外，我们也推荐开发者从字段角度来对值进行增删改查操作例如：
+
+```typescript
+await singleSelectField.setValueAsync(recordOrId, 'OptionId1');
+```
+
+在脚本插件中，由于脚本编辑语言为javascript，可以通过Base上提供的isFieldOfType进行类型推断：
+
+```typescript
+if (sheet)
+```
+
+详细用法可以点击具体字段类型模块中查看，如[文本字段](https://alidocs.dingtalk.com/i/nodes/QPGYqjpJYRyab0nxszLmaeDD8akx1Z5N?utm_scene=person_space)。
+
+:::
+本文子目录中包含了目前已经支持所有字段类型，本文的后续介绍了一些通用的方法
+:::
+
+## 基本信息方法
+
+### isValid
+
+检查当前字段对象是否有效。
+
+```typescript
+isValid: () => boolean
+
+```
+
+**返回值**
+
+*   `boolean` - 如果字段存在且有效返回true，否则返回false
+    
+
+**示例**
+
+```typescript
+if (field.isValid()) {
+  console.log('字段有效，可以进行操作');
+} else {
+  console.log('字段无效或已被删除');
+}
+
+```
+```typescript
+if (field.isValid()) {
+  Output.log('字段有效，可以进行操作');
+} else {
+  Output.log('字段无效或已被删除');
+}
+
+```
+
+### getSheetId
+
+获取字段所属数据表的ID。
+
+```typescript
+getSheetId: () => string
+
+```
+
+**返回值**
+
+*   `string` - 数据表ID
+    
+
+**示例**
+
+```typescript
+const sheetId = field.getSheetId();
+
+```
+
+### getId
+
+获取字段ID。
+
+```typescript
+getId: () => string
+
+```
+
+**返回值**
+
+*   `string` - 字段ID
+    
+
+**示例**
+
+```typescript
+const fieldId = field.getId();
+
+```
+
+### isPrimary
+
+当前字段对象是否为主键列。
+
+```typescript
+isPrimary: () => boolean
+
+```
+
+**返回值**
+
+*   `boolean` - 是否为主键
+    
+
+**示例**
+
+```typescript
+if(field.isPrimary()) {
+  console.log('当前字段为数据表主键');
+} else {
+  console.log('当前字段不是数据表主键')
+}
+
+```
+```typescript
+if(field.isPrimary()) {
+  Output.log('当前字段为数据表主键');
+} else {
+  Output.log('当前字段不是数据表主键')
+}
+
+```
+
+### getName
+
+获取字段名称。
+
+```typescript
+getName: () => string
+
+```
+
+**返回值**
+
+*   `string` - 字段名称
+    
+
+**示例**
+
+```typescript
+const fieldName = field.getName();
+
+```
+
+### setName
+
+设置字段名称。
+
+```typescript
+setName: (name: string) => Field<T>
+
+```
+
+**参数**
+
+*   `name`: `string` - 新的字段名称
+    
+
+**返回值**
+
+*   `Field`  - 字段对象本身，支持链式调用
+    
+
+**示例**
+
+```typescript
+// 修改字段名称
+field.setName('客户全名');
+
+// 链式调用
+field.setName('联系电话').getProperty();
+
+```
+
+**注意事项**
+
+*   不能修改从其他数据源同步的字段名称
+    
+*   字段名称在同一数据表中必须唯一
+    
+*   需要有字段更新权限
+    
+
+### getType
+
+获取字段类型。
+
+```typescript
+getType: () => FieldType
+
+```
+
+**返回值**
+
+*   [`FieldType`](https://alidocs.dingtalk.com/notable/record?dentryUuid=GZLxjv9VGGDA9Ro2u05KgqMnV6EDybno&rowId=7Gtfo83ZWU&sheetId=hERWDMS&viewId=qvGDAH2) - 字段类型
+    
+
+**示例**
+
+```typescript
+const fieldType = field.getType();
+console.log(`字段类型: ${fieldType}`);
+
+// 根据字段类型执行不同操作
+if (fieldType === 'singleSelect') {
+  console.log('这是一个单选字段');
+} else if (fieldType === 'date') {
+  console.log('这是一个日期字段');
+}
+
+```
+```typescript
+const fieldType = field.getType();
+console.log(`字段类型: ${fieldType}`);
+
+// 根据字段类型执行不同操作
+if (fieldType === 'singleSelect') {
+  console.log('这是一个单选字段');
+} else if (fieldType === 'date') {
+  console.log('这是一个日期字段');
+}
+
+```
+
+## 字段属性方法（不建议直接使用）
+
+### getProperty
+
+获取字段配置属性。
+
+```typescript
+getProperty: () => FieldProperty | undefined
+
+```
+
+**返回值**
+
+*   [`FieldProperty | undefined`](https://alidocs.dingtalk.com/notable/record?dentryUuid=GZLxjv9VGGDA9Ro2u05KgqMnV6EDybno&rowId=tguz2mP8WZ&sheetId=hERWDMS&viewId=qvGDAH2) - 字段的配置属性，不同类型的字段有不同的属性结构，具体可以参考[《字段数据结构》](https://alidocs.dingtalk.com/i/nodes/nYMoO1rWxmP7olkyF0kGwelwV47Z3je9?utm_scene=team_space&iframeQuery=anchorId%3Duu_mk4xf3z7pfeezmqbo5e)
+    
+
+**示例**
+
+```typescript
+const property = field.getProperty();
+
+// 对于数字字段，获取格式设置
+if (field.getType() === 'number') {
+  console.log(`数字格式: ${property.format}`);
+  console.log(`精度: ${property.precision}`);
+}
+
+```
+```typescript
+const property = field.getProperty();
+
+// 对于数字字段，获取格式设置
+if (field.getType() === 'number') {
+  Output.log(`数字格式: ${property.format}`);
+  Output.log(`精度: ${property.precision}`);
+}
+
+```
+
+### setPropertyAsync
+
+异步设置字段配置属性。
+
+```typescript
+setPropertyAsync: (property: FieldProperty) => Promise<Field<T>>
+```
+
+**参数**
+
+`property`\- [`FieldProperty`](https://alidocs.dingtalk.com/notable/record?dentryUuid=GZLxjv9VGGDA9Ro2u05KgqMnV6EDybno&rowId=tguz2mP8WZ&sheetId=hERWDMS&viewId=qvGDAH2) 字段的新配置属性
+
+根据字段类型不同，支持传入的字段属性结构也不同，具体可以参考[《字段数据结构》](https://alidocs.dingtalk.com/i/nodes/nYMoO1rWxmP7olkyF0kGwelwV47Z3je9?utm_scene=team_space&iframeQuery=anchorId%3Duu_mk4xf3z7pfeezmqbo5e)
+
+**返回值**
+
+*   `Promise<Field<T>>` - 字段对象本身，支持链式调用
+    
+
+**示例**
+
+```typescript
+// 修改数字字段的格式
+if (field.getType() === 'number') {
+  await field.setPropertyAsync({
+    formatter: 'FLOAT_1'
+  })
+}
+
+```
+
+**注意事项**
+
+*   不同类型的字段有不同的属性结构
+    
+*   某些字段属性修改可能需要更新整列数据，会触发数据加载
+    
+*   需要有字段更新权限
+    
+
+## 记录方法
+
+### getFieldValuesAsync
+
+分页获取整列字段值。
+
+```typescript
+getFieldValuesAsync: (options?: GetFieldValuesOptions) => Promise<PagedFieldValues<T> | null>;
+```
+
+**参数**
+
+`options`\- [`GetFieldValuesOptions`](https://alidocs.dingtalk.com/notable/record?dentryUuid=GZLxjv9VGGDA9Ro2u05KgqMnV6EDybno&rowId=kStgmhj5zj&sheetId=hERWDMS&viewId=qvGDAH2) 可选项，分页获取参数
+
+**返回值**
+
+*   [`Promise<PagedFieldValues<T> | null>`](https://alidocs.dingtalk.com/notable/record?dentryUuid=GZLxjv9VGGDA9Ro2u05KgqMnV6EDybno&rowId=4sBB3qX3SZ&sheetId=hERWDMS&viewId=qvGDAH2) - 分页获取结果
+    
+
+**示例**
+
+```typescript
+const result = await field.getFieldValuesAsync({
+  pageSize: 20,
+});
+if (result) {
+  const { fieldValues, hasMore, cursor, total } = result;
+}
+```
+
+## 类型化字段
+
+Field类支持泛型，可以获取特定类型的字段:
+
+```typescript
+// 获取特定类型的字段
+const selectField = sheet.getField<SelectField>('状态');
+if (selectField) {
+  // 可以使用SelectField特有的方法
+  const options = selectField.getOptions();
+}
+
+const numberField = sheet.getField<NumberField>('金额');
+if (numberField) {
+  // 可以使用NumberField特有的方法
+  const format = numberField.getFormat();
+}
+
+```
+
+**注意事项**
+
+*   确保获取的字段类型与指定泛型匹配，否则可能导致运行时错误
+    
+*   当不确定字段类型时，可以先通过getType()方法判断