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/350/204/232/346/234/254/346/217/222/344/273/266 /345/274/200/345/217/221/346/214/207/345/215/227/Field /346/250/241/345/235/227.md" DELETED Viewed

@@ -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()方法判断

@@ -1,331 +0,0 @@
-# Input模块
-# Input 模块
-支持在运行页面中创建交互式UI，等待用户输入后执行后续步骤。每个交互式输入法都是异步的，因此调用此API时需要使用`await`表达式。
-### textAsync
-在运行插件面板插入一个输入框，等待用户输入完毕后执行后续操作。
-```typescript
-textAsync: (label: string, config?: InputConfig<string>) => Promise<string>;
-```
-**参数**
-*   `label`: `string` - 输入框标题
-*   `config`: `InputConfig<string>` - 配置参数，详细见后文[《Input模块》](https://alidocs.dingtalk.com/i/nodes/3NwLYZXWyrmRolXLcYE0oX7aVkyEqBQm?utm_scene=team_space&iframeQuery=anchorId%3Duu_mmiv2vbfh6belccm86f)
-**返回值**
-*   `Promise<string>` - 用户输入并提交后返回的输入结果
-**示例**
-```typescript
-const userInput = await Input.textAsync("请输入一段内容");
-Output.info('用户输入的内容为', userInput);
-```
-![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/pLdn55XMvyeMyno8/img/f9995ccb-041f-4bd7-990f-fe08d1f3ce5e.png)
-### selectAsync
-在运行插件面板插入一个选择器，显示一组按钮，等待用户点击后执行后续操作。
-```typescript
-selectAsync: <V = unknown>(label: string, options: Array<string | SelectOption<V>>, config: InputConfig<string | V | undefined>) => Promise<string | V | undefined>;
-interface SelectOption<V> {
-  /** 选项展示的文本 */
-  text: string;
-  /** 选项值 */
-  value: V;
-}
-```
-**参数**
-*   `label`: `string` - 选择器标题
-*   `options`: `Array<string | SelectOption>`选项配置，支持设置字符串格式的选项，或同时配置选项的文案和实际值。
-*   `config`: `InputConfig<string | V | undefined>` - 配置参数，详细见后文[《Input模块》](https://alidocs.dingtalk.com/i/nodes/3NwLYZXWyrmRolXLcYE0oX7aVkyEqBQm?utm_scene=team_space&iframeQuery=anchorId%3Duu_mmiv2vbfh6belccm86f)
-**返回值**
-*   `Promise<string | V | undefined>` - 用户点击按钮后返回的结果
-**示例**
-```typescript
-const userInput = await Input.selectAsync('请选择答案', ['A', 'B', 'C', 'D']);
-Output.info('用户选择的答案为', userInput);
-```
-![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/pLdn55XMvyeMyno8/img/fb8a8701-ca5a-40d7-ae7e-5a595bb7153d.png)
-### formAsync
-在运行面板中插入一个表单，等待用户提交后执行后续操作
-```typescript
-formAsync: (title: string, items: FormItem[], config?: InputConfig<Record<FormItemKey, FormItemResult | undefined>>) => Promise<Record<FormItemKey, FormItemResult | undefined>>;
-/** 表单项的唯一标识 */
-type FormItemKey = string;
-type FormItem = {
-  /** 表单项唯一标识 */
-  key: FormItemKey;
-  /** 表单项是否为必填项，默认为 true */
-  required?: boolean;
-} & (
-  | SheetFormItem
-  | FieldFormItem
-  | ViewFormItem
-  | RecordFormItem
-  | TextFormItem
-  | NumberFormItem
-  | SelectFormItem
-);
-/** 数据表表单项 */
-interface SheetFormItem {
-  type: 'sheet';
-  option: {
-    /** 表单项的标题（可选，为空时默认以 key 作为标题） */
-    label?: string;
-    /** 表单项的描述说明（可选） */
-    description?: string;
-  };
-}
-/** 字段表单项 */
-interface FieldFormItem {
-  type: 'field';
-  option: {
-    label?: string;
-    description?: string;
-    /** 字段所属的数据表表单项唯一标识 */
-    referenceSheet: FormItemKey;
-  };
-}
-/** 视图表单项 */
-interface ViewFormItem {
-  type: 'view';
-  option: {
-    label?: string;
-    description?: string;
-    /** 视图所属的数据表表单项唯一标识 */
-    referenceSheet: FormItemKey;
-  };
-}
-/** 记录表单项 */
-interface RecordFormItem {
-  type: 'record';
-  option: {
-    label?: string;
-    description?: string;
-    /** 记录所属的数据表表单项唯一标识 */
-    referenceSheet: FormItemKey;
-  };
-}
-/** 文本输入框表单项 */
-interface TextFormItem {
-  type: 'text';
-  option: {
-    label?: string;
-    description?: string;
-  };
-}
-/** 数字输入框表单项 */
-interface NumberFormItem {
-  type: 'number';
-  option: {
-    label?: string;
-    description?: string;
-  };
-}
-/** 选择器表单项 */
-interface SelectFormItem {
-  type: 'select';
-  option: {
-    label?: string;
-    description?: string;
-    options: Array<string | SelectOption<unknown>>;
-  };
-}
-type FormItemResult =
-  | Sheet      /** 数据表 */
-  | Field      /** 字段 */
-  | View       /** 视图 */
-  | string     /** 文本输入框返回结果 */
-  | number     /** 数字输入框返回结果 */
-  | unknown;   /** 选择器返回结果 */
-type FormItemResult =
-  Sheet /** 数据表 */ |
-  Field /** 字段 */ |
-  View /** 视图 */ |
-  string /** 文本输入框返回结果 */ |
-  number /** 数字输入框返回结果 */ |
-  unknown /** 选择器返回结果 */;
-```
-**参数**
-*   `title`: `string` - 表单标题
-*   `item`: `FormItem[]`表单项。
-*   `config`: `InputConfig<Record<FormItemKey, FormItemResult | undefined>>` - 配置参数，详细见后文[《Input模块》](https://alidocs.dingtalk.com/i/nodes/3NwLYZXWyrmRolXLcYE0oX7aVkyEqBQm?utm_scene=team_space&iframeQuery=anchorId%3Duu_mmiv2vbfh6belccm86f)
-**返回值**
-*   `Promise<Record<FormItemKey, FormItemResult | undefined>>` - 用户点击提交后返回的结果
-**示例**
-```typescript
-const formResult = await Input.formAsync('请填写表单', [{
-    type: 'sheet',
-    key: 'sheet',
-    option: {
-        label: '选择一张数据表',
-    },
-    required: true,
-}, {
-    type: 'field',
-    key: 'field',
-    option: {
-        label: '选择一个字段',
-        description: '字段来自于上方选择的数据表',
-        referenceSheet: 'sheet',
-    },
-    required: false,
-}, {
-    type: 'text',
-    key: 'text',
-    option: {
-        label: '请输入文本',
-    },
-    required: true,
-}, {
-    type: 'number',
-    key: 'number',
-    option: {
-        label: '请输入数字',
-    },
-    required: true,
-}, {
-    type: 'select',
-    key: 'select',
-    option: {
-        label: '请选择选项',
-        options: ['1', '2', '3'],
-    },
-}]);
-Output.table(formResult);
-```
-![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/pLdn55XMvyeMyno8/img/a84f21dd-da0a-4351-810e-0a5c0a69046e.png)
-### 入参校验
-`textAsync`、`selectAsync`、`formAsync` 均支持传入可选的 `config` 参数，用于对用户输入进行校验。校验不通过时，会在输入框下方展示错误信息，阻止用户提交，直到校验通过为止。
-```typescript
-interface InputConfig<T> {
-  /**
-   * 校验函数，接收用户输入值，返回校验结果。
-   * 支持同步或异步校验。
-   */
-  validate?: (response: T) => ValidationResult | Promise<ValidationResult>;
-}
-type ValidationResult =
-  | { valid: true }
-  | { valid: false; error: string };
-```
-**示例**
-```typescript
-// 校验用户输入不能为空
-const userInput = await Input.textAsync('请输入内容', {
-  validate: (value) => {
-    if (!value || value.trim() === '') {
-      return { valid: false, error: '内容不能为空' };
-    }
-    return { valid: true };
-  },
-});
-// 异步校验：检查输入值是否已存在
-const name = await Input.textAsync('请输入名称', {
-  validate: async (value) => {
-    const exists = await checkNameExists(value);
-    if (exists) {
-      return { valid: false, error: '该名称已存在，请重新输入' };
-    }
-    return { valid: true };
-  },
-});
-```
-# 按钮字段触发脚本
-脚本可以通过两种方式启动：
-1.  **直接运行**：在脚本面板中点击运行。
-2.  **按钮字段触发**：点击数据表中的按钮字段按钮运行。
-当通过 **按钮字段** 触发脚本时，`formAsync` 方法会自动识别当前的上下文（即点击按钮所在的行记录），并尝试自动填充表单中对应的内容。
-### 自动填充规则
-如果 `formAsync` 的表单项满足以下条件，将会被自动填充并直接提交，无需用户手动操作：
-1.  **Sheet 类型**
-    *   会自动填充为当前 Button 字段所在的数据表。
-2.  **View 类型**
-    *   需配置 `referenceSheet` 指向上述自动填充的 Sheet 表单项。
-    *   会自动填充为当前所在的视图。
-3.  **Record 类型**
-    *   需配置 `referenceSheet` 指向上述自动填充的 Sheet 表单项。
-    *   会自动填充为当前点击 Button 的那一行记录。
-    *   如果配置了 `referenceView`，则也会校验当前记录是否在该视图内。
-**注意**：只有当所有 **必填 (**`**required: true**`**)** 的表单项都能在上下文中找到对应值并成功填充时，表单才会自动提交。如果任一必填项无法自动填充（例如表单中还包含一个需要用户手动输入的文本框），则表单面板会正常弹出，已识别的项会预先填入，等待用户完成剩余输入后手动提交。
-通过这种机制，可以编写出既支持手动运行（用户选表选记录），又支持按钮字段快捷操作（自动定位当前记录）的通用脚本。