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.

Nota:

• Los catálogos de SharePoint no admiten comandos de complemento. Puede implementar comandos de complemento a través del portal de aplicaciones integradas o Microsoft Marketplace, o usar la instalación de prueba para implementar el comando de complemento para realizar pruebas.
• Actualmente, los complementos de contenido no admiten los comandos de complementos.

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:

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

  • El tiempo de ejecución se cierra cuando se completa la función o se han transcurrido 5 minutos, lo que sea anteriormente.

  • La función que se desencadena puede llamar al método displayDialogAsync para mostrar un cuadro de diálogo. Esta es una buena manera de mostrar un error, mostrar el progreso o pedir al usuario la entrada.

    Nota:

    Debido al tiempo de espera de 5 minutos, el cuadro de diálogo debe diseñarse para que los usuarios completen su interacción y la cierren en 5 minutos. El complemento debe usar un panel de tareas para interacciones más largas.

  • Si el complemento está configurado para usar un entorno de ejecución compartido, la función también puede llamar al método showAsTaskpane .

  Sugerencia

  Los comandos de función no son la única manera de ejecutar JavaScript arbitrario en un complemento. Un complemento también puede incluir:

  • Controladores personalizados para determinados eventos, como un usuario que abre un nuevo panel de mensajes en Outlook.
  • Agentes de Copilot personalizados que realizan acciones en respuesta a solicitudes de lenguaje natural de los usuarios del complemento.

Ubicación de los comandos de complemento

Cuando un usuario instala un complemento, los comandos del complemento se encuentran en la cinta de opciones, en una pestaña integrada de Office o en una pestaña personalizada especificada en el manifiesto. (También puede colocar comandos de complemento en una pestaña contextual personalizada que el código del complemento define en tiempo de ejecución). Aparecen en la interfaz de usuario como un botón o un elemento en un menú desplegable.

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.

En Office en la Web, si usa el diseño de cinta de opciones de una sola línea o simplificado, el nombre del complemento no se muestra en la cinta de opciones. Solo se muestra el icono de comando del complemento.

Excel, PowerPoint y Word

A continuación se muestra un ejemplo de comandos de complemento en un grupo personalizado en la pestaña Datos de la cinta de opciones de Excel.

Outlook

Para Outlook, cuando quiera un comando de complemento en una pestaña de cinta integrada, en lugar de crear la suya propia, el comando aparecerá en la pestaña predeterminada en función de la plataforma y 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. 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.

Comandos de complemento agrupados en la cinta de opciones

Se pueden agrupar varios comandos de complemento en la cinta de opciones. Un grupo debe contener al menos un comando de complemento en forma de botón o menú desplegable. En Office en Windows y en Mac, la etiqueta y el icono de un botón o menú desplegable suelen mostrarse para los comandos de complemento de un grupo. Sin embargo, el tamaño del icono y la visibilidad de la etiqueta pueden variar debido a los siguientes factores que restringen el espacio.

• Número de comandos de complemento del grupo.
• Tamaño de la ventana de cliente de Office.

Si la ventana de cliente está maximizada y hay más de tres controles en un grupo, se muestra la etiqueta de cada control, pero el tamaño de su icono puede variar (algunos se muestran como 16 x 16 píxeles, mientras que otros se muestran como 32 x 32 píxeles).

Cuando hay dos o más comandos de complemento en un grupo y el espacio se limita, se realizan los siguientes ajustes en la forma en que se muestran los comandos de complemento. Estos cambios se aplican a los grupos de comandos de complemento de derecha a izquierda a través de la cinta de opciones en la secuencia siguiente.

1. Se muestran iconos pequeños (16 x 16 píxeles) y etiquetas para cada comando de complemento de un grupo.
2. Solo se muestran iconos pequeños.
3. El grupo se muestra como un menú desplegable en lugar de mostrar comandos de complemento individuales en la cinta de opciones. También aparece un icono de control deslizante de desplazamiento en la cinta de opciones para que pueda desplazarse por la cinta de opciones.

En Office en la Web, el tamaño del icono y la visibilidad de la etiqueta de los controles de los grupos no cambian a medida que se cambia el tamaño de la ventana del explorador. El icono del control deslizante de desplazamiento simplemente se muestra en la cinta de opciones.

Capacidades de comando

Actualmente, se admiten las capacidades de comando siguientes.

Puntos de extensión

• Pestañas de la cinta de opciones: amplíe las pestañas integradas o cree una nueva pestaña principal personalizada. Un complemento puede tener solo una pestaña principal personalizada. (También puede colocar comandos de complemento en una pestaña contextual personalizada).

  Nota:

  Para Outlook, las pestañas personalizadas solo se admiten en Outlook clásico en Windows. En Outlook en la Web, en Mac y en el nuevo Outlook en Windows, puede colocar grupos personalizados de controles en una de las pestañas integradas de la cinta de opciones en su lugar.

• 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 de disponibilidad predeterminado

Puede especificar si el comando está disponible cuando se inicia el complemento y cambiar la configuración mediante programación.

Nota:

Esta característica no se admite en todas las aplicaciones o escenarios de Office. Para obtener más información, vea Cambiar la disponibilidad de los comandos de complemento.

Posición en la cinta

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.

Nota:

Esta característica no se admite en todas las aplicaciones o escenarios de Office. Para obtener más información, consulte Ubicar una pestaña personalizada en la cinta de opciones.

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.

Nota:

Esta característica no se admite en todas las aplicaciones o escenarios de Office. Para obtener más información, consulte Integrar los botones integrados de Office en las pestañas personalizadas.

Fichas contextuales

Puede especificar una pestaña contextual personalizada; es decir, una pestaña que solo está visible en la cinta de opciones en determinados contextos, como cuando se selecciona un gráfico en Excel.

Nota:

Esta característica no se admite en todas las aplicaciones o escenarios de Office. Para obtener más información, consulte Crear pestañas contextuales personalizadas en los complementos de Office.

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 conectado a una suscripción de Microsoft 365
• Office en Mac conectado a una suscripción de Microsoft 365
• Office 2021 perpetua o posterior en Windows o en Mac

Nota:

Para obtener información sobre la compatibilidad en Outlook, consulte las notas de soporte técnico de Outlook.

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

Procedimientos recomendados para comandos de complemento en la cinta de opciones

En la tabla siguiente se describen los límites recomendados para los objetos de una cinta de opciones de aplicación de Office.

Objeto	Límite recomendado	Justificación de la facilidad de uso
Pestañas	Siete pestañas visibles a la vez	Evita saturar a los usuarios con demasiadas opciones y les ayuda a recordar dónde se encuentran los comandos. Se recomienda usar pestañas contextuales para reducir el desorden.
Grupos por pestaña	Seis grupos	Ayuda a los usuarios a examinar y localizar comandos rápidamente.
Comandos por grupo	Siete comandos	Reduce la fatiga de decisión de demasiadas opciones.
Total de comandos en la cinta de opciones	70 comandos visibles	Ayuda a los usuarios a localizar acciones de forma eficaz. Si el complemento tiene más de 70 comandos, se recomienda implementar galerías, menús desplegables o diálogos para el desbordamiento.

Además de los límites de objetos recomendados, tenga en cuenta lo siguiente al configurar los comandos de complemento en la cinta de opciones.

• Coloque los comandos en una pestaña existente, como las pestañas Insertar y Revisar, 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 en todas las versiones de Office (como Office en la Web o escritorio) y una pestaña no está disponible en todas las versiones.
• 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.
• Asegúrese de que los grupos se contraen correctamente cuando cambie el tamaño de la ventana de la aplicación de Office. Aunque la cinta de opciones ofrece un cambio de tamaño dinámico (consulte Comandos de complemento agrupados en la cinta de opciones), también debe definir combinaciones de grupos para el complemento.
• 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.
• Implemente un cuadro de diálogo para proporcionar a los usuarios opciones avanzadas. Esto impide que el complemento sobrecargue la cinta de opciones con comandos que no se usan con frecuencia. Para obtener información sobre cómo implementar un cuadro de diálogo, vea Usar la API de diálogo de Office en complementos de Office.

Nota:

Es posible que los complementos que ocupan demasiado espacio no pasen la validación de Microsoft Marketplace.

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.