Google Sheets API Toolkit
npm install @d-zero/google-sheets@d-zero/google-sheetsGoogle Sheets API を使いやすくラップした TypeScript ライブラリです。型安全なテーブル操作を提供します。
``bash`
npm install @d-zero/google-sheets @d-zero/google-auth
`typescript
import { authentication } from '@d-zero/google-auth';
const auth = await authentication('path/to/credentials.json', [
'https://www.googleapis.com/auth/spreadsheets',
]);
`
認証の詳細は @d-zero/google-auth を参照してください。
`typescript
import { SheetTable } from '@d-zero/google-sheets';
const table = await SheetTable.create(
'https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit',
'Users',
auth,
{
define: {
name: '名前',
email: 'メールアドレス',
age: '年齢',
registered: '登録日',
},
},
);
await table.addRecords([
{
name: '田中太郎',
email: 'tanaka@example.com',
age: { value: 25 },
registered: { value: new Date('2024-01-15') },
},
]);
`
`typescript
const table = await SheetTable.create(
'https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit',
'Products',
auth,
{
search: ['id', 'name', 'price', 'inStock'],
},
);
const products = await table.getData();
`
文字列の代わりにオブジェクトを渡すことで、セルの書式を指定できます。
`typescript`
await table.addRecords([
{
title: 'プロジェクトA',
link: {
value: 'https://example.com',
textFormat: {
link: { uri: 'https://example.com' },
foregroundColor: { blue: 1.0 },
},
},
status: {
value: '完了',
textFormat: {
bold: true,
foregroundColor: { green: 0.8 },
},
},
},
]);
ヘッダー定義時に条件付き書式を設定できます。
`typescript`
const table = await SheetTable.create(spreadsheetUrl, 'Sales', auth, {
define: {
date: '日付',
amount: {
label: '売上金額',
conditionalFormatRules: [
{
booleanRule: {
condition: {
type: 'NUMBER_GREATER_THAN_EQ',
values: [{ userEnteredValue: '10000' }],
},
format: {
backgroundColor: { red: 0.8, green: 1.0, blue: 0.8 },
},
},
},
],
},
status: 'ステータス',
},
});
#### 静的メソッド
##### SheetTable.create(sheetUrl, sheetName, auth, header, options?)
テーブルを作成します。シートが存在しない場合は作成されます。
パラメータ:
- sheetUrl: string - スプレッドシートの URLsheetName: string
- - シート名auth: OAuth2Client
- - 認証クライアントheader
- - ヘッダー設定{ define: { [key: string]: string | HeaderCell } }
- - ヘッダーを定義する{ search: string[] }
- - 既存のヘッダーを検索するoptions?
- - オプション設定bodyStartRow?: number
- - データ開始行(デフォルト: 2)frozen?: { rows: number; cols: number }
- - 固定する行・列数
戻り値: Promise
#### インスタンスメソッド
##### addRecords(records)
レコードを追加します。
パラメータ:
- records - レコードの配列。各値は string または { value, textFormat?, cellFormat?, ... } オブジェクト(文字列以外の値も { value: ... } でラップ)
##### getData()
すべてのデータを取得します。セルの型(文字列、数値、日付など)は自動変換されます。
戻り値: Promise
#### HeaderCell
`typescript`
type HeaderCell = {
readonly label: string;
readonly conditionalFormatRules?: sheets_v4.Schema$ConditionalFormatRule[];
};
#### CellData
`typescript`
type CellData
readonly value: T;
readonly textFormat?: sheets_v4.Schema$TextFormat | null;
readonly cellFormat?: sheets_v4.Schema$CellFormat | null;
readonly image?: boolean;
readonly note?: string;
readonly ifNull?: T;
};
#### CellRawData
`typescript`
type CellRawData = string | number | boolean | Date | null | undefined;
#### Row
`typescript`
type Row = readonly Cell[];
#### CellType
`typescript`
type CellType = 'string' | 'number' | 'boolean' | 'date' | 'formula' | 'error';
#### CellTypeInfo
`typescript`
type CellTypeInfo = {
readonly index: number;
readonly type: CellType;
};
textFormat の主なプロパティ:
- bold?: boolean - 太字italic?: boolean
- - 斜体foregroundColor?: { red?: number; green?: number; blue?: number }
- - 文字色(0.0-1.0)link?: { uri: string }
- - ハイパーリンク
詳細は Google Sheets API リファレンス を参照してください。
SheetTable を使わず、より細かい制御が必要な場合は Sheets クラスを直接使用できます。
`typescript
import { Sheets } from '@d-zero/google-sheets';
const sheets = new Sheets(sheetUrl, auth);
const sheet = await sheets.create('SheetName');
// sheet.addRowData(), sheet.setHeaders() など
``
詳細は ソースコード を参照してください。
MIT