docs.sheetjs.com/docz/docs/03-demos/02-frontend/04-vue.md
2024-07-15 21:40:51 -04:00

17 KiB

title sidebar_label description pagination_prev pagination_next sidebar_position
Sheets in VueJS Sites VueJS Build interactive websites with VueJS. Seamlessly integrate spreadsheets into your app using SheetJS. Bring Excel-powered workflows and data to the modern web. demos/index demos/grid/index 4

import current from '/version.js'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock';

VueJS is a JavaScript library for building user interfaces.

SheetJS is a JavaScript library for reading and writing data from spreadsheets.

This demo uses VueJS and SheetJS to process and generate spreadsheets. We'll explore how to load SheetJS in a VueJS SFC (single-file component) and compare common state models and data flow strategies.

:::note pass

This demo focuses on VueJS concepts. Other demos cover general deployments:

:::

Installation

The "Frameworks" section covers installation with Yarn and other package managers.

The library can be imported directly from JS or JSX code with:

import { read, utils, writeFile } from 'xlsx';

Internal State

The various SheetJS APIs work with various data shapes. The preferred state depends on the application.

Array of Objects

Typically, some users will create a spreadsheet with source data that should be loaded into the site. This sheet will have known columns.

State

The example presidents sheet has one header row with "Name" and "Index" columns. The natural JS representation is an object for each row, using the values in the first rows as keys:

SpreadsheetState

pres.xlsx data

[
  { Name: "Bill Clinton", Index: 42 },
  { Name: "GeorgeW Bush", Index: 43 },
  { Name: "Barack Obama", Index: 44 },
  { Name: "Donald Trump", Index: 45 },
  { Name: "Joseph Biden", Index: 46 }
]

Using the VueJS Composition API, the ref1 function creates state objects:

<script setup>
import { ref } from "vue";

/* the component state is an array of objects */
const pres = ref([]);
</script>
<script setup lang="ts">
import { ref } from "vue";

/* the component state is an array of objects */
const pres = ref<any[]>([]);
</script>

When the spreadsheet header row is known ahead of time, row typing is possible:

<script setup lang="ts">
import { ref } from "vue";

interface President {
  Name: string;
  Index: number;
}

/* the component state is an array of presidents */
const pres = ref<President[]>([]);
</script>

:::caution pass

The types are informative. They do not enforce that worksheets include the named columns. A runtime data validation library should be used to verify the dataset.

When the file header is not known in advance, any should be used.

:::

Updating State

The SheetJS read and sheet_to_json functions simplify state updates. They are best used in the function bodies of lifecycle hooks including onMounted2.

The onMounted hook can download and update state when a person loads the site:

flowchart LR
  url[(Remote\nFile)]
  ab[(Data\nArrayBuffer)]
  wb(SheetJS\nWorkbook)
  ws(SheetJS\nWorksheet)
  aoo(array of\nobjects)
  state((component\nstate))
  url --> |fetch\n\n| ab
  ab --> |read\n\n| wb
  wb --> |wb.Sheets\nselect sheet| ws
  ws --> |sheet_to_json\n\n| aoo
  aoo --> |setPres\nfrom `setState`| state
<script setup>
import { ref, onMounted } from "vue";
import { read, utils } from 'xlsx';

/* the component state is an array of objects */
const pres = ref([]);

/* Fetch and update the state once */
onMounted(async() => {
  /* Download from https://docs.sheetjs.com/pres.numbers */
  const f = await fetch("https://docs.sheetjs.com/pres.numbers");
  const ab = await f.arrayBuffer();

  // highlight-start
  /* parse */
  const wb = read(ab);

  /* generate array of objects from first worksheet */
  const ws = wb.Sheets[wb.SheetNames[0]]; // get the first worksheet
  const data = utils.sheet_to_json(ws); // generate objects

  /* update state */
  pres.value = data;
  // highlight-end
});
</script>
<script setup lang="ts">
import { ref, onMounted } from "vue";
import { read, utils } from 'xlsx';

interface President {
  Name: string;
  Index: number;
}

/* the component state is an array of presidents */
const pres = ref<President[]>([]);

/* Fetch and update the state once */
onMounted(async() => {
  /* Download from https://docs.sheetjs.com/pres.numbers */
  const f = await fetch("https://docs.sheetjs.com/pres.numbers");
  const ab = await f.arrayBuffer();

  // highlight-start
  /* parse */
  const wb = read(ab);

  /* generate array of presidents from the first worksheet */
  const ws = wb.Sheets[wb.SheetNames[0]]; // get the first worksheet
  const data: President[] = utils.sheet_to_json<President>(ws); // generate objects

  /* update state */
  pres.value = data;
  // highlight-end
});
</script>

Rendering Data

A component will typically map over the data with v-for3. The following example generates a TABLE with a row for each President:

<script setup>
import { ref } from "vue";
const rows = ref([]);
</script>

<template>
<table>
  <!-- The `thead` section includes the table header row -->
  <thead><tr><th>Name</th><th>Index</th></tr></thead>
  <!-- The `tbody` section includes the data rows -->
  <tbody>
    <!-- generate row (TR) for each president -->
    <!-- highlight-start-->
    <tr v-for="(row, idx) in rows" :key="idx">
      <td>{{ row.Name }}</td>
      <td>{{ row.Index }}</td>
    </tr>
    <!-- highlight-end-->
  </tbody>
</table>
</template>

Exporting Data

The writeFile and json_to_sheet functions simplify exporting data. They are best used in the function bodies of v-on event handlers like @click4.

A callback can generate a local file when a user clicks a button:

flowchart LR
  state((component\nstate))
  ws(SheetJS\nWorksheet)
  wb(SheetJS\nWorkbook)
  file[(XLSX\nexport)]
  state --> |json_to_sheet\n\n| ws
  ws --> |book_new\nbook_append_sheet| wb
  wb --> |writeFile\n\n| file
<script setup>
import { ref } from "vue";
import { utils, writeFileXLSX } from 'xlsx';

const pres = ref([]);

/* get state data and export to XLSX */
function exportFile() {
  /* generate worksheet from state */
  // highlight-next-line
  const ws = utils.json_to_sheet(pres.value);
  /* create workbook and append worksheet */
  const wb = utils.book_new();
  utils.book_append_sheet(wb, ws, "Data");
  /* export to XLSX */
  writeFileXLSX(wb, "SheetJSVueAoO.xlsx");
}
</script>

<template>
  <button @click="exportFile">Export XLSX</button>
</template>

Complete Component

This complete component example fetches a test file and displays the contents in a HTML table. When the export button is clicked, a callback will export a file:

<script setup>
import { ref, onMounted } from "vue";
import { read, utils, writeFileXLSX } from 'xlsx';

const rows = ref([]);

onMounted(async() => {
  /* Download from https://docs.sheetjs.com/pres.numbers */
  const f = await fetch("https://docs.sheetjs.com/pres.numbers");
  const ab = await f.arrayBuffer();

  /* parse workbook */
  const wb = read(ab);

  /* update data */
  rows.value = utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]]);
});

/* get state data and export to XLSX */
function exportFile() {
  const ws = utils.json_to_sheet(rows.value);
  const wb = utils.book_new();
  utils.book_append_sheet(wb, ws, "Data");
  writeFileXLSX(wb, "SheetJSVueAoO.xlsx");
}
</script>

<template>
  <table><thead><tr><th>Name</th><th>Index</th></tr></thead><tbody>
    <tr v-for="(row, idx) in rows" :key="idx">
      <td>{{ row.Name }}</td>
      <td>{{ row.Index }}</td>
    </tr>
  </tbody><tfoot><td colSpan={2}>
    <button @click="exportFile">Export XLSX</button>
  </td></tfoot></table>
</template>
How to run the example (click to hide)

:::note Tested Deployments

This demo was tested in the following environments:

VueJS ViteJS Date
3.4.27 5.2.11 2024-05-26

:::

  1. Create a new site:
npm init vue@latest -- sheetjs-vue --default
  1. Install the SheetJS dependency and start the dev server:

{\ cd sheetjs-vue npm i npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz npm run dev}

  1. Open a web browser and access the displayed URL (http://localhost:5173)

  2. Replace src/App.vue with the src/SheetJSVueAoO.vue example.

The page will refresh and show a table with an Export button. Click the button and the page will attempt to download SheetJSVueAoO.xlsx. There may be a delay since Vite will try to optimize the SheetJS library on the fly.

  1. Stop the dev server and build the site:
npm run build

The generated site will be placed in the dist folder.

  1. Start a local web server:
npx http-server dist

Access the displayed URL (typically http://localhost:8080) with a web browser and test the page.

:::note Tested Deployments

This demo was tested in the following environments:

VueJS NuxtJS Date
3.4.21 3.11.1 2024-03-21

:::

  1. Create a new site:
npx nuxi@latest init sheetjs-nuxt --packageManager npm --no-install --no-gitInit
  1. Install the SheetJS dependency and start the dev server:

{\ cd sheetjs-nuxt npm i npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz npm run dev}

  1. Open a web browser and access the displayed URL (http://localhost:3000)

  2. Replace app.vue with the src/SheetJSVueAoO.vue example.

The page will refresh and show a table with an Export button. Click the button and the page will attempt to download SheetJSVueAoO.xlsx.

  1. Stop the dev server and build the site:
npm run generate

The generated site will be placed in the dist folder.

  1. Start a local web server:
npx http-server .output/public/

Access the displayed URL (typically http://localhost:8080) with a web browser and test the page.

HTML

The main disadvantage of the Array of Objects approach is the specific nature of the columns. For more general use, passing around an Array of Arrays works. However, this does not handle merge cells5 well!

The sheet_to_html function generates HTML that is aware of merges and other worksheet features. VueJS v-html6 attribute allows code to set the innerHTML attribute, effectively inserting the code into the page.

In this example, the component attaches a ref to the DIV container. During export, the first TABLE child element can be parsed with table_to_book to generate a workbook object.

<script setup>
import { ref, onMounted } from "vue";
import { read, utils, writeFileXLSX } from 'xlsx';

const html = ref("");
const tableau = ref();

onMounted(async() => {
  /* Download from https://docs.sheetjs.com/pres.numbers */
  const f = await fetch("https://docs.sheetjs.com/pres.numbers");
  const ab = await f.arrayBuffer();

  /* parse workbook */
  const wb = read(ab);

  /* update data */
  html.value = utils.sheet_to_html(wb.Sheets[wb.SheetNames[0]]);
});

/* get live table and export to XLSX */
function exportFile() {
  const wb = utils.table_to_book(tableau.value.getElementsByTagName("TABLE")[0])
  writeFileXLSX(wb, "SheetJSVueHTML.xlsx");
}
</script>

<template>
  <div ref="tableau" v-html="html"></div>
  <button @click="exportFile">Export XLSX</button>
</template>
How to run the example (click to hide)

:::note Tested Deployments

This demo was tested in the following environments:

VueJS ViteJS Date
3.4.21 5.2.2 2024-03-21

:::

  1. Create a new site:
npm init vue@latest -- sheetjs-vue --default
  1. Install the SheetJS dependency and start the dev server:

{\ cd sheetjs-vue npm i npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz npm run dev}

  1. Open a web browser and access the displayed URL (http://localhost:5173)

  2. Replace src/App.vue with the src/SheetJSVueHTML.vue example.

The page will refresh and show a table with an Export button. Click the button and the page will attempt to download SheetJSVueHTML.xlsx. There may be a delay since Vite will try to optimize the SheetJS library on the fly.

  1. Stop the dev server and build the site:
npm run build

The generated site will be placed in the dist folder.

  1. Start a local web server:
npx http-server dist

Access the displayed URL (typically http://localhost:8080) with a web browser and test the page.

:::note Tested Deployments

This demo was tested in the following environments:

VueJS NuxtJS Date
3.4.21 3.11.1 2024-03-21

:::

  1. Create a new site:
npx nuxi@latest init sheetjs-nuxt --packageManager npm --no-install --no-gitInit
  1. Install the SheetJS dependency and start the dev server:

{\ cd sheetjs-nuxt npm i npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz npm run dev}

  1. Open a web browser and access the displayed URL (http://localhost:3000)

  2. Replace app.vue with the src/SheetJSVueHTML.vue example.

The page will refresh and show a table with an Export button. Click the button and the page will attempt to download SheetJSVueHTML.xlsx.

  1. Stop the dev server and build the site:
npm run generate

The generated site will be placed in the dist folder.

  1. Start a local web server:
npx http-server .output/public/

Access the displayed URL (typically http://localhost:8080) with a web browser and test the page.

Rows and Columns

Some data grids and UI components split worksheet state in two parts: an array of column attribute objects and an array of row objects. The former is used to generate column headings and for indexing into the row objects.

The safest approach is to use an array of arrays for state and to generate column objects that map to A1-Style column headers.

The vue3-table-lite demo generates rows and columns objects with the following structure:

/* rows are generated with a simple array of arrays */
rows.value = utils.sheet_to_json(worksheet, { header: 1 });

/* column objects are generated based on the worksheet range */
const range = utils.decode_range(ws["!ref"]||"A1");
columns.value = Array.from({ length: range.e.c + 1 }, (_, i) => ({
  /* for an array of arrays, the keys are "0", "1", "2", ... */
  field: String(i),
  /* column labels: encode_col translates 0 -> "A", 1 -> "B", 2 -> "C", ... */
  label: XLSX.utils.encode_col(i)
}));

Legacy Deployments

The Standalone Scripts play nice with legacy deployments that do not use a bundler.

The legacy demos show a simple VueJS component. It is written in ES5 syntax. The pages are not minified and "View Source" should be used to inspect.

There is a shared component SheetJS-vue.js

:::caution pass

The entire demo is designed to run in Internet Explorer and does not reflect modern design patterns.

:::


  1. See ref() in the VueJS documentation. ↩︎

  2. See onMounted() in the VueJS documentation. ↩︎

  3. See v-for in the VueJS documentation. ↩︎

  4. See v-on in the VueJS documentation. ↩︎

  5. See "Merged Cells" in "SheetJS Data Model" for more details. ↩︎

  6. See v-html in the VueJS documentation. ↩︎