当前位置：首页 > news >正文

同一个灰色，POI取出来却是白色：一次Excel颜色解析的踩坑记录

news 2025/9/23 8:56:52

最近在写一个后端转换功能，导入xlsx文件，给他解析成JSON格式。结果测试时发现一个问题：两个看起来一模一样的灰色单元格，代码读出来的颜色不一样。属实给我整懵逼了。
比如下面这两个单元格
在这里插入图片描述

A1：能正常拿到灰值，比如 #808080
B1：拿到的是 FFFFFF —— 白的

明明都是手动设置的灰色，样式也一样，拿到的填充颜色确不一样。

我第一反应是前景色/背景色搞混了，于是加了一个判断，前景色拿不到就从背景色拿：

XSSFColor color = (XSSFColor) cellStyle.getFillForegroundColorColor();
if (color == null) {color = (XSSFColor) cellStyle.getFillBackgroundColorColor();
}

最后一试，还是白的。

折腾半天，最后发现关键在于：B1 是个主题色，而 A1 是个普通颜色（换了三个AI，问了半天结合起来才折腾出来）。

主题色是什么？

在 Excel 里用“主题颜色”面板选的颜色，比如“辅助色 3”、“深色 1”这类，都叫主题色。它们不是固定的 RGB 值，而是指向当前工作簿的主题定义。也就是说，换一套主题，这颜色可能就变了。

POI 的 XSSFColor 提供了一个方法判断：

color.isThemed() // 返回 true 表示是主题色

如果是主题色，直接调 .getRGB() 或 .getARGB() 是拿不到有效值的，经常就是 null 或 FFFFFF。

得结合 ThemesTable 把真正的颜色算出来。

但这还没完。
即使你从 ThemesTable 拿到了主题里的基础颜色，结果可能还是不对。因为还有一个东西叫 tint。

什么是 tint

tint 是 Excel 里用来微调主题颜色明暗的一个参数，取值范围是 -1.0 到 1.0：

tint = 0：原色
tint > 0：越接近 1，颜色越亮（往白色混合）
tint < 0：越接近 -1，颜色越暗（往黑色混合）

比如你选了个“辅助色 3”是深灰，但 Excel 默认给它加了个 tint = -0.24，意思是在这个主题色基础上再压暗一点。如果你忽略这个值，直接拿原始主题色，就会偏亮，甚至变成白色。

所以，只处理主题色不处理 tint，拿到的颜色也可能有问题。

最终解决方案

核心思路：

判断是否为 isThemed()
如果是，从 ThemesTable 中取出对应索引的基础 RGB
再根据 getTint() 值，对颜色做明暗调整

下面是封装好的工具类，可以直接用：

import lombok.extern.slf4j.Slf4j;
import org.apache.poi.xssf.model.ThemesTable;
import org.apache.poi.xssf.usermodel.XSSFColor;import java.awt.*;@Slf4j
public class ThemeColorResolver {/*** 获取颜色的ARGB十六进制字符串表示** @param themedColor XSSFColor对象* @param theme       主题表* @return ARGB格式的十六进制字符串(如 " FFFF0000 " 表示红色)，如果无法解析则返回null*/public static String getActualColorHex(XSSFColor themedColor, ThemesTable theme) {Color color = resolveActualColor(themedColor, theme);return color != null ? toARGBHex(color) : null;}/*** 获取颜色的RGB十六进制字符串表示(不带Alpha通道)** @param themedColor XSSFColor对象* @param theme       主题表* @return RGB格式的十六进制字符串(如 " FF0000 " 表示红色)，如果无法解析则返回null*/public static String getActualColorRGBHex(XSSFColor themedColor, ThemesTable theme) {Color color = resolveActualColor(themedColor, theme);return color != null ? toRGBHex(color) : null;}/*** 获取颜色的java.awt.Color对象** @param themedColor XSSFColor对象* @param theme       主题表* @return 解析后的Color对象，如果无法解析则返回null*/public static Color getActualColor(XSSFColor themedColor, ThemesTable theme) {return resolveActualColor(themedColor, theme);}/*** 核心解析方法*/private static Color resolveActualColor(XSSFColor themedColor, ThemesTable theme) {// 如果不是主题色，直接返回ARGB颜色if (!themedColor.isThemed()) {byte[] argb = themedColor.getARGB();if (argb == null || argb.length < 3) {log.warn("Non-themed color has invalid ARGB value");return null;}return new Color(argb[1] & 0xFF, argb[2] & 0xFF, argb[3] & 0xFF, argb[0] & 0xFF);}// 解析主题颜色try {int themeIndex = themedColor.getTheme();XSSFColor themeColor = theme.getThemeColor(themeIndex);byte[] themeRgb = themeColor.getRGB();if (themeRgb == null || themeRgb.length < 3) {log.warn("Theme color not found for index: {}", themeIndex);return null;}// 获取基础颜色(不考虑tint)Color baseColor = new Color(themeRgb[0] & 0xFF, themeRgb[1] & 0xFF, themeRgb[2] & 0xFF);// 应用tint调整double tint = themedColor.getTint();if (tint != 0.0) {return applyTint(baseColor, tint);}return baseColor;} catch (Exception e) {log.error("Error resolving theme color", e);return null;}}/*** 应用tint值调整颜色*/private static Color applyTint(Color baseColor, double tint) {int r = baseColor.getRed();int g = baseColor.getGreen();int b = baseColor.getBlue();if (tint > 0) {// 变亮（混合白色）r = (int) (r + (255 - r) * tint);g = (int) (g + (255 - g) * tint);b = (int) (b + (255 - b) * tint);} else if (tint < 0) {// 变暗（混合黑色）r = (int) (r * (1 + tint));g = (int) (g * (1 + tint));b = (int) (b * (1 + tint));}// 确保值在0-255范围内r = Math.min(255, Math.max(0, r));g = Math.min(255, Math.max(0, g));b = Math.min(255, Math.max(0, b));return new Color(r, g, b);}/*** 将Color转换为ARGB十六进制字符串*/private static String toARGBHex(Color color) {return String.format("%02X%02X%02X%02X",color.getAlpha(), color.getRed(), color.getGreen(), color.getBlue());}/*** 将Color转换为RGB十六进制字符串(不带Alpha)*/private static String toRGBHex(Color color) {return String.format("%02X%02X%02X",color.getRed(), color.getGreen(), color.getBlue());}
}

使用方式

// 获取工作簿的主题表
ThemesTable themes = workbook instanceof XSSFWorkbook ? ((XSSFWorkbook) workbook).getThemesTable() : null;// 获取单元格样式颜色
XSSFColor fill = (XSSFColor) cellStyle.getFillForegroundColorColor();
Color actualColor = ThemeColorResolver.getActualColor(fill, themes);if (actualColor != null) {String hex = ThemeColorResolver.toHex(actualColor); // 如 #808080
}