Utiliser le JSON de mise en forme des colonnes SharePoint dans List Filter Online

Introduction

La mise en forme des colonnes est une fonctionnalité de SharePoint Online qui modifie l'affichage d'une colonne à l'aide d'une description JSON : un état affiché sous forme de pastille colorée, un nombre coloré selon sa valeur, une personne affichée sous forme de lien qui démarre un e-mail. La description est stockée sur la colonne elle-même, et SharePoint l'applique dans chaque vue de la liste.

List Filter Online peut respecter ces descriptions. Lorsque l'option est activée, le composant WebPart lit le JSON de mise en forme de chaque colonne qui en possède un et en tire le rendu des cellules du tableau : le tableau de votre page ressemble ainsi à la liste dont il provient. Le composant WebPart implémente le sous-ensemble couramment utilisé du langage de mise en forme des colonnes ; cet article indique précisément ce qui est pris en charge, ce qui ne l'est pas, et ce qui se passe lorsqu'un format dépasse ce sous-ensemble.

Activer la mise en forme des colonnes

Modifiez la page, ouvrez le volet des propriétés du composant WebPart et développez le groupe Appearance (Apparence). Activez Use column formatting from the list (Utiliser la mise en forme des colonnes de la liste). L'option est désactivée par défaut.

Le JSON lui-même n'est pas saisi dans le composant WebPart. Il provient de la définition de la colonne dans la liste source — la même définition que SharePoint modifie lorsque vous ouvrez Column settings → Format this column dans la liste et enregistrez un format. Le composant WebPart le charge avec les autres propriétés des colonnes ; un format défini sur une colonne d'une liste située sur un autre site est donc appliqué lui aussi. Les formats s'appliquent par colonne : chaque colonne qui porte un format est rendue d'après celui-ci, et les colonnes sans format conservent les formats d'affichage choisis dans le configurateur de colonnes (voir KB10258. Configurer les colonnes dans List Filter Online : légendes, formats et options d'affichage).

Lorsqu'un format est appliqué à une colonne, il remplace entièrement la cellule, y compris l'option Linked to item (Lié à l'élément) de cette colonne. Placez un lien dans le format lui-même si la valeur doit rester cliquable.

Ce qui est pris en charge

Éléments

Un format est une arborescence d'éléments. Chaque élément est un objet comportant les clés suivantes :

• elmType — l'un des types div, span, a, img, button ou p. Toute autre valeur, à l'exception de celles non prises en charge énumérées plus bas, est rendue sous forme de div.
• txtContent — le texte de l'élément : une chaîne littérale, un jeton de champ ou une expression.
• style — les propriétés CSS de l'élément (voir ci-dessous).
• attributes — les attributs HTML de l'élément (voir ci-dessous).
• children — un tableau d'éléments enfants, rendus dans l'ordre.

Les clés que le composant WebPart ne connaît pas, telles que $schema ou debugMode, sont ignorées.

Styles

L'objet style peut définir les propriétés CSS suivantes ; chaque valeur peut être un littéral ou une expression :

background, background-color, border, border-top, border-right, border-bottom, border-left, border-color, border-style, border-width, border-radius, box-shadow, color, cursor, direction, display, fill, flex-direction, flex-wrap, align-items, justify-content, font-family, font-size, font-style, font-weight, letter-spacing, line-height, text-align, text-decoration, text-overflow, text-transform, white-space, word-break, overflow, opacity, visibility, padding, padding-top, padding-right, padding-bottom, padding-left, margin, margin-top, margin-right, margin-bottom, margin-left, width, min-width, max-width, height, min-height, max-height.

Les propriétés qui ne figurent pas dans cette liste — par exemple position ou z-index, qui pourraient perturber la mise en page du tableau — sont ignorées silencieusement. Une valeur qui contient url( est également ignorée : il n'est donc pas possible de charger des images d'arrière-plan par le biais des styles.

Attributs

Les autres attributs, y compris role, aria-*, d et data-interception, sont ignorés.

Jetons de champ

Les jetons peuvent figurer seuls ("txtContent": "@currentField") ou à l'intérieur d'une chaîne plus longue ("txtContent": "Owner: [$Owner.title]"). Une colonne à valeurs multiples (plusieurs personnes, recherches ou termes) est affichée sous la forme d'une liste séparée par des virgules ; l'accès à une propriété telle que [$Owner.email] sur une colonne à valeurs multiples renvoie la propriété de la première valeur. Les valeurs de type personne et recherche affichent leur nom ; les dates s'affichent sous la forme d'une date localisée.

Expressions

Les expressions peuvent être écrites sous forme d'arborescences d'opérateurs — des objets comportant operator et operands — ou sous forme de chaînes commençant par =, avec la syntaxe de type Excel de SharePoint. Les deux formes prennent en charge le même ensemble d'opérations :

• arithmétique : + (également pour la concaténation de chaînes), -, *, /, % ;
• comparaison : ==, !=, >, <, >=, <= — les dates sont comparées d'après leur horodatage ;
• logique : &&, ||, !, la conditionnelle ? : (dans une arborescence, l'opérateur ? ou : avec trois opérandes) et la fonction if(condition, whenTrue, whenFalse) ;
• conversion : toString(), Number(), Date() ;
• nombres : abs(), floor(), ceiling() ;
• chaînes : toLowerCase(), toUpperCase(), indexOf(), substring(), length().

Dans les chaînes =, les littéraux de chaîne s'écrivent entre guillemets simples ou doubles, les nombres en chiffres, les booléens avec true et false ; les parenthèses regroupent les sous-expressions, et les jetons de champ s'utilisent directement : =if([$Priority] == 'High', '#a4262c', '#323130').

Ce qui n'est pas pris en charge

Le composant WebPart n'implémente pas les éléments suivants du langage de mise en forme des colonnes :

• forEach — répétition d'un élément pour chaque valeur d'une colonne à valeurs multiples ;
• customRowAction — boutons qui démarrent un flux, ouvrent un volet ou définissent la valeur d'un champ ;
• elmType: "filepreview" — aperçus de documents ;
• elmType: "svg" et path — graphiques vectoriels intégrés ;
• les jetons @rowIndex, @window, @thumbnail, @currentWeb et les autres jetons non énumérés ci-dessus ;
• les opérateurs et fonctions non énumérés ci-dessus, tels que toLocaleString(), toLocaleDateString(), startsWith(), padStart(), replace(), split(), join(), getDate(), addDays(), getUserImage(), cos() et sin().

Un format qui utilise forEach, customRowAction, filepreview, svg, un opérateur ou une fonction inconnus, un jeton @ inconnu ou qui comporte une erreur de syntaxe dans une expression = ne peut pas être rendu. Dans ce cas, le composant WebPart abandonne le format et rend la colonne avec son affichage par défaut — le format choisi dans le configurateur de colonnes —, exactement comme si l'option était désactivée pour cette colonne. Les autres colonnes ne sont pas affectées. En revanche, les attributs et propriétés de style inconnus sont simplement ignorés, et le reste du format est appliqué.

Exemples

Les formats suivants restent dans le sous-ensemble pris en charge.

Une pastille d'état. La valeur du choix est affichée sur un fond arrondi dont la couleur dépend de la valeur :

{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "div",
  "txtContent": "@currentField",
  "style": {
    "display": "inline-block",
    "padding": "2px 10px",
    "border-radius": "12px",
    "font-weight": "600",
    "color": "#ffffff",
    "background-color": "=if(@currentField == 'Approved', '#107c10', if(@currentField == 'Rejected', '#a4262c', '#8a8886'))"
  }
}

Un nombre coloré selon sa valeur, écrit sous forme d'arborescence d'opérateurs. Les montants supérieurs à 1000 s'affichent en rouge et en gras :

{
  "elmType": "span",
  "txtContent": "@currentField",
  "style": {
    "color": {
      "operator": "?",
      "operands": [
        { "operator": ">", "operands": [ { "operator": "Number()", "operands": [ "@currentField" ] }, 1000 ] },
        "#a4262c",
        "#107c10"
      ]
    },
    "font-weight": "=if(Number(@currentField) > 1000, '700', '400')"
  }
}

Un lien avec une icône. La personne de la colonne Assigned To est rendue sous forme de lien de messagerie avec une icône d'enveloppe ; le format est défini sur la colonne Assigned To elle-même et utilise les propriétés de la valeur de type personne :

{
  "elmType": "a",
  "attributes": {
    "href": "='mailto:' + @currentField.email",
    "title": "=@currentField.title",
    "iconName": "Mail",
    "target": "_blank"
  },
  "txtContent": "@currentField.title",
  "style": {
    "color": "#0078d4",
    "text-decoration": "none"
  }
}

Performances

Le JSON d'une colonne est analysé une seule fois, lors du premier rendu d'une cellule de cette colonne, et l'arborescence analysée est réutilisée pour toutes les autres cellules de la colonne et pour chaque page d'éléments ultérieure. Seuls les jetons et les expressions sont évalués cellule par cellule. L'activation de l'option n'ajoute donc que très peu au temps d'affichage du tableau, même sur de longues pages.

Articles connexes