使用 Python 在 Word 文档中添加、修改和删除变量

Word 里除了看得见的文字、表格和图片，还藏着一层看不见的数据，也就是文档变量。它是一组挂在文档的键值对，不占用正文的任何位置，却可以随文件一起保存、分发，常被用来记录模板的版本号、客户编号、审批状态这类元信息。做合同模板、报告模板的人对它应该不陌生：正文里的内容可以千变万化，但某些标记性的信息需要一直跟着文档走。

真正让文档变量有用的，是它和 DocVariable 域的配合。变量本身只是存值的仓库，想让某个值出现在正文中，需要插入一个同名的 DocVariable 域，由域去取值显示。这样一来，只要改变量的值，再刷新域，正文里的内容就跟着变了，这正是模板批量生成的底层机制。

本文用 Spire.Doc for Python，完整走一遍文档变量的增、改、删、读：先讲清变量与域的对应关系，再分别演示添加、读取、修改和删除，最后用一个批量更新模板变量的综合示例把它们串起来。

环境准备

本文使用 Spire.Doc for Python，文档变量通过 Document.Variables 集合访问。通过以下命令安装：

pip install Spire.Doc

安装完成后，同时导入 spire.doc 与 spire.doc.common 两个模块即可开始使用。

先弄清一件事：变量与 DocVariable 域

在写代码之前，这个关系必须先建立起来，否则很容易出现"变量加了但文档里什么都看不到"的困惑。

文档变量是一组键值对，比如 A1 = 12，它只存在于文档的属性里，打开 Word 的正文界面是看不到的。要让这个值显示出来，得在段落里插入一个 DocVariable 类型的域，域的名称与变量名一致（都叫 A1），Word 渲染时就会去变量集合里取出对应的值填进去。所以完整的一条链路是：建变量 → 插同名域 → 更新域 → 保存。

其中"更新域"这一步由 document.IsUpdateFields 属性控制。把它设为 True，保存时 Spire.Doc 会刷新所有域的内容；如果漏了这一步，域里显示的仍是插入时的旧值，改过的变量不会生效。这是本篇最容易踩的坑，后面每个示例都会带上它。

添加变量并让它在正文显示

先在段落里插一个 DocVariable 域把"显示位"占住，再用 Variables.Add 把对应的变量名和值写进文档。两边的名称必须完全一致，域才能准确读到内容。为了让演示效果更直观，我们在代码里加了几个带有文字标签的字段，模拟出一份带有标题和具体条目的订单确认函模板。

from spire.doc import *
from spire.doc.common import *

outputFile = "AddVariables.docx"

# 创建文档与节
document = Document()
section = document.AddSection()

# 添加标题段落
p1 = section.AddParagraph()
p1.AppendText("--- 销售订单确认函 ---")

# 添加带有域的段落：客户名称
p2 = section.AddParagraph()
p2.AppendText("客户名称：")
p2.AppendField("ClientName", FieldType.FieldDocVariable)

# 添加带有域的段落：订单金额
p3 = section.AddParagraph()
p3.AppendText("订单金额：")
p3.AppendField("OrderAmount", FieldType.FieldDocVariable)

# 向文档变量集合中添加对应的变量及取值
document.Variables.Add("ClientName", "上海某某科技有限公司")
document.Variables.Add("OrderAmount", "58,000 元")

# 保存前更新域，让域显示变量的当前值
document.IsUpdateFields = True

document.SaveToFile(outputFile, FileFormat.Docx2013)
document.Close()

AppendField 的第一个参数是域名，第二个参数指定域的类型------只有 FieldDocVariable 才会去读取文档变量。Variables.Add 负责真正的写值，所有数值或文本一律以字符串形式存放。最后加上 IsUpdateFields = True 保证保存时自动刷新，这样打开生成的文档就能直接看到正文里整洁的填充效果了。

读取变量：按名称或按索引

读取有三种入口，覆盖不同场景：知道名称时直接按名取值；需要遍历全部时按索引取名称和值；只想知道有多少个时读 Count。下面的例子把三种方式放在一起，遍历输出每个变量的名称与值。

from spire.doc import *
from spire.doc.common import *

document = Document()
document.LoadFromFile("/AddVariables.docx")

# 按名称直接取值（改成实际存在的变量名）
value_by_name = document.Variables["ClientName"]

# 遍历全部变量：按索引取名称与值
for i in range(document.Variables.Count):
    name = document.Variables.GetNameByIndex(i)
    value = document.Variables.GetValueByIndex(i)
    print("Name: " + name + ", Value: " + value)

print("变量总数：" + str(document.Variables.Count))
print("ClientName 的值：" + str(value_by_name))

document.Close()

Variables["ClientName"] 这种下标写法最直观，适合已知变量名的场景；GetNameByIndex(i) 与 GetValueByIndex(i) 则是一对"按位置"的访问器，配合 Count 就能完整枚举------这在处理来源不明的模板时特别有用，先把所有变量列出来，才知道有哪些键可以操作。返回值都是字符串，需要参与数值计算时要自己转换类型。

修改变量：删掉旧值再写新值

由于文档变量集合提供的是 Add 和 Remove，并没有单独的 Update 方法。因此本章我们通过先移除同名变量，再以同一名称写入新值来实现修改变量。名称保持不变，正文里的域就仍然能对上，刷新后自然显示新内容。

from spire.doc import *
from spire.doc.common import *

document = Document()
# 加载前面生成的订单确认函文档
document.LoadFromFile("/AddVariables.docx")

# 先移除旧的订单金额变量
document.Variables.Remove("OrderAmount")

# 再以同名写入修改后的新值，等效于更新变量
document.Variables.Add("OrderAmount", "62,000 元")

# 刷新域，让正文显示更新后的数值
document.IsUpdateFields = True

document.SaveToFile("/ModifyVariable.docx", FileFormat.Docx2013)
document.Close()

删除变量

删除只需一个 Remove 调用，传入变量名即可。与修改一样，删除后同样要刷新域------否则正文里可能还残留着上一次渲染出来的文本。

from spire.doc import *
from spire.doc.common import *

document = Document()
document.LoadFromFile("Template_Docx_6.docx")

# 按名称移除变量
document.Variables.Remove("A1")

# 刷新域
document.IsUpdateFields = True

document.SaveToFile("RemoveVariables.docx", FileFormat.Docx2013)
document.Close()

值得注意的是，Remove 只删变量，段落里那个 DocVariable 域还在。域找不到同名变量时，通常显示为空或保留旧文本，取决于文档的具体状态。如果目的是让正文里那一处内容也彻底消失，还需要另外处理该域；如果只是不想再让这个值随文档流转，删变量就够了。

综合示例：批量更新模板里的变量

实际使用中，模板里往往不止一个变量------客户名称、合同编号、签署日期可能各占一个。这时更实用的做法是：遍历全部变量，用一个"旧值 → 新值"的映射表决定改哪些，逐个执行"删旧写新"，最后统一刷新并保存。

from spire.doc import *
from spire.doc.common import *

document = Document()
document.LoadFromFile("Template_Docx_6.docx")

# 待更新的映射：变量名 -> 新值
updates = {
    "A1": "2026",
    "A2": "华东区",
    "A3": "已审批",
}

# 遍历全部变量，命中的逐个替换
for i in range(document.Variables.Count):
    name = document.Variables.GetNameByIndex(i)
    if name in updates:
        document.Variables.Remove(name)
        document.Variables.Add(name, updates[name])

document.IsUpdateFields = True
document.SaveToFile("BatchUpdateVariables.docx", FileFormat.Docx2013)
document.Close()

这段代码把"读取 + 修改"两步合成了一次遍历：先按索引拿到变量名，与映射表比对，命中就执行删旧写新。由于 Remove 会让集合长度变化，遍历时用 Count 作为上界需要在删除后格外小心；稳妥的写法是先收集所有需要修改的名称，再对这份名单逐个处理。示例中的映射表也可以换成从配置文件、数据库或命令行参数读入，模板就能做成"同一份文件、按批次填不同数据"的形态。

实用技巧

• IsUpdateFields 是必须项 ：凡是改动过变量，保存前都要把它设为 True。漏掉这一步，是"改了没效果"最常见的原因。
• 变量不显示属正常 ：变量只是键值对，正文里看不见它。要显示就必须有同名的 FieldDocVariable 域。
• 名称就是契约 ：域与变量靠名称字符串绑定，大小写、空格都要一致。命名建议用有意义的英文短名（如 CustomerName），避免 A1、A2 这类难以维护的编号。
• 值统一按字符串处理 ：Variables.Add 接收的是字符串，数字、日期都要先格式化再写入。
• 保存格式按需选择 ：示例用 FileFormat.Docx2013，若下游只认 2007 版格式，可换成 FileFormat.Docx。

总结

Word 文档变量其实就像是藏在文档后台的"数据字典"，它们独立于正文内容存在。通过这套机制，你可以灵活地对这些变量进行管理：无论是新建并插入对应的占位符、读取当前数值、通过覆盖来实现更新，还是直接清理不再需要的变量，操作都非常直观。只要在修改完成后记得刷新一下文档的域，保存出来的文件就会自动呈现出最新的内容。这种"数据驱动"的设计让 Word 模板变得极为高效------你只需要固定好页面的排版结构，把具体内容交由外部数据动态填充，就能通过简单地替换变量值，轻松实现海量个性化文档的自动化批量生成。