Composer les interfaces

Partir du Model

Une interface Surface organise les informations et les opérations de votre app. Le Model définit les Fields, les profils de fiche, les Queries et les Actions; la composition choisit les composants qui les présentent et leur disposition. Le Studio et l’AI utilisent le même catalogue Surface.

Pour l’app Clients, commencez par la fiche : une identité reconnaissable, les informations que l’équipe consulte et modifie, puis les commandes et les liens utiles au travail. Les réglages occasionnels restent accessibles dans les paramètres de la fiche.

Choisir les composants

Composant Surface	Options / valeurs attendues	Description
Page, Section, Stack, Grid, Card	Titres, espacement et colonnes selon le composant	Organisent la page et regroupent les informations
RecordLayout	asideWidth obligatoire : standard ou compact; exactement deux enfants Stack	Dispose le contenu principal puis le panneau de relations, sans cadre ajouté
RecordIdentity	recordProfileKey : clé d’un profil de fiche déclaré	Présente l’identité de la fiche courante
RecordField	recordProfileKey et fieldPath, par exemple fields/notes	Affiche un Field prévu dans la Surface avec son contrôle adapté
RecordSettings	recordProfileKey	Donne accès aux Fields placés dans les paramètres
RecordRelations	recordProfileKey et groupKey : groupe de relations déclaré	Présente les objets liés à la fiche
QueryTable	binding : référence à une collection ou section déclarée	Présente une vue de données avec ses colonnes et sa Query
ModelAction	actionKey, label et événement press associé à la même Action	Propose une commande définie dans le Model
Tabs, TabPanel	Groupe, clés et libellés ordonnés, onglet initial et panneau correspondant	Organisent la fiche sans fermer ses composants natifs
ActionGroup	Action principale facultative, Actions secondaires, menu et événements exacts	Hiérarchise les commandes sans modifier leurs droits ou confirmations
HomeHeader, HomeLaunchers	Déclarations de l’accueil du Model	Présentent son titre, son introduction, sa navigation principale et ses Actions de lancement
HomeLayout	Blocs d’accueil enfants	Organise les placements main et aside, empilés sur petit écran
HomeSection	sectionKey et un enfant Query correspondant	Présente un aperçu borné avec son lien vers la collection complète
HomeActivity	blockKey d’un bloc d’activité déclaré	Présente les événements autorisés du journal de l’application

La référence des composants Surface détaille chaque propriété, variante et événement. Utilisez les clés de votre Model : le nom visible d’une section ne remplace pas une référence de Field, de Query ou d’Action.

Exemple : la fiche Client

Le profil client présente l’entreprise Atelier Nord. Dans le Studio, organisez sa fiche de cette façon :

1. Placez RecordIdentity en tête de la fiche avec recordProfileKey égal à client.
2. Ajoutez une section « Suivi du client » contenant un RecordField pour fields/notes et un autre pour fields/status. Le premier présente le texte éditable sous son titre; le second utilise les choix définis dans le Field.
3. Ajoutez RecordSettings pour les informations placées dans les paramètres du profil client.
4. Ajoutez les relations vers les soumissions depuis le groupe déclaré dans le Model. Le panneau affiche quelques liens et permet d’ouvrir la liste complète.
5. Placez une commande « Préparer une soumission » référençant l’Action correspondante du Model.

Les Fields doivent être déclarés et placés dans le profil avant leur utilisation. Pour ajouter une liste de soumissions avec colonnes et filtres, définissez d’abord sa Query et sa vue, puis insérez QueryTable avec le binding correspondant. Les guides Fields, tableaux et Actions détaillent ces étapes.

Disposer l’identité de page et ses Actions

Header, dans la famille de catalogue 0.5.15, dispose exactement deux enfants Stack explicitement déclarés : l’identité de page, puis les Actions. Conservez RecordIdentity, ou le titre et l’introduction déclarés, dans la première région. Placez ActionGroup dans la seconde, ou laissez cette pile vide si la page ne propose aucune commande. Les deux régions restent déclarées.

Header ne demande aucune propriété, n’expose aucun événement et n’ajoute ni Card ni cadre englobant. Ses régions se réorganisent sur petit écran. Les commandes conservent leurs Actions déclarées, permissions, préparation et confirmation; afficher l’en-tête ne les exécute jamais. Vérifiez la famille exacte compatible dans la référence des composants; une nouvelle famille ne met pas à niveau un Model existant.

Disposer le contenu principal et les informations liées

Placez RecordLayout sous l’identité et les commandes de la fiche. Déclarez exactement deux enfants directs Stack : d’abord la région principale, puis la région complémentaire. Leurs clés d’éléments restent libres; « main » et « aside » désignent des positions, pas des slots nommés.

Placez Notes, les Fields éditables et l’éditeur de contenu natif dans le premier Stack. Placez les groupes de relations vers les soumissions, les Tags, les métriques ou les paramètres de fiche dans le second selon le besoin. Ces composants conservent leurs bindings et permissions. Le layout ne devine pas la place d’une relation et ne crée aucun autre éditeur, Form ou geste d’enregistrement.

Choisissez le preset obligatoire asideWidth : standard donne un panneau de 230 px; compact, 220 px. L’intervalle est de 21 px. Sous 850 px, la région complémentaire suit le contenu principal dans une colonne. RecordLayout n’ajoute ni bordure ni Card; ajoutez une Card pour un regroupement visuel voulu, pas autour de chaque région.

La référence du composant indique sa famille exacte de catalogue compatible. Un Model conserve la famille de sa Revision sélectionnée; ajouter un composant d’une autre famille exige une évolution explicite et validée du Model. Les outils Surface prennent en charge les identités et compatibilités. Une version de package logiciel n’est pas une capacité de composant, et ouvrir une fiche ne met pas son Model à jour.

Composer l’accueil du Workspace

Pour l’app Clients, l’accueil rassemble les commandes de l’équipe, les dossiers à reprendre et les changements récents. Déclarez d’abord ces éléments dans le Model, puis composez leur présentation :

1. Placez HomeHeader pour afficher le titre du Workspace, l’introduction et la destination principale de l’accueil. HomeLaunchers présente les Actions de lancement avec leurs libellés et icônes déclarés; afficher l’accueil ne lance aucune Action.
2. Ajoutez HomeLayout, puis un HomeSection pour chaque section à montrer. Sa sectionKey référence la section déclarée; son unique enfant de Query utilise cette même section et cette même vue. Le placement main ou aside provient du bloc d’accueil.
3. Réglez la limite maximumVisible et la destination viewAll dans le bloc. L’aperçu limite les éléments affichés, pas les résultats de la Query. « Voir tout » ouvre la collection avec la même Query et la même vue; recherche, filtres et pagination s’y appliquent à la liste complète.
4. Ajoutez HomeActivity avec la blockKey du bloc d’activité. Il présente les événements du journal, et non une activité déduite des dates de modification des fiches. Un contenu supprimé ou inaccessible n’acquiert ni titre ni lien d’ouverture inventé.

Les sections de reprise du travail présentent l’avancement, les blocages et les prochaines étapes issus des faits de travail Surface. Le nombre de cartes visibles ne sert pas de progression, et la fin d’une Task ne valide pas à elle seule les critères métier. Si les faits sont indisponibles ou périmés, l’accueil le signale au lieu d’afficher une progression nulle ou un journal vide comme s’ils avaient été chargés.

Conserver les saisies et les permissions

Une mise à jour des données conserve le brouillon en cours. Un changement concurrent est présenté à l’usager pour résolution; il ne remplace pas sa saisie silencieusement. Les contrôles de Field, les éditeurs de contenu et les vues utilisent les mêmes opérations Surface pour lire et enregistrer leurs informations.

La présence d’un composant ne donne aucun droit supplémentaire. Les lectures, modifications et Actions restent soumises aux permissions du membre. Avant de publier une modification de l’interface, utilisez la validation et l’aperçu du Model pour vérifier les références et le parcours complet.

Onglets et Actions contextualisées

Tabs organise les parties d’une fiche en onglets déclarés, par exemple Description, Relations et Validation. Chaque TabPanel conserve son contenu et votre saisie lorsque vous affichez un autre onglet. Un même éditeur de Surface n’est pas dupliqué dans plusieurs panneaux. Les libellés, l’ordre et l’onglet initial appartiennent au Model.

ActionGroup distingue une Action principale, les Actions secondaires et un menu. Ces boutons utilisent les mêmes formulaires, permissions et confirmations que les autres points d’entrée. Changer d’onglet ne termine pas une étape; sélectionner un scénario ne constitue pas une preuve de réussite. Le Model et l’interface sélectionnent la version exacte du catalogue qui décrit ces composants, sans modifier silencieusement les applications existantes.

Dans les interfaces composées, ModelAction et ActionGroup retirent les commandes qui ne sont plus éligibles. Une commande éligible reste visible, mais temporairement désactivée pendant une opération. Un geste engagé sur un ancien choix de menu ne peut pas exécuter une Action ou une cible de remplacement. Pour le focus clavier, privilégiez une Page ou le TabPanel sélectionné comme région explicite de reprise; aucun de ces composants n’est obligatoire. Si une commande focalisée disparaît, Surface restitue le focus uniquement à un déclencheur de menu encore présent ou à une région déclarée toujours présente dans le même contexte, et seulement si aucun nouveau geste ou changement de focus n’a eu lieu. Surface ne change pas d’onglet et n’invente pas de destination de reprise lorsqu’aucune n’est déclarée.

Exemples appliqués : Composer la fiche et ses relations

Deux Stack déclarés portent le contenu principal puis les relations, sans cadres supplémentaires. Le preset choisit la largeur du panneau droit.

Configuration

Propriétés du composant RecordLayout.props. Propriétés et valeurs admises.

{
  "asideWidth": "standard"
}

Variante et raccordement

Propriétés du composant RecordLayout.props. Propriétés et valeurs admises.

{
  "asideWidth": "compact"
}

Exemple de disposition UI

La disposition illustrative ci-dessous situe cette configuration dans l’app Clients/Soumissions. Chaque fragment s’insère à l’emplacement indiqué; ses références aux Fields, Queries et Actions correspondent aux déclarations du Model.

1. Identité du client
2. Notes et suivi
3. Paramètres
4. Soumissions liées

SurfaceClients / Atelier NordExemple

Composer les interfacesComposer la fiche et ses relations

Clients

AN

Atelier NordClient actif · Services professionnels

ÉtatActif ⌄

Notes et suivi

Le client souhaite préparer une proposition pour son nouveau projet. Préciser les besoins et confirmer le budget avant la revue.

Texte éditable dans la Surface

Paramètres de la fiche