Repository navigation
JavaScript API
Spreadsheet Viewer comes with an official JavaScript API, which is a JavaScript module that wraps around our low-level Web Messaging API.
The JavaScript API is very easy to use. As a developer, integrating Spreadsheet Viewer into your app, you need to prepare a DOM node that is a container the viewer and pass a reference to that node to the function SpreadsheetViewer. When the promise returned by SpreadsheetViewer is resolved, you can use helper methods to pass a spreadsheet file to the viewer and observe interaction events.
JavaScript API uses ES6 Promise. Promise is available in any modern JavaScript engine. However, it is not available natively in IE11. If your app supports IE11, your code must load a polyfill that includes Promise. In our demo, we are using CoreJS 2 polyfill for that (example), but other polyfills are equally good.
Usage of the JavaScript API is presented in the Quick Start examples included in the Spreadsheet Viewer ZIP package.
function SpreadsheetViewer(configuration): Promise<SpreadsheetViewerInstance>
The basis of the JavaScript API is the SpreadsheetViewer function that takes a configuration object as the parameter and returns a promise of a SpreadsheetViewerInstance object.
The configuration object describes the environment in which the Spreadsheet Viewer iframe will be installed. It contains the following properties:
-
container- Required. A DOM element (preferably an empty div), where the Spreadsheet Viewer iframe will be injected. This DOM element can be styled upon your liking. It will be fully filled with a borderless iframe. -
assetsUrl- Required. The URL to theindex.htmlfile of the Spreadsheet Viewer frame. The URL should end withindex.html(and, optionally, with a URL query string for the Query String API parameters)). The URL can either be absolute or relative to the web address that is visible in the browser's address bar of your app. If the assets are served from a different origin (for strict security), make sure that the server includes proper CORS headers.
The return value is a promise that resolves with a SpreadsheetViewerInstance object, when the iframe's static application assets (internal CSS, JS files) are fully loaded and available for use.
Before the promise is resolved, the iframe displays a static loading screen and rejects any communication from the host app.
Note about cold vs hot start. We call it a "hot start" if you keep the iframe hidden until the promise is resolved, or a "cold start" if you display the iframe before the promise is resolved. All our code samples demonstrate a "hot start" because the user experience is superior.
Example:
import { SpreadsheetViewer } from `./clientLibrary`;
const sv = SpreadsheetViewer({ container: document.querySelector('#spreadsheet-viewer') });
sv.then(function(spreadsheetViewerInstance) {
spreadsheetViewerInstance.loadWorkbook(workbookUrl, 0, 'the-file.xlsx');
});The SpreadsheetViewerInstance extends the Window interface of the Spreadsheet Viewer iframe with additional methods and events. The methods are used to trigger request messages to the iframe and the events are used to catch callback messages from the iframe.
You can call these methods directly on the SpreadsheetViewerInstance object.
Request message that reconfigures up the internal state of the Spreadsheet Viewer iframe in the runtime.
The only argument is an object with the following properties:
-
themeStylesheet: Optional. A string representing the name of the built-in theme (color scheme) which can be eitherlightordark. Default value:dark -
licenseKey: Optional. A string representing Spreadsheet Viewer license key. Default value: empty string (meaning: unlicensed)
Request message to Spreadsheet Viewer to render a file. Provided a URL, Spreadsheet Viewer will download and render the file. Provided a Data URL or an ArrayBuffer, Spreadsheet Viewer will render the file contents without additional downloading.
While loading and parsing the workbook file, Spreadsheet Viewer displays an animated loading screen.
Arguments:
-
workbook: Required. A URL to a workbook file, or a base64-encoded string (Data URL) representing the file contents or an ArrayBuffer with the file contents. -
sheet: Required. A number, starting from 0, representing the index of the sheet within the document that will be open after the file loads. -
fileName: Required ifworkbookis anArrayBuffer, otherwise optional. A string representing a file name of the current workbook. If the file name is not provided andworkbookis an HTTP(S) URL, the app considers the last segment of the URL as the file name (after the last/). Otherwise, if the file name cannot be determined, the app will show "Unnamed file" as the file name.
Selects the given cells in the current workbook.
Arguments:
-
range- Required.[number, number, number, number]-[startRow, startCol, endRow, endCol]. Specifies a range of the cells to be selected.
You can catch the events listed below using EventTarget interface on the SpreadsheetViewerInstance object.
Event emitted when a sheet is changed by the end-user.
The event has a detail property, which is an object with the following property:
-
sheet- anumber, starting from 0, representing the index of the sheet within the document
Emitted when a selection is made in the data grid.
Properties:
-
name-"cellSelectionChanged" -
range-[number, number, number, number]- coordinates of the selection
These are not triggered in Spreadsheet Viewer's logic and include things like key pressed, that can be used for integration with your app.
When a key is pressed down.
Properties:
-
name-"keydown" -
key-KeyboardEvent.key
When a key is released.
Properties:
-
name-"keyup" -
key-KeyboardEvent.key
When a file (or files) are dropped on the Spreadsheet Viewer window.
Properties:
-
name-"drop" -
files-FileList
When something (for example, a file) is dragged over the Spreadsheet Viewer window.
Properties:
-
name-"dragover"
When something (for example, a file) stops being dragged over the Spreadsheet Viewer window (usually used together with the dragover event)
Properties:
-
name-"dragleave"
- Installation
- API guides
- Advanced topics
- Features and known limitations
- Open-source licenses