Ampliar documentos de Word y libros de Excel en complementos en el nivel de la aplicación en tiempo de ejecución

Artículo
02/19/2013

Puede usar un complemento en el nivel de la aplicación para personalizar documentos de Word y libros de Excel de las siguientes maneras:

Agregar controles administrados a cualquier documento u hoja de cálculo abierta.
Convertir un objeto de lista de una hoja de cálculo de Excel en un objeto ListObject extendido que exponga los eventos y se pueda enlazar a datos mediante el modelo de enlace de datos de Windows Forms.
Tener acceso a los eventos en el nivel de la aplicación que exponen Word y Excel para los documentos, libros y hojas de cálculo concretos.

Para usar esta funcionalidad, genere un objeto en tiempo de ejecución que extienda el documento o el libro.

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

Generar objetos extendidos en complementos

Los objetos extendidos son instancias de tipos que proporciona el runtime de Visual Studio Tools para Office que agregan funcionalidad a los objetos que existen de forma nativa en word o los modelos de objetos de Excel (denominado natural Office se opone).Para generar un objeto extendido para un objeto de Excel o Word, utilice el método GetVstoObject.La primera vez que se llama al método de GetVstoObject para un objeto de word o excel especificado, devuelve un nuevo objeto que extiende el objeto especificado. Cada vez que se llama al método y especifica el mismo objeto de word o excel, devuelve el mismo objeto extendido.

El tipo del objeto extendido tiene el mismo nombre que el tipo del objeto de Office nativo, pero se define en el espacio de nombres Microsoft.Office.Tools.Word o Microsoft.Office.Tools.Excel.Por ejemplo, si llama al método GetVstoObject para extender un objeto Microsoft.Office.Interop.Word.Document, el método devuelve un objeto Microsoft.Office.Tools.Word.Document.

Los métodos GetVstoObject se utilizan principalmente en proyectos en el nivel de la aplicación.También puede utilizarlos en proyectos en el nivel del documento, pero se comportan de manera diferente y tienen menos usos.

Para determinar si ya se ha generado un objeto extendido para un objeto de Office nativo determinado, use el método HasVstoObject.Para obtener más información, vea Determinar si se ha extendido un objeto de Office.

Generar elementos host

Al utilizar GetVstoObject para extender un objeto de nivel de documento (es decir, Microsoft.Office.Interop.Excel.Workbook, Microsoft.Office.Interop.Excel.Worksheet o Microsoft.Office.Interop.Word.Document), el objeto devuelto se denomina elemento host.Un elemento host es un tipo que puede contener otros objetos, incluidos otros controles y objetos extendidos.Se parece al tipo correspondiente del ensamblado de interoperabilidad primario de Word o Excel, pero tiene características adicionales.Para obtener más información acerca de los elementos de host, vea Información general sobre elementos y controles Host.

Después de generar un elemento host, puede utilizarlo para agregar controles administrados al documento, el libro, u hoja de cálculo.Para obtener más información, vea Agregar controles administrados a documentos y hojas de cálculo.

Para generar un elemento host para un documento de Word

El ejemplo de código siguiente se muestra cómo generar un elemento host para el documento activo.

If Globals.ThisAddIn.Application.Documents.Count > 0 Then
    Dim NativeDocument As Microsoft.Office.Interop.Word.Document = _
        Globals.ThisAddIn.Application.ActiveDocument
    Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
        Globals.Factory.GetVstoObject(NativeDocument)
End If

if (Globals.ThisAddIn.Application.Documents.Count > 0)
{
    Microsoft.Office.Interop.Word.Document nativeDocument =
        Globals.ThisAddIn.Application.ActiveDocument;
    Microsoft.Office.Tools.Word.Document vstoDocument =
        Globals.Factory.GetVstoObject(nativeDocument);
}

Para generar un elemento host para un libro de Excel

El ejemplo de código siguiente se muestra cómo generar un elemento host para el libro activo.

Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook =
    Globals.ThisAddIn.Application.ActiveWorkbook
If NativeWorkbook IsNot Nothing Then
    Dim vstoWorkbook As Microsoft.Office.Tools.Excel.Workbook =
        Globals.Factory.GetVstoObject(NativeWorkbook)
End If

Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
    Globals.ThisAddIn.Application.ActiveWorkbook;
if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
        Globals.Factory.GetVstoObject(nativeWorkbook);
}

Para generar un elemento host para una hoja de cálculo de Excel

El ejemplo de código siguiente se muestra cómo generar un elemento host para la hoja de cálculo activa en un proyecto.

Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If NativeWorksheet IsNot Nothing Then
    Dim vstoSheet As Microsoft.Office.Tools.Excel.Worksheet =
        Globals.Factory.GetVstoObject(NativeWorksheet)
End If

Microsoft.Office.Interop.Excel.Worksheet nativeWorksheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (nativeWorksheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet = 
        Globals.Factory.GetVstoObject(nativeWorksheet);
}

Generar controles host ListObject

Al utilizar el método GetVstoObject para extender Microsoft.Office.Interop.Excel.ListObject, el método devuelve Microsoft.Office.Tools.Excel.ListObject.Microsoft.Office.Tools.Excel.ListObject tiene todas las características del Microsoft.Office.Interop.Excel.ListObject original, pero también tiene funcionalidad adicional, como la capacidad de enlazarse a datos utilizando el modelo de enlace de datos de Windows Forms.Para obtener más información, consulte ListObject (Control).

Para generar un control host para un ListObject

El siguiente ejemplo de código muestra cómo generar Microsoft.Office.Tools.Excel.ListObject para primer Microsoft.Office.Interop.Excel.ListObject en la hoja de cálculo activa en un proyecto.

Dim sheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If sheet.ListObjects.Count > 0 Then
    Dim listObject As Excel.ListObject = sheet.ListObjects(1)
    Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject =
        Globals.Factory.GetVstoObject(listObject)
End If

Microsoft.Office.Interop.Excel.Worksheet sheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (sheet.ListObjects.Count > 0)
{
    Excel.ListObject listObject = 
        sheet.ListObjects[1];
    Microsoft.Office.Tools.Excel.ListObject vstoListObject =
        Globals.Factory.GetVstoObject(listObject);
}

Agregar controles administrados a documentos y hojas de cálculo

Después de generar un Microsoft.Office.Tools.Word.Document o un Microsoft.Office.Tools.Excel.Worksheet, puede agregar controles al documento u hoja de cálculo que estos objetos extendidos representan.Para ello, use la propiedad Controls de Microsoft.Office.Tools.Word.Document o Microsoft.Office.Tools.Excel.Worksheet.Para obtener más información, vea Agregar controles a documentos de Office en tiempo de ejecución.

Puede agregar controles de formularios Windows Forms o controles host.Un control host es un control que proporciona Runtime de Microsoft Visual Studio Tools para Office y que encapsula el control correspondiente en el ensamblado de interoperabilidad primario de Word o Excel.Un control host expone todo el comportamiento del objeto de Office nativo subyacente, pero también provoca eventos y se puede enlazar a datos utilizando el modelo de enlace de datos de los formularios Windows Forms.Para obtener más información, vea Información general sobre elementos y controles Host.

[!NOTA]

No puede agregar un control de XmlMappedRange a una hoja de cálculo, o un control de XMLNode o de XMLNodes a un documento, utilizando un complemento.Estos controles host no pueden agregarse mediante programación.Para obtener más información, vea Limitaciones de programación de elementos y controles Host.

Conservar y quitar controles

Cuando se agregan controles administrados a un documento o a una hoja de cálculo, éstos no se conservan cuando se guarda y se cierra el documento.Se quitan todos los controles host solo para dejar los objetos de Office nativos subyacentes.Por ejemplo, Microsoft.Office.Tools.Excel.ListObject se convierte en Microsoft.Office.Interop.Excel.ListObject.También se quitan todos los controles de formularios Windows Forms, pero se dejan en el documento los contenedores de ActiveX para los controles.Debe incluir código en el complemento para limpiar los controles o volver a crearlos la próxima vez que se abra el documento.Para obtener más información, vea Guardar controles dinámicos en documentos de Office.

Acceso a eventos en el nivel de la aplicación en documentos y libros

Algunos eventos de documento, libro y hoja de cálculo de los modelos de objetos nativos de Word y de Excel solo se provocan en el nivel de la aplicación.Por ejemplo, se provoca el evento DocumentBeforeSave cuando un documento se abre en Word, pero este evento se define en la clase Microsoft.Office.Interop.Word.Application, en lugar de en la clase Microsoft.Office.Interop.Word.Document.

Cuando solo se utilizan objetos de Office nativos en el complemento, debe administrar estos eventos en el nivel de la aplicación y escribir el código adicional para determinar si el documento que provocó el evento es un documento que ha personalizado.Los elementos host proporcionan estos eventos en el nivel del documento, para que sea más fácil controlar los eventos para un documento concreto.Puede generar un elemento host y, a continuación, controlar el evento para dicho elemento host.

Ejemplo que utiliza objetos de Word nativos

En el ejemplo de código siguiente se muestra cómo administrar un evento en el nivel de la aplicación para los documentos de Word.El método CreateDocument crea un nuevo documento y, a continuación, define un controlador de eventos DocumentBeforeSave que evita que se guarde el documento.Dado que éste es un evento en el nivel de la aplicación que se provoca para el objeto Microsoft.Office.Interop.Word.Application, el controlador de eventos debe comparar el parámetro Doc con el objeto document1 para determinar si document1 representa el documento guardado.

Private document1 As Word.Document = Nothing

Private Sub CreateDocument1()
    document1 = Me.Application.Documents.Add()
End Sub

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
    Handles Application.DocumentBeforeSave
    If Type.ReferenceEquals(Doc, document1) Then
        Cancel = True
    End If
End Sub

private Word.Document document1 = null;

private void CreateDocument1()
{
    document1 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
}

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    if (Type.ReferenceEquals(Doc, document1)) 
    {
        Cancel = true;
    }
}

Ejemplos que utilizan un elemento host

En los ejemplos de código siguientes se simplifica este proceso controlando el evento BeforeSave de un elemento host Microsoft.Office.Tools.Word.Document.En estos ejemplos, el método CreateDocument2 genera un Microsoft.Office.Tools.Word.Document que extiende el objeto document2 y, a continuación, define un controlador de eventos BeforeSave que evita que el documento se guarde.Dado que solo se llama a este controlador de eventos cuando se guarda document2, el controlador puede cancelar la acción de guardado sin hacer tareas adicionales para comprobar qué documento se guardó.

El ejemplo de código siguiente muestra esta tarea.

Private document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = Globals.Factory.GetVstoObject(document2)
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub

private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = Globals.Factory.GetVstoObject(document2);
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

Determinar si se ha extendido un objeto de Office

Para determinar si ya se ha generado un objeto extendido para un objeto de Office nativo determinado, use el método HasVstoObject.Este método devuelve true si ya se ha generado un objeto extendido; de lo contrario, devuelve false.

Utilice el método Globals.Factory.HasVstoMethod.Pase el objeto de word o excel nativo, como Microsoft.Office.Interop.Word.Document o Microsoft.Office.Interop.Excel.Worksheet, que desea probar para un objeto extendido.

El método HasVstoObject es útil si desea ejecutar el código únicamente cuando un objeto de Office especificado tiene un objeto extendido.Por ejemplo, si tiene un complemento de Word que controla el evento DocumentBeforeSave para quitar controles administrados de un documento antes de guardarlo, puede utilizar el método HasVstoObject para determinar si se ha extendido el documento.Si no se ha extendido el documento, no puede contener los controles administrados y, por consiguiente, el controlador de eventos simplemente puede volver sin intentar limpiar los controles del documento.

Vea también

Conceptos

Agregar controles a documentos de Office en tiempo de ejecución

Información general sobre elementos y controles Host

Otros recursos

Programar complementos de nivel de aplicación

Ejemplos y tutoriales del desarrollo de Office

Compartir a través de