如何使用 openpyxl 获取和设置 Excel 单元格格式

我被代码海扁署名-非商业-禁演绎

阅读 31:38·字数 9493·更新 2025-1-10

Youtube 频道 Bilibili 空间
关注 1800

与 Excel 命名格式相关的内容，请查看内容分类一段列出的章节。

openpyxl Excel 颜色对象 Color

openpyxl包的Color类，属于模块openpyxl.styles.colors，用于表示 Excel 中的颜色，比如单元格的字体颜色，单元格的边框颜色。

Color对象的构造器如下，在创建Color实例时，只需根据颜色的类型给出必要的参数即可。

Color(rgb='00000000', indexed=None, auto=None, theme=None, tint=0.0, index=None, type='rgb')

rgb 参数

rgb参数是一个形式为AARRGGBB或RRGGBB的字符串，其中RR，GG，BB，AA是表示红色，绿色，蓝色以及透明度的十六进制数字，取值范围从00到FF。

AA为00表示不透明，AA为FF表示完全透明，透明度的效果视具体的 Office 软件而定，一些 Office 软件可能不会支持透明度。

indexed 参数

indexed参数是一个取值范围在0到63之间的整数，用于选择某个预先定义的索引颜色。

auto 参数

auto参数是一个布尔值，如果为True则表示使用自动颜色。

theme 参数

theme参数是一个整数，用于指定颜色是 Excel 文件当前主题中的第几个颜色，比如，0表示采用当前主题中的第一个颜色。

tint 参数

tint参数是一个取值范围在-1到1之间的浮点数，用于设置颜色的饱和度与亮度，该参数的值越大，则颜色越趋近于白色，该参数的值越小，则颜色越趋近于黑色，如果为0，则颜色保持原有的饱和度与亮度。

index 参数

index参数与indexed参数的作用相同。

type 参数

type参数用于表示颜色的类型，但事实上他没有任何的作用，Color对象的颜色类型将由构造器的其他参数确定。

Color对象的value属性，可以方便的获取或设置颜色的值，但不能赋值不同类型的颜色。

color.value color.value = value

value 值: value值是某种类型的颜色的值。

openpyxl.styles.colors模块拥有以下表示颜色的形式为AARRGGBB的字符串变量，BLACK（黑色，00000000），WHITE（白色，00FFFFFF），BLUE（蓝色，000000FF）。

Color 对象的特性

Color对象拥有变量rgb，indexed，auto，theme，tint和type，以及只读属性index，他们的值与传递给Color构造器的实参的值相同，如果你没有对变量作出修改。

color.py

from openpyxl.styles import Color


# 红色，饱和度 50%
c = Color(rgb='FF0000', tint=0.5)
print(c.value)
# 将颜色设置为蓝色
c.value = '0000FF'


# 索引为 2 的索引颜色是红色
Color(indexed=2)
# 自动颜色
Color(auto=True)


from openpyxl.styles.colors import BLACK
# 黑色
Color(rgb=BLACK)

00FF0000

openpyxl Excel 字体对象 Font

openpyxl包的Font类，属于模块openpyxl.styles.fonts，表示 Excel 中的字体格式，通常用于单元格对象Cell，其构造器如下。

Font(name=None, sz=None, b=None, i=None, charset=None, u=None, strike=None, color=None, scheme=None, family=None, size=None, bold=None, italic=None, strikethrough=None, underline=None, vertAlign=None, outline=None, shadow=None, condense=None, extend=None)

name 参数: name参数是一个表示字体名称的字符串。
sz 参数: sz参数是一个表示字体大小的浮点数，以磅（pt）为单位。
b 参数: b参数是一个布尔值，如果为True则采用粗体。
i 参数: i参数是一个布尔值，如果为True则采用斜体。
charset 参数: charset参数是一个整数，表示字体针对的是哪种语言。
u 参数: u参数是一个表示下划线格式的字符串，可以是以下值之一，'single'（单下划线，对应Font的类变量UNDERLINE_SINGLE），'double'（双下划线，对应Font的类变量UNDERLINE_DOUBLE），'singleAccounting'（会计单下划线，对应Font的类变量UNDERLINE_SINGLE_ACCOUNTING），'doubleAccounting'（会计双下划线，对应Font的类变量UNDERLINE_DOUBLE_ACCOUNTING）。
strike 参数: strike参数是一个布尔值，如果为True则采用删除线。
color 参数: color参数表示字体的颜色，可以是一个Color对象，或一个形式为AARRGGBB或RRGGBB的字符串。
scheme 参数: scheme参数是一个字符串，用于表示使用字体方案中的哪个字体，可以是以下值之一，'major'（使用字体方案中的主要字体），'minor'（使用字体方案中的次要字体）。
family 参数: family参数（可能）是一个表示字体所属家族的数字。
size 参数: size参数与sz参数的作用相同。
bold 参数: bold参数与b参数的作用相同。
italic 参数: italic参数与i参数的作用相同。
strikethrough 参数: strikethrough参数与strike参数的作用相同。
underline 参数: underline参数与u参数的作用相同。
vertAlign 参数: vertAlign参数是一个表示字体的垂直对齐方式的字符串，可以是以下值之一，'superscript'（字体作为上标显示），'subscript'（字体作为下标显示），'baseline'（字体采用基线对齐）。
outline 参数: outline参数是一个布尔值，如果为True则显示文本的轮廓。
shadow 参数: shadow参数是一个布尔值，如果为True则显示文本的阴影。
condense 参数: condense参数一个布尔值，如果为True，则表示缩小文字间距（该参数可能不会产生效果）。
extend 参数: extend参数一个布尔值，如果为True，则表示扩大文字间距（该参数可能不会产生效果）。

openpyxl.styles.fonts模块的变量DEFAULT_FONT定义了默认字体，其值为表达式Font(name='Calibri', sz=11, family=2, b=False, i=False, color=Color(theme=1), scheme='minor')的运算结果。

Font 对象的变量

Font对象拥有变量name，sz，b，i，charset，u，strike，color，scheme，family，size，bold，italic，strikethrough，underline，vertAlign，outline，shadow，condense，extend，在未作出修改时，他们的值与传递给Font构造器的实参的值相同。

font.py

from openpyxl.styles import Font, Color


# 粗体，斜体，单下划线，删除线
Font(b=True, i=True, u=Font.UNDERLINE_SINGLE, strike=True)
# 轮廓，阴影，20 磅
Font(outline=True, shadow=True, sz=20)
# 下标
Font(vertAlign='superscript')
# 红色，饱和度 50%
Font(color=Color(rgb='FF0000', tint=0.5))
# 蓝色
Font(color='0000FF')

openpyxl Excel 边对象 Side

openpyxl包的Side类，属于模块openpyxl.styles.borders，用于表示 Excel 中的边的格式。请注意边与边框的区别，边框包含多个边，Side对象对应了边框中的边，其构造器如下。

Side(style=None, color=None, border_style=None)

style 参数

style参数是一个表示边的形状的字符串，可以是以下值之一，'dashDot'（点状虚线），'dashDotDot'（点点状虚线），'dashed'（虚线），'dotted'（点线），'double'（双实线），'hair'（发线），'medium'（中等实线），'mediumDashDot'（点状中等虚线），'mediumDashDotDot'（点点状中等虚线），'mediumDashed'（中等粗虚线），'slantDashDot'（斜角点状虚线），'thick'（粗实线），'thin'（细实线）。

以上值分别对应openpyxl.styles.borders模块中的变量BORDER_DASHDOT，BORDER_DASHDOTDOT，BORDER_DASHED，BORDER_DOTTED，BORDER_DOUBLE，BORDER_HAIR，BORDER_MEDIUM，BORDER_MEDIUMDASHDOT，BORDER_MEDIUMDASHDOTDOT，BORDER_MEDIUMDASHED，BORDER_SLANTDASHDOT，BORDER_THICK，BORDER_THIN。

color 参数

color参数表示边的颜色，可以是一个Color对象，或一个形式为AARRGGBB或RRGGBB的字符串。

border_style 参数

border_style参数与style参数的作用相同。

Side 对象的变量

Side对象拥有变量style，color，border_style，在未作出修改时，他们的值与传递给Side构造器的实参的值相同。

side.py

from openpyxl.styles import Side


# 红色点线
Side('dotted', 'FF0000')

openpyxl Excel 边框对象 Border

openpyxl包的Border类，属于模块openpyxl.styles.borders，用于表示 Excel 中边框的格式，其构造器如下。

Border(left=None, right=None, top=None, bottom=None, diagonal=None, diagonal_direction=None, vertical=None, horizontal=None, diagonalUp=False, diagonalDown=False, outline=True, start=None, end=None)

left，right，top，bottom 参数: left，right，top，bottom参数是表示左边，右边，上边，下边格式的Side对象。
diagonal 参数: diagonal参数是表示边框对角线格式的Side对象。
diagonal_direction 参数: diagonal_direction参数表示边框对角线的方向，但其用法未知。
vertical 参数: vertical参数（可能）是表示边框中垂直线格式的Side对象，当边框包含多个单元格时。
horizontal 参数: horizontal参数（可能）是表示边框中水平线格式的Side对象，当边框包含多个单元格时。
diagonalUp 参数: diagonalUp参数是一个布尔值，如果为True则在边框中显示上对角线，即从左下角到右上角的对角线。
diagonalDown 参数: diagonalDown参数是一个布尔值，如果为True则在边框中显示下对角线，即从左上角到右下角的对角线。
outline 参数: outline参数（可能）是一个表示是否显示边框外框的布尔值。
start，end 参数: start参数与left参数的作用（可能）类似，end参数与right参数的作用（可能）类似。

Border 对象的变量

Border对象拥有变量left，right，top，bottom，diagonal，diagonal_direction，vertical，horizontal，diagonalUp，diagonalDown，outline，start，end，在未作出修改时，他们的值与传递给Border构造器的实参的值相同。

border.py

from openpyxl.styles import Border, Side, Color


# 左右为红色双实线，上下为蓝色粗实线的边框
double = Side('double', 'FF0000')
thick = Side('thick', Color('0000FF'))
Border(double, double, thick, thick)

openpyxl Excel 填充对象 PatternFill，GradientFill

openpyxl包中的类PatternFill和GradientFill，属于模块openpyxl.styles.fills，分别用于表示 Excel 中的图案填充格式和渐变填充格式，他们的构造器如下。

PatternFill(patternType=None, fgColor=Color(), bgColor=Color(), fill_type=None, start_color=None, end_color=None)

patternType 参数

patternType参数是一个表示图案填充类型的字符串，可以是以下值之一，'solid'，'darkDown'，'darkGray'，'darkGrid'，'darkHorizontal'，'darkTrellis'，'darkUp'，'darkVertical'，'gray0625'，'gray125'，'lightDown'，'lightGray'，'lightGrid'，'lightHorizontal'，'lightTrellis'，'lightUp'，'lightVertical'，'mediumGray'。

以上值分别对应openpyxl.styles.fills模块中的变量FILL_SOLID，FILL_PATTERN_DARKDOWN，FILL_PATTERN_DARKGRAY，FILL_PATTERN_DARKGRID，FILL_PATTERN_DARKHORIZONTAL，FILL_PATTERN_DARKTRELLIS，FILL_PATTERN_DARKUP，FILL_PATTERN_DARKVERTICAL，FILL_PATTERN_GRAY0625，FILL_PATTERN_GRAY125，FILL_PATTERN_LIGHTDOWN，FILL_PATTERN_LIGHTGRAY，FILL_PATTERN_LIGHTGRID，FILL_PATTERN_LIGHTHORIZONTAL，FILL_PATTERN_LIGHTTRELLIS，FILL_PATTERN_LIGHTUP，FILL_PATTERN_LIGHTVERTICAL，FILL_PATTERN_MEDIUMGRAY。

fgColor 参数

fgColor参数表示填充的前景（开始）颜色，可以是一个Color对象，或一个形式为AARRGGBB或RRGGBB的字符串。

bgColor 参数

bgColor参数表示填充的背景（结束）颜色，可以是一个Color对象，或一个形式为AARRGGBB或RRGGBB的字符串。

fill_type 参数

fill_type参数与patternType参数的作用相同。

start_color 参数

start_color参数与fgColor参数的作用相同。

end_color 参数

end_color参数与bgColor参数的作用相同。

openpyxl.styles.fills模块的变量DEFAULT_EMPTY_FILL，DEFAULT_GRAY_FILL定义了默认图案填充格式，其值为表达式PatternFill()和PatternFill(patternType='gray125')的运算结果。

PatternFill 对象的变量

PatternFill对象拥有变量patternType，fgColor，bgColor，fill_type，start_color，end_color，在未作出修改时，他们的值与传递给PatternFill构造器的实参的值相同。

在GradientFill类的构造器中，参数degree，left，right，top，bottom均可能对渐变的角度产生影响。

GradientFill(type='linear', degree=0, left=0, right=0, top=0, bottom=0, stop=())

type 参数: type参数是一个表示渐变填充类型的字符串，可以是以下值之一，'linear'（线性），'path'（路径）。
degree 参数: degree参数是一个浮点数，表示渐变的方向（角度）。
left 参数: left参数是表示渐变左边位置的浮点数，其具体作用和渐变类型有关，取值范围从0到1。
right 参数: right参数是表示渐变右边位置的浮点数，其具体作用和渐变类型有关，取值范围从0到1。
top 参数: top参数是表示渐变顶部位置的浮点数，其具体作用和渐变类型有关，取值范围从0到1。
bottom 参数: bottom参数是表示渐变底部位置的浮点数，其具体作用和渐变类型有关，取值范围从0到1。
stop 参数: stop参数是一个迭代器对象，包含若干Stop对象，用于表示渐变的终结点。

GradientFill 对象的变量

GradientFill对象拥有变量type，degree，left，right，top，bottom，stop，在未作出修改时，他们的值与传递给GradientFill构造器的实参的值相同。

openpyxl包的Stop类，属于模块openpyxl.styles.fills，用于表示 Excel 渐变填充格式中的颜色终结点，从一个终结点到另一个终结点，颜色将逐渐发生变化。

Stop(color, position)

color 参数: color参数表示终结点的颜色，可以是一个Color对象，或一个形式为AARRGGBB或RRGGBB的字符串。
position 参数: position参数是表示终结点位置的浮点数，取值范围从0到1。

Stop 对象的变量

Stop对象拥有变量color，position，在未作出修改时，他们的值与传递给Stop构造器的实参的值相同。

fill.py

from openpyxl.styles import PatternFill, GradientFill, Color
from openpyxl.styles.fills import Stop


# 图案 darkDown，前景红色，背景绿色
PatternFill('darkDown', 'FF0000', Color('00FF00'))
# 旋转 90 度，开始和结束为红色，中间为绿色
GradientFill('path', 90, stop=(
	Stop('FF0000', 0),
	Stop('00FF00', 0.5),
	Stop('FF0000', 1),
))

openpyxl Excel 对齐对象 Alignment

openpyxl包的Alignment类，属于模块openpyxl.styles.alignment，用于表示 Excel 中的对齐格式，其构造器如下。

Alignment(horizontal=None, vertical=None, textRotation=0, wrapText=None, shrinkToFit=None, indent=0, relativeIndent=0, justifyLastLine=None, readingOrder=0, text_rotation=None, wrap_text=None, shrink_to_fit=None, mergeCell=None)

horizontal 参数: horizontal参数是一个表示水平对齐方式的字符串，可以是以下值之一，'general'（常规），'left'（左对齐），'center'（居中对齐），'right'（右对齐），'fill'（填充，换行效果将被取消，并在需要时重复文字以占满整个行），'justify'（两端对齐，如果文字即将占满整个行，则扩大文字之间的距离，以占满整个行），'centerContinuous'（跨列居中，文字会在多个列内居中对齐，即便这些列没有合并），'distributed'（分散对齐，尝试扩大文字或单词之间的距离以占满整个行）。
vertical 参数: vertical参数是一个表示垂直对齐方式的字符串，可以是以下值之一，'top'（靠上对齐），'center'（居中对齐），'bottom'（靠下对齐），'justify'（两端对齐，尝试扩大行之间的距离以占满垂直空间），'distributed'（分散对齐，尝试扩大行之间的距离以占满垂直空间，如果只有一行，则该行会垂直居中）。
textRotation 参数: textRotation参数是一个表示文本的旋转角度的整数，比如，30表示逆时针旋转30度。
wrapText 参数: wrapText参数是一个布尔值，如果为True则表示启用自动换行。
shrinkToFit 参数: shrinkToFit参数是一个布尔值，如果为True则会在需要时缩小文字以显示全部。
indent 参数: indent参数是一个表示行首缩进大小的整数，取值范围在0至255之间。
relativeIndent 参数: relativeIndent参数是一个表示行首的相对缩进大小的整数，取值范围在-255至255之间。
justifyLastLine 参数: justifyLastLine参数是一个布尔值，如果为True则对最后一行文字采用两端对齐。
readingOrder 参数: readingOrder参数是一个表示文本方向的整数，1表示从左到右，2表示从右到左，0表示未设置文本方向。
text_rotation 参数: text_rotation参数与textRotation参数的作用相同。
wrap_text 参数: wrap_text参数与wrapText参数的作用相同。
shrink_to_fit 参数: shrink_to_fit参数与shrinkToFit参数的作用相同。
mergeCell 参数: mergeCell参数没有任何的作用。

Alignment 对象的变量

Alignment对象拥有变量horizontal，vertical，textRotation，wrapText，shrinkToFit，indent，relativeIndent，justifyLastLine，readingOrder，text_rotation，wrap_text，shrink_to_fit，mergeCell，在未作出修改时，他们的值与传递给Alignment构造器的实参的值相同。

align.py

from openpyxl.styles import Alignment


# 水平居中，垂直居中，自动换行
Alignment('center', 'center', wrapText=True)
# 需要时缩小文字，行首缩进大小 1
Alignment(shrinkToFit=True, indent=1)
# 文本方向从右到左
Alignment(readingOrder=2)

获取和设置 Excel 单元格的一般格式

Cell对象拥有名称为font，border，fill，alignment的变量，可将其类型视为Font，Border，PatternFill或GradientFill，Alignment类，他们被用于获取和设置 Excel 单元格的字体格式，边框格式，填充格式，以及对齐格式。

ReadOnlyCell对象拥有名称为font，border，fill，alignment的只读属性，其类型分别为Font，Border，PatternFill或GradientFill，Alignment类，可用于获取 Excel 单元格的字体格式，边框格式，填充格式，以及对齐格式。

cell|readonlycell.font cell|readonlycell.border cell|readonlycell.fill cell|readonlycell.alignment cell.font = font cell.border = border cell.fill = fill cell.alignment = alignment

font 值: font是一个表示单元格字体格式的Font对象。
border 值: border是一个表示单元格边框格式的Border对象。
fill 值: fill是一个表示单元格填充格式的PatternFill对象或GradientFill对象，。
alignment 值: alignment是一个表示单元格对齐格式的Alignment对象。

cell.py

# 读取 Excel 文件 Style.xlsx 中的工作表 Cell
from openpyxl import load_workbook
wb = load_workbook('Style.xlsx')
ws = wb['Cell']


from openpyxl.styles import Font, Border, PatternFill, Alignment, Color, Side


# 设置字体 Tahoma，15 磅，粗体，绿色，饱和度 50%
ws['A1'].font = Font('Tahoma', 15, True, color=Color('00FF00', tint=0.5))


# 显示蓝色的双实线对角线
ws['B2'].border = Border(diagonal=Side('double', color='0000FF'), diagonalUp=True, diagonalDown=True)


# 图案 lightDown，前景蓝色，背景红色
ws['C3'].fill = PatternFill('lightDown', Color('0000FF'), Color('FF0000'))


# 显示在右上角，在需要时缩小文字
ws['D4'].alignment = Alignment('right', 'top', shrinkToFit=True)


wb.save('Cell.xlsx')

不能通过 Cell 对象直接修改单元格的具体格式

对于Cell对象，你不能通过其font，border，fill，alignment变量修改单元格的具体格式，只能通过赋值一个新的Font，Border，PatternFill或GradientFill，Alignment对象来替换单元格的原有格式，否则将引发异常AttributeError: Style objects are immutable and cannot be changed.Reassign the style with a copy。

事实上，openpyxl包的设计者并未严格实施以上的策略，比如，通过Cell对象的font属性的color变量可以直接修改字体的颜色。

我们为上面的示例添加一些代码，直接修改A1单元格字体的具体格式，这将导致异常，但通过color变量修改字体颜色是可以的。

cell.py

# …
# 可以修改字体颜色
ws['A1'].font.color.rgb = 'FFFF00'
# ERROR 不能直接修改具体格式
ws['A1'].font.b = True

AttributeError: Style objects are immutable and cannot be changed.Reassign the style with a copy

获取和设置 Excel 单元格的数字格式

Cell对象拥有名称为number_format的字符串类型变量，可用于表示如何对 Excel 单元格中的数字进行格式化。

ReadOnlyCell对象拥有名称为number_format的字符串类型的只读属性，可用于获取 Excel 单元格中数字的格式化方式。

cell|readonlycell.number_format cell.number_format = format

format 值: format是一个表示如何对单元格中的数字进行格式化的字符串。

openpyxl.styles.numbers模块拥有一些名称以FORMAT开头的变量，他们是openpyxl包预先定义的 Excel 数字格式化方式。

在下面的示例中，我们设置了单元格E5的数字格式，他将使用千位分隔符，并在小于0时显示为红色。

num_format.py

# 读取 Excel 文件 Style.xlsx 中的工作表 Cell
from openpyxl import load_workbook
wb = load_workbook('Style.xlsx')
ws = wb['Cell']


# 使用千位分隔符，如果是负数，则显示为红色
ws['E5'].number_format = '#,##0;[RED]-#,##0'


wb.save('Format.xlsx')

获取和设置 Excel 行或列中的单元格格式

Worksheet和WriteOnlyWorksheet对象的变量row_dimensions和column_dimensions，他们的font，border，fill，alignment，number_format变量的类型分别为Font，Border，PatternFill或GradientFill，Alignment类以及str字符串，可用于获取和设置 Excel 行或列中的单元格的字体格式，边框格式，填充格式，对齐格式，数字格式。

Worksheet 和 WriteOnlyWorksheet 对象可能无法为拥有格式的单元格设置格式

如果Cell对象已经拥有格式，那么通过Worksheet或WriteOnlyWorksheet对象的row_dimensions或column_dimensions变量为其设置格式可能不会成功。

WriteOnlyWorksheet 对象应在写入数据之前设置单元格格式

应该在写入任何数据之前，使用WriteOnlyWorksheet对象的column_dimensions变量，为某一列中的单元格设置格式，否则格式可能不会生效。

应该在写入任何一行数据之前，使用WriteOnlyWorksheet对象的row_dimensions变量，为该行中的单元格设置格式，否则格式可能不会生效。

在下面的示例中，由于单元格A1，B2，D4（包括在代码执行过程中被设置了格式的单元格）拥有格式，因此，通过行和列设置的格式对他们可能无效。

row_col.py

# 读取 Excel 文件 Style.xlsx 中的工作表 Cell
from openpyxl import load_workbook
wb = load_workbook('Style.xlsx')
ws = wb['Cell']


from openpyxl.styles import Font, Border, PatternFill, Alignment, Side


# 为第一行设置字体 Arial，双实线下划线
ws.row_dimensions[1].font = Font('Arial', u='double')
# 为第二列设置红色底边
ws.column_dimensions['B'].border = Border(bottom=Side('dashed', 'FF0000'))
# 为第四列填充绿色
ws.column_dimensions['D'].fill = PatternFill('solid', '00FF00')
# 为第四行设置左下角对齐
ws.row_dimensions[4].alignment = Alignment('left', 'bottom')


wb.save('RC.xlsx')

内容分类

源码

src/zh/openpyxl/styles·codebeatme/office-programming·GitHub