nginstack

Class: XLSXWriter

@nginstack/engine/lib/xlsx/XLSXWriter~ XLSXWriter

new XLSXWriter()

XLSXWriter é uma classe que permite escrever arquivos no formato XLSX (Excel).

Antes de iniciar a escrita, uma planilha deve ser adicionada utilizando o método addWorksheet. A seguir, as células devem ser escritas uma por vez utilizando os métodos de escrita, que recebem linha, coluna, valor e opcionalmente uma formatação para a célula. As células são sempre escritas na última planilha adicionada.

Cada método de escrita possui uma formatação pré-definida que pode ser sobrescrita pelo parâmetro de formatação. Este parâmetro pode ser um objeto passado diretamente no método de escrita, ou preferencialmente apenas o nome de uma formatação definida previamente. Para definir uma formatação, utilize o método addFormat passando o nome da formatação e um objeto com as opções desejadas.

A escrita deve ocorrer sequencialmente, pois apenas uma linha é mantida por vez em memória. Uma vez que uma célula é escrita em uma linha, não é possível escrever outra célula em uma linha anterior daquela planilha. De mesmo modo, uma vez que uma nova planilha é adicionada, não é possível acessar planilhas anteriores.

Finalizada a escrita, o método saveToFile deve ser utilizado passando o nome do arquivo destino para gerar o arquivo XLSX.

Example
const XLSXWriter = require('@nginstack/engine/lib/xlsx/XLSXWriter.js');

// Criando uma instância do XLSXWriter
const writer = new XLSXWriter();

// Definindo formatos personalizados
writer.addFormat('header', { bold: true, fontSize: 12 });
writer.addFormat('date', { numericFormat: 'dd/mm' });

// Adicionando uma planilha
writer.addWorksheet('Datas Comemorativas 2025');

// Escrevendo a primeira linha com cabeçalhos
writer.writeString(0, 0, 'Nome', 'header');
writer.writeString(0, 1, 'Data', 'header');

// Escrevendo dados na planilha
writer.writeString(1, 0, 'Natal');
writer.writeDate(1, 1, '2025-12-25', 'date');
writer.writeString(2, 0, 'Carnaval');
writer.writeDate(2, 1, '2025-03-04', 'date');

// Salvando o arquivo XLSX
writer.saveToFile('datas_comemorativas_2025.xlsx');

Methods

addFormat(name, format)

Define uma formatação personalizada que pode ser utilizada ao escrever células.

Preferencialmente, para uma melhor performance durante a escrita, utilize este método para definir as formatações previamente, e informe apenas o nome como parâmetro de formatação nos métodos de escrita.

Parameters:
Name Type Description
name string

Nome da formatação. Este nome é utilizado para referenciar a formatação ao escrever células.
format FormatOptions

Objeto contendo as opções de formatação.

addWorksheet( [name])

Adiciona uma planilha ao arquivo XLSX. Para escrever células, é necessário que pelo menos uma planilha tenha sido adicionada.

A escrita é feita sequencialmente, portanto os dados são sempre escritos na última planilha adicionada, e não é possível acessar e escrever em planilhas anteriores após adicionar uma nova planilha.

Parameters:
Name Type Argument Description
name string <optional>

Nome opcional da planilha a ser adicionada. Caso não seja informado, a planilha receberá um nome padrão como "Sheet1", "Sheet2", etc.

saveToFile(filename)

Salva o arquivo XLSX no caminho especificado. O arquivo será criado ou sobrescrito se já existir.

Parameters:
Name Type Description
filename string

Caminho do arquivo onde o XLSX será salvo.

setColumnWidth(col, width)

Define a largura de uma coluna na planilha atual.

Colunas que não passam por este método têm sua largura definida por uma heurística que leva em consideração o número de caracteres dos valores escritos, o tipo do dado e a formatação aplicada.

Pode ser necessário definir a largura de colunas que abrigam fórmulas, que tenham o tamanho da fonte alterado ou cuja formatação numérica seja muito diferente do padrão definido para o tipo de dado.

Parameters:
Name Type Description
col number

Coluna que terá a largura definida (0-indexed).
width number

Largura da coluna em unidades de caractere. Uma unidade equivale à largura de um caractere na fonte padrão do Excel (Calibri 11).

writeBoolean(row, col, value [, format])

Escreve um valor booleano em uma célula da planilha atual.

Parameters:
Name Type Argument Description
row number

Número da linha onde o valor booleano será escrito (0-indexed).
col number

Número da coluna onde o valor booleano será escrito (0-indexed).
value boolean

O valor booleano a ser escrito na célula.
format string | FormatOptions <optional>

Nome da formatação definida previamente ou um objeto contendo as opções de formatação. Se não for informado, o booleano será escrito sem formatação.

writeDate(row, col, value [, format])

Escreve uma data em uma célula da planilha atual.

Parameters:
Name Type Argument Description
row number

Número da linha onde a data será escrita (0-indexed).
col number

Número da coluna onde a data será escrita (0-indexed).
value Date | number | string

O valor da data a ser escrita na célula. Pode ser um objeto Date, um timestamp, ou uma string no formato "yyyy-mm-dd" ou "yyyy-mm-dd hh:mm:ss".
format string | FormatOptions <optional>

Nome da formatação definida previamente ou um objeto contendo as opções de formatação. Se não for informado, será utilizada a formatação numérica "dd/mm/yyy".

writeFormula(row, col, formula [, format])

Escreve uma fórmula em uma célula da planilha atual.

Parameters:
Name Type Argument Description
row number

Número da linha onde a fórmula será escrita (0-indexed).
col number

Número da coluna onde a fórmula será escrita (0-indexed).
formula string

A fórmula a ser escrita na célula (ex: "=SUM(A1:A10)").
format string | FormatOptions <optional>

Nome da formatação definida previamente ou um objeto contendo as opções de formatação. Se não for informado, o resultado da fórmula será exibido sem formatação.

writeInteger(row, col, value [, format])

Escreve um inteiro em uma célula da planilha atual.

Parameters:
Name Type Argument Description
row number

Número da linha onde o inteiro será escrito (0-indexed).
col number

Número da coluna onde o inteiro será escrito (0-indexed).
value number

O valor inteiro a ser escrito na célula.
format string | FormatOptions <optional>

Nome da formatação definida previamente ou um objeto contendo as opções de formatação. Se não for informado, será utilizada a formatação numérica "0", que indica um número sem casas decimais e sem separador de milhar.

writeNumber(row, col, value [, format])

Escreve um número em uma célula da planilha atual.

Parameters:
Name Type Argument Description
row number

Número da linha onde o número será escrito (0-indexed).
col number

Número da coluna onde o número será escrito (0-indexed).
value number

O valor numérico a ser escrito na célula.
format string | FormatOptions <optional>

Nome da formatação definida previamente ou um objeto contendo as opções de formatação. Se não for informado, será utilizada a formatação numérica "0.00", que indica um número com duas casas decimais e sem separador de milhar.

writeString(row, col, str [, format])

Escreve uma string em uma célula da planilha atual.

Parameters:
Name Type Argument Description
row number

Número da linha onde a string será escrita (0-indexed).
col number

Número da coluna onde a string será escrita (0-indexed).
str string

O valor da string a ser escrita na célula.
format string | FormatOptions <optional>

Nome da formatação definida previamente ou um objeto contendo as opções de formatação. Se não for informado, será utilizada a formatação numérica "@", que indica o formato padrão para textos.

writeTime(row, col, value [, format])

Escreve um horário em uma célula da planilha atual.

Parameters:
Name Type Argument Description
row number

Número da linha onde o horário será escrito (0-indexed).
col number

Número da coluna onde o horário será escrito (0-indexed).
value string

O valor do horário a ser escrito na célula. Deve ser uma string no formato "hh:mm", "hh:mm:ss" ou "hh:mm:ss.sss".
format string | FormatOptions <optional>

Nome da formatação definida previamente ou um objeto contendo as opções de formatação. Se não for informado, será utilizada a formatação numérica "hh:mm:ss".

writeURL(row, col, url [, format])

Escreve uma URL em uma célula da planilha atual.

Parameters:
Name Type Argument Description
row number

Número da linha onde a URL será escrita (0-indexed).
col number

Número da coluna onde a URL será escrita (0-indexed).
url string

O valor da URL a ser escrita na célula.
format string | FormatOptions <optional>

Nome da formatação definida previamente ou um objeto contendo as opções de formatação. Se não for informado, a URL será escrita sem formatação.