Python在Excel中添加与自定义文本框

在制作说明性表格、仪表盘或带批注的报表时，常规单元格往往难以承载大段说明文字或自由排版的注释。Excel 的文本框（TextBox）提供了一种独立于单元格网格的容器：它可以放置在任意位置、容纳多行文本、单独设置字体与背景，并且完全不影响周边单元格的数据与公式。

工作中需要批量生成带注释的 Excel 表格时，手动操作不仅效率低，也难以保持一致性，这时候借助程序操控文本框就变得非常可靠。本文会一步步说明，如何用 Python 在 Excel 工作表中插入文本框，并完成文本内容、对齐方式、字体、背景、内边距、自动换行等常见设置，以及读取和替换文本框中的文字。

为什么使用文本框而非普通单元格

将说明文字直接写入单元格，有时确实不够灵活。文本框拥有几项实用优势：

• 自由定位：可以悬浮在任意位置，不必受限于单元格的行列结构。
• 独立样式：字体、颜色、背景、边框都能单独设置，与表格主体样式完全解耦。
• 承载长文本：适合放置说明、注释、图例等多行内容，并借助自动换行保持排版整洁。
• 便于查找替换：可将文本框当作模板占位符的载体，实现批量填充或替换文字，非常适合自动化报表生成。

环境准备

处理 Excel 文本框，推荐使用 Spire.XLS for Python 库，通过 pip 直接安装：

pip install Spire.Xls

在脚本中按如下方式导入主模块与通用模块：

from spire.xls import *
from spire.xls.common import *

插入文本框并设置文本与对齐

在工作表中插入文本框，使用 sheet.TextBoxes.AddTextBox() 方法，参数依次为文本框所在的行、列、高度和宽度（均以 Excel 内部单位计）。插入后即可通过 Text 属性写入内容，并通过 HAlignment / VAlignment 控制文字的水平与垂直对齐方式。

from spire.xls import *
from spire.xls.common import *
workbook = Workbook()
workbook.Version = ExcelVersion.Version2013
sheet = workbook.Worksheets[0]
# 在第 2 行第 2 列插入文本框，高度 18、宽度 65 个单位
textbox = sheet.TextBoxes.AddTextBox(2, 2, 18, 65)
textbox.Text = "Spire.XLS for Python 是一款专业的 Excel Python API..."
textbox.HAlignment = CommentHAlignType.Center
textbox.VAlignment = CommentVAlignType.Center
workbook.SaveToFile("TextBox.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

需要注意，AddTextBox 的前两个参数（行、列）决定文本框左上角锚定在哪一个单元格位置，后两个参数决定它自身的尺寸，这与单元格本身的宽高并非同一套单位，设置时建议以实际显示效果为准进行调整。

设置字体与背景

文本框的文字外观通过富文本（RichText）机制来设置，可以精确控制从某个字符到另一个字符的区间字体。背景则通过 Fill 属性填充纯色，实现样式的灵活定制。

from spire.xls import *
from spire.xls.common import *
workbook = Workbook()
workbook.LoadFromFile("Template_Xls_5.xlsx")
sheet = workbook.Worksheets[0]
shape = sheet.TextBoxes[0]
# 创建字体并设置属性
font = workbook.CreateFont()
font.FontName = "Century Gothic"
font.Size = 10
font.IsBold = True
font.Color = Color.get_Blue()
# 将字体应用到整个文本框文本
rt = RichText(shape.RichText)
rt.SetFont(0, len(shape.Text) - 1, font)
# 设置纯色背景
shape.Fill.FillType = ShapeFillType.SolidColor
shape.Fill.ForeKnownColor = ExcelColors.BlueGray
workbook.SaveToFile("SetFontAndBackground.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

这里 RichText.SetFont(start, end, font) 的三个参数分别为起始索引、结束索引和字体对象，索引从 0 开始、包含两端。如果只需对整段文本统一设置样式，用 0 到 len(text) - 1 覆盖全部字符即可；当需要局部高亮时，再传入对应的区间就能实现差异化效果。

设置内边距与自动换行

当文本框内文字较多时，可以通过内边距属性控制文字与边框的间距，并借助 IsWrapText 开启自动换行，避免文字溢出或过度拥挤，确保排版美观。

from spire.xls import *
from spire.xls.common import *
workbook = Workbook()
workbook.LoadFromFile("Template_Xls_4.xlsx")
sheet = workbook.Worksheets[0]
textbox = sheet.TextBoxes.AddTextBox(4, 2, 100, 300)
textbox.Text = "在 Excel 中插入文本框并设置内边距"
textbox.HAlignment = CommentHAlignType.Center
textbox.VAlignment = CommentVAlignType.Center
# 设置文本框内部边距
textbox.InnerLeftMargin = 1
textbox.InnerRightMargin = 3
textbox.InnerTopMargin = 1
textbox.InnerBottomMargin = 1
workbook.SaveToFile("SetInternalMarginOfTextbox.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

对于已存在且文字较长的文本框，直接开启自动换行即可：

from spire.xls import *
from spire.xls.common import *
workbook = Workbook()
workbook.LoadFromFile("TextBoxSampleB.xlsx")
sheet = workbook.Worksheets[0]
shape = sheet.TextBoxes[0]
shape.IsWrapText = True
workbook.SaveToFile("TextBoxWithWrapText.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

内边距的单位是磅（point），数值越大文字离边框越远；自动换行会让文本框根据内容在设置好的尺寸内重新排列行，两者配合使用能显著改善长文本的排版观感，让单元格注释更清晰易读。

读取与替换文本框中的文本

文本框本质上是文档中的可访问对象，通过遍历 sheet.TextBoxes 即可读取或批量替换其中的文字，这非常适合用作模板占位符的填充，大幅提升自动化处理效率。

from spire.xls import *
from spire.xls.common import *
workbook = Workbook()
workbook.LoadFromFile("ReplaceTextInTextBox.xlsx")
sheet = workbook.Worksheets[0]
# 遍历所有文本框，替换指定文本
for tb in sheet.TextBoxes:
    if tb.Text != "" and "" in tb.Text:
        tb.Text = tb.Text.replace("", "Spire.XLS for .NET")
workbook.SaveToFile("ReplaceTextInTextBox.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

如果文档中文本框较多，还可以为文本框命名，之后按名称直接定位，而不必依赖索引，使代码更清晰易维护：

from spire.xls import *
from spire.xls.common import *
workbook = Workbook()
sheet = workbook.Worksheets[0]
textbox = sheet.TextBoxes.AddTextBox(2, 2, 18, 65)
textbox.Name = "FirstTextBox"
textbox.Text = "需要被检索的说明文字"
# 按名称获取文本框
found = sheet.TextBoxes["FirstTextBox"]
print(found.Text)
workbook.Dispose()

命名方式在生成大量带标识的文本框时尤为实用，例如把每个说明框命名为"注释_客户信息""注释_费用说明"等，后续维护就能精准命中目标，显著提升脚本的可读性和可维护性。

实用建议

• 区分锚定与尺寸：AddTextBox(row, col, height, width) 中行列决定锚点，高度宽度决定文本框自身大小，两者单位不同，初次使用建议小范围试值，以确认实际显示效果。
• 替换前先判空：遍历替换时加上 tb.Text != "" 的判断，可避免空文本框引发的意外错误，确保脚本稳定运行。
• 字号与背景搭配：浅色背景配深色文字、深色背景配浅色文字，能提升文本框在密集报表中的可读性，让注释更突出。
• 及时释放资源：批量处理多份工作簿后，记得调用 Dispose() 释放内存，避免文件句柄占用，确保长期运行不卡顿。

总结

本文围绕 Excel 文本框的常见操作，介绍了插入文本框并设置文本对齐、设置字体与背景、调整内边距与自动换行，以及读取和替换文本框文字四个核心方向。这些功能的统一入口是工作表的 sheet.TextBoxes 集合：AddTextBox() 负责创建，Text 与 RichText 负责内容与样式，Fill 负责背景，Inner*Margin 与 IsWrapText 负责排版，而遍历或按名称访问则支撑了批量维护与自动化处理。

在此基础上，还可以将文本框与图表、形状、数据验证等功能组合使用，例如为图表添加带说明的文本框、在仪表盘里用文本框承载动态提示语，从而让自动生成的 Excel 文档既数据严谨又说明清晰，大幅提升工作效率。