如何使用Office.js API更新文档自定义属性对应的字段值？

问题 #

需要更新文档中所有已存在的自定义属性对应的字段值，当前使用insertText()函数无法生效，需找到正确的更新方法。

原代码问题 #

原代码尝试直接修改字段的result文本，但Word字段的result是动态生成的内容，直接调用insertText()无法持久更新，必须通过字段自身的更新机制来同步自定义属性的值。

修正后的代码 #

Word.run(function (context) {
    const customDocProps = context.document.properties.customProperties;
    // 加载所有自定义属性的items集合
    context.load(customDocProps, "items");

    return context.sync()
        .then(function () {
            // 没有自定义属性则直接返回
            if (customDocProps.items.length === 0) return;

            const fields = context.document.body.fields;
            // 加载字段的code和result属性
            context.load(fields, "items/code,items/result");

            return context.sync()
                .then(function () {
                    // 将自定义属性转为小写键的Map，方便快速匹配
                    const propMap = new Map();
                    customDocProps.items.forEach(prop => {
                        propMap.set(prop.key.toLowerCase(), prop.value);
                    });

                    // 遍历所有字段，处理DOCPROPERTY类型的字段
                    fields.items.forEach(field => {
                        const codeParts = field.code.trim().split(/\s+/);
                        // 确认是DOCPROPERTY字段
                        if (codeParts[0].toLowerCase() === "docproperty") {
                            // 提取属性名，去除两端的引号
                            const propName = codeParts[1].replace(/"/g, "").toLowerCase();
                            // 如果该属性存在且值不匹配，更新字段
                            if (propMap.has(propName) && field.result.text !== propMap.get(propName)) {
                                field.update();
                            }
                        }
                    });

                    // 统一提交所有更新操作
                    return context.sync();
                });
        });
}).catch(function (error) {
    debugger;
    console.log('错误: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('调试信息: ' + JSON.stringify(error.debugInfo));
    }
});

关键修改说明 #

• 替换更新方式：放弃insertText()，改用field.update()方法，Word的DOCPROPERTY字段会自动关联对应自定义属性，调用update()即可同步最新属性值到字段显示。
• 优化匹配逻辑：将自定义属性存入Map，避免嵌套循环，提升匹配效率；同时准确提取字段代码中的属性名（去除引号、统一小写），确保匹配准确。
• 批量操作提升性能：所有字段修改操作完成后统一调用context.sync()，减少API交互次数，提升运行效率。
• 精简冗余代码：移除了不必要的单个属性加载逻辑，直接加载所有自定义属性集合。

内容的提问来源于stack exchange，提问作者Baljeet