Scripts et appartenance des composants Studio
Scripts et appartenance des composants Studio
Un composant Studio (DocType Studio Component) est un arbre de blocs réutilisable. Il peut aussi avoir un script qui garde son propre état, ses valeurs calculées et ses gestionnaires, et qui envoie des événements à la page. Cette page décrit le script, les props, l'application propriétaire du composant et la migration des anciennes lignes d'entrée.
L'éditeur Studio (/studio) n'est pas traduit : ses libellés et ses messages sont en anglais.
Script d'un composant
Le champ Script du composant contient un module JavaScript. Son export par défaut est une définition de composant Vue sans modèle : les blocs du composant forment le modèle.
import { ref, computed } from "vue"
export default {
props: {
title: { type: String, required: true },
price: { type: Number, default: 0 },
max: { type: Number, default: 5 },
},
emits: ["change"],
setup(props, { emit }) {
const quantity = ref(0)
const canAdd = computed(() => quantity.value < props.max)
function add() {
quantity.value += 1
emit("change", quantity.value)
}
return { quantity, canAdd, add }
},
}
- Un bloc lit une prop avec
{{ props.title }}et une valeur retournée parsetuppar son nom, par exemple{{ quantity }}.inputsest l'ancien nom depropset fonctionne encore. setups'exécute dans une instance de composant Vue :ref,computed,watchet les fonctions de cycle de vie fonctionnent. Unsetupasynchrone fonctionne sans<Suspense>.setupdoit retourner un objet. Une fonction retournée est refusée.- Le script accepte seulement
props,emitsetsetup. Une autre clé provoque l'erreur « A component script cannot use … Use only props, emits and setup. ».setupdoit être une fonction. - Un composant lit ses propres props et les valeurs de son
setup, les emplacements (par exempledataItem) et les aides intégréesroute,router,socket,toastetcall. - Si un script mis à jour ne se charge pas ou n'est pas valide, Studio garde le dernier script qui fonctionnait et affiche l'erreur dans l'éditeur.
Props
Un composant déclare ses props uniquement dans son script. Le formulaire des props de l'éditeur lit les props du script et y écrit les modifications.
- Une prop a un type Vue (
String,Number,Boolean,Array,Object…). - Une prop peut avoir un contrôle d'édition, gardé dans la clé
metade la prop :control(textarea,selectoucolorpour une propString),options(liste des choix d'unselect) etdescription. - Changer le type d'une prop dans le formulaire supprime sa valeur par défaut et son contrôle.
- Le formulaire ne peut pas modifier une prop construite à partir d'une variable ou d'un spread : modifiez-la dans le script.
- Les valeurs d'aperçu (Preview values) montrent le composant avec des données dans l'éditeur de composant. Studio ne les enregistre pas.
export default {
props: {
columns: { type: Number, default: 3 },
size: {
type: String,
default: "md",
meta: { control: "select", options: ["sm", "md", "lg"], description: "Taille de la grille" },
},
},
}
Anciennes lignes d'entrée
Le tableau Inputs (libellé non traduit, DocType Studio Component Input) est conservé pour compatibilité et est en lecture seule. Un composant sans script prend ses props de ces lignes, sans type.
- Ajouter ou modifier une ligne est refusé : « You cannot add or edit input rows. Define props in the component's script instead. » (message non traduit). Cette règle ne s'applique pas à l'import des fichiers d'une application, qui peut encore apporter des lignes.
- Le correctif
frappe.studio.doctype.studio_component.patches.move_inputs_to_script_props(déclaré dansfrappe/patches.txt) s'exécute pendantbench migrate. Pour chaque composant créé sur le site (non standard) qui a des lignes et pas de script, il écrit une prop par ligne dans le script, puis supprime les lignes. Les typestext,textarea,selectetcolordeviennentString,numberdevientNumberetcheckboxdevientBoolean. - Le correctif ignore un composant dont une valeur par défaut n'a pas d'équivalent comme défaut de prop : une valeur qui contient une liaison
{{ }}, ou une valeur par défaut sur une ligne de type nombre ou case à cocher. Il liste ces composants dans la console ; déclarez leurs props dans un script. - Le correctif ignore aussi les composants standard (exportés) : leur fichier JSON est leur source, donc le dépôt de l'application doit changer.
Application propriétaire
Le champ Studio App (libellé non traduit) d'un composant désigne l'application qui le possède. Il ne peut être défini qu'à la création.
Dans l'éditeur, la fenêtre Create Component a une case Global Component. Si la case est décochée, le composant appartient à l'application ouverte. Dans les réglages d'un composant, l'interrupteur Global component déplace le composant (voir Déplacer un composant).
| Cas | Nom du document | Disponibilité |
|---|---|---|
| Composant d'application | <application>/<identifiant> | Les pages et composants de cette application. |
| Composant global (sans application) | <identifiant> | Toutes les applications du site, et en dehors d'une application. |
- L'identifiant (
component_id, en lecture seule) est unique dans son application. Deux applications peuvent donc avoir chacune un composantcard. Sans identifiant fourni, Studio le déduit du nom du composant et ajoute un numéro si l'identifiant existe déjà dans la même application. - Les blocs désignent un composant par son identifiant. Pour une application, le composant propre à l'application passe avant un composant global de même identifiant.
- Renommer le document renomme l'identifiant : Studio renomme les fichiers exportés du composant (JSON et script) et met à jour les blocs des pages et des composants qui l'utilisent. Le nouveau nom peut être l'identifiant seul ; un composant ne peut pas changer d'application par un renommage, et deux composants ne peuvent pas être fusionnés.
- Renommer une application renomme ses composants (le nom du document contient le nom de l'application) et réexporte leurs fichiers.
- Le champ virtuel Nom du dossier de Studio App (libellé non traduit) (masqué, en lecture seule) donne le dossier de l'application dans le dossier
studiode son application Frappe.
Composant global : limites
Un composant global s'affiche dans toutes les applications, il ne peut donc pas dépendre des fichiers d'une seule :
- L'enregistrement est refusé (« Script not saved », titre non traduit) si son script importe
@app/…ou un chemin relatif. Importez seulement des bibliothèques commevue. - Si vous modifiez ses blocs et qu'ils utilisent un composant Vue
.vuede l'application, Studio affiche un avertissement : le composant ne fonctionnera pas dans les autres applications.
Déplacer un composant
La méthode Studio Component.set_app(studio_app=None) (accessible via frappe.whitelist) déplace un composant global vers une application, ou rend global un composant d'application quand aucune application n'est donnée.
- Elle exige le droit d'écriture sur le composant et, pour une application cible, sur cette application.
- L'identifiant ne change pas : le nom du document change, pas les blocs qui l'utilisent.
- Rendre un composant global échoue si un composant global avec le même identifiant existe déjà.
- Quand une autre application utilise le composant global, celui-ci reste en place à côté de la copie de l'application. Le retour est
{"name": <nouveau nom>, "is_global_kept": <booléen>}.
Supprimer un composant
La suppression d'un composant est refusée (« Component not deleted », titre non traduit) tant qu'une page ou un autre composant contient un bloc qui le désigne. Le message liste les titres, suivis d'un décompte des utilisations que vous n'avez pas le droit de lire. Studio Component.get_usages() retourne ces titres (None pour une utilisation illisible). Supprimer une application supprime ses composants, qui peuvent s'utiliser entre eux. En mode développeur, la suppression retire aussi les fichiers exportés du composant.
Fichiers du composant
- Le script d'un composant apparaît dans l'explorateur de fichiers de l'éditeur sous
studio_components/<identifiant>.js, que l'application soit en base de données ou exportée. Les API de fichiers (list_studio_files,read_studio_file,write_studio_file) lisent et écrivent le champ Script. L'explorateur liste les composants à script que les pages de l'application utilisent. Une écriture avec un hachage connu est refusée (« {0} changed since you opened it. ») si le script a changé entre-temps. - Pour une application exportée, le dossier
studio_components/contient<identifiant>.jsonet le script<identifiant>.js. Dans une application exportée, le fichier est la copie que le développeur modifie : Studio ne le remplace que si le champ Script a changé, et un fichier existant garde son langage. Un nouveau fichier est en JavaScript. - Dans une application exportée, écrire, renommer ou supprimer
studio_components/<identifiant>.jspar les API de fichiers met aussi à jour le champ Script du composant. - L'export d'une page standard écrit dans
studio_components/les composants que ses blocs utilisent (celui de l'application, sinon le global) et les marque standard. Il supprime les fichiers (JSON et script) des composants qu'aucune page de l'application n'utilise. Le JSON ne contient ni le script ni les champs virtuels. - La compilation de l'application Studio inclut les scripts des composants : les fichiers
studio_components/d'une application exportée, ou le champ Script des composants utilisés par les pages d'une application en base de données.
Copier-coller des blocs entre applications
Un bloc copié emporte les composants qu'il utilise, avec leur script.
- Au collage dans une autre application, un composant d'application devient un composant de l'application cible (
<application cible>/<identifiant>). Un composant global reste global. - Si un composant de même nom existe déjà avec un contenu différent (nom, blocs, script, désactivation ou lignes d'entrée), la fenêtre Pasted block conflicts s'ouvre. Keep existing garde le composant existant. Use copied le remplace : les blocs des autres pages qui l'utilisent changent aussi.
Migrer les composants globaux d'une application exportée
Les composants exportés avant l'introduction de l'appartenance n'ont pas d'application : ils sont globaux. Dans le dépôt de l'application Frappe, pour chaque fichier de <application_frappe>/studio/<application_studio>/studio_components/ :
- Lisez le nom de l'application dans le champ
namede<application_studio>.json(le dossier porte le nom normalisé,mon-appdonnemon_app). - Dans le JSON du composant, ajoutez
studio_app, remplaceznamepar<application>/<identifiant>et définissezis_standardà1. Ne changez nicomponent_id, ni le nom des fichiers, ni les pages. - Convertissez les lignes
inputsen props dansstudio_components/<identifiant>.js, puis retirez la cléinputsdu JSON. La valeur par défaut d'une ligne est un texte : écrivezdefault: "md"pour du texte,default: 3oudefault: truepour un nombre ou une case à cocher, et une fonction pour un tableau ou un objet. Utiliseznullcomme type quand la valeur peut être un tableau ou un objet. - L'import crée le composant d'application et laisse l'ancien enregistrement global. Ajoutez un correctif à l'application qui appelle
sync_studio_apps("<application>")d'abord, puis supprime chaque ancien enregistrement avecfrappe.delete_doc("Studio Component", <identifiant>, force=True). Ne supprimez pas un composant global qu'une application en base de données du site peut utiliser (identifiant générique commeheader). - Vérifiez :
bench --site <site> migrate, ouverture des pages dans l'éditeur et publiées, puisbench build --app <application_frappe>.
Un composant peut aussi cesser de lire les variables, ressources et fonctions de la page : passez les données par des props, déclarez des emits pour les actions de la page, et gérez l'événement dans les événements du bloc sur la page.
Exemple
Exemple fictif. L'application boutique a un composant carte_produit avec un compteur.
- Créez le composant dans l'application
boutique: son nom de document estboutique/carte_produit. - Dans son script, déclarez la prop
title, l'événementchangeet lesetupde l'exemple ci-dessus. - Dans un bloc texte du composant, saisissez
{{ props.title }} : {{ quantity }}. - Sur la page, ajoutez le composant, renseignez
titleet gérez l'événementchangedans les événements du bloc.
Une autre application du site peut avoir son propre carte_produit sans conflit.