Crear una extensión de tarjeta adaptable con acción de geolocalización
Nota:
En este tutorial se asume que ha instalado SPFx v1.14
Para obtener más información sobre cómo instalar SPFx v1.14, vea las notas de la versión de SharePoint Framework v1.14.
Aplicar andamiaje a un proyecto de extensión de tarjeta adaptable
Cree un directorio de proyecto nuevo para el proyecto y cambie la carpeta actual a ese directorio.
Cree un nuevo proyecto ejecutando el generador de SharePoint Yeoman desde el nuevo directorio que creó:
yo @microsoft/sharepoint
En el momento en que se le solicite, introduzca los siguientes valores (seleccione la opción predeterminada para todas las solicitudes que se omiten a continuación):
- ¿Cuál es el nombre de la solución? tutorial de geolocalización
- ¿Cuál es el tipo de componente del lado cliente que se va a crear? Extensión de tarjeta adaptable
- ¿Qué plantilla quiere usar? Plantilla de texto principal
- ¿Cuál es el nombre de su extensión de tarjeta adaptable? Geolocalización
En ese momento, Yeoman instalará las dependencias necesarias y aplicará scaffolding en los archivos de la solución. Este proceso puede tardar unos minutos.
Actualice la dirección URL del área de trabajo hospedada del proyecto.
Cuando use la tarea Gulp serve, de forma predeterminada se iniciará un explorador con la dirección URL del área de trabajo hospedada especificada en el proyecto. La dirección URL predeterminada del área de trabajo hospedada en un nuevo proyecto apunta a una dirección URL no válida.
Busque y abra el archivo ./config/serve.json en el proyecto.
Busque la propiedad
initialPage:{ "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json", "port": 4321, "https": true, "initialPage": "https://enter-your-SharePoint-site/ _layouts/workbench.aspx" }Cambie el dominio
enter-your-SharePoint-sitea la dirección URL de su espacio empresarial y sitio de SharePoint que desee usar para las pruebas. Por ejemplo:https://contoso.sharepoint.com/sites/devsite/_layouts/workbench.aspx.
En este momento, si lo hacegulp serve, verá la tarjetaGeoLocation:
Incorporación de acciones de geolocalización a la extensión de tarjeta adaptable
En este momento, tenemos el código con scaffolding listo para usar. Ahora, vamos a intentar agregar acciones de geolocalización a las experiencias Vista de tarjeta y Vista rápida.
Crearemos una tarjeta que tendrá Vista de tarjeta y Vista rápida. En Vista de tarjeta, proporcionaremos un botón, que mostrará al usuario su ubicación actual y, al hacer clic en la propia Vista de tarjeta, se abrirá Vista rápida.
En Vista rápida, proporcionaremos tres botones que realizarán las siguientes acciones:
- Obtener la ubicación actual del usuario
- Permitir al usuario elegir una ubicación del mapa
- Mostrar una ubicación específica en el mapa
Actualizar las etiquetas que se mostrarán en la tarjeta
Antes de empezar a agregar las acciones, vamos a actualizar primero las cadenas que verá en la tarjeta.
Para ello, busque y abra el siguiente archivo en el proyecto: ./src/adaptiveCardExtensions/geoLocation/loc/es-es.js
Reemplace el contenido de este archivo por:
define([], function() {
return {
"PropertyPaneDescription": "Tutorial on geolocation action in ACE.",
"TitleFieldLabel": "Geolocation",
"Title": "GeoLocation",
"SubTitle": "GeoLocation Actions",
"PrimaryText": "Location Demo",
"Description": "Demonstrating GeoLocation Capabilities",
"ShowCurrentLocation": "My Location"
}
});
A continuación, busque y abra el siguiente archivo en el proyecto: ./src/adaptiveCardExtensions/geoLocation/loc/mystring.d.ts
Agregue lo siguiente:
ShowCurrentLocation: string;
en la interfaz IGeoLocationAdaptiveCardExtensionStrings.
Agregar acciones en Vista de tarjeta
Como se mencionó anteriormente, en Vista de tarjeta, agregaremos un botón que mostrará al usuario su ubicación actual y, al hacer clic en Vista de tarjeta, mostraremos la experiencia Vista rápida.
En primer lugar, agregaremos la funcionalidad del botón en Vista de tarjeta. Para ello, busque y abra el siguiente archivo en el proyecto: ./src/adaptiveCardExtensions/geoLocation/cardView/CardView.ts
En este caso, reemplace la definición de la función cardButtons por lo siguiente:
public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
return [
{
title: strings.ShowCurrentLocation,
action: {
type: 'VivaAction.ShowLocation'
}
}
];
}
Con este cambio, hemos configurado un botón con la etiqueta My Location y la acción al hacer clic es VivaAction.ShowLocation, que mostrará al usuario su ubicación actual.
A continuación, reemplace el contenido de la función onCardSelection por lo siguiente:
public get onCardSelection(): IQuickViewCardAction | IExternalLinkCardAction | undefined {
return {
type: 'QuickView',
parameters: {
view: QUICK_VIEW_REGISTRY_ID
}
};
}
Este cambio implica que cuando un usuario hace clic en Vista de tarjeta, se debe abrir Vista rápida para él.
Con los cambios realizados hasta ahora, Vista de tarjeta tendría el siguiente aspecto:
Agregar acciones en Vista rápida
En Vista rápida, se introducirán botones para 3 acciones:
- Obtener la ubicación actual del usuario
- Permitir al usuario elegir una ubicación del mapa
- Mostrar una ubicación específica en el mapa (en nuestro ejemplo se mostrará el monte Everest)
Además, tendremos dos bloques de texto para mostrar Latitude y Longitude, que mostrarán las coordenadas respectivas cuando se ejecute la acción VivaAction.GetLocation (más adelante).
En primer lugar, definiremos la plantilla de Vista rápida. Para ello, busque y abra el siguiente archivo en el proyecto: ./src/adaptiveCardExtensions/geoLocation/quickView/template/QuickViewTemplate.json
Reemplace el contenido de este archivo por el siguiente.
{
"schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.2",
"body": [
{
"type": "TextBlock",
"text": "${latitude}"
},
{
"type": "TextBlock",
"text": "${longitude}"
}
],
"actions": [
{
"title": "Choose location on map",
"type": "VivaAction.GetLocation",
"parameters": {
"chooseLocationOnMap": true
}
},
{
"title": "Get my location",
"type": "VivaAction.GetLocation"
},
{
"title": "Show custom location",
"type": "VivaAction.ShowLocation",
"parameters": {
"locationCoordinates": {
"latitude": 27.98884062493244,
"longitude": 86.9249751
}
}
}
]
}
Con esto, proporcionamos dos bloques de texto para mostrar los Latitude y Longitude de la ubicación que obtenemos a través de VivaAction.GetLocation. Además de estas, hemos descrito tres acciones de geolocalización.
Después de agregar estas acciones, Vista rápida tendría el siguiente aspecto:
Configurar el estado de la extensión de tarjeta adaptable
Hasta ahora, hemos creado Vista de tarjeta y Vista rápida. Si realiza una gulp serve en este momento, podrá realizar las acciones descritas anteriormente.
Pero ahora, vamos a ir al siguiente nivel.
Ahora queremos mostrar las coordenadas de la ubicación actual del usuario o la ubicación elegida del usuario en Vista rápida cuando se ejecuten las acciones respectivas.
Para ello, aprovecharemos los dos bloques de texto que hemos introducido anteriormente en el archivo QuickViewTemplate.json
Para ello, primero introduciremos nuevos estados. En primer lugar, busque y abra el siguiente archivo en el proyecto: ./src/adaptiveCardExtensions/geoLocation/GeoLocationAdaptiveCardExtension.ts
Aquí, agregue el siguiente states a la interfaz IGeoLocationAdaptiveCardExtensionState:
latitude: string;
longitude: string;
A continuación, en la función onInit, cambie this.state={} a
this.state = {
latitude: 'TBD',
longitude: 'TBD'
};
Ahora también realizaremos cambios similares en Vista rápida.
Busque y abra el siguiente archivo del proyecto: ./src/adaptiveCardExtensions/helloWorld/quickView/QuickView.ts
Agregue las siguientes propiedades a la interfaz IQuickViewData:
latitude: string;
longitude: string;
y agregue las dos líneas siguientes en el objeto devuelto de data captador:
latitude: "Latitude: " + this.state.latitude,
longitude: "Longitude: " + this.state.longitude
Implementar la función onAction
Hasta ahora, hemos creado acciones de geolocalización definidas y cableadas en nuestros estados. Por último, podemos implementar la función onAction, lo que permite al desarrollador de terceros decidir qué quiere hacer con las coordenadas de ubicación que el usuario ha compartido con él.
Para ello, abra el archivo QuickView.ts (./src/adaptiveCardExtensions/geoLocation/quickView/QuickView.ts) e importe la interfaz IGetLocationActionArguments de la siguiente manera:
import {IGetLocationActionArguments} from '@microsoft/sp-adaptive-card-extension-base';
Por último, presente la siguiente función onAction en la clase QuickView:
public onAction(action: IGetLocationActionArguments): void {
if (action.type === 'VivaAction.GetLocation') {
this.setState({
latitude: action.location.latitude.toString(),
longitude: action.location.longitude.toString()
});
}
}
Ahora, cada vez que la acción VivaAction.GetLocation se desencadene desde Vista rápida y en función de los parámetros que se pasasen, el marco de extensión de tarjeta adaptable pasará las coordenadas actuales del usuario o las coordenadas elegidas del usuario a la devolución de llamada onAction. En la implementación compartida anteriormente, comprobamos si el tipo action es de tipo VivaAction.GetLocation y, si es así, se vuelve a representar Vista rápida mediante una setState, en la que actualizamos los bloques de texto latitude y longitude.
En este punto, puede volver a ejecutar gulp serve y ver cómo se implementaron todos los cambios realizados hasta ahora.
Ya ha terminado. Enhorabuena por crear correctamente la extensión de tarjeta adaptable con acciones de geolocalización.