Share via

Abrir automáticamente un panel de tareas con un documento

  • Artículo

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 panel de tareas autoabrir, introducida en el conjunto de requisitos AddInCommands 1.1, para abrir automáticamente un panel de tareas cuando el escenario lo requiera.

Nota:

Para configurar un panel de tareas para que se abra inmediatamente cuando se instala el complemento, pero no necesariamente siempre que el documento se abra más adelante, vea Abrir automáticamente un panel de tareas cuando se instala un complemento.

¿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 se conservan en ese documento. Como resultado, cuando otros usuarios abren el documento, se les pide que instalen el complemento y se abre el panel de tareas. El desafío con este modelo es que, en muchos casos, los usuarios no quieren que el complemento persista 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 se admite actualmente en los siguientes productos y plataformas.

Productos Plataformas
  • Word
  • Excel
  • PowerPoint
 Plataformas admitidas para todos los productos admitidos:
  • Office en la web
  • Office en Windows (compilación 16.0.8121.1000 o posterior)
  • Office en Mac (compilación 15.34.17051500 o posterior)

Procedimientos recomendados

Aplique los siguientes procedimientos recomendados cuando use 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 del conjunto de requisitos para determinar si la característica de apertura automática está disponible y proporcionar 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.

    Nota:

    Si Microsoft detecta un abuso de la característica AutoOpen, puede que rechace el complemento de AppSource.

  • 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.

Implementación de 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.

Importante

El panel que designe para abrirse automáticamente solo se abrirá si el complemento ya está instalado en el dispositivo del usuario. Si el usuario no tiene instalado el complemento al abrir un documento, la característica AutoOpen no funcionará y se omitirá la configuración. Si también necesita que el complemento se distribuya con el documento, debe establecer la propiedad visibility en 1; esto solo puede hacerse mediante OpenXML, se ofrece un ejemplo más adelante en este artículo.

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

Para especificar el panel de tareas que se abrirá automáticamente, establezca el valor TaskpaneId en Office.AutoShowTaskpaneWithDocument. Solo se puede establecer este valor en un panel de tareas. Si establece este valor en varios paneles de tareas, la primera repetición del valor se reconocerá y el resto se omitirán.

En el ejemplo siguiente se muestra el valor de TaskPaneId establecido en 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 método settings.set de Office.js para establecer Office.AutoShowTaskpaneWithDocumenttrueen , 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 AppSource 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.

El webextension elemento también incluye una referencia al almacén o catálogo con atributos para id, storeType, storey 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.

Valor storeType Valor id Valor store Valor version
OMEX (AppSource) El identificador de recurso de AppSource del complemento (consulte la nota). La configuración regional de AppSource, por ejemplo: "en-us". Versión del catálogo de AppSource (consulte la nota).
WOPICatalog (hosts de WOPI asociados) El identificador de recurso de AppSource del complemento (consulte la nota). "wopicatalog". Use este valor para los complementos que se publican en el origen de la aplicación y se instalan en hosts WOPI. Para obtener más información, vea Integración con Office Online. La versión en el manifiesto del complemento.
Sistema de archivos (un recurso compartido de red) El GUID del complemento en el manifiesto del complemento. Ruta de acceso del recurso compartido de red; por ejemplo, "\\MyComputer\MySharedFolder". La versión en el manifiesto del complemento.
EXCatalog (implementación por servidor Exchange) El GUID del complemento en el manifiesto del complemento. "EXCatalog". La fila EXCatalog es la fila que se va a usar con los complementos que usan la implementación centralizada en el Centro de administración de Microsoft 365. La versión en el manifiesto del complemento.
Registro (Registro del sistema) El GUID del complemento en el manifiesto del complemento. "developer" La versión en el manifiesto del complemento.

Nota:

Para buscar el identificador de recurso y la versión de un complemento en AppSource, vaya a la página de aterrizaje de AppSource del complemento. El identificador de recurso aparece en la barra de direcciones del explorador. La versión se muestra en la sección Detalles de la página.

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 webextension 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.

Nota:

Si quiere distribuir el complemento con el documento, para que se pida a los usuarios que lo instalen, tiene que establecer la propiedad visibility en 1. Esto solo se puede hacer con Open XML.

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 y, a continuación, 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 del SDK de Open XML para generar código de C# para agregar mediante programación el marcado basado en el XML que genere.

Probar y comprobar abrir paneles de tareas

Puede implementar una versión de prueba del complemento que abrirá automáticamente un panel de tareas mediante la implementación centralizada a través de la Centro de administración de Microsoft 365. En el ejemplo siguiente se muestra cómo se insertan los complementos desde el catálogo Implementación centralizada mediante 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 mediante la suscripción de 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, puede calificar para una suscripción de desarrollador de Microsoft 365 E5 a través del Programa para desarrolladores de Microsoft 365; para obtener más información, consulte las preguntas más frecuentes. Como alternativa, puede registrarse para obtener una evaluación gratuita de 1 mes o comprar un plan de Microsoft 365.

Consulte también