For many business systems, previewing a document means asking the user to download it and open it locally, or relying on a browser plug-in. Spire.OfficeJS supports opening documents directly in the page, and users do not need to install Office. The document can come from an address the business system can already access or from the user's local selection. This article uses Word as an example to explain how to open documents with Spire.OfficeJS:

• Document opening process
• Ways to open a document
  • Open a document with sourceUrl
  • Open a document with fileData
• FAQ

Document opening process

The figure and steps below describe the process of opening a document. "Business page" refers to the page in your own business system that hosts the editor.

1. The user opens the document through the business page to view or edit it.
2. The business page prepares the config: sourceUrl (or serverless.fileData), fileInfo, user, and editorAttrs.
3. SpireCloudEditor.OpenApi creates the editor iframe.
4. In sourceUrl mode, the browser reads the document from your business storage; in fileData mode, the bytes passed in by the page are used directly.
5. WebAssembly converts the Office document into the editor's internal format, and the internal JavaScript renders the content on the page.

Ways to open a document

Spire.OfficeJS supports two ways to open a document: use sourceUrl when the document already has an accessible URL, and use fileData when the document comes from the user's local selection and has not been uploaded yet. The steps for each option are described below.

Open a document with sourceUrl

Use this option when the document already has an accessible URL. Create an empty .html file and add the key content following the steps below; replace LocalExample with the actual deployment address.

1. Add the editor container:

   <div id="editor"></div>
   

2. Include the editor script:

   <script src="http://LocalExample:3000/web/editors/spireapi/SpireCloudEditor.js"></script>
   

3. Prepare the config. The important parts are the document URL and the web resource URL:

   var config = {
     fileAttrs: {
       fileInfo: { name: 'sample.docx', ext: 'docx' },
       sourceUrl: 'http://LocalExample:3000/samples/sample.docx'
     },
     user: { id: 'uid-1', name: 'Jonn' },
     editorAttrs: {
       editorMode: 'edit',
       editorType: 'document',
       viewLanguage: 'en',
       useWebAssemblyDoc: true,
       serverless: {
         useServerless: true,
         baseUrl: 'http://LocalExample:3000'
       }
     }
   };
   

4. Initialize the editor:

   new SpireCloudEditor.OpenApi('editor', config);
   

Open a document with fileData

Use this option when the document comes from the user's local selection and has not been uploaded yet. The page structure is the same as in the sourceUrl option (container + editor script); the difference is that you add a file selector and put the document bytes into serverless.fileData.

1. Add the file selector and the editor container:

   <input type="file" id="fileInput" accept=".doc,.docx">
   <div id="editor"></div>
   

2. Read the file, build the config, and initialize:

   var opened = false;
   
   document.getElementById('fileInput').addEventListener('change', function (e) {
     var file = e.target.files[0];
     if (!file) return;
   
     var ext = file.name.split('.').pop().toLowerCase();
     var reader = new FileReader();
   
     reader.onload = function (event) {
       var config = {
         fileAttrs: {
           fileInfo: { name: file.name, ext: ext },
           sourceUrl: 'offline' // placeholder; it is not requested in fileData mode
         },
         user: { id: 'uid-1', name: 'Jonn' },
         editorAttrs: {
           editorMode: 'edit',
           editorType: 'document',
           viewLanguage: 'zh',
           useWebAssemblyDoc: true,
           serverless: {
             useServerless: true,
             baseUrl: 'http://LocalExample:3000',
             fileData: event.target.result
           }
         }
       };
   
       var targetId = opened ? 'SpireCloudEditor' : 'editor';
       opened = true;
       new SpireCloudEditor.OpenApi(targetId, config);
     };
   
     reader.readAsArrayBuffer(file);
   });
   

FAQ

sourceUrl is configured but the document fails to load

Cause: The document is read directly by the browser. If sourceUrl cannot be reached, the editor cannot get the document and it will not open.

Solution: Set sourceUrl to an address the browser can open directly, and make sure the document can be accessed in the browser.

Do I need sourceUrl when using the fileData option

Cause: In fileData mode, the editor uses the bytes passed in by the page directly and does not request sourceUrl; however, sourceUrl must not be empty.

Solution: Set sourceUrl to a placeholder value such as offline.

The document content is incomplete and a watermark is shown

Cause: A valid license is not configured, or the license does not match the product that opens the document. Without a license, the editor shows red watermark text in the document and limits the document length, so the content is displayed incompletely.

Solution: Fill in the license field for the corresponding product in editorAttrs; for example, fill in spireDocJsLicense for WordJS. If you use the bundled example system, configure the License Key under server.customization in example/config/default.json.

The Spire.OfficeJS review feature records modifications as revision marks instead of overwriting the original text. This state is often called review mode (also known as track-changes mode), where all changes are kept as suggestions layered over the original text, waiting for a reviewer to handle them. Once Track Changes is on, insertions, deletions, and formatting adjustments are recorded with their author, and other people can inspect, accept, or reject them one by one. This article uses Word as an example to explain the operations and permission configuration. In this article, "review" refers to the revision-related features on the Review tab.

• Review
  • Review Tab Capabilities
  • Configure Review Capabilities
  • Control Review-Related Buttons
  • FAQ

Review Tab Capabilities

The Review tab in the Word editor provides the following revision-related capabilities:

The following sections explain display modes and the accept and reject operations. The other capabilities can be used directly from the locations listed in the table.

Display Modes

Accept and Reject Revisions

"Accept" and "Reject" process one revision at a time by default and then jump to the next one. The drop-down menu can process all revisions at once, or you can click a revision mark in the body text to choose directly. Accepting or rejecting changes the body text directly, and you can undo before saving.

Configure Review Capabilities

Revision capabilities are controlled by editorAttrs: canReview determines whether review is enabled, and canEdit determines whether editing is allowed.

editorAttrs: {
  editorMode: 'edit',
  canEdit: true,
  canReview: true
}

Review State on Open

The review state when a document opens is controlled by two switches under user.customization.public.common. Both are false by default, and you can turn them on individually as needed:

• openReviewChanges: true: enters the track-changes state immediately after the document opens, so you do not need to click "Track Changes" manually.
• openReviewPanel: true: expands the reviewing pane when the document opens, suitable for handling revisions in one place, and requires canReview to be true.

user: {
  customization: {
    public: {
      common: {
        openReviewChanges: true, // enters the track-changes state immediately after the document opens
        openReviewPanel: true    // expands the reviewing pane when the document opens
      }
    }
  }
}

Read-Only Review

External reviewers can only view revisions and the reviewing pane. They cannot change the body text, and they cannot accept or reject revisions:

editorAttrs: {
  editorMode: 'edit',
  canEdit: false,
  canReview: true
}

Disable Review

editorAttrs: {
  canReview: false
}

Users can still edit normally, but the Review tab no longer provides revision-related capabilities.

Control Review-Related Buttons

canReview only toggles the review capability as a whole. If you want to hide only some buttons (for example, keep viewing and navigation but remove "Accept" and "Reject"), configure user.customization.public.common.btnPermissions.docBtnPermissions. Removed buttons and their corresponding shortcuts are disabled as well:

user: {
  customization: {
    public: {
      common: {
        btnPermissions: {
          docBtnPermissions: [
            { modular: 'Toolbar', subModule: ['btnTurnOn', 'Accept', 'Reject'] }
          ]
        }
      }
    }
  }
}

For more about button permission configuration, see the documentation on customizing the toolbar menu.

FAQ

The Track Changes toggle or Accept/Reject buttons are unavailable

Common causes are that the current session is in read-only review (canEdit: false, canReview: true), the document is protected, or the user does not have edit permission. Read-only review can view revisions but cannot toggle Track Changes or accept or reject revisions. If a reviewer needs to handle revisions, they must be given edit permission. If they need to handle revisions but should not change the body text freely, enable "Restrict Editing → Tracked Changes", so that all modifications can only be produced as tracked changes.

The Review tab is not visible after opening a document

Check the following in order:

1. Whether editorAttrs.editorMode is edit. view mode does not provide editing or review.
2. Whether editorAttrs.canReview is true, and whether both canEdit: true and a valid license are available.
3. Whether btnReview was removed through btnPermissions, or the document is protected as read-only.

Revision authors are wrong or all the same

Revision authors come from user.name in the current session, and the user identity comes from user.id. Make sure each user uses a unique, stable id, pass the correct display name when opening the document, and do not let multiple users share a fixed account.