Compartir a través de

Programar personalizaciones de nivel de documento

  • Artículo

Al ampliar Microsoft Office Word o Microsoft Office Excel mediante una personalización de nivel de documento, puede realizar las siguientes tareas:

  • Automatizar la aplicación mediante su modelo de objetos.

  • Agregar controles en la superficie del documento.

  • Llamar al código de Visual Basic para aplicaciones (VBA) en el documento desde el ensamblado de personalización.

  • Llamar al código en el ensamblado de personalización desde VBA.

  • Administrar determinados aspectos del documento mientras se encuentra en un servidor que no tiene instalado Microsoft Office.

  • Personalizar la interfaz de usuario (UI) de la aplicación.

    Aplicación: la información de este tema se aplica a los proyectos de nivel de documento de Excel y Word. Para obtener más información, consulte Características disponibles por aplicación y tipo de proyecto de Office.

    Algunos aspectos de la escritura de código en proyectos de nivel de documento difieren de otros tipos de proyectos de Visual Studio. Muchas de estas diferencias se deben a la forma en que los modelos de objetos de Office se exponen al código administrado. Para obtener más información, consulte Escritura de código en soluciones de Office.

    Para obtener información general sobre las personalizaciones de nivel de documento y otros tipos de soluciones que puede crear mediante las herramientas de desarrollo de Office en Visual Studio, consulte Información general sobre el desarrollo de soluciones de Office (VSTO).

Uso de clases generadas en proyectos de nivel de documento

Cuando crea un proyecto de nivel de documento, Visual Studio crea automáticamente una clase en el proyecto que puede usar para comenzar a escribir el código. Visual Studio crea diferentes clases para Word y Excel:

  • En los proyectos de nivel de documento de Word, la clase se denomina ThisDocument de forma predeterminada.

  • En cambio, los proyectos de nivel de documento de Excel tienen creadas varias clases: una para el propio libro y una para cada hoja de cálculo. Estas clases se denominan de la siguiente manera, de forma predeterminada:

    • ThisWorkbook

    • Sheet1

    • Sheet2

    • Sheet3

    La clase creada incluye controladores de eventos a los que se llama cuando el documento está abierto o cerrado. Para ejecutar el código cuando se abre el documento, agregue ese código al controlador de eventos Startup . Para ejecutar el código justo antes de cerrar el documento, agregue ese código al controlador de eventos Shutdown . Para obtener más información, consulte Events in Office Projects.

Información acerca del diseño de las clases generadas

En los proyectos destinados a .NET Framework 4 o .NET Framework 4.5, los tipos de elementos host del Runtime de Microsoft Visual Studio Tools para Office son interfaces, por lo que las clases generadas no pueden derivar su implementación de ellos. En su lugar, las clases creadas derivan la mayoría de sus miembros de las siguientes clases base:

  • ThisDocument: deriva de DocumentBase.

  • ThisWorkbook: deriva de WorkbookBase.

  • Sheet n: se deriva de WorksheetBase.

    Estas clases base redirigen todas las llamadas realizadas a sus miembros, a las implementaciones internas de las correspondientes interfaces de elementos host del Runtime de Microsoft Visual Studio Tools para Office. Por ejemplo, si llama al método Protect de la clase ThisDocument, la clase DocumentBase redirige esta llamada a la implementación interna de la interfaz de Document en el Runtime de Microsoft Visual Studio Tools para Office.

Acceso al modelo de objetos de la aplicación host

Para obtener acceso al modelo de objetos de la aplicación host, use los miembros de la clase generada en el proyecto. Cada una de esas clases corresponde a un objeto del modelo de objetos de Excel o de Word y contiene en su mayoría las mismas propiedades, métodos y eventos. Por ejemplo, la clase ThisDocument de un proyecto de nivel de documento de Word proporciona en su mayoría los mismos miembros que el objeto Document del modelo de objetos de Word.

En el ejemplo de código siguiente se muestra cómo usar el modelo de objetos de Word para guardar el documento que forma parte de una personalización de nivel de documento de Word. Este ejemplo está pensado para ejecutarse desde la clase ThisDocument .

this.Save();

Para hacer lo mismo desde fuera de la clase ThisDocument , use el objeto Globals para tener acceso a la clase ThisDocument . Por ejemplo, puede agregar este código a un archivo de código del panel de acciones si desea incluir el botón Guardar en la interfaz de usuario del panel de acciones.

Globals.ThisDocument.Save();

Dado que la clase ThisDocument obtiene la mayoría de sus miembros del elemento host Document , el método Save al que se llama en este código es de hecho el método Save del elemento host Document . Este método corresponde al método Save del objeto Document en el modelo de objetos de Word.

Para obtener más información acerca del uso de los modelos de objetos de Word y Excel, consulte Información general sobre el modelo de objetos de Word e Información general sobre el modelo de objetos de Excel.

Para obtener más información sobre el objeto Globals, consulte Acceso global a objetos en proyectos de Office.

Adición de controles a documentos

Para personalizar la interfaz de usuario del documento, puede agregar controles de Windows Forms o controles host a la superficie del documento. Si combina diferentes conjuntos de controles y escribe código, puede enlazar los controles a los datos, recopilar información del usuario y responder a las acciones del usuario.

Los controles host son clases que extienden algunos de los objetos de los modelos de objetos de Word y Excel. Por ejemplo, el control host ListObject proporciona toda la funcionalidad del elemento ListObject en Excel. Sin embargo, el control host ListObject también tiene eventos adicionales y funciones de enlace de datos.

Para obtener más información, consulte Información general sobre elementos y controles Host e Información general sobre controles de Windows Forms en documentos de Office.

Combinación de personalizaciones de VBA y de nivel de documento

Puede usar código de VBA en un documento que forma parte de una personalización de nivel de documento Asimismo, también puede llamar al código VBA del documento desde el ensamblado de personalización, y configurar el proyecto de modo que permita que el código VBA del documento llame al código del ensamblado de personalización.

Para obtener más información, consulte Combinación de personalizaciones de VBA y de nivel de documento.

Administración de documentos en un servidor

Puede administrar diferentes aspectos de las personalizaciones de nivel de documento en un servidor que no tenga Microsoft Office Word o Microsoft Office Excel instalado. Por ejemplo, puede obtener acceso y modificar los datos en la caché de datos del documento. Asimismo, también puede administrar el ensamblado de personalización asociado al documento. Por ejemplo, puede quitar mediante programación el ensamblado del documento para que este no ejecute el código, o bien puede asociar mediante programación un ensamblado a un documento.

Para obtener más información, consulte Administración de documentos en un servidor mediante la clase ServerDocuments.

Personalización de la interfaz de usuario de las aplicaciones de Microsoft Office

Puede personalizar la interfaz de usuario de Word y Excel de las siguientes maneras, mediante una personalización de nivel de documento:

Obtención de objetos extendidos de los objetos de Office nativos en personalizaciones de nivel de documento

Muchos controladores de eventos de Office reciben un objeto de Office nativo que representa el libro, la hoja de cálculo o el documento que provocó el evento. En algunos casos, le puede interesar ejecutar cierto código, solo si el libro o el documento de la personalización de nivel del documento provocó el evento. Por ejemplo, en una personalización de nivel de documento de Excel, le podría interesar ejecutar el código cuando el usuario activa una de las hojas de cálculo del libro personalizado, pero no cuando el usuario activa una hoja de cálculo en algún otro libro que esté abierto al mismo tiempo que el primero.

Si tiene un objeto de Office nativo, puede probar si ese objeto se ha extendido en un elemento host o en un control host de una personalización de nivel de documento. Los elementos y controles host son tipos proporcionados por el Runtime de Visual Studio Tools para Office que agregan funcionalidad a los objetos ya existentes de forma nativa en los modelos de objetos de Word o Excel (denominados objetos nativos de Office). En conjunto, los elementos host y los controles host también se denominan objetos extendidos. Para obtener más información sobre los elementos y controles host, consulte Información general sobre elementos y controles host.

Información acerca de los métodos GetVstoObject y HasVstoObject

Para probar un objeto de Office nativo, use los métodos HasVstoObject y GetVstoObject del proyecto:

  • Use el método HasVstoObject si desea determinar si el objeto de Office nativo tiene un objeto extendido en la personalización. Este método devuelve true si el objeto de Office nativo tiene un objeto extendido, y false si no lo tiene.

  • Use el método GetVstoObject si desea obtener el objeto extendido de un objeto de Office nativo. Este método devuelve un objeto ListObject, Workbook, Worksheeto Document si el objeto de Office nativo especificado tiene uno. En caso contrario, GetVstoObject devuelve null. Por ejemplo, el método GetVstoObject devuelve un Document si el Document especificado es el objeto subyacente del documento que se encuentra en el proyecto de documento de Word.

    En los proyectos de nivel de documento, no se puede utilizar el método GetVstoObject para crear un nuevo elemento host Workbook, Worksheet o Document en tiempo de ejecución. Solo puede usar este método para tener acceso a los elementos host existentes creados en el proyecto en tiempo de diseño. Si desea crear nuevos elementos host en tiempo de ejecución, debe desarrollar un proyecto de complemento VSTO. Para obtener más información, consulte Limitaciones de programación de elementos y controles host y Extensión de documentos de Word y libros de Excel en complementos de VSTO en tiempo de ejecución.

Uso de los métodos GetVstoObject y HasVstoObject

Para llamar al método HasVstoObject y GetVstoObject, use el método Globals.Factory.GetVstoObject o Globals.Factory.HasVstoObject y pase el objeto nativo de Word o Excel (por ejemplo, Document o Worksheet) que desea probar.

Contenido relacionado