Studio 1.5.0

Runtime 2.8.0

REDY 16.4.0

Tableau de données

Un acteur qui permet de créer des tableaux de données dynamiques.

Tableau de données

💎 Acteur Avancé

Le tableau de données est un acteur qui nécessite une bonne compréhension de son fonctionnement et de ses propriétés ainsi que des notions de JSON et parfois du JavaScript.

L’entrée des données se fait sous la forme de tableau d’objets JSON. Il est possible de définir des colonnes typées et personnalisées. De nombreux évènements sont disponibles pour interagir avec le tableau ou chaque cellule et avec des boutons de pagination.

Les types de colonnes disponibles sont :

  • texte : pour afficher simplement la donnée d’une cellule,
  • nombre : pour afficher directement un nombre,
  • booléen : pour afficher une valeur vraie ou fausse et définir les textes associés,
  • booléen images : pour afficher une image en fonction de la valeur booléenne et définir les textes associés,
  • date/heure : pour afficher une date ou une heure avec un format personnalisable,
  • personnalisé : pour utiliser un composite comme contenu de la cellule.
Sommaire

🔧 propriété · ℹ️ information · ⚙️ méthode · ⚡ évènement · 🔒 lecture seule

Propriétés

Colonnes

this.properties.columns · any[] · défaut '[]' · modifie : Rendu

Liste des colonnes du tableau.

Cette propriété permet de définir les colonnes du tableau de données. Le JSON est structuré sous la forme d’un tableau d’objets, chaque objet représentant une colonne du tableau de données.

Studio permet de configurer les colonnes via l’inspecteur.

Lorsque vous modifiez une colonne, la prévisualisation du tableau de données n’est pas mise à jour automatiquement. Il faut cliquer sur le bouton “Appliquer les modifications” pour mettre à jour le tableau de données avec les nouvelles définitions de colonnes.

Champs de colonne

Champ Propriété Description
Clé key Clé unique de la colonne ; utilisée pour lier la cellule à la donnée si fieldPath n’est pas défini.
Nom name Nom affiché dans l’en-tête ; laisser vide pour ne pas afficher de nom.
Chemin du champ fieldPath Chemin d’accès dans l’objet de la ligne pour récupérer la valeur ; si vide, key est utilisé.
Visible isVisible Booléen indiquant si la colonne est visible.
Type type Type de la colonne. Valeurs : string, number, boolean, boolean-image, date-time, custom.
Style style Style d’acteur cellule à utiliser pour cette colonne (seuls les styles compatibles sont proposés).
Style d’en-tête headerStyle Style d’acteur cellule pour l’en-tête ; si vide, le style d’en-tête par défaut est utilisé.
Largeur de colonne columnWidth Largeur de la colonne (auto, max-content, valeur fixe, etc.).

Types de colonnes

Type Description
Texte string Affiche la valeur comme du texte.
Nombre number Affiche la valeur comme un nombre.
Booléen boolean Affiche la valeur comme vrai/faux avec un texte.
Booléen image Affiche la valeur comme vrai/faux avec une image et un texte.
Date/heure Affiche la valeur comme une date ou une heure au format par défaut comme 23/12/2025 21:30:00.
Personnalisé Utilise un composite comme contenu de la cellule.

Chaque type de colonne utilise un style de cellule. Des styles par défaut sont fournis pour chaque type :

Type Style par défaut
Texte string Texte table-cell-string
Nombre number Nombre table-cell-number
Booléen boolean Booléen table-cell-boolean
Booléen image Booléen image table-cell-boolean-image
Date/heure Date/heure table-cell-datetime
Personnalisé Personnalisé table-cell-custom

Il est possible de créer d’autres styles d’acteur Cellule de donnée pour les personnaliser. Il seront basés sur les styles par défaut pour les utiliser dans les colonnes de type correspondant.
Voir la page Cellule de tableau de données pour plus de détails.

En-tête ?

this.properties.displayHeader · boolean · défaut true

Indique si l’entête du tableau est visible.

Cette propriété permet d’afficher ou non l’en-tête du tableau de données.

Lignes de données

this.properties.dataRows · string · défaut '' · modifie : Rendu

Lignes de données du tableau.

Cette propriété permet de renseigner un tableau d’objets JSON représentant les lignes de données à afficher dans le tableau de données.

Exemple de données JSON pour cette propriété :

[
  {
    "name": "Robert",
    "age": 23,
    "hasLicence": false
  },
  {
    "name": "Valerie",
    "age": 26,
    "hasLicence": true
  },
  {
    "name": "Bob",
    "age": 32,
    "hasLicence": true
  }
]

Le JSON est stucturé sous la forme d’un tableau d’objets, chaque objet représentant une ligne de données. Chaque propriété de l’objet représente une colonne potentielle du tableau de données.

Nombre de pages

this.properties.pageMax · number · défaut 1

Nombre de pages de la pagination.

Cette propriété permet de définir le nombre maximum de pages pour la pagination du tableau de données.

Pagination ?

this.properties.displayPaging · boolean · défaut true

Indique si la pagination est activée.

Cette propriété permet d’afficher ou non les boutons de pagination du tableau de données. Il faut aussi augmenter le nombre de page avec le champ pageMax pour que les boutons de pagination apparaissent.

Style d’en-tête

this.properties.headerStyle · string · défaut 'table-cell-string-header' · modifie : Rendu

Cette propriété permet de définir le style d’acteur cellule à utiliser pour l’en-tête du tableau de données lorsqu’aucun style spécifique n’est défini dans la colonne.

Par défaut, le style Texte entête table-cell-string-header est utilisé.

Il est possible de définir d’autres styles d’en-tête. Pour cela, il faut créer un style de cellule de tableau de données et le baser sur le style Texte entête table-cell-string-header ou Texte table-cell-string. Ensuite, il sera proposé dans la liste des styles d’acteur cellule d’en-tête.
Voir la page Cellule de tableau de données pour plus de détails.

Informations

Accessibles par script, via this dans un script de l’acteur ou context.getActor('clé') depuis un autre acteur.

canAddActor

this.canAddActor · 🔒 lecture seule · boolean

Pour savoir s’il est possible d’ajouter un acteur.

canClearActors

this.canClearActors · 🔒 lecture seule · boolean

Pour savoir s’il est possible de retirer tous les acteurs.

canRemoveActor

this.canRemoveActor · 🔒 lecture seule · boolean

Pour savoir s’il est possible de retirer un acteur.

childActors

this.childActors · 🔒 lecture seule · Array<BaseActor

Obtiens la liste de tous les acteurs enfants.

Colonnes

this.columns · 🔒 lecture seule

Colonnes visibles du tableau, lues depuis la propriété columns (JSON) et complétées des valeurs par défaut.

Le champ Colonnes permet d’obtenir les définitions des colonnes directement sous forme d’un tableau d’objets à la différence de la propriété qui contient le JSON sous forme de texte.

Ligne de données

this.dataRows · 🔒 lecture seule

Lignes de données du tableau, lues depuis la propriété dataRows (JSON).

Le champ Ligne de données permet d’obtenir les ligne de données directement sous forme d’un tableau d’objets à la différence de la propriété qui contient le JSON sous forme de texte.

headerRow

this.headerRow

Ligne d’en-tête affichée : associe à chaque clé de colonne l’acteur cellule d’en-tête, null sans en-tête.

isLoading

this.isLoading

Indique si le voile de chargement du tableau est affiché.

Numéro de page

this.page

Page courante du tableau (à partir de 1).

Le champ page permet d’obtenir le numéro de la page actuellement affichée dans le tableau de données.

rows

this.rows

Lignes affichées : un objet par ligne, qui associe à chaque clé de colonne l’acteur cellule correspondant.

Nombre de lignes

this.rowsCount · 🔒 lecture seule

Nombre de lignes de données du tableau.

Le champ Nombre de lignes permet d’obtenir le nombre de lignes de données actuellement présentes dans le tableau.

Méthodes

addActor(actorSetup, atIndex)

this.addActor(actorSetup, atIndex) · renvoie Promise<Actor.BaseActor>

Ajoute un acteur enfant. L’acteur est ajouté à la fin de la liste si atIndex n’est pas renseigné. Note: C’est le seul moyen de créer un acteur.

  • actorSetup : Setup JSON de l’acteur à ajouter.
  • atIndex : Position à laquelle l’acteur doit être ajouté.

addActors(actorSetups, atIndexes?)

this.addActors(actorSetups, atIndexes?) · renvoie Promise<Array.<Actor.BaseActor>>

Ajoute une collection d’acteurs enfants. Les acteurs sont ajoutés à la fin de la liste si le tableau d’indexes n’est pas spécifié.

  • actorSetups : Tableau des Setups JSON des acteurs à ajouter.
  • atIndexes : Tableau des indexes où ajouter les acteurs.

changePage(newPage)

this.changePage(newPage)

Affiche la page demandée (entre 1 et pageMax) et déclenche onChangeDataPage.

clearActors()

this.clearActors()

Retire tous les acteurs enfants.

getActor(key)

this.getActor(key) · renvoie Actor.BaseActor

Obtient un acteur enfant par sa clé.

  • key : Clé de l’acteur à trouver.

moveDownActor(key)

this.moveDownActor(key)

Déplace vers le bas un acteur enfant obtenu par sa clé.

  • key : Clé de l’acteur enfant à déplacer.

moveUpActor(key)

this.moveUpActor(key)

Déplace vers le haut un acteur enfant obtenu par sa clé.

  • key : Clé de l’acteur enfant à déplacer.

refreshTable()

this.refreshTable()

Reconstruit les cellules du tableau à partir des colonnes et des lignes de données, puis déclenche onDidTableRender.

removeActor(actorKey)

this.removeActor(actorKey)

Retire un acteur enfant.

  • actorKey : Clé de l’acteur enfant à retirer.

removeActors(…actorKeys)

this.removeActors(...actorKeys)

Retire les acteurs enfants.

  • actorKeys : Clés de l’acteur enfant à retirer.

Événements

Les évènements communs à tous les acteurs sont décrits avec l’acteur de base.

onCellContentTransform

Cet évènement est déclenché lors de la transformation du contenu d’une cellule du tableau de données.

context : contexte d’évènement, avec en plus :

Membre de context Type Description
isHeader Boolean Vrai si c’est une cellule d’en-tête
isCell Boolean Vrai si c’est une cellule
column Object La définition de la colonne
rowKey String La clé de la ligne
columnKey String La clé de la colonne
dataRow Object La ligne de données complète
dataRows Array Toutes les lignes de données
value any La valeur brute de la cellule
cell Object La cellule en cours de rendu
transformedValue any La valeur transformée de la cellule
text String Le texte affiché dans la cellule
content any Le contenu affiché dans la cellule
row Object La ligne en cours de rendu
rows Array Toutes les lignes en cours de rendu

Valeur renvoyée (any) : La valeur transformée de la cellule

C’est le bon moment pour modifier le contenu affiché dans la cellule (texte, image, etc.). Le retour de cet évènement sera dans le champ transformedValue stocké après dans le contexte de l’évènement et utilisé pour l’affichage de la cellule.

onChangeDataPage

context : contexte d’évènement, avec en plus :

Membre de context Type Description
page    

Cet évènement est déclenché lors du changement de page du tableau de données. C’est le bon moment pour modifier les données affichées en fonction de la page demandée. Voir la section La pagination pour plus de détails.

onDidActorAdd

Se produit lorsque un acteur est ajouté.

context : contexte d’évènement, avec en plus :

Membre de context Type Description
addedActor Actor.BaseActor Acteur ajouté.

onDidActorRemove

Se produit lorsque un acteur est retiré.

context : contexte d’évènement, avec en plus :

Membre de context Type Description
removedActor Actor.BaseActor Acteur retiré.

onDidActorsAdd

Se produit lorsque une collection d’acteurs est ajoutée.

context : contexte d’évènement, avec en plus :

Membre de context Type Description
addedActors Array.<Actor.BaseActor> Acteurs ajoutés.

onDidActorsClear

Se produit lorsque la collection d’acteurs est vidée.

context : contexte d’évènement, avec en plus :

Membre de context Type Description
removedActors Array.<Actor.BaseActor> Acteurs retirés.

onDidActorsRemove

Se produit lorsque des acteurs sont retirés.

context : contexte d’évènement, avec en plus :

Membre de context Type Description
removedActors Array.<Actor.BaseActor> Acteurs retirés.

onDidCellRender

Cet évènement est déclenché après le rendu d’une cellule du tableau de données.

context : contexte d’évènement, avec en plus :

Membre de context Type Description
isHeader Boolean Vrai si c’est une cellule d’en-tête
isCell Boolean Vrai si c’est une cellule
column Object La définition de la colonne
rowKey String La clé de la ligne
columnKey String La clé de la colonne
dataRow Object La ligne de données complète
dataRows Array Toutes les lignes de données
value any La valeur brute de la cellule
cell Object La cellule en cours de rendu
transformedValue any La valeur transformée de la cellule
text String Le texte affiché dans la cellule
content any Le contenu affiché dans la cellule
row Object La ligne en cours de rendu
rows Array Toutes les lignes en cours de rendu

C’est le bon moment pour récupérer la cellule rendue et effectuer des actions dessus.

onDidTableRender

Cet évènement est déclenché après le rendu complet du tableau de données.

context : contexte d’évènement, avec en plus :

Membre de context Type Description
headerRow Object La ligne d’en-tête
rows Array Toutes les lignes en cours de rendu

C’est le bon moment pour récupérer le tableau rendu et effectuer des actions dessus.

onWillCellRender

Cet évènement est déclenché avant le rendu d’une cellule du tableau de données.

context : contexte d’évènement, avec en plus :

Membre de context Type Description
isHeader Boolean Vrai si c’est une cellule d’en-tête
isCell Boolean Vrai si c’est une cellule
column Object La définition de la colonne
rowKey String La clé de la ligne
columnKey String La clé de la colonne
dataRow Object La ligne de données complète
dataRows Array Toutes les lignes de données
value any La valeur brute de la cellule
cell Object La cellule en cours de rendu
transformedValue any La valeur transformée de la cellule
text String Le texte affiché dans la cellule
content any Le contenu affiché dans la cellule
row Object La ligne en cours de rendu
rows Array Toutes les lignes en cours de rendu

C’est le bon moment pour modifier la donnée d’une cellule avant son traitement et son affichage.

⚡Evènements souris et tactile

Dans les éèvènements souris et tactile de l’acteur tableau de données, le context contient des informations supplémentaires sur la cellule ou la ligne de données concernée par l’évènement. C’est donc un bon moyen pour interagir avec les cellules du tableau.

Contexte des évènements

Le contexte des évènements contient les informations suivantes :

Champ Type Description
isHeader Boolean Vrai si c’est une cellule d’en-tête
isCell Boolean Vrai si c’est une cellule
column Object La définition de la colonne
rowKey String La clé de la ligne
columnKey String La clé de la colonne
dataRow Object La ligne de données complète
dataRows Array Toutes les lignes de données
value Any La valeur brute de la cellule
cell Object La cellule en cours de rendu
transformedValue Any La valeur transformée de la cellule
text String Le texte affiché dans la cellule
content Any Le contenu affiché dans la cellule
row Object La ligne en cours de rendu
rows Array Toutes les lignes en cours de rendu

Disponibilité des champs dans les évènements

Champ onWillCellRender onCellContentTransform onDidCellRender onDidTableRender Evènements souris
isHeader ✔️ ✔️ ✔️ ❌ ✔️
isCell ✔️ ✔️ ✔️ ❌ ✔️
column ✔️ ✔️ ✔️ ❌ ✔️
rowKey ✔️ ✔️ ✔️ ❌ ✔️
columnKey ✔️ ✔️ ✔️ ❌ ✔️
dataRow ✔️ ✔️ ✔️ ❌ ✔️
dataRows ✔️ ✔️ ✔️ ❌ ✔️
value ✔️ ✔️ ✔️ ❌ ✔️
cell ✔️ ✔️ ✔️ ❌ ✔️
transformedValue ❌ ❌ ✔️ ❌ ✔️
text ❌ ❌ ✔️ ❌ ✔️
content ❌ ❌ ✔️ ❌ ✔️
row Partiellement Partiellement Partiellement ❌ ✔️
rows Partiellement Partiellement Partiellement ✔️ ✔️
headerRow ❌ ❌ ❌ ✔️ ❌

Hérite de

Outre ce qui est décrit ici, l’acteur a tout ce que décrit l’acteur de base : propriétés communes (taille, disposition, aspect, texte, bordures, effets…), évènements communs (cycle de vie, souris, clavier…) et membres accessibles par script.

Il hérite aussi de :

  • LayoutBase : Base pour les acteurs de disposition.
  • Parenthood (comportement) : Étend la classe pour permettre d’avoir des acteurs enfants.

La pagination

Le tableau accèpte la pagination mais doit être implémentée avec l’évènement de changement de page onChangeDataPage.

Pour faire apparaitre les boutons de pagination, il faut activer l’option displayPaging et augmenter le nombre de page avec le champ pageMax dans les propriétés de l’acteur.

En suite, il faut gérer l’évènement onChangeDataPage pour modifier les données affichées en fonction de la page demandée.

L’évènement fournit le numéro de la page demandée dans le champ context.page de l’objet évènement.

exemple d’implémentation de la pagination :

// onChangeDataPage

// taille de chaque page
const pageSize = 10;

const data = [
  /* ... tableau complet des données ... */
];

// Extraction des lignes de données pour la page demandée
const dataPage = data.slice((context.page - 1) * pageSize, context.page * pageSize);

// Mise à jour des lignes de données en fonction de la page demandée. Le format est du JSON texte.
this.properties.dataRows = JSON.stringify(dataPage);

Un exemple d’acteur au complet avec la gestion de la pagination :

SYNAPPS-STUDIO-SCENE|{"config":{"key":"scene158","name":"Tableau de données"},"leadActor":{"type":"layout/stack","key":"stack1","children":[{"type":"layout/stack","key":"stack2","properties":{"width":"910px","horizontalAlignment":"middle","verticalAlignment":"middle","overflowX":"auto","overflowY":"auto"},"children":[{"type":"display/data-table","key":"data-table1","properties":{"columns":"[{\"key\":\"name\",\"newKey\":\"name\",\"name\":\"Nom\",\"type\":\"string\",\"fieldPath\":\"\",\"isVisible\":true,\"headerStyle\":\"\",\"style\":\"table-cell-string\",\"columnWidth\":\"max-content\"},{\"key\":\"age\",\"newKey\":\"age\",\"name\":\"Age\",\"type\":\"number\",\"fieldPath\":\"\",\"isVisible\":true,\"headerStyle\":\"\",\"style\":\"table-cell-number\",\"columnWidth\":\"max-content\"},{\"key\":\"hasLicence\",\"newKey\":\"hasLicence\",\"name\":\"Licence ?\",\"type\":\"boolean-image\",\"fieldPath\":\"\",\"isVisible\":true,\"headerStyle\":\"\",\"style\":\"table-cell-boolean-image\",\"columnWidth\":\"max-content\"},{\"key\":\"birthDate\",\"newKey\":\"birthDate\",\"name\":\"Date de Naissance\",\"type\":\"string\",\"fieldPath\":\"\",\"isVisible\":true,\"headerStyle\":\"\",\"style\":\"table-cell-string\",\"columnWidth\":\"max-content\"},{\"key\":\"na\",\"newKey\":\"na\",\"name\":\"Nom & age\",\"type\":\"string\",\"fieldPath\":\"\",\"isVisible\":true,\"headerStyle\":\"\",\"style\":\"table-cell-string\",\"columnWidth\":\"max-content\"},{\"key\":\"diff\",\"newKey\":\"diff\",\"name\":\"Différence age\",\"type\":\"number\",\"fieldPath\":\"\",\"isVisible\":true,\"headerStyle\":\"\",\"style\":\"table-cell-number\",\"columnWidth\":\"max-content\"},{\"key\":\"_\",\"newKey\":\"_\",\"name\":\"\",\"type\":\"string\",\"fieldPath\":\"\",\"isVisible\":true,\"headerStyle\":\"\",\"style\":\"table-cell-string\",\"columnWidth\":\"auto\"}]","pageMax":5},"events":{"onChangeDataPage":["// chaque page contiendra 4 lignes","const pageSize = 4;","","// tableau complet des données","const allDataRows = this._data;","","// Extraction des lignes de données pour la page demandée","const dataRows = allDataRows.slice((context.page - 1) * pageSize, context.page * pageSize);","","// Mise à jour des lignes de données en fonction de la page demandée. Le format est du JSON texte.","this.properties.dataRows = JSON.stringify(dataRows);",""],"onInit":["// on garde les lignes de données ici.","this._data =","  [","    { \"name\": \"Robert\", \"age\": 23, \"hasLicence\": false, \"birthDate\": \"2002-07-01\" },","    { \"name\": \"Valerie\", \"age\": 26, \"hasLicence\": true, \"birthDate\": \"1999-07-01\" },","    { \"name\": \"Bob\", \"age\": 32, \"hasLicence\": true, \"birthDate\": \"1993-07-01\" },","    { \"name\": \"Alice\", \"age\": 19, \"hasLicence\": false, \"birthDate\": \"2006-07-01\" },","    { \"name\": \"John\", \"age\": 45, \"hasLicence\": true, \"birthDate\": \"1980-07-01\" },","    { \"name\": \"Emma\", \"age\": 28, \"hasLicence\": true, \"birthDate\": \"1997-07-01\" },","    { \"name\": \"Paul\", \"age\": 34, \"hasLicence\": false, \"birthDate\": \"1991-07-01\" },","    { \"name\": \"Sophie\", \"age\": 22, \"hasLicence\": true, \"birthDate\": \"2003-07-01\" },","    { \"name\": \"Lucas\", \"age\": 30, \"hasLicence\": true, \"birthDate\": \"1995-07-01\" },","    { \"name\": \"Marie\", \"age\": 27, \"hasLicence\": false, \"birthDate\": \"1998-07-01\" },","    { \"name\": \"David\", \"age\": 40, \"hasLicence\": true, \"birthDate\": \"1985-07-01\" },","    { \"name\": \"Julie\", \"age\": 21, \"hasLicence\": false, \"birthDate\": \"2004-07-01\" },","    { \"name\": \"Thomas\", \"age\": 36, \"hasLicence\": true, \"birthDate\": \"1989-07-01\" },","    { \"name\": \"Laura\", \"age\": 24, \"hasLicence\": true, \"birthDate\": \"2001-07-01\" },","    { \"name\": \"Antoine\", \"age\": 33, \"hasLicence\": false, \"birthDate\": \"1992-07-01\" },","    { \"name\": \"Clara\", \"age\": 20, \"hasLicence\": false, \"birthDate\": \"2005-07-01\" },","    { \"name\": \"Hugo\", \"age\": 29, \"hasLicence\": true, \"birthDate\": \"1996-07-01\" },","    { \"name\": \"Camille\", \"age\": 25, \"hasLicence\": true, \"birthDate\": \"2000-07-01\" },","    { \"name\": \"Pierre\", \"age\": 38, \"hasLicence\": true, \"birthDate\": \"1987-07-01\" },","    { \"name\": \"Nina\", \"age\": 31, \"hasLicence\": false, \"birthDate\": \"1994-07-01\" }","  ];","","// on en montre que la première page de 4 lignes","const pageDataRows = this._data.slice(0, 4);","","// on l'enregistre dans la propriété des lignes de données","this.properties.dataRows = JSON.stringify(pageDataRows);"],"onCellContentTransform":["// Exemples de transformations :","","// Concaténation de 2 données.","if (!context.isHeader && context.columnKey === 'na') {","  // pour un cellule des lignes de données et lorsqu'elle concerne la colonne Nom & Age.","  return context.dataRow.name + ' - ' + context.dataRow.age;","}","","// Calcul entre deux lignes.","if (!context.isHeader && context.columnKey === 'diff') {","  // pour un cellule des lignes de données et lorsqu'elle concerne la colonne Différence age","  const rowIndexInAllData = (this.page - 1) * 4 + context.rowKey;","  if (rowIndexInAllData >= 1) {","","    // on retourne la différence d'age entre la ligne d'avant et l'actuelle","    return context.dataRow.age - this._data[rowIndexInAllData - 1].age;","  }","}","","// dans tous les autres cellules, on laisse passer la valeur de la donnée.","return context.value;"]}},{"type":"display/html","key":"html1","properties":{"content":"<b>Nombre de lignes : </b> {{rowCount}}<br/>\n<b>Page en cours: </b> {{page}}<br/>\n"},"additionalDefs":{"rowCount":{"type":"text"},"page":{"type":"number"}},"bindings":{"additionals.rowCount":"actor#data-table1@rowsCount","additionals.page":"actor#data-table1@page"}}]}]}}