Programar personalizaciones de nivel de documentoProgram document-level customizations

Al ampliar Microsoft Office Word o Microsoft Office Excel mediante una personalización de nivel de documento, puede realizar las siguientes tareas:When you extend Microsoft Office Word or Microsoft Office Excel by using a document-level customization, you can perform the following tasks:

  • Automatizar la aplicación mediante su modelo de objetos.Automate the application by using its object model.

  • Agregar controles en la superficie del documento.Add controls to the surface of the document.

  • Llamar al código de Visual Basic para aplicaciones (VBA) en el documento desde el ensamblado de personalización.Call Visual Basic for Applications (VBA) code in the document from the customization assembly.

  • Llamar al código en el ensamblado de personalización desde VBA.Call code in the customization assembly from VBA.

  • Administrar determinados aspectos del documento mientras se encuentra en un servidor que no tiene instalado Microsoft Office.Manage certain aspects of the document while it is on a server that does not have Microsoft Office installed.

  • Personalizar la interfaz de usuario (UI) de la aplicación.Customize the user interface (UI) of the application.

    Aplicación: la información de este tema se aplica a los proyectos de nivel de documento de Excel y Word.Applies to: The information in this topic applies to document-level projects for Excel and Word. Para obtener más información, consulte características disponibles por tipo de aplicación y el proyecto de Office.For more information, see Features available by Office application and project type.

    Algunos aspectos de la escritura de código en proyectos de nivel de documento difieren de otros tipos de proyectos de Visual Studio.Some aspects of writing code in document-level projects are different from other types of projects in 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.Many of these differences are caused by the way the Office object models are exposed to managed code. Para obtener más información, consulte escribir código en soluciones de Office.For more information, see Write code in Office solutions.

    Para obtener información general sobre las personalizaciones de nivel de documento y otros tipos de soluciones que puede crear mediante el uso de las herramientas de desarrollo de Office en Visual Studio, consulte información general sobre el desarrollo de soluciones de Office (VSTO).For general information about document-level customizations and other types of solutions you can create by using the Office development tools in Visual Studio, see Office solutions development overview (VSTO).

Usar las clases generadas en proyectos de nivel de documentoUse the generated classes in document-level projects

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.When you create a document-level project, Visual Studio automatically generates a class in the project that you can use to start writing your code. Visual Studio crea diferentes clases para Word y Excel:Visual Studio generates different classes for Word and Excel:

  • En los proyectos de nivel de documento de Word, la clase se denomina ThisDocument de forma predeterminada.In document-level projects for Word, the class is called ThisDocument by default.

  • 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.Document-level projects for Excel have multiple generated classes: one for the workbook itself, and one for each worksheet. Estas clases se denominan de la siguiente manera, de forma predeterminada:By default, these classes have the following names:

    • ThisWorkbook

    • Sheet1

    • Sheet2

    • Sheet3

    La clase creada incluye controladores de eventos a los que se llama cuando el documento está abierto o cerrado.The generated class includes event handlers that are called when the document is opened or closed. Para ejecutar el código cuando se abre el documento, agregue ese código al controlador de eventos Startup .To run code when the document is opened, add code to the Startup event handler. Para ejecutar el código justo antes de cerrar el documento, agregue ese código al controlador de eventos Shutdown .To run code just before the document is closed, add code to the Shutdown event handler. Para obtener más información, consulte eventos en proyectos de Office.For more information, see Events in Office projects.

Entender el diseño de las clases generadasUnderstand the design of the generated classes

En aquellos proyectos que tienen como destino .NET Framework 4.NET Framework 4 o .NET Framework 4.5.NET Framework 4.5, los tipos de elementos host que se encuentran en Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime son interfaces, por lo que las clases creadas no pueden derivar su implementación de ellas.In projects that target the .NET Framework 4.NET Framework 4 or the .NET Framework 4.5.NET Framework 4.5, the host item types in the Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime are interfaces, so the generated classes cannot derive their implementation from them. En su lugar, las clases creadas derivan la mayoría de sus miembros de las siguientes clases base:Instead, the generated classes derive most of their members from the following base classes:

  • ThisDocument: deriva de DocumentBase.ThisDocument: derives from DocumentBase.

  • ThisWorkbook: deriva de WorkbookBase.ThisWorkbook: derives from WorkbookBase.

  • Sheet n: se deriva de WorksheetBase.Sheet n: derives from 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 OfficeVisual Studio Tools for Office runtime.These base classes redirect all calls to their members to internal implementations of the corresponding host item interfaces in the Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime. 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 Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime.For example, if you call the Protect method of the ThisDocument class, the DocumentBase class redirects this call to the internal implementation of the Document interface in the Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime.

Obtener acceso al modelo de objeto de la aplicación hostAccess the object model of the host application

Para obtener acceso al modelo de objetos de la aplicación host, use los miembros de la clase generada en el proyecto.To access the object model of the host application, use members of the generated class in your project. 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.Each of these classes corresponds to an object in the object model of Excel or Word, and they contain most of the same properties, methods, and events. 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.For example, the ThisDocument class in a document-level project for Word provides most of the same members as the Document object in the Word object model.

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. The following code example shows how to use the Word object model to save the document that is part of a document-level customization for Word. Este ejemplo está pensado para ejecutarse desde la clase ThisDocument .This example is intended to be run from the ThisDocument class.

Me.Save()  
this.Save();  

Para hacer lo mismo desde fuera de la clase ThisDocument , use el objeto Globals para tener acceso a la clase ThisDocument .To do the same thing from outside the ThisDocument class, use the Globals object to access the ThisDocument class. 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.For example, you can add this code to an actions pane code file if you want to include a Save button in the actions pane UI.

Globals.ThisDocument.Save()  
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 .Because the ThisDocument class obtains most of its members from the Document host item, the Save method that is called in this code is really the Save method of the Document host item. Este método corresponde al método Save del objeto Document en el modelo de objetos de Word.This method corresponds to the Save method of the Document object in the Word object model.

Para obtener más información sobre el uso de los modelos de objetos de Word y Excel, vea información general sobre el modelo de objetos de Word y información general sobre el modelo de objetos de Excel.For more information about using the object models of Word and Excel, see Word object model overview and Excel object model overview.

Para obtener más información sobre la Globals de objetos, consulte acceso Global a objetos en los proyectos de Office.For more information about the Globals object, see Global access to objects in Office projects.

Agregar controles a documentosAdd controls to documents

Para personalizar la interfaz de usuario del documento, puede agregar controles de Windows Forms o controles host a la superficie del documento.To customize the UI of the document, you can add Windows Forms controls or host controls to the document surface. 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.By combining different sets of controls and writing code, you can bind the controls to data, collect information from the user, and respond to user actions.

Los controles host son clases que extienden algunos de los objetos de los modelos de objetos de Word y Excel.Host controls are classes that extend some of the objects in the Word and Excel object model. Por ejemplo, el control host ListObject proporciona toda la funcionalidad del elemento ListObject en Excel.For example, the ListObject host control provides all of the functionality of the ListObject in Excel. Sin embargo, el control host ListObject también tiene eventos adicionales y funciones de enlace de datos.However, the ListObject host control also has additional events and data binding capabilities.

Para obtener más información, consulte elementos Host y hospedar información general sobre controles y controles de información general sobre documentos de Office de formularios de Windows forms.For more information, see Host items and host controls overview and Windows forms controls on Office documents overview.

Combinar VBA y personalizaciones de nivel de documentoCombine VBA and document-level customizations

Puede usar código de VBA en un documento que forma parte de una personalización de nivel de documentoYou can use VBA code in a document that is part of a document-level customization. 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.You can call VBA code in the document from the customization assembly, and you can also configure your project to enable VBA code in the document to call code in the customization assembly.

Para obtener más información, consulte combinar VBA y personalizaciones de nivel de documento.For more information, see Combine VBA and document-level customizations.

Administrar documentos en un servidorManage documents on a server

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.You can manage several different aspects of document-level customizations on a server that does not have Microsoft Office Word or Microsoft Office Excel installed. Por ejemplo, puede obtener acceso y modificar los datos en la caché de datos del documento.For example, you can access and modify data in the data cache of the document. Asimismo, también puede administrar el ensamblado de personalización asociado al documento.You can also manage the customization assembly that is associated with the document. 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.For example, you can programmatically remove the assembly from the document so that the document no longer runs your code, or you can programmatically attach an assembly to a document.

Para obtener más información, consulte administrar documentos en un servidor mediante la clase ServerDocument.For more information, see Manage documents on a server by using the ServerDocument class.

Personalizar la interfaz de usuario de aplicaciones de Microsoft OfficeCustomize the user interface of Microsoft Office applications

Puede personalizar la interfaz de usuario de Word y Excel de las siguientes maneras, mediante una personalización de nivel de documento:You can customize the UI of Word and Excel in the following ways by using a document-level customization:

Obtener objetos extendidos de objetos de Office nativos en personalizaciones de nivel de documentoGet extended objects from native Office objects in document-level customizations

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.Many event handlers for Office events receive a native Office object that represents the workbook, worksheet, or document that raised the event. 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.In some cases, you might want to run some code only if the workbook or document in your document-level customization raised the event. 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.For example, in a document-level customization for Excel, you might want to run some code when the user activates one of the worksheets in the customized workbook, but not when the user activates a worksheet in some other workbook that happens to be open at the same time.

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.When you have a native Office object, you can test whether that object has been extended into a host item or host control in a document-level customization. Los elementos host y los controles host son tipos que proporciona Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime , y que agregan funcionalidad a los objetos que existen de forma nativa en los modelos de objetos de Excel o Word (denominados objetos de Office nativos).Host items and host controls are types provided by the Runtime de Microsoft Visual Studio Tools para OfficeVisual Studio Tools for Office runtime that add functionality to objects that exist natively in the Word or Excel object models (called native Office objects). En conjunto, los elementos host y los controles host también se denominan objetos extendidos.Collectively, host items and host controls are also called extended objects. Para obtener más información acerca de los elementos host y controles host, consulte elementos Host y hospedar información general sobre controles.For more information about host items and host controls, see Host items and host controls overview.

Comprender los métodos HasVstoObject y GetVstoObjectUnderstand the GetVstoObject and HasVstoObject methods

Para probar un objeto de Office nativo, use los métodos HasVstoObject y GetVstoObject del proyecto:To test a native Office object, use the HasVstoObject and GetVstoObject methods in your project:

  • Use el método HasVstoObject si desea determinar si el objeto de Office nativo tiene un objeto extendido en la personalización.Use the HasVstoObject method if you want to determine whether the native Office object has an extended object in your customization. Este método devuelve true si el objeto de Office nativo tiene un objeto extendido, y false si no lo tiene.This method returns true if the native Office object has an extended object, and false otherwise.

  • Use el método GetVstoObject si desea obtener el objeto extendido de un objeto de Office nativo.Use the GetVstoObject method if you want to get the extended object for a native Office object. Este método devuelve un objeto ListObject, Workbook, Worksheeto Document si el objeto de Office nativo especificado tiene uno.This method returns a ListObject, Workbook, Worksheet, or Document object if the specified native Office object has one. En caso contrario, GetVstoObject devuelve null.Otherwise, GetVstoObject returns 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.For example, the GetVstoObject method returns a Document if the specified Document is the underlying object for the document in your Word document project.

    En los proyectos de nivel de documento, no puede usar el GetVstoObject método para crear un nuevo Workbook, Worksheet, o Document elemento host en tiempo de ejecución.In document-level projects, you cannot use the GetVstoObject method to create a new Workbook, Worksheet, or Document host item at runtime. Solo puede usar este método para tener acceso a los elementos host existentes creados en el proyecto en tiempo de diseño.You can use this method only to access existing host items that are generated in your project at design time. Si desea crear nuevos elementos host en tiempo de ejecución, debe desarrollar un proyecto de complemento VSTO.If you want to create new host items at runtime, you must develop a VSTO Add-in project. Para obtener más información, consulte limitaciones de programación de elementos host y controles host y documentos ampliar Word y libros de Excel en complementos VSTO en tiempo de ejecución.For more information, see Programmatic limitations of host items and host controls and Extend Word documents and Excel workbooks in VSTO Add-ins at runtime.

Utilice los métodos HasVstoObject y GetVstoObjectUse the GetVstoObject and HasVstoObject methods

Para llamar a la HasVstoObject y GetVstoObject método, use el Globals.Factory.GetVstoObject o Globals.Factory.HasVstoObject método y pase el objeto nativo de Word o Excel (como un Document o Worksheet) que va a probar.To call the HasVstoObject and GetVstoObject method, use the Globals.Factory.GetVstoObject or Globals.Factory.HasVstoObject method, and pass in the native Word or Excel object (such as a Document or Worksheet) that you want to test.

Vea tambiénSee also

Controles en documentos de Office Controls on Office documents
Combinar VBA y personalizaciones de nivel de documento Combine VBA and document-level customizations
Administrar documentos en un servidor mediante la clase ServerDocument Manage documents on a server by using the ServerDocument class
Escribir código en soluciones de OfficeWrite code in Office solutions