L'objectif est de générer un classeur XLSB contenant les noms et les dates de naissance des présidents des États-Unis.

Acquérir des données

Données brutes

https://theunitedstates.io/congress-legislators/executive.json contient les données souhaitées. Par exemple, John Adams :```js { "id": { /* (data omitted) / }, "name": { "first": "John", // <-- first name "last": "Adams" // <-- last name }, "bio": { "birthday": "1735-10-19", // <-- birthday "gender": "M" }, "terms": [ { "type": "viceprez", / (other fields omitted) / }, { "type": "viceprez", / (other fields omitted) / }, { "type": "prez", / (other fields omitted) */ } // <-- look for "prez" ] }

_Filtrage pour les Présidents_

Le jeu de données inclut Aaron Burr, un Vice-Président qui n'a jamais été Président !

`Array#filter` crée un nouveau tableau avec les lignes souhaitées.  Un Président a servi
au moins un mandat avec `type` défini sur `"prez"`.  Pour tester si une ligne particulière a
au moins un mandat `"prez"`, `Array#some` est une autre fonction native JS.  Le
filtre complet serait :```js
const prez = raw_data.filter(row => row.terms.some(term => term.type === "prez"));

Lining up the data

Pour cet exemple, le nom sera le prénom combiné avec le nom de famille (row.name.first + " " + row.name.last) et la date de naissance sera le sous-champ row.bio.birthday. En utilisant Array#map, l'ensemble de données peut être traité en un seul appel :```js const rows = prez.map(row => ({ name: row.name.first + " " + row.name.last, birthday: row.bio.birthday }));

Le résultat est un tableau d'objets "simples" sans imbrication :```js
[
  { name: "George Washington", birthday: "1732-02-22" },
  { name: "John Adams", birthday: "1735-10-19" },
  // ... one row per President
]

Extraire les données

Avec le jeu de données nettoyé, XLSX.utils.json_to_sheet génère une feuille de calcul :```js const worksheet = XLSX.utils.json_to_sheet(rows);

`XLSX.utils.book_new` crée un nouveau classeur et `XLSX.utils.book_append_sheet`
ajoute une feuille de calcul au classeur. La nouvelle feuille de calcul s'appellera "Dates" :```js
const workbook = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(workbook, worksheet, "Dates");

Process Data

Correction des en-têtes

Par défaut, json_to_sheet crée une feuille de calcul avec une ligne d'en-tête. Dans ce cas, les en-têtes proviennent des clés de l'objet JS : "name" et "birthday".

Les en-têtes se trouvent dans les cellules A1 et B1. XLSX.utils.sheet_add_aoa peut écrire des valeurs textuelles dans la feuille de calcul existante à partir de la cellule A1 :```js XLSX.utils.sheet_add_aoa(worksheet, [["Name", "Birthday"]], { origin: "A1" });

_Correction des largeurs de colonnes_

Certains noms sont plus longs que la largeur de colonne par défaut.  Les largeurs de colonnes sont
définies en [définissant la propriété `"!cols"` de la feuille de calcul](#row-and-column-properties).

La ligne suivante définit la largeur de la colonne A à environ 10 caractères :```js
worksheet["!cols"] = [ { wch: 10 } ]; // set column A width to 10 characters

Un appel Array#reduce sur rows peut calculer la largeur maximale :```js const max_width = rows.reduce((w, r) => Math.max(w, r.name.length), 10); worksheet["!cols"] = [ { wch: max_width } ];

Remarque : Si le point de départ était un fichier ou un tableau HTML, `XLSX.utils.sheet_to_json` générera un tableau d'objets JS.

**Données du paquet et de la version**

`XLSX.writeFile` crée un fichier de feuille de calcul et tente de l'écrire sur le système. Dans le navigateur, il tentera de demander à l'utilisateur de télécharger le fichier. Dans NodeJS, il écrira dans le répertoire local.```js
XLSX.writeFile(workbook, "Presidents.xlsx");

Exemple complet```js // Uncomment the next line for use in NodeJS: // const XLSX = require("xlsx"), axios = require("axios");

(async() => { /* fetch JSON data and parse */ const url = "https://theunitedstates.io/congress-legislators/executive.json"; const raw_data = (await axios(url, {responseType: "json"})).data;

/* filter for the Presidents */ const prez = raw_data.filter(row => row.terms.some(term => term.type === "prez"));

/* flatten objects */ const rows = prez.map(row => ({ name: row.name.first + " " + row.name.last, birthday: row.bio.birthday }));

/* generate worksheet and workbook */ const worksheet = XLSX.utils.json_to_sheet(rows); const workbook = XLSX.utils.book_new(); XLSX.utils.book_append_sheet(workbook, worksheet, "Dates");

/* fix headers */ XLSX.utils.sheet_add_aoa(worksheet, [["Name", "Birthday"]], { origin: "A1" });

/* calculate column width */ const max_width = rows.reduce((w, r) => Math.max(w, r.name.length), 10); worksheet["!cols"] = [ { wch: max_width } ];

/* create an XLSX file and try to save to Presidents.xlsx */ XLSX.writeFile(workbook, "Presidents.xlsx"); })();

Pour une utilisation dans le navigateur web, en supposant que l'extrait soit sauvegardé sous `snippet.js`, des balises script devraient être utilisées pour inclure les versions autonomes de `axios` et `xlsx` :```html
<script src="https://unpkg.com/xlsx/dist/xlsx.full.min.js"></script>
<script src="https://unpkg.com/axios/dist/axios.min.js"></script>
<script src="snippet.js"></script>

readFile utilise fs.readFileSync en interne :```js var XLSX = require("xlsx");

var workbook = XLSX.readFile("test.xlsx");

Pour Node ESM, l'assistant `readFile` n'est pas activé. À la place, `fs.readFileSync` doit être utilisé pour lire les données du fichier sous forme de `Buffer` pour utilisation avec `XLSX.read` :```js
import { readFileSync } from "fs";
import { read } from "xlsx/xlsx.mjs";

const buf = readFileSync("test.xlsx");
/* buf is a Buffer */
const workbook = read(buf);

readFile utilise Deno.readFileSync en interne :```js // @deno-types="https://deno.land/x/sheetjs/types/index.d.ts" import * as XLSX from 'https://deno.land/x/sheetjs/xlsx.mjs'

const workbook = XLSX.readFile("test.xlsx");

Applications reading files must be invoked with the `--allow-read` flag.  The
[`deno` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/deno/) has more examples

</details>

<details>
  <summary><b>Fichier soumis par l'utilisateur dans une page web (« Glisser-déposer »)</b> (cliquez pour afficher)</summary>

Pour les sites web modernes ciblant Chrome 76+, `File#arrayBuffer` est recommandé :```js
// XLSX is a global from the standalone script

async function handleDropAsync(e) {
  e.stopPropagation(); e.preventDefault();
  const f = e.dataTransfer.files[0];
  /* f is a File */
  const data = await f.arrayBuffer();
  /* data is an ArrayBuffer */
  const workbook = XLSX.read(data);

  /* DO SOMETHING WITH workbook HERE */
}
drop_dom_element.addEventListener("drop", handleDropAsync, false);

Pour une compatibilité maximale, l'API FileReader doit être utilisée :```js function handleDrop(e) { e.stopPropagation(); e.preventDefault(); var f = e.dataTransfer.files[0]; /* f is a File / var reader = new FileReader(); reader.onload = function(e) { var data = e.target.result; / reader.readAsArrayBuffer(file) -> data will be an ArrayBuffer */ var workbook = XLSX.read(data);

/* DO SOMETHING WITH workbook HERE */

}; reader.readAsArrayBuffer(f); } drop_dom_element.addEventListener("drop", handleDrop, false);

<https://oss.sheetjs.com/sheetjs/> démontre la technique FileReader.

</details>

<details>
  <summary><b>Fichier soumis par l'utilisateur avec un élément HTML INPUT</b> (cliquez pour afficher)</summary>

En commençant par un élément HTML INPUT avec `type="file"` :```html
<input type="file" id="input_dom_element">

Pour les sites web modernes ciblant Chrome 76+, Blob#arrayBuffer est recommandé:```js // XLSX is a global from the standalone script

async function handleFileAsync(e) { const file = e.target.files[0]; const data = await file.arrayBuffer(); /* data is an ArrayBuffer */ const workbook = XLSX.read(data);

/* DO SOMETHING WITH workbook HERE */ } input_dom_element.addEventListener("change", handleFileAsync, false);

Pour une compatibilité plus large (y compris IE10+), l'approche `FileReader` est recommandée :```js
function handleFile(e) {
  var file = e.target.files[0];
  var reader = new FileReader();
  reader.onload = function(e) {
    var data = e.target.result;
    /* reader.readAsArrayBuffer(file) -> data will be an ArrayBuffer */
    var workbook = XLSX.read(e.target.result);

    /* DO SOMETHING WITH workbook HERE */
  };
  reader.readAsArrayBuffer(file);
}
input_dom_element.addEventListener("change", handleFile, false);

Le oldie démo montre un scénario de repli compatible IE.

Pour les sites web modernes ciblant Chrome 42+, fetch est recommandé :```js // XLSX is a global from the standalone script

(async() => { const url = "http://oss.sheetjs.com/test_files/formula_stress_test.xlsx"; const data = await (await fetch(url)).arrayBuffer(); /* data is an ArrayBuffer */ const workbook = XLSX.read(data);

/* DO SOMETHING WITH workbook HERE */ })();

Pour une compatibilité plus large, l'approche `XMLHttpRequest` est recommandée :```js
var url = "http://oss.sheetjs.com/test_files/formula_stress_test.xlsx";

/* set up async GET request */
var req = new XMLHttpRequest();
req.open("GET", url, true);
req.responseType = "arraybuffer";

req.onload = function(e) {
  var workbook = XLSX.read(req.response);

  /* DO SOMETHING WITH workbook HERE */
};

req.send();

La xhr démo inclut une discussion plus longue et plus d'exemples.

http://oss.sheetjs.com/sheetjs/ajax.html montre des approches de repli pour IE6+.

readFile encapsule la logique File dans Photoshop et d'autres cibles ExtendScript. Le chemin spécifié doit être un chemin absolu :```js #include "xlsx.extendscript.js"

/* Read test.xlsx from the Documents folder */ var workbook = XLSX.readFile(Folder.myDocuments + "/test.xlsx");

La [démo `extendscript`](https://github.com/weareu/xlsx/blob/HEAD/demos/extendscript/) inclut un exemple plus complexe.

</details>

<details>
  <summary><b>Fichier local dans une application Electron</b> (cliquer pour afficher)</summary>

`readFile` peut être utilisé dans le processus de rendu :```js
/* From the renderer process */
var XLSX = require("xlsx");

var workbook = XLSX.readFile(path);

Electron APIs have changed over time. The electron demo shows a complete example and details the required version-specific settings.

La démo react inclut un exemple d'application React Native.

Étant donné que React Native ne permet pas de lire des fichiers du système de fichiers, une bibliothèque tierce doit être utilisée. Les bibliothèques suivantes ont été testées :

• react-native-file-access

L'encodage base64 renvoie des chaînes compatibles avec le type base64 :```js import XLSX from "xlsx"; import { FileSystem } from "react-native-file-access";

const b64 = await FileSystem.readFile(path, "base64"); /* b64 is a base64 string */ const workbook = XLSX.read(b64, {type: "base64"});

- [`react-native-fs`](https://npm.im/react-native-fs)

Le codage `ascii` renvoie des chaînes binaires compatibles avec le type `binary` :```js
import XLSX from "xlsx";
import { readFile } from "react-native-fs";

const bstr = await readFile(path, "ascii");
/* bstr is a binary string */
const workbook = XLSX.read(bstr, {type: "binary"});

read peut accepter un buffer NodeJS. readFile peut lire les fichiers générés par un analyseur de corps de requête HTTP POST comme formidable:```js const XLSX = require("xlsx"); const http = require("http"); const formidable = require("formidable");

const server = http.createServer((req, res) => { const form = new formidable.IncomingForm(); form.parse(req, (err, fields, files) => { /* grab the first file */ const f = Object.entries(files)[0][1]; const path = f.filepath; const workbook = XLSX.readFile(path);

/* DO SOMETHING WITH workbook HERE */

}); }).listen(process.env.PORT || 7262);

The [`server` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/server) contains des exemples plus avancés.

</details>

<details>
  <summary><b>Télécharger des fichiers dans un processus NodeJS</b> (cliquez pour afficher)</summary>

Node 17.5 et 18.0 offrent un support natif pour fetch :```js
const XLSX = require("xlsx");

const data = await (await fetch(url)).arrayBuffer();
/* data is an ArrayBuffer */
const workbook = XLSX.read(data);

Pour une compatibilité plus large, des modules tiers sont recommandés.

request nécessite un encodage null pour produire des Buffers :```js var XLSX = require("xlsx"); var request = require("request");

request({url: url, encoding: null}, function(err, resp, body) { var workbook = XLSX.read(body);

/* DO SOMETHING WITH workbook HERE */ });

[`axios`](https://npm.im/axios) fonctionne de la même manière dans le navigateur et dans NodeJS :```js
const XLSX = require("xlsx");
const axios = require("axios");

(async() => {
  const res = await axios.get(url, {responseType: "arraybuffer"});
  /* res.data is a Buffer */
  const workbook = XLSX.read(res.data);

  /* DO SOMETHING WITH workbook HERE */
})();

Le module net dans le processus principal peut effectuer des requêtes HTTP/HTTPS vers des ressources externes. Les réponses doivent être concaténées manuellement en utilisant Buffer.concat :```js const XLSX = require("xlsx"); const { net } = require("electron");

const req = net.request(url); req.on("response", (res) => { const bufs = []; // this array will collect all of the buffers res.on("data", (chunk) => { bufs.push(chunk); }); res.on("end", () => { const workbook = XLSX.read(Buffer.concat(bufs));

/* DO SOMETHING WITH workbook HERE */

}); }); req.end();

</details>

<details>
  <summary><b>Readable Streams in NodeJS</b> (cliquez pour afficher)</summary>

Lorsqu'il s'agit de Readable Streams, l'approche la plus simple consiste à mettre en mémoire tampon le flux et à traiter l'ensemble à la fin :```js
var fs = require("fs");
var XLSX = require("xlsx");

function process_RS(stream, cb) {
  var buffers = [];
  stream.on("data", function(data) { buffers.push(data); });
  stream.on("end", function() {
    var buffer = Buffer.concat(buffers);
    var workbook = XLSX.read(buffer, {type:"buffer"});

    /* DO SOMETHING WITH workbook IN THE CALLBACK */
    cb(workbook);
  });
}

Lorsqu'on traite avec ReadableStream, l'approche la plus simple est de mettre en mémoire tampon le flux et de traiter l'ensemble à la fin :```js // XLSX is a global from the standalone script

async function process_RS(stream) { /* collect data */ const buffers = []; const reader = stream.getReader(); for(;;) { const res = await reader.read(); if(res.value) buffers.push(res.value); if(res.done) break; }

/* concat */ const out = new Uint8Array(buffers.reduce((acc, v) => acc + v.length, 0));

let off = 0; for(const u8 of arr) { out.set(u8, off); off += u8.length; }

return out; }

const data = await process_RS(stream); /* data is Uint8Array */ const workbook = XLSX.read(data);

</details>

Des exemples plus détaillés sont couverts dans les [démos incluses](https://github.com/weareu/xlsx/blob/HEAD/demos/)

### Traitement des données JSON et JS

Les données JSON et JS représentent généralement des feuilles de calcul uniques.  Cette section utilisera quelques fonctions utilitaires pour générer des classeurs.

_Créer un nouveau classeur_```js
var workbook = XLSX.utils.book_new();

La fonction utilitaire book_new crée un classeur vide sans feuilles de calcul.

Les logiciels de tableur exigent généralement au moins une feuille de calcul et imposent cette exigence dans l'interface utilisateur. Cette bibliothèque impose l'exigence au moment de l'écriture, générant des erreurs si un classeur vide est passé aux fonctions d'écriture.

API

Créer une feuille de calcul à partir d'un tableau de tableaux de valeurs JS```js var worksheet = XLSX.utils.aoa_to_sheet(aoa, opts);

La fonction utilitaire `aoa_to_sheet` parcourt un "array of arrays" dans l'ordre ligne-majeur, générant un objet de feuille de calcul. L'extrait suivant génère une feuille avec la cellule `A1` définie sur la chaîne `A1`, la cellule `B1` sur `B1`, etc:```js
var worksheet = XLSX.utils.aoa_to_sheet([
  ["A1", "B1", "C1"],
  ["A2", "B2", "C2"],
  ["A3", "B3", "C3"]
]);

"Array of Arrays Input" décrit la fonction et l'argument optionnel opts plus en détail.

Créer une feuille de calcul à partir d'un tableau d'objets JS```js var worksheet = XLSX.utils.json_to_sheet(jsa, opts);

La fonction utilitaire `json_to_sheet` parcourt un tableau d'objets JS dans l'ordre,
générant un objet de feuille de calcul. Par défaut, elle génère une ligne d'en-tête et
une ligne par objet dans le tableau. L'argument optionnel `opts` a des paramètres pour
contrôler l'ordre des colonnes et la sortie d'en-tête.

["Entrée d'un tableau d'objets"](#entrée-dun-tableau-de-tableaux) décrit la fonction et
l'argument optionnel `opts` plus en détail.

**Exemples**

["La Zen de SheetJS"](#la-zen-de-sheetjs) contient un exemple détaillé "Obtenir des données
d'un point de terminaison JSON et générer un classeur"

[`x-spreadsheet`](https://github.com/myliang/x-spreadsheet) est une grille de données interactive
pour prévisualiser et modifier des données structurées dans le navigateur web. La
[démo `xspreadsheet`](https://github.com/weareu/xlsx/blob/HEAD/demos/xspreadsheet) inclut un script d'exemple avec la
fonction `xtos` pour convertir d'un objet de données x-spreadsheet en classeur.
<https://oss.sheetjs.com/sheetjs/x-spreadsheet> est une démo en direct.

<details>
  <summary><b>Enregistrements d'une requête de base de données (SQL ou no-SQL)</b> (cliquez pour afficher)</summary>

La [`démo database`](https://github.com/weareu/xlsx/blob/HEAD/demos/database/) inclut des exemples de travail avec
des bases de données et des résultats de requêtes.

</details>

<details>
  <summary><b>Calculs numériques avec TensorFlow.js</b> (cliquez pour afficher)</summary>

[`@tensorflow/tfjs`](https://github.com/weareu/xlsx/blob/HEAD/@tensorflow/tfjs) et d'autres bibliothèques attendent des données sous forme de tableaux simples,
bien adaptés aux feuilles de calcul où chaque colonne est un vecteur de données. C'est
la transposée de la façon dont la plupart des gens utilisent les tableurs, où chaque ligne est un vecteur.

Lors de la récupération des données de `tfjs`, les points de données renvoyés sont stockés dans un tableau
typé. Un tableau de tableaux peut être construit avec des boucles. `Array#unshift` peut
ajouter une ligne de titre en préfixe avant la conversion :```js
const XLSX = require("xlsx");
const tf = require('@tensorflow/tfjs');

/* suppose xs and ys are vectors (1D tensors) -> tfarr will be a typed array */
const tfdata = tf.stack([xs, ys]).transpose();
const shape = tfdata.shape;
const tfarr = tfdata.dataSync();

/* construct the array of arrays */
const aoa = [];
for(let j = 0; j < shape[0]; ++j) {
  aoa[j] = [];
  for(let i = 0; i < shape[1]; ++i) aoa[j][i] = tfarr[j * shape[1] + i];
}
/* add headers to the top */
aoa.unshift(["x", "y"]);

/* generate worksheet */
const worksheet = XLSX.utils.aoa_to_sheet(aoa);

La démo array montre un exemple complet.

Plusieurs tableaux sur une page web peuvent être convertis en feuilles de calcul individuelles:```js
/* create new workbook */
var workbook = XLSX.utils.book_new();

/* convert table "table1" to worksheet named "Sheet1" */
var sheet1 = XLSX.utils.table_to_sheet(document.getElementById("table1"));
XLSX.utils.book_append_sheet(workbook, sheet1, "Sheet1");

/* convert table "table2" to worksheet named "Sheet2" */
var sheet2 = XLSX.utils.table_to_sheet(document.getElementById("table2"));
XLSX.utils.book_append_sheet(workbook, sheet2, "Sheet2");

/* workbook now has 2 worksheets */

Alternativement, le code HTML peut être extrait et analysé:```js var htmlstr = document.getElementById("tableau").outerHTML; var workbook = XLSX.read(htmlstr, {type:"string"});

</details>

<details>
  <summary><b>Extension Chrome/Chromium</b> (cliquez pour afficher)</summary>

La [`chrome` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/chrome/) montre un exemple complet et détaille les
autorisations requises et autres paramètres.

Dans une extension, il est recommandé de générer le classeur dans un script de contenu
et de renvoyer l'objet à l'extension :```js
/* in the worker script */
chrome.runtime.onMessage.addListener(function(msg, sender, cb) {
  /* pass a message like { sheetjs: true } from the extension to scrape */
  if(!msg || !msg.sheetjs) return;
  /* create a new workbook */
  var workbook = XLSX.utils.book_new();
  /* loop through each table element */
  var tables = document.getElementsByTagName("table")
  for(var i = 0; i < tables.length; ++i) {
    var worksheet = XLSX.utils.table_to_sheet(tables[i]);
    XLSX.utils.book_append_sheet(workbook, worksheet, "Table" + i);
  }
  /* pass back to the extension */
  return cb(workbook);
});

La démo headless inclut une démo complète pour convertir des fichiers HTML en classeurs XLSB. L'idée principale est d'ajouter le script à la page, d'analyser le tableau dans le contexte de la page, de générer un classeur base64 et de le renvoyer pour traitement ultérieur :```js const XLSX = require("xlsx"); const { readFileSync } = require("fs"), puppeteer = require("puppeteer");

const url = https://sheetjs.com/demos/table;

/* get the standalone build source (node_modules/xlsx/dist/xlsx.full.min.js) */ const lib = readFileSync(require.resolve("xlsx/dist/xlsx.full.min.js"), "utf8");

(async() => { /* start browser and go to web page */ const browser = await puppeteer.launch(); const page = await browser.newPage(); await page.goto(url, {waitUntil: "networkidle2"});

/* inject library */ await page.addScriptTag({content: lib});

/* this function s5s will be called by the script below, receiving the Base64-encoded file */ await page.exposeFunction("s5s", async(b64) => { const workbook = XLSX.read(b64, {type: "base64" });

/* DO SOMETHING WITH workbook HERE */

});

/* generate XLSB file in webpage context and send back result / await page.addScriptTag({content: ` / call table_to_book on first table */ var workbook = XLSX.utils.table_to_book(document.querySelector("TABLE"));

/* generate XLSX file */
var b64 = XLSX.write(workbook, {type: "base64", bookType: "xlsb"});

/* call "s5s" hook exposed from the node process */
window.s5s(b64);

`});

/* cleanup */ await browser.close(); })();

</details>

<details>
  <summary><b>Tableaux HTML côté serveur avec WebKit sans tête</b> (cliquer pour afficher)</summary>

La [démo `headless`](https://github.com/weareu/xlsx/blob/HEAD/demos/headless/) inclut une démonstration complète pour convertir des fichiers HTML en classeurs XLSB en utilisant [PhantomJS](https://phantomjs.org/). L'idée principale est d'ajouter le script à la page, d'analyser le tableau dans le contexte de la page, de générer un classeur `binary` et de le renvoyer pour un traitement ultérieur :```js
var XLSX = require('xlsx');
var page = require('webpage').create();

/* this code will be run in the page */
var code = [ "function(){",
  /* call table_to_book on first table */
  "var wb = XLSX.utils.table_to_book(document.body.getElementsByTagName('table')[0]);",

  /* generate XLSB file and return binary string */
  "return XLSX.write(wb, {type: 'binary', bookType: 'xlsb'});",
"}" ].join("");

page.open('https://sheetjs.com/demos/table', function() {
  /* Load the browser script from the UNPKG CDN */
  page.includeJs("https://unpkg.com/xlsx/dist/xlsx.full.min.js", function() {
    /* The code will return an XLSB file encoded as binary string */
    var bin = page.evaluateJavaScript(code);

    var workbook = XLSX.read(bin, {type: "binary"});
    /* DO SOMETHING WITH workbook HERE */

    phantom.exit();
  });
});

NodeJS n'inclut pas d'implémentation DOM et Puppeteer nécessite une lourde build Chromium. jsdom est une alternative légère :```js const XLSX = require("xlsx"); const { readFileSync } = require("fs"); const { JSDOM } = require("jsdom");

/* obtain HTML string. This example reads from test.html / const html_str = fs.readFileSync("test.html", "utf8"); / get first TABLE element / const doc = new JSDOM(html_str).window.document.querySelector("table"); / generate workbook */ const workbook = XLSX.utils.table_to_book(doc);

</details>

## Traitement des données

Le ["Common Spreadsheet Format"](#common-spreadsheet-format) est une représentation simple sous forme d'objet des concepts fondamentaux d'un classeur. Les fonctions utilitaires travaillent avec cette représentation objet et sont conçues pour gérer les cas d'utilisation courants.

### Modification de la structure du classeur

**API**

_Ajouter une feuille de calcul à un classeur_```js
XLSX.utils.book_append_sheet(workbook, worksheet, sheet_name);

La fonction utilitaire book_append_sheet ajoute une feuille de calcul au classeur. Le troisième argument spécifie le nom souhaité de la feuille de calcul. Plusieurs feuilles de calcul peuvent être ajoutées à un classeur en appelant la fonction plusieurs fois. Si le nom de la feuille de calcul est déjà utilisé dans le classeur, une erreur sera levée.

Ajouter une feuille de calcul à un classeur et trouver un nom unique```js var new_name = XLSX.utils.book_append_sheet(workbook, worksheet, name, true);

Si le quatrième argument est `true`, la fonction commencera avec le nom de feuille de calcul spécifié. Si le nom de feuille existe dans le classeur, un nouveau nom de feuille de calcul sera choisi en trouvant la racine du nom et en incrémentant le compteur :```js
XLSX.utils.book_append_sheet(workbook, sheetA, "Sheet2", true); // Sheet2
XLSX.utils.book_append_sheet(workbook, sheetB, "Sheet2", true); // Sheet3
XLSX.utils.book_append_sheet(workbook, sheetC, "Sheet2", true); // Sheet4
XLSX.utils.book_append_sheet(workbook, sheetD, "Sheet2", true); // Sheet5

Lister les noms des feuilles de calcul dans l'ordre des onglets```js var wsnames = workbook.SheetNames;

La propriété `SheetNames` de l'objet workbook est une liste des noms de feuilles de calcul dans « l'ordre des onglets ». Les fonctions API examineront ce tableau.

_Remplacer une feuille de calcul sur place_```js
workbook.Sheets[sheet_name] = new_worksheet;

La propriété Sheets de l'objet workbook est un objet dont les clés sont des noms et dont les valeurs sont des objets worksheet. En réaffectant une propriété de l'objet Sheets, l'objet worksheet peut être modifié sans perturber le reste de la structure du classeur.

Exemples

</details>

### Modification des valeurs de cellule

**API**

_Modifier une seule valeur de cellule dans une feuille de calcul_```js
XLSX.utils.sheet_add_aoa(worksheet, [[new_value]], { origin: address });

La fonction utilitaire `sheet_add_aoa` modifie les valeurs des cellules dans une feuille de calcul.  Le premier argument est l'objet de la feuille de calcul.  Le deuxième argument est un tableau de tableaux de valeurs.  La clé `origin` du troisième argument contrôle l'emplacement d'écriture des cellules.  L'extrait suivant définit `B3=1` et `E5="abc"` :```js
XLSX.utils.sheet_add_aoa(worksheet, [
  [1],                             // <-- Write 1 to cell B3
  ,                                // <-- Do nothing in row 4
  [/*B5*/, /*C5*/, /*D5*/, "abc"]  // <-- Write "abc" to cell E5
], { origin: "B3" });

Options d'analyse

Les fonctions exportées read et readFile acceptent un argument d'options :

• Même si cellNF est faux, le texte formaté sera généré et sauvegardé dans .w
• Dans certains cas, les feuilles peuvent être analysées même si bookSheets est faux.
• Excel essaie agressivement d'interpréter les valeurs provenant de CSV et d'autres textes bruts. Cela provoque un comportement surprenant ! L'option raw supprime l'analyse des valeurs.
• bookSheets et bookProps se combinent pour fournir les deux ensembles d'informations
• Deps sera un objet vide si bookDeps est faux
• Le comportement de bookFiles dépend du type de fichier :
  • tableau keys (chemins dans le ZIP) pour les formats basés sur ZIP
  • hachage files (mappage des chemins vers des objets représentant les fichiers) pour ZIP
  • objet cfb pour les formats utilisant des conteneurs CFB

Type d'entrée

Les chaînes peuvent être interprétées de plusieurs manières. Le paramètre type pour read indique à la bibliothèque comment analyser l'argument de données :

Deviner le type de fichier

</details>

## Options d'écriture

Les fonctions exportées `write` et `writeFile` acceptent un argument d'options :

| Nom de l'option |  Défaut | Description                                         |
| :-------------- | ------: | :-------------------------------------------------- |
|`type`           |          | Encodage des données de sortie (voir Type de sortie ci-dessous) |
|`cellDates`      |  `false` | Stocke les dates sous le type `d` (par défaut `n`)  |
|`bookSST`        |  `false` | Génère une table de chaînes partagées **            |
|`bookType`       | `"xlsx"` | Type de classeur (voir ci-dessous pour les formats pris en charge) |
|`sheet`          |     `""` | Nom de la feuille de calcul pour les formats à une seule feuille ** |
|`compression`    |  `false` | Utilise la compression ZIP pour les formats basés sur ZIP ** |
|`Props`          |          | Remplace les propriétés du classeur lors de l'écriture ** |
|`themeXLSX`      |          | Remplace le XML du thème lors de l'écriture XLSX/XLSB/XLSM ** |
|`ignoreEC`       |   `true` | Supprime les erreurs « nombre comme texte » **      |
|`numbers`        |          | Charge utile pour l'exportation NUMBERS **          |

- `bookSST` est plus lent et plus gourmand en mémoire, mais offre une meilleure compatibilité avec les anciennes versions d'iOS Numbers
- Les données brutes sont les seules garanties d'être sauvegardées. Les fonctionnalités non décrites dans ce README peuvent ne pas être sérialisées.
- `cellDates` ne s'applique qu'à la sortie XLSX et n'est pas garanti de fonctionner avec des lecteurs tiers. Excel lui-même n'écrit généralement pas de cellules de type `d`, donc les outils non-Excel peuvent ignorer les données ou générer une erreur en présence de dates.
- `Props` est un objet reflétant le champ `Props` du classeur. Voir le tableau de la section [Propriétés du fichier classeur](#workbook-file-properties).
- Si spécifié, la chaîne de `themeXLSX` sera sauvegardée comme thème principal pour les fichiers XLSX/XLSB/XLSM (vers `xl/theme/theme1.xml` dans le ZIP)
- En raison d'un bug dans le programme, certaines fonctionnalités comme « Convertir en colonnes » planteront Excel sur les feuilles de calcul où les conditions d'erreur sont ignorées. L'écrivain marquera les fichiers pour ignorer l'erreur par défaut. Définissez `ignoreEC` à `false` pour supprimer cela.
- En raison de la taille des données, les données NUMBERS ne sont pas incluses par défaut. Les scripts inclus `xlsx.zahl.js` et `xlsx.zahl.mjs` contiennent les données.

### Formats de sortie pris en charge

La valeur spéciale d'origine -1 indique à sheet_add_aoa de commencer dans la colonne A de la ligne après la dernière ligne de la plage, en ajoutant les données :```js XLSX.utils.sheet_add_aoa(worksheet, [ ["first row after data", 1], ["second row after data", 2] ], { origin: -1 });

</details>


### Modification des autres propriétés de feuille de calcul / classeur / cellule

La section ["Common Spreadsheet Format"](#common-spreadsheet-format) décrit les structures d'objet plus en détail.

## Emballage et publication des données

### Écriture des classeurs

**API**

_Générer des octets de feuille de calcul (fichier) à partir des données_```js
var data = XLSX.write(workbook, opts);

La méthode write tente de regrouper les données du classeur dans un fichier en mémoire. Par défaut, des fichiers XLSX sont générés, mais cela peut être contrôlé avec la propriété bookType de l'argument opts. Selon l'option type, les données peuvent être stockées sous forme de « chaîne binaire », chaîne JS, Uint8Array ou Buffer.

Le deuxième argument opts est requis. Options d'écriture couvre les propriétés et comportements pris en charge.

Générer et tenter d'enregistrer le fichier```js XLSX.writeFile(workbook, filename, opts);

La méthode `writeFile` empaquette les données et tente de sauvegarder le nouveau fichier. Le format du fichier exporté est déterminé par l'extension de `filename` (`SheetJS.xlsx` signale une exportation XLSX, `SheetJS.xlsb` signale une exportation XLSB, etc).

La méthode `writeFile` utilise des API spécifiques à la plateforme pour initier la sauvegarde du fichier. Dans NodeJS, `fs.readFileSync` peut créer un fichier. Dans le navigateur web, un téléchargement est tenté en utilisant l'attribut `download` HTML5, avec des solutions de repli pour IE.

_Générer et tenter de sauvegarder un fichier XLSX_```js
XLSX.writeFileXLSX(workbook, filename, opts);

La méthode writeFile intègre un certain nombre de fonctions d'exportation différentes. C'est excellent pour l'expérience développeur mais pas adapté à l'élimination des exports inutilisés (tree shaking) avec les outils de développement actuels. Lorsque seules les exportations XLSX sont nécessaires, cette méthode évite de référencer les autres fonctions d'exportation.

Le second argument opts est facultatif. "Writing Options" décrit les propriétés et comportements pris en charge.

Exemples

Pour Node ESM, l’assistant `writeFile` n’est pas activé. À la place, `fs.writeFileSync` devrait être utilisé pour écrire les données du fichier dans un `Buffer`, destiné à être utilisé avec `XLSX.write` :```js
import { writeFileSync } from "fs";
import { write } from "xlsx/xlsx.mjs";

const buf = write(workbook, {type: "buffer", bookType: "xlsb"});
/* buf is a Buffer */
const workbook = writeFileSync("out.xlsb", buf);

Applications writing files must be invoked with the `--allow-write` flag.  La
[`deno` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/deno/) contient plus d'exemples

</details>

<details>
  <summary><b>Fichier local dans un plugin PhotoShop ou InDesign</b> (cliquez pour afficher)</summary>

`writeFile` encapsule la logique `File` dans Photoshop et autres cibles ExtendScript.
Le chemin spécifié doit être un chemin absolu :```js
#include "xlsx.extendscript.js"

/* output format determined by filename */
XLSX.writeFile(workbook, "out.xlsx");
/* at this point, out.xlsx is a file that you can distribute */

</details>

<details>
  <summary><b>Télécharger un fichier dans les navigateurs anciens</b> (cliquez pour afficher)</summary>

Les techniques de `XLSX.writeFile` fonctionnent pour la plupart des navigateurs modernes ainsi que pour les anciens IE.
Pour les navigateurs beaucoup plus anciens, il existe des contournements implémentés par des bibliothèques wrapper.

[`FileSaver.js`](https://github.com/eligrey/FileSaver.js/) implémente `saveAs`.
Note : `XLSX.writeFile` appellera automatiquement `saveAs` si disponible.```js
/* bookType can be any supported output type */
var wopts = { bookType:"xlsx", bookSST:false, type:"array" };

var wbout = XLSX.write(workbook,wopts);

/* the saveAs call downloads a file on the local machine */
saveAs(new Blob([wbout],{type:"application/octet-stream"}), "test.xlsx");

Remarque : La section [« Traitement des tableaux HTML »](#processing-html-tables) montre comment
générer un classeur à partir de tableaux HTML dans une page en « WebKit sans tête ».

</details>



Les [démos incluses](https://github.com/weareu/xlsx/blob/HEAD/demos/) couvrent les applications mobiles et autres déploiements spéciaux.

### Exemples d'écriture

- <http://sheetjs.com/demos/table.html> exportation d'un tableau HTML
- <http://sheetjs.com/demos/writexlsx.html> génère un fichier simple

### Écriture en flux

Les fonctions d'écriture en flux sont disponibles dans l'objet `XLSX.stream`. Elles
prennent les mêmes arguments que les fonctions d'écriture normales mais retournent un
flux lisible NodeJS.

- `XLSX.stream.to_csv` est la version en flux de `XLSX.utils.sheet_to_csv`.
- `XLSX.stream.to_html` est la version en flux de `XLSX.utils.sheet_to_html`.
- `XLSX.stream.to_json` est la version en flux de `XLSX.utils.sheet_to_json`.

<details>
  <summary><b>Conversion en CSV avec Node.js et écriture dans un fichier</b> (clic pour afficher)</summary>```js
var output_file_name = "out.csv";
var stream = XLSX.stream.to_csv(worksheet);
stream.pipe(fs.createWriteStream(output_file_name));

</details>

<details>
  <summary><b>Exportation des fichiers NUMBERS</b> (cliquer pour afficher)</summary>

L'outil d'exportation NUMBERS nécessite une base assez volumineuse. Les scripts
supplémentaires `xlsx.zahl` fournissent le support. `xlsx.zahl.js` est conçu
pour une utilisation autonome et NodeJS, tandis que `xlsx.zahl.mjs` convient
pour ESM.

_Navigateur_```html
<meta charset="utf8">
<script src="xlsx.full.min.js"></script>
<script src="xlsx.zahl.js"></script>
<script>
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
  ["SheetJS", "<3","விரிதாள்"],
  [72,,"Arbeitsblätter"],
  [,62,"数据"],
  [true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL, compression: true});
</script>

_Deno_```ts
import * as XLSX from './xlsx.mjs';
import XLSX_ZAHL from './dist/xlsx.zahl.mjs';

var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
  ["SheetJS", "<3","விரிதாள்"],
  [72,,"Arbeitsblätter"],
  [,62,"数据"],
  [true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textports.numbers", {numbers: XLSX_ZAHL, compression: true});

https://github.com/sheetjs/sheetaki achemine les flux d'écriture vers la réponse nodejs.

Génération de données JSON et JS

Les données JSON et JS ont tendance à représenter des feuilles de calcul individuelles. Les fonctions utilitaires de cette section travaillent avec une seule feuille de calcul.

La section "Common Spreadsheet Format" décrit la structure de l'objet plus en détail. workbook.SheetNames est une liste ordonnée des noms de feuilles de calcul. workbook.Sheets est un objet dont les clés sont les noms des feuilles et les valeurs sont les objets feuilles de calcul.

La « première feuille de calcul » est stockée dans workbook.Sheets[workbook.SheetNames[0]].

API

Créer un tableau d'objets JS à partir d'une feuille de calcul```js var jsa = XLSX.utils.sheet_to_json(worksheet, opts);

_Créer un tableau de tableaux de valeurs JS à partir d'une feuille de calcul_```js
var aoa = XLSX.utils.sheet_to_json(worksheet, {...opts, header: 1});

La fonction utilitaire sheet_to_json parcourt un classeur ligne par ligne, générant un tableau d'objets. Le second argument opts contrôle un certain nombre de décisions d'exportation, notamment le type de valeurs (valeurs JS ou texte formaté). La section "JSON" décrit l'argument plus en détail.

Par défaut, sheet_to_json scanne la première ligne et utilise les valeurs comme en-têtes. Avec l'option header: 1, la fonction exporte un tableau de tableaux de valeurs.

Exemples

x-spreadsheet est un tableau de données interactif pour prévisualiser et modifier des données structurées dans le navigateur Web. La xspreadsheet démo inclut un script d'exemple avec la fonction stox pour convertir un classeur en objet de données x-spreadsheet. https://oss.sheetjs.com/sheetjs/x-spreadsheet est une démonstration en direct.

/* use sheet_to_json with header: 1 to generate an array of arrays */
const data = utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]], { header: 1 });

/* see react-data-grid docs to understand the shape of the expected data */
setColumns(data[0].map((r) => ({ key: r, name: r })));
setRows(data.slice(1).map((r) => r.reduce((acc, x, i) => {
  acc[data[0][i]] = x;
  return acc;
}, {})));

</details>

<details>
  <summary><b>Aperçu des données dans une grille de données VueJS</b> (cliquer pour afficher)</summary>

[`vue3-table-lite`](https://github.com/linmasahiro/vue3-table-lite) est une simple table de données VueJS 3.  Elle est présentée [dans la démo VueJS](https://github.com/weareu/xlsx/blob/HEAD/demos/vue/modify/).

</details>

<details>
  <summary><b>Remplir une base de données (SQL ou no-SQL)</b> (cliquer pour afficher)</summary>

La démo [`database`](https://github.com/weareu/xlsx/blob/HEAD/demos/database/) inclut des exemples de travail avec des bases de données et des résultats de requêtes.

</details>

<details>
  <summary><b>Calculs numériques avec TensorFlow.js</b> (cliquer pour afficher)</summary>

[`@tensorflow/tfjs`](https://github.com/weareu/xlsx/blob/HEAD/@tensorflow/tfjs) et d'autres bibliothèques s'attendent à des données sous forme de tableaux simples, bien adaptés aux feuilles de calcul où chaque colonne est un vecteur de données.  C'est la transposée de la façon dont la plupart des gens utilisent les tableurs, où chaque ligne est un vecteur.

Un seul `Array#map` peut extraire des lignes nommées individuelles de l'exportation `sheet_to_json` :```js
const XLSX = require("xlsx");
const tf = require('@tensorflow/tfjs');

const key = "age"; // this is the field we want to pull
const ages = XLSX.utils.sheet_to_json(worksheet).map(r => r[key]);
const tf_data = tf.tensor1d(ages);

La [`react` démo](https://github.com/weareu/xlsx/blob/HEAD/demos/react) inclut plus d'exemples React.

</details>

<details>
  <summary><b>VueJS : récupérer un classeur et générer des aperçus de tableau HTML</b> (cliquer pour afficher)</summary>

Il est généralement recommandé d'utiliser un workflow compatible VueJS, mais il est possible
de générer du HTML et de l'utiliser dans VueJS avec la directive `v-html` :```jsx
import { read, utils } from 'xlsx';
import { reactive } from 'vue';

const S5SComponent = {
  mounted() { (async() => {
    /* fetch and parse workbook -- see the fetch example for details */
    const workbook = read(await (await fetch("sheetjs.xlsx")).arrayBuffer());
    /* loop through the worksheet names in order */
    workbook.SheetNames.forEach(name => {
      /* generate HTML from the corresponding worksheets */
      const html = utils.sheet_to_html(workbook.Sheets[name]);
      /* add to state */
      this.wb.wb.push({ name, html });
    });
  })(); },
  /* this state mantra is required for array updates to work */
  setup() { return { wb: reactive({ wb: [] }) }; },
  template: `
  <div v-for="ws in wb.wb" :key="ws.name">
    <h3>{{ ws.name }}</h3>
    <div v-html="ws.html"></div>
  </div>`
};

Génération d'instantanés de feuille unique

Les fonctions sheet_to_* acceptent un objet feuille de calcul.

API

Générer un CSV à partir d'une seule feuille de calcul```js var csv = XLSX.utils.sheet_to_csv(worksheet, opts);

Cet instantané est conçu pour reproduire le type de sortie "CSV UTF8 (`.csv`)".
["Sortie séparée par des délimiteurs"](#delimiter-separated-output) décrit la
fonction et l'argument optionnel `opts` plus en détail.

_Générer "Texte" à partir d'une seule feuille de calcul_```js
var txt = XLSX.utils.sheet_to_txt(worksheet, opts);

Ce snapshot est conçu pour reproduire le type de sortie "Texte UTF16 (.txt)". "Sortie séparée par des délimiteurs" décrit la fonction et l'argument optionnel opts plus en détail.

Générer une liste de formules à partir d'une seule feuille de calcul```js var fmla = XLSX.utils.sheet_to_formulae(worksheet);

Cet instantané génère un tableau d'entrées représentant les formules intégrées. Les formules matricielles sont rendues sous la forme `range=formule` tandis que les cellules simples sont rendues sous la forme `cell=formule ou valeur`.  Les littéraux de chaîne sont préfixés d'une apostrophe `'`, conformément à l'affichage de la barre de formule d'Excel.

["Sortie des formules"](#formulae-output) décrit la fonction plus en détail.

## Interface

`XLSX` est la variable exposée dans le navigateur et la variable exportée de Node.

`XLSX.version` est la version de la bibliothèque (ajoutée par le script de construction).

`XLSX.SSF` est une version intégrée de la [bibliothèque de format](https://git.io/ssf).

### Fonctions d'analyse

`XLSX.read(data, read_opts)` tente d'analyser `data`.

`XLSX.readFile(filename, read_opts)` tente de lire `filename` et de l'analyser.

Les options d'analyse sont décrites dans la section [Options d'analyse](#parsing-options).

### Fonctions d'écriture

`XLSX.write(wb, write_opts)` tente d'écrire le classeur `wb`.

`XLSX.writeFile(wb, filename, write_opts)` tente d'écrire `wb` dans `filename`. Dans des environnements basés sur un navigateur, il tentera de forcer un téléchargement côté client.

`XLSX.writeFileAsync(wb, filename, o, cb)` tente d'écrire `wb` dans `filename`. Si `o` est omis, l'écrivain utilisera le troisième argument comme fonction de rappel.

`XLSX.stream` contient un ensemble de fonctions d'écriture en flux.

Les options d'écriture sont décrites dans la section [Options d'écriture](#writing-options).

### Utilitaires

Les utilitaires sont disponibles dans l'objet `XLSX.utils` et sont décrits dans la section [Fonctions utilitaires](#utility-functions) :

**Construction :**

- `book_new` crée un classeur vide
- `book_append_sheet` ajoute une feuille de calcul à un classeur

**Importation :**

- `aoa_to_sheet` convertit un tableau de tableaux de données JS en une feuille de calcul.
- `json_to_sheet` convertit un tableau d'objets JS en une feuille de calcul.
- `table_to_sheet` convertit un élément DOM TABLE en une feuille de calcul.
- `sheet_add_aoa` ajoute un tableau de tableaux de données JS à une feuille de calcul existante.
- `sheet_add_json` ajoute un tableau d'objets JS à une feuille de calcul existante.

**Exportation :**

- `sheet_to_json` convertit un objet feuille de calcul en un tableau d'objets JSON.
- `sheet_to_csv` génère une sortie de valeurs séparées par un délimiteur.
- `sheet_to_txt` génère du texte formaté en UTF16.
- `sheet_to_html` génère une sortie HTML.
- `sheet_to_formulae` génère une liste des formules (avec des valeurs de repli).

**Manipulation des cellules et des adresses de cellules :**

- `format_cell` génère la valeur textuelle d'une cellule (en utilisant les formats de nombre).
- `encode_row / decode_row` convertit entre les lignes indexées à 0 et les lignes indexées à 1.
- `encode_col / decode_col` convertit entre les colonnes indexées à 0 et les noms de colonnes.
- `encode_cell / decode_cell` convertit les adresses de cellule.
- `encode_range / decode_range` convertit les plages de cellules.

## Common Spreadsheet Format

SheetJS est conforme au Common Spreadsheet Format (CSF) :

### Structures générales

Les objets d'adresse de cellule sont stockés sous la forme `{c:C, r:R}` où `C` et `R` sont respectivement les numéros de colonne et de ligne indexés à 0.  Par exemple, l'adresse de cellule `B5` est représentée par l'objet `{c:1, r:4}`.

Les objets de plage de cellules sont stockés sous la forme `{s:S, e:E}` où `S` est la première cellule et `E` la dernière cellule de la plage.  Les plages sont inclusives.  Par exemple, la plage `A3:B7` est représentée par l'objet `{s:{c:0, r:2}, e:{c:1, r:6}}`.
Les fonctions utilitaires effectuent un parcours dans l'ordre principal des lignes d'une plage de feuille de calcul :```js
for(var R = range.s.r; R <= range.e.r; ++R) {
  for(var C = range.s.c; C <= range.e.c; ++C) {
    var cell_address = {c:C, r:R};
    /* if an A1-style address is needed, encode the address */
    var cell_ref = XLSX.utils.encode_cell(cell_address);
  }
}

Cell Object

Les objets Cell sont de simples objets JS dont les clés et valeurs suivent la convention suivante :

Les utilitaires d'exportation intégrés (tels que l'exportateur CSV) utiliseront le texte w s'il est disponible. Pour modifier une valeur, assurez-vous de supprimer cell.w (ou de le définir sur undefined) avant de tenter d'exporter. Les utilitaires régénéreront le texte w à partir du format de nombre (cell.z) et de la valeur brute si possible.

La formule matricielle réelle est stockée dans le champ f de la première cellule de la plage matricielle. Les autres cellules de la plage omettront le champ f.

Data Types

La valeur brute est stockée dans la propriété de valeur v, interprétée en fonction du type t. Cette séparation permet de représenter à la fois des nombres et du texte numérique. Il existe 6 types de cellules valides :

Le type n est le type Nombre. Il inclut toutes les formes de données qu'Excel stocke sous forme de nombres, comme les dates/heures et les champs booléens. Excel utilise exclusivement des données pouvant tenir dans un nombre à virgule flottante IEEE754, tout comme le type Number de JS, donc le champ v contient le nombre brut. Le champ w contient le texte formaté. Les dates sont stockées sous forme de nombres par défaut et converties avec XLSX.SSF.parse_date_code.

Le type d est le type Date, généré uniquement lorsque l'option cellDates est transmise. Comme JSON n'a pas de type Date naturel, les analyseurs sont généralement censés stocker des chaînes de date ISO 8601 comme celles que vous obtiendriez de date.toISOString(). D'autre part, les rédacteurs et exportateurs doivent être capables de traiter les chaînes de date et les objets Date JS. Notez qu'Excel ignore les modificateurs de fuseau horaire et traite toutes les dates dans le fuseau horaire local. La bibliothèque ne corrige pas cette erreur.

Le type s est le type Chaîne. Les valeurs sont explicitement stockées sous forme de texte. Excel interprétera ces cellules comme "nombre stocké sous forme de texte". Les fichiers Excel générés suppriment automatiquement cette classe d'erreur, mais d'autres formats peuvent provoquer des erreurs.

Le type z représente les cellules stub vides. Elles sont générées dans les cas où les cellules n'ont pas de valeur attribuée mais contiennent des commentaires ou d'autres métadonnées. Elles sont ignorées par les fonctions utilitaires de traitement de données de la bibliothèque principale. Par défaut, ces cellules ne sont pas générées ; l'option d'analyse sheetStubs doit être définie sur true.

Dates

</details>

### Objets de feuille

Chaque clé qui ne commence pas par `!` correspond à une cellule (en utilisant la notation `A-1`)

`sheet[address]` renvoie l'objet cellule pour l'adresse spécifiée.

**Clés spéciales de feuille (accessibles sous la forme `sheet[key]`, chacune commençant par `!`):**

- `sheet['!ref']` : Plage basée sur A-1 représentant la plage de la feuille. Les fonctions qui travaillent avec des feuilles doivent utiliser ce paramètre pour déterminer la plage. Les cellules assignées en dehors de la plage ne sont pas traitées. En particulier, lors de la création manuelle d'une feuille, les cellules en dehors de la plage ne sont pas incluses.

  Les fonctions qui manipulent les feuilles doivent vérifier la présence du champ `!ref`. Si `!ref` est omis ou n'est pas une plage valide, les fonctions sont libres de traiter la feuille comme vide ou de tenter de deviner la plage. Les utilitaires standards fournis avec cette bibliothèque traitent les feuilles comme vides (par exemple, la sortie CSV est une chaîne vide).

  Lors de la lecture d'une feuille de calcul avec la propriété `sheetRows` définie, le paramètre ref utilisera la plage restreinte. La plage d'origine est définie dans `ws['!fullref']`

- `sheet['!margins']` : Objet représentant les marges de la page. Les valeurs par défaut suivent le préréglage « normal » d'Excel. Excel propose également des préréglages « large » et « étroit », mais ils sont stockés sous forme de mesures brutes. Les principales propriétés sont listées ci-dessous :

<details>
  <summary><b>Détails des marges de page</b> (cliquez pour afficher)</summary>

| clé      | description            | "normal" | "large" | "étroit" |
|----------|------------------------|:---------|:-------|:-------- |
| `left`   | marge gauche (pouces)   | `0.7`    | `1.0`  | `0.25`   |
| `right`  | marge droite (pouces)  | `0.7`    | `1.0`  | `0.25`   |
| `top`    | marge haute (pouces)    | `0.75`   | `1.0`  | `0.75`   |
| `bottom` | marge basse (pouces) | `0.75`   | `1.0`  | `0.75`   |
| `header` | marge d'en-tête (pouces) | `0.3`    | `0.5`  | `0.3`    |
| `footer` | marge de pied de page (pouces) | `0.3`    | `0.5`  | `0.3`    |```js
/* Set worksheet sheet to "normal" */
ws["!margins"]={left:0.7, right:0.7, top:0.75,bottom:0.75,header:0.3,footer:0.3}
/* Set worksheet sheet to "wide" */
ws["!margins"]={left:1.0, right:1.0, top:1.0, bottom:1.0, header:0.5,footer:0.5}
/* Set worksheet sheet to "narrow" */
ws["!margins"]={left:0.25,right:0.25,top:0.75,bottom:0.75,header:0.3,footer:0.3}

Objet Feuille de Calcul

En plus des clés de base de la feuille, les feuilles de calcul ajoutent également :

• ws['!cols'] : tableau d'objets de propriétés de colonnes. Les largeurs de colonnes sont en fait stockées dans les fichiers de manière normalisée, mesurées en termes de "Largeur Maximale de Chiffre" (la plus grande largeur des chiffres rendus 0-9, en pixels). Lors de l'analyse, les objets de colonne stockent la largeur en pixels dans le champ wpx, la largeur en caractères dans le champ wch, et la largeur maximale de chiffre dans le champ MDW.

• ws['!rows'] : tableau d'objets de propriétés de lignes comme expliqué plus loin dans la documentation. Chaque objet ligne encode des propriétés incluant la hauteur de ligne et la visibilité.

• ws['!merges'] : tableau d'objets de plage correspondant aux cellules fusionnées dans la feuille de calcul. Les formats de texte brut ne supportent pas les cellules fusionnées. L'export CSV écrira toutes les cellules de la plage fusionnée si elles existent, alors assurez-vous que seule la première cellule (en haut à gauche) de la plage est définie.

• ws['!outline'] : configurer le comportement des plans. Les options par défaut sont les paramètres par défaut d'Excel 2019 :

• ws['!protect'] : objet des propriétés de protection de feuille en écriture. La clé password spécifie le mot de passe pour les formats supportant les feuilles protégées par mot de passe (XLSX/XLSB/XLS). L'écrivain utilise la méthode d'obfuscation XOR. Les clés suivantes contrôlent la protection de la feuille — définir sur false pour activer une fonctionnalité lorsque la feuille est verrouillée ou sur true pour la désactiver :

• ws['!autofilter'] : objet AutoFilter suivant le schéma :```typescript type AutoFilter = { ref:string; // A-1 based range representing the AutoFilter table range }

#### Objet Chartsheet

Les Chartsheets sont représentés comme des feuilles standard.  Ils se distinguent avec la propriété `!type` définie à `"chart"`.

Les données sous-jacentes et `!ref` font référence aux données mises en cache dans le chartsheet.  La première ligne du chartsheet est l'en-tête sous-jacent.

#### Objet Macrosheet

Les Macrosheets sont représentés comme des feuilles standard.  Ils se distinguent avec la propriété `!type` définie à `"macro"`.

#### Objet Dialogsheet

Les Dialogsheets sont représentés comme des feuilles standard. Ils se distinguent avec la propriété `!type` définie à `"dialog"`.

### Objet Workbook

`workbook.SheetNames` est une liste ordonnée des feuilles dans le classeur

`wb.Sheets[sheetname]` renvoie un objet représentant la feuille de calcul.

`wb.Props` est un objet stockant les propriétés standard.  `wb.Custprops` stocke les propriétés personnalisées. Étant donné que les propriétés standard XLS diffèrent de la norme XLSX, l'analyse XLS stocke les propriétés de base dans les deux endroits.

`wb.Workbook` stocke les [attributs au niveau du classeur](#workbook-level-attributes).

#### Propriétés du fichier du classeur

Les différents formats de fichiers utilisent des noms internes différents pour les propriétés de fichier.  L'objet `Props` du classeur normalise les noms :

<details>
  <summary><b>Propriétés du fichier</b> (cliquer pour afficher)</summary>

| Nom JS        | Description Excel                     |
|:--------------|:--------------------------------------|
| `Title`       | Onglet Résumé "Titre"                 |
| `Subject`     | Onglet Résumé "Sujet"                 |
| `Author`      | Onglet Résumé "Auteur"                |
| `Manager`     | Onglet Résumé "Responsable"           |
| `Company`     | Onglet Résumé "Société"               |
| `Category`    | Onglet Résumé "Catégorie"             |
| `Keywords`    | Onglet Résumé "Mots-clés"             |
| `Comments`    | Onglet Résumé "Commentaires"          |
| `LastAuthor`  | Onglet Statistiques "Dernière sauvegarde par" |
| `CreatedDate` | Onglet Statistiques "Créé"            |

</details>

Par exemple, pour définir la propriété de titre du classeur :```js
if(!wb.Props) wb.Props = {};
wb.Props.Title = "Insert Title Here";

Les propriétés personnalisées sont ajoutées dans l'objet Custprops du classeur :```js if(!wb.Custprops) wb.Custprops = {}; wb.Custprops["Custom Property"] = "Custom Value";

Les Writers traiteront la clé `Props` de l'objet options :```js
/* force the Author to be "SheetJS" */
XLSX.write(wb, {Props:{Author:"SheetJS"}});

Attributs au niveau du classeur

wb.Workbook stocke les attributs au niveau du classeur.

Noms définis

wb.Workbook.Names est un tableau d'objets de nom définis qui possèdent les clés :

Excel permet à deux noms définis dans la portée d'une feuille de partager le même nom. Cependant, un nom de portée de feuille ne peut pas entrer en collision avec un nom de portée de classeur. Les créateurs de classeurs peuvent ne pas appliquer cette contrainte.

Vues du classeur

wb.Workbook.Views est un tableau d'objets de vue du classeur qui possèdent les clés :

Propriétés diverses du classeur

wb.Workbook.WBProps contient d'autres propriétés du classeur :

Fonctionnalités du document

Même pour des fonctionnalités de base comme le stockage des dates, les formats Excel officiels stockent le même contenu de différentes manières. Les analyseurs sont censés convertir de la représentation du format de fichier sous-jacent au format Common Spreadsheet Format. Les créateurs sont censés reconvertir du CSF au format de fichier sous-jacent.

Formules

La chaîne de formule de style A1 est stockée dans le champ f. Bien que différents formats de fichier stockent les formules de différentes manières, les formats sont traduits. Même si certains formats stockent les formules avec un signe égal en tête, les formules CSF ne commencent pas par =.

Formules à cellule unique

Pour les formules simples, la clé f de la cellule souhaitée peut être définie sur le texte réel de la formule. Cette feuille de calcul représente A1=1, A2=2 et A3=A1+A2 :```js var worksheet = { "!ref": "A1:A3", A1: { t:'n', v:1 }, A2: { t:'n', v:2 }, A3: { t:'n', v:3, f:'A1+A2' } };

Les utilitaires comme `aoa_to_sheet` acceptent des objets de cellule à la place des valeurs :```js
var worksheet = XLSX.utils.aoa_to_sheet([
  [ 1 ], // A1
  [ 2 ], // A2
  [ {t: "n", v: 3, f: "A1+A2"} ] // A3
]);

Les cellules contenant des entrées de formule mais sans valeur seront sérialisées d'une manière que Excel et d'autres outils de tableur reconnaîtront. Cette bibliothèque ne calculera pas automatiquement les résultats des formules ! Par exemple, la feuille de calcul suivante inclura la fonction BESSELJ mais le résultat ne sera pas disponible en JavaScript :```js var worksheet = XLSX.utils.aoa_to_sheet([ [ 3.14159, 2 ], // Row "1" [ { t:'n', f:'BESSELJ(A1,B1)' } ] // Row "2" will be calculated on file open }

Si les résultats réels sont nécessaires en JS, [SheetJS Pro](https://sheetjs.com/pro)
propose un composant de calcul de formules pour évaluer des expressions, mettre à jour
les valeurs et les cellules dépendantes, et actualiser des classeurs entiers.

**Formules de tableau**

_Attribuer une formule de tableau_```js
XLSX.utils.sheet_set_array_formula(worksheet, range, formula);

Les formules matricielles sont stockées dans la cellule en haut à gauche du bloc matriciel. Toutes les cellules d'une formule matricielle ont un champ F correspondant à la plage. Une formule monocellulaire peut être distinguée d'une formule simple par la présence du champ F.

Par exemple, en définissant la cellule C1 à la formule matricielle {=SUM(A1:A3*B1:B3)} :```js // API function XLSX.utils.sheet_set_array_formula(worksheet, "C1", "SUM(A1:A3*B1:B3)");

// ... OR raw operations worksheet['C1'] = { t:'n', f: "SUM(A1:A3*B1:B3)", F:"C1:C1" };

Pour une formule de tableau multi-cellules, chaque cellule a la même plage de tableau mais seule la première cellule spécifie la formule.  Considérez `D1:D3=A1:A3*B1:B3` :```js
// API function
XLSX.utils.sheet_set_array_formula(worksheet, "D1:D3", "A1:A3*B1:B3");

// ... OR raw operations
worksheet['D1'] = { t:'n', F:"D1:D3", f:"A1:A3*B1:B3" };
worksheet['D2'] = { t:'n', F:"D1:D3" };
worksheet['D3'] = { t:'n', F:"D1:D3" };

Les utilitaires et rédacteurs sont censés vérifier la présence d'un champ F et ignorer tout élément de formule f possible dans les cellules autres que la cellule de départ. Ils ne sont pas censés effectuer la validation des formules !

Formules de matrice dynamique

Assigner une formule de matrice dynamique```js XLSX.utils.sheet_set_array_formula(worksheet, range, formula, true);

Publiées en 2020, les formules de tableau dynamique sont prises en charge dans les formats de fichiers XLSX/XLSM et XLSB.  Elles sont représentées comme des formules matricielles normales mais possèdent des métadonnées de cellule spéciales indiquant que la formule doit pouvoir ajuster la plage.

Une formule matricielle peut être marquée comme dynamique en définissant la propriété `D` de la cellule sur true.  La plage `F` est attendue mais peut être définie sur la cellule actuelle :```js
// API function
XLSX.utils.sheet_set_array_formula(worksheet, "C1", "_xlfn.UNIQUE(A1:A3)", 1);

// ... OR raw operations
worksheet['C1'] = { t: "s", f: "_xlfn.UNIQUE(A1:A3)", F:"C1", D: 1 }; // dynamic

Localisation avec les noms de fonctions

SheetJS fonctionne au niveau du fichier. Excel stocke les expressions de formule en utilisant les noms de fonctions anglais (États-Unis). Pour les utilisateurs non anglophones, Excel utilise un ensemble localisé de noms de fonctions.

Par exemple, lorsque la langue et la région de l'ordinateur sont définies sur Français (France), Excel interprète =SOMME(A1:C3) comme si SOMME était la fonction SUM. Cependant, dans le fichier réel, Excel stocke SUM(A1:C3).

Préfixe des « fonctions futures »

Les fonctions introduites dans les versions plus récentes d'Excel sont préfixées par _xlfn. lorsqu'elles sont stockées dans les fichiers. Lors de l'écriture d'expressions de formule utilisant ces fonctions, le préfixe est nécessaire pour une compatibilité maximale :```js // Broadest compatibility XLSX.utils.sheet_set_array_formula(worksheet, "C1", "_xlfn.UNIQUE(A1:A3)", 1);

// Can cause errors in spreadsheet software XLSX.utils.sheet_set_array_formula(worksheet, "C1", "UNIQUE(A1:A3)", 1);

Lors de la lecture d'un fichier, l'option `xlfn` préserve les préfixes.

<details>
  <summary><b> Fonctions nécessitant le préfixe `_xlfn.`</b> (cliquer pour afficher)</summary>

Cette liste s'allonge à chaque version d'Excel.```
ACOT
ACOTH
AGGREGATE
ARABIC
BASE
BETA.DIST
BETA.INV
BINOM.DIST
BINOM.DIST.RANGE
BINOM.INV
BITAND
BITLSHIFT
BITOR
BITRSHIFT
BITXOR
BYCOL
BYROW
CEILING.MATH
CEILING.PRECISE
CHISQ.DIST
CHISQ.DIST.RT
CHISQ.INV
CHISQ.INV.RT
CHISQ.TEST
COMBINA
CONFIDENCE.NORM
CONFIDENCE.T
COT
COTH
COVARIANCE.P
COVARIANCE.S
CSC
CSCH
DAYS
DECIMAL
ERF.PRECISE
ERFC.PRECISE
EXPON.DIST
F.DIST
F.DIST.RT
F.INV
F.INV.RT
F.TEST
FIELDVALUE
FILTERXML
FLOOR.MATH
FLOOR.PRECISE
FORMULATEXT
GAMMA
GAMMA.DIST
GAMMA.INV
GAMMALN.PRECISE
GAUSS
HYPGEOM.DIST
IFNA
IMCOSH
IMCOT
IMCSC
IMCSCH
IMSEC
IMSECH
IMSINH
IMTAN
ISFORMULA
ISOMITTED
ISOWEEKNUM
LAMBDA
LET
LOGNORM.DIST
LOGNORM.INV
MAKEARRAY
MAP
MODE.MULT
MODE.SNGL
MUNIT
NEGBINOM.DIST
NORM.DIST
NORM.INV
NORM.S.DIST
NORM.S.INV
NUMBERVALUE
PDURATION
PERCENTILE.EXC
PERCENTILE.INC
PERCENTRANK.EXC
PERCENTRANK.INC
PERMUTATIONA
PHI
POISSON.DIST
QUARTILE.EXC
QUARTILE.INC
QUERYSTRING
RANDARRAY
RANK.AVG
RANK.EQ
REDUCE
RRI
SCAN
SEC
SECH
SEQUENCE
SHEET
SHEETS
SKEW.P
SORTBY
STDEV.P
STDEV.S
T.DIST
T.DIST.2T
T.DIST.RT
T.INV
T.INV.2T
T.TEST
UNICHAR
UNICODE
UNIQUE
VAR.P
VAR.S
WEBSERVICE
WEIBULL.DIST
XLOOKUP
XOR
Z.TEST

Propriétés des lignes : XLSX/M, XLSB, BIFF8 XLS, XLML, SYLK, DOM

Propriétés des colonnes : XLSX/M, XLSB, BIFF8 XLS, XLML, SYLK, DOM

Il existe trois types de largeur différents correspondant aux trois manières dont les tableurs stockent les largeurs de colonnes :

Les formats SYLK et autres formats texte brut utilisent un comptage brut de caractères. Les outils contemporains comme Visicalc et Multiplan étaient basés sur les caractères. Puisque les caractères avaient la même largeur, il suffisait de stocker un comptage. Cette tradition s'est poursuivie dans les formats BIFF.

SpreadsheetML (2003) a tenté de s'aligner sur HTML en standardisant le comptage des pixels à l'écran dans tout le fichier. Les largeurs de colonnes, les hauteurs de lignes et autres mesures utilisent des pixels. Lorsque les comptages de pixels et de caractères ne correspondent pas, Excel arrondit les valeurs.

XLSX stocke en interne les largeurs de colonnes sous une forme nébuleuse de "Largeur maximale des chiffres" (Max Digit Width). La largeur maximale des chiffres est la largeur du chiffre le plus grand lorsqu'il est rendu (généralement le caractère "0" est le plus large). La largeur interne doit être un multiple entier de la largeur divisée par 256. ECMA-376 décrit une formule pour convertir entre les pixels et la largeur interne. Cela représente une approche hybride.

Les fonctions de lecture tentent de renseigner les trois propriétés. Les fonctions d'écriture essaieront de convertir les valeurs spécifiées vers le type souhaité. Pour éviter les conflits potentiels, la manipulation doit d'abord supprimer les autres propriétés. Par exemple, lors du changement de la largeur en pixels, supprimez les propriétés wch et width.

Hauteurs des lignes

Excel stocke en interne les hauteurs de lignes en points. La résolution par défaut est 72 DPI ou 96 PPI, donc la taille en pixels et en points devrait correspondre. Pour des résolutions différentes, elles peuvent ne pas correspondre, donc la bibliothèque sépare les concepts.

Même si toutes les informations sont disponibles, les fonctions d'écriture doivent suivre l'ordre de priorité :

1. utiliser la hauteur en pixels hpx si disponible
2. utiliser la hauteur en points hpt si disponible

Largeurs des colonnes

Compte tenu des contraintes, il est possible de déterminer le MDW sans inspecter réellement la police ! Les analyseurs devinent la largeur en pixels en convertissant de la largeur en pixels et inversement, en répétant pour tous les MDW possibles et en sélectionnant le MDW qui minimise l'erreur. XLML stocke en réalité la largeur en pixels, donc la devinette fonctionne dans le sens inverse.

Même si toutes les informations sont disponibles, les fonctions d'écriture doivent suivre l'ordre de priorité :

1. utiliser le champ width si disponible
2. utiliser la largeur en pixels wpx si disponible
3. utiliser le comptage de caractères wch si disponible

Les formats par défaut sont répertoriés dans ECMA-376 18.8.30 :

Hyperliens de cellule : XLSX/M, XLSB, BIFF8 XLS, XLML, ODS

Infobulles : XLSX/M, XLSB, BIFF8 XLS, XLML