Composant CardSet

CardSet est utilisé pour restituer plusieurs enregistrements de la même source de données dans une collection de cartes réactives. Il convient aux pages qui nécessitent une navigation rapide des résumés d'entités, tels que les catalogues de produits, les listes d'applications, les catalogues d'actifs et les entrées de connaissances.

Après avoir lu ce manuel, vous pouvez effectuer la configuration suivante :

• Charger des données à l'aide d'un Business Object ou d'une URL personnalisée
• Définir ou importer des champs de réponse réutilisables pour les URL personnalisées
• Choisissez des cartes Standard, Cover ou Compact dans la bibliothèque de modèles visuels
• Mapper les champs d'enregistrement de retour au titre, à la description, à l'image, au statut et aux métadonnées
• Configurer les filtres fixes, les champs de requête et le formulaire de requête
• Définir le nombre de colonnes pour les ordinateurs de bureau, les tablettes et les appareils mobiles
• Choisissez la méthode de tournage de page entre Pagination et Charger plus
• Utilisez Current Record pour configurer des clics de carte entiers et des opérations de carte

CardSet est une collection répétitive basée sur les données et n'est pas utilisée pour gérer manuellement les cartes statiques une par une. Pour les données tabulaires, veuillez utiliser DataList ou ProTable.

1. Préparation avant utilisation

1.1 Sélectionner la source de données

CardSet prend en charge les sources de données suivantes :

Source de données	Scénarios applicables
Source de données du modèle	Les données proviennent de Spark Business Object et nécessitent DQL, des champs de modèle ou un formulaire de requête
URL personnalisée	Les données proviennent de l'API de l'application, d'un service externe ou d'une interface d'agrégation personnalisée

Avant d'utiliser la source de données du modèle, le formulaire de données des scénarios d'objet métier, de champ, de requête et de QUERY doit être complété dans Objects Designer.

L'URL personnalisée doit fournir une collection d'enregistrements paginable. Format de réponse recommandé :

{
  "success": true,
  "data": {
    "current": 1,
    "pageSize": 12,
    "records": [],
    "total": 0
  }
}

1.2 Exemple de cet article

Cet article utilise l'interface du catalogue de produits Spark Sample :

POST https://spark.hiforce.ai/spark/api/sample/cardset/products

L'interface renvoie 23 éléments de données produit en anglais, notamment :

Champ	Objectif
identifiant	Enregistrer la clé unique
code	Titre auxiliaire de la carte
nom	Titre de la carte
description	Description de la carte
imageUrl	Image de couverture
statut	étiquette de statut
catégorie	Classement des produits
prix	Prix ​​du produit
actions	Stock actuel
mis à jourà	Heure de mise à jour

2. Ajouter un jeu de cartes

1. Ouvrez la page cible et entrez Page Designer.
2. Développez Conteneurs dans le panneau des composants de gauche.
3. Faites glisser le CardSet dans le conteneur de pages.
4. Sélectionnez CardSet, configurez d'abord Source de données dans le panneau de propriétés à droite, puis configurez Modèle de carte.
5. Définissez un nom stable pour le contrôle, tel que « productCardSet ».

CardSet ne nécessite plus de deviner un nom de classe Java CardTemplate. L'apparence du modèle et le mappage des champs sont unifiés dans la boîte de dialogue de configuration visuelle.

3. Configurer la source de données

3.1 Exemple d'URL personnalisée

Sélectionnez URL personnalisée dans Source de données et configurez :

Propriétés	Valeurs
URL	/spark/api/sample/cardset/products
Méthode de demande	POST
Chemin des lignes	data.records
Chemin total	data.total
Chemin de la page actuelle	data.current
Chemin de taille de page	data.pageSize

L'URL personnalisée elle-même ne peut pas fournir de métadonnées de modèle comme l'objet métier. Les Champs de réponse doivent donc également être configurés dans la même boîte de dialogue Source de données. L'exemple de configuration dans cet article est le suivant :

Chemin de champ	Étiquette	Type de données
identifiant	ID	NOMBRE
code	Codes	TEXTE
nom	Nom	TEXTE
description	Descriptif	TEXTE
imageUrl	URL de l'image	URL
statut	Statut	TEXTE
catégorie	Catégorie	TEXTE
prix	Prix ​​	NOMBRE
actions	Actions	NOMBRE
mis à jourà	Mis à jour à	DATEHEURE

Les champs de réponse ont deux méthodes de configuration :

1. Cliquez sur le signe plus pour ajouter manuellement le chemin du champ, l'étiquette et le type de données.
2. Après avoir renseigné l'URL, la méthode de demande et le chemin de réponse, cliquez sur Test et importer pour importer à partir de la réponse réelle.

Test & Import lit jusqu'à 20 enregistrements et fusionne les champs qui y apparaissent. Les objets imbriqués généreront des chemins de points sous la forme de « propriétaire.nom » ; les tableaux sont uniquement enregistrés en tant que « ARRAY » et les chemins instables avec des indices de tableau ne seront pas générés. L'importation conservera l'étiquette, le type de données et l'ordre qui ont été modifiés manuellement, ajoutera uniquement les nouveaux champs et ne supprimera pas automatiquement les anciens champs. Lorsque l'interface renvoie un tableau vide ou que la requête échoue, la configuration existante ne changera pas.

Les champs de réponse sont des contrats de champ enregistrés dans la configuration de la page et n'enregistrent pas les exemples de valeurs renvoyées par l'interface. L'ouverture de la boîte de dialogue Source de données n'appellera pas automatiquement l'arrière-plan.

CardSet envoie la page actuelle, le nombre par page, le filtre fixe, la requête rapide et les valeurs du formulaire de requête. Exemple de requête POST :

{
  "current": 1,
  "pageSize": 12,
  "conditions": [
    {"field": "status", "operator": "EQ", "value": "ACTIVE"}
  ],
  "queryFormValues": {}
}

Les requêtes d'URL personnalisées comportent également automatiquement un en-tête de contexte de page unifié :

En-tête	Valeur d'énumération	Descriptif
X-Spark-Page-Environnement	DEV, TEST, PROD	L'environnement de la page actuelle ; l'aperçu dans le concepteur est corrigé pour utiliser DEV
Mode de rendu de page X-Spark	DESIGN_PREVIEW, RUNTIME	Le Concepteur de page, l'aperçu ouvert par le concepteur et l'aperçu de l'enregistrement réel sont « DESIGN_PREVIEW » ; la page d'exécution normale est RUNTIME

Par exemple, la page d'exécution de l'environnement de développement envoie « DEV + RUNTIME » et l'aperçu de l'enregistrement réel dans la boîte de dialogue Modèle de carte envoie « DEV + DESIGN_PREVIEW ». Il s’agit d’une spécification unifiée pour toutes les requêtes backend de Page Designer et Page Runtime, pas seulement pour CardSet. Le backend doit gérer une énumération stable et ne pas déduire de scénarios via Referer ; Les URL personnalisées inter-domaines doivent également autoriser ces deux en-têtes dans « Access-Control-Allow-Headers » de CORS.

3.2 Source de données du modèle

Après avoir sélectionné Source de données du modèle :

1. Sélectionnez Objet métier.
2. Sélectionnez Requête DQL selon vos besoins.
3. Liez les paramètres DQL dans Paramètres de requête.
4. La liste déroulante des champs du modèle de carte utilisera directement les métadonnées du champ de l'objet métier actuel.

La pagination, les paramètres DQL et les conditions de requête de la source de données du modèle sont gérés de manière uniforme par le runtime Spark.

4. Sélectionnez le modèle de carte

Cliquez sur l'icône d'édition sur le côté droit de Modèle de carte pour ouvrir la grande boîte de dialogue de configuration. La bibliothèque de modèles supérieure affichera directement trois aperçus miniatures :

Modèle	Scénarios applicables
Norme	Entités commerciales communes, structure équilibrée du titre, de la description, du statut et des métadonnées
Couverture	Catalogues de marchandisage, de médias et d'actifs avec images de couverture 16:9
Compacte	Atelier d'exploitation et de maintenance ou de gestion, réduisant la zone de description et augmentant la densité de l'information

Après avoir sélectionné un modèle, l'aperçu à droite changera immédiatement. Il n'est pas nécessaire de sauvegarder ou d'accéder à la page d'exécution pour juger de l'apparence du modèle. Le bas de la bibliothèque de modèles est divisé en trois onglets selon le thème : Contenu, Requête et Mise en page et pagination ; l'aperçu de droite est toujours conservé et le bureau, la tablette et le mobile sont utilisés pour modifier la largeur de l'aperçu.

La zone de configuration et la zone d'aperçu peuvent défiler indépendamment. Les champs de carte, les métadonnées et les tonalités d'état dans le contenu utilisent tous un regroupement indépendant ; Les champs de requête et les filtres fixes utilisent également des tables de configuration avec des en-têtes de colonnes. Lorsqu'il existe de nombreuses configurations, vous devez continuer à faire défiler l'onglet actuel vers le bas et la configuration inférieure ne sera pas coupée par la boîte de dialogue.

5. Configurer le mappage des champs

Accédez à l'onglet Contenu pour configurer les champs de la carte, les métadonnées et les tonalités d'état. Le côté droit de chaque champ de carte est marqué avec la zone de la carte dans laquelle il se trouve, par exemple En-tête, Coin, Au-dessus du titre ou Corps ; Le titre est marqué d’une marque rouge obligatoire.

L'exemple de couverture de cet article utilise le mappage suivant :

Zone de carte	Champs
Champ des sourcils	code
Champ de titre	nom
Champ de description	description
Champ d'image	imageUrl
Champ d'état	statut

Le champ titre est le champ d'identification le plus important et doit toujours être configuré. Lorsque les autres champs sont vides, aucun espace vide ne sera conservé dans la zone correspondante.

5.1 Source du champ et chemin personnalisé

Les listes déroulantes de champs sont fournies par source de données :

• La source de données du modèle utilise les métadonnées du champ Business Object.
• L'URL personnalisée utilise des champs de réponse enregistrés.

« Étiquette (chemin) » s'affiche lors de la sélection d'un champ et vous pouvez effectuer une recherche par étiquette ou par chemin. Lorsque vous avez vraiment besoin de lier un champ dynamique non enregistré, sélectionnez Ajouter un chemin personnalisé et remplissez-le manuellement. Les champs réguliers doivent d'abord être ajoutés aux champs de réponse pour éviter la maintenance répétée des chemins de chaînes dans différents CardSets ou ProTables.

Les objets imbriqués utilisent des chemins en pointillés, par exemple :

owner.name
pricing.amount

Le champ de titre est requis pour enregistrer CardSet. Lorsque d'autres mappages facultatifs sont vides, la zone de carte correspondante ne sera pas rendue.

5.2 Actualiser l'aperçu réel

Une fois la source de données et le mappage de champs enregistrés, cliquez sur l'icône d'actualisation à côté du titre Live Preview sur la droite. Le concepteur lira un enregistrement avec pageSize=1 et enverra X-Spark-Page-Environment : DEV et X-Spark-Page-Render-Mode : DESIGN_PREVIEW.

L'actualisation met uniquement à jour la valeur d'affichage de la carte de droite et n'ajoute, ne supprime ou ne modifie pas les champs de réponse. Préserve l'aperçu actuel et la configuration des champs lorsque la demande échoue.

5.3 Configurer les métadonnées

Les métadonnées sont utilisées pour afficher de courtes informations telles que le prix, l'inventaire, la personne responsable ou l'heure de mise à jour. Cliquez sur Ajouter une ligne pour ajouter une nouvelle ligne. Le tableau de configuration affiche en permanence les en-têtes de colonnes Étiquette, Champ et Format :

Propriétés	Descriptif
Étiquette	La courte étiquette apparaissant sur la carte, par ex. Prix
Chemin de champ	Champ de données, tel que « prix »
Formater	TEXT, NUMBER, CURRENCY, DATE ou DATETIME

Les exemples de produits suggèrent d'ajouter :

Étiquette	Champ	Formater
Catégorie	catégorie	TEXTE
Prix ​​	prix	MONNAIE
Actions	actions	NOMBRE

5.4 Configurer les tonalités d'état

Les tonalités d'état sont une carte de couleurs d'état facultative. Le tableau de configuration utilise deux colonnes : Lorsque l'état est égal à et Afficher la tonalité. Par exemple, « ACTIVE » est mappé à « SUCCESS » et « DRAFT » est mappé à « WARNING ». Lorsqu'aucun mappage n'est configuré, CardSet utilise des couleurs sémantiques intégrées pour les valeurs d'état communes et « MUTED » pour les valeurs inconnues.

6. Configurer la requête

Accédez à l'onglet Requête pour configurer le formulaire de requête, afficher la barre de filtre, les champs de requête et les filtres fixes. Le formulaire de requête et Afficher la barre de filtre sont situés dans la barre d'outils supérieure, et les champs de requête et les conditions fixes sont regroupés ci-dessous.

6.1 Champs de requête

Les champs de requête sont affichés sur la première ligne de la zone de requête. Affichage fixe du tableau de configuration des en-têtes de colonnes Champ, Étiquette, Opérateur et Type.

Après avoir sélectionné un champ, le concepteur préremplit la configuration de requête avec l'étiquette et le type de données du champ Champ de réponse ou Objet métier ; l'étiquette et le type de requête peuvent toujours être ajustés. OBJECT et ARRAY n'apparaîtront pas dans les candidats des champs de requête de raccourci.

Exemples de produits recommandés :

Champ	Étiquette	Opérateur	Tapez
nom	Rechercher des produits	J'AIME	TEXTE
catégorie	Catégorie	EQ	TEXTE
statut	Statut	EQ	TEXTE

Les types de date et d’heure sont automatiquement rendus sous forme de sélecteurs de plage. Rechercher, Plus et Réinitialiser se trouvent toujours à droite de la barre de requête.

6.2 Filtres fixes

Les filtres fixes prennent effet à chaque fois que vous effectuez une requête, mais ne seront pas affichés à l'utilisateur actif. Par exemple, pour afficher uniquement les produits valides :

Champ	Opérateur	Valeur
statut	EQ	'ACTIF'

La désactivation de Afficher la barre de filtres masque uniquement la zone de requête utilisateur et ne désactive pas les filtres fixes.

6.3 Formulaire de requête

Le formulaire de requête est un formulaire de requête avancé facultatif. Après avoir sélectionné le formulaire de données du scénario QUERY dans la liste déroulante, cliquez sur Plus pendant l'exécution pour développer le formulaire. Lorsque CardSet utilise Model Data Source, la liste déroulante donnera la priorité à l'affichage du formulaire de requête de l'objet métier actuel ; lors de l'utilisation d'une URL personnalisée, le formulaire QUERY disponible dans l'application s'affichera.

• La source de données du modèle doit sélectionner le formulaire de données QUERY de l'objet métier actuel.
• L'URL personnalisée enverra queryFormValues au backend tel quel, et l'interface interprétera la signification des champs.

7. Configurer la mise en page et la pagination

Accédez à l'onglet Mise en page et pagination pour configurer les numéros de colonnes réactifs, l'espacement, la pagination et les clés uniques de ligne. Le groupe Colonnes réactives utilisera les trois diagrammes d'appareils Desktop, Tablet et Mobile pour afficher le nombre actuel de colonnes en temps réel ; le groupe Paging & Data gère de manière centralisée le mode de pagination, la taille de la page et la clé unique de ligne.

Valeurs par défaut recommandées :

Propriétés	Valeur par défaut
Colonnes de bureau	'4'
Colonnes de tablette	'2'
Colonnes mobiles	'1'
Espacement	PAR DÉFAUT
Taille des pages	'12'
Mode radiomessagerie	PAGINATION
Clé unique de ligne	identifiant

Le mode de pagination prend en charge :

• PAGINATION : Affiche le nombre total et le numéro de page, adapté à la gestion des pages.
• LOAD_MORE : Ajoutez la page d'enregistrements suivante, adaptée à la navigation dans les répertoires.
• NONE : Seules les données actuellement renvoyées par l'interface sont affichées, et le contrôle de rotation de page n'est pas affiché.

Utilisez les contrôles de segment Ordinateur, Tablette et Mobile sur la droite pour vérifier la largeur d'une seule carte ; le nombre de colonnes changera automatiquement en fonction de la largeur de la page pendant le fonctionnement réel.

8. Configurer les interactions

CardSet prend en charge deux niveaux d’interaction :

1. L’événement onClick de la carte entière.
2. L’événement onClick d’une action affichée au bas de la carte.

8.1 Configurer les actions de carte

Les Card Actions se configurent en dehors de la boîte de dialogue Card Template. Sélectionnez le CardSet sur le canevas, puis utilisez la section d’éléments enfants Card Actions dans le panneau de propriétés à droite :

1. Cliquez sur Add child element pour créer une CardAction.
2. Saisissez son Title dans le formulaire d’ajout, puis confirmez. Le concepteur sélectionne automatiquement la nouvelle CardAction.
3. Dans le panneau de propriétés de la CardAction, utilisez le sélecteur Icon commun pour choisir une icône système ou téléverser une image personnalisée.
4. Cliquez sur Interaction, puis ajoutez un événement onClick et les actions à exécuter.

Pour modifier une action existante, cliquez sur sa ligne dans la liste Card Actions. Utilisez la poignée à gauche pour réorganiser les actions. À l’exécution, les trois premières actions apparaissent au bas de chaque carte dans cet ordre. Un clic sur une action bloque la propagation de l’événement et ne déclenche donc pas également le clic de la carte.

8.2 Configurer le clic de la carte entière

Sélectionnez de nouveau le CardSet, cliquez sur Interaction, puis configurez son onClick. Une carte ainsi configurée peut recevoir le focus avec Tab et être activée avec Entrée ou Espace.

8.3 Lire l’enregistrement courant

Avant d’exécuter l’une ou l’autre interaction, CardSet écrit l’enregistrement de la carte sélectionnée dans le contexte d’exécution sous le nom record. Dans l’éditeur Interaction, cette source apparaît sous Current Record ; les actions suivantes peuvent donc lire :

record.id
record.code
record.name

Ces valeurs proviennent de la carte sélectionnée à l’exécution ; elles ne sont pas définies en dur lors de la conception. Pour que l’éditeur propose les bons champs Current Record, configurez les Response Fields d’une Custom URL ou fournissez les métadonnées de champs du Business Object pour une Model Data Source.

8.4 Exemple : Afficher les détails de la carte dans un tiroir

Dans l’exemple View product, deux actions sont configurées sous le même onClick, dans l’ordre suivant :

1. Ajoutez Set component value et nommez l’action Fill product details. Associez les champs Current Record, par exemple record.id, record.code et record.name, aux contrôles correspondants du formulaire dans le tiroir de détails.
2. Ajoutez Open/close dialog/drawer et nommez l’action Open product details. Définissez Target component sur Product details (Drawer) et activez Open target.

Renseignez les valeurs du formulaire avant d’ouvrir le tiroir. L’éditeur Interaction exécute l’Action tree de haut en bas ; si l’ordre est inversé, le tiroir peut afficher brièvement l’enregistrement précédent ou des valeurs vides.

Une fois la configuration terminée, un clic sur View product au bas d’une carte ouvre le tiroir avec les détails de cette carte.

9. Exemple d'implémentation backend

L’exemple de code se trouve à l’adresse :

spark-sample/src/main/java/hiforce/spark/sample/cardset/

La requête de produit réutilise la pagination et le traitement conditionnel de l'exemple ProTable. Le contrôleur CardSet est chargé d’exposer l’URL dédiée ; l'image de couverture est générée par le point de terminaison PNG local et ne repose pas sur des services d'image externes.

Cela peut être vérifié après avoir démarré localement :

curl -X POST 'http://localhost:18080/spark/api/sample/cardset/products' \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: zh-CN' \
  -H 'X-Spark-Page-Environment: DEV' \
  -H 'X-Spark-Page-Render-Mode: DESIGN_PREVIEW' \
  -d '{"current":1,"pageSize":12,"conditions":[{"field":"status","operator":"EQ","value":"ACTIVE"}]}'

Le « data.requestContext » dans l'exemple de réponse fera écho à « l'environnement » et au « renderMode » normalisés pour vérifier que le backend a réellement reçu et traité le contexte de la page. Les interfaces métiers de production peuvent utiliser ce contexte pour sélectionner des données ou effectuer des audits sans nécessiter d'écho.

10. FAQ

Le concepteur n'a que le nom du modèle, pas d'apparence

Assurez-vous d'utiliser la nouvelle icône d'édition Modèle de carte. Le modèle doit être affiché avec trois vignettes ; si l'ancien nom de classe comme « ResourceInfoCard » apparaît toujours, actualisez les métadonnées du concepteur et ajoutez à nouveau le CardSet.

Aucune carte lors de l'exécution

Vérifiez dans l'ordre :

1. Si la source de données a été enregistrée.
2. Si Rows Path pointe vers un tableau.
3. Si le champ titre existe dans l'enregistrement.
4. Vérifiez si la requête dans le réseau du navigateur réussit.
5. Si les filtres fixes excluent tous les enregistrements.

La liste déroulante des champs pour l'URL personnalisée est vide

Ouvrez la source de données et vérifiez si les champs de réponse ont été enregistrés. Vous pouvez l'ajouter manuellement ou utiliser Test & Import après avoir confirmé que l'URL et le chemin des lignes sont corrects. L'actualisation de l'aperçu en direct n'est pas responsable de la génération du catalogue de champs.

Test & Import n'a pas de champs d'importation

Vérifiez l'URL, la méthode de requête, le chemin des lignes et le réseau du navigateur. L'interface doit renvoyer au moins un enregistrement dans les conditions actuelles ; les résultats légaux mais vides ne généreront pas de champs et les champs de réponse doivent être gérés manuellement dans ce cas.

Les images ne s'affichent pas

Le champ Image doit renvoyer une URL d’image accessible au navigateur. Les URL relatives doivent être basées sur le nom de domaine Spark actuel et confirmer que l'interface ne renvoie pas de page de connexion HTML.

Il n'y a aucun changement dans le résultat après l'interrogation

Le backend de l'URL personnalisée doit gérer les « conditions » et les « queryFormValues ». CardSet est uniquement responsable de l'envoi de la sémantique des requêtes et n'effectuera pas de filtrage secondaire sur l'ensemble des données complètes dans le navigateur.

11. Liste de contrôle de configuration

• La source de données peut renvoyer des « enregistrements » et un « total »
• URL personnalisée configurée et champs de réponse enregistrés
• La clé unique de la ligne est unique dans chaque enregistrement
• Le modèle approprié a été sélectionné via la vignette
• Le champ titre est configuré et renvoie une valeur non nulle
• Le modèle de couverture a configuré un champ d'image accessible -[ ] Les métadonnées ne dépassent pas la quantité d'informations requise pour la numérisation des pages
• Les champs de requête et les filtres fixes utilisent des champs et des opérateurs pris en charge par le backend -[ ] Le backend d'URL personnalisé gère correctement deux en-têtes X-Spark-Page-*
• Pas de débordement dans les aperçus sur ordinateur, tablette et mobile
• Pagination ou Load More peuvent lire correctement la page suivante -[ ] Les clics sur la carte et les éléments d'action peuvent lire l'enregistrement actuel