Import & Export

📊 Univer Sheet

🏆

This feature contains closed-source code, allowing any user to use it for free. It also includes an optional business upgrade plan that provides richer features and services.

💻

This feature depends on the Univer backend service. Please make sure you have read the related documentation and completed the deployment before using it.

Univer implements the import and export of Excel XLSX format files through plugins and backend services. The plugin integrates the ability to interact with the server and provides an import and export menu entry.

❓

Why does Univer implement import and export through backend services?

Importing and exporting implemented only through the frontend cannot meet enterprise requirements in terms of performance or effect. Therefore, we provide backend services to implement import and export features. You can use some open-source XLSX parsing libraries to parse files into data structures that conform to the IWorksheetData interface, and then import the data into Univer through the Facade API.

Installation

pnpm add @univerjs-pro/exchange-client @univerjs-pro/sheets-exchange-client

Import

import '@univerjs-pro/exchange-client/lib/index.css';
 
import { UniverExchangeClientPlugin } from '@univerjs-pro/exchange-client';
import { UniverSheetsExchangeClientPlugin } from '@univerjs-pro/sheets-exchange-client';

Internationalization

import { LocaleType, Tools } from '@univerjs/core';
import ExchangeClientEnUS from '@univerjs-pro/exchange-client/locale/en-US';
 
const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: Tools.deepMerge(
      ExchangeClientEnUS
    ),
  },
});

Register

univer.registerPlugin(UniverExchangeClientPlugin);
univer.registerPlugin(UniverSheetsExchangeClientPlugin);

Configuration

If the Univer page and the server are not on the same domain, you need to additionally configure parameters such as uploadFileServerUrl.

univer.registerPlugin(UniverExchangeClientPlugin, {
  uploadFileServerUrl: `http://localhost:3010/universer-api/stream/file/upload`,
  importServerUrl: `http://localhost:3010/universer-api/exchange/{type}/import`,
  exportServerUrl: `http://localhost:3010/universer-api/exchange/{type}/export`,
  getTaskServerUrl: `http://localhost:3010/universer-api/exchange/task/{taskID}`,
  signUrlServerUrl: `http://localhost:3010/universer-api/file/{fileID}/sign-url`,
});
univer.registerPlugin(UniverSheetsExchangeClientPlugin);

You can change the maximum timeout for file uploads by configuring maxTimeoutTime. If you need to upload larger files, you can increase this value appropriately. The default is 2 minutes.

univer.registerPlugin(UniverExchangeClientPlugin, {
  maxTimeoutTime: 1000 * 60 * 10, // 10 minutes
});
univer.registerPlugin(UniverSheetsExchangeClientPlugin);

Custom Usage

If you are not satisfied with the features provided by the plugin, you can also use the Facade API to implement custom import and export processes. Please refer to Server-Related Features for more details.

FAQ

How to Open or Edit an Excel File from a URL

Here is an implementation idea for your reference. First, use the browser's fetch API to download the file from the URL and convert it into a File object. Then, call the importXLSXToUnitId or importXLSXToSnapshot methods from the Facade API to import it. The sample code is as follows:

const url = 'https://example.com/filename.xlsx'; // Your Excel file URL
 
// Function to fetch and convert the URL to a File object
async function fetchExcelFile(url) {
  try {
    const response = await fetch(url);
    const blob = await response.blob();
    return new File([blob], 'filename.xlsx', { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
  } catch (error) {
    console.error('Failed to fetch the file:', error);
  }
}
 
// Fetch the file and import it as a snapshot
fetchExcelFile(url).then(async file => {
  if (file) {
    // Modify the following code according to the actual situation
    univerAPI.importXLSXToSnapshot(file).then(snapshot => {
      console.log('Snapshot created:', snapshot); // see more: https://univer.ai/guides/sheet/getting-started/cell-data
    });
 
    univerAPI.importXLSXToUnitId(file).then(unitId => {
      console.log('Unit ID created:', unitId);
 
      // Utilize automatic data loading in conjunction with collaborative editing. https://univer.ai/guides/sheet/features/collaboration#automatically-load-data
      const url = new URL(window.location.href);
      const unit = url.searchParams.get('unit');
      url.searchParams.set('unit', unitID);
      url.searchParams.set('type', "2"); // The meaning of "2" is String(UniverInstanceType.UNIVER_SHEET)
      console.log('Unit URL:', url.toString());
    });
  }
});

Note: The Facade API univerAPI.importXLSXToSnapshot utilizes the functionality provided by @univerjs-pro/exchange-client. Ensure that @univerjs-pro/exchange-client is installed in the project before use.

The Import/Export API is not functioning properly

To ensure proper functioning of the Import/Export feature, you need to correctly configure the S3 settings in Univer Server. These configurations will be used for storing imported and exported files.

Read the Troubleshooting section for more information.

Print Collaborative Editing