Conceptos básicos de las ACE: plantillas de tarjeta, CardViews, propiedades y estados
Los clientes pueden personalizar Viva Connections y Viva Inicio de varias maneras para crear experiencias personalizadas para sus clientes.
Los desarrolladores pueden personalizar y ampliar Viva Connections con elementos web creados mediante el SharePoint Framework (SPFx). A continuación, los editores pueden colocar los elementos web en áreas de contenido de las páginas y configurarlos para crear una experiencia personalizada para los usuarios.
Los desarrolladores también pueden crear personalizadores de aplicaciones SPFx, un tipo de extensión SPFx que puede insertar HTML y JavaScript en el encabezado y pie de página de las páginas.
Otro tipo de opción de extensibilidad que los desarrolladores y personalizadores pueden usar para personalizar Viva Connections y Viva Inicio es con extensiones de tarjeta adaptable (ACE). Las ACE son similares a los elementos web, pero usan principalmente tarjetas adaptables para implementar la experiencia del usuario.
En esta unidad, aprenderá qué son las ACE, cómo funcionan y los conceptos básicos de la creación de ACE personalizadas para ampliar la experiencia de Viva Connections y Viva Inicio del usuario.
Extensiones de tarjeta adaptable (ACE)
El panel de Viva Home y Viva Connections y la experiencia móvil se pueden ampliar y personalizar mediante las ACE. Los desarrolladores usan SPFx para crear ACE personalizadas para habilitar experiencias personalizadas en paneles de Viva Connections y la aplicación móvil Viva Connections.
Las ACE permiten a los usuarios ver información rápidamente de un vistazo o interactuar con las tarjetas en una experiencia sencilla y centrada en los dispositivos móviles.
Los desarrolladores pueden crear una nueva ACE mediante SPFx. Microsoft agregó compatibilidad para crear ACE en SPFx v1.13 publicada a finales de 2021. Esto agregó una cuarta funcionalidad de tipo de componente, además de la compatibilidad existente con elementos web, extensiones y componentes de biblioteca.
Una ACE tiene una estructura similar a un elemento web, por lo que si tiene experiencia en la creación de elementos web, el proceso de creación de ACE resultará familiar. Al igual que los elementos web, las ACE se pueden desarrollar y probar mediante el área de trabajo hospedada de SharePoint en un sitio de SharePoint Online existente.
Tipos de tarjeta
Viva Connections y SPFx admiten algunos tipos diferentes de vistas de tarjeta. Estos incluyen la vista de tarjeta básica, la vista de tarjeta de imagen y la vista de tarjeta de texto principal. Cada uno de estos tipos de tarjetas diferentes tiene diferencias sutiles en las propiedades que puede establecer en CardView.
Plantilla de tarjeta básica
La plantilla Tarjeta básica admite dos propiedades:
-
titlede la ACE, que normalmente se establece al crear el proyecto con el generador de Yeoman para el SharePoint Framework. -
primaryTextde la ACE, que se usa para proporcionar un contexto al usuario sobre la tarjeta.
Vista de tarjeta de imagen
La plantilla tarjeta de imagen admite tres propiedades:
-
titlede la ACE, que normalmente se establece al crear el proyecto con el generador de Yeoman para el SharePoint Framework. -
primaryTextde la ACE, que se usa para proporcionar un contexto al usuario sobre la tarjeta. - de
imageUrlla imagen que se va a mostrar en la tarjeta.
Cuando el tamaño de la tarjeta se establece en grande , la imagen se representa a la derecha de la tarjeta, como se muestra en la imagen anterior. Cuando se establece en la *tarjeta de tamaño medio, la imagen se representa por encima del título de la tarjeta.
Vista de tarjeta de texto principal
La plantilla tarjeta de texto principal admite tres propiedades:
-
titlede la ACE, que normalmente se establece al crear el proyecto con el generador de Yeoman para el SharePoint Framework. -
primaryTextde la ACE, que se usa para proporcionar un contexto al usuario sobre la tarjeta. - De
descriptionla ACE se usa para mostrar más información textual al usuario.
Ver tipos
Las ACE se basan en dos tipos de vistas:
CardView
CardView es la vista predeterminada de una ACE cuando se representa. CardViews se representa en uno de dos tamaños: mediano o grande.
La vista media puede contener texto y uno o ningún botón.
La opción de vista grande de CardView puede contener texto, hasta dos botones y, opcionalmente, una imagen.
Al crear una nueva ACE, seleccionará una de las tres plantillas de tarjeta disponibles que definen qué propiedades están disponibles en CardView.
Vista rápida
El otro tipo de vista compatible con las ACE es QuickView. QuickView se representa en función de una interacción con CardView. Se pueden mostrar cuando el usuario selecciona CardView o cuando se selecciona uno de los botones.
A diferencia de CardView, la representación de QuickView se implementa con el esquema JSON de tarjeta adaptable. Los desarrolladores pueden hacer que QuickView sea dinámico mediante la funcionalidad plantillas de tarjeta adaptable , donde los marcadores de posición pueden hacer referencia a los datos enlazados a la plantilla como un objeto independiente.
Por ejemplo, un objeto JSON con una description propiedad se puede enlazar a QuickView:
{
"description": "This is some description to display on the QuickView"
}
Para hacer referencia a la propiedad en la tarjeta adaptable usada por QuickView, use la ${} noción como se indica a continuación:
{
"type": "TextBlock",
"text": "${description}",
"wrap": true
}
Creación de ACE
Los desarrolladores pueden crear tarjetas adaptables con el mismo generador de Yeoman para SharePoint usado para crear elementos web, extensiones y componentes de biblioteca de SPFx.
Exploración de la clase ACE principal
Una ACE se implementa mediante el archivo *AdaptiveCardExtension.ts . Este archivo exporta tres tipos de miembros usados para implementar la ACE:
- interfaces que definen las propiedades públicas y el estado del componente
- constantes que definen identificadores únicos para cada una de las vistas rápidas usadas en la ACE
- una clase que actúa como centro para la ACE
La clase ACE contiene algunos métodos predeterminados similares a un elemento web SPFx.
El onInit() método se usa para controlar las tareas de inicialización de estado, visualización del registro y precarga de datos. Revisaremos este método y algunos de estos problemas más adelante en el módulo:
public onInit(): Promise<void> {
this.state = { };
this.cardNavigator.register(CARD_VIEW_REGISTRY_ID, () => new CardView());
this.quickViewNavigator.register(QUICK_VIEW_REGISTRY_ID, () => new QuickView());
return Promise.resolve();
}
Los getPropertyPaneConfiguration() métodos y loadPropertyPaneResources() se usan para inicializar, configurar y cargar el panel de propiedades de las ACE que tienen propiedades públicas configurables.
Para admitir mejor la experiencia móvil de ACE, el loadPropertyPaneResources() método usa la característica de fragmentación de Webpack para dividir la lógica de negocios en los archivos de script que implementan el panel de propiedades y los cargan cuando se activa el panel de propiedades. Esta optimización hace que todos los usuarios que consumen la ACE no siempre carguen el script del panel de propiedades que no usarán:
protected loadPropertyPaneResources(): Promise<void> {
return import(
/* webpackChunkName: 'HelloWorld-property-pane'*/
'./HelloWorldPropertyPane'
)
.then(
(component) => {
this._deferredPropertyPane = new component.HelloWorldPropertyPane();
}
);
}
protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
return this._deferredPropertyPane?.getPropertyPaneConfiguration();
}
Por último, el renderCard() método es similar al método del render() elemento web. Devuelve el identificador de CardView que se debe usar para representar la ACE:
protected renderCard(): string | undefined {
return CARD_VIEW_REGISTRY_ID;
}
Explorar la clase CardView
CardView para la ACE se implementa en ./[..]/cardView/CardView.ts archivo. El archivo CardView.ts inicial creado por el generador de Yeoman contiene tres métodos.
El cardButtons() método devuelve cero, uno o dos objetos de tipo ICardButton que definen los botones representados en CardView. Las distintas plantillas de CardView restringen cuántos botones se pueden mostrar en función de varios factores. Por ejemplo, la plantilla Tarjeta de texto principal solo puede mostrar dos botones cuando su tamaño está establecido en grande.
public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
return [
{
title: strings.QuickViewButton,
action: {
type: 'QuickView',
parameters: {
view: QUICK_VIEW_REGISTRY_ID
}
}
}
];
}
El data() método devuelve un objeto enlazado a la plantilla de CardView mediante plantillas de tarjeta adaptable. Las propiedades de este objeto deben coincidir con las propiedades admitidas por la plantilla de tarjeta ACE actual seleccionada al crear el proyecto. Por ejemplo, el método siguiente data() es para la plantilla de tarjeta básica:
public get data(): IBasicCardParameters {
return {
primaryText: strings.PrimaryText,
title: this.properties.title
};
}
Por último, el onCardSelection() método se usa para controlar lo que ocurre cuando se selecciona CardView. Por ejemplo, la siguiente implementación abrirá un vínculo en una nueva pestaña del explorador cuando se seleccione CardView:
public get onCardSelection(): IQuickViewCardAction | IExternalLinkCardAction | undefined {
return {
type: 'ExternalLink',
parameters: {
target: 'https://www.bing.com'
}
};
}
Propiedades configurables con ACE
Al igual que los elementos web SPFx, las ACE admiten propiedades configurables para proporcionar a los editores la capacidad de personalizar cada instancia de una ACE. La implementación es similar a los elementos web en el sentido de que las propiedades se definen en una interfaz del mismo archivo que el componente.
Por ejemplo, si la ACE muestra datos de una lista de SharePoint, debe almacenar una referencia al identificador de la lista para que la interfaz de propiedad tenga un aspecto similar al siguiente:
export interface ISharePointRestAdaptiveCardExtensionProps {
title: string;
listId: string;
}
Al igual que los elementos web, el valor predeterminado se puede establecer en el objeto del archivo *.manifest.json del preconfiguredEntries.properties componente.
Una diferencia con respecto a los elementos web es que las ACE están diseñadas en torno a un enfoque de mobile-first. Para el panel de propiedades, como se ha explicado anteriormente, esto se implementa separando el código usado para definir la representación del panel de propiedades del resto del componente. El código inicial creado para una ACE por el generador coloca la definición del panel de propiedades en un archivo independiente:
export class SharePointRestPropertyPane {
public getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
return {
pages: [
{
header: { description: strings.PropertyPaneDescription },
groups: [
{
groupFields: [
PropertyPaneTextField('title', {
label: strings.TitleFieldLabel
}),
PropertyPaneTextField('listId', {
label: 'List ID (GUID)'
})
]
}
]
}
]
};
}
}
Estado del componente ACE
Si ha creado un elemento web SPFx con React, es probable que esté familiarizado con el concepto de estado del componente. Las ACE implementan el mismo concepto en que, cuando cambia el estado, desencadena que la ACE se vuelva a representar.
El estado del componente es accesible no solo en la propia ACE, sino en todas sus vistas. Esto incluye cardview y todas las vistas rápidas usadas por la ACE.
El estado del componente, al igual que sus propiedades públicas, se define en una interfaz del mismo archivo que el componente.
Siguiendo con el escenario de ejemplo de una ACE que muestra datos de una lista de SharePoint, probablemente quiera conservar una copia de todos los elementos recuperados de la lista de SharePoint:
export interface ISharePointRestAdaptiveCardExtensionState {
listTitle: string;
listItems: IListItem[];
}
Al usar el estado en el componente, asegúrese de establecer correctamente su estado inicial en el método del onInit() componente:
public async onInit(): Promise<void> {
this.state = {
listTitle: '',
listItems: []
};
// .. omitted for brevity
}
Después, puede usar el onInit() método para recuperar los elementos de la lista o hacer que algún otro desencadenador de eventos desencadene el mismo proceso. Por ejemplo, puede implementar el onPropertyPaneFieldChanged() método al que se llama cuando se actualiza un campo en el panel de propiedades para hacer lo mismo:
public async onInit(): Promise<void> {
// .. omitted for brevity
if (this.properties.listId) {
Promise.all([
this.setState({ listTitle: await fetchListTitle(this.context, this.properties.listId) }),
this.setState({ listItems: await fetchListItems(this.context, this.properties.listId) })
]);
}
return Promise.resolve();
}
protected onPropertyPaneFieldChanged(propertyPath: string,
oldValue: any,
newValue: any): void {
if (propertyPath === 'listId' && newValue !== oldValue) {
if (newValue) {
(async () => {
this.setState({ listTitle: await fetchListTitle(this.context, newValue) });
this.setState({ listItems: await fetchListItems(this.context, newValue) });
})();
} else {
this.setState({ listTitle: '' });
this.setState({ listItems: [] });
}
}
}
Resumen
En esta unidad, ha aprendido qué son las ACE, cómo funcionan y los conceptos básicos de la creación de ACE personalizadas para ampliar la experiencia de Viva Connections del usuario.