@d-zero/google-sheets

Google Sheets API を使いやすくラップした TypeScript ライブラリです。型安全なテーブル操作を提供します。

インストール

``bash
npm install @d-zero/google-sheets @d-zero/google-auth
`

基本的な使い方

$3

`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 を参照してください。

$3

`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') },
},
]);
`

$3

`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();
`

$3

文字列の代わりにオブジェクトを渡すことで、セルの書式を指定できます。

`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 },
},
},
},
]);
`

$3

ヘッダー定義時に条件付き書式を設定できます。

`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: 'ステータス',
},
});
`

API リファレンス

$3

#### 静的メソッド

##### SheetTable.create(sheetUrl, sheetName, auth, header, options?)

テーブルを作成します。シートが存在しない場合は作成されます。

パラメータ:

- sheetUrl: string - スプレッドシートの URL
- sheetName: 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

$3

#### 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 リファレンス を参照してください。

$3

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