# 金山多维表格 AirScript 文档

> **来源**: [WPS 开放平台 AirScript 文档](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/AirScript/AirScript-instro)
> **抓取时间**: 2026-03-08

---

## 目录

1. [AirScript 简介](#1-airscript-简介)
2. [快速入门](#2-快速入门)
3. [内置基础类型](#3-内置基础类型)
4. [脚本经典案例](#4-脚本经典案例)
5. [API 文档 — 数据表 (Sheets)](#5-api-文档--数据表-sheets)
6. [API 文档 — 字段 (Field / FieldDescriptor)](#6-api-文档--字段-field--fielddescriptor)
7. [API 文档 — 记录 (Record)](#7-api-文档--记录-record)
8. [API 文档 — 视图 (View)](#8-api-文档--视图-view)
9. [API 文档 — 其他](#9-api-文档--其他)

---

## 1. AirScript 简介

**在线文档**: [AirScript-instro](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/AirScript/AirScript-instro)

AirScript 是一个简单快速的轻量级脚本应用开发平台，致力于为 WPS 核心组件提供更为强大的效率工具能力。通过 AirScript，开发者可以利用 JavaScript 语言编写处理逻辑，实现文档处理的自动化。

### AirScript 能做什么

AirScript 为用户和开发者提供了轻便的脚本运行环境、多端运行的能力以及丰富的 API 接口：

- **无需搭建本地环境**：脚本编辑器随开随用，无需安装配置复杂的本地开发环境。
- **多端一致的运行体验**：编写一次脚本，可直接在 Web、桌面端（Windows/Mac）以及移动端运行。
- **内置定制化的全局 Application 对象**：通过简单直观的 Application 对象，直接操作表格数据。
- **同步获取属性**：AirScript 提供的 API 支持同步获取属性和设置值，代码逻辑更加简洁高效。
- **得益于集成化开发环境**：支持代码高亮、智能提示、在线调试等功能。

### 如何使用 AirScript

AirScript 可在 WPS 多维表格中通过多种方式触发运行：

1. **编辑器手动运行**：点击顶部菜单「效率」→「AirScript 脚本编辑器」，在打开的窗口中编写代码并点击运行。
2. **按钮触发**：在多维表格中添加「按钮」字段，并在其设置中选择点击按钮时「执行 AirScript 脚本」。
3. **自动化流程触发**：在多维表格的自动化流程配置中，添加操作「执行以下操作」→「执行 AirScript 脚本」，并选择对应的脚本文件及配置参数。

---

## 2. 快速入门

**在线文档**: [AirScript-quickstart](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/AirScript/AirScript-quickstart)

### 在 AirScript 编辑器中运行

在金山文档首页新建一个 WPS 多维表格并打开来体验 AirScript。打开 WPS 多维表格，点击「脚本」-「JS脚本」下的「新建脚本」，点击即可调起 AirScript 编辑器。

#### 示例 1：Hello World

```javascript
function main(){
    console.log("hello world!")
}
main()
```

#### 示例 2：操作工作表与单元格

```javascript
function main(){
    // 遍历并打印所有工作表的名称
    let sheets = Application.Sheets
    for (let i = 0; i < sheets.Count; i++) {
        let sheet = sheets.Item(i + 1)
        console.log(sheet.Name)
    }
    const sheet = Application.Selection.GetActiveSheet()
    // 打印当前激活Sheet的名称
    console.log(sheet.name)
    // 打印单元格内容
    console.log(Application.ActiveView.RecordRange(1, 1).Text)
    // 修改单元格内容
    Application.ActiveView.RecordRange(1, 1).Value = 2;
    // 打印修改后的单元格内容
    console.log(Application.ActiveView.RecordRange(1, 1).Text)
}
main()
```

### 在自动化流程中运行

1. 点击「自动化」-「新建自动化」，添加「执行AirScript脚本」操作，点击「管理脚本」-「新建脚本」进入脚本编辑器即可。
2. 在脚本中获取到传递的参数进行开发使用：

```javascript
// 通过 Context.argv 获取入参
console.log("脚本入参: ", Context.argv);
console.log("脚本入参p1: ", Context.argv.p1);
```

更多自动化请查看 [执行AirScript脚本操作使用指南](https://kdocs.cn/l/cdQOqc6TZuMk)

---

## 3. 内置基础类型

**在线文档**: [AirScript-build-in](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/AirScript/AirScript-build-in)

内置的基本数据类型、对象和函数用来帮助开发者开发，遵循 JavaScript 函数命名的标准规范，同时不能和 OpenApi 提供对象重名。

### 基本数据类型

| 类型 | 说明 |
|------|------|
| Boolean | 布尔值 |
| Null | 空值 |
| Undefined | 未定义 |
| Number | 数字 |
| String | 字符串 |

### 内置对象

| 对象 | 说明 |
|------|------|
| Object | 基础对象 |
| Array | 数组 |
| Function | 函数 |
| Date | 日期 |
| RegExp | 正则表达式 |
| JSON | JSON 处理 |
| Math | 数学计算 |
| Number | 数字对象 |
| String | 字符串对象 |
| Map / Set | 集合 |
| Promise | 异步处理 |

### 全局对象与函数

- **console**: 日志输出，支持 `.log`, `.info`, `.warn`, `.error`, `.time`, `.timeEnd`
- **fetch**: 网络请求
- **常用函数**: `parseInt`, `parseFloat`, `isNaN`, `isFinite`, `decodeURI`, `encodeURI` 等

### 高级内置服务

#### Crypto — 加密服务

```javascript
// Hash 计算
Crypto.hash("md5", "hello")       // 支持: md5, sha1, sha256
Crypto.hash("sha256", "data")

// HMAC 计算
Crypto.hmac("hmac-sha1", "key", "data")     // 支持: hmac-sha1, hmac-sha256
Crypto.hmac("hmac-sha256", "secretKey", "message")
```

#### Buffer — 二进制数据处理

```javascript
// 创建 Buffer
Buffer.from("hello", "text")     // 支持编码: text, base64, hex
Buffer.from("aGVsbG8=", "base64")

// 转换输出
let buf = Buffer.from("hello", "text")
buf.toString("base64")   // 输出 base64 编码
buf.toString("hex")      // 输出 hex 编码
```

#### Time — 时间服务

```javascript
Time.sleep(1000)    // 睡眠 1000 毫秒
Time.now()          // 获取当前纳秒时间
```

#### Arguments — 脚本执行参数

```javascript
// 获取脚本执行参数（自动化流程传参时使用）
let args = Context.argv
console.log(args)
```

---

## 4. 脚本经典案例

**在线文档**: [AirScript-demo](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/AirScript/AirScript-demo)

### 案例 1：选中区域快速批量填值

通过 `Selection` 获取当前选区并循环填入指定值。

```javascript
function main() {
  const range = Application.Selection.Range;
  for (let i = 1; i <= range.Rows.Count; i++) {
    for (let j = 1; j <= range.Columns.Count; j++) {
      range.Rows(i).Columns(j).Value = "待处理";
    }
  }
}
```

### 案例 2：快速实现"一键归档"

根据状态字段（如"已完成"）将记录从当前表移动到归档表。

```javascript
// 核心逻辑：获取符合条件的记录范围
// 然后执行 AddRecords 并 DeleteRecords
function main() {
  const activeSheet = Application.Selection.GetActiveSheet();
  const archiveSheet = Application.Sheets.Item("归档表");
  // 遍历记录，筛选状态为"已完成"的记录
  // 将其添加到归档表并从原表删除
}
```

### 案例 3：快速删除空白数据

自动识别并删除关键字段为空的行。

### 案例 4：快速创建一张表

使用 `Application.Sheets.Add()` 动态创建新表并定义字段结构。

```javascript
function main() {
  Application.Sheets.Add("新表名", {
    Fields: [
      { Name: "姓名", Type: "Text" },
      { Name: "年龄", Type: "Number" }
    ]
  });
}
```

### 案例 5：格式化数据批量插入

将外部 JSON 或格式化字符串批量导入到多维表格中。

### 案例 6：自动双向关联

当 A 表关联 B 表时，脚本自动反向设置 B 表关联 A 表，保持数据同步。

### 案例 7：同步主表数据到其他表

实现跨表的数据联动，当主表更新时，自动更新关联表中的冗余字段。

### 案例 8：获取日期筛选后记录

利用 `RecordRange.Condition` 配合日期函数进行条件筛选。

### 案例 9：获取联系人筛选后记录

筛选特定负责人或创建人的记录信息。

### 案例 10：批量将获取的图片 URL 进行文字识别 (OCR)

调用百度云 OCR 接口，识别表中附件字段的图片内容并将文字回填。

```javascript
const access_token = "xxxxxx";
function main() {
  const view = Application.ActiveSheet.Views(1);
  const attachments = view.RecordRange('1:' + view.RecordRange.Count, ["@图片和附件"]).Value;
  // 调用 fetch 请求 OCR 接口并将结果回填
}
```

---

## 5. API 文档 — 数据表 (Sheets)

### 5.1 Application.Sheets

全局入口，获取当前文档中所有数据表的集合。

```javascript
const sheets = Application.Sheets;
```

### 5.2 Sheets.Count — 获取数据表总数

**在线文档**: [Sheets_Count](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/Sheets_Count)

```javascript
const count = Application.Sheets.Count;
console.log("共有 " + count + " 张数据表");
```

**返回值**: `Number` — 数据表数量

### 5.3 Sheets.Item(Index) — 获取指定数据表

**在线文档**: [Sheets_Item](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/Sheets_Item)

**语法**: `Application.Sheets.Item(Index)`

**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| Index | Number / String | 数据表的索引（从 1 开始）或名称 |

**示例**:

```javascript
// 通过索引获取
const sheet = Application.Sheets.Item(1);

// 通过名称获取
const sheet = Application.Sheets.Item("项目基本信息表");
```

**返回值**: `Sheet` 对象

### 5.4 Sheets.Add() — 新建数据表

**在线文档**: [Sheets_Add](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/Sheets_Add)

**语法**: `Application.Sheets.Add(Name, Options)`

**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| Name | String | 新表的名称 |
| Options | Object | 可选，包含 Fields 数组来初始化表结构 |

**示例**:

```javascript
Application.Sheets.Add("新表名", {
  Fields: [
    { Name: "姓名", Type: "Text" },
    { Name: "年龄", Type: "Number" },
    { Name: "状态", Type: "SingleSelect" }
  ]
});
```

**返回值**: 新创建的 `Sheet` 对象

### 5.5 Sheet 对象属性

#### Sheet.Name — 获取/设置表名

**在线文档**: [Sheet_Name](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/Sheet_Name)

```javascript
const sheet = Application.Sheets.Item(1);
// 获取表名
console.log(sheet.Name);
// 修改表名
sheet.Name = "新表名";
```

#### Sheet.Id — 获取表 ID

**在线文档**: [Sheet_Id](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/Sheet_Id)

```javascript
const sheet = Application.Sheets.Item(1);
console.log(sheet.Id);  // 返回该数据表的唯一数字 ID
```

**返回值**: `Number` — 数据表唯一 ID

---

## 6. API 文档 — 字段 (Field / FieldDescriptor)

### 6.1 Sheet.FieldDescriptors — 获取所有字段描述符

**在线文档**: [FieldDescriptors](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/FieldDescriptors)

获取指定数据表的所有字段描述信息集合。

```javascript
const sheet = Application.Sheets.Item(1);
const descriptors = sheet.FieldDescriptors;

// 获取字段总数
console.log(descriptors.Count);
```

**属性**:
| 属性 | 类型 | 说明 |
|------|------|------|
| Count | Number | 字段总数 |

**方法**:
| 方法 | 说明 |
|------|------|
| Item(Index) | 获取指定序号的字段描述（从 1 开始） |

### 6.2 FieldDescriptors.Item(Index) — 获取单个字段描述

**在线文档**: [FieldDescriptors_Item](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/FieldDescriptors_Item)

**语法**: `表达式.Item(Index)` 或 `表达式(Index)`

**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| Index | Number / String | 字段索引（从 1 开始）或字段名称（以 `@` 前缀） |

**示例**:

```javascript
const sheet = Application.Sheets.Item(1);
const descriptors = sheet.FieldDescriptors;

// 通过索引获取
const field1 = descriptors.Item(1);
console.log(field1.name);  // 字段名
console.log(field1.type);  // 字段类型

// 通过名称获取
const field2 = descriptors.Item("@项目名称");
console.log(field2.type);
```

**返回值**: `FieldDescriptor` 对象

### 6.3 FieldDescriptor 对象

**在线文档**: [FieldDescriptor](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/FieldDescriptor)

用于描述字段的属性（如类型）。修改后需调用 `.Apply()` 方法才能生效。

**属性**:
| 属性 | 类型 | 说明 |
|------|------|------|
| name | String | 字段名称 |
| type | String | 字段类型 |

**方法**:
| 方法 | 说明 |
|------|------|
| Apply() | 应用对字段描述的修改 |

### 6.4 Field 对象

**在线文档**: [Field](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/Field)

代表视图中呈现的字段实例。

**属性**:
| 属性 | 类型 | 说明 |
|------|------|------|
| Id | Number | 字段唯一 ID |
| Name | String | 字段名称 |
| Type | String | 字段类型 |
| Width | Number | 字段宽度 |

### 6.5 字段类型 (Field Type) 枚举

以下是创建字段时支持的类型值：

| 类型值 | 说明 |
|--------|------|
| `Text` / `MultiLineText` | 多行文本 |
| `Number` | 数字 |
| `SingleSelect` | 单选 |
| `MultipleSelect` | 多选 |
| `Date` / `DateTime` | 日期 / 日期时间 |
| `Checkbox` | 复选框 |
| `Attachment` | 附件 |
| `Link` | 关联（外键关联其他表） |
| `Url` | 超链接 |
| `Phone` | 电话 |
| `Email` | 邮箱 |
| `AutoNumber` | 自动编号 |
| `Contact` | 成员/联系人 |
| `Formula` | 公式 |
| `CreatedTime` | 创建时间 |
| `ModifiedTime` | 修改时间 |
| `CreatedBy` | 创建人 |
| `ModifiedBy` | 修改人 |

> **注意**: 使用 `Application.Sheet.CreateSheet()` 创建表时的字段类型值可能与此处略有不同。
> 请参考创建表的 API 文档确认有效值。

---

## 7. API 文档 — 记录 (Record)

### 7.1 RecordRange — 获取记录范围

通过视图对象访问记录：

```javascript
const view = Application.ActiveSheet.Views(1);
// 获取单个记录的单元格值
const value = view.RecordRange(1, 1).Text;

// 获取记录范围
const range = view.RecordRange('1:10', ["@字段名"]);
```

### 7.2 Record 操作示例

```javascript
// 获取当前选中的表
const sheet = Application.Selection.GetActiveSheet();

// 读取数据
const view = sheet.Views(1);
const count = view.RecordRange.Count;
console.log("记录总数: " + count);

// 修改单元格
view.RecordRange(1, 1).Value = "新值";

// 批量读取
for (let i = 1; i <= count; i++) {
  console.log(view.RecordRange(i, 1).Text);
}
```

---

## 8. API 文档 — 视图 (View)

### 8.1 获取视图

```javascript
// 获取当前活跃视图
const activeView = Application.ActiveView;

// 通过 Sheet 的 Views 集合获取
const sheet = Application.Sheets.Item(1);
const view = sheet.Views(1);  // 索引从 1 开始
```

### 8.2 Selection — 选区对象

```javascript
const selection = Application.Selection;

// 获取当前选中的 Sheet
const sheet = selection.GetActiveSheet();

// 获取选中范围
const range = selection.Range;
```

---

## 9. API 文档 — 其他

### 9.1 Application.Sheet.CreateSheet() — 创建表 (REST API 风格)

> **注意**: 此方法与 `Application.Sheets.Add()` 不同，使用了 REST API 风格的调用方式。

```javascript
var sheet = Application.Sheet.CreateSheet({
  Name: '表名',
  Views: [{ name: '默认视图', type: 'Grid' }],
  Fields: [
    { name: '字段1', type: 'MultiLineText' },
    { name: '状态', type: 'SingleSelect', items: [
      { value: '选项1' }, { value: '选项2' }
    ] },
    { name: '日期', type: 'Date' },
    { name: '数字', type: 'Number' },
    { name: '复选', type: 'Checkbox' },
    { name: '附件', type: 'Attachment' },
    { name: '链接', type: 'Url' },
    { name: '电话', type: 'Phone' },
    { name: '自动编号', type: 'AutoNumber' },
    { name: '成员', type: 'Contact', multipleContacts: false, noticeNewContact: false }
  ]
});
var sheetId = sheet.id;
```

### 9.2 Application.Field.CreateFields() — 创建字段

```javascript
Application.Field.CreateFields({
  SheetId: sheetId,
  Fields: [
    { name: '关联字段', type: 'Link', linkSheet: targetSheetId, multipleLinks: false }
  ]
});
```

### 9.3 Application.Field.GetFields() — 获取字段信息

```javascript
var fields = Application.Field.GetFields({
  SheetId: sheetId
});
// fields 返回该表的所有字段详细信息
console.log(JSON.stringify(fields, null, 2));
```

### 9.4 HTTP / fetch — 网络请求

```javascript
// 使用 fetch 发起 HTTP 请求
const response = fetch("https://api.example.com/data", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ key: "value" })
});
console.log(response.json());
```

### 9.5 console — 日志输出

```javascript
console.log("普通日志");
console.info("信息日志");
console.warn("警告日志");
console.error("错误日志");

// 计时
console.time("操作耗时");
// ... 执行操作 ...
console.timeEnd("操作耗时");
```

---

## 附录 A: 常用代码片段

### A.1 遍历所有表并打印表名

```javascript
const sheets = Application.Sheets;
for (let i = 1; i <= sheets.Count; i++) {
  const sheet = sheets.Item(i);
  console.log(i + ". " + sheet.Name + " (Id: " + sheet.Id + ")");
}
```

### A.2 获取指定表的所有字段信息

```javascript
const sheet = Application.Sheets.Item("项目基本信息表");
const descriptors = sheet.FieldDescriptors;
for (let i = 1; i <= descriptors.Count; i++) {
  const fd = descriptors.Item(i);
  console.log(fd.name + " → " + fd.type);
}
```

### A.3 导出所有表结构为 JSON

```javascript
var result = [];
var sheets = Application.Sheets;
for (var i = 1; i <= sheets.Count; i++) {
  var sheet = sheets.Item(i);
  var fields = [];
  var descriptors = sheet.FieldDescriptors;
  for (var j = 1; j <= descriptors.Count; j++) {
    var fd = descriptors.Item(j);
    fields.push({ name: fd.name, type: fd.type });
  }
  result.push({
    tableName: sheet.Name,
    sheetId: sheet.Id,
    fieldCount: fields.length,
    fields: fields
  });
}
console.log(JSON.stringify(result, null, 2));
```

### A.4 获取环境信息

```javascript
// 当前激活的表
console.log("当前表: " + Application.Selection.GetActiveSheet().Name);

// 当前文档中的所有表
var sheets = Application.Sheets;
console.log("表数量: " + sheets.Count);
```

---

## 附录 B: 文档链接索引

| 章节 | 在线链接 |
|------|---------|
| AirScript 简介 | [链接](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/AirScript/AirScript-instro) |
| 快速入门 | [链接](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/AirScript/AirScript-quickstart) |
| 内置基础类型 | [链接](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/AirScript/AirScript-build-in) |
| 脚本经典案例 | [链接](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/AirScript/AirScript-demo) |
| API: Sheets.Add | [链接](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/Sheets_Add) |
| API: Sheets.Item | [链接](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/Sheets_Item) |
| API: Sheet.Name | [链接](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/Sheet_Name) |
| API: Sheet.Id | [链接](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/Sheet_Id) |
| API: FieldDescriptors | [链接](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/FieldDescriptors) |
| API: FieldDescriptors.Item | [链接](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/FieldDescriptors_Item) |
| API: FieldDescriptor | [链接](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/FieldDescriptor) |
| API: Field | [链接](https://365.kdocs.cn/3rd/open/documents/app-integration-dev/guide/dbsheet/Api/Field) |
