npm - aitable-workflow-cli - Versions diffs - 0.1.15 → 0.1.16-beta.1786022310508 - Mend

aitable-workflow-cli 0.1.15 → 0.1.16-beta.1786022310508

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (263) hide show

package/templates/aitable-handoff/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" DELETED Viewed

@@ -1,266 +0,0 @@
-# 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` 指定用户

@@ -1,379 +0,0 @@
-# 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()方法判断