如何使用PHP Google Sheets API按列名或命名范围插入表格数据

Google Sheets 官方API没有原生支持按列名写入数据的能力，你可以通过先读取表头建立列名和列位置映射的方式实现需求，具体逻辑和PHP实现如下：

实现逻辑 #

• 先读取目标工作表的表头行（默认第一行存放列名，如name/price/quantity）
• 建立列名到列索引的映射关系
• 构造写入数组时，按照表头顺序填充数据，不需要写入的列填空字符串占位即可

完整PHP实现代码 #

// 配置参数
$spreadsheetId = '你的表格ID';
$list = '你的工作表名称';
$targetRow = $total; // 你要写入的目标行号，和你原有逻辑里的$total一致
// 要写入的列名和对应值
$insertData = [
    'name' => 'Samsung',
    'quantity' => '10'
];

// 1. 读取表头行（默认第一行是表头，若表头在其他行可修改行号）
$headerRange = $list . '!1:1';
$headerResponse = $service->spreadsheets_values->get($spreadsheetId, $headerRange);
$headers = $headerResponse->getValues()[0] ?? [];
if (empty($headers)) {
    throw new Exception('未读取到表头数据');
}

// 2. 建立列名到索引的映射
$colMap = [];
foreach ($headers as $index => $header) {
    $colMap[trim($header)] = $index;
}

// 3. 构造符合列顺序的写入数组
$values = array_fill(0, count($headers), ''); // 先填充全量空值
foreach ($insertData as $colName => $colValue) {
    if (isset($colMap[$colName])) {
        $values[$colMap[$colName]] = $colValue;
    }
}
$values = [$values]; // 转为二维数组符合API要求

// 4. 执行写入操作，和你原有逻辑一致
$ValueRange = new Google_Service_Sheets_ValueRange();
$ValueRange->setValues($values);
$options = ['valueInputOption' => 'USER_ENTERED'];
$service->spreadsheets_values->update($spreadsheetId, $list . '!A' . $targetRow, $ValueRange, $options);

注意事项 #

• 该方案默认表头无重复列名，若有重复列名需要自行调整映射逻辑
• 如果你的表格表头不在第一行，只需要修改$headerRange里的行号即可，比如表头在第二行就改成$list . '!2:2'

内容的提问来源于stack exchange，提问作者василий федотов