El objetivo es generar un libro de trabajo XLSB con los nombres y cumpleaños de los presidentes de EE. UU.

Adquirir datos

Datos sin procesar

https://theunitedstates.io/congress-legislators/executive.json contiene los datos deseados. Por ejemplo, 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" ] }

_Filtrado para Presidentes_

El conjunto de datos incluye a Aaron Burr, un Vicepresidente que nunca fue Presidente.

`Array#filter` crea un nuevo array con las filas deseadas.  Un Presidente sirvió
al menos un mandato con `type` establecido en `"prez"`.  Para comprobar si una fila concreta tiene
al menos un mandato `"prez"`, `Array#some` es otra función nativa de JS.  El
filtro completo sería:```js
const prez = raw_data.filter(row => row.terms.some(term => term.type === "prez"));

Alineando los datos

Para este ejemplo, el nombre será el primer nombre combinado con el apellido (row.name.first + " " + row.name.last) y la fecha de nacimiento será el subcampo row.bio.birthday. Usando Array#map, el conjunto de datos se puede transformar en una sola llamada:```js const rows = prez.map(row => ({ name: row.name.first + " " + row.name.last, birthday: row.bio.birthday }));

El resultado es un array de objetos "simples" sin anidamiento:```js
[
  { name: "George Washington", birthday: "1732-02-22" },
  { name: "John Adams", birthday: "1735-10-19" },
  // ... one row per President
]

Extraer datos

Con el conjunto de datos limpio, XLSX.utils.json_to_sheet genera una hoja de cálculo:```js const worksheet = XLSX.utils.json_to_sheet(rows);

`XLSX.utils.book_new` crea un nuevo libro de trabajo y `XLSX.utils.book_append_sheet` añade una hoja de cálculo al libro de trabajo. La nueva hoja de cálculo se llamará "Dates":```js
const workbook = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(workbook, worksheet, "Dates");

Process Data

Fixing headers

Por defecto, json_to_sheet crea una hoja de cálculo con una fila de encabezados. En este caso, los encabezados provienen de las claves del objeto JS: "name" y "birthday".

Los encabezados están en las celdas A1 y B1. XLSX.utils.sheet_add_aoa puede escribir valores de texto en la hoja de cálculo existente comenzando en la celda A1:```js XLSX.utils.sheet_add_aoa(worksheet, [["Name", "Birthday"]], { origin: "A1" });

_Fixing Column Widths_

Algunos de los nombres son más largos que el ancho de columna predeterminado.  Los anchos de columna se establecen mediante [la propiedad de la hoja de cálculo `"!cols"`](#row-and-column-properties).

La siguiente línea establece el ancho de la columna A en aproximadamente 10 caracteres:```js
worksheet["!cols"] = [ { wch: 10 } ]; // set column A width to 10 characters

Una llamada a Array#reduce sobre rows puede calcular el ancho máximo:```js const max_width = rows.reduce((w, r) => Math.max(w, r.name.length), 10); worksheet["!cols"] = [ { wch: max_width } ];

Nota: Si el punto de partida era un archivo o una tabla HTML, `XLSX.utils.sheet_to_json`
generará una matriz de objetos JS.

**Datos de Paquete y Versión**

`XLSX.writeFile` crea un archivo de hoja de cálculo e intenta escribirlo en el sistema.
En el navegador, intentará solicitar al usuario que descargue el archivo.  En NodeJS,
lo escribirá en el directorio local.```js
XLSX.writeFile(workbook, "Presidents.xlsx");

Ejemplo completo```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"); })();

Para usar en el navegador web, suponiendo que el snippet se guarde como `snippet.js`, se deben usar etiquetas de script para incluir las compilaciones independientes de `axios` y `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 utiliza fs.readFileSync bajo el capó:```js var XLSX = require("xlsx");

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

Para Node ESM, el helper `readFile` no está habilitado. En su lugar, `fs.readFileSync`
debe usarse para leer los datos del archivo como un `Buffer` para usarlos con `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 utiliza Deno.readFileSync internamente:```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");

Las aplicaciones que leen archivos deben invocarse con el indicador `--allow-read`.  El
[`deno` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/deno/) tiene más ejemplos

</details>

<details>
  <summary><b>Archivo enviado por el usuario en una página web ("Arrastrar y soltar")</b> (click to show)</summary>

Para sitios web modernos que apuntan a Chrome 76+, se recomienda `File#arrayBuffer`:```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);

Para máxima compatibilidad, se debe usar la API FileReader:```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/> demuestra la técnica de FileReader.

</details>

<details>
  <summary><b>Archivo enviado por el usuario con un elemento HTML INPUT</b> (clic para mostrar)</summary>

Empezando con un elemento HTML INPUT con `type="file"`:```html
<input type="file" id="input_dom_element">

Para sitios web modernos que apuntan a Chrome 76+, se recomienda Blob#arrayBuffer:```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);

Para una compatibilidad más amplia (incluido IE10+), se recomienda el enfoque `FileReader`:```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);

La demo oldie muestra un escenario de respaldo compatible con IE.

Para sitios web modernos dirigidos a Chrome 42+, se recomienda fetch:```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 */ })();

Para una compatibilidad más amplia, se recomienda el enfoque `XMLHttpRequest`:```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 demo xhr incluye una discusión más detallada y más ejemplos.

http://oss.sheetjs.com/sheetjs/ajax.html muestra enfoques de respaldo para IE6+.

readFile envuelve la lógica de File en Photoshop y otros destinos de ExtendScript. La ruta especificada debe ser una ruta absoluta:```js #include "xlsx.extendscript.js"

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

La [demostración de `extendscript`](https://github.com/weareu/xlsx/blob/HEAD/demos/extendscript/) incluye un ejemplo más complejo.

</details>

<details>
  <summary><b>Archivo local en una aplicación Electron</b> (haz clic para mostrar)</summary>

`readFile` se puede usar en el proceso de renderizado:```js
/* From the renderer process */
var XLSX = require("xlsx");

var workbook = XLSX.readFile(path);

Las APIs de Electron han cambiado con el tiempo. La electron demo muestra un ejemplo completo y detalla la configuración requerida específica de la versión.

La react demo incluye una aplicación React Native de ejemplo.

Dado que React Native no ofrece una forma de leer archivos del sistema de archivos, se debe utilizar una biblioteca de terceros. Se han probado las siguientes bibliotecas:

• react-native-file-access

La codificación base64 devuelve cadenas compatibles con el tipo 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)

La codificación `ascii` devuelve cadenas binarias compatibles con el tipo `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 puede aceptar un buffer de NodeJS. readFile puede leer archivos generados por un analizador de cuerpo de solicitudes HTTP POST como 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);

La [demo `server`](https://github.com/weareu/xlsx/blob/HEAD/demos/server) tiene ejemplos más avanzados.

</details>

<details>
  <summary><b>Descargar archivos en un proceso NodeJS</b> (haz clic para mostrar)</summary>

Node 17.5 y 18.0 tienen soporte nativo para fetch:```js
const XLSX = require("xlsx");

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

Para una mayor compatibilidad, se recomiendan módulos de terceros.

request requiere una codificación null para producir 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) funciona de la misma manera en el navegador y en 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 */
})();

El módulo net en el proceso principal puede realizar solicitudes HTTP/HTTPS a recursos externos. Las respuestas deben concatenarse manualmente usando 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>Flujos legibles en NodeJS</b> (clic para mostrar)</summary>

Al trabajar con flujos legibles, el enfoque más sencillo es almacenar en búfer el flujo
y procesar todo al final:```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);
  });
}

Al trabajar con ReadableStream, el enfoque más sencillo es almacenar en búfer el flujo y procesar todo al final:```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>

Los ejemplos más detallados están cubiertos en las [demostraciones incluidas](https://github.com/weareu/xlsx/blob/HEAD/demos/)

### Procesamiento de datos JSON y JS

Los datos JSON y JS tienden a representar hojas de cálculo individuales. Esta sección utilizará algunas funciones de utilidad para generar libros de trabajo.

_Crear un nuevo Workbook_```js
var workbook = XLSX.utils.book_new();

La función de utilidad book_new crea un libro de trabajo vacío sin hojas de cálculo.

El software de hojas de cálculo generalmente requiere al menos una hoja de cálculo y aplica el requisito en la interfaz de usuario. Esta librería aplica el requisito al escribir, lanzando errores si se pasa un libro de trabajo vacío a las funciones de escritura.

API

Crear una hoja de cálculo a partir de un array de arrays de valores JS```js var worksheet = XLSX.utils.aoa_to_sheet(aoa, opts);

La función de utilidad `aoa_to_sheet` recorre una "matriz de matrices" en orden fila-principal, generando un objeto de hoja de cálculo. El siguiente fragmento genera una hoja con la celda `A1` establecida en la cadena `A1`, la celda `B1` en `B1`, etc:```js
var worksheet = XLSX.utils.aoa_to_sheet([
  ["A1", "B1", "C1"],
  ["A2", "B2", "C2"],
  ["A3", "B3", "C3"]
]);

"Entrada de matriz de matrices" describe la función y el argumento opcional opts con más detalle.

Crear una hoja de cálculo a partir de una matriz de objetos JS```js var worksheet = XLSX.utils.json_to_sheet(jsa, opts);

La función de utilidad `json_to_sheet` recorre un array de objetos JS en orden,
generando un objeto de hoja de cálculo.  Por defecto, generará una fila de encabezado y
una fila por objeto en el array.  El argumento opcional `opts` tiene configuraciones para
controlar el orden de las columnas y la salida del encabezado.

["Entrada de array de objetos"](#array-of-arrays-input) describe la función y
el argumento opcional `opts` con más detalle.

**Ejemplos**

["Zen de SheetJS"](#the-zen-of-sheetjs) contiene un ejemplo detallado "Obtener datos
de un endpoint JSON y generar un libro de trabajo"


[`x-spreadsheet`](https://github.com/myliang/x-spreadsheet) es una cuadrícula interactiva
de datos para previsualizar y modificar datos estructurados en el navegador web.  El
[`xspreadsheet` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/xspreadsheet) incluye un script de ejemplo con la
función `xtos` para convertir desde el objeto de datos de x-spreadsheet a un libro de trabajo.
<https://oss.sheetjs.com/sheetjs/x-spreadsheet> es una demo en vivo.

<details>
  <summary><b>Registros de una consulta de base de datos (SQL o no-SQL)</b> (haz clic para mostrar)</summary>

El [`database` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/database/) incluye ejemplos de trabajo con
bases de datos y resultados de consultas.

</details>


<details>
  <summary><b>Cálculos numéricos con TensorFlow.js</b> (haz clic para mostrar)</summary>

[`@tensorflow/tfjs`](https://github.com/weareu/xlsx/blob/HEAD/@tensorflow/tfjs) y otras bibliotecas esperan datos en arrays
simples, muy adecuados para hojas de cálculo donde cada columna es un vector de datos.  Eso es
la transpuesta de cómo la mayoría de las personas usan las hojas de cálculo, donde cada fila es un vector.

Al recuperar datos de `tfjs`, los puntos de datos devueltos se almacenan en un array
tipado.  Se puede construir un array de arrays con bucles. `Array#unshift` puede
anteponer una fila de título antes de la conversión:```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 demostración array muestra un ejemplo completo.

Se pueden convertir varias tablas de una página web en hojas de cálculo individuales:```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 */

Alternativamente, el código HTML se puede extraer y analizar:```js var htmlstr = document.getElementById("tableau").outerHTML; var workbook = XLSX.read(htmlstr, {type:"string"});

</details>

<details>
  <summary><b>Extensión de Chrome/Chromium</b> (clic para mostrar)</summary>

La [demo de `chrome`](https://github.com/weareu/xlsx/blob/HEAD/demos/chrome/) muestra un ejemplo completo y detalla los
permisos requeridos y otras configuraciones.

En una extensión, se recomienda generar el libro de trabajo en un script de contenido
y pasar el objeto de vuelta a la extensión:```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 demo headless incluye una demo completa para convertir archivos HTML a libros de trabajo XLSB. La idea central es añadir el script a la página, analizar la tabla en el contexto de la página, generar un libro de trabajo en base64 y enviarlo de vuelta para su posterior procesamiento:```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>Tablas HTML del lado del servidor con WebKit sin interfaz gráfica</b> (clic para mostrar)</summary>

La [`demo` headless](https://github.com/weareu/xlsx/blob/HEAD/demos/headless/) incluye una demo completa para convertir
archivos HTML en libros de trabajo XLSB usando [PhantomJS](https://phantomjs.org/). La idea
principal es añadir el script a la página, analizar la tabla en el contexto de la página, generar
un libro de trabajo `binary` y enviarlo de vuelta para su posterior procesamiento:```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 no incluye una implementación del DOM y Puppeteer requiere una voluminosa compilación de Chromium. jsdom es una alternativa ligera:```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>

## Procesamiento de datos

El ["Formato Común de Hoja de Cálculo"](#common-spreadsheet-format) es una representación de objetos
simple de los conceptos centrales de un libro de trabajo.  Las funciones de utilidad trabajan
con la representación de objetos y están diseñadas para manejar casos de uso comunes.

### Modificación de la estructura del libro de trabajo

**API**

_Agregar una hoja de cálculo a un libro de trabajo_```js
XLSX.utils.book_append_sheet(workbook, worksheet, sheet_name);

La función de utilidad book_append_sheet añade una hoja de cálculo al libro de trabajo. El tercer argumento especifica el nombre deseado de la hoja de cálculo. Se pueden añadir varias hojas de cálculo a un libro de trabajo llamando a la función varias veces. Si el nombre de la hoja de cálculo ya se utiliza en el libro de trabajo, se lanzará un error.

Añade una hoja de cálculo a un libro de trabajo y encuentra un nombre único```js var new_name = XLSX.utils.book_append_sheet(workbook, worksheet, name, true);

Si el cuarto argumento es `true`, la función comenzará con el
nombre de la hoja de cálculo especificado.  Si el nombre de la hoja existe en el libro de trabajo, se elegirá un nuevo nombre de hoja de cálculo
encontrando la raíz del nombre e incrementando el contador:```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

Enumera los nombres de las hojas de cálculo en orden de pestañas```js var wsnames = workbook.SheetNames;

La propiedad `SheetNames` del objeto workbook es una lista de los nombres
de las hojas de cálculo en "orden de pestañas".  Las funciones de la API utilizarán esta matriz.

_Reemplazar una hoja de cálculo en su lugar_```js
workbook.Sheets[sheet_name] = new_worksheet;

La propiedad Sheets del objeto workbook es un objeto cuyas claves son nombres y cuyos valores son objetos de hoja de cálculo. Al reasignar una propiedad del objeto Sheets, el objeto de hoja de cálculo se puede cambiar sin alterar el resto de la estructura de la hoja de cálculo.

Ejemplos

</details>

### Modificación de valores de celda

**API**

_Modifica un valor de celda individual en una hoja de cálculo_```js
XLSX.utils.sheet_add_aoa(worksheet, [[new_value]], { origin: address });

La función de utilidad `sheet_add_aoa` modifica los valores de las celdas en una hoja de cálculo.  El
primer argumento es el objeto de la hoja de cálculo.  El segundo argumento es un array de
arrays de valores.  La clave `origin` del tercer argumento controla dónde se escribirán
las celdas.  El siguiente fragmento establece `B3=1` y `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" });

Opciones de análisis

Las funciones exportadas read y readFile aceptan un argumento de opciones:

• Incluso si cellNF es false, se generará texto formateado y se guardará en .w
• En algunos casos, las hojas pueden analizarse incluso si bookSheets es false.
• Excel intenta de forma agresiva interpretar valores de CSV y otros textos planos. ¡Esto puede provocar comportamientos sorprendentes! La opción raw suprime la interpretación de valores.
• bookSheets y bookProps se combinan para ofrecer ambos conjuntos de información
• Deps será un objeto vacío si bookDeps es false
• El comportamiento de bookFiles depende del tipo de archivo:
  • matriz keys (rutas en el ZIP) para formatos basados en ZIP
  • hash files (mapeo de rutas a objetos que representan los archivos) para ZIP
  • objeto cfb para formatos que usan contenedores CFB

Tipo de entrada

Las cadenas pueden interpretarse de varias maneras. El parámetro type de read le indica a la biblioteca cómo analizar el argumento de datos:

Adivinación del tipo de archivo

</details>

## Opciones de Escritura

Las funciones exportadas `write` y `writeFile` aceptan un argumento de opciones:

| Nombre de la opción |  Predeterminado | Descripción                                         |
| :---------- | -------: | :-------------------------------------------------- |
|`type`       |          | Codificación de datos de salida (ver Tipo de Salida más abajo)        |
|`cellDates`  |  `false` | Almacenar fechas como tipo `d` (predeterminado es `n`)            |
|`bookSST`    |  `false` | Generar Tabla de Cadenas Compartidas **                     |
|`bookType`   | `"xlsx"` | Tipo de Libro de Trabajo (ver formatos soportados más abajo)  |
|`sheet`      |     `""` | Nombre de la Hoja de Cálculo para formatos de una sola hoja **       |
|`compression`|  `false` | Usar compresión ZIP para formatos basados en ZIP **        |
|`Props`      |          | Sobrescribir las propiedades del libro de trabajo al escribir **        |
|`themeXLSX`  |          | Sobrescribir el XML del tema al escribir XLSX/XLSB/XLSM **   |
|`ignoreEC`   |   `true` | Suprimir errores de "número como texto" **                 |
|`numbers`    |          | Carga útil para exportación NUMBERS **                       |

- `bookSST` es más lento y consume más memoria, pero tiene mejor compatibilidad
  con versiones antiguas de iOS Numbers
- Los datos sin procesar son lo único que se garantiza que se guarde.  Las características no descritas
  en este README pueden no serializarse.
- `cellDates` solo se aplica a la salida XLSX y no se garantiza que funcione con
  lectores de terceros.  Excel normalmente no escribe celdas con tipo `d`
  por lo que las herramientas que no son de Excel pueden ignorar los datos o dar error en presencia de fechas.
- `Props` es un objeto que refleja el campo `Props` del libro de trabajo.  Consulte la tabla de
  la sección [Propiedades del archivo de libro de trabajo](#workbook-file-properties).
- si se especifica, la cadena de `themeXLSX` se guardará como el tema principal
  para los archivos XLSX/XLSB/XLSM (en `xl/theme/theme1.xml` dentro del ZIP)
- Debido a un error en el programa, algunas funciones como "Texto en columnas" harán que Excel se bloquee
  en hojas de cálculo donde se ignoran las condiciones de error.  El escritor marcará los archivos para
  ignorar el error de forma predeterminada.  Establezca `ignoreEC` en `false` para suprimirlo.
- Debido al tamaño de los datos, los datos NUMBERS no se incluyen de forma predeterminada.  Los
  scripts incluidos `xlsx.zahl.js` y `xlsx.zahl.mjs` incluyen los datos.

### Formatos de Salida Soportados

Para una amplia compatibilidad con herramientas de terceros, esta biblioteca admite muchos
formatos de salida.  El tipo de archivo específico se controla con la opción `bookType`:

| `bookType` | ext. de archivo | contenedor | hojas | Descripción                     |
| :--------- | -------: | :-------: | :----- |:------------------------------- |
| `xlsx`     | `.xlsx`  |    ZIP    | múltiple  | Formato XML de Excel 2007+          |
| `xlsm`     | `.xlsm`  |    ZIP    | múltiple  | Formato XML de macros de Excel 2007+    |
| `xlsb`     | `.xlsb`  |    ZIP    | múltiple  | Formato binario de Excel 2007+       |
| `biff8`    | `.xls`   |    CFB    | múltiple  | Formato de libro de Excel 97-2004   |
| `biff5`    | `.xls`   |    CFB    | múltiple  | Formato de libro de Excel 5.0/95    |
| `biff4`    | `.xls`   |   ninguno | única    | Formato de hoja de cálculo de Excel 4.0 |
| `biff3`    | `.xls`   |   ninguno | única    | Formato de hoja de cálculo de Excel 3.0 |
| `biff2`    | `.xls`   |   ninguno | única    | Formato de hoja de cálculo de Excel 2.0 |
| `xlml`     | `.xls`   |   ninguno | múltiple  | Excel 2003-2004 (SpreadsheetML) |
| `numbers`  |`.numbers`|    ZIP    | única    | Hoja de cálculo Numbers 3.0+        |
| `ods`      | `.ods`   |    ZIP    | múltiple  | Hoja de cálculo OpenDocument        |
| `fods`     | `.fods`  |   ninguno | múltiple  | Hoja de cálculo OpenDocument plana   |
| `wk3`      | `.wk3`   |   ninguno | múltiple  | Libro de trabajo Lotus (WK3)            |
| `csv`      | `.csv`   |   ninguno | única    | Valores separados por comas          |
| `txt`      | `.txt`   |   ninguno | única    | Texto Unicode UTF-16 (TXT)       |
| `sylk`     | `.sylk`  |   ninguno | única    | Enlace simbólico (SYLK)            |
| `html`     | `.html`  |   ninguno | única    | Documento HTML                   |
| `dif`      | `.dif`   |   ninguno | única    | Formato de intercambio de datos (DIF)   |
| `dbf`      | `.dbf`   |   ninguno | única    | dBASE II + extensiones VFP (DBF) |
| `wk1`      | `.wk1`   |   ninguno | única    | Hoja de cálculo Lotus (WK1)           |
| `rtf`      | `.rtf`   |   ninguno | única    | Formato de texto enriquecido (RTF)          |
| `prn`      | `.prn`   |   ninguno | única    | Texto formateado Lotus            |
| `eth`      | `.eth`   |   ninguno | única    | Formato de registro Ethercalc (ETH)   |

- `compression` solo se aplica a formatos con contenedores ZIP.
- Los formatos que solo admiten una sola hoja requieren una opción `sheet` que especifique
  la hoja de cálculo.  Si la cadena está vacía, se utiliza la primera hoja de cálculo.
- `writeFile` adivinará automáticamente el formato de archivo de salida basándose en la extensión
  del archivo si no se especifica `bookType`.  Elegirá el primer formato de
  la tabla mencionada que coincida con la extensión.

### Tipo de Salida

El argumento `type` para `write` refleja el argumento `type` para `read`:

| `type`     | salida                                                          |
|------------|-----------------------------------------------------------------|
| `"base64"` | string: codificación Base64 del archivo                         |
| `"binary"` | string: cadena binaria (el byte `n` es `data.charCodeAt(n)`)    |
| `"string"` | string: cadena JS (los caracteres se interpretan como UTF8)     |
| `"buffer"` | Buffer de nodejs                                                |
| `"array"`  | ArrayBuffer, matriz de respaldo de enteros sin signo de 8 bits  |
| `"file"`   | string: ruta del archivo que se creará (solo nodejs)            |

- Para compatibilidad con Excel, la salida `csv` siempre incluirá la marca de orden de bytes
  UTF-8.

## Funciones de Utilidad

Las funciones `sheet_to_*` aceptan una hoja de cálculo y un objeto de opciones opcional.

Las funciones `*_to_sheet` aceptan un objeto de datos y un objeto de opciones opcional.

---

[Read more](https://github.com/weareu/xlsx)

El valor especial de origen -1 indica a sheet_add_aoa que comience en la columna A de la fila siguiente a la última fila del rango, añadiendo los datos:```js XLSX.utils.sheet_add_aoa(worksheet, [ ["first row after data", 1], ["second row after data", 2] ], { origin: -1 });

</details>


### Modificación de otras propiedades de hoja de cálculo / libro de trabajo / celda

La sección ["Formato común de hoja de cálculo"](#common-spreadsheet-format) describe
las estructuras de los objetos con mayor detalle.

## Empaquetado y publicación de datos

### Escritura de libros de trabajo

**API**

_Generar bytes de hoja de cálculo (archivo) a partir de datos_```js
var data = XLSX.write(workbook, opts);

El método write intenta empaquetar los datos del libro de trabajo en un archivo en memoria. De forma predeterminada, se generan archivos XLSX, pero eso se puede controlar con la propiedad bookType del argumento opts. Según la opción type, los datos se pueden almacenar como una "cadena binaria", una cadena JS, Uint8Array o Buffer.

El segundo argumento opts es obligatorio. "Opciones de escritura" cubre las propiedades y comportamientos admitidos.

Generar e intentar guardar el archivo```js XLSX.writeFile(workbook, filename, opts);

El método `writeFile` empaqueta los datos e intenta guardar el nuevo archivo.  El
formato del archivo de exportación se determina por la extensión de `filename` (`SheetJS.xlsx`
indica exportación XLSX, `SheetJS.xlsb` indica exportación XLSB, etc).

El método `writeFile` utiliza APIs específicas de la plataforma para iniciar el guardado del archivo. En
NodeJS, `fs.readFileSync` puede crear un archivo.  En el navegador web, se intenta una descarga
usando el atributo `download` de HTML5, con alternativas para IE.

_Genera e intenta guardar un archivo XLSX_```js
XLSX.writeFileXLSX(workbook, filename, opts);

El método writeFile incorpora una serie de funciones de exportación diferentes. Esto es excelente para la experiencia del desarrollador, pero no es adecuado para tree shaking con las herramientas de desarrollo actuales. Cuando solo se necesitan exportaciones XLSX, este método evita hacer referencia a las otras funciones de exportación.

El segundo argumento opts es opcional. "Opciones de escritura" cubre las propiedades y comportamientos admitidos.

Ejemplos

Para Node ESM, el helper `writeFile` no está habilitado. En su lugar, se debe usar `fs.writeFileSync` para escribir los datos del archivo en un `Buffer` para usarlos con `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.  The
[`deno` demo](https://github.com/weareu/xlsx/blob/HEAD/demos/deno/) has more examples

</details>

<details>
  <summary><b>Local file in a PhotoShop or InDesign plugin</b> (click to show)</summary>

`writeFile` wraps the `File` logic in Photoshop and other ExtendScript targets.
The specified path should be an absolute path:```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>Descargar un archivo en navegadores antiguos</b> (haz clic para mostrar)</summary>

Las técnicas de `XLSX.writeFile` funcionan en la mayoría de los navegadores modernos, así como en versiones antiguas de IE.
Para navegadores mucho más antiguos, existen soluciones alternativas implementadas por librerías envolventes.

[`FileSaver.js`](https://github.com/eligrey/FileSaver.js/) implementa `saveAs`.
Nota: `XLSX.writeFile` llamará automáticamente a `saveAs` si está 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");

Nota: La sección ["Procesamiento de tablas HTML"](#processing-html-tables) muestra cómo
generar un libro de trabajo a partir de tablas HTML en una página en "Headless WebKit".

</details>



Las [demostraciones incluidas](https://github.com/weareu/xlsx/blob/HEAD/demos/) cubren aplicaciones móviles y otros despliegues especiales.

### Ejemplos de escritura

- <http://sheetjs.com/demos/table.html> exporta una tabla HTML
- <http://sheetjs.com/demos/writexlsx.html> genera un archivo simple

### Escritura en streaming

Las funciones de escritura en streaming están disponibles en el objeto `XLSX.stream`.  Toman
los mismos argumentos que las funciones de escritura normales, pero devuelven un flujo
legible de NodeJS.

- `XLSX.stream.to_csv` es la versión en streaming de `XLSX.utils.sheet_to_csv`.
- `XLSX.stream.to_html` es la versión en streaming de `XLSX.utils.sheet_to_html`.
- `XLSX.stream.to_json` es la versión en streaming de `XLSX.utils.sheet_to_json`.

<details>
  <summary><b>nodejs convertir a CSV y escribir archivo</b> (haz clic para mostrar)</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>Exportar archivos NUMBERS</b> (click para mostrar)</summary>

El escritor de NUMBERS requiere una base bastante grande. Los scripts complementarios `xlsx.zahl` proporcionan soporte. `xlsx.zahl.js` está diseñado para uso independiente y con NodeJS, mientras que `xlsx.zahl.mjs` es adecuado para ESM.

_Navegador_```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 canaliza flujos de escritura a la respuesta de nodejs.

Generando datos JSON y JS

Los datos JSON y JS suelen representar hojas de cálculo individuales. Las funciones de utilidad de esta sección trabajan con hojas de cálculo individuales.

La sección "Formato común de hoja de cálculo" describe la estructura del objeto con más detalle. workbook.SheetNames es una lista ordenada de los nombres de las hojas de cálculo. workbook.Sheets es un objeto cuyas claves son nombres de hojas y cuyos valores son objetos de hoja de cálculo.

La "primera hoja de cálculo" se almacena en workbook.Sheets[workbook.SheetNames[0]].

API

Crear un array de objetos JS a partir de una hoja de cálculo```js var jsa = XLSX.utils.sheet_to_json(worksheet, opts);

_Crea una matriz de matrices de valores JS a partir de una hoja de cálculo_```js
var aoa = XLSX.utils.sheet_to_json(worksheet, {...opts, header: 1});

La función de utilidad sheet_to_json recorre un libro de trabajo en orden por filas, generando un array de objetos. El segundo argumento opts controla una serie de decisiones de exportación, incluido el tipo de valores (valores JS o texto con formato). La sección "JSON" describe este argumento con más detalle.

Por defecto, sheet_to_json escanea la primera fila y utiliza los valores como encabezados. Con la opción header: 1, la función exporta un array de arrays de valores.

Ejemplos

x-spreadsheet es una cuadrícula de datos interactiva para previsualizar y modificar datos estructurados en el navegador web. La demo de xspreadsheet incluye un script de ejemplo con la función stox para convertir un libro de trabajo en un objeto de datos de x-spreadsheet. https://oss.sheetjs.com/sheetjs/x-spreadsheet es una demo en vivo.

/* 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>Vista previa de datos en una cuadrícula de datos de VueJS</b> (clic para mostrar)</summary>

[`vue3-table-lite`](https://github.com/linmasahiro/vue3-table-lite) es una tabla
de datos simple de VueJS 3.  Se presenta [en la demo de VueJS](https://github.com/weareu/xlsx/blob/HEAD/demos/vue/modify/).

</details>

<details>
  <summary><b>Poblar una base de datos (SQL o no-SQL)</b> (clic para mostrar)</summary>

La [demo de `database`](https://github.com/weareu/xlsx/blob/HEAD/demos/database/) incluye ejemplos de trabajo con
bases de datos y resultados de consultas.

</details>

<details>
  <summary><b>Cálculos numéricos con TensorFlow.js</b> (clic para mostrar)</summary>

[`@tensorflow/tfjs`](https://github.com/weareu/xlsx/blob/HEAD/@tensorflow/tfjs) y otras bibliotecas esperan datos en
arreglos simples, adecuados para hojas de cálculo donde cada columna es un
vector de datos.  Esa es la transposición de cómo la mayoría de las personas usan las hojas de cálculo, donde cada fila es un vector.

Un solo `Array#map` puede extraer filas individuales con nombre de la exportación de `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 [demo `react`](https://github.com/weareu/xlsx/blob/HEAD/demos/react) incluye más ejemplos de React.

</details>

<details>
  <summary><b>Cuaderno de trabajo de fetch de VueJS y generar vistas previas de tablas HTML</b> (clic para mostrar)</summary>

Generalmente se recomienda utilizar un flujo de trabajo compatible con VueJS, pero es posible
generar HTML y usarlo en VueJS con la directiva `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>`
};

Generación de instantáneas de una sola hoja de cálculo

Las funciones sheet_to_* aceptan un objeto de hoja de cálculo.

API

Generar un CSV a partir de una sola hoja de cálculo```js var csv = XLSX.utils.sheet_to_csv(worksheet, opts);

Esta instantánea está diseñada para replicar el tipo de salida "CSV UTF8 (`.csv`)".
["Salida separada por delimitadores"](#delimiter-separated-output) describe la
función y el argumento opcional `opts` con más detalle.

_Generar "Texto" desde una sola hoja de cálculo_```js
var txt = XLSX.utils.sheet_to_txt(worksheet, opts);

This snapshot is designed to replicate the "UTF16 Text (.txt)" output type. "Salida separada por delimitadores" describe la función y el argumento opcional opts con más detalle.

Generar una lista de fórmulas a partir de una sola hoja de cálculo```js var fmla = XLSX.utils.sheet_to_formulae(worksheet);

Esta instantánea genera una matriz de entradas que representan las fórmulas incrustadas.
Las fórmulas de matriz se representan en la forma `range=formula`, mientras que las celdas normales se
representan en la forma `cell=formula or value`. Los literales de cadena llevan el prefijo
de un apóstrofo `'`, de acuerdo con la visualización de la barra de fórmulas de Excel.

La sección ["Salida de fórmulas"](#formulae-output) describe la función con más detalle.

## Interfaz

`XLSX` es la variable expuesta en el navegador y la variable de node exportada

`XLSX.version` es la versión de la biblioteca (añadida por el script de compilación).

`XLSX.SSF` es una versión integrada de la [librería de formatos](https://git.io/ssf).

### Funciones de análisis

`XLSX.read(data, read_opts)` intenta analizar `data`.

`XLSX.readFile(filename, read_opts)` intenta leer `filename` y analizarla.

Las opciones de análisis se describen en la sección [Opciones de análisis](#parsing-options).

### Funciones de escritura

`XLSX.write(wb, write_opts)` intenta escribir el libro de trabajo `wb`

`XLSX.writeFile(wb, filename, write_opts)` intenta escribir `wb` en `filename`.
En entornos basados en navegador, intentará forzar una descarga del lado del cliente.

`XLSX.writeFileAsync(wb, filename, o, cb)` intenta escribir `wb` en `filename`.
Si se omite `o`, el escritor utilizará el tercer argumento como devolución de llamada.

`XLSX.stream` contiene un conjunto de funciones de escritura en streaming.

Las opciones de escritura se describen en la sección [Opciones de escritura](#writing-options).

### Utilidades

Las utilidades están disponibles en el objeto `XLSX.utils` y se describen en la
sección [Funciones de utilidad](#utility-functions):

**Construcción:**

- `book_new` crea un libro de trabajo vacío
- `book_append_sheet` añade una hoja de cálculo a un libro de trabajo

**Importación:**

- `aoa_to_sheet` convierte una matriz de matrices de datos JS en una hoja de cálculo.
- `json_to_sheet` convierte una matriz de objetos JS en una hoja de cálculo.
- `table_to_sheet` convierte un elemento DOM TABLE en una hoja de cálculo.
- `sheet_add_aoa` añade una matriz de matrices de datos JS a una hoja de cálculo existente.
- `sheet_add_json` añade una matriz de objetos JS a una hoja de cálculo existente.


**Exportación:**

- `sheet_to_json` convierte un objeto de hoja de cálculo en una matriz de objetos JSON.
- `sheet_to_csv` genera una salida de valores separados por delimitadores.
- `sheet_to_txt` genera texto con formato UTF16.
- `sheet_to_html` genera una salida HTML.
- `sheet_to_formulae` genera una lista de las fórmulas (con valores de respaldo).


**Manipulación de celdas y direcciones de celda:**

- `format_cell` genera el valor de texto para una celda (usando formatos de número).
- `encode_row / decode_row` convierte entre filas indexadas desde 0 y filas indexadas desde 1.
- `encode_col / decode_col` convierte entre columnas indexadas desde 0 y nombres de columnas.
- `encode_cell / decode_cell` convierte direcciones de celda.
- `encode_range / decode_range` convierte rangos de celdas.

## Formato Común de Hoja de Cálculo

SheetJS se ajusta al Formato Común de Hoja de Cálculo (CSF):

### Estructuras generales

Los objetos de dirección de celda se almacenan como `{c:C, r:R}` donde `C` y `R` son números de
columna y fila indexados desde 0, respectivamente. Por ejemplo, la dirección de celda `B5` se
representa mediante el objeto `{c:1, r:4}`.

Los objetos de rango de celdas se almacenan como `{s:S, e:E}` donde `S` es la primera celda y
`E` es la última celda del rango. Los rangos son inclusivos. Por ejemplo, el
rango `A3:B7` se representa mediante el objeto `{s:{c:0, r:2}, e:{c:1, r:6}}`.
Las funciones de utilidad realizan un recorrido del rango de una hoja en orden de fila principal:```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

Los objetos Cell son objetos JS simples con claves y valores que siguen la convención:

Las utilidades de exportación integradas (como el exportador CSV) usarán el texto w si está disponible. Para cambiar un valor, asegúrese de eliminar cell.w (o establézcalo en undefined) antes de intentar exportar. Las utilidades regenerarán el texto w a partir del formato numérico (cell.z) y del valor bruto si es posible.

La fórmula matricial real se almacena en el campo f de la primera celda del rango de la matriz. Las demás celdas del rango omitirán el campo f.

Tipos de datos

El valor bruto se almacena en la propiedad de valor v, interpretado según la propiedad de tipo t. Esta separación permite representar números así como texto numérico. Hay 6 tipos de celda válidos:

El tipo n es el tipo Número. Esto incluye todas las formas de datos que Excel almacena como números, como fechas/horas y campos booleanos. Excel utiliza exclusivamente datos que caben en un número de punto flotante IEEE754, igual que el tipo Number de JS, por lo que el campo v contiene el número bruto. El campo w contiene el texto formateado. Las fechas se almacenan como números de forma predeterminada y se convierten con XLSX.SSF.parse_date_code.

El tipo d es el tipo Fecha, generado solo cuando se pasa la opción cellDates. Dado que JSON no tiene un tipo Fecha natural, generalmente se espera que los analizadores almacenen cadenas de fecha ISO 8601 como las que obtendría de date.toISOString(). Por otro lado, los escritores y exportadores deberían poder manejar cadenas de fecha y objetos Date de JS. Tenga en cuenta que Excel ignora los modificadores de zona horaria y trata todas las fechas en la zona horaria local. La biblioteca no corrige este error.

El tipo s es el tipo Cadena. Los valores se almacenan explícitamente como texto. Excel interpretará estas celdas como "número almacenado como texto". Los archivos Excel generados suprimen automáticamente esa clase de error, pero otros formatos pueden provocar errores.

El tipo z representa celdas stub en blanco. Se generan en casos donde las celdas no tienen un valor asignado pero contienen comentarios u otros metadatos. Son ignoradas por las funciones de utilidad de procesamiento de datos de la biblioteca principal. De forma predeterminada, estas celdas no se generan; la opción sheetStubs del analizador debe establecerse en true.

Fechas

</details>

### Objetos de hoja

Cada clave que no comienza con `!` se asigna a una celda (usando notación `A-1`)

`sheet[address]` devuelve el objeto de celda para la dirección especificada.

**Claves especiales de hoja (accesibles como `sheet[key]`, cada una comenzando con `!`):**

- `sheet['!ref']`: rango basado en A-1 que representa el rango de la hoja. Las funciones que
  trabajan con hojas deben usar este parámetro para determinar el rango.  Las celdas que
  se asignan fuera del rango no se procesan.  En particular, cuando
  se escribe una hoja manualmente, las celdas fuera del rango no se incluyen

  Las funciones que manejan hojas deben verificar la presencia del campo `!ref`.
  Si se omite `!ref` o no es un rango válido, las funciones pueden tratar
  la hoja como vacía o intentar adivinar el rango.  Las utilidades estándar que
  se incluyen con esta librería tratan las hojas como vacías (por ejemplo, la salida CSV es
  una cadena vacía).

  Al leer una hoja de trabajo con la propiedad `sheetRows` establecida, el parámetro ref
  usará el rango restringido.  El rango original se establece en `ws['!fullref']`

- `sheet['!margins']`: Objeto que representa los márgenes de página.  Los valores predeterminados
  siguen el ajuste preestablecido "normal" de Excel.  Excel también tiene ajustes "wide" y "narrow"
  pero se almacenan como medidas en bruto. Las propiedades principales se enumeran a continuación:

<details>
  <summary><b>Detalles de los márgenes de página</b> (clic para mostrar)</summary>

| clave    | descripción            | "normal" | "wide" | "narrow" |
|----------|------------------------|:---------|:-------|:-------- |
| `left`   | margen izquierdo (pulgadas)   | `0.7`    | `1.0`  | `0.25`   |
| `right`  | margen derecho (pulgadas)  | `0.7`    | `1.0`  | `0.25`   |
| `top`    | margen superior (pulgadas)    | `0.75`   | `1.0`  | `0.75`   |
| `bottom` | margen inferior (pulgadas) | `0.75`   | `1.0`  | `0.75`   |
| `header` | margen de encabezado (pulgadas) | `0.3`    | `0.5`  | `0.3`    |
| `footer` | margen de pie de página (pulgadas) | `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}

Objeto de hoja de cálculo

Además de las claves base de la hoja, las hojas de cálculo también añaden:

• ws['!cols']: array de objetos de propiedades de columnas. Los anchos de columna se almacenan realmente en los archivos de forma normalizada, medidos en términos del "ancho máximo de dígitos" (el mayor ancho de los dígitos representados 0-9, en píxeles). Al analizarse, los objetos de columna almacenan el ancho en píxeles en el campo wpx, el ancho en caracteres en el campo wch y el ancho máximo de dígitos en el campo MDW.

• ws['!rows']: array de objetos de propiedades de filas, como se explica más adelante en la documentación. Cada objeto de fila codifica propiedades que incluyen la altura de la fila y la visibilidad.

• ws['!merges']: array de objetos de rango correspondientes a las celdas combinadas en la hoja de cálculo. Los formatos de texto plano no admiten celdas combinadas. La exportación CSV escribirá todas las celdas del rango combinado si existen, así que asegúrese de que solo esté establecida la primera celda (superior izquierda) del rango.

• ws['!outline']: configura cómo deben comportarse los esquemas. Las opciones tienen como valores predeterminados los ajustes predeterminados de Excel 2019:

• ws['!protect']: objeto de propiedades de protección de la hoja para la escritura. La clave password especifica la contraseña para los formatos que admiten hojas protegidas con contraseña (XLSX/XLSB/XLS). El escritor utiliza el método de ofuscación XOR. Las siguientes claves controlan la protección de la hoja -- establezca en false para habilitar una característica cuando la hoja esté bloqueada o en true para deshabilitarla:

• ws['!autofilter']: objeto AutoFilter que sigue el esquema:```typescript type AutoFilter = { ref:string; // A-1 based range representing the AutoFilter table range }

#### Objeto Chartsheet

Los Chartsheets se representan como hojas estándar. Se distinguen con la
propiedad `!type` establecida en `"chart"`.

Los datos subyacentes y `!ref` se refieren a los datos en caché en el chartsheet. La
primera fila del chartsheet es el encabezado subyacente.

#### Objeto Macrosheet

Los Macrosheets se representan como hojas estándar. Se distinguen con la
propiedad `!type` establecida en `"macro"`.

#### Objeto Dialogsheet

Los Dialogsheets se representan como hojas estándar. Se distinguen con la
propiedad `!type` establecida en `"dialog"`.

### Objeto Workbook

`workbook.SheetNames` es una lista ordenada de las hojas en el libro de trabajo

`wb.Sheets[sheetname]` devuelve un objeto que representa la hoja de cálculo.

`wb.Props` es un objeto que almacena las propiedades estándar. `wb.Custprops` almacena
propiedades personalizadas. Dado que las propiedades estándar de XLS difieren del estándar
XLSX, el análisis de XLS almacena las propiedades principales en ambos lugares.

`wb.Workbook` almacena [atributos a nivel de libro de trabajo](#atributos-a-nivel-de-libro-de-trabajo).

#### Propiedades de archivo del Workbook

Los distintos formatos de archivo utilizan nombres internos diferentes para las propiedades de archivo. El
objeto `Props` del workbook normaliza los nombres:

<details>
  <summary><b>Propiedades de archivo</b> (clic para mostrar)</summary>

| Nombre JS     | Descripción en Excel           |
|:--------------|:-------------------------------|
| `Title`       | Pestaña Resumen "Título"       |
| `Subject`     | Pestaña Resumen "Asunto"       |
| `Author`      | Pestaña Resumen "Autor"        |
| `Manager`     | Pestaña Resumen "Administrador"|
| `Company`     | Pestaña Resumen "Empresa"      |
| `Category`    | Pestaña Resumen "Categoría"    |
| `Keywords`    | Pestaña Resumen "Palabras clave"|
| `Comments`    | Pestaña Resumen "Comentarios"  |
| `LastAuthor`  | Pestaña Estadísticas "Guardado por última vez por"|
| `CreatedDate` | Pestaña Estadísticas "Creado"  |

</details>

Por ejemplo, para establecer la propiedad de título del workbook:```js
if(!wb.Props) wb.Props = {};
wb.Props.Title = "Insert Title Here";

Las propiedades personalizadas se agregan en el objeto Custprops del libro de trabajo:```js if(!wb.Custprops) wb.Custprops = {}; wb.Custprops["Custom Property"] = "Custom Value";

Los escritores procesarán la clave `Props` del objeto de opciones:```js
/* force the Author to be "SheetJS" */
XLSX.write(wb, {Props:{Author:"SheetJS"}});

Atributos a Nivel de Libro

wb.Workbook almacena atributos a nivel de libro.

Nombres Definidos

wb.Workbook.Names es un array de objetos de nombres definidos que tienen las claves:

Excel permite que dos nombres definidos con ámbito de hoja compartan el mismo nombre. Sin embargo, un nombre con ámbito de hoja no puede colisionar con un nombre de ámbito de libro. Los escritores de libros pueden no hacer cumplir esta restricción.

Vistas de Libro

wb.Workbook.Views es un array de objetos de vista de libro que tienen las claves:

Propiedades Diversas del Libro

wb.Workbook.WBProps contiene otras propiedades del libro:

Características del Documento

Incluso para características básicas como el almacenamiento de fechas, los formatos oficiales de Excel almacenan el mismo contenido de diferentes maneras. Se espera que los analizadores conviertan desde la representación del formato de archivo subyacente al Formato Común de Hoja de Cálculo. Se espera que los escritores conviertan de CSF de vuelta al formato de archivo subyacente.

Fórmulas

La cadena de fórmula de estilo A1 se almacena en el campo f. Aunque diferentes formatos de archivo almacenan las fórmulas de diferentes maneras, los formatos se traducen. Aunque algunos formatos almacenan las fórmulas con un signo igual inicial, las fórmulas CSF no comienzan con =.

Fórmulas de una sola celda

Para fórmulas simples, la clave f de la celda deseada puede establecerse con el texto de fórmula real. Esta hoja de cálculo representa A1=1, A2=2 y 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' } };

Utilidades como `aoa_to_sheet` aceptarán objetos de celda en lugar de valores:```js
var worksheet = XLSX.utils.aoa_to_sheet([
  [ 1 ], // A1
  [ 2 ], // A2
  [ {t: "n", v: 3, f: "A1+A2"} ] // A3
]);

Las celdas con entradas de fórmula pero sin valor se serializarán de una manera que Excel y otras herramientas de hojas de cálculo reconocerán. Esta biblioteca no calculará automáticamente los resultados de las fórmulas! Por ejemplo, la siguiente hoja de cálculo incluirá la función BESSELJ, pero el resultado no estará 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 se necesitan los resultados reales en JS, [SheetJS Pro](https://sheetjs.com/pro)
ofrece un componente de calculadora de fórmulas para evaluar expresiones, actualizar
valores y celdas dependientes, y refrescar libros de trabajo completos.

**Fórmulas de matriz**

_Asignar una fórmula de matriz_```js
XLSX.utils.sheet_set_array_formula(worksheet, range, formula);

Las fórmulas de matriz se almacenan en la celda superior izquierda del bloque de matriz. Todas las celdas de una fórmula de matriz tienen un campo F correspondiente al rango. Una fórmula de celda única se puede distinguir de una fórmula normal por la presencia del campo F.

Por ejemplo, al establecer la celda C1 con la fórmula de matriz {=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" };

Para una fórmula de matriz de varias celdas, cada celda tiene el mismo rango de matriz pero solo la
primera celda especifica la fórmula.  Considera `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" };

Se espera que las utilidades y los escritores comprueben la presencia de un campo F e ignoren cualquier posible elemento de fórmula f en celdas distintas de la celda inicial. ¡No se espera que realicen la validación de las fórmulas!

Fórmulas de matriz dinámica

Asignar una fórmula de matriz dinámica```js XLSX.utils.sheet_set_array_formula(worksheet, range, formula, true);

Publicadas en 2020, las fórmulas de matriz dinámica son compatibles con los formatos de archivo XLSX/XLSM y XLSB. Se representan como fórmulas de matriz normales pero tienen metadatos de celda especiales que indican que se debe permitir que la fórmula ajuste el rango.

Una fórmula de matriz se puede marcar como dinámica estableciendo la propiedad `D` de la celda en `true`. Se espera el rango `F`, pero se puede establecer a la celda actual:```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

Localización con nombres de funciones

SheetJS opera a nivel de archivo. Excel almacena las expresiones de fórmula utilizando los nombres de funciones en inglés (Estados Unidos). Para usuarios que no hablan inglés, Excel utiliza un conjunto localizado de nombres de funciones.

Por ejemplo, cuando el idioma y la región del equipo están configurados en francés (Francia), Excel interpreta =SOMME(A1:C3) como si SOMME fuera la función SUM. Sin embargo, en el archivo real, Excel almacena SUM(A1:C3).

Funciones "futuras" con prefijo

Las funciones introducidas en versiones más recientes de Excel llevan el prefijo _xlfn. cuando se almacenan en archivos. Al escribir expresiones de fórmula que utilizan estas funciones, el prefijo es necesario para una compatibilidad máxima:```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);

Al leer un archivo, la opción `xlfn` conserva los prefijos.

<details>
  <summary><b> Funciones que requieren el prefijo `_xlfn.`</b> (haz clic para mostrar)</summary>

Esta lista crece con cada versión de 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

Propiedades de filas: XLSX/M, XLSB, BIFF8 XLS, XLML, SYLK, DOM, ODS

Propiedades de columnas: XLSX/M, XLSB, BIFF8 XLS, XLML, SYLK, DOM

Hay tres tipos de anchura diferentes que corresponden a las tres formas distintas en que las hojas de cálculo almacenan los anchos de columna:

SYLK y otros formatos de texto plano usan el recuento bruto de caracteres. Las herramientas contemporáneas como Visicalc y Multiplan se basaban en caracteres. Como los caracteres tenían el mismo ancho, bastaba con almacenar un recuento. Esta tradición se continuó en los formatos BIFF.

SpreadsheetML (2003) intentó alinearse con HTML estandarizando el recuento de píxeles de pantalla en todo el archivo. Los anchos de columna, las alturas de fila y otras medidas usan píxeles. Cuando el recuento de píxeles y de caracteres no coincide, Excel redondea los valores.

XLSX almacena internamente los anchos de columna en una nebulosa forma de "Max Digit Width". El Max Digit Width es el ancho del dígito más grande al renderizarse (generalmente el carácter "0" es el más ancho). La anchura interna debe ser un múltiplo entero de la anchura dividida entre 256. ECMA-376 describe una fórmula para convertir entre píxeles y la anchura interna. Esto representa un enfoque híbrido.

Las funciones de lectura intentan rellenar las tres propiedades. Las funciones de escritura intentarán convertir los valores especificados al tipo deseado. Para evitar posibles conflictos, la manipulación debe eliminar primero las otras propiedades. Por ejemplo, al cambiar la anchura en píxeles, elimine las propiedades wch y width.

Alturas de fila

Excel almacena internamente las alturas de fila en puntos. La resolución predeterminada es 72 DPI o 96 PPI, por lo que los tamaños en píxeles y en puntos deberían coincidir. Para resoluciones diferentes pueden no coincidir, por lo que la biblioteca separa los conceptos.

Aunque toda la información está disponible, se espera que las funciones de escritura sigan el orden de prioridad:

1. usar la altura en píxeles hpx si está disponible
2. usar la altura en puntos hpt si está disponible

Anchos de columna

Dadas las restricciones, es posible determinar el MDW sin inspeccionar realmente la fuente! Los analizadores adivinan la anchura en píxeles convirtiendo la anchura a píxeles y viceversa, repitiendo para todos los MDW posibles y seleccionando el MDW que minimiza el error. XLML en realidad almacena la anchura en píxeles, por lo que la suposición funciona en la dirección opuesta.

Aunque toda la información está disponible, se espera que las funciones de escritura sigan el orden de prioridad:

1. usar el campo width si está disponible
2. usar la anchura en píxeles wpx si está disponible
3. usar el recuento de caracteres wch si está disponible

Los formatos predeterminados se enumeran en ECMA-376 18.8.30:

Hipervínculos de celda: XLSX/M, XLSB, BIFF8 XLS, XLML, ODS

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