Amplíe documentos de Word y libros de Excel en complementos de VSTO en tiempo de ejecución

  • Artículo

Puede utilizar un complemento de VSTO para personalizar documentos de Word y libros de Excel de las maneras siguientes:

  • Agregar controles administrados a cualquier documento u hoja de cálculo abiertos.

  • Convertir un objeto de lista existente de una hoja de cálculo de Excel en un ListObject extendido que expone eventos y que puede enlazarse a datos utilizando el modelo de enlace de datos de formularios Windows Forms.

  • Obtener acceso a eventos de aplicación expuestos por Word y Excel para determinados documentos, libros y hojas de cálculo.

    Para utilizar esta funcionalidad, se genera un objeto en tiempo de ejecución que extienda el documento o libro.

    Aplicación: la información de este artículo se aplica a los proyectos de complementos de VSTO para las siguientes aplicaciones: Excel y Word. Para obtener más información, consulte Características disponibles por aplicación y tipo de proyecto de Office.

Generar objetos extendidos en complementos de VSTO

Losobjetos extendidos son instancias de 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). Para generar un objeto extendido para un objeto de Word o Excel, use el método GetVstoObject. La primera vez que se llama al método GetVstoObject para un objeto de Word o Excel especificado, se devuelve un nuevo objeto que extiende el objeto especificado. Cada vez que llame al método y especifique 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 nativo de Office, pero este tipo está definido en el espacio de nombres Microsoft.Office.Tools.Excel o Microsoft.Office.Tools.Word . Por ejemplo, si se llama a la GetVstoObject método para extender un objeto Document, el método devuelve un objeto Document.

Los métodos GetVstoObject se usan principalmente en proyectos de complementos VSTO. También puede utilizar estos métodos en proyectos de nivel de documento, pero se comportan de manera diferente y tienen menos usos.

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

Generar elementos host

Cuando se usa GetVstoObject para extender un objeto de nivel de documento (es decir, un Workbook, Worksheet o 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 sobre los elementos host, consulte Información general sobre elementos y controles Host.

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

Para generar un elemento host para un documento de Word

  • En 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)
{
    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

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

    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

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

    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

Cuando se usa el método GetVstoObject para extender un ListObject, el método devuelve un ListObject. ListObject tiene todas las características del ListObject original. También dispone de funciones adicionales y puede enlazarse a datos mediante el modelo de enlace de datos de Windows Forms. Para obtener más información, consulte el Control ListObject.

Para generar un control host para un ListObject

  • En el ejemplo de código siguiente se muestra cómo generar un ListObject para el primer ListObject de la hoja de cálculo activa en un proyecto.

    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 Document o Worksheet, puede agregar controles al documento o la hoja de cálculo que representan estos objetos extendidos. Para agregar controles, use la propiedad Controls de Document o Worksheet. Para obtener más información, consulte 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 proporcionado por el tiempo de ejecución de Visual Studio Tools for Office que encapsula el control correspondiente del ensamblado de interoperabilidad primario de Word o Excel. Un control host expone todo el comportamiento del objeto nativo subyacente de Office. También genera eventos y puede enlazarse a datos mediante el modelo de enlace de datos de Windows Forms. Para obtener más información, consulte Información general sobre elementos y controles Host.

Nota:

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

Conservar y quitar controles

Al agregar controles administrados a un documento o una hoja de cálculo, los controles no se conservan cuando se guarda y se cierra el documento. Se quitan todos los controles de host para que solo queden los objetos nativos subyacentes de Office. Por ejemplo, ListObject se convierte en ListObject. También se quitan todos los controles de formularios Windows Forms, pero los contenedores ActiveX de los controles se quedan en el documento. Debe incluir código en el complemento de VSTO para limpiar los controles o volver a crearlos la próxima vez que se abra el documento. Para obtener más información, consulte Conservación de controles dinámicos en documentos de Office.

Obtener acceso a los eventos en el nivel de 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 Excel solo se desencadenan en el nivel de aplicación. Por ejemplo, el evento DocumentBeforeSave se desencadena cuando se abre un documento de Word, pero este evento está definido en la clase Application , en lugar de la clase Document .

Si usa únicamente objetos nativos de Office en el complemento de VSTO, debe controlar estos eventos en el nivel de aplicación y, a continuación, escribir código adicional para determinar si el documento que desencadenó el evento es un complemento que ha personalizado. Los elementos host proporcionan estos eventos en el nivel de documento para que resulte más fácil controlar los eventos de un documento específico. Puede generar un elemento host y, a continuación, controlar el evento para ese elemento host.

Ejemplo que usa objetos nativos de Word

En el ejemplo de código siguiente se muestra cómo controlar un evento en el nivel de 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 impide que se guarde este documento. El evento en el nivel de aplicación que se desencadena para el objeto Application y el controlador de eventos debe comparar el parámetro Doc con el objeto document1 para determinar si document1 representa el documento guardado.

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

Los ejemplos de código siguientes simplifican este proceso controlando el evento BeforeSave de un elemento host Document . El método CreateDocument2 de estos ejemplos genera un Document que extiende el objeto document2 y, a continuación, define un controlador de eventos BeforeSave que evita que se guarde el documento. Solo se llama al controlador de eventos cuando se guarda document2 y se puede cancelar la acción sin tener que realizar ningún trabajo adicional para comprobar qué documento se guardó.

El siguiente ejemplo de código muestra esta tarea.

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 un objeto de Office se ha extendido

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

Use el método Globals.Factory.HasVstoObject. Pase el objeto nativo de Word o Excel, como Document o Worksheet, que desea probar para un objeto extendido.

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

Contenido relacionado