钉钉表格脚本脚本是钉钉文档提供的自动化工具。用户可以将常用的操作以脚本的形式记录下来，便于后续执行同样的操作。用户也可以借助脚本，扩展钉钉文档本身的能力，将钉钉文档融入到个人或企业工作中。

支持语言是JavaScript。

钉钉表格脚本API设计基于表格的对象模型。

当需要执行某个具体的操作时，应当首先获取到对应的对象，然后调用对象上的具体方法。

钉钉表格API的顶级对象为Workbook，代表当前表格。调用API读写表格数据时，通常从Workbook开始。

如下图所示，根据表格的数据对象模型，将API进行了对象划分。常用的对象有：

Workbook：工作簿。包含多个工作表，Workbook为顶级对象，可以直接在脚本中使用。

Sheet：工作表。包含单元格和单元格区域，要获取Sheet对象，可以使用 Workbook.getSheet('Sheet1') 方法，其中Sheet1为工作表名称。

Range：单个选区。包含单个或者多个单元格，要获取Range对象，可以使用Workbook.getRange('A1:B1')方法， 获取当前工作表上的A1:B1选区；或者也可以使用sheet.getRange('A1:B1') 获取特定工作表上的A1:B1选区。

RangeList：多个选区。包含多个区域，要获取RangeList对象，可以使用Workbook.getRangeList(['A1:B1', 'C2:D2']) 方法来获取当前工作表上的A1:B1和C1:D2选区。同样的，在sheet上也可以调用类似的API来获取特定工作表上的选区。

首先需要确定要操作的对象，再调该对象上的API。

例如，需要设置一个区域内所有单元格的背景色，那么操作对象就是Range，首先获取到Range，再调用Range对象中的setBackgroundColor API。

// 获取当前的 sheet
const sheet = Workbook.getActiveSheet();
// 获取选区 A1
const range = sheet.getRange('A1');
// 设置选区 A1 的背景色
range.setBackgroundColor('#ffff00');

const inputValue = await Input.textAsync("请输入数据：");

// 输出A1的值
Output.log("A1 value: " + range[0][0].getValue());

// 修改A1的值
range.setValues([
    ["New Value"]
])

钉钉表格脚本支持异步编程，使用 async/await 语法处理异步操作。

1. 函数声明：如果函数内部使用了异步方法（如 Input.textAsync、fetch 等），必须将函数声明为 async
2. 函数调用：调用 async 函数时，必须使用 await 关键字
3. 顶层调用：在脚本顶层调用 async 函数时，也需要使用 await

// 声明为 async 函数
async function processData() {
  // 使用 await 调用异步方法
  const inputValue = await Input.textAsync("请输入数据：");
  
  const response = await fetch('https://api.example.com/data');
  const data = await response.json();
  
  // 处理数据...
  Output.log(`处理完成：${inputValue}`);
}

// 调用时使用 await
await processData();

// ❌ 错误：函数内使用 await 但未声明为 async
function processData() {
  const inputValue = await Input.textAsync("请输入数据："); // 语法错误
}

// ❌ 错误：调用 async 函数时未使用 await
async function processData() {
  const inputValue = await Input.textAsync("请输入数据：");
}
processData(); // 可能导致执行顺序问题

以下方法需要使用 await：

• Input.textAsync() - 获取用户输入
• fetch() - 网络请求
• response.json() - 解析JSON响应
• response.text() - 解析文本响应
• 其他返回 Promise 的自定义异步函数

钉钉表格脚本支持使用 fetch API 获取网络数据，可以实现从外部API获取数据并填充到表格中。

// 获取当前工作表
const sheet = Workbook.getActiveSheet();

// 从API获取数据
const response = await fetch('https://api.example.com/data');
const data = await response.json();

// 将数据填充到表格
if (data && data.items) {
  // 设置表头
  const headers = [["ID", "名称", "状态", "创建时间"]];
  sheet.getRange('A1:D1').setValues(headers);
  sheet.getRange('A1:D1').setFontWeight('bold');
  
  // 填充数据
  const rows = data.items.map(item => [
    item.id,
    item.name,
    item.status,
    item.createdAt
  ]);
  
  sheet.getRange(1, 0, rows.length, 4).setValues(rows);
  
  Output.log(`成功导入 ${rows.length} 条数据`);
}

1. 异步操作：fetch 返回 Promise，需要使用 await 关键字，且必须在 async 函数中使用
2. 错误处理：建议使用 try-catch 捕获网络错误
3. 响应格式：支持 .json()、.text()、.blob() 等方法解析响应，这些方法也需要 await
4. 跨域限制：某些API可能有CORS限制，需要API服务器支持
5. 请求头设置：可以通过 fetch 的第二个参数配置请求选项

// 带请求头的 fetch 示例
const response = await fetch('https://api.example.com/data', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

💡 更多示例：查看 examples/fetch-demo.js 获取更多完整的 fetch 使用示例，包括：

• 从公开API获取数据
• POST 请求示例
• 错误处理最佳实践
• 批量请求和进度显示
• 各种实际应用场景

以下是钉钉表格脚本提供的主要API对象及其说明：

API	说明	文档链接
Workbook	工作簿	查看详情
Sheet	工作表	查看详情
Range	单个选区	查看详情
RangeList	多个选区	查看详情
Input	用户输入交互	查看详情
Output	输出信息	查看详情
Filter	筛选	查看详情
FilterCriteriaBuilder	筛选规则构造器	查看详情
FilterCriteria	筛选规则	查看详情
FilterCondition	筛选条件	查看详情
Hyperlink	超链接	查看详情
SearchOptions	搜索选项	查看详情
SortField	排序字段	查看详情
SetValueOptions	设置值的选项	查看详情
DropdownListOption	下拉列表选项	查看详情
BorderType	边框类型	查看详情
Color	颜色	查看详情

所有API对象的详细文档已从钉钉官方文档转换并保存在 docs/api/ 目录中，每个API对象都有对应的Markdown文档，包含：

• 方法说明
• 参数列表
• 返回值说明
• 示例代码

点击上表中的"查看详情"链接可以查看对应API的完整文档。

• 钉钉表格脚本官方文档