Abrir automáticamente un panel de tareas con un documento

Puede usar comandos de complemento en el complemento de Office para ampliar la interfaz de usuario de Office agregando botones a la cinta de opciones de la aplicación de Office. Cuando los usuarios hacen clic en el botón de comando, se ejecuta una acción (por ejemplo, se abre un panel de tareas).

En algunos escenarios, es necesario que el panel de tareas se abra automáticamente al abrir un documento, sin la interacción explícita del usuario. Puede usar la característica de abrir automáticamente el panel de tareas, incluida en el conjunto de requisitos de AddInCommands 1.1, para abrir automáticamente un panel de tareas cuando su escenario lo requiera.

¿En qué se diferencia la característica AutoOpen de insertar un panel de tareas?

Cuando un usuario inicia complementos que no usan comandos de complemento, los complementos se insertan en el documento y permanecen en ese documento. Como resultado, cuando otros usuarios abran el documento, se les pedirá que instalen el complemento y se abrirá el panel de tareas. El desafío con este modelo es que, en muchos casos, los usuarios no quieren que el complemento permanezca en el documento. Por ejemplo, puede que un alumno que use un complemento del diccionario en un documento de Word no quiera que a sus compañeros de clase o docentes se les pida que instalen el complemento cuando abran el documento.

Con la característica AutoOpen, puede definir de forma explícita (o permitir al usuario definirlo) que un complemento de panel de tareas específico persista en un documento concreto.

Compatibilidad y disponibilidad

La característica de apertura automática es compatible actualmente con los siguientes productos y plataformas.

Procedimientos recomendados

Aplique los siguientes procedimientos recomendados al usar la característica de apertura automática.

• Use la característica AutoOpen cuando permita a los usuarios del complemento ser más eficientes, como en los casos siguientes:
  • Cuando el documento necesita el complemento para funcionar correctamente. Por ejemplo, en una hoja de cálculo con valores bursátiles que se actualicen de forma periódica con un complemento. El complemento se abrirá automáticamente al abrir la hoja de cálculo para mantener actualizados los valores.
  • Cuando es muy probable que el usuario siempre use el complemento con un documento específico. Por ejemplo, un complemento que ayuda a los usuarios a rellenar o cambiar datos de un documento al extraer información de un sistema back-end.
• Permite a los usuarios activar o desactivar la característica AutoOpen. Incluya una opción en la interfaz de usuario para que los usuarios puedan seleccionar que ya no quieren abrir automáticamente el panel de tareas del complemento.
• Use la detección de conjuntos de requisitos para determinar si la función de apertura automática está disponible y proporcione un comportamiento de reserva si no lo está.
• No use la característica AutoOpen para aumentar de manera artificial el uso del complemento. Si no tiene sentido que el complemento se abra automáticamente con determinados documentos, esta característica puede molestar a los usuarios.
• No use esta característica para anclar varios paneles de tareas. Solo se puede establecer un panel del complemento para que se abra automáticamente en un documento.

Implementar la característica de apertura automática

• Especifique el panel de tareas que se abrirá automáticamente.
• Etiquete el documento para que abra automáticamente el panel de tareas.

Paso 1. Especificar el panel de tareas que se va a abrir

Configure el manifiesto para especificar la página del panel de tareas que se debe abrir automáticamente. El proceso depende del tipo de manifiesto que use el complemento.

"runtimes": [
    {
        ...
        "code": {
            "page": "https://contoso.com/taskpane.html"
        },
        "actions": [
            {
                "id": "ShowTaskPane",
                "type": "openPage",
                "view": "Office.AutoShowTaskpaneWithDocument"
            }
        ]
    }
]

<Action xsi:type="ShowTaskpane">
    <TaskpaneId>Office.AutoShowTaskpaneWithDocument</TaskpaneId>
    <SourceLocation resid="Contoso.Taskpane.Url" />
</Action>

Paso 2: Etiquetar el documento para que abra automáticamente el panel de tareas

Puede usar dos métodos para etiquetar el documento para que desencadene la característica AutoOpen. Elija la alternativa que mejor se ajuste a su escenario.

Etiquetar el documento en el lado cliente

Use el Office.js método settings.set para establecer Office.AutoShowTaskpaneWithDocument en true, como se muestra en el ejemplo siguiente.

Office.context.document.settings.set("Office.AutoShowTaskpaneWithDocument", true);
Office.context.document.settings.saveAsync();

Use este método si necesita etiquetar el documento como parte de su interacción con el complemento (por ejemplo, cuando el usuario crea un enlace, o bien cuando selecciona una opción para indicar que quiere que el panel se abra automáticamente).

Usar Open XML para etiquetar el documento

Puede usar Open XML para crear o modificar un documento y agregar el marcado de Office Open XML para desencadenar la característica AutoOpen. Vea un ejemplo donde se muestra este procedimiento en Office-OOXML-EmbedAddin.

Agregue dos elementos Open XML al documento.

• Una parte webextension
• Una parte taskpane

En el ejemplo siguiente se muestra cómo agregar el elemento webextension.

<we:webextension xmlns:we="http://schemas.microsoft.com/office/webextensions/webextension/2010/11" id="[ADD-IN ID PER MANIFEST]">
  <we:reference id="[GUID or Microsoft Marketplace asset ID]" version="[your add-in version]" store="[Pointer to store or catalog]" storeType="[Store or catalog type]"/>
  <we:alternateReferences/>
  <we:properties>
   <we:property name="Office.AutoShowTaskpaneWithDocument" value="true"/>
  </we:properties>
  <we:bindings/>
  <we:snapshot xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"/>
</we:webextension>

En el elemento webextension se incluye un contenedor de propiedades y una propiedad llamada Office.AutoShowTaskpaneWithDocument que tiene que establecerse en true.

La webextension parte también incluye una referencia a la tienda o catálogo con atributos para id, storeType, store, y version. De los valores de storeType, solo cuatro son relevantes para la característica AutoOpen. Los valores de los otros tres atributos dependen del valor de storeType, como se muestra en la tabla siguiente.

Para más información sobre la marcación de webextension, vea [MS-OWEXML] 2.2.5. WebExtensionReference.

En el ejemplo siguiente se muestra cómo agregar el elemento taskpane.

<wetp:taskpane dockstate="right" visibility="0" width="350" row="4" xmlns:wetp="http://schemas.microsoft.com/office/webextensions/taskpanes/2010/11">
  <wetp:webextensionref xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" r:id="rId1" />
</wetp:taskpane>

Tenga en cuenta que, en este ejemplo, el atributo visibility se estableció en “0”. Esto significa que después de agregar la extensión web y taskpane los elementos, la primera vez que se abre el documento, el usuario tiene que instalar el complemento desde el botón Complemento de la cinta de opciones. Después, el panel de tareas del complemento se abrirá automáticamente al abrir el archivo. Además, al establecer visibility en “0”, puede usar Office.js para permitir que los usuarios activen o desactiven la característica AutoOpen. En concreto, el script establece la configuración del documento Office.AutoShowTaskpaneWithDocument en true o false. (Para obtener más información, vea Etiquetar el documento en el lado cliente).

Si visibility se establece en “1”, el panel de tareas se abrirá automáticamente la primera vez que se abra el documento. Se pedirá al usuario que confíe en el documento y, después de conceder la confianza, se abrirá el complemento. Después, el panel de tareas del complemento se abrirá automáticamente al abrir el archivo. Pero, si visibility se establece en “1”, no podrá usar Office.js para permitir que los usuarios activen o desactiven la característica AutoOpen.

Establecer visibility en “1” es una opción recomendada si el complemento de la plantilla o el contenido del documento están tan integrados que el usuario no quiere desactivar la característica AutoOpen.

Una manera fácil de escribir el XML es ejecutar primero el complemento y etiquetar el documento en el lado cliente para escribir el valor. Después, guardar el documento e inspeccionar el XML que se genera. Office detectará y proporcionará los valores de atributo adecuados. También puede usar la herramienta de productividad Open XML SDK para generar código C# para agregar mediante programación el marcado en función del XML que genere.

Probar y comprobar abrir paneles de tareas

Puede implementar una versión de prueba del complemento que abra automáticamente un panel de tareas mediante la implementación centralizada a través del Centro de administración de Microsoft 365. En el ejemplo siguiente se muestra cómo se insertan los complementos desde el catálogo de implementación centralizada utilizando la versión del almacén EXCatalog.

<we:webextension xmlns:we="http://schemas.microsoft.com/office/webextensions/webextension/2010/11" id="{52811C31-4593-43B8-A697-EB873422D156}">
    <we:reference id="af8fa5ba-4010-4bcc-9e03-a91ddadf6dd3" version="1.0.0.0" store="EXCatalog" storeType="EXCatalog"/>
    <we:alternateReferences/>
    <we:properties/>
    <we:bindings/>
    <we:snapshot xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"/>
</we:webextension>

Puede probar el ejemplo anterior con su suscripción a Microsoft 365 para probar la implementación centralizada y comprobar que el complemento funciona según lo esperado. Si aún no tiene una suscripción a Microsoft 365, es posible que sea apto para una suscripción de desarrollador de Microsoft 365 E5 a través del Programa de desarrollador de Microsoft 365; para obtener más información, consulte las preguntas más frecuentes. Como alternativa, puede registrarse para obtener una prueba gratuita de 1 mes o comprar un plan de Microsoft 365.

Vea también

• Para obtener un ejemplo que muestra cómo usar la característica de apertura automática, consulte Abrir automáticamente un panel de tareas con un documento.
• Abrir automáticamente un panel de tareas cuando se instala un complemento
• Infórmese sobre el Programa de desarrolladores de Microsoft 365
• Administrar opciones de confianza para complementos de Office