Administrador para el COM de Microsoft Excel. Más...

Clases
class	ConnectionTypeEnum
	Tipos de conexión o de uso admitidos para los libros de trabajo. Más...

Métodos públicos
	__New (allowReadAndWrite :=false)
	Crea un administrador para el COM de Microsoft Excel.
	GetAllOpenWorkbooksNames ()
	Obtiene los nombres sin extensión de todos los libros de trabajo abiertos y compatibles (con extensión ".xlsx").
	ConnectWorkbookByName (connType, name, lockSheet :=false)
	Conecta un libro de trabajo abierto mediante su nombre para el tipo de conexión especificado.
	AllowWorkbookClosure (allow)
	Permite cerrar los libros de trabajo conectados.
	UnlockWorkbook (connType, unlock)
	Desbloquea el libro de trabajo y hoja de cálculo objetivos para el tipo de conexión especificado.
	DisconnectWorkbook (connType)
	Desconecta el libro de trabajo conectado para el tipo de uso especificado, desbloqueándolo.
	Dispose ()
	Desecha la instancia desconectando los libros conectados y limpiando los manejadores de eventos configurados.

Atributos públicos
	ReadWorkbookAdapter => this._readWorkbookAdapter
	WriteWorkbookAdapter => this._writeWorkbookAdapter

Métodos privados
	_ConnectWorkbook (connType, workbook?, lockSheet :=false)
	Conecta el libro de trabajo abierto solicitado.
	_DisconnectWorkbook (adapter)
	Desconecta un libro de trabajo conectado, desbloqueándolo.
	_SetWorkbookAdapter (adapter)
	Establece el adaptador para el libro de trabajo objetivo según el tipo que le corresponda, y comprueba si se está infringiendo la regla de lectura y escritura en la misma hoja de cálculo.
	_SameAdapterForReadAndWrite (readAdapter :=this._readWorkbookAdapter, writeAdapter :=this._writeWorkbookAdapter)
	Comprueba si los adaptadores de lectura y escritura son el mismo.
	_LockWorkbook (adapter, lock)
	Bloquea el libro de trabajo especificado impidiendo su cierre y la manipulación del número de hojas.
	__OnTargetWorkbookBeforeClose (caller, cancel, workbook)
	Llamada ejecutada antes del cierre de alguno de los libros de trabajos conectados.
	__InvokeExcelSafely (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	_GetExcelCOM ()
	Ejecuta y/u obtiene el COM del proceso activo de Microsoft Excel y conecta el manejador de eventos para su aplicación.

Atributos privados
_excelCOM	:= unset
_allowReadAndWrite	:= unset
_readWorkbookAdapter	:= 0
_writeWorkbookAdapter	:= 0

Descripción detallada

Administrador para el COM de Microsoft Excel.

Conceptualizado para NO TOCAR los datos preexistentes en el libro de lectura y preservar así su integridad (excepto las cabeceras que se normalizan).
Es capaz de escapar la edición del usuario si impide el acceso al COM.
Es la ostia de rápido.

Nota

Se impone el uso de tablas para definir los rangos utilizados.
Relacionado con el anterior, las hojas de cálculo a trabajar solo pueden contener una tabla como máximo.
La validación de tipos perjudica el rendimiento.

Autor: bitasuperactive

Fecha: 25/12/2025

Versión: 0.9.2-Beta

Atención

Dependencias:

ExcelEventController.ahk
WorkbookWrapper.ahk
ReadWorkbookAdapter.ahk
WriteWorkbookAdapter.ahk
Utils.ahk

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

Documentación de funciones miembro

◆ __InvokeExcelSafely()

ExcelManager::__InvokeExcelSafely	(	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), esta función envía {ESCAPE} para cancelar la edición en curso y reintenta la operación una única vez.

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

Nota: No notifica al usuario al escapar la edición, ya que se asume que ha sido iniciada manualmente.

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 el reintento falla.

◆ __New()

ExcelManager::__New ( allowReadAndWrite : = false )

inline

Crea un administrador para el COM de Microsoft Excel.

Ejecuta Excel automáticamente.
Establece la conexión con el COM de Excel.

Atención: Al tratar con datos sensibles, es recomendable no permitir leer y escribir en la misma hoja de cálculo para garantizar la integridad de los datos.

Parámetros

{Boolean} allowReadAndWrite Si permitir que una misma hoja de cálculo se utilice tanto para lectura como para escritura.

Excepciones

{TargetError}	Si no ha sido posible iniciar Microsoft Excel automáticamente.
{Error}	(0x80004002) Si Microsoft Excel ha rechazado la conexión a su interfaz.

◆ __OnTargetWorkbookBeforeClose()

ExcelManager::__OnTargetWorkbookBeforeClose	(	caller	,
		cancel	,
		workbook	)

inlineprivate

Llamada ejecutada antes del cierre de alguno de los libros de trabajos conectados.

Desconecta el libro antes de completar el cierre.

Atención: Si el usuario cancela el guardado, el libro queda desconectado.

Parámetros

{Object}	caller Referencia al objeto llamante.
{Boolean}	cancel Si se ha cancelado el cierre solicitado.
{Microsoft.Office.Interop.Excel.Workbook}	workbook Libro de trabajo a cerrar.

◆ _ConnectWorkbook()

ExcelManager::_ConnectWorkbook	(	connType	,
		workbook?	,
		lockSheet :	= false )

inlineprivate

Conecta el libro de trabajo abierto solicitado.

Toma la hoja de cálculo activa en el momento de la conexión.
El libro es bloqueado para evitar su cierre y la manipulación del número de hojas.

Parámetros

{ExcelManager.ConnectionTypeEnum}	connType Tipo de uso que se le dará al libro.
{Microsoft.Office.Interop.Excel.Workbook}	workbook (Opcional) Libro de trabajo objetivo. Por defecto es el libro activo.
{Boolean}	lockSheet (Opcional) Si bloquear la hoja de cálculo objetivo impidiendo la modificación y la selección de sus celdas. Por defecto es falso.

Excepciones

{Error} Si no se ha permitido leer y escribir en la misma hoja de cálculo pero se intenta establecer esa conexión.

Bloquea la hoja de cálculo objetivo y conecta sus eventos.

◆ _DisconnectWorkbook()

ExcelManager::_DisconnectWorkbook ( adapter )

inlineprivate

Desconecta un libro de trabajo conectado, desbloqueándolo.

Parámetros

{ReadWorkbookAdapter | WriteWorkbookAdapter} adapter Adaptador del libro de trabajo objetivo.

Desbloquea la hoja de cálculo objetivo y desconecta sus eventos.

Nulifica la propiedad de instancia que almacena el adaptador especificado.

Parámetros

{ReadWorkbookAdapter | WriteWorkbookAdapter} adapter Adaptador del libro de trabajo objetivo.

◆ _GetExcelCOM()

ExcelManager::_GetExcelCOM ( )

inlinestaticprivate

Ejecuta y/u obtiene el COM del proceso activo de Microsoft Excel y conecta el manejador de eventos para su aplicación.

Devuelve: {Microsoft.Office.Interop.Excel.Application} Common Object Model para la instancia activa de Microsoft Excel.

Excepciones

{TargetError}	(0x800401E3)? Si no ha sido posible iniciar Microsoft Excel automáticamente.
{Error}	(0x80004002) Si Microsoft Excel ha rechazado la conexión a su interfaz.

◆ _LockWorkbook()

ExcelManager::_LockWorkbook	(	adapter	,
		lock	)

inlineprivate

Bloquea el libro de trabajo especificado impidiendo su cierre y la manipulación del número de hojas.

También desactiva las alertas de Excel.

Nota: Es obligatorio bloquear el libro objetivo para evitar que el usuario lo cierre y manipule el número de hojas.

Parámetros

{WorkbookWrapper}	adapter Adaptador objetivo.
{Boolean}	lock Si bloquear o desbloquear.

Excepciones

{Error} Si se intenta desbloquear el libro mientras la hoja de cálculo objetivo está bloqueada.

◆ _SameAdapterForReadAndWrite()

ExcelManager::_SameAdapterForReadAndWrite	(	readAdapter :	= this._readWorkbookAdapter,
		writeAdapter :	= this._writeWorkbookAdapter )

inlineprivate

Comprueba si los adaptadores de lectura y escritura son el mismo.

Parámetros

{ReadWorkbookAdapter}	readAdapter (Opcional) Libro de lectura.
{WriteWorkbookAdapter}	writeAdapter (Opcional) Libro de escritura.

Devuelve: {Boolean} Verdadero si ambos adaptadores son el mismo, Falso en su defecto.

◆ _SetWorkbookAdapter()

ExcelManager::_SetWorkbookAdapter ( adapter )

inlineprivate

Establece el adaptador para el libro de trabajo objetivo según el tipo que le corresponda, y comprueba si se está infringiendo la regla de lectura y escritura en la misma hoja de cálculo.

Parámetros

{ReadWorkbookAdapter | WriteWorkbookAdapter} adapter Adaptador para el libro de trabajo a establecer.

Excepciones

{Error} Si no se ha permitido leer y escribir en la misma hoja de cálculo pero se intenta establecer para ambos propósitos.

◆ AllowWorkbookClosure()

ExcelManager::AllowWorkbookClosure ( allow )

inline

Permite cerrar los libros de trabajo conectados.

Por defecto es Falso.

Parámetros

{Boolean} allow Verdadero para permitir el cierre, Falso para impedirlo.

◆ ConnectWorkbookByName()

ExcelManager::ConnectWorkbookByName	(	connType	,
		name	,
		lockSheet :	= false )

inline

Conecta un libro de trabajo abierto mediante su nombre para el tipo de conexión especificado.

Toma la hoja de cálculo activa en el momento de la conexión como objetivo del uso.
El libro es bloqueado para evitar su cierre y la manipulación del número de hojas.

Parámetros

{ExcelManager.ConnectionTypeEnum}	connType Tipo de uso que se le dará al libro.
{String}	name Nombre del libro de trabajo objetivo.
{Boolean}	lockSheet (Opcional) Si bloquear la hoja de cálculo objetivo impidiendo la modificación y la selección de sus celdas. Por defecto es falso.

Excepciones

{ValueError}	Si no existe ningún libro de trabajo abierto y compatible con el nombre solicitado.
{Error}	Si no se ha permitido leer y escribir en la misma hoja de cálculo pero se intenta establecer esa conexión.

◆ DisconnectWorkbook()

ExcelManager::DisconnectWorkbook ( connType )

inline

Desconecta el libro de trabajo conectado para el tipo de uso especificado, desbloqueándolo.

Parámetros

{ExcelManager.ConnectionTypeEnum} connType Tipo del libro de trabajo objetivo.

◆ GetAllOpenWorkbooksNames()

ExcelManager::GetAllOpenWorkbooksNames ( )

inline

Obtiene los nombres sin extensión de todos los libros de trabajo abiertos y compatibles (con extensión ".xlsx").

Devuelve: {Array<String>}

◆ UnlockWorkbook()

ExcelManager::UnlockWorkbook	(	connType	,
		unlock	)

inline

Desbloquea el libro de trabajo y hoja de cálculo objetivos para el tipo de conexión especificado.

Permisos administrados:

Editar la hoja de cálculo.
Cerrar el libro de trabajo.
Manipular el número de hojas.
Mostrar las alertas de Excel.

Atención: No sé por qué querrías hacer esto, pero no te lo recomiendo.

Parámetros

{ExcelManager.ConnectionTypeEnum}	connType Tipo del libro de trabajo objetivo.
{Boolean}	unlock Verdadero para desbloquear, Falso para bloquear.

Documentación de datos miembro

◆ ReadWorkbookAdapter

ExcelManager::ReadWorkbookAdapter => this._readWorkbookAdapter

Devuelve: {ReadWorkbookAdapter} Adaptador para el libro de lectura conectado.

◆ WriteWorkbookAdapter

ExcelManager::WriteWorkbookAdapter => this._writeWorkbookAdapter

Devuelve: {WriteWorkbookAdapter} Adaptador para el libro de escritura conectado.

Clases

Métodos públicos

Atributos públicos

Métodos privados

Métodos privados estáticos

Atributos privados

Descripción detallada

Documentación de funciones miembro

◆ __InvokeExcelSafely()

◆ __New()

◆ __OnTargetWorkbookBeforeClose()

◆ _ConnectWorkbook()

◆ _DisconnectWorkbook()

◆ _GetExcelCOM()

◆ _LockWorkbook()

◆ _SameAdapterForReadAndWrite()

◆ _SetWorkbookAdapter()

◆ AllowWorkbookClosure()

◆ ConnectWorkbookByName()

◆ DisconnectWorkbook()

◆ GetAllOpenWorkbooksNames()

◆ UnlockWorkbook()

Documentación de datos miembro

◆ ReadWorkbookAdapter

◆ WriteWorkbookAdapter