Adición de compatibilidad con acciones principales

Precaución

Esta versión está disponible actualmente como una versión beta pública disponible para pruebas.

Para entornos de producción, le recomendamos que use la versión de SPFx a la que se hace referencia en Configurar el entorno de desarrollo de SharePoint Framework.

En la actualidad, los usuarios deben tener en cuenta los paneles de propiedades del elemento web para averiguar las opciones adicionales que proporciona cada elemento web. Se trata de un fragmento de comentarios común en el que los usuarios quieren que las acciones se resalten en el contexto de dónde están sin tener que depender de la apertura de algo para llegar a esas opciones. Por lo tanto, ahora podemos exponer las configuraciones más comunes desde el panel de propiedades de un elemento web directamente en la barra de herramientas del elemento web. Estas configuraciones comunes se conocen como acciones principales del elemento web.

Importante

Esta característica sigue siendo un estado de vista previa como parte de la versión 1.16 y no debe usarse en producción. Estamos pensando en publicarlos oficialmente como parte de la próxima versión 1.17. En el momento de escribir este artículo, Acciones principales solo admite la representación de un comando desplegable y de botón.

Introducción

Sugerencia

En estas instrucciones se supone que sabe cómo crear un elemento web hello world.

Definición de las configuraciones de la acción superior

En el ejemplo siguiente se define la función de devolución de llamada que se usará para extraer las configuraciones de nuestros comandos de acción superior.

Nota:

getTopActionsConfiguration debe definirse como público en la clase del elemento web.

import { ITopActions } from '@microsoft/sp-top-actions';

public getTopActionsConfiguration(): ITopActions | undefined {
  return {
    topActions: [],
    onExecute: (actionName: string, newValue: any) => {}
  };
}

Definición de la interfaz de usuario de la barra de herramientas

La topActions matriz es una lista ordenada de controles que se van a representar en la barra de herramientas del elemento web. En el ejemplo siguiente se define una acción superior como una interfaz de botón.

import { PropertyPaneFieldType } from '@microsoft/sp-property-pane';

return {
  topActions: [
    {
      targetProperty: 'reset',
      properties: {
        icon: 'Reset'
      },
      type: PropertyPaneFieldType.Button
    }
  ]
  ...
}

Ejecute el comando cuando el usuario interactúe

En el paso anterior se mostró cómo obtener un botón para mostrarlo en la barra de herramientas del elemento web. Ahora realizaremos una acción cuando el usuario seleccione el botón. Tenga en cuenta que se definió como targetProperty en el último paso y, dado que actionName se trata de un botón, podemos pasar por alto lo newValue que aparece.

return {
  ...
  onExecute: (actionName: string, newValue: any) => {
    if (actionName === 'reset') {
      // user defined logic to reset the web part
      this.reset();
    }
  }
}

Sugerencia

El problema común al implementar el onExecute comando es no sincronizar el nuevo estado con las propiedades del elemento web o no actualizar o volver a representar el elemento web.

Fragmentos de código

Comando de botón

El tipo interace de un botón es similar al botón del panel de propiedades (IPropertyPaneButtonProps).

import { ITopActions } from '@microsoft/sp-top-actions';
import { PropertyPaneFieldType } from '@microsoft/sp-property-pane';
...
public getTopActionsConfiguration(): ITopActions | undefined {
  return {
    topActions: [
      {
        targetProperty: 'reset',
        type: PropertyPaneFieldType.Button,
        properties: {
          icon: 'Reset'
        }
      }
    ],
    onExecute: (actionName: string, newValue: any) => {
      if (actionName === 'reset') {
        // user defined logic to reset the web part
        this.reset();
      }
    }
  };
}

Comando desplegable

La interfaz de tipo de una lista desplegable es similar al grupo de opciones del panel de propiedades (IPropertyPaneChoiceGroupOption).

import { ITopActions } from '@microsoft/sp-top-actions';
import { PropertyPaneFieldType } from '@microsoft/sp-property-pane';
...
public getTopActionsConfiguration(): ITopActions | undefined {
  return {
    topActions: [{
      targetProperty: 'layout',
      type: PropertyPaneFieldType.ChoiceGroup,
      properties: {
        options: [
          {
            // key maps to newValue in onExecute
            key: 'card',
            text: 'Card Layout',
            imageSize: { width: 32, height: 32 },
            iconProps: { officeFabricIconFontName: 'ArticlesIcon' },
            checked: this.state.layout === 'card'
          },
          {
            key: 'list',
            text: 'List Layout',
            imageSize: { width: 32, height: 32 },
            // you can use iconProps, icon to define icons
            icon: 'List',
            checked: this.state.alignment === 'list'
          }
        ]
      }
    }],
    // for ChoiceGroup drop-down, the newValue tells us which option's key was selected
    onExecute: (actionName: string, newValue: any) => {
      if (actionName === 'layout') {
        this.setLayout(newValue);
        this.render();
      }
    }
  };
}

Configuraciones avanzadas

Para las configuraciones avanzadas de los comandos de acción superior, desproteger las definiciones de tipo de @microsoft/sp-property-pane y @microsoft/sp-top-actions. Actualmente, los dos comandos de acción superior admitidos, button y drop-down, se pueden definir mediante un subconjunto de los tipos IPropertyPaneChoiceGroupOption y IPropertyPaneButtonProps.

• Para IPropertyPaneButtonProps, las propiedades admitidas actualmente son icon, text, , ariaLabeldisabled
• Para IPropertyPaneChoiceGroupOption, el porperty admitido actualmente es options y desde esa matriz se admite key, , iconProps.officeFabricIconFontNametext, imageSize, , checked,title

import { IPropertyPaneButtonProps, IPropertyPaneChoiceGroupOption } from '@microsoft/sp-property-pane'
import { ITopActions } from '@microsoft/sp-top-actions';

Más información

Api de acciones principalesIPropertyPaneButtonPropsIPropertyPaneChoiceGroupOption