# @budibase/google-spreadsheet 中文文档

规范地址：https://npmcn.com/package/%40budibase/google-spreadsheet/

版本：4\.1\.5
npm 元数据更新时间：2026-08-17T10:37:32.432Z
中文译文更新时间：2026-11-08T18:18:58.545Z
软件包许可：Unlicense

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40budibase/google-spreadsheet
原文对照：https://npmcn.com/package/%40budibase/google-spreadsheet/?lang=original
项目主页：https://theoephraim.github.io/node-google-spreadsheet
源码仓库：https://github.com/theoephraim/node-google-spreadsheet

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：219 kB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：google-auth-library ^8\.8\.0 \|\| ^9\.0\.0
- 首次发布：2024-05-17T09:47:41.552Z
- 最新版本发布：2024-09-19T15:11:33.909Z
- 近 30 天下载量：37732（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 0 个）

## 中文简介

Google 工作表 API - 读取/写入数据和管理工作表的简单界面

## 安装

```sh
npm install @budibase/google-spreadsheet
```

也可以使用：`pnpm add @budibase/google-spreadsheet`、`yarn add @budibase/google-spreadsheet`、`bun add @budibase/google-spreadsheet`

## README

# google-快报

> 最受欢迎的 [谷歌工作表 API](https://developers.google.com/sheets/api/guides/concepts) javascript/ 打字的包装

[![NPM version](https://img.shields.io/npm/v/google-spreadsheet)](https://www.npmjs.com/package/google-spreadsheet) [![CI status](https://github.com/theoephraim/node-google-spreadsheet/actions/workflows/ci.yml/badge.svg)](https://github.com/theoephraim/node-google-spreadsheet/actions/workflows/ci.yml) [![Known Vulnerabilities](https://snyk.io/test/github/theoephraim/node-google-spreadsheet/badge.svg?targetFile=package.json)](https://snyk.io/test/github/theoephraim/node-google-spreadsheet?targetFile=package.json) [![NPM](https://img.shields.io/npm/dw/google-spreadsheet)](https://www.npmtrends.com/google-spreadsheet)

-   多个认证选项( 通过 [google-auth-图书馆](https://www.npmjs.com/package/google-auth-library)\- 服务账户、OAuth、API密钥、ADC等
-   基于单元格的 API - 读取、写入、批量更新、格式化
-   基于行的 API - 读取,更新,删除(基于旧的 v3 行调用)
-   管理工作表 - 添加、删除、调整大小、更新属性(例如:标题),复制到同一文档或其他文档
-   管理 docs - 创建新 doc, 删除 doc, 基本共享/允许
-   导出 - 各种格式的下载工作表/文件

**文档网站 -** 完整的文件可用时间 [https://theoephraim.github.io/node-google-spreadsheet 互联网档案馆的存檔,存档日期2013-12-12](https://theoephraim.github.io/node-google-spreadsheet)

* * *

> 🌈 **安装** - 说吧 `pnpm i google-spreadsheet`  
> (或 `npm i google-spreadsheet --save` 或者说 `yarn add google-spreadsheet`(中文(简体) )

## 实例

_下面的例子是为了给你一个想法 只是一些你可以做的事情_

> **重要说明** - 为了保持简洁的例子, 我打电话等待 [最高层](https://v8.dev/features/top-level-await) 在一些更古老的节点版本中不允许。 如果您需要用脚本在根位调用等待, 且您的环境不支持它, 您必须将其包装为类似 async 函数 :

```javascript
(async function () {
  await someAsyncFunction();
})();
```

### 基本情况

```js
import { GoogleSpreadsheet } from 'google-spreadsheet';
import { JWT } from 'google-auth-library';

// Initialize auth - see https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication
const serviceAccountAuth = new JWT({
  // env var values here are copied from service account credentials generated by google
  // see "Authentication" section in docs for more info
  email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
  key: process.env.GOOGLE_PRIVATE_KEY,
  scopes: ['https://www.googleapis.com/auth/spreadsheets'],
});

const doc = new GoogleSpreadsheet('<the sheet ID from the url>', serviceAccountAuth);

await doc.loadInfo(); // loads document properties and worksheets
console.log(doc.title);
await doc.updateProperties({ title: 'renamed doc' });

const sheet = doc.sheetsByIndex[0]; // or use `doc.sheetsById[id]` or `doc.sheetsByTitle[title]`
console.log(sheet.title);
console.log(sheet.rowCount);

// adding / removing sheets
const newSheet = await doc.addSheet({ title: 'another sheet' });
await newSheet.delete();
```

更多信息 :

-   [谷歌读取表](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet)
-   [谷歌Spreadsheet 工作表](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-worksheet)
-   [认证](https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication)

### 随行工作

```js
// if creating a new sheet, you can set the header row
const sheet = await doc.addSheet({ headerValues: ['name', 'email'] });

// append rows
const larryRow = await sheet.addRow({ name: 'Larry Page', email: 'larry@google.com' });
const moreRows = await sheet.addRows([
  { name: 'Sergey Brin', email: 'sergey@google.com' },
  { name: 'Eric Schmidt', email: 'eric@google.com' },
]);

// read rows
const rows = await sheet.getRows(); // can pass in { limit, offset }

// read/write row values
console.log(rows[0].get('name')); // 'Larry Page'
rows[1].set('email', 'sergey@abc.xyz'); // update a value
rows[2].assign({ name: 'Sundar Pichai', email: 'sundar@google.com' }); // set multiple values
await rows[2].save(); // save updates on a row
await rows[2].delete(); // delete a row
```

行方法支持清晰的数据形状类型Script

```typescript
type UsersRowData = {
  name: string;
  email: string;
  type?: 'admin' | 'user';
};
const userRows = await sheet.getRows<UsersRowData>();

userRows[0].get('name'); // <- TS is happy, knows it will be a string
userRows[0].get('badColumn'); // <- will throw a type error
```

更多信息 :

-   [GoogleSpreadsheet 工作表 > 用行工作](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-worksheet#working-with-rows)
-   [谷歌SpreadsheetRow 页面存档备份,存于互联网](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-row)

### 与牢房合作

```js
await sheet.loadCells('A1:E10'); // loads range of cells into local cache - DOES NOT RETURN THE CELLS
console.log(sheet.cellStats); // total cells, loaded, how many non-empty
const a1 = sheet.getCell(0, 0); // access cells using a zero-based index
const c6 = sheet.getCellByA1('C6'); // or A1 style notation
// access everything about the cell
console.log(a1.value);
console.log(a1.formula);
console.log(a1.formattedValue);
// update the cell contents and formatting
a1.value = 123.456;
c6.formula = '=A1';
a1.textFormat = { bold: true };
c6.note = 'This is a note!';
await sheet.saveUpdatedCells(); // save all updates in one call
```

更多信息 :

-   [GoogleSpreadsheet 工作表 > 与单元格一起工作](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-worksheet#working-with-cells)
-   [谷歌SpreadsheetCell 页面](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-cell)

### 管理文件和分享

```js
const auth = new JWT({
  email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
  key: process.env.GOOGLE_PRIVATE_KEY,
  scopes: [
    'https://www.googleapis.com/auth/spreadsheets',
    // note that sharing-related calls require the google drive scope
    'https://www.googleapis.com/auth/drive.file',
  ],
});

// create a new doc
const newDoc = await GoogleSpreadsheet.createNewSpreadsheetDocument(auth, { title: 'new fancy doc' });

// share with specific users, domains, or make public
await newDoc.share('someone.else@example.com');
await newDoc.share('mycorp.com');
await newDoc.setPublicAccessLevel('reader');

// delete doc
await newDoc.delete();
```

## 为什么?

> **这个模块提供了一个围绕Google的API的直观包装器来简化常见的相互作用**

虽然Google的 v4 工作表 API 比 v3 更容易使用,但官方 [googleapis npm 模块](https://www.npmjs.com/package/googleapis) 是一个巨大的自动生成的元工具,可以处理 _每个谷歌产品_模块和API本身都很尴尬 文档很可怕 至少要开始.

**在什么情况下你应该直接使用Google的API?**  
本模块为接口的简单取舍. Google的API提供了一个并行提出许多请求的机制,因此如果速度和效率对于你的使用案例极为重要,你可能希望直接使用他们的API. 其API中还有许多使用较少的特征尚未在这里实施.

## 支持和贡献

这个模块是写成的,并一直由 [西奥·伊法莱姆](https://theoephraim.com/)。 。 。 .

**您是否在商业项目中积极使用此模块? 想帮忙支持吗?**  
[买 西奥 啤酒](https://paypal.me/theoephraim)

### 发起人

还没有 联系一下!

### 捐款

欢迎各方提交资料,但请遵照现行公约行事,使用网关,增加相关测试,并增加相关文件.

文件站点使用 [文档化](https://docsify.js.org/)。要预览和本地运行,您可以编辑、运行 `npm run docs:preview` 并直接前往 http://localhost:300 内容存在于 Docs 文件夹中的 markdown 文件 .

## 许可证

这是自由而不受限制的公有领域软件. 关于更多信息,见 [https://unlicense.org (中文(简体) )](https://unlicense.org/)。 。 。 .

## 常见问题

### @budibase/google-spreadsheet 是什么？

Google 工作表 API - 读取/写入数据和管理工作表的简单界面

### 如何安装 @budibase/google-spreadsheet？

在项目目录运行 npm install @budibase/google-spreadsheet，或使用 pnpm add / yarn add / bun add。

### @budibase/google-spreadsheet 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @budibase/google-spreadsheet 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @budibase/google-spreadsheet 可以商用吗？

@budibase/google-spreadsheet 使用 Unlicense 许可。作者将代码贡献到公共领域，可不受限制地使用。以上为概括，不构成法律意见，请以许可原文为准。

### @budibase/google-spreadsheet 的下载量有多少？

根据 npm 官方下载统计，@budibase/google-spreadsheet 在 2026/10/09 – 2026/11/07 这 30 天内被下载 37,732 次，日均约 1,258 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @budibase/google-spreadsheet 还在维护吗？

最新版本 4\.1\.5 发布于 2024/09/19（2 年前）；至今共发布 4 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/05/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。