HotXLS Docs

Referencias externas de libro

Información general

Los modelos de hoja de cálculo suelen obtener datos de libros secundarios mediante fórmulas de referencia cruzada; HotXLS admite el análisis, la escritura y la conservación de referencias externas de libro tanto en documentos BIFF8 (XLS clásico) como en OpenXML (XLSX)

Espacio de trabajo de libros activos

TXLSWorkbookWorkspace, en lxWorkbookWorkspace, es el núcleo compartido de identidad y registro para libros externos activos; tanto TXLSWorkbook como TXLSXWorkbook exponen CreateWorkspaceWorkbook y tienen un ExternalWorkspace propio que usan sus evaluadores de fórmulas, mientras que un libro ODS abierto por medio de TXLSXWorkbook reporta el tipo de motor OpenDocument a través del mismo adaptador

var
  Host, Target: TXLSXWorkbook;
begin
  Host.ExternalWorkspace.Add(
    '..\Data\Target.xlsx',
    '..\Data\Target.xlsx',
    'C:\Models\Host.xlsx',
    Target.CreateWorkspaceWorkbook);

  // The compatibility facade maps an unambiguous name to the
  // relationship target already stored in Host.ExternalLinks
  Host.RegisterExternalWorkbook('Target.xlsx', Target);

  // The matching call revokes a facade-level registration
  Host.UnregisterExternalWorkbook('Target.xlsx');
end;

Los libros clásicos usan los mismos métodos de compatibilidad con destinos TXLSWorkbook; RegisterExternalWorkbook y UnregisterExternalWorkbook administran únicamente la asignación de nombres a nivel de fachada, mientras que ExternalWorkspace.Remove y Clear revocan los registros del espacio de trabajo en sí. Los llamadores multi-motor agregan cualquier adaptador clásico, XLSX u ODS directamente a ExternalWorkspace

  • La normalización de identidades es léxica e insensible a mayúsculas y minúsculas, preserva rutas y extensiones, resuelve los destinos relativos contra la identidad de origen del propietario, colapsa los segmentos de puntos y no realiza ningún acceso al sistema de archivos ni a la red
  • Las identidades exactas y los alias explícitos se resuelven primero; la búsqueda solo por nombre base tiene éxito únicamente cuando exactamente un registro conectado coincide; de lo contrario, Resolve devuelve xlswrsConflict
  • Add rechaza las colisiones de clave exacta, de alias y de libros duplicados; rutas completas distintas y extensiones distintas pueden coexistir
  • Remove y Clear revocan los registros, mientras que la destrucción directa de un destino clásico o XLSX desconecta su adaptador y espera a los lectores activos antes de liberar el modelo
  • Las hojas externas se resuelven por el nombre declarado antes del fallback posicional basado en uno, de modo que el orden de hojas del libro de destino no tiene que coincidir con el directorio de vínculos de origen
  • El evaluador de fórmulas lee primero un libro activo resuelto y luego recurre a la caché con tipos del archivo anfitrión; los anfitriones XLS clásicos decodifican valores XCT y CRN dispersos, mientras que los anfitriones XLSX usan la caché de vínculos externos que el modelo de paquete ya contiene
  • OnLoadWorkbook es una petición de recurso opcional y controlada; su valor predeterminado es nil, de modo que el recálculo sigue sin realizar acceso al sistema de archivos ni a la red, salvo que el código de la aplicación provea explícitamente esa política
  • Cada identidad normalizada invoca el loader a lo sumo una vez hasta ResetLoadAttempts; las peticiones de nivel superior concurrentes comparten el resultado en curso, incluidos los desenlaces de no encontrado y de error con tipos, en lugar de abrir el mismo recurso repetidamente
  • MaxLoadDepth tiene como valor predeterminado 16 y MaxWorkbookCount 64; la reentrada con la misma identidad, las dependencias anidadas sobre una identidad ya en curso, el agotamiento de profundidad y el agotamiento del recuento de libros devuelven diagnósticos con tipos sin bloquearse dentro de un ciclo de carga
  • Las IRI de fuentes externas ODF permanecen como identidades léxicas completas, incluidos los esquemas URI y los caracteres entre comillas, pero nunca autorizan un acceso implícito a archivos o a la red
  • Un conflicto de identidades permanece como #REF! para que datos en caché obsoletos no puedan ocultar un enrutamiento ambiguo; una celda ausente en la caché es un valor vacío solo cuando el archivo declara una caché válida para esa hoja

Resolve realiza la búsqueda en los registros y luego la carga opcional controlada; su resultado es un TXLSWorkspaceResolveStatus (xlswrsResolved, xlswrsNotFound, xlswrsConflict, xlswrsDisconnected, xlswrsLoadNotFound, xlswrsLoadLimit, xlswrsLoadLoop o xlswrsLoadError), y ResolveWithLoader también devuelve un TXLSWorkspaceLoadDiagnostic que empareja un TXLSWorkspaceLoadDiagnosticCode con un TXLSWorkspaceLoadResponseStatus (xlswlrsNotFound, xlswlrsResolved, xlswlrsError) para distinguir los desenlaces de no encontrado, error del loader, resultado desconectado, límite de profundidad o de libros, reentrada de identidad, dependencia concurrente y conflicto de registro. La devolución de llamada del loader recibe un TXLSWorkspaceLoadRequest (identidad, profundidad, recuento registrado, límites) y responde con un TXLSWorkspaceLoadResponse

Recalculate reporta un TXLSWorkspaceRecalcStatus, opcionalmente con un desglose TXLSWorkspaceRecalcResult, y el evaluador registra la procedencia por celda como un TXLSWorkspaceRuntimeLookup (xlswrlInactive, xlswrlResolved, xlswrlFallbackCache o xlswrlError) para que los diagnósticos puedan distinguir una lectura activa de un fallback a la caché

El adaptador IXLSWorkspaceWorkbook expone EngineKind (tipo TXLSWorkspaceEngineKind: xlsweClassic, xlsweOpenXml u xlsweOpenDocument), SourceIdentity, InstanceIdentity y Generation, comprueba si está vivo con IsConnected, lee una celda por medio de TryGetCellValue (que devuelve un TXLSWorkspaceCellStatus con tipos: valor, ausente, referencia inválida, desconectado o error, más una marca de fuera del rango usado), actualiza el modelo con Recalculate y se desvincula del modelo del libro con Disconnect

El registro agrega AddAlias para nombres adicionales enlazados a una identidad registrada, TryResolve como la variante de búsqueda sin excepciones y BaseNameMatchCount para previsualizar cuántos registros conectados comparten un nombre base antes de elegir un destino no ambiguo

Grafo de dependencias entre libros

BuildDependencyGraph toma una instantánea de cada adaptador de libro registrado y extrae nodos de fórmulas de los modelos XLS clásico, XLSX y ODS hacia un único TXLSWorkspaceDepGraph; el método devuelve False y ningún grafo parcial cuando algún adaptador registrado no puede proveer los metadatos de dependencias

  • Cada nodo de fórmula conserva su identidad canónica de libro, el nombre de hoja y la posición de hoja basada en uno, la posición de celda con base cero, el rectángulo de salida del array, la volatilidad y el estado de referencias sin resolver
  • Las referencias de celdas y de rangos rectangulares conservan las identidades canónicas del libro y de la hoja de destino; las referencias de columna completa, fila completa y hoja completa permanecen como un único intervalo en lugar de expandirse a millones de celdas
  • Los nombres definidos locales siguen siendo consultables como dependencias simbólicas y también se expanden a sus dependencias concretas de celda o de rango cuando la definición puede resolverse de forma estática
  • Los nombres definidos externos preservan la ranura del vínculo externo, el nombre declarado, el ámbito opcional de hoja y la identidad canónica del destino, sin tratar los metadatos DDE, OLE o de funciones de usuario como nombres de libro
  • FindDependentsOfCell y la construcción de aristas del grafo usan árboles de intervalos de filas con poda de extremo máximo; LastRangeCandidateChecks y EdgeCandidateChecks exponen el número de comprobaciones exactas de rectángulos para verificar el rendimiento
  • La extracción de fórmulas se ejecuta bajo concesiones de lectura del libro y solo escanea los objetos de fórmula materializados, de modo que el almacenamiento de valores empaquetados sigue empaquetado y la creación del grafo no modifica las generaciones del libro

Recálculo programado

Recalculate retiene el grafo compartido y solo lo reconstruye cuando cambia el registro del espacio de trabajo o la generación de dependencias de fórmulas de un libro; las generaciones de valores disparan una nueva pasada dirty, y lo dirty se propaga a través de las aristas de dependencia entre libros

var
  RecalcInfo: TXLSWorkspaceRecalcResult;
  Status: TXLSWorkspaceRecalcStatus;
begin
  Status := Workspace.Recalculate(RecalcInfo);
  if Status <> xlswrcOk then
    HandleWorkspaceCalculation(Status, RecalcInfo);
end;
  • Los componentes fuertemente conexos se calculan sobre las celdas de fórmulas, de modo que los libros pueden enlazarse en ambas direcciones y seguir siendo acíclicos cuando sus rutas de dependencia a nivel de celda no forman un ciclo
  • Los miembros reales de un ciclo y los descendientes dirty bloqueados por un ciclo se invalidan y se excluyen del orden topológico, lo que evita que valores en caché obsoletos se presenten como resultados exitosos
  • Las referencias volátiles o sin resolver estáticamente fuerzan el comportamiento dirty conservador que exige la corrección, mientras que los grafos estables reutilizan el trabajo de dependencias previo
  • Las lecturas externas dentro de una pasada usan una caché exacta por instancia de libro, hoja, fila y columna; una fórmula programada invalida su rango de salida antes de evaluarse para que los dependientes posteriores observen el nuevo valor
  • La caché local de la pasada nunca otorga autoridad sobre recursos; los libros registrados y el loader opcional controlado por el llamador siguen siendo las únicas fuentes de resolución activas, seguidas por las cachés de archivos con tipos y #REF!
  • TXLSWorkspaceRecalcResult expone si el grafo fue reconstruido, además de los recuentos de dirty, de evaluadas, de invalidadas, de ciclos, de bloqueadas, de aciertos y de fallos de caché
  • El estado distingue éxito, adaptadores no admitidos, libros desconectados, referencias circulares, errores de cálculo y mutación del espacio de trabajo durante la pasada
  • Las llamadas a Recalculate sobre el mismo espacio de trabajo se serializan, de modo que dos sesiones de cálculo nunca modifican concurrentemente el grafo compartido ni las cachés del libro
  • Remove o Clear pueden ejecutarse mientras una pasada está activa; la pasada conserva instantáneas seguras de los adaptadores y devuelve xlswrcWorkspaceChanged en lugar de desreferenciar un registro eliminado
  • Destruir un espacio de trabajo espera a que su pasada activa termine, mientras que destruir un libro registrado desconecta su adaptador y hace que la resolución posterior falle de forma segura
  • Los fallos del loader y los resultados de no encontrado permanecen en caché una sola vez por identidad normalizada hasta ResetLoadAttempts, y un cálculo fallido retiene el estado dirty local para un reintento explícito
  • El grafo retenido hace que una pasada posterior sin cambios sea proporcional a los libros registrados en lugar del número de fórmulas; el análisis de componentes no recursivo y las aristas de rango compactas mantienen los modelos profundos y anchos acotados por los metadatos de fórmulas materializados

Desvincular nombres definidos externos

ConvertExternalDefinedNamesToRefErrors ofrece la misma operación pública en TXLSWorkbook y TXLSXWorkbook; devuelve el número de definiciones con ámbito de libro y de hoja que se reemplazaron con #REF! nativo

var
  Converted: Integer;
begin
  Converted := Workbook.ConvertExternalDefinedNamesToRefErrors;
  // External-link parts and ordinary cell formulas remain intact
end;
  • La selección en XLS clásico usa tokens de referencia BIFF compilados y la identidad XTI del libro de apoyo, de modo que las referencias tridimensionales dentro del mismo libro y los flujos de tokens inciertos permanecen sin cambios
  • La selección en XLSX usa ranuras numéricas de libro conscientes de la sintaxis en el orden de documento de las relaciones y acepta solo partes de vínculos externos de libro, excluyendo DDE, OLE, ranuras sin resolver, referencias de tabla y texto entre corchetes dentro de cadenas
  • Todos los reemplazos se preparan antes de la primera mutación y se confirman como una única operación de escritura; una segunda llamada es idempotente
  • El texto del nombre, el ámbito de libro o de hoja, la visibilidad, los comentarios, las marcas de macro y de integrado, los atributos XLSX desconocidos y el directorio de vínculos externos siguen disponibles después de la conversión y del round trip
  • Las definiciones mal formadas y no admitidas permanecen preservadas byte a byte o como texto cuando es posible, y agregan diagnósticos xlsDiagnosticDefinedNameConversionSkipped en lugar de adivinarse
  • Las fórmulas dependientes se recalculan al valor de error correspondiente de Excel, mientras que un resultado en caché válido para una fórmula externa directa ordinaria sigue disponible si su libro activo se desconecta más adelante
  • La operación es específica de Excel y no reinterpreta la semántica de nombres con fórmula de OpenDocument

Referencias externas XLS clásico

En los libros XLS clásicos, los vínculos externos se almacenan en el bloque de directorio global mediante registros EXTERNALBOOK y EXTERNNAME; HotXLS mantiene estos directorios durante los ciclos de lectura/escritura del archivo, asegurando que las referencias de rango remotas sobrevivan a los bucles de modificación

Relaciones externas XLSX

Para los libros OOXML, la asignación de vínculos externos se gestiona mediante partes de relación; consulte los detalles de las interfaces de apoyo a continuación

Copyright © 2010-2026 losLab Software