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/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"

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

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

@@ -0,0 +1,331 @@
+# 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**`**)** 的表单项都能在上下文中找到对应值并成功填充时，表单才会自动提交。如果任一必填项无法自动填充（例如表单中还包含一个需要用户手动输入的文本框），则表单面板会正常弹出，已识别的项会预先填入，等待用户完成剩余输入后手动提交。
+
+通过这种机制，可以编写出既支持手动运行（用户选表选记录），又支持按钮字段快捷操作（自动定位当前记录）的通用脚本。