When a user finishes editing, where the document goes and how it is stored is usually up to the business system. Saving in Spire.OfficeJS leaves that control with you: the editor only generates the current document in the browser, and you can either send it to a backend endpoint or handle it in the page. Whether it overwrites the original document, creates a new version, or saves a copy can follow your own rules. The examples below use Word to show how to save documents with Spire.OfficeJS:

• Document saving process
• Before you save
• Ways to save a document
  • Save a document with callbackUrl
  • Save a document with onSave
• FAQ

Document saving process

The save takes five steps. "Business page" in the figure refers to the page that hosts the editor; the term is used throughout below.

1. The user edits the document.
2. The user saves.
3. The editor generates the current document.
4. With callbackUrl, the document is sent to that address; with onSave, the business page receives it.
5. The editor shows "Saved successfully".

Before you save

Saving requires the following configuration:

• user.canSave set to true (the default).
• editorAttrs.editorMode set to edit.

Both examples below include these settings. Replace LocalExample with the actual deployment address.

Ways to save a document

Spire.OfficeJS supports two ways to save a document: use callbackUrl when the document should be saved by your backend, and use onSave when the page should handle the save result itself. The steps for each option are described below.

Save a document with callbackUrl

Use this when your backend saves the document. With callbackUrl configured, the editor sends the current document to that address on save, and the endpoint receives and stores it.

1. Create an .html page to open the document.
2. Configure the save endpoint in config.fileAttrs.callbackUrl.
3. Open the page, edit the document, and save. The editor shows "Saved successfully" once the endpoint returns success.

Example configuration:

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

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

Save a document with onSave

Use this when you have no save endpoint, or you want the page to handle the save result itself. On save, the editor calls onSave and passes the result in event.data:

• event.data[0] is the file name, a string such as sample.docx.
• event.data[1] is the current document content, a standard browser File object you can download or upload directly.

What you do with these two items is up to the page: download locally, upload to a backend, rename the document, or just show a message. The editor only generates the save result and calls the callback.

Example configuration (do not set callbackUrl in fileAttrs, or set it to empty):

var config = {
  fileAttrs: {
    fileInfo: 
    { name: 'sample.docx', 
      ext: 'docx', 
      primary: '001' },
    sourceUrl: 'http://LocalExample:3000/samples/sample.docx'
  },
  user: 
  { id: 'uid-1', 
    name: 'Jonn', 
    canSave: true
  },
  editorAttrs: {
    editorMode: 'edit',
    editorType: 'document',
    viewLanguage: 'en',
    useWebAssemblyDoc: true,
    serverless: {
      useServerless: true,
      baseUrl: 'http://LocalExample:3000'
    },
    events: {
      onSave: function (event) {
        var fileName = event.data[0]; // file name (FileName), e.g. sample.docx
        var file = event.data[1];     // file object (File), the current document
        var key = event.key;          // document key, equal to fileInfo.primary, e.g. 001

        // The handling below is entirely up to the page.
        // Example: download locally
        var url = URL.createObjectURL(file);
        var link = document.createElement('a');
        link.href = url;
        link.download = fileName;
        document.body.appendChild(link);
        link.click();
        document.body.removeChild(link);
        setTimeout(function () {
          URL.revokeObjectURL(url);
        }, 1000);
      },
      onDocumentStateChange: function (event) {
        console.log(event.data ? 'Unsaved' : 'Saved');
      }
    }
  }
};

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

This is what event.data looks like at an onSave :

FAQ

Will saving overwrite the original document automatically

Cause: Spire.OfficeJS does not write the edits back to sourceUrl automatically. Saving only generates the current document and hands it to your business system.

Solution: Handle it in the callbackUrl endpoint or the onSave callback: whether to overwrite the original document, create a new version, or save a copy is up to your business system.

Both callbackUrl and onSave are configured, but onSave does not run

Cause: When both are configured, callbackUrl takes precedence and onSave does not run; with neither, the editor offers no save function.

Solution: Keep only one save outlet. If the page should handle the document itself, remove fileAttrs.callbackUrl or set it to empty.

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.

Contract delivery usually calls for PDF, archiving may call for DOCX, and some pages also need to export HTML or TXT. Spire.OfficeJS converts the document currently in the editor into these formats and hands it to the browser for download. This article uses Word as an example to explain how to convert and download documents with Spire.OfficeJS:

• Document conversion and download process
• Using downloadAs
• Supported formats
• FAQ

Document conversion and download process

The download takes four steps:

1. The user opens a document in the editor.
2. The user clicks the convert-and-download button on the page, which calls docEditor.downloadAs() with the target format.
3. The editor converts the current document to the target format.
4. The browser downloads the document locally.

Using downloadAs

The editor provides the downloadAs() method to convert the current document to a specified format and hand it to the browser for download. You can call it once the editor is initialized; the conversion runs in the browser, and the result is a local copy.

Example configuration (converting to PDF):

var onDownloadAs = function () {
  docEditor.downloadAs({ format: 'pdf'});
};

format takes the target format's file extension and is case-insensitive.

Complete code:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Spire.OfficeJS Convert File - downloadAs</title>
  <style>
    html, body { height: 100%; margin: 0; }
    body { display: flex; flex-direction: column; }
    #editor { flex: 1; min-height: 0; }
    #editor iframe { width: 100%; height: 100%; border: 0; }
  </style>
</head>
<body>
  <button type="button" id="download" onclick="onDownloadAs()" disabled>Download PDF</button>
  <div id="editor"></div>
  <script src="http://LocalExample:3000/web/editors/spireapi/SpireCloudEditor.js"></script>
  <script>
    var SERVER = 'http://LocalExample:3000';
    var downloadButton = document.getElementById('download');

    var config = {
      fileAttrs: {
        fileInfo: { name: 'sample.docx', ext: 'docx' },
        sourceUrl: SERVER + '/samples/sample.docx'
      },
      user: { id: 'uid-1', name: 'Jonn' },
      editorAttrs: {
        editorMode: 'edit',
        editorType: 'document',
        viewLanguage: 'en',
        canDownload: true,
        useWebAssemblyDoc: true,
        serverless: { useServerless: true, baseUrl: SERVER },
        events: {
          onStart: function () {
            downloadButton.disabled = false;
          }
        }
      }
    };

    var docEditor = new SpireCloudEditor.OpenApi('editor', config);

    function onDownloadAs() {
      docEditor.downloadAs({ format: 'pdf' });
    }
  </script>
</body>
</html>

After selecting a document and clicking the download button, the editor converts it and the browser downloads the resulting PDF:

Supported formats

The formats you can convert to depend on the editor that opened the document. Word, Excel, and Presentation load on different pages and support different target formats, so pick the format for the editor that matches the document. The target formats supported by each editor are listed below:

FAQ

Does downloading modify the original document or trigger save callbacks

Cause: Downloading does not call callbackUrl or onSave, and it does not write back to sourceUrl; it only generates the document in the browser and downloads it.

Solution: No extra handling is needed. The download is a local copy; neither the original document nor the one in your business system is modified.

format is set, but the downloaded document's format does not change

Cause: If format is unrecognized, the document editor falls back to the document's original format.

Solution: Use the target formats listed for the matching editor in the supported formats table. For example, with sample.docx as the original and format: 'bogus', the downloaded document is still sample.docx.

Can multiple documents be converted at once

Cause: downloadAs() converts only the document currently open in the editor, and one call produces one document in the target format.

Solution: To convert multiple documents, open each document in turn and call downloadAs() for each one, for example by opening the next document after each conversion on the business page.

A valid License is required after Spire.OfficeJS is deployed. Without a License, opened documents show a red trial notice and the content is restricted: Word is limited to 500 paragraphs and 25 tables, Excel to 5 worksheets with up to 200 rows per worksheet, and Presentation and PDF to 10 pages. For details on the restrictions, see the trial version notes on the official download page.

After purchasing or applying for a trial, you will receive a license file in XML format, usually named license.elic.xml. Open the file with a text editor, copy the value of the Key attribute from the root element <License Key="..."> (without the quotes and tags), and fill it into the corresponding field in the table below. The file is digitally signed; do not modify it.

License configuration

The bundled example system and your own frontend project use the same license fields; only the location where you configure them differs. The licensed products and their corresponding fields are:

Whichever product you purchased, fill its License Key into the corresponding field, and leave the fields for products you have not purchased as empty strings "". For example, if you only purchased Spire.WordJS, fill in spireDocJsLicense:

"editorAttrs": {
  "spireDocJsLicense": "WordJS License Key",
  "spireXlsJsLicense": "",
  "spirePresentationJsLicense": "",
  "spirePdfJsLicense": "",
  "spireOfficeJsLicense": ""
}

If you purchased the Spire.OfficeJS suite license, fill in only spireOfficeJsLicense and leave the other four fields empty. The suite already includes Spire.WordJS, Spire.ExcelJS, Spire.PresentationJS, and Spire.PDFJS.

Where to configure the License depends on how you use Spire.OfficeJS: use the example system bundled with the product package for a quick trial, or integrate the editor into your own frontend project.

Option 1: Use the bundled example system (default port 3000)

When using the example system bundled with the product package, the license fields are located under server.customization in example/config/default.json. Only the license fields are listed below; leave the other settings unchanged:

"customization": {
  "spireDocJsLicense": "WordJS License Key",
  "spireXlsJsLicense": "",
  "spirePresentationJsLicense": "",
  "spirePdfJsLicense": "",
  "spireOfficeJsLicense": ""
}

After saving, restart the example service for the new configuration to take effect.

Option 2: Integrate into your own frontend project

In your own frontend project, the license fields are written under the editorAttrs object passed to the editor. For example, in Vue:

config.value = {
        "editorAttrs": {
            "spireDocJsLicense": "WordJS License Key",
            "spireXlsJsLicense": "",
            "spirePresentationJsLicense": "",
            "spirePdfJsLicense": "",
            "spireOfficeJsLicense": "",
        }
    };

Other frameworks work the same way: find editorAttrs in your configuration and fill in the same fields.

For complete integration steps for each framework, see: JavaScript, Vue, React, Angular.

Take effect and verify

After modifying editorAttrs, save and refresh the page for the changes to take effect. When only the frontend configuration is changed, there is no need to restart OfficeServer.

• Vue / React (Vite): hot reload usually applies the changes automatically. If the editor does not reload, refresh the page first; if that still does not work, run npm run dev.
• Angular: if the changes do not take effect, run ng serve.

After making the changes, open a document of a licensed product and check whether the red trial notice is gone. For a suite license, open one document each in Word, Excel, Presentation, and PDF to verify.