本文详解如何通过 Google Apps Script 导入 CSV 数据时强制将含前导零的数字（如 "0001"）作为纯文本写入 Google Sheets，避免自动转为数值 1，核心是结合 setNumberFormat("@") 预设文本格式并正确调用 setValues()。
本文详解如何通过 google apps script 导入 csv 数据时强制将含前导零的数字（如 "0001"）作为纯文本写入 google sheets，避免自动转为数值 1，核心是结合 `setnumberformat("@")` 预设文本格式并正确调用 `setvalues()`。
在使用 Utilities.parseCsv() 解析 CSV 并通过 setValues() 写入 Google Sheets 时，一个常见痛点是：像 "0001","0002","0003" 这类带前导零的字符串，会被 Sheets 自动识别为数字并抹去前导零，最终显示为 1, 2, 3——这在处理订单号、员工工号、产品编码等需要严格格式的场景中是不可接受的。
根本原因在于：Google Sheets 的单元格默认采用“自动格式”，当内容可被解析为数字时，它会优先应用数值格式；而 setValues() 仅写入值本身，不携带格式指令。因此，必须显式设置单元格的数字格式为文本（@），且该设置需在 setValues() 之后（或链式调用中）立即生效，以确保值以原始字符串形式呈现。
✅ 正确解决方案：setNumberFormat("@") 链式调用
以下是最简洁、可靠的核心代码段：
function importCsv(e) {
if (!e) {
SpreadsheetApp.getUi().showModalDialog(
HtmlService.createHtmlOutputFromFile("index"),
"CSV 导入工具"
);
return;
}
// 解析 CSV 字符串为二维数组（每行 = 子数组，每列 = 元素）
const csvContent = Utilities.newBlob(...e).getDataAsString();
const csv = Utilities.parseCsv(csvContent);
const sheet = SpreadsheetApp.getActiveSheet();
const targetRange = sheet.getRange(
sheet.getLastRow() + 1, // 下一行起始行
1, // 第一列
csv.length, // 行数
csv[0].length // 列数（假设非空）
);
// 关键：先设文本格式，再写入值（顺序不可颠倒！）
targetRange.setNumberFormat("@").setValues(csv);
}? 关键点说明：
- setNumberFormat("@") 是 Google Sheets 的「文本格式代码」，表示将单元格强制设为纯文本模式；
- 必须在 setValues() 之前或链式调用中同步设置——若先 setValues() 后 setNumberFormat()，部分单元格可能因自动格式化已丢失前导零，导致无效；
- @ 格式对所有数据类型均安全：文本保持原样，数字也以字符串形式显示（如 0001 不变），不会引发错误。
⚠️ 注意事项与进阶适配
1. 处理 CSV 中字段内含逗号的异常情况
原始问题中的示例 CSV：
0001,0002,0003 test,test2,test3
符合标准 CSV 结构（每行三列），上述方案完全适用。但若实际 CSV 出现类似 "A,B",C,"D,E,F" 的带引号逗号字段，则 Utilities.parseCsv() 已内置 RFC 4180 兼容解析，无需额外处理。
2. 当 CSV 实际为单列、值内含逗号（如 "0001,0002,0003"）时
若你的 CSV 文件实际是 单列多行，且每行内容为用英文逗号分隔的字符串（例如第一行内容就是字面量 "0001,0002,0003"），则需手动拆分：
function importCsvSplitComma(e) {
if (!e) {
SpreadsheetApp.getUi().showModalDialog(HtmlService.createHtmlOutputFromFile("index"), "sample");
return;
}
const csvContent = Utilities.newBlob(...e).getDataAsString();
// 按行分割 → 每行按逗号分割 → 展开嵌套结构
const temp = csvContent.split("\n")
.map(line => line.trim())
.filter(line => line.length > 0)
.map(line => line.split(",").map(cell => cell.trim()));
// 确保每行长度一致（补 null 避免 setValues 报错）
const maxCols = Math.max(...temp.map(r => r.length));
const csv = temp.map(row => [...row, ...Array(maxCols - row.length).fill("")]);
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange(
sheet.getLastRow() + 1,
1,
csv.length,
maxCols
);
range.setNumberFormat("@").setValues(csv);
}3. 批量更新（Batch Update）方案的格式限制
注意：Google Sheets API 的 pasteData 请求 不支持直接设置数字格式。即使你传入字符串数组，API 仍会依据目标单元格当前格式或自动判断决定渲染方式。因此，若坚持使用 batchUpdate，必须提前用 Apps Script 将目标区域格式设为文本：
// 在 batchUpdate 前添加（独立调用）
sheet.getRange("A1:Z1000").setNumberFormat("@"); // 覆盖足够大的范围
// 再执行 Sheets.Spreadsheets.batchUpdate(...)✅ 总结
| 方法 | 是否保留前导零 | 是否推荐 | 说明 |
|---|---|---|---|
| setValues() + setNumberFormat("@")（链式） | ✅ 完全保留 | ✅ 强烈推荐 | 简洁、可靠、可控性强 |
| 仅 setValues() | ❌ 自动转数值 | ❌ 不可用 | 默认行为，无法满足需求 |
| batchUpdate + pasteData | ⚠️ 依赖目标格式 | ⚠️ 慎用 | 需预设格式，灵活性低 |
只要牢记 “先设格式，再写值” 这一黄金法则，并选用 @ 文本格式码，即可彻底解决 CSV 导入中前导零丢失问题。此方案兼容所有标准 CSV 结构，且无需修改原始数据，是生产环境下的最佳实践。
