Office Online中通过Office-js更新SharePoint文档元数据的正确方案咨询

Got it, let's break down why this happens and the correct way to update SharePoint document metadata in Word Online.

First, the key difference between desktop Word and Word Online here is how they sync with SharePoint. On desktop, modifying that specific Custom XML part (the one with the http://schemas.microsoft.com/office/2006/metadata/properties schema) triggers a sync with SharePoint's metadata store—this is a legacy behavior tied to desktop Office's deep integration. But Word Online's architecture doesn’t use that same sync pipeline; directly editing the XML part there won’t push changes back to SharePoint, which is why you end up with mismatched data.

The right approach is to use Office JS's built-in document properties APIs, which are designed to work consistently across both desktop and online environments. Here's how to do it:

1. Update built-in metadata fields (like Title, Author) #

For standard SharePoint columns that map to Office's built-in properties, you can set them directly and save:

// Update the document Title (maps to SharePoint's Title column)
Office.context.document.properties.title = "Updated Document Title";
// Save changes to sync with SharePoint
Office.context.document.saveAsync(function(result) {
  if (result.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Built-in metadata updated successfully");
  } else {
    console.error("Error saving: " + result.error.message);
  }
});

2. Update custom SharePoint metadata columns #

Custom SharePoint columns are exposed as custom document properties in Office JS. Use the customProperties object to read, modify, and save these:

// Get existing custom properties
Office.context.document.properties.customProperties.getAsync(function(getResult) {
  if (getResult.status === Office.AsyncResultStatus.Succeeded) {
    const props = getResult.value;
    // Update your custom SharePoint column (replace "ProjectID" with your column name)
    props.set("ProjectID", "PROJ-12345");
    // Optional: Set multiple properties at once
    props.set("ClientName", "Acme Corp");
    
    // Save changes to sync with SharePoint
    props.saveAsync(function(saveResult) {
      if (saveResult.status === Office.AsyncResultStatus.Succeeded) {
        console.log("Custom metadata synced to SharePoint");
      } else {
        console.error("Failed to save properties: " + saveResult.error.message);
      }
    });
  } else {
    console.error("Failed to retrieve properties: " + getResult.error.message);
  }
});

Why this works for Word Online #

The Office JS customProperties API is directly integrated with SharePoint's metadata layer in the online environment. When you call saveAsync, Word Online triggers a proper sync with SharePoint, ensuring both the document's properties and the SharePoint list item's columns stay in sync—no more mismatched data from editing XML parts directly.

Quick notes to avoid issues #

• Permissions: Make sure your add-in manifest includes the ReadWriteDocument permission level (or a more specific one if needed) to modify document properties.
• Document location: The document must be saved directly to SharePoint (not a local draft) for the metadata to sync properly.
• Batch updates: If you're updating multiple fields, set all properties first then call saveAsync once—this is more efficient than multiple save calls.

This method will work reliably across both desktop Office and Word Online, so you don't have to maintain separate logic for each environment.

内容的提问来源于stack exchange，提问作者Leander van Eck