问 WPS 多维表AirScript API与HTTP API比较与分析

Lv.2潜力创作者

一、AirScript：文档内部的脚本 API

用户用 WPS 多维表管理数据时，常需要执行重复性操作：每周新建同样结构的数据表、批量更新字段、定时整理记录。手动操作费时费力，在AirScript脚本编辑器中编写代码并运行，可以实现多维表的自动化操作。

但AirScript只能在本文档的脚本编辑器中运行，无法在文档外部执行。比如外部系统数据批量导入多维表，有以下途径：①浏览器扩展/油猴脚本；②浏览器自动化工具（如 Playwright）；③开发者工具中的CDP调试协议。但它们都在文档页面之外运行，要想实现自动化操作，要么调用 AirScript-Token，要么通过网页发送 HTTP 请求。

二、HTTP API：文档外部的请求接口

HTTP API 有两个入口：

入口 A：V7 REST（功能完整）

地址格式：api.wps.cn/v7/dbsheet/{fileId}/sheets

覆盖数据表、记录、字段、视图的全部操作（增删改查都支持）

每次请求需要带上认证令牌（从浏览器登录态中提取的一串字符串）

入口 B：core/execute 网关（轻量便捷）

地址格式：www.kdocs.cn/api/v3/office/file/{fileId}/core/execute

和文档页面在同一个网站域下，油猴脚本设置 credentials: 'include' 就能自动携带登录 Cookie，无需手动传令牌

能力有限：不支持创建记录、不支持创建视图

能力边界如下：

操作	AirScript	HTTP API
查询结构（表/字段/视图）	✅	✅
创建/删除数据表	✅	✅
创建/更新/删除字段	✅	✅
查询记录	✅	✅
创建/更新/删除记录	✅	仅 V7 REST 支持
创建视图	✅	仅 V7 REST 支持
更新/删除视图	✅	✅
是否需要手动处理认证	不需要（文档内自带登录态）	core/execute：不需要（自动带 Cookie） V7 REST：需要（手动传令牌）

AirScript 功能最全，但只能在文档脚本编辑器内用。V7 REST什么都能做，但调用门槛高，每次要传令牌。core/execute 用起来方便但能力受限，只适合做查询和结构管理（建表、改字段）。

选择的关键在于"代码在哪里运行"。

你的场景	推荐方案	理由
在表格内部可闭环的自动化任务（按钮点击、定时运行、表单提交后处理）	AirScript	对象模型直观，全功能覆盖，不用处理 HTTP。
用油猴脚本在页面加载时自动操作	core/execute	自动带登录态，适合查询和结构管理。如需写入记录或创建视图，可调用AirScript 脚本。
用 Playwright / CDP 做自动化测试或批量处理	V7 REST	全功能覆盖，适合独立于浏览器的后端处理。需要从浏览器提取认证令牌后手动传入。

如果需要在外部写入数据并操作多维表，要么用V7 REST，要么调用 AirScript-Token。

三、操作对比

同一操作在 AirScript 和 HTTP API 中的参数写法完全不同。

3.1 创建数据表

AirScript —— 对象嵌套，类型名首字母大写：

Application.Sheets.Add(
  null,                           // 在哪个表之前（null 表示不指定）
  null,                           // 在哪个表之后（null 表示不指定）
  'xlEtDataBaseSheet',            // 固定类型：多维数据表
  {
    fields: [{                    // 字段定义
      fieldType: 'SingleLineText',  // 类型：单行文本（首字母大写）
      args: { fieldName: '标题', fieldWidth: 15 }
    }],
    name: '样本表',                // 数据表名称
    views: [{ name: '网格视图', type: 'Grid' }]  // 视图：首字母大写
  }
);

core/execute —— 扁平参数，类型名全小写：

fetch('https://www.kdocs.cn/api/v3/office/file/{fileId}/core/execute', {
  method: 'POST',
  credentials: 'include',          // 自动携带登录 Cookie
  body: JSON.stringify({
    command: 'http.db.createSheet', // 命令名
    param: {
      name: '样本表',
      fields: [{ name: '标题', type: 'MultiLineText', width: 15 }],
      views: [{ name: '默认视图', type: 'grid' }]  // 注意：全小写
    }
  })
});
// {fileId} 替换为文档真实 ID（可从网址中获取）

差异一：AirScript 的文本字段区分 SingleLineText（单行）和 MultiLineText（多行）；HTTP API 统一用 MultiLineText。

差异二：视图类型 Grid 在 AirScript 中首字母大写，HTTP API 中全小写 grid。

3.2 字段管理

AirScript —— 通过 FieldDescriptors 集合管理：

// ---- 新增字段 ----
var desc = FieldDescriptor('MultiLineText', '新字段'); // 创建字段描述器
desc.FieldWidth = 15;                                   // 设置列宽
Application.Sheets(1).FieldDescriptors.AddField(desc); // 追加到第1个数据表

// ---- 删除字段 ----
var field = Application.Sheets(1).FieldDescriptors(2); // 取第2个字段
field.Delete();                                         // 删除

core/execute —— 通过命令名区分操作：

fetch('https://www.kdocs.cn/api/v3/office/file/{fileId}/core/execute', {
  method: 'POST', credentials: 'include',
  body: JSON.stringify({
    command: 'http.db.createFields',
    param: {
      sheetId: 1,
      fields: [{ name: '新字段', type: 'MultiLineText', width: 15 }]
    }
  })
});

两者的设计思路不同：AirScript 是对象导向——每次操作对应一个方法（.AddField()、.Delete()），通过 "." 链式调用；HTTP API 是命令导向——不是调用对象方法，而是向指定网址发送一段 JSON 数据，所有操作发到同一个地址，靠字符串指令名区分。

3.3 记录操作

AirScript —— 可以完整增删改查：

// ---- 插入一条记录，写入数据 ----
var r = Application.ActiveView.RecordRange.Add(null, null, 1);
//                          新增1条空记录 ↑
r.Item(undefined, '@标题').Value = 'Demo Record';
//      列标识 ↑       写入值 ↑

core/execute —— 只能查，不能增删改：

fetch('https://www.kdocs.cn/api/v3/office/file/{fileId}/core/execute', {
  method: 'POST', credentials: 'include',
  body: JSON.stringify({
    command: 'http.db.listRecords',
    param: { sheetId: 1, pageSize: 20 }
  })
});

V7 REST —— 可以写入记录：

fetch('https://api.wps.cn/v7/dbsheet/{fileId}/sheets/1/records/batch_create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'wps_sid=' + wps_sid
  },
  body: JSON.stringify({
    records: [{
      fields: { '标题': 'Demo Record' }
    }]
  })
});

如果需要通过 HTTP 写入记录，必须使用V7 REST的批量写入接口，或调用 AirScript-Token。

3.4 视图管理

AirScript —— 统一在一个对象链上操作：

// ---- 新建甘特视图、修改颜色 ----
var ganttView = Application.Sheets(1).Views.Add('Gantt', '甘特视图');
//                视图类型 ↑         视图名称 ↑
ganttView.TimelineColor = '#ff6600';  // 时间线颜色：橙色

core/execute —— 只能更新和删除，不能创建：

fetch('https://www.kdocs.cn/api/v3/office/file/{fileId}/core/execute', {
  method: 'POST', credentials: 'include',
  body: JSON.stringify({
    command: 'http.db.updateView',
    param: {
      sheetId: 1,
      id: 'viewId',
      name: '新名称',
      themeColor: '#ff6600'
    }
  })
});

V7 REST —— 可以创建视图：

fetch('https://api.wps.cn/v7/dbsheet/{fileId}/sheets/1/views', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'wps_sid=' + wps_sid
  },
  body: JSON.stringify({
    name: '甘特视图',
    view_type: 'Gantt'
  })
});

创建视图必须通过 V7 REST 或 AirScript，core/execute 不支持。

四、案例

WPS 多维表模板库

该脚本在多维表页面注入一个浮动按钮，点击展开模板面板，内置「项目追踪表」「客户管理表」「库存管理表」三个预设模板。选中模板后，脚本会自动通过 core/execute在当前文档中创建对应的数据表和字段——无需打开脚本编辑器，无需手动拼写请求参数。读者亦可仿照其代码结构添加自定义模板。

综合杂谈圈

21小时前

6 +1