Programar personalizaciones de nivel de documento

Artículo
02/19/2013

Si extiende Microsoft Office Word o Microsoft Office Excel con una personalización de nivel de documento, puede realizar las tareas siguientes:

Automatizar la aplicación mediante su modelo de objetos.
Agregar controles a la superficie del documento.
Llamar a código de Visual Basic para Aplicaciones (VBA) en el documento desde el ensamblado de personalización.
Llamar a código del ensamblado de personalización desde VBA.
Administrar ciertos aspectos del documento mientras está en un servidor que no tiene Microsoft Office instalado.
Personalizar la interfaz de usuario de la aplicación.

Se aplica a: La información de este tema se aplica a los proyectos de nivel de documento para las siguientes aplicaciones: Excel 2013 y Excel 2010; Word 2013 y Word 2010. Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto de Office.

Algunos aspectos a la hora de escribir código en proyectos de nivel de documento son diferentes con respecto a otros tipos de proyectos en Visual Studio.Muchas de estas diferencias se deben a la manera en que se exponen los modelos de objetos de Office en el código administrado.Para obtener más información, vea Escribir código en soluciones de Office.

Para obtener información general sobre las personalizaciones de nivel de documento y otros tipos de soluciones que se pueden crear mediante las herramientas de desarrollo de Office en Visual Studio, vea Información general sobre el desarrollo de soluciones de Office.

Utilizar las clases generadas en proyectos de nivel de documento

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

En proyectos de nivel de documento para Word, la clase se denomina de forma predeterminada ThisDocument.
En proyectos de nivel de documento para Excel se generan varias clases: una para el propio libro y una para cada hoja de cálculo.De forma predeterminada, estas clases tienen los nombres siguientes:
- ThisWorkbook
- Sheet1
- Sheet2
- Sheet3

La clase generada incluye controladores de eventos a los que se llama cuando el documento se abre o se cierra.Para ejecutar código al abrir el documento, agregue código al controlador de eventos Startup.Para ejecutar código justo antes de que se cierre el documento, agregue código al controlador de eventos Shutdown.Para obtener más información, vea Eventos de los proyectos de Office.

Introducción al diseño de las clases generadas

En proyectos destinados .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 ellas.En su lugar, las clases generadas derivan la mayoría de sus miembros de las siguientes clases base:

ThisDocument: deriva de Microsoft.Office.Tools.Word.DocumentBase.
ThisWorkbook: deriva de Microsoft.Office.Tools.Excel.WorkbookBase.
Sheetn: deriva de Microsoft.Office.Tools.Excel.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 de Protect de la clase de ThisDocument, la clase de Microsoft.Office.Tools.Word.DocumentBase redirige esta llamada a la implementación interna de la interfaz de Microsoft.Office.Tools.Word.Document en Runtime de Microsoft Visual Studio Tools para Office.

Tener acceso al modelo de objetos de la aplicación host

Para tener acceso al modelo de objetos de la aplicación host, utilice miembros de la clase generada en el proyecto.Cada una de estas clases corresponde a un objeto del modelo de objetos de Excel o 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 para Word proporciona en su mayoría los mismos miembros que el objeto Microsoft.Office.Interop.Word.Document del modelo de objetos de Word.

En el ejemplo de código siguiente se muestra cómo utilizar el modelo de objetos de Word para guardar el documento que forma parte de una personalización en el nivel de documento para Word.Este ejemplo está diseñado para su ejecución desde la clase ThisDocument.

Me.Save()

this.Save();

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

Globals.ThisDocument.Save()

Globals.ThisDocument.Save();

Dado que la clase ThisDocument obtiene la mayoría de sus miembros del elemento host Microsoft.Office.Tools.Word.Document, el método Save al que se llama en este código es de hecho el método Save del elemento host Microsoft.Office.Tools.Word.Document.Este método corresponde al método Save del objeto Microsoft.Office.Interop.Word.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, vea Información general acerca del modelo de objetos de Word y Información general sobre el modelo de objetos de Excel.

Para obtener más información acerca del objeto Globals, vea Acceso global a objetos en los proyectos de Office.

Agregar controles a documentos

Para personalizar la interfaz de usuario del documento, puede agregar controles de formularios 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 datos, recopilar información del usuario y responder a 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 Microsoft.Office.Tools.Excel.ListObject proporciona toda la funcionalidad de Microsoft.Office.Interop.Excel.ListObject en Excel.Sin embargo, el control host Microsoft.Office.Tools.Excel.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 y Información general sobre controles de formularios Windows Forms en documentos de Office.

Combinar personalizaciones de VBA y de nivel de documento

Puede utilizar código de VBA en un documento que forma parte de una personalización de nivel de documento.Puede llamar a código de VBA del documento desde el ensamblado de personalización y también puede configurar el proyecto para permitir que código de VBA del documento llame a código del ensamblado de personalización.

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

Administrar documentos en un servidor

Puede administrar diferentes aspectos de las personalizaciones de nivel de documento en un servidor que no tiene Microsoft Office Word o Microsoft Office Excel instalado.Por ejemplo, puede obtener acceso y modificar los datos en la caché de datos del documento.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 éste ya no ejecute el código, o bien puede asociar mediante programación un ensamblado a un documento.

Para obtener más información, vea Administrar documentos en un servidor mediante la clase ServerDocument.

Personalizar la interfaz de usuario de aplicaciones de Microsoft Office

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

Agregar controles host o controles de formularios Windows Forms a la superficie del documento.

Para obtener más información, vea Automatizar Word con objetos extendidos, Automatizar Excel usando objetos extendidos y Información general sobre controles de formularios Windows Forms en documentos de Office.
Agregar un panel de acciones al documento.

Para obtener más información, vea Información general sobre paneles de acciones.
Agregar pestañas personalizadas a la cinta de opciones.

Para obtener más información, vea Información general sobre la cinta de opciones.
Agregar grupos personalizados a una ficha integrada en la cinta de opciones.

Para obtener más información, vea Cómo: Personalizar una pestaña integrada.

Para obtener más información sobre cómo personalizar la interfaz de usuario de las aplicaciones de Microsoft Office, vea Personalización de la interfaz de usuario de Office.

Obtener 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 su personalización en el nivel del documento provocó el evento.Por ejemplo, en una personalización de nivel de documento para Excel, le podría interesar ejecutar código cuando el usuario activa una de las hoja de cálculo en la libro personalizado, pero no cuando el usuario activa una hoja de cálculo en algún otro libro que está abierto al mismo tiempo.

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

Descripción de los métodos GetVstoObject y HasVstoObject

Para probar un objeto de Office nativo, utilice los métodos GetVstoObject y HasVstoObject en el proyecto:

Utilice 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.
Utilice el método GetVstoObject si desea obtener el objeto extendido para un objeto de Office nativo.Este método devuelve un objeto Microsoft.Office.Tools.Excel.ListObject, Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet o Microsoft.Office.Tools.Word.Document si el objeto de Office nativo especificado tiene uno.De lo contrario, GetVstoObject devuelve null.Por ejemplo, el método GetVstoObject devuelve un documento Microsoft.Office.Tools.Word.Document si el documento Microsoft.Office.Interop.Word.Document especificado es el objeto subyacente del documento en el proyecto de documento de Word.

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

Utilizar los métodos HasVstoObject y GetVstoObject

Para llamar al método de HasVstoObject y de GetVstoObject, use el método de Globals.Factory.GetVstoObject o de Globals.Factory.HasVstoObject, y pase el objeto de word o excel nativo (como Microsoft.Office.Interop.Word.Document o Microsoft.Office.Interop.Excel.Worksheet) que desea probar.