使用 Python 在 Excel 中添加和自定义文本框

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

当需要在自动化流程中批量生成这类带注释的表格时，用程序操控文本框比手工绘制更高效，也更容易保持一致。本文将介绍如何用 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 "<TAG_1>" in tb.Text: tb.Text = tb.Text.replace("<TAG_1>", "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 文档既数据严谨又说明清晰