dingtalk-sheet-scripts

DingTalk スプレッドシートのスクリプト開発

実行環境

• 言語：JavaScript (ES6+)
• DingTalk スプレッドシートのサンドボックス環境で実行
• Output.log() でログを出力（console.log ではありません）
• async/await と fetch API に対応

コアオブジェクト

オブジェクト	説明	取得方法
Workbook	ワークブック（最上位オブジェクト）	直接使用
Sheet	ワークシート	Workbook.getActiveSheet()
Range	セル範囲	sheet.getRange('A1:B10')
Input	ユーザー入力（非同期）	await Input.textAsync()
Output	ログ出力	Output.log()

クイックサンプル

// 基础数据写入
const sheet = Workbook.getActiveSheet();
sheet.getRange('A1:B2').setValues([
  ['姓名', '分数'],
  ['张三', 95]
]);

// 异步用户输入
const name = await Input.textAsync('请输入姓名：');
Output.log(`你好，${name}`);

// 网络请求
const response = await fetch('https://api.example.com/data');
const data = await response.json();

主要な規則

非同期プログラミング

すべての非同期操作では async/await を使用する必要があります。

// 正确
async function process() {
  const input = await Input.textAsync('输入：');
  const response = await fetch(url);
  const data = await response.json();
}
await process();

// 错误：缺少 async/await
function process() {
  const input = Input.textAsync('输入：'); // 错误
}
process(); // 错误

データ更新の方針

全量の書き戻しは避け、変更部分のみを更新してください。

// 正确：只更新需要修改的行
const values = sheet.getRange('A2:D100').getValues();
for (let i = 0; i < values.length; i++) {
  if (values[i][2] === '待处理') {
    sheet.getRange(i + 1, 2, 1, 1).setValues([['已处理']]);
  }
}

// 错误：读取整表后全量回写
const allValues = sheet.getRange('A1:D100').getValues();
allValues[5][2] = '已处理';
sheet.getRange('A1:D100').setValues(allValues); // 避免这样做

getRange のパラメーター

• A1 表記：sheet.getRange('A1:B10')
• 数値インデックス：sheet.getRange(row, col, rowCount, colCount) - 行と列のインデックスは 0 から始まります

sheet.getRange(0, 0, 1, 1)  // A1
sheet.getRange(0, 0, 10, 2) // A1:B10
sheet.getRange(1, 0, 5, 3)  // A2:C6

エラー処理

try {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }
  const data = await response.json();
} catch (error) {
  Output.error(`失败：${error.message}`);
}

よく使うパターン

ヘッダーのスタイル設定

const header = sheet.getRange('A1:D1');
header.setValues([['ID', '名称', '状态', '金额']]);
header.setFontWeight('bold');
header.setBackgroundColor('#4285F4');
header.setFontColor('#FFFFFF');

条件付き書式

for (let i = 0; i < values.length; i++) {
  const cell = sheet.getRange(i + 1, 2, 1, 1);
  const score = values[i][2];

  if (score >= 90) cell.setBackgroundColor('#C8E6C9');
  else if (score >= 60) cell.setBackgroundColor('#FFF9C4');
  else cell.setBackgroundColor('#FFCDD2');
}

ユーザーが選択した操作

const action = await Input.selectAsync('选择操作：', [
  { text: '导入数据', value: 'import' },
  { text: '导出数据', value: 'export' },
  { text: '生成报表', value: 'report' }
]);

if (action === 'import') { /* ... */ }

ファイルのインポート

const files = await Input.filesAsync('上传 CSV', {
  multiple: false,
  fileType: '.csv'
});

if (files && files.length > 0) {
  const content = await files[0].text();
  const rows = content.split('\n').map(row => row.split(','));
  sheet.getRange(0, 0, rows.length, rows[0].length).setValues(rows);
}

API リファレンス

詳細な API ドキュメントは docs/api/ ディレクトリにあります。

API	説明	ドキュメント
Workbook	ワークブック	docs/api/Workbook.md
Sheet	ワークシート	docs/api/Sheet.md
Range	セル範囲	docs/api/Range.md
RangeList	複数選択範囲	docs/api/RangeList.md
Input	ユーザー入力	docs/api/Input.md
Output	ログ出力	docs/api/Output.md
Filter	フィルター	docs/api/Filter.md

サンプルコード

examples/ ディレクトリで、その他のサンプルを確認できます。

• examples/fetch-demo.js - ネットワークリクエストのサンプル（GET/POST、一括リクエスト、エラー処理）

API ドキュメントの更新

scripts/update_api_docs.py を使用して、DingTalk 公式 OSS から最新の API ドキュメントを取得します。

依存関係のインストール

pip install markitdown requests

使い方

# 更新所有 API 文档
python scripts/update_api_docs.py

# 更新指定的 API 文档
python scripts/update_api_docs.py --api Workbook Sheet Range

# 列出所有可用的 API
python scripts/update_api_docs.py --list

利用可能な API の一覧

• コアオブジェクト: Workbook, Sheet, Range, RangeList
• ユーザー操作: Input, Output
• フィルター関連: Filter, FilterCriteria, FilterCriteriaBuilder, FilterCondition
• データ形式: SetValueOptions, DropdownListOption, BorderType, Color, SearchOptions, SortField
• その他: Hyperlink