dingtalk-sheet-scripts

钉钉表格脚本开发

运行环境

• 语言：JavaScript (ES6+)
• 运行在钉钉表格的沙箱环境中
• 使用 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 从钉钉官方 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