Ejecutar código en el complemento de Office cuando se abre el documento

  • Artículo

Importante

El entorno de ejecución compartido solo se admite en algunas aplicaciones de Office. Para obtener más información, vea Conjuntos de requisitos de runtime compartido.

Puede configurar el complemento de Office para cargar y ejecutar código en cuanto se abra el documento. Esto resulta útil si necesita registrar controladores de eventos, cargar previamente datos para el panel de tareas, sincronizar la interfaz de usuario o realizar otras tareas antes de que el complemento esté visible.

Nota:

La configuración se implementa con un método al que llama el código en tiempo de ejecución. Esto significa que el complemento no se ejecutará la primera vez que un usuario abra el documento. El complemento debe abrirse manualmente por primera vez en cualquier documento. Una vez que se ejecuta el método, ya sea en Office.initialize, Office.onReady o porque el usuario toma una ruta de acceso de código que lo ejecuta; a continuación, cada vez que se vuelve a abrir el documento, el complemento se carga inmediatamente y se ejecuta cualquier código del Office.initialize método o Office.onReady .

Nota:

En este artículo se requiere que el complemento de Office esté configurado para usar un entorno de ejecución compartido. Para obtener más información, vea Configurar el complemento de Office para usar un entorno de ejecución compartido.

Configuración del complemento para cargarlo cuando se abra el documento

El código siguiente configura el complemento para cargarlo y empezar a ejecutarse cuando se abra el documento.

Office.addin.setStartupBehavior(Office.StartupBehavior.load);

Nota:

El setStartupBehavior método es asincrónico.

Colocar código de inicio en Office.initialize o Office.onReady

Cuando el complemento está configurado para cargarse en el documento abierto, se ejecutará inmediatamente. Se llamará al Office.initialize controlador de eventos. Coloque el código de inicio en el controlador de Office.initialize eventos o Office.onReady .

El siguiente código del complemento de Excel muestra cómo registrar un controlador de eventos para los eventos de cambio de la hoja de cálculo activa. Si configura el complemento para cargarlo al abrir el documento, este código registrará el controlador de eventos cuando se abra el documento. Puede controlar los eventos de cambio antes de abrir el panel de tareas.

// This is called as soon as the document opens.
// Put your startup code here.
Office.initialize = () => {
  // Add the event handler.
  Excel.run(async context => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.onChanged.add(onChange);

    await context.sync();
    console.log("A handler has been registered for the onChanged event.");
  });
};

/**
 * Handle the changed event from the worksheet.
 *
 * @param event The event information from Excel
 */
async function onChange(event) {
    await Excel.run(async (context) => {    
        await context.sync();
        console.log("Change type of event: " + event.changeType);
        console.log("Address of event: " + event.address);
        console.log("Source of event: " + event.source);
  });
}

El siguiente código de complemento de PowerPoint muestra cómo registrar un controlador de eventos para los eventos de cambio de selección del documento de PowerPoint. Si configura el complemento para cargarlo al abrir el documento, este código registrará el controlador de eventos cuando se abra el documento. Puede controlar los eventos de cambio antes de abrir el panel de tareas.

// This is called as soon as the document opens.
// Put your startup code here.
Office.onReady(info => {
  if (info.host === Office.HostType.PowerPoint) {
    Office.context.document.addHandlerAsync(Office.EventType.DocumentSelectionChanged, onChange);
    console.log("A handler has been registered for the onChanged event.");
  }
});

/**
 * Handle the changed event from the PowerPoint document.
 *
 * @param event The event information from PowerPoint
 */
async function onChange(event) {
  console.log("Change type of event: " + event.type);
}

Configuración del complemento para que no tenga ningún comportamiento de carga en el documento abierto

Puede haber escenarios en los que quiera desactivar el comportamiento "Ejecutar en el documento abierto". El código siguiente configura el complemento para que no se inicie cuando se abra el documento. En su lugar, se iniciará cuando el usuario lo interactúe de alguna manera, como elegir un botón de cinta de opciones o abrir el panel de tareas. Este código no tiene ningún efecto si el método no se ha llamado previamente en el documento actual, con Office.StartupBehavior.load como parámetro.

Nota:

Si el complemento llama al método , con Office.StartupBehavior.load como parámetro , en Office.initialize o Office.onReady, el comportamiento se vuelve a activar. Por lo tanto, en este escenario, desactivarlo solo se aplica a la próxima vez que se abra el documento, no a todas las aperturas posteriores.

Office.addin.setStartupBehavior(Office.StartupBehavior.none);

Obtener el comportamiento de carga actual

Puede haber escenarios en los que el complemento necesite saber si está configurado para iniciarse automáticamente la próxima vez que se abra el documento actual. Para determinar cuál es el comportamiento de inicio actual, ejecute el método siguiente, que devuelve un valor Office.StartupBehavior .

let behavior = await Office.addin.getStartupBehavior();

Vea también