Vistas rápidas de ACE y trabajo con navegadores de vistas

  • 10 minutos

La representación de extensiones de tarjeta adaptable (ACE) se implementa mediante dos tipos diferentes de vistas: CardViews y QuickViews.

En esta unidad, obtendrá más información sobre las vistas rápidas, los navegadores usados en ambos tipos de vistas y algunas técnicas y escenarios comunes para las tarjetas adaptables.

Vista rápida

La vista rápida de una ACE no es visible al principio; CardView es lo que se ve primero en Viva Connections escritorio y móvil.

QuickView se muestra en función de la interacción del usuario con CardView. Esto sucede cuando la ACE se selecciona con el mouse o cuando se selecciona uno de los botones de CardView.

Mientras que CardView para la ACE se implementa en ./[..]/cardView/CardView.ts archivo, las vistas rápidas están en ./[..]Carpeta /quickView . El archivo de QuickView.ts inicial creado por el generador de Yeoman contiene tres métodos.

QuickView.template()

El template() método devuelve el código JSON de una tarjeta adaptable que define la representación de QuickView:

public get template(): ISPFxAdaptiveCard {
  return require('./template/QuickViewTemplate.json');
}

Mientras que las plantillas de tarjeta adaptable predeterminadas se encuentran en ./[..]Carpeta /quickView/template , eso no es un requisito. El método solo necesita devolver el JSON que se usa para implementar la tarjeta adaptable para QuickView.

QuickView.data()

De forma similar a CardView, el data() método devuelve un objeto enlazado a la plantilla de QuickView mediante plantillas de tarjeta adaptable. Las propiedades de este objeto deben coincidir con las propiedades esperadas que se usan en la implementación de la tarjeta adaptable de QuickView.

Por ejemplo, el siguiente data() método...

public get data(): IQuickViewData {
  return this.state.listItems[this.state.currentIndex]);
}

... devuelve un objeto que contiene todas las propiedades del elemento seleccionado actualmente en la listItems matriz. Estas propiedades, incluida la propiedad , y Description del elemento de IDlista, se esperan en la plantilla de tarjeta adaptable asociada, como puede ver en la ${} notación usada por las tarjetas adaptablesTitle:

{
  "type": "Container",
  "items": [
    {
      "type": "TextBlock",
      "text": "(${ID}) ${Title}",
      "horizontalAlignment": "Center",
      "size": "Medium",
      "weight": "Bolder",
      "wrap": true
    },
    {
      "type": "TextBlock",
      "text": "${Description}",
      "horizontalAlignment": "Center",
      "size": "Default",
      "wrap": true
    }
  ]
}

QuickView.onAction()

Por último, el SharePoint Framework (SPFx) llama al onAction() método cuando se genera una acción dentro de la representación de tarjeta adaptable. Entre las acciones se incluyen Enviar acciones o cuando la ACE usa las funcionalidades de selección de medios o ubicación geográfica admitidas por Viva Connections:

public onAction(action: IActionArguments): void {
  if (action.type !== 'Submit') { return ;}

  if (action.id === 'next') {
    let currentIndex = this.state.currentIndex;
    this.setState({ currentIndex: currentIndex + 1 });
  }
}

Navegadores de vistas ace

Otra cosa con la que los desarrolladores de ACE deben estar familiarizados son los navegadores de vistas. La ACE usa los navegadores de vistas para realizar un seguimiento de todas las vistas cardview y vistas rápidas que puede usar la ACE.

Registro de cardviews y vistas rápidas

Los dos tipos de vistas deben registrarse primero con sus respectivos navegadores de vistas antes de poder usarlos. El registro implica establecer el identificador de la vista y el objeto que implementa la vista.

El archivo principal que contiene la clase que define la ACE, el archivo *AdaptiveCardExtension.ts , contiene los identificadores de todas las vistas.

Normalmente, el módulo no exporta el identificador de cardviews porque solo se hace referencia a él dentro de la clase definida en el mismo archivo:

const CARD_VIEW_REGISTRY_ID: string = 'SharePointRest_CARD_VIEW';

Sin embargo, los identificadores de QuickView se exportan desde este módulo porque se hace referencia a ellos en CardView y en otras vistas rápidas:

export const QUICK_VIEW_REGISTRY_ID: string = 'SharePointRest_QUICK_VIEW';

El registro de todas las vistas se realiza en el método de onInit() la ACE. Observe cómo el código siguiente pasa dos parámetros: el identificador de la vista y una instancia del objeto de vista:

import { CardView } from './cardView/CardView';
import { QuickView } from './quickView/QuickView';

// .. omitted for brevity

export default class SharePointRestAdaptiveCardExtension extends BaseAdaptiveCardExtension<
  ISharePointRestAdaptiveCardExtensionProps, ISharePointRestAdaptiveCardExtensionState> {
  // .. omitted for brevity

  public async onInit(): Promise<void> {
    // .. omitted for brevity

    this.cardNavigator.register(CARD_VIEW_REGISTRY_ID, () => new CardView());
    this.quickViewNavigator.register(QUICK_VIEW_REGISTRY_ID, () => new QuickView());

    // .. omitted for brevity
  }

  // .. omitted for brevity
}

Trabajar con los navegadores de vista

Ambos navegadores de vista, y cardViewNavigatorquickViewNavigator son básicamente pilas o matrices que contienen vistas. El elemento de la parte superior de la pila es lo que representa el motor de representación de SPFx ACE a menos que se especifique una vista específica.

Veamos cómo podemos interactuar con el navegador de vistas mediante algunas implementaciones de QuickView. Imagine la siguiente situación:

Quiere mostrar una vista rápida con un formulario para recopilar información de un usuario. Esto se puede desencadenar mediante un botón en CardView. El CardView.cardButtons() método puede devolver un botón con action.type establecido en QuickView. El view parámetro indica a SPFx qué vista rápida se va a mostrar. SPFx usa el identificador para buscar y mostrar quickview:

public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
  return [{
    title: 'Book a Trip',
    action: {
      type: 'QuickView',
      parameters: { view: QUICK_VIEW_START_TRIP_REGISTRY_ID }
    }
  }];
}

Captura de pantalla de una activación de QuickView desde una instancia de CardView.

QuickView contiene algunos botones. Los dos primeros botones son acciones que inician otras vistas rápidas para recopilar información adicional del usuario:

export class StartTrip extends BaseAdaptiveCardView<
  ICampusShuttleAdaptiveCardExtensionProps,
  ICampusShuttleAdaptiveCardExtensionState,
  IStartTripData
> {
  // .. omitted for brevity

  public onAction(action: IActionArguments): void {
    if (action.type === 'Submit') {
      if (action.id === 'originLocation') {
        this.quickViewNavigator.push(QUICK_VIEW_SET_ORIGIN_REGISTRY_ID);
      } else if (action.id === 'destinationLocation') {
        this.quickViewNavigator.push(QUICK_VIEW_SET_DESTINATION_REGISTRY_ID);
      } else if (action.id === 'save') {
        (async () => {
          await upsertListItem(this.context, this.properties.listId, this.state.currentTrip);
          this.quickViewNavigator.push(QUICK_VIEW_SAVE_TRIP_REGISTRY_ID);
        })();
      }
    }
  }
}

Por ejemplo, si el usuario selecciona el botón Seleccionar o establecer destino de viaje , inicia el selector de destino QuickView llamando al this.quickViewNavigator.push() método . Esto hace que el motor de representación de ACE reemplace el contenido de QuickView mediante la vista rápida diferente:

Captura de pantalla del selector de destino de QuickView.

Después de completar el formulario, cuando el usuario selecciona el botón Guardar ubicación de destino , el onAction() controlador de esa vista rápida actualiza primero el estado del componente y, a continuación, extrae la vista rápida actual del navegador, lo que hace que el formulario inicial QuickView esté en la parte superior y se vuelva a representar:

public onAction(action: IActionArguments | IGetLocationActionArguments): void {
  const currentTrip = this.state.currentTrip;

  // logic to handle updating the trip destination object
  //    based on the selection in the form

  this.setState({ currentTrip: currentTrip });
  this.quickViewNavigator.pop();
}

Cuando el usuario selecciona el botón Guardar viaje en el formulario inicial, la vista rápida que muestra una confirmación de guardado se muestra con el QUICK_VIEW_SAVE_TRIP_REGISTRY_ID identificador:

Captura de pantalla de la confirmación del viaje de guardado de QuickView.

Por último, cuando el usuario selecciona el botón Cerrar final, se cierra toda la vista rápida mediante el close() método en el navegador:

{
  "schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [{
    "type": "TextBlock", "text": "${title}"
  }],
  "actions": [{
    "type": "Action.Submit",
    "id": "close", "title": "Close"
  }]
}

public onAction(action: IActionArguments): void {
  if (action.id === 'close') {
    this.quickViewNavigator.close();
  }
}

Aplazar la carga de vistas rápidas

Los desarrolladores pueden crear ACE complejas mediante varias vistas rápidas para interacciones avanzadas. Si no todos los quickviews los usan la mayoría de los usuarios, es mejor cargarlos solo cuando sea necesario. Esto reduce el tamaño de descarga y acelera la carga de páginas.

Para implementar esto, quite la import instrucción de QuickView que se encuentra normalmente en la parte superior del archivo de componentes de ace:

import { QuickView } from './quickView/QuickView';

A continuación, actualice la quickViewNavigator.register() llamada al método con el código siguiente para cargar el componente solo cuando sea necesario para el entorno de ejecución de SPFx ACE:

// this.quickViewNavigator.register(QUICK_VIEW_REGISTRY_ID, () => new QuickView());
this.quickViewNavigator.register(
  QUICK_VIEW_REGISTRY_ID,
  () => import('./quickView/QuickView').then((c) => new c.QuickView())
);

Resumen

En esta unidad, ha aprendido más sobre QuickViews, los navegadores usados en ambos tipos de vistas y algunas técnicas y escenarios comunes que puede usar en las tarjetas adaptables.