Google Sheets API更新图表后BOTTOM_AXIS样式无法生效问题

使用Google Sheets API更新图表的数据范围和轴样式时，数据范围更新正常，但BOTTOM_AXIS的文本样式（字体大小50、白色）无法生效，更新后会重置为默认值。

环境：

• PHP 7.4+
• "google/apiclient": "^2.0" 及 Google Sheets API v4

相关PHP代码：

$chartId = null;
foreach ($spreadsheetInfo->getSheets() as $sheet) {
    if ($sheet->getProperties()->getSheetId() == self::$FunctionsSheetId && $sheet->getCharts()) {
                foreach ($sheet->getCharts() as $chart) {
                    $chartId = $chart->getChartId();
                    
                    # Get the existing chart spec
                    $existingSpec = $chart->getSpec();
                    
                    # Modify ONLY the source ranges
                    $basicChart = $existingSpec->getBasicChart();
                                            
                    # Update series ranges (typically Y-axis)
                    $series = $basicChart->getSeries();
                    foreach ($series as $seriesItem) {
                        $sourceRange = $seriesItem->getSeries()->getSourceRange();
                        $sources = $sourceRange->getSources();
                        foreach ($sources as $source) {
                            $source->setStartRowIndex(0);
                            $source->setEndRowIndex(count($attributeValues));
                        }
                    }

                    $axes = $basicChart->getAxis();
                    foreach ($axes as $axis) {
                        if ($axis->getPosition() === 'BOTTOM_AXIS') {
                            $textFormat = new TextFormat();

                            #color
                            $color = new Color();
                            $color->setRed(1); 
                            $color->setGreen(1);
                            $color->setBlue(1);
                            
                            $colorStyle = new ColorStyle();
                            $colorStyle->setRgbColor($color);
                            $textFormat->setForegroundColorStyle($colorStyle);
                            
                            #font size
                            $textFormat->setFontSize(50);
                            
                            $axis->setFormat($textFormat);
                        }
                    }
                    
                    #set the BasicChart back
                    $existingSpec->setBasicChart($basicChart);
                        
                    # Put the modified chart back
                    $requests = [
                        new SheetsRequest([
                            'updateChartSpec' => [
                                'chartId' => $chartId,
                                'spec' => $existingSpec
                            ]
                        ])
                    ];

                    $batchUpdateRequest = new BatchUpdateSpreadsheetRequest([
                        'requests' => $requests
                    ]);

                    try {
                        $sheetsService->spreadsheets->batchUpdate($this->spreadSheetId, $batchUpdateRequest);
                    } catch (\Exception $e) {
                        Yii::error("Error updating chart: " . $e->getMessage());
                    }
                    
                    break 2;
                }
            }
        }

已尝试操作：

• 验证图表已成功更新为新数据
• 确认已正确检测到BOTTOM_AXIS
• 尝试在更新系列前后设置格式

问题出在两个核心点：

1. 未指定updateMask参数
   Google Sheets API的updateChartSpec请求默认会全量替换spec对象，未显式设置的字段会被重置为默认值。必须通过updateMask明确告诉API哪些字段需要更新，避免无关样式被覆盖。

2. 格式对象的覆盖逻辑问题
   直接新建TextFormat对象会完全替换原有轴格式，如果原有格式包含其他未修改的属性，会被一并清除。建议优先复用原有格式对象再修改指定属性。

修改后的代码调整 #

1. 调整轴格式设置逻辑

$axes = $basicChart->getAxis();
foreach ($axes as $axis) {
    if ($axis->getPosition() === 'BOTTOM_AXIS') {
        // 复用原有格式对象，避免覆盖未修改的属性
        $textFormat = $axis->getFormat() ?: new TextFormat();

        // 设置白色
        $color = new Color();
        $color->setRed(1); 
        $color->setGreen(1);
        $color->setBlue(1);
        
        $colorStyle = new ColorStyle();
        $colorStyle->setRgbColor($color);
        $textFormat->setForegroundColorStyle($colorStyle);
        
        // 设置字体大小
        $textFormat->setFontSize(50);
        
        $axis->setFormat($textFormat);
    }
}

2. 添加updateMask到请求中

$requests = [
    new SheetsRequest([
        'updateChartSpec' => [
            'chartId' => $chartId,
            'spec' => $existingSpec,
            // 指定需要更新的字段，用逗号分隔多个字段
            'updateMask' => 'basicChart.series,basicChart.axis.format'
        ]
    ])
];

updateMask中的basicChart.series对应数据范围的更新，basicChart.axis.format对应轴格式的更新。如果还有其他需要修改的字段，可继续添加到掩码中。

这样修改后，API只会更新指定的字段，轴的文本样式就能正常生效且不会被重置。

内容的提问来源于stack exchange，提问作者Mfoq