Referencia API

Aquí tienes el contrato completo de spreadsheet: todo lo que puedes enlazar, escuchar, proyectar y personalizar, reunido en un solo sitio. Enlaza lo que necesites y dale el estilo que quieras — es standalone y reactivo con signals.

Inputs

Ajusta spreadsheet a tu gusto con 31 inputs. Se enlazan como cualquier @Input de Angular.

Nombre	Tipo	Por defecto	Descripción
`rows`Obligatorio	`readonly TRow[]`	—	Las filas, tal como las tienes. La hoja nunca escribe en ellas.
`columns`Obligatorio	`readonly HubSpreadsheetColumn<TRow>[]`	—	Qué muestra y qué permite cada columna.
`rowKey`Obligatorio	`(row: TRow) => string`	—	Un nombre estable por fila, para que el estado de guardado la siga tras una recarga.
`errors`	`Record<string, string>`	`{}`	Un mensaje de validación por celda, con la misma clave que `states`. Lo tiene quien usa la hoja, porque validar es de quien sabe qué significan los datos.
`states`	`Record<string, HubSpreadsheetCellState>`	`{}`	Estado de guardado por celda, con la clave de la fila y el alias de la columna unidos por un tabulador.
`decimalMark`	`',' \| '.'`	`','`	Con qué carácter escribe los decimales este lector. Solo se consulta cuando lo pegado no traía número crudo.
`emptyText`	`string`	`''`	Qué dice una hoja vacía.
`pageSize`	`number`	`10`	Cuántas filas recorren Re Pág y Av Pág.
`readonly`	`boolean`	`false`	Desactiva todos los editores, digan lo que digan las celdas.
`frozenColumns`	`number`	`0`	Cuántas columnas quedan fijadas al margen inicial, contadas como congela paneles Excel.
`frozenRows`	`number`	`0`	Cuántas filas quedan fijadas bajo la cabecera.
`spans`	`readonly HubGridSpan[]`	`[]`	Bloques combinados, cada uno con su esquina superior izquierda y su extensión.
`fillHandle`	`boolean`	`false`	Si la hoja ofrece el tirador de relleno en la esquina de la selección.
`canUndo`	`boolean`	`false`	Si se puede deshacer. La hoja solo pregunta; el histórico lo tiene quien la usa.
`canRedo`	`boolean`	`false`	Si se puede rehacer.
`resizableColumns`	`boolean`	`false`	Si el lector puede arrastrar el borde de una columna para ensancharla o estrecharla.
`reorderableColumns`	`boolean`	`false`	Si el lector puede arrastrar una cabecera para llevarse la columna a otro sitio.
`columnWidths`	`Record<string, number>`	`{}`	El ancho de cada columna en píxeles, con el alias por clave. De dos sentidos: la hoja lo escribe al arrastrar y tú puedes guardarlo.
`minColumnWidth`	`number`	`48`	Lo más estrecha que se puede dejar una columna.
`virtual`	`boolean`	`false`	Dibuja solo las filas que cubre la ventana y reserva la altura del resto, para una hoja de miles. Apagado por omisión, y tiene coste: las filas fuera de la vista no están en el documento, así que la búsqueda del navegador y la impresión solo alcanzan lo dibujado, y las filas tienen que medir lo mismo. Activarlo además le da a la hoja una altura de 24rem, porque una hoja que se deja crecer mide lo que su contenido y entonces no hay nada que virtualizar.
`rowHeight`	`number`	`0`	Cuánto mide una fila al virtualizar, en píxeles. Cero mide la primera fila dibujada, que es lo correcto cuando son iguales. Decláralo si la hoja se construye oculta: una fila que nunca se ha maquetado mide cero, y una ventana calculada desde cero es la hoja entera.
`formulas`	`boolean`	`false`	Si una celda cuyo valor empieza por = es una fórmula. Apagado salvo que se pida: una columna de texto puede llevar perfectamente =1+1 como lo que alguien escribió. Una fórmula puede nombrar una columna por su alias —=[units] * [price], =SUM([total:])—, que sigue queriendo decir lo mismo después de mover una columna o reescribir una cabecera, o por coordenada como se escribe en una hoja de cálculo —=ROUND(SUM(E1:E4), 2)—, que dice dónde estaba una columna y no cuál es; rewriteRowFormulas() mueve esas con la hoja, y una referencia a algo borrado pasa a ser #REF! en lugar de leer en silencio a su vecina. Los dos puntos leen la columna entera dejando fuera la celda que pregunta; cualquier otro círculo se muestra como #CYCLE! en lugar de perseguirse.
`mergeable`	`boolean`	`false`	Si el lector puede combinar celdas y separarlas, desde el menú contextual —así que necesita también contextMenu—. Desactivado salvo que se pida, como todo cambio de estructura.
`editOn`	`'click' \| 'double-click'`	`'double-click'`	Qué abre el editor con el puntero. Doble clic por omisión, la convención de las hojas de cálculo: un clic elige la celda y deja su valor en paz, el primer carácter que se teclea abre el editor y cae dentro, y una celda con lista o fecha enseña una marca que la abre de un solo clic. Con click se abre al primero, para una hoja que existe para escribir en ella. En ambos casos el editor abre al soltar y solo si el puntero no se ha movido, así que arrastrar un rango sigue funcionando.
`contextMenu`	`boolean`	`false`	Si el botón derecho ofrece el menú de cambios de estructura. Cada entrada tiene que pasar los permisos, y el menú nunca se abre vacío.
`columns[].kind`	`'text' \| 'number' \| 'currency' \| 'date' \| 'boolean' \| 'select'`	`'text'`	Cómo muestra la columna sus valores y cómo lee lo que se escribe. Una columna de lista abre un desplegable y rechaza lo que no esté en él; una de sí/no dibuja una casilla que se cambia de un clic; una de fecha abre un campo de fecha.
`columns[].formula`	`string`	—	Una fórmula de la que sale cada celda de esta columna, declarada en código y no guardada en los datos: un total de línea, un impuesto, un saldo acumulado. Es lo contrario de una fórmula que escribe el lector, que es un valor que la fila tiene y se cambia como cualquier otro. Las celdas de una columna así no se pueden editar: sustituir una perdería la fórmula solo en esa fila, y eso no se nota hasta que los totales dejan de cuadrar. Necesita formulas en la hoja.
`columns[].placeholder`	`string`	—	Un aviso que sale en una celda vacía de esta columna mientras el puntero está encima. Nunca en lugar de un valor: una columna de avisos siempre visibles se lee como una columna con contenido.
`columns[].options`	`readonly HubSpreadsheetOption[]`	—	Las respuestas que ofrece una columna de lista. La celda muestra la etiqueta que corresponde y no el valor guardado, y si no encaja ninguna muestra el valor en crudo, para que una fila con una opción retirada siga leyéndose.
`structure`	`HubSpreadsheetStructureOptions<TRow>`	`{}`	Qué cambios de estructura puede pedir el lector. Todo se rechaza hasta que se permite.
`retiredColumnKeys`	`readonly string[]`	`[]`	Alias de columnas borradas, para que una nueva no herede una identidad muerta.

Outputs

Reacciona a lo que hace spreadsheet: 12 eventos a los que enganchar tu lógica.

Nombre	Tipo	Descripción
`commit`	`HubSpreadsheetCommit<TRow>`	Una celda toma un valor nuevo, distinto del que tenía.
`pasted`	`HubSpreadsheetPaste<TRow>`	Se pegó un bloque, con la cuenta de lo que cayó fuera y de lo que no era número.
`cleared`	`HubSpreadsheetCellRef<TRow>[]`	Se pulsó Supr sobre una selección; trae las celdas editables que cubría.
`selectionChange`	`HubGridRange \| null`	Cambió el rectángulo seleccionado.
`filled`	`HubSpreadsheetPaste<TRow>`	Terminó un arrastre del tirador, avisado como un solo evento para todo el gesto.
`undoRequested`	`void`	El lector pidió deshacer.
`redoRequested`	`void`	El lector pidió rehacer.
`columnMoved`	`{ from: number; to: number; key: string; keys: string[] }`	Se soltó una columna en otro sitio. Se avisa, no se aplica: el aviso trae los alias ya reordenados.
`mergeRequested`	`HubSpreadsheetMergeRequest`	El lector pide combinar una selección. Lleva el bloque que se crea y las anclas de los que absorbe, porque añadirlo sin quitar esos deja dos bloques reclamando la misma celda. applySpanMerge() lo resuelve en una línea.
`unmergeRequested`	`readonly HubGridCoords[]`	El lector pide separar los bloques que toca su selección, nombrados por sus anclas. applySpanUnmerge() lo aplica.
`insertRequested`	`HubSpreadsheetInsertRequest`	El lector pidió añadir filas o columnas.
`deleteRequested`	`HubSpreadsheetDeleteRequest`	El lector pidió quitar filas o columnas, nombrando los alias en juego.

Métodos

Controla spreadsheet desde el código — 17 métodos en su superficie programática.

Nombre	Firma	Devuelve	Descripción
`sheetToXlsx`	`sheetToXlsx<TRow>(rows, columns, options?: HubXlsxOptions): Uint8Array`	`Uint8Array`	La hoja como un .xlsx de verdad, en bytes. Los números siguen siendo números y una columna de fecha es una fecha, que es lo que un CSV no sabe llevar. Escribe lo que muestra la celda —una columna de lista exporta su etiqueta; una fórmula, su resultado— salvo que se pida values: 'stored'.
`downloadXlsx`	`downloadXlsx(filename: string, bytes: Uint8Array): void`	—	Le da ese libro al lector para que lo guarde, añadiendo .xlsx al nombre si le falta. Está aquí porque todos los anfitriones escriben las mismas seis líneas y se olvidan de liberar la URL del objeto.
`xlsxToRecords`	`xlsxToRecords<TRow>(bytes, columns, options?: HubXlsxReadOptions): Promise<Array<Record<string, string>>>`	`Promise<Array<Record<string, string>>>`	Lee la primera hoja de un libro y devuelve las filas con los alias de columna por clave, deshaciendo las dos cosas que un CSV nunca hace: las cadenas compartidas y las fechas guardadas como número de días. Es asíncrona porque un libro de verdad viene comprimido y el descompresor lo trae la plataforma.
`sheetToCsv`	`sheetToCsv<TRow>(rows, columns, options?: HubCsvOptions): string`	`string`	La hoja como CSV. Si no se dice el separador, sale de la marca decimal —una coma no puede separar lo que también puntúa—, así que un archivo que se va a leer donde se escribe 1.234,56 lleva punto y coma.
`downloadText`	`downloadText(filename: string, text: string, type?: string): void`	—	Le da al lector un archivo de texto para guardar, con la marca que hace que una hoja de cálculo lo abra como UTF-8 y no como galimatías.
`csvToRecords`	`csvToRecords<TRow>(text, columns, options?: HubCsvOptions): Array<Record<string, string>>`	`Array<Record<string, string>>`	Lee un CSV y devuelve las filas con los alias de columna por clave, olfateando el separador en la primera línea en lugar de suponerlo. Las cabeceras se emparejan primero por cabecera y después por alias, sin distinguir mayúsculas ni espacios.
`sheetValues`	`sheetValues<TRow>(rows, columns, options?: HubSheetValuesOptions): HubSpreadsheetValue[][]`	`HubSpreadsheetValue[][]`	Lo que tiene cada celda, con las fórmulas ya resueltas y las que fallan escritas como las escribe una hoja de cálculo. Es lo que leen los dos exportadores, expuesto para quien escriba su propio archivo.
`evaluateSheet`	`evaluateSheet<TRow>(input: HubFormulaSheetInput<TRow>): HubFormulaSheet`	`HubFormulaSheet`	Ejecuta todas las fórmulas de una hoja en el orden que exijan las dependencias, con el resultado calculado a demanda y recordado. Un círculo se detecta en cuanto se cierra, en lugar de perseguirse. Se exporta para quien quiera las respuestas sin dibujarlas.
`rewriteRowFormulas`	`rewriteRowFormulas<TRow extends object>(rows, change: HubFormulaShapeChange): TRow[]`	`TRow[]`	Mueve todas las coordenadas de las filas cuando la hoja cambia de forma: una columna movida, o filas y columnas insertadas o borradas. Una referencia a algo borrado pasa a ser #REF! en lugar de leer en silencio a su vecina. La llama el anfitrión, porque las filas son suyas.
`mergeRequestFor`	`mergeRequestFor(spans, range): HubSpreadsheetMergeRequest \| null`	`HubSpreadsheetMergeRequest \| null`	El bloque en que se convertiría una selección, y las anclas que absorbe; null si es una sola celda. Las anclas absorbidas son la parte que se hace mal a mano: si se añade sin quitarlas, dos bloques reclaman la misma celda.
`applySpanMerge`	`applySpanMerge(spans, request: HubSpreadsheetMergeRequest): HubGridSpan[]`	`HubGridSpan[]`	La lista de bloques después de esa combinación, sin los que absorbe.
`applySpanUnmerge`	`applySpanUnmerge(spans, anchors: readonly HubGridCoords[]): HubGridSpan[]`	`HubGridSpan[]`	La lista de bloques después de separar esos.
`spreadsheetRecords`	`spreadsheetRecords<TRow>(rows, columns): HubSpreadsheetRecord[]`	`HubSpreadsheetRecord[]`	Todas las filas como datos planos con los alias de columna por clave, para trabajar con { price: 12, units: 3 } en lugar de emparejar coordenadas con los campos propios por posición.
`parseForColumn`	`parseForColumn<TRow>(text, column, decimalMark: ',' \| '.'): HubSpreadsheetValue \| undefined`	`HubSpreadsheetValue \| undefined`	Lo que vale en una columna un texto escrito o pegado: el valor, null si la celda está vacía y undefined si es algo que la columna no puede tener, con lo que quien llama puede rechazarlo en vez de guardar basura.
`nextColumnKey`	`nextColumnKey(taken: Iterable<string>, prefix?: string): string`	`string`	Un alias que no ha sido nunca de otra columna, así que una columna nueva no reutiliza un nombre retirado y ninguna referencia guardada puede acabar apuntando a otra cosa.
`danglingColumnKeys`	`danglingColumnKeys<TRow>(referenced: Iterable<string>, columns): string[]`	`string[]`	Las referencias que ya no apuntan a ninguna columna, que es lo que un borrado dejaría colgando.
`provideHubSpreadsheetControls`	`provideHubSpreadsheetControls(adapter: HubSpreadsheetControlsAdapter): EnvironmentProviders`	`EnvironmentProviders`	Registra un adaptador de controles, y entonces todas las columnas de lista se abren con él: con búsqueda, ya desplegado y con el carácter que abrió la celda en su caja de búsqueda. Sin adaptador la hoja dibuja su lista nativa, que es lo que la deja instalable por su cuenta.

Templates

Hazlo tuyo — 2 plantillas para proyectar tu propio marcado.

Nombre	Descripción	Ejemplo
`hubSpreadsheetEditor`	Sustituye el editor de una columna, nombrada por su alias. La plantilla recibe el valor, el par confirmar y cancelar, y `seed`: el carácter con el que el lector abrió la celda al escribir, que es lo que va en el buscador de un selector. Permanece abierta hasta que llama a uno de los dos. La hoja no depende de lo que pongas dentro.	`<ng-template hubSpreadsheetEditor="assignee" let-value let-seed="seed" let-commit="commit"> <hub-select [items]="people" autoOpen [initialSearchTerm]="seed ?? null" [ngModel]="value" (ngModelChange)="commit($event)" /> </ng-template>`
`hubSpreadsheetCell`	Dibuja tú las celdas de una columna mientras no se editan: una insignia para un estado, un avatar junto a un nombre, una fila de acciones. Es el hermano de hubSpreadsheetEditor, que cubre la otra mitad de la vida de una celda. El portapapeles sigue llevando el valor y no el dibujo, y la celda sigue siendo lo que tiene el teclado. Pasando las filas por hubSpreadsheetCellRows, el compilador sabe qué es `row`.	`<ng-template hubSpreadsheetCell="state" let-value> <hub-badge variant="soft" [color]="colourOf(value)">{{ labelOf(value) }}</hub-badge> </ng-template>`