Read Excel Sheet

Tipo: excel-read-sheet · Paquete: Excel Activities v1.0.6 · Salida: DataTable

Lee una hoja completa de Excel y la devuelve como una DataTable, usando la primera fila como encabezados de columna. Es la forma más práctica y común de leer datos de Excel: obtienes una tabla lista para recorrer, filtrar o volcar a otra fuente.

Cómo funciona

Abre la hoja indicada y convierte en DataTable su rango usado: el rectángulo que va desde la primera hasta la última celda con contenido (las celdas que solo tienen formato no cuentan). Si indicas range, lee exactamente ese rango. Por defecto toma la primera fila como nombres de columna (hasHeader = true), de modo que luego accedes a las celdas por nombre: str(fila["Cliente"]). Acepta session (modo sesión) o path (modo rápido) — ver los dos modos.

Solo lee: en modo rápido no modifica el archivo.

Parámetros requeridos

Ninguno — pero debes indicar session o path (o estar dentro del body de un Excel Open).

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
`session`	`ZoanExcelSession`	—	Sesión de Excel Open (en vez de `path`).
`path`	`string`	—	Ruta al `.xlsx` (modo rápido: abre y cierra solo). El archivo debe existir.
`sheet`	`string \| int`	—	Nombre o índice (desde 1) de la hoja. Si se omite, la primera.
`hasHeader`	`bool`	`true`	La primera fila son los encabezados. Con `false`, las columnas se llaman `Col1`, `Col2`… y la primera fila es un dato más.
`range`	`string`	—	Limitar a un rango, ej. `"A1:D50"`. Si se omite, el rango usado de la hoja.

Salida

Devuelve un DataTable:

Columnas: con hasHeader = true, el texto de cada celda de la primera fila; un encabezado vacío se llama Col<n> según su posición (Col4). Con hasHeader = false, Col1, Col2…
Filas: una por cada fila del rango (sin la de encabezado), incluidas las filas vacías intermedias.
Valores: cada celda conserva su tipo (desde la versión 1.0.6): número (double), fecha (DateTime), booleano o texto; las fórmulas, con su resultado. Una columna con solo texto es de texto; si trae números, fechas o booleanos admite cualquier valor. Las celdas vacías son DBNull. Al volver a escribir la tabla con Write Excel Sheet, los números y fechas siguen siendo números y fechas. Ver cómo llegan los datos.
Hoja vacía: devuelve una DataTable sin columnas ni filas (y deja un aviso en el log).

Errores comunes

Mensaje	Causa y solución
`Indica 'session' o 'path'.`	Falta `session` y `path`. Indica uno de los dos.
`No se encontró el archivo.`	`path` no existe. Valida antes con File Exists.
`There isn't a worksheet named '…'.`	No hay una hoja con ese nombre. Lista las hojas con Get Excel Sheet Names.
`There isn't a worksheet associated with that position.`	El índice es mayor que el número de hojas, o el nombre de la hoja es solo un número (se toma como índice). Ver hojas con nombre numérico.
`'…' is not A1 address or named range.`	`range` no es una dirección válida. Usa la forma `"A1:D50"`.
`A column named '…' already belongs to this DataTable.`	Dos encabezados se llaman igual (sin distinguir mayúsculas). Renombra uno en el archivo o lee con `hasHeader = false`.
`Extension 'xls' is not supported. Supported extensions are '.xlsx', '.xlsm', '.xltx' and '.xltm'.`	El archivo es `.xls` o `.csv`. Conviértelo a `.xlsx`; para CSV usa Read CSV.

Ejemplo

Read Excel Sheet   path = asset("clientes.xlsx")   sheet = "Activos"   → output: clientes
Log   message = "Clientes leídos: " + rowCount(clientes)

For Each   items = clientes   itemVariable = fila
 └─ activities:
      Log   message = str(fila["Nombre"]) + " — " + str(fila["NIT"])

Actividades relacionadas

Read Excel Range — leer un rango exacto.
Read Excel Cell — leer una sola celda, con su tipo.
Write Excel Sheet — escribir una DataTable de vuelta.