@d-zero/google-sheets

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

インストール

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

基本的な使い方

認証

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

データを書き込む

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: '[email protected]',
		age: { value: 25 },
		registered: { value: new Date('2024-01-15') },
	},
]);

データを読み取る

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

セルのスタイリング

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

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

条件付き書式

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

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 リファレンス

SheetTable

静的メソッド

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<SheetTable>

インスタンスメソッド

addRecords(records)

レコードを追加します。

パラメータ:

• records - レコードの配列。各値は string または { value, textFormat?, cellFormat?, ... } オブジェクト（文字列以外の値も { value: ... } でラップ）

getData()

すべてのデータを取得します。セルの型（文字列、数値、日付など）は自動変換されます。

戻り値: Promise<T[]>

型定義

HeaderCell

type HeaderCell = {
	readonly label: string;
	readonly conditionalFormatRules?: sheets_v4.Schema$ConditionalFormatRule[];
};

CellData

type CellData<T = CellRawData> = {
	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

type CellRawData = string | number | boolean | Date | null | undefined;

Row

type Row = readonly Cell[];

CellType

type CellType = 'string' | 'number' | 'boolean' | 'date' | 'formula' | 'error';

CellTypeInfo

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

低レベル API

SheetTable を使わず、より細かい制御が必要な場合は Sheets クラスを直接使用できます。

import { Sheets } from '@d-zero/google-sheets';

const sheets = new Sheets(sheetUrl, auth);
const sheet = await sheets.create('SheetName');
// sheet.addRowData(), sheet.setHeaders() など

詳細は ソースコード を参照してください。

ライセンス

MIT