# office: hojas de Excel (xlsx.dkh) y texto de documentos (doc.dkh) La biblioteca **office** trae dos encabezados que comparten la misma DLL (`Devkron.Ext.Office.dll`): - **`xlsx.dkh`**: crear y leer libros de Excel `.xlsx` (usa ClosedXML). - **`doc.dkh`**: sacar el texto de documentos PDF, DOCX y XLSX (usa PdfPig, DocumentFormat.OpenXml y ClosedXML). Se instala aparte del motor: vea [Bibliotecas de terceros](/es/devkron/2.0/bibliotecas/terceros/). ## Cuándo usarla - Entregar reportes en Excel con números y fechas como tales (no como texto), en una o varias hojas. - Importar la plantilla de Excel que llena el usuario (catálogo de productos, clientes, existencias iniciales). - Indexar o buscar en contratos, facturas en PDF o manuales; pasar el texto de un documento a un agente de IA. ## Instalación Copie junto a `dkl` (o a la carpeta del servidor FastCGI) `xlsx.dkh`, `doc.dkh`, `Devkron.Ext.Office.dll` y las DLL que vienen en el zip (`ClosedXML.dll`, `ClosedXML.Parser.dll`, `DocumentFormat.OpenXml.dll`, `DocumentFormat.OpenXml.Framework.dll`, `ExcelNumberFormat.dll`, `RBush.dll`, `SixLabors.Fonts.dll`, `UglyToad.PdfPig*.dll` y las demás que incluya). Incluya solo el encabezado que use: ```dkl #include "xlsx.dkh" #include "doc.dkh" ``` ## xlsx.dkh | Función | Devuelve | Descripción | |---|---|---| | `xlsx.write(archivo, lista)` | — | Crea un libro con una hoja `Hoja1` | | `xlsx.write_sheets(archivo, hojas)` | — | Crea un libro con varias hojas | | `xlsx.to_bytes(lista)` | bytes | El libro de una hoja en memoria, sin archivo | | `xlsx.read(archivo, hoja)` | lista | Lee una hoja como lista de registros | | `xlsx.sheets(archivo)` | lista | Nombres de las hojas del libro | ### xlsx.write(archivo, lista) Crea (o sobrescribe) `archivo` con una hoja llamada `Hoja1`. - `lista`: lista de registros. La fila 1 lleva los nombres de los campos en negritas y queda inmovilizada; las columnas son la unión de los campos de todos los registros en el orden en que aparecen. - Los números se guardan como número y las cadenas como texto. Un campo que falta en un registro deja la celda vacía. - Las fechas de DKL (`20261027.143005`) son números: se guardan como número, no como fecha de Excel. ### xlsx.write_sheets(archivo, hojas) `hojas` es un registro cuyo nombre de campo es el nombre de la hoja y cuyo valor es la lista de registros (recuerde el `*` en los campos que apuntan a objetos): ```dkl new hojas { @"Productos*": productos @"Clientes*": clientes } do xlsx.write_sheets("reporte.xlsx", hojas) ``` Los nombres de hoja no pueden estar vacíos, pasar de 31 caracteres ni contener `: \ / ? * [ ]`. ### xlsx.to_bytes(lista) Devuelve el libro (una hoja `Hoja1`) como arreglo de bytes. Úselo en un servicio web para responder la descarga sin crear un archivo temporal; también puede guardarlo con `file.wbytes`. ### xlsx.read(archivo, hoja) Lee la hoja indicada (con `""` lee la primera) y devuelve una lista de registros. La primera fila con datos son los nombres de los campos; se lee solo el rango usado de la hoja. | Contenido de la celda | Valor en DKL | |---|---| | número | número (15 dígitos significativos, como Excel: `0.1` y no `0.1000000000000001`); uno fuera del rango decimal (±7.9 × 10²⁷) llega como cadena | | fecha | número `AAAAMMDD.HHMMSS` | | hora sola | número `0.HHMMSS` | | VERDADERO / FALSO | `1` / `0` | | texto | cadena | | vacía | `""` (cadena vacía) | | error de fórmula | el texto del error (`#N/A`, `#DIV/0!`…) | | fórmula | su resultado; si el libro no lo trae guardado se recalcula | Encabezado vacío → `columna_N`; repetido → `nombre_2`, `nombre_3`… Las filas totalmente vacías se saltan. Una hoja vacía devuelve una lista vacía. ### xlsx.sheets(archivo) Lista de cadenas con los nombres de las hojas, en orden. ### Errores de xlsx | Mensaje | Causa | |---|---| | `xlsx: no existe el archivo '…'.` | La ruta no existe | | `xlsx: falta la ruta del archivo.` / `… de destino.` | Ruta vacía | | `xlsx: el libro no tiene la hoja '…'.` | `hoja` no existe (revise con `xlsx.sheets`) | | `xlsx: no se pudo abrir '…' como libro XLSX: …` | No es `.xlsx`/`.xlsm`/`.xltx`/`.xltm` o está dañado. Los `.xls` antiguos no se leen: guárdelos como `.xlsx` | | `xlsx: no se pudo guardar '…': …` | Carpeta inexistente o el archivo está abierto en Excel | | `xlsx: el nombre de la hoja '…' pasa de 31 caracteres.` / `… tiene caracteres no permitidos …` / `… no puede estar vacío.` | Nombre de hoja inválido en `xlsx.write_sheets` | | `xlsx: se esperaba un registro {hoja: lista, ...}.` / `xlsx: el registro de hojas está vacío.` | Argumento de `xlsx.write_sheets` inválido | | `xlsx: la hoja '…' debe recibir una lista de registros.` / `… cada elemento de la hoja '…' debe ser un registro.` | La lista no es de registros | ## Ejemplo: leer un Excel y exportar un CSV Lee la hoja `Ventas`, descarta las filas sin fecha, suma el importe y deja un CSV para otro sistema. Requiere también [csv.dkh](/es/devkron/2.0/bibliotecas/terceros/csv.md). ```dkl #include "dkli.dkh" #! program "excel a csv" { #include "functions.dkh" #include "serialize.dkh" #include "xlsx.dkh" #include "csv.dkh" origen = "datos/ventas.xlsx" destino = "datos/ventas.csv" do print("Hojas: " + list.join(xlsx.sheets(origen), ", ")) ref filas = xlsx.read(origen, "Ventas") ref limpias = list.create() total = 0 for i=0; i: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" @http_context<"response/headers/content-disposition">: "attachment; filename=\"precios.xlsx\"" @http_context<"response/output">: "binary" @http_context<"response/binary*">: bytes } ``` En un programa real `filas` vendría de `dbr.list` (MySQL u otra base). Este ejemplo necesita el servidor FastCGI; en consola, guarde los bytes con `file.wbytes("precios.xlsx", bytes)`. ## doc.dkh | Función | Devuelve | Descripción | |---|---|---| | `doc.text(archivo)` | cadena | Texto de un `.pdf`, `.docx`, `.xlsx` o `.xlsm`, según la extensión | | `doc.pages(archivo)` | lista | Texto de cada página de un `.pdf` (una cadena por página) | ### doc.text(archivo) - **PDF**: el texto de todas las páginas, separadas por salto de línea, armado por renglones con las palabras de cada página. No hace OCR: un PDF escaneado (solo imágenes) devuelve texto vacío. - **DOCX**: un párrafo por línea (incluidos los de las tablas, una celda por línea); tabuladores y saltos de línea manuales se conservan. - **XLSX**: cada hoja precedida de `--- Hoja: Nombre ---` y cada fila con las celdas separadas por tabulador (fechas como `aaaa-mm-dd hh:mm:ss`, lógicos como `TRUE`/`FALSE`). ### doc.pages(archivo) Solo para PDF. Útil para decir en qué página aparece algo o para mandar el documento por partes a un LLM. ### Errores de doc | Mensaje | Causa | |---|---| | `doc: no existe el archivo '…'.` / `doc: falta la ruta del archivo.` | Ruta inexistente o vacía | | `doc: extensión no admitida en '…' (se admiten .pdf, .docx, .xlsx).` | Otro tipo de archivo (`.doc`, `.txt`…) | | `doc: doc.pages solo admite archivos .pdf ('…').` | `doc.pages` con un DOCX o XLSX | | `doc: no se pudo leer el PDF '…': …` / `doc: no se pudo leer el DOCX '…': …` | Archivo dañado o protegido con contraseña | ## Ejemplo: buscar en qué página de un PDF aparece un dato ```dkl #include "dkli.dkh" #! program "buscar en pdf" { #include "functions.dkh" #include "doc.dkh" ref paginas = doc.pages("datos/muestra.pdf") for i=0; i= 0 { do print("Página " + str(i + 1) + ": " + texto) } } do print("--- DOCX ---") do print(doc.text("datos/muestra.docx")) } ``` Salida: ``` Página 1: Factura de prueba pagina uno Total: 1,500.75 MXN --- DOCX --- Contrato de prueba Primer párrafo con acentos: ñandú. Segundo con tabulador celda A celda B ``` ## Buenas prácticas - **Limite el tamaño de los archivos que suben los usuarios** antes de abrirlos: `xlsx.read`, `doc.text` y `doc.pages` cargan el documento completo en memoria, sin tope de páginas ni de celdas. Un XLSX hecho para ocupar gigas al descomprimirse o un PDF enorme pueden agotar la memoria del servidor FastCGI. Revise `field.num(httpreq.file(campo), "size")` y procese los documentos grandes en una tarea de consola. - `xlsx.write` guarda las cadenas como texto, nunca como fórmula: un valor `=SUMA(A1:A9)` escrito por un usuario no se ejecuta al abrir el libro. - Un libro con fórmulas sin valor guardado (generado por otro programa) se recalcula al leerlo; con fórmulas muy pesadas puede tardar. - Todo es .NET administrado, sin bibliotecas nativas: funciona igual en Linux y Windows (x64 y ARM). ## Errores típicos - **`Tipos no coinciden` al sumar o comparar un campo leído de Excel**: una celda vacía llega como `""` y una con número como número. Revise el tipo con `field.typeof(registro, "campo")` (1 = cadena, 2 = número) o lea con `field.num`/`field.dnum` y `field.str`. - **El archivo no se guarda en Windows**: el libro está abierto en Excel; ciérrelo. - **Texto vacío de un PDF**: el PDF es una imagen escaneada; `doc.text` no hace OCR. - **Fechas como número**: es lo esperado en DKL (`AAAAMMDD.HHMMSS`). Para mostrarlas use las funciones de fecha de `functions.dkh` o [time.dkh](/es/devkron/2.0/bibliotecas/estandar/time.md).