调用Sheet.getData()触发NPE，求数据范围请求方法及单元格背景色方案

一、为什么会触发空指针异常（NPE） #

你遇到的问题核心在于：调用service.spreadsheets().get(spreadsheetId).execute()时，Google Sheets API默认不会返回工作表的GridData（也就是Sheet.getData()要获取的内容）。API默认只返回资源的基础属性（比如工作表标题），如果需要获取单元格数据、格式这类附加信息，必须显式指定要请求的字段范围，否则sheet.getData()就会返回null，进而触发NPE。

二、修复NPE的代码修改 #

你需要在调用spreadsheets().get()时，通过setFields()方法明确指定要获取的字段，确保包含sheets.data相关内容。如果你只需要工作表标题和单元格背景色，可以这样调整代码：

Sheets service = new Sheets.Builder(HTTP_TRANSPORT, JSON_FACTORY, getCredentials(HTTP_TRANSPORT))
        .setApplicationName(APPLICATION_NAME)
        .build();

// 关键修改：指定要获取的字段，包含工作表标题和单元格背景色格式
Spreadsheet spreadsheet = service.spreadsheets().get(spreadsheetId)
        .setFields("sheets(properties(title),data(rowData(values(effectiveFormat.backgroundColor))))")
        .execute();

List<Sheet> sheets = spreadsheet.getSheets();
Sheet sheet = null;
for(Sheet s : sheets) {
    if(s.getProperties().getTitle().equalsIgnoreCase("GSheets API Sheet")) {
        sheet = s;
        break; // 找到目标sheet后提前退出循环，提升效率
    }
}

// 现在sheet.getData()不会返回null了
List<GridData> data = sheet.getData();
// 遍历数据提取背景色
for(GridData gridData : data) {
    for(RowData rowData : gridData.getRowData()) {
        for(CellData cellData : rowData.getValues()) {
            Color bgColor = cellData.getEffectiveFormat().getBackgroundColor();
            if(bgColor != null) {
                // 处理背景色，例如打印RGB值
                System.out.printf("背景色：R=%f, G=%f, B=%f%n", 
                    bgColor.getRed(), bgColor.getGreen(), bgColor.getBlue());
            }
        }
    }
}

setFields参数说明：

• sheets(properties(title))：获取工作表的标题属性，用于匹配你的目标sheet
• data(rowData(values(effectiveFormat.backgroundColor)))：获取每行数据中单元格的有效格式（effectiveFormat）里的背景色

三、另一种获取单元格背景色的高效方法 #

如果你只需要特定范围的单元格背景色，使用spreadsheets().getByDataFilter()可以更精准地请求数据，减少不必要的返回内容，提升效率：

// 先定位目标sheet的ID
Sheet targetSheet = null;
for(Sheet s : sheets) {
    if(s.getProperties().getTitle().equalsIgnoreCase("GSheets API Sheet")) {
        targetSheet = s;
        break;
    }
}
if(targetSheet == null) {
    // 处理sheet不存在的异常情况
    return;
}

// 创建数据过滤器，指定要获取的单元格范围
GridRange gridRange = new GridRange()
        .setSheetId(targetSheet.getProperties().getSheetId())
        .setStartRowIndex(0) // 起始行（从0开始计数）
        .setEndRowIndex(10)  // 结束行（不包含该行）
        .setStartColumnIndex(0) // 起始列
        .setEndColumnIndex(5);  // 结束列

DataFilter dataFilter = new DataFilter().setGridRange(gridRange);
GetSpreadsheetByDataFilterRequest request = new GetSpreadsheetByDataFilterRequest()
        .setDataFilters(Collections.singletonList(dataFilter))
        .setIncludeGridData(true);

// 发送请求获取指定范围的格式数据
Spreadsheet response = service.spreadsheets().getByDataFilter(spreadsheetId, request).execute();

// 提取并处理背景色
List<DataFilterValueRange> valueRanges = response.getDataFilterValueRanges();
for(DataFilterValueRange range : valueRanges) {
    for(List<CellData> row : range.getRowData()) {
        for(CellData cell : row) {
            Color bgColor = cell.getEffectiveFormat().getBackgroundColor();
            if(bgColor != null) {
                System.out.printf("背景色：R=%f, G=%f, B=%f%n", 
                    bgColor.getRed(), bgColor.getGreen(), bgColor.getBlue());
            }
        }
    }
}

重要提示 #

• values().get()方法仅能获取单元格的数值内容，无法获取格式信息（比如背景色），必须使用spreadsheets().get()或spreadsheets().getByDataFilter()这类接口。
• 尽量精确指定setFields的内容，避免请求不必要的数据，减少API响应时间和数据传输量。

内容的提问来源于stack exchange，提问作者Jonathan M.