vika：维格表官方 JavaScript SDK 接入与数据操作指南

一、项目官方信息

说明：本仓库是维格表（vika.cn）官方 JavaScript SDK，而不是可自托管的服务端程序。维格表本身是一款在线的“多维表格”SaaS 产品（类似 Airtable），官方通过这套 SDK 与 Fusion API 让你在自己的应用里对维格表数据做增删改查。因此本文重点是“接入与使用”，而非 Docker 部署一套服务端。

vika（@vikadata/vika） 是对维格表 Fusion API 的官方封装。README 中的定位是：让你轻松拥有维格表的扩展能力，方便地把维格表中的数据集成到自己的应用中。你可以把维格表当作一个可视化编辑的在线数据库，再用 SDK 在代码里读写其中的记录。

二、官方图片

上图为该仓库在 GitHub 上的社交预览图。维格表的可视化界面（表格、字段、视图）在 vika.cn 网页端操作，SDK 只负责通过 API 读写这些数据。

三、环境要求

• Node.js 14 及以上版本（带 npm 或 yarn）。
• 一个维格表（vika.cn）账号，并在其中创建好一张多维表格（数据表）。
• 已获取 API Token（见下文第一步）。
• 网络可访问 https://vika.cn。

四、接入步骤

第一步：获取 API Token

按官方文档，API Token 即用户认证令牌：

1. 登录维格表（vika.cn）。
2. 点击左下角个人头像，进入「用户中心」。
3. 前往「开发者配置」界面，点击「+」生成 API Token（首次生成需绑定邮箱）。
4. 复制并妥善保管 Token。请求时需在请求头带上 Authorization: Bearer {你的 API Token}。

注意：认证成功后，这份 API 请求拥有与该用户在界面上相同的权限——用户能在界面上操作什么数据，API 就能操作什么数据。因此 Token 泄露等于把数据交给别人，泄露后应在「开发者配置」里重新生成。

第二步：安装 SDK

# npm
npm install @vikadata/vika@latest

# yarn
yarn add @vikadata/vika@latest

第三步：初始化客户端

const { Vika } = require('@vikadata/vika');

const vika = new Vika({
  token: '_替换成你的_API_Token_',
  // fieldKey 可选，指定查询/返回字段时用 'name'（字段名）还是 'id'（字段 ID）
});

实例化时可配置的全局参数：token（必填，API Token）、fieldKey（字段 key 类型，默认为按字段名 name）。

第四步：定位数据表

你需要两个关键 ID：

• datasheetId：数据表 ID，在维格表 URL 或表格信息里可找到。
• viewId（可选）：指定某个视图。

第五步：对记录做增删改查

// 获取记录（带分页与筛选）
const records = await vika.vc
  .record.list({
    datasheetId: '你的数据表ID',
    pageSize: 100,
  });

// 新增记录
await vika.vc.record.create({
  datasheetId: '你的数据表ID',
  records: [{ fields: { '姓名': '张三', '城市': '西安' } }],
});

// 更新记录
await vika.vc.record.update({
  datasheetId: '你的数据表ID',
  records: [{ recordId: 'recXXXX', fields: { '城市': '兰州' } }],
});

// 删除记录
await vika.vc.record.delete({
  datasheetId: '你的数据表ID',
  recordIds: ['recXXXX'],
});

如果不想用 SDK，也可以直接发 HTTPS 请求，例如获取记录：

curl "https://vika.cn/fusion/v1/datasheets/{datasheetId}/records" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {你的 API Token}"

五、使用方法

• 作为后台数据库：在维格表网页端维护表格结构与数据，用 SDK 在自己的小程序/网站/脚本里读取，省去自建数据库后台。
• 字段即列：一条记录对应表格里的一行，fields 里的键是字段名（或字段 ID，取决于 fieldKey）。
• 视图与筛选：record.list 支持指定视图、筛选条件与分页，只取你需要的数据子集。
• 字段与表管理：除记录外，Fusion API 还提供字段、视图、附件上传、空间站、文件节点、通讯录成员/小组/角色等接口（见官方文档目录）。
• 多语言客户端：除了 JavaScript SDK，官方还提供 Go、Java、Python、PHP 等客户端，按技术栈选用即可。
• 与知识库/博客结合：可以把维格表当一个可协作编辑的后台，用 SDK 拉取数据渲染成页面或简单列表，非技术同事在表格里改内容，你的应用实时读取。

六、常见问题 FAQ

1. 这个仓库能 Docker 部署一套自己的维格表吗？ 不能。vikadata/vika 是官方 JavaScript SDK，维格表服务端并未开源；它是 vika.cn 在线服务的客户端库。想自托管多维表格，需要另选其他开源方案。

2. 报 401 / 认证失败？ 多半是 Token 填错或过期。确认初始化时 token 正确，请求头为 Authorization: Bearer {token}；必要时在「开发者配置」重新生成。

3. 字段名读不到数据？ 注意 fieldKey 模式：默认按字段名（name）匹配。如果你的字段名里有空格、 emoji 或后续被改过名，建议改用字段 ID（id）模式，并传字段 ID。

4. datasheetId 从哪里找？ 打开对应数据表，从浏览器地址栏或表格的「说明/信息」里获取数据表 ID；它是后续所有 record/field 接口的必填参数。

5. 一次能查多少条记录？ 记录接口是分页返回的，用 pageSize 与分页参数翻页拉取，不要假设一次能取完全部。

6. Token 泄露了怎么办？ 立即在维格表「用户中心 → 开发者配置」里重新生成 Token，旧 Token 即失效；这相当于该用户账号的长期密码，务必妥善保管。

七、跳转链接

• GitHub 仓库：https://github.com/vikadata/vika
• 快速上手文档：https://vika.cn/developers/api/quick-start/
• npm 包：https://www.npmjs.com/package/@vikadata/vika
• 维格表官网：https://vika.cn