Comandos de complemento

Los comandos de complementos son elementos de interfaz de usuario que amplían la interfaz de usuario de Office e inician acciones en el complemento. Puede utilizar comandos de complementos para agregar un botón en la cinta de opciones o un elemento a un menú contextual. Cuando los usuarios seleccionan un comando, inician acciones como ejecutar código JavaScript o mostrar una página de complemento en un panel de tareas. Los comandos de complementos ayudan a los usuarios a encontrar y utilizar el complemento, que puede ayudar a aumentar la adopción y reutilización de su complemento y mejorar la retención de los clientes.

Tipos de comandos de complemento

Hay dos tipos de comandos de complemento, en función del tipo de acción que desencadena el comando.

• Comandos del panel de tareas: el botón o elemento de menú abre el panel de tareas del complemento. Agregue este tipo de comando de complemento con marcado en el manifiesto. Office proporciona el "código subyacente" del comando.
• Comandos de función: el botón o elemento de menú ejecuta cualquier JavaScript arbitrario. El código casi siempre llama a las API de la biblioteca de JavaScript de Office, pero no es necesario. Este tipo de complemento normalmente no muestra ninguna interfaz de usuario que no sea el botón o el propio elemento de menú. Tenga en cuenta lo siguiente sobre los comandos de función:
  • La función que se desencadena puede llamar al método displayDialogAsync para mostrar un cuadro de diálogo, que es una buena manera de mostrar un error, mostrar el progreso o solicitar la entrada del usuario. Si el complemento está configurado para usar un entorno de ejecución compartido, la función también puede llamar al método showAsTaskpane .
  • El tiempo de ejecución en el que se ejecuta el comando de función es un tiempo de ejecución completo basado en explorador. Puede representar HTML y llamar a Internet para enviar u obtener datos.

Ubicación de los comandos de complemento

Cuando un usuario instala un complemento, la ubicación de sus comandos depende de la aplicación, la plataforma y el contexto. Los comandos de complemento se encuentran en la cinta de opciones, en una pestaña predeterminada o personalizada, o en una barra de acciones (solo se aplica a determinadas plataformas de Outlook). Aparecen en la interfaz de usuario como un botón o un elemento en un menú desplegable.

Para los comandos de complemento que aparecen en la cinta de opciones, si usa el diseño simplificado de la cinta de opciones, el nombre del complemento se quita de la barra de aplicaciones. Solo permanece el botón de comando de complemento en la cinta de opciones.

A medida que la cinta de opciones o la barra de acciones se llenan más, los comandos de complemento se muestran en el menú de desbordamiento. Los comandos del mismo complemento suelen agruparse.

Excel, PowerPoint y Word

La pestaña predeterminada depende de la aplicación y el contexto. Para Excel, PowerPoint y Word, la pestaña predeterminada es Inicio.

Outlook

Para Outlook, la ubicación predeterminada de un comando de complemento se basa en la plataforma y en el modo actual de Outlook. Para obtener instrucciones, vea Usar complementos en Outlook.

Menú desplegable

Un comando de complemento de menú desplegable define una lista estática de elementos que se presentan en el menú desplegable. El menú pueden ser cualquier mezcla de elementos que ejecuten una función o que abran un panel de tareas. No se admiten submenús.

Capacidades de comando

Actualmente, se admiten las capacidades de comando siguientes.

Puntos de extensión

• Pestañas de la cinta: ampliar las pestañas integradas o crear una pestaña personalizada. Un complemento puede tener solo una pestaña personalizada.
• Menús contextuales: ampliar los menús contextuales seleccionados.

Tipos de controles

• Botones sencillos: activan acciones específicas.
• Menús: menú sencillo desplegable con botones que activan acciones.

Estado habilitado o deshabilitado de forma predeterminada

Puede especificar si el comando estará habilitado o deshabilitado cuando se inicie el complemento y cambiar la configuración mediante programación.

Ubicación en la cinta de opciones (versión preliminar)

Puede especificar el lugar en el que se muestra una pestaña personalizada, como "solo a la derecha de la pestaña Inicio", en la cinta de opciones de la aplicación de Office.

Integración de los botones integrados de Office

Puede insertar los botones integrados de la cinta de opciones de Office en los grupos de comandos personalizados y en la pestaña de la cinta de opciones personalizadas.

Fichas contextuales

Puede especificar que una pestaña solo esté visible en la cinta en determinados contextos, como cuando se selecciona un gráfico en Excel.

Plataformas compatibles

Actualmente, los comandos del complemento son compatibles con las siguientes plataformas, a excepción de las limitaciones que se especifican en las subsecciones de las Funciones de comando anteriores.

• Office en la web
• Office en Windows (versión 1604 (compilación 6769.2000) o posterior, conectada a una suscripción de Microsoft 365)
• Office en Mac (versión 15.33 (17040900) o posterior, conectada a una suscripción de Microsoft 365)
• Perpetua office 2019 o posterior en Windows o en Mac

Depuración

Para depurar un comando de complemento, debe ejecutarlo en Office en la Web. Para obtener más información, vea Depurar complementos en Office en la Web.

Procedimientos recomendados

Aplique las siguientes prácticas recomendadas al desarrollar comandos de complemento.

• Use comandos para representar una acción específica con un resultado claro y específico para los usuarios. No combine varias acciones en un solo botón.

• Ofrezca acciones pormenorizadas para que las tareas más comunes del complemento sean más eficientes de realizar. Minimice el número de pasos que una acción se tarda en completar.

• Para colocar los comandos en la cinta de opciones de la aplicación de Office:

  • Coloque los comandos en una pestaña existente (Insertar, Revisar, etc.) si la funcionalidad proporcionada se ajusta allí. Por ejemplo, si el complemento permite a los usuarios insertar medios, agregue un grupo a la pestaña Insertar. Tenga en cuenta que no todas las pestañas están disponibles en todas las versiones de Office. Para obtener más información, vea Manifiesto de complementos de Office.
  • Coloque los comandos en la pestaña Inicio si la función no se ajusta a ninguna otra pestaña y si tiene menos de seis comandos de nivel superior. También puede agregar comandos a la pestaña Inicio si el complemento necesita trabajar entre versiones de Office (como Office en la Web o escritorio) y una pestaña no está disponible en todas las versiones (por ejemplo, la pestaña Diseño no existe en Office en la Web).
  • Coloque comandos en una pestaña personalizada si tiene más de seis comandos de nivel superior.
  • Asigne un nombre al grupo que coincida con el nombre del complemento. Si tiene varios grupos, asigne un nombre a cada grupo según la función de los comandos del grupo.
  • No agregue botones innecesarios para aumentar el patrimonio real del complemento.
  • No coloque una pestaña personalizada a la izquierda de la pestaña Inicio ni déle el foco de forma predeterminada cuando se abra el documento, a menos que el complemento sea la forma principal en que los usuarios interactuarán con el documento. Darle una excesiva prominencia al complemento podría resultar inconveniente y molesto para los usuarios y administradores.
  • Si el complemento es la forma principal en la que los usuarios van a interactuar con el documento y usted dispone de una pestaña de la cinta de opciones personalizada, considere integrar en esa pestaña los botones de las funciones de Office que los usuarios suelan necesitar.
  • Si la funcionalidad proporcionada con una pestaña personalizada solo debe estar disponible en determinados contextos, use pestañas contextuales personalizadas. Si usa pestañas contextuales personalizadas, asegúrese de implementar una experiencia de reserva por si su complemento se ejecuta en plataformas que no admitan pestañas contextuales personalizadas.

  Nota:

  Los complementos que ocupan demasiado espacio podrían no superar la validación de AppSource.

• Para todos los iconos, siga las directrices de diseño de iconos.

• Proporcione una versión del complemento que funcione en aplicaciones o plataformas de Office (como iPad) que no admitan comandos. Se puede usar un único manifiesto de complemento para estas versiones.

Pasos siguientes

La mejor manera de empezar a usar comandos de complementos es echar un vistazo a los ejemplos de comandos de complementos de Office en GitHub.

Para obtener más información sobre cómo especificar comandos de complemento en un manifiesto de solo complemento, vea Crear comandos de complemento con el manifiesto de solo complemento y el contenido de referencia VersionOverrides .

Para obtener más información sobre cómo especificar comandos de complemento en el manifiesto unificado para Microsoft 365, consulte Creación de comandos de complemento con el manifiesto unificado para Microsoft 365.