“详见第三章”“参见图 1”这类引用,如果靠手写章节号与图号,一旦调整顺序、增删章节,全文的引用就得逐一核对。交叉引用把引用目标登记为书签,引用处只保存书签名,更新域时再取最新内容,改顺序、加章节都不容易写错。
本文用 Spire.Doc for JavaScript 在浏览器中直接创建交叉引用。整个过程基于 WebAssembly 在浏览器端完成,无需安装 Office,也不依赖任何后端,文件始终留在用户的设备上。
本文介绍四个核心功能点:
有关安装和项目配置,请参考 React 项目中集成 Spire.Doc for JavaScript。下面的示例假定 Spire.Doc 已安装、WebAssembly 模块已初始化。
下文的示例基于一份云栈 WMS 技术白皮书,章节标题、图表题注与阅读指引都已写好,只是引用位置还空着:

为标题创建交叉引用
引用的稳定性来自书签。先给标题文字加上书签,再在引用处插入 REF 域,域代码里写字签名;标题文字变化后,只要书签还在,更新域就能同步引用。为标题创建交叉引用,用到的主要对象如下:
| 对象 | 作用 |
|---|---|
paragraph.AppendBookmarkStart(name) |
在段落中插入书签起始标记 |
paragraph.AppendBookmarkEnd(name) |
在段落中插入书签结束标记 |
paragraph.AppendField(name, FieldType.FieldRef) |
在段落末尾插入 REF 域 |
field.Code |
指定引用的书签名与开关 |
document.Bookmarks.FindByName(name) |
校验书签是否存在 |
具体操作步骤如下:
- 获取 Spire.Doc 的 WASM 模块,确认已就绪。
- 载入字体与示例文档,取到第一节的段落集合。
- 按整段文字定位三个章标题,用书签起始、结束标记把标题文字包起来。
- 在“阅读指引”段落末尾插入
REF域,域代码写字签名与\h开关。 - 保存结果文件,从 VFS 读出后触发浏览器下载。
为标题创建交叉引用的代码如下:
// 按文字定位段落:exact 为 true 时要求整段文字完全一致
const findParagraph = (paragraphs, text, exact = false) => {
for (let i = 0; i < paragraphs.Count; i++) {
const paragraph = paragraphs.get_Item(i);
const value = String(paragraph.Text).trim();
if (exact ? value === text : value.includes(text)) {
return paragraph;
}
}
return null;
};
// 把段落中已有的文字包进书签:先追加标记,再移动到文字前后
const wrapBookmark = (paragraph, name, endIndex) => {
const start = paragraph.AppendBookmarkStart(name);
const end = paragraph.AppendBookmarkEnd(name);
paragraph.ChildObjects.Remove(start);
paragraph.ChildObjects.Insert(0, start);
paragraph.ChildObjects.Remove(end);
paragraph.ChildObjects.Insert(
endIndex === undefined ? paragraph.ChildObjects.Count : endIndex,
end
);
};
function App() {
const addHeadingReferences = async () => {
// 获取 Spire.Doc 的 WASM 模块
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
// 载入字体与示例文档
await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
await window.spire.FetchFileToVFS('Whitepaper.docx', '', `${process.env.PUBLIC_URL}/data/`);
const doc = new docModule.Document();
doc.LoadFromFile('Whitepaper.docx');
const paragraphs = doc.Sections.get_Item(0).Body.Paragraphs;
// 三章标题各自加书签,书签范围就是整行标题文字
['第一章 系统概述', '第二章 部署方案', '第三章 运维保障'].forEach((title, index) => {
const heading = findParagraph(paragraphs, title, true);
if (heading) {
wrapBookmark(heading, `BM_Chapter${index + 1}`);
}
});
// 在“阅读指引”段落末尾写入三个 REF 域
const guide = findParagraph(paragraphs, '详细说明可参阅');
for (let i = 1; i <= 3; i++) {
if (i > 1) guide.AppendText('、');
const ref = guide.AppendField('Ref', docModule.FieldType.FieldRef);
ref.Code = `REF BM_Chapter${i} \\h`;
ref.Update();
}
guide.AppendText('。');
// 保存结果文件
const outputFileName = 'WhitepaperWithChapterRefs.docx';
doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Docx2013 });
doc.Dispose();
// 从 VFS 读出结果,触发下载
const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([fileArray], { type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = outputFileName;
a.click();
URL.revokeObjectURL(url);
};
return (
<div style={{ textAlign: 'center', height: '300px' }}>
<h1>标题交叉引用</h1>
<button onClick={addHeadingReferences}>
插入章节引用
</button>
</div>
);
}
export default App;
插入三个章节引用后的阅读指引:

\h 开关让引用可以点击跳转
\h 让引用结果成为指向书签的超链接,点击后光标跳到目标位置。省略该开关时,引用只显示文字,不响应点击。对外分发的文档建议保留该开关,阅读体验更好。
书签范围决定引用显示的内容
REF 域取的是书签范围内的文字。书签包住整行标题,引用就显示整行标题;只包住“第三章”三个字,引用就只显示“第三章”。创建书签时应先想清楚引用粒度,不要图省事把整段都包进去。上图的引用结果沿用了标题的字体与颜色,这是域结果跟随书签文字格式的正常表现;如果不希望引用处跟随标题样式,可以缩小书签范围,或在 Word 中选中引用结果单独设置格式。
为图表题注创建交叉引用
为图表题注创建交叉引用,做法与标题基本相同,差别在书签范围:题注段落里有“图 1”和说明文字两部分,通常只把编号包进书签,引用处才只显示“图 1”,后续更换说明文字也不影响引用。
具体操作步骤如下:
- 按整段文字定位题注段落“图 1 系统总体架构”。
- 在段首插入书签起始标记,在编号“图 1”之后插入结束标记,让书签只包住编号。
- 定位正文中以“系统总体架构如”结尾的句子,在其后追加
REF域。 - 补上“ 所示。”,更新域后保存并下载。
下面的代码沿用上文定义的 findParagraph 与 wrapBookmark,只保留题注引用部分:
function App() {
const addCaptionReference = async () => {
// 获取 Spire.Doc 的 WASM 模块
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
// 载入字体与示例文档
await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
await window.spire.FetchFileToVFS('Whitepaper.docx', '', `${process.env.PUBLIC_URL}/data/`);
const doc = new docModule.Document();
doc.LoadFromFile('Whitepaper.docx');
const paragraphs = doc.Sections.get_Item(0).Body.Paragraphs;
// 题注段落中“图 1”与说明文字是两段文字,endIndex 取 2 让书签只包住编号
const caption = findParagraph(paragraphs, '图 1 系统总体架构', true);
wrapBookmark(caption, 'BM_Figure1', 2);
// 正文“……系统总体架构如”之后追加 REF 域
const body = findParagraph(paragraphs, '系统总体架构如');
const figureRef = body.AppendField('FigRef', docModule.FieldType.FieldRef);
figureRef.Code = 'REF BM_Figure1 \\h';
figureRef.Update();
body.AppendText(' 所示。');
// 保存结果文件
const outputFileName = 'WhitepaperWithFigureRef.docx';
doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Docx2013 });
doc.Dispose();
// 从 VFS 读出结果,触发下载
const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([fileArray], { type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = outputFileName;
a.click();
URL.revokeObjectURL(url);
};
return (
<div style={{ textAlign: 'center', height: '300px' }}>
<h1>题注交叉引用</h1>
<button onClick={addCaptionReference}>
插入题注引用
</button>
</div>
);
}
export default App;
正文通过 REF 域引用图 1 的编号:

为什么不用 AddCaption 自动生成的书签
Word 桌面版插入题注时会顺带建立隐藏书签,Spire.Doc for JavaScript 的 AddCaption 则只写入 SEQ 编号域,文档里不会多出可供 REF 直接命中的书签,域代码里也就没有现成名称可填。与其在生成后猜测书签名,不如按本文做法,给题注中的编号手工加一个名字固定的书签。
表格题注的引用方式相同
表格题注“表 1 部署环境要求”用同一套做法:书签只包住编号,正文在“最低与推荐配置如”之后补一个 REF 域。
// 表格题注同样只包住编号
const tableCaption = findParagraph(paragraphs, '表 1 部署环境要求', true);
wrapBookmark(tableCaption, 'BM_Table1', 2);
const tableBody = findParagraph(paragraphs, '最低与推荐配置如');
const tableRef = tableBody.AppendField('TabRef', docModule.FieldType.FieldRef);
tableRef.Code = 'REF BM_Table1 \\h';
tableRef.Update();
tableBody.AppendText(' 所示。');
引用书签所在页码
引用书签所在页码,用的是 PAGEREF 域。它与 REF 域一样指向书签,取的内容却是书签所在页的页码,像“完整的环境准备清单见第 2 页”这样的说法就适合用它生成。
具体操作步骤如下:
- 给目标章节标题加书签,名称如
BM_Chapter2。 - 定位正文中“完整的环境准备清单见第”所在的段落。
- 追加
PAGEREF域,域代码为PAGEREF BM_Chapter2 \h。 - 在域前后补上空格与“页。”,更新域后保存并下载。
下面的代码沿用上文定义的 findParagraph 与 wrapBookmark,只保留页码引用部分:
function App() {
const addPageReference = async () => {
// 获取 Spire.Doc 的 WASM 模块
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
// 载入字体与示例文档
await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
await window.spire.FetchFileToVFS('Whitepaper.docx', '', `${process.env.PUBLIC_URL}/data/`);
const doc = new docModule.Document();
doc.LoadFromFile('Whitepaper.docx');
const paragraphs = doc.Sections.get_Item(0).Body.Paragraphs;
// 目标章节标题加书签
const chapter = findParagraph(paragraphs, '第二章 部署方案', true);
wrapBookmark(chapter, 'BM_Chapter2');
// 正文“……见第”之后写入 PAGEREF 域
const deploy = findParagraph(paragraphs, '完整的环境准备清单见第');
deploy.AppendText(' ');
const pageRef = deploy.AppendField('PageRef', docModule.FieldType.FieldPageRef);
pageRef.Code = 'PAGEREF BM_Chapter2 \\h';
pageRef.Update();
deploy.AppendText(' 页。');
// 保存结果文件
const outputFileName = 'WhitepaperWithPageRef.docx';
doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Docx2013 });
doc.Dispose();
// 从 VFS 读出结果,触发下载
const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([fileArray], { type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = outputFileName;
a.click();
URL.revokeObjectURL(url);
};
return (
<div style={{ textAlign: 'center', height: '300px' }}>
<h1>页码交叉引用</h1>
<button onClick={addPageReference}>
插入页码引用
</button>
</div>
);
}
export default App;
引用结果由图中的“见第 2 页”给出,同一页上的表格引用也已生效:

PAGEREF 与 REF 有什么区别
两个域都指向书签,取的内容不同:REF 取书签范围内的文字,PAGEREF 取书签所在页的页码。页码依赖分页结果,增删内容、调整字号都可能改变它,因此文档结构变动后需要重新更新域,才能得到准确页码。
更新域并校验失效引用
更新域并校验失效引用,是交付前要做的最后一步:交叉引用在目标变更后不会自己更新,书签被删除或改名时,引用处还会留下错误提示。稳妥的做法是在保存前统一更新全部域,并核对域代码里的书签名是否仍然存在。
具体操作步骤如下:
- 载入文档,为章节标题、图题注、表题注创建书签。
- 在阅读指引、正文与题注句子中写入
REF与PAGEREF域。 - 收集文档中现有的全部书签名称。
- 遍历
doc.Fields逐个调用Update(),同时从域代码解析书签名并比对。 - 记录缺失目标,确认无误后保存并下载。
更新域并校验失效引用的完整代码如下,辅助函数沿用上文:
function App() {
const updateAndVerify = async () => {
// 获取 Spire.Doc 的 WASM 模块
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
// 载入字体与示例文档
await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
await window.spire.FetchFileToVFS('Whitepaper.docx', '', `${process.env.PUBLIC_URL}/data/`);
const doc = new docModule.Document();
doc.LoadFromFile('Whitepaper.docx');
const paragraphs = doc.Sections.get_Item(0).Body.Paragraphs;
// 1. 标题书签与章节引用
['第一章 系统概述', '第二章 部署方案', '第三章 运维保障'].forEach((title, index) => {
const heading = findParagraph(paragraphs, title, true);
if (heading) {
wrapBookmark(heading, `BM_Chapter${index + 1}`);
}
});
const guide = findParagraph(paragraphs, '详细说明可参阅');
for (let i = 1; i <= 3; i++) {
if (i > 1) guide.AppendText('、');
const ref = guide.AppendField('Ref', docModule.FieldType.FieldRef);
ref.Code = `REF BM_Chapter${i} \\h`;
ref.Update();
}
guide.AppendText('。');
// 2. 图题注与引用
const caption = findParagraph(paragraphs, '图 1 系统总体架构', true);
wrapBookmark(caption, 'BM_Figure1', 2);
const figBody = findParagraph(paragraphs, '系统总体架构如');
const figRef = figBody.AppendField('FigRef', docModule.FieldType.FieldRef);
figRef.Code = 'REF BM_Figure1 \\h';
figRef.Update();
figBody.AppendText(' 所示。');
// 3. 表题注与引用
const tableCaption = findParagraph(paragraphs, '表 1 部署环境要求', true);
wrapBookmark(tableCaption, 'BM_Table1', 2);
const tableBody = findParagraph(paragraphs, '最低与推荐配置如');
const tableRef = tableBody.AppendField('TabRef', docModule.FieldType.FieldRef);
tableRef.Code = 'REF BM_Table1 \\h';
tableRef.Update();
tableBody.AppendText(' 所示。');
// 4. 章节页码引用
const pageBody = findParagraph(paragraphs, '完整的环境准备清单见第');
pageBody.AppendText(' ');
const pageRef = pageBody.AppendField('PageRef', docModule.FieldType.FieldPageRef);
pageRef.Code = 'PAGEREF BM_Chapter2 \\h';
pageRef.Update();
pageBody.AppendText(' 页。');
// 5. 收集现有书签名称
const bookmarkNames = new Set();
for (let i = 0; i < doc.Bookmarks.Count; i++) {
bookmarkNames.add(String(doc.Bookmarks.get_Item(i).Name));
}
// 6. 逐个更新域,并核对域代码中的书签名
const missing = [];
for (let i = 0; i < doc.Fields.Count; i++) {
const field = doc.Fields.get_Item(i);
field.Update();
const match = String(field.Code).match(/^(?:REF|PAGEREF)\s+(\S+)/i);
if (match && !bookmarkNames.has(match[1])) {
missing.push(match[1]);
}
}
if (missing.length > 0) {
console.warn('以下引用目标不存在:', [...new Set(missing)]);
}
// 保存结果文件
const outputFileName = 'WhitepaperWithReferences.docx';
doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Docx2013 });
doc.Dispose();
// 从 VFS 读出结果,触发下载
const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([fileArray], { type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = outputFileName;
a.click();
URL.revokeObjectURL(url);
};
return (
<div style={{ textAlign: 'center', height: '300px' }}>
<h1>更新交叉引用</h1>
<button onClick={updateAndVerify}>
更新并检查引用
</button>
</div>
);
}
export default App;
更新全部域后的白皮书:

引用失效时域会显示什么
书签名不存在或拼写不一致时,REF 域会显示 Error! Reference source not found.;PAGEREF 域找不到目标时可能得到一个无效页码,例如 -1。两者都不会中断程序,容易在生成环节被忽略,所以在保存前把域代码解析一遍、与书签列表比对,比交付后逐页检查更省事。
常见问题
更新域后仍显示 Error! Reference source not found.,怎么排查
先比对名称:书签名区分大小写,空格、全角与半角符号、下划线都不能混用,域代码里的名称要与 doc.Bookmarks 中实际存在的名称逐字一致。再确认书签确实包住了文字——起始标记在段首、结束标记在文字之后。定位困难时,把 doc.Bookmarks 中的所有名称打印出来,与每个域代码并排核对。
设置了 IsUpdateFields,在 Word 中打开时域为什么没有自动更新
IsUpdateFields 不能替代保存前的域更新,也不保证 Word 打开文档时重新计算全部域。更可控的做法是本文的方式:保存前遍历 doc.Fields 逐个调用 Update()。如果打开文档后发现页码或编号仍是旧值,在 Word 中全选后按 F9 可以手动更新。
AddCaption 添加的题注,能直接用 _Ref 书签引用吗
通常不行。Spire.Doc for JavaScript 的 AddCaption 会写入 SEQ 编号域,但文档中不会出现可供 REF 直接命中的 _Ref 书签,域代码里也就没有现成名称可用。建议按本文做法,给题注中的编号手工加一个名字固定的书签,引用关系更清楚。
引用的内容为什么和标题一样粗、一样大
REF 域取的是书签范围内的文字,结果沿用了这段文字的字体、字号与颜色,所以引用标题时会带上标题的样式。如果只想要“图 1”这样的短引用,把书签范围缩小到编号;如果希望引用处使用正文样式,可以在 Word 中选中引用结果单独设置格式。
在浏览器里生成带交叉引用的 Word,需要安装 Office 或上传文件吗
不需要安装 Office。Spire.Doc for JavaScript 基于 WebAssembly 在浏览器端读写文档,示例通过虚拟文件系统(VFS)在本地加载与保存,库本身不会把文件发往服务器。文件最终是否会离开设备,取决于你在页面上另外接入的代码。
获取免费许可证
如果您希望删除结果文档中的评估消息,或者摆脱功能限制,请该Email地址已收到反垃圾邮件插件保护。要显示它您需要在浏览器中启用JavaScript。获取有效期 30 天的临时许可证。







