Cargando documentos con LoadOptions

Esta guía muestra cómo controlar la carga de documentos más allá de una ruta de archivo o flujo simple, usando la clase LoadOptions. Document tiene sobrecargas de constructor que aceptan una instancia de LoadOptions — Document(fileName, loadOptions) y Document(stream, loadOptions) — de modo que cualquiera de los ajustes descritos aquí se aplique en el momento de la carga, antes de que el objeto documento sea devuelto a su código.

La clase LoadOptions

LoadOptions lleva los ajustes Aspose.Words que FOSS necesita al cargar un documento en un objeto Document. Sus constructores incluyen un LoadOptions() sin parámetros, LoadOptions(password) para abrir directamente un archivo protegido con contraseña, y LoadOptions(loadFormat, password, baseUri) para especificar el formato explícitamente. Más allá de Password y BaseUri (utilizados para resolver referencias relativas como recursos enlazados), LoadOptions expone Encoding para formatos basados en texto, TempFolder para el procesamiento de documentos grandes, MswVersion para especificar qué convenciones de formato de la versión de Word se aplican, y UpdateDirtyFields, IgnoreOleData y UseSystemLcid para un control más fino del comportamiento de carga. LoadOptions.FontSettings le permite suministrar FontSettings en el momento de la carga en lugar de configurar fuentes solo después de que el documento se haya cargado.

Opciones de carga específicas del formato

Algunos formatos tienen su propia subclase LoadOptions que expone ajustes específicos para ese formato. TxtLoadOptions (para texto sin formato) añade AutoNumberingDetection, DetectNumberingWithWhitespaces, DetectHyperlinks, DocumentDirection, y LeadingSpacesOptions/TrailingSpacesOptions separados de tipo TxtLeadingSpacesOptions/TxtTrailingSpacesOptions para controlar cómo se maneja el espacio en blanco inicial y final en cada línea. MarkdownLoadOptions añade PreserveEmptyLines, ImportUnderlineFormatting y SoftLineBreakCharacter para controlar cómo las convenciones de salto de línea de Markdown se mapean a los párrafos y ejecuciones del documento. Ambas subclases heredan cada propiedad general LoadOptions, de modo que una contraseña o una devolución de llamada de carga de recursos establecida en una instancia TxtLoadOptions o MarkdownLoadOptions se comporta igual que en la clase base.

Devoluciones de llamada de carga de recursos

LoadOptions.ResourceLoadingCallback acepta una implementación de IResourceLoadingCallback, la cual es notificada a medida que el cargador resuelve recursos externos referenciados por el documento que se está cargando. La devolución de llamada recibe un ResourceLoadingArgs que describe el ResourceType del recurso que se está cargando, y devuelve un ResourceLoadingAction para indicar al cargador si debe cargar el recurso normalmente, omitirlo o sustituir datos personalizados. Este es el punto de extensión para controlar o interceptar la resolución de recursos durante la carga, independientemente del formato que se esté leyendo.

Configuración de idioma, dirección y recuperación

LoadOptions.LanguagePreferences es un objeto LanguagePreferences cuyo DefaultEditingLanguage (un valor de enumeración EditingLanguage) establece el idioma Aspose.Words que FOSS asume cuando un documento no especifica uno explícitamente; AddEditingLanguage(language) y AddEditingLanguages(languages) registran idiomas adicionales que el documento puede usar. DocumentDirection (también expuesto directamente en TxtLoadOptions) es una enumeración con valores LeftToRight, RightToLeft y Auto para controlar la dirección del flujo de texto al cargar. LoadOptions.RecoveryMode recibe un valor DocumentRecoveryMode, que controla cómo responde el cargador cuando encuentra un documento malformado o parcialmente corrupto.

Callbacks de progreso y advertencia

Más allá de la carga de recursos, LoadOptions.WarningCallback y LoadOptions.ProgressCallback aceptan implementaciones de callbacks que son notificadas de problemas no fatales encontrados durante la carga y del progreso de la carga, respectivamente — útiles para exponer problemas recuperables al código llamador o informar del progreso en documentos grandes sin necesidad de sondear.

Consejos y mejores prácticas

Pase LoadOptions(password) (o establezca LoadOptions.Password) en lugar de capturar una excepción de carga y volver a intentar — Aspose.Words FOSS necesita la contraseña antes de poder analizar el documento.
Establezca LanguagePreferences.DefaultEditingLanguage al cargar documentos cuyo metadato de idioma falta o es poco fiable, de modo que el procesamiento posterior dependiente del idioma se comporte de forma predecible.
Prefiere la clase de opciones específicas del formato (TxtLoadOptions, MarkdownLoadOptions) sobre la LoadOptions base al cargar esos formatos, ya que la subclase específica expone configuraciones relevantes al formato que la clase base no tiene.
Implementa IResourceLoadingCallback cuando necesites redirigir, almacenar en caché o bloquear la resolución de recursos externos durante la carga en lugar de hacerlo después de que el documento ya esté en memoria.
Establece LoadOptions.RecoveryMode deliberadamente para canalizaciones que procesan documentos de fuentes no confiables o de terceros, en lugar de depender del comportamiento de recuperación predeterminado.

Problemas comunes

Problema	Causa	Corrección
Cargar un documento protegido con contraseña lanza una excepción	No se proporcionó una contraseña, o se proporcionó después de que la carga ya había comenzado	Pase `LoadOptions(password)` (o establezca `Password` en una instancia de `LoadOptions`) al sobrecarga del constructor `Document` que acepta `LoadOptions`
Los espacios en blanco al inicio o al final de un archivo de texto cargado no se manejan como se esperaba	El comportamiento predeterminado de `TxtLeadingSpacesOptions`/`TxtTrailingSpacesOptions` no coincide con las convenciones de espacios en blanco del archivo fuente	Establecer `TxtLoadOptions.LeadingSpacesOptions` / `TrailingSpacesOptions` explícitamente
Los saltos de línea de Markdown no se corresponden con la estructura de párrafo esperada	`MarkdownLoadOptions.PreserveEmptyLines` o `SoftLineBreakCharacter` no coincide con las convenciones del Markdown de origen	Ajusta la propiedad `MarkdownLoadOptions` relevante antes de cargar
La carga de recursos externos no se observa ni es controlable	No se registró ningún `IResourceLoadingCallback` en `LoadOptions.ResourceLoadingCallback`	Implementa `IResourceLoadingCallback` y asígnalo antes de cargar

FAQ

¿Cómo cargo un documento protegido con contraseña?

Construye LoadOptions con la contraseña — new LoadOptions(password) — o establece LoadOptions.Password, luego pásalo a new Document(fileName, loadOptions) o new Document(stream, loadOptions).

¿Necesito una subclase `LoadOptions` específica del formato, o basta con la clase base?

La clase base LoadOptions cubre configuraciones comunes a todos los formatos (contraseña, codificación, callbacks). Utilice una subclase específica del formato como TxtLoadOptions o MarkdownLoadOptions cuando necesite configuraciones específicas de ese formato, como el manejo de espacios en blanco para archivos de texto o convenciones de salto de línea para Markdown.

¿Cómo intercepto o redirijo los recursos que un documento referencia durante la carga?

Implemente IResourceLoadingCallback y asígnelo a LoadOptions.ResourceLoadingCallback antes de cargar. El callback recibe un ResourceLoadingArgs por recurso y devuelve un ResourceLoadingAction que decide cómo continúa el cargador.

¿Cómo controlo qué idioma asume Aspose.Words FOSS para un documento cargado?

Establezca LoadOptions.LanguagePreferences.DefaultEditingLanguage a un valor EditingLanguage antes de cargar; use AddEditingLanguage/AddEditingLanguages para registrar idiomas adicionales que el documento pueda contener.

¿Qué ocurre si el cargador encuentra un documento malformado?

El comportamiento está controlado por LoadOptions.RecoveryMode, un valor DocumentRecoveryMode que determina cómo responde el cargador a los problemas estructurales en el documento fuente.

API Reference Resumen

Clase/Método	Descripción
`LoadOptions`	Objeto de opciones base que controla cómo se carga un documento
`Document(fileName, loadOptions)` / `Document(stream, loadOptions)`	Sobrecargas del constructor que aplican `LoadOptions` durante la carga
`TxtLoadOptions`	Opciones de carga específicas para documentos de texto plano
`MarkdownLoadOptions`	Opciones de carga específicas para documentos Markdown
`IResourceLoadingCallback`	Interfaz de devolución de llamada para interceptar la resolución de recursos externos durante la carga
`ResourceLoadingArgs` / `ResourceLoadingAction`	Datos del evento por recurso y la acción devuelta al cargador
`LanguagePreferences`	Configura los idiomas de edición predeterminados y adicionales que se asumen al cargar
`DocumentDirection`	Enum que controla la dirección del flujo de texto (`LeftToRight`, `RightToLeft`, `Auto`)
`DocumentRecoveryMode`	Controla el comportamiento del cargador cuando un documento está malformado

Ver también

Aspose.Words for .NET — Enterprise Documentation

Cargando documentos con LoadOptions