Clase envoltorio que permite la administración general de libros de trabajo y sus hojas de cálculo. Más...

Diagrama de herencia de WorkbookWrapper

Métodos públicos
	__New (workbook, targetSheet?)
	Crea un envoltorio para la administración de un libro de trabajo específico y una de sus hojas de cálculo.
	IsAvailable ()
	Comprueba si el libro de trabajo objetivo está abierto y accesible.
	IsWorkbookLocked ()
	Comprueba si el libro de cálculo objetivo está bloqueado.
	IsSheetLocked ()
	Comprueba si la hoja de cálculo objetivo está bloqueada.
	GetRowCount ()
	Obtiene el número de filas utilizadas en el rango objetivo.
	GetColumnCount ()
	Obtiene el número de columnas utilizadas en el rango objetivo.
	IsTargetSheetEmpty ()
	Comprueba si la hoja de cálculo objetivo está vacía.
	IsTargetWorkbook (workbook)
	Comprueba si un libro de trabajo coincide con el libro objetivo.
	HighlightRow (row)
	Señala con un color amarillo la fila indicada y restablece la anterior.
	ValidateHeaders (expectedHeaders, &missingHeaders :=unset)
	Normaliza las cabeceras de la tabla objetivo y las valida respecto a la colección facilitada.
	FindString (str, lookAt :=2, matchCase :=false)
	Busca una cadena en el rango objetivo y devuelve el número de fila relativa a la primera coincidencia en el rango utilizado.

Atributos públicos
	Name => this._name
	{String} Nombre del libro de trabajo objetivo.
	TargetSheetName => this._targetSheetName
	{String} Nombre de la hoja de cálculo objetivo.

Métodos protegidos
	_LockWorkbook (lock)
	Bloquea el libro de trabajo objetivo impidiendo la manipulación del número de hojas.
	_LockSheet (lock)
	Bloquea la hoja de cálculo objetivo impidiendo la modificación y la selección de sus celdas.
	_DeleteEmptyRows ()
	_GetTargetRange ()
	Obtiene el rango de la primera tabla si existiera, o el rango continuo utilizado.
	_WrapTargetRangeInTable (hasHeaders :=0)
	Envuelve el rango objetivo en una tabla si no existe ninguna.
	_GetRowSafeArray (row)
	Obtiene el contenido de una fila del rango objetivo como un SafeArray COM.
	_NormalizeTableHeaders ()
	Normaliza las cabeceras de la tabla objetivo conforme a __NormalizeHeader.
	_SpeedupIO (i)

Métodos protegidos estáticos
static	_NormalizeObjProps (obj)
	Normaliza los nombres de las propiedades del objeto indicado conforme a __NormalizeHeader.
static	_CreateInteropArray (size1, size2)
	Crea un SafeArray bidimensional (VT_VARIANT) con índices de base 1 como los que devuelve Interop, que se supone utiliza una versión descontinuada del SafeArray.

Atributos protegidos
_name	:= unset
_workbook	:= unset
_targetSheet	:= unset
_targetSheetName	:= unset

Métodos privados
	__ThrowIfWorkbookIsInvalid (workbook :=this._workbook)
	Valida que el libro de trabajo se encuentre abierto y accesible.
	__InvokeExcelSafelyDelayed (fun, params *)
	Ejecuta una función controlando la interacción del usuario con Excel para evitar fallos de automatización durante sus operaciones con el COM.

Métodos privados estáticos
static	__NormalizeHeader (header)
	Una cabecera normalizada debe estar en mayúsculas, sin tildes y con barras bajas en vez de espacios.

Atributos privados
__lastHighlightedRow	:= 0

Descripción detallada

Clase envoltorio que permite la administración general de libros de trabajo y sus hojas de cálculo.

Es capaz de escapar la edición del usuario si impide la conexión con la interfaz de Excel.

Nota: La hoja de cálculo objetivo solo puede contener una tabla como máximo.

Autor: bitasuperactive

Fecha: 25/12/2025

Versión: 0.9.1-Beta

Atención

Dependencias:

Utils.ahk

Ver también: https://github.com/bitasuperactive/ahk2-excel-library/blob/master/ExcelLibrary/ExcelBridge/WorkbookWrapper.ahk

Documentación de funciones miembro

◆ __InvokeExcelSafelyDelayed()

WorkbookWrapper::__InvokeExcelSafelyDelayed	(	fun	,
		params *	)

inlineprivate

Ejecuta una función controlando la interacción del usuario con Excel para evitar fallos de automatización durante sus operaciones con el COM.

Si Excel rechaza la llamada COM por estar ocupado (por ejemplo, debido a edición activa de celdas o diálogos modales) tras 30 reintentos en 30 segundos, esta función envía {ESCAPE} para cancelar la edición en curso y reintenta la operación una única vez más.

Solo intercepta errores COM conocidos relacionados con Excel ocupado (HRESULT 0x80010001, 0x800AC472). Cualquier otro error se relanza.

Nota: Notifica al usuario mediante un TrayTip al escapar la edición.

Parámetros

{Func}	fun Función a ejecutar. Debe aceptar this como primer parámetro.
{Any}	params Parámetros opcionales que se pasarán a la función.

Devuelve: {Any} Valor devuelto por la función ejecutada.

Excepciones

{Error} Relanza la excepción si el error no es recuperable o si todos los reintentos fallan.

◆ __New()

WorkbookWrapper::__New	(	workbook	,
		targetSheet?	)

inline

Crea un envoltorio para la administración de un libro de trabajo específico y una de sus hojas de cálculo.

Envuelve los datos preexistentes en una tabla para facilitar su delimitación.

Parámetros

{Microsoft.Office.Interop.Excel.Workbook}	workbook Libro de trabajo objetivo.
{Microsoft.Office.Interop.Excel.Worksheet}	targetSheet (Opcional) Hoja de cálculo objetivo. Por defecto, será la hoja de cálculo activa en el libro.

Excepciones

{TargetError}	(0x80010108) Si el libro de trabajo objetivo se encuentra cerrado.
{Error}	(0x80010001) Si Microsoft Excel rechaza la conexión a su interfaz.
{ValueError}	Si existe más de tabla definida en la hoja de cálculo objetivo.

◆ __NormalizeHeader()

WorkbookWrapper::__NormalizeHeader ( header )

inlinestaticprivate

Una cabecera normalizada debe estar en mayúsculas, sin tildes y con barras bajas en vez de espacios.

Parámetros

{String} header Título de la cabecera a normalizar.

Devuelve: {String} Cabecera normalizada.

◆ __ThrowIfWorkbookIsInvalid()

WorkbookWrapper::__ThrowIfWorkbookIsInvalid ( workbook : = this._workbook )

inlineprivate

Valida que el libro de trabajo se encuentre abierto y accesible.

Parámetros

{Microsoft.Office.Interop.Excel.Workbook} workbook (Opcional) Libro de trabajo a validar. Por defecto es el libro de trabajo objetivo.

Excepciones

{TargetError}	(0x80010108) Si el libro se encuentra cerrado.
{Error}	(0x80010001) Si Microsoft Excel rechaza la conexión a su interfaz.

◆ _CreateInteropArray()

WorkbookWrapper::_CreateInteropArray	(	size1	,
		size2	)

inlinestaticprotected

Crea un SafeArray bidimensional (VT_VARIANT) con índices de base 1 como los que devuelve Interop, que se supone utiliza una versión descontinuada del SafeArray.

Parámetros

{Integer}	size1 Tamaño para la primera dimensión.
{Integer}	size2 Tamaño para la segunda dimensión.

Devuelve: {ComObjArray} SafeArray bidimensional (VT_VARIANT) con índices de base 1.

◆ _DeleteEmptyRows()

WorkbookWrapper::_DeleteEmptyRows ( )

inlineprotected

Obsoleto

En desuso, es una función O(n) muy lenta para libros grandes.

Elimina las filas vacías del rango objetivo (contempla fórmulas).

Las tablas deben contener al menos un valor para auto-expandirse. Por ello, si la tabla carece de contenido, se rellenará la primera fila con el valor "null".

◆ _GetRowSafeArray()

WorkbookWrapper::_GetRowSafeArray ( row )

inlineprotected

Obtiene el contenido de una fila del rango objetivo como un SafeArray COM.

Excel Interop presenta un comportamiento inconsistente al leer valores:

Si la fila contiene una única columna o está vacía, devuelve un valor.
Si contiene varias columnas, devuelve un SafeArray.

Esta función normaliza dicho comportamiento garantizando que el valor devuelto sea siempre un ComObjArray (SafeArray) con índice base 1, incluso cuando la fila esté vacía o contenga una sola celda.

Parámetros

{Integer} row Índice (1-based) de la fila dentro del rango objetivo.

Devuelve: {ComObjArray} SafeArray bidimensional (1×N) que representa la fila solicitada.

Excepciones

{ValueError} Si el índice de fila está fuera del rango utilizado.

◆ _GetTargetRange()

WorkbookWrapper::_GetTargetRange ( )

inlineprotected

Obtiene el rango de la primera tabla si existiera, o el rango continuo utilizado.

Devuelve: {Microsoft.Office.Interop.Excel.Range} Rango objetivo.

Excepciones

{ValueError} Si existe más de tabla definida en la hoja de cálculo objetivo.

◆ _LockSheet()

WorkbookWrapper::_LockSheet ( lock )

inlineprotected

Bloquea la hoja de cálculo objetivo impidiendo la modificación y la selección de sus celdas.

Parámetros

{Boolean} lock Veradero para bloquear, Falso para desbloquear.

◆ _LockWorkbook()

WorkbookWrapper::_LockWorkbook ( lock )

inlineprotected

Bloquea el libro de trabajo objetivo impidiendo la manipulación del número de hojas.

Parámetros

{Boolean} lock Si bloquear o desbloquear.

◆ _NormalizeObjProps()

WorkbookWrapper::_NormalizeObjProps ( obj )

inlinestaticprotected

Normaliza los nombres de las propiedades del objeto indicado conforme a __NormalizeHeader.

Se utiliza para mantener la coherencia entre las tablas y los objetos AHK.

Parámetros

{Object} obj Objeto a normalizar.

Devuelve: {Object} Objeto normalizado.

Ver también: WorkbookWrapper::__NormalizeHeader

◆ _NormalizeTableHeaders()

WorkbookWrapper::_NormalizeTableHeaders ( )

inlineprotected

Normaliza las cabeceras de la tabla objetivo conforme a __NormalizeHeader.

Ver también: WorkbookWrapper::__NormalizeHeader

◆ _SpeedupIO()

WorkbookWrapper::_SpeedupIO ( i )

inlineprotected

Obsoleto: En desuso, la mejora de rendimiento es despreciable.

Desactiva o reactiva las optimizaciones de rendimiento en Excel. Principalmente, mejora el rendimiento de la escritura.

Parámetros

{Integer} i 1 para optimizar, 0 para restablecer.

◆ _WrapTargetRangeInTable()

WorkbookWrapper::_WrapTargetRangeInTable ( hasHeaders : = 0 )

inlineprotected

Envuelve el rango objetivo en una tabla si no existe ninguna.

Parámetros

{Integer} hasHeaders Si el rango tiene encabezados. Debe ser un valor XlYesNoGuess (1,2,0). Por defecto es 0 (Guess).

Excepciones

{ValueError} Si existe más de tabla definida en la hoja de cálculo objetivo.

◆ FindString()

WorkbookWrapper::FindString	(	str	,
		lookAt :	= 2,
		matchCase :	= false )

inline

Busca una cadena en el rango objetivo y devuelve el número de fila relativa a la primera coincidencia en el rango utilizado.

Parámetros

{String}	str Cadena a buscar.
{Integer}	lookAt (Opcional) 1 Buscar coincidencia completa. 2 Buscar coincidencia parcial. Por defecto es 2.
{Integer}	matchCase (Opcional) true para distinguir mayúsculas de minúsculas, false para no distinguir. Por defecto es false.

Devuelve: {Integer} Número de fila relativa a la posición de la cadena buscada. Devuelve 0 si no se encuentra.

◆ GetColumnCount()

WorkbookWrapper::GetColumnCount ( )

Obtiene el número de columnas utilizadas en el rango objetivo.

Devuelve: {Integer}

◆ GetRowCount()

WorkbookWrapper::GetRowCount ( )

Obtiene el número de filas utilizadas en el rango objetivo.

Devuelve: {Integer}

◆ HighlightRow()

WorkbookWrapper::HighlightRow ( row )

inline

Señala con un color amarillo la fila indicada y restablece la anterior.

Si se indica una fila ya señalada, restablece su color.

Parámetros

{Integer} row Fila a señalizar o restablecer.

◆ IsAvailable()

WorkbookWrapper::IsAvailable ( )

inline

Comprueba si el libro de trabajo objetivo está abierto y accesible.

Devuelve: {Boolean}

◆ IsSheetLocked()

WorkbookWrapper::IsSheetLocked ( )

Comprueba si la hoja de cálculo objetivo está bloqueada.

Devuelve: {Boolean}

◆ IsTargetSheetEmpty()

WorkbookWrapper::IsTargetSheetEmpty ( )

Comprueba si la hoja de cálculo objetivo está vacía.

Devuelve: {Boolean}

◆ IsTargetWorkbook()

WorkbookWrapper::IsTargetWorkbook ( workbook )

inline

Comprueba si un libro de trabajo coincide con el libro objetivo.

Parámetros

{Microsoft.Office.Interop.Excel.Workbook} workbook Libro de trabajo a comparar.

Devuelve: {Boolean} Verdadero si son equivalentes, Falso en su defecto.

◆ IsWorkbookLocked()

WorkbookWrapper::IsWorkbookLocked ( )

Comprueba si el libro de cálculo objetivo está bloqueado.

Devuelve: {Boolean}

◆ ValidateHeaders()

WorkbookWrapper::ValidateHeaders	(	expectedHeaders	,
		&missingHeaders :	= unset )

inline

Normaliza las cabeceras de la tabla objetivo y las valida respecto a la colección facilitada.

Parámetros

{Array<String>}	expectedHeaders Colección de los nombres de las cabeceras esperadas.
{VarRef<Array<String>>}	missingHeaders (OUT) Colección de los nombres de las cabeceras faltantes.

Devuelve: {Boolean} Verdadero si la tabla contiene todas las cabeceras, Falso en su defecto.

Métodos públicos

Atributos públicos

Métodos protegidos

Métodos protegidos estáticos

Atributos protegidos

Métodos privados

Métodos privados estáticos

Atributos privados

Descripción detallada

Documentación de funciones miembro

◆ __InvokeExcelSafelyDelayed()

◆ __New()

◆ __NormalizeHeader()

◆ __ThrowIfWorkbookIsInvalid()

◆ _CreateInteropArray()

◆ _DeleteEmptyRows()

◆ _GetRowSafeArray()

◆ _GetTargetRange()

◆ _LockSheet()

◆ _LockWorkbook()

◆ _NormalizeObjProps()

◆ _NormalizeTableHeaders()

◆ _SpeedupIO()

◆ _WrapTargetRangeInTable()

◆ FindString()

◆ GetColumnCount()

◆ GetRowCount()

◆ HighlightRow()

◆ IsAvailable()

◆ IsSheetLocked()

◆ IsTargetSheetEmpty()

◆ IsTargetWorkbook()

◆ IsWorkbookLocked()

◆ ValidateHeaders()