← 返回WPS在线表格组件参考 · 全部使用指导

WPS在线表格使用指导

• WPS在线表格使用指导
  • 准备：粘贴脚本、拿到链接和令牌
    • 1. 新建表格并设置工作表名
    • 2. 创建文档共享脚本
    • 3. 复制 webhook 链接
    • 4. 创建脚本令牌
  • 快速上手：在线报名表
    • 手机提交与在线表格结果
  • 按条件查找
  • 运行自己写的脚本
  • 常见问题
  • 搭建与测试
  • 属性、方法与事件速查
  • 常见问题与验收
  • 完整 .aia 源码：活动报名与名单管理
    • 活动报名与名单管理

不可见组件：读写金山文档（WPS）在线表格，国内直接可用，用来替代依赖谷歌服务的电子表格。 适合报名表、签到表、库存清单、成绩查询这类「多台手机共用一张表、电脑上也能直接打开编辑」的场景。

原理：在金山文档表格里放一段 AirScript 脚本（本页提供，整段复制即可），App 带着「脚本令牌」调用这段脚本， 由脚本在表格里完成读写。方法和事件与电子表格同名，谷歌表格做的项目换成本组件基本不用改代码块。

行号、列号都从 1 开始；读出的单元格一律是文本（数字 98 读出来是 "98"，空单元格是空文本）。 写入时数字积木写成数值，文本积木写成文本（手机号用文本输入框的内容写入，不会变成科学计数法）。

准备：粘贴脚本、拿到链接和令牌

本页配置与运行效果截图来自社区文章 WPS在线表格：实时读取/编辑线上表格。按下面的顺序完成配置；点击图片可查看原图。

1. 新建表格并设置工作表名

电脑浏览器打开 金山文档，在「新建」中选择 Office 文档 → 表格，再选择「空白表格」。

把底部第一个工作表标签改名为 报名，第一行 A1、B1、C1 分别填写 姓名、手机、时间。组件方法中的工作表名对应这个底部标签。

2. 创建文档共享脚本

菜单「效率」→「高级开发」→「AirScript 脚本编辑器」。

点「创建脚本」→「文档共享脚本」，或左侧「文档共享脚本」旁的 + 新建脚本。必须选「文档共享脚本」；「我的脚本」没有本案例需要的 webhook 链接。把下面的通用脚本整段粘贴进去并保存，脚本名称可以自定（截图中为 ai2）。

通用脚本（不要修改，组件的读写方法都靠它）：

// App Inventor「WPS在线表格」通用脚本 v1（fun123.cn）：整段复制粘贴，无需修改
var a = Context.argv || {}
var s = a.sheet ? Application.Sheets.Item(a.sheet) : Application.ActiveSheet
if (!s) {
  throw new Error('找不到工作表：' + a.sheet)
}

// 列号转列字母：1→A，27→AA
function col(n) {
  var t = ''
  while (n > 0) {
    t = String.fromCharCode(65 + (n - 1) % 26) + t
    n = Math.floor((n - 1) / 26)
  }
  return t
}

// 有数据的最后一行、最后一列（空表都是 0）
function used() {
  var u = s.UsedRange
  var r = u.Row + u.Rows.Count - 1
  var c = u.Column + u.Columns.Count - 1
  if (r === 1 && c === 1) {
    var v = s.Range('A1').Value2
    if (v === null || v === undefined || v === '') {
      return { row: 0, col: 0 }
    }
  }
  return { row: r, col: c }
}

// 写入区域：只有一个单元格时直接写值
function put(range, values) {
  if (Array.isArray(values) && values.length === 1 && values[0].length === 1) {
    values = values[0][0]
  }
  s.Range(range).Value2 = values
}

var u
switch (a.action) {
  case 'read':
    return s.Range(a.range).Value2
  case 'write':
    put(a.range, a.values)
    return true
  case 'clear':
    s.Range(a.range).ClearContents()
    return true
  case 'readRow':
    u = used()
    return u.col === 0 ? [] : s.Range('A' + a.row + ':' + col(u.col) + a.row).Value2
  case 'readSheet':
    u = used()
    return u.row === 0 ? [] : s.Range('A1:' + col(u.col) + u.row).Value2
  case 'addRow':
    u = used().row + 1
    put('A' + u + ':' + a.lastCol + u, a.values)
    return u
  case 'removeRow':
    s.Range('A' + a.row).EntireRow.Delete()
    return true
  default:
    throw new Error('未知操作：' + a.action + '（这是 App Inventor 通用脚本，自定义脚本请另建一个）')
}

3. 复制 webhook 链接

保存脚本后，在左侧脚本列表中点击该脚本的「更多」菜单，选择「复制脚本 webhook」，把完整链接填到 WPS在线表格组件的 WebhookUrl（Webhook链接） 属性。这里需要的是脚本 webhook，不能用浏览器地址栏里的表格链接代替。

4. 创建脚本令牌

点击脚本编辑器工具栏的盾牌图标「脚本令牌」，勾选「我已知晓」，再点「创建脚本令牌」（首次需要实名认证）。复制令牌后填到组件的 Token（访问令牌） 属性。

令牌默认 180 天到期，创建时可以延长，到期后 App 会报「脚本令牌无效或已过期」。WebhookUrl 和 Token 都配置好后，再搭建下面的 App。

快速上手：在线报名表

手机填姓名和手机号提交，数据追加到金山文档的「报名」表；点「刷新」把所有人的姓名显示在列表里。 电脑上打开这张表，能实时看到手机提交的数据，也可以直接在表里改。

1. 拖一个WPS在线表格，填好 WebhookUrl 和 Token（见上一节）；
2. 拖两个文本输入框（文本输入框_姓名、文本输入框_手机）、两个按钮（按钮_提交、按钮_刷新）、 一个标签（标签_状态）、一个列表显示框（列表显示框1）和一个计时器（计时器1）。关闭计时器的「启用计时」属性，本例只用它获取当前时间；
3. 搭下面的代码块：

各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。

when 按钮_提交.Click {
  var 时间 = 计时器1.FormatDateTime(计时器1.Now(), "yyyy-MM-dd HH:mm")
  WPS在线表格1.AddRow("报名", [文本输入框_姓名.Text, 文本输入框_手机.Text, 时间])
  标签_状态.Text = "提交中…"
}

when WPS在线表格1.FinishedAddRow(行号) {
  标签_状态.Text = join("已提交，在第 ", 行号, " 行")
}

when 按钮_刷新.Click {
  WPS在线表格1.ReadSheet("报名")
}

when WPS在线表格1.GotSheetData(表格数据) {
  var 姓名列表 = []
  foreach 行 in 表格数据 {
    listAdd(姓名列表, 行[1])
  }
  列表显示框1.Elements = 姓名列表
}

when WPS在线表格1.ErrorOccurred(错误信息) {
  标签_状态.Text = 错误信息
}

运行后提交一条，电脑上的表格里立刻多出一行；点「刷新」，列表第一项是标题「姓名」，下面是所有报名的人。 （要去掉标题行，可以在循环里跳过第 1 行，或改用 读取范围（工作表名，范围标识）（ReadRange） 读 A2:A200。）

手机提交与在线表格结果

在手机输入姓名和手机号，点击提交。标签先显示「提交中…」，添加行完成后显示新行号。原帖效果图中输入的是演示值 123、abc，状态为「已提交，在第 2 行」。

回到电脑上的「报名」工作表，第 2 行可看到对应的姓名、手机和时间。原帖截图中的 123、abc 与手机输入一致，说明数据已写入这张在线表格。自己操作时，用实际输入值核对新行；再点击 App 的「刷新」，检查姓名列表是否更新。

按条件查找

按列筛选与谷歌表格一致：精确匹配数据（工作表名，列ID，值）（ReadWithExactFilter）找某列等于给定文本的行， 部分匹配数据（工作表名，列ID，值）（ReadWithPartialFilter）找某列包含给定文本的行，都区分大小写，返回的行号含标题行（标题行是第 1 行）。

when 按钮_查询.Click {
  WPS在线表格1.ReadWithExactFilter("报名", 2, 文本输入框_手机.Text)
}

when WPS在线表格1.GotFilterResult(行号列表, 行数据列表) {
  if length(行号列表) == 0 {
    标签_状态.Text = "没有报名记录"
  } else {
    标签_状态.Text = join("已报名，姓名：", 行数据列表[1][1])
  }
}

运行自己写的脚本

需要通用脚本做不到的事（如只返回某人的成绩、跨表统计）时，在同一个表格里另建一个文档共享脚本， 用它的 webhook 链接调用运行脚本（参数字典）（RunScript）：参数字典在脚本里用 Context.argv 读取，脚本 return 的值由 获得脚本结果（返回结果）（GotScriptResult）返回（对象变字典、数组变列表）。一个组件只对应一个 webhook 链接， 通用脚本和自定义脚本要同时用时，放两个 WPS在线表格组件。

例：成绩表第 1 列是学号、第 2 列是姓名、第 3 列是分数，只按学号返回这个人的成绩：

var id = String(Context.argv.id)
var n = Application.ActiveSheet.UsedRange.Rows.Count
for (var i = 2; i <= n; i++) {
  if (String(Application.ActiveSheet.Range('A' + i).Value2) === id) {
    return { name: Application.ActiveSheet.Range('B' + i).Value2, score: Application.ActiveSheet.Range('C' + i).Value2 }
  }
}
return {}

when 按钮_查询.Click {
  WPS在线表格_查分.RunScript(makeDict(pair("id", 文本输入框_学号.Text)))
}

when WPS在线表格_查分.GotScriptResult(返回结果) {
  标签_状态.Text = join(dictLookup(返回结果, "name", "查无此人"), " ", dictLookup(返回结果, "score", ""))
}

常见问题

搭建与测试

在设计器拖入本组件和案例涉及的按钮、标签、布局等组件，按案例中的名称重命名。先运行最小案例，确认事件返回，再增加业务逻辑。示例中的素材先上传到项目，服务器地址、令牌、文件路径换成自己的值。

可见组件需要有非零宽高；不可见工具组件必须由属性或方法启动。设计器展示样式不等于运行时已加载数据或绑定目标。联机测试应使用包含本组件的 AI 伴侣；涉及系统入口或权限的行为还要编译安装后验证。

属性、方法与事件速查

完整参数类型、默认值和平台说明见组件参考。下表按调用入口列出用途；有完成事件的方法在事件中读取结果。

常见问题与验收

完整 .aia 源码：活动报名与名单管理

下载 .aia 源码

导入WpsSheetAllFeatures.aia后展开“表格配置与部署脚本”。在自己的金山文档中新建工作表“报名案例”，A1、B1、C1写姓名、手机、时间。使用本工程“复制完整部署脚本”取得随工程打包的通用AirScript，创建文档共享脚本并保存，复制真实Webhook链接和令牌填写到应用。具体配置步骤见本组件原指导的截图。令牌不预置、不显示明文、不自动存盘。

应用配置后点刷新验证真实连接。填写姓名和手机提交，只有实际FinishedAddRow才显示成功及行号；电脑打开同一表格核对。刷新显示所有报名，按姓名查询返回真实行号和数据。无配置、空姓名、非法行号、重复在途请求、表格失败均有反馈。

管理面板默认收起。读取单元格、行、范围、精确／部分筛选和脚本读取都使用真实在线表。修改姓名、写两行明确标为演示的数据、清空或删除选定行，必须勾选确认，行号至少2；删除会使后续行上移，请刷新再操作。不要用自己的正式业务工作表测试删除。复制脚本本身不是联网成功。

覆盖全部方法、事件、Token与WebhookUrl的配置和读写；不会把令牌输出到界面。验证报告内部留存。需要你自己的账号与真实表格配置；本轮尚未进行真实WPS账号联调或真机实测。

活动报名与名单管理

导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 主界面提交、刷新和查询实际报名，配置与数据管理默认收起。通用部署脚本已打包，可从工程复制，使用自己的真实脚本Webhook和令牌。只有真实事件确认提交成功；令牌不预置或输出到界面。 覆盖30/30，正式编辑器首次载入与保存重开零错误，后台导入及安装包编译通过。账号联调、真机／伴侣尚未实测。