Librairie en cours de développement — API instable, ne pas utiliser en production. Signaler un problème

Ariane

v0.1.0-alpha.18
Sur cette page

Table Sort

Alpha

Affiche un indicateur de tri sur un entête de colonne, avec confirmation asynchrone du résultat. À utiliser pour trier une liste de données côté serveur ou après un traitement asynchrone.

Accessibilité

#Lien direct vers cette section

Pris en charge automatiquement

#Lien direct vers cette section
  • aria-sort est posé et mis à jour sur le <th> ancêtre à chaque changement (none → "none", asc → "ascending", desc → "descending").
  • scope="col" est posé sur le <th> ancêtre s’il est absent — ne remplace jamais un scope existant.
  • Le bouton reçoit aria-disabled="true" (pas disabled) pendant pending — reste focusable ; un nouveau clic pendant cet état annonce “Tri en cours, veuillez patienter.”.
  • Un tooltip (ar-tooltip) expose l’action suivante au survol et au focus : “Trier de A à Z”, “Supprimer le tri alphabétique”, etc.
  • Une région aria-live="polite" annonce l’attente (“Tri en cours…”) puis le résultat, y compris pour les méthodes : confirm() → “Prix : tri croissant appliqué” ; reject() → “Nom : échec du tri.” ; reset() → “Nom : tri supprimé” (silencieux si déjà à none).

Les critères WCAG suivants sont implémentés :

Multi-colonnes

#Lien direct vers cette section

ar-table-sort ne coordonne pas les colonnes entre elles. Deux chemins de réinitialisation sont disponibles :

  • reset() — à utiliser en réponse à une action utilisateur. Annule la demande en attente (sans annonce), remet order à none, annonce “tri supprimé” aux lecteurs d’écran si la colonne était triée, et ne change rien à order si elle était déjà à none. C’est le chemin à privilégier dans un handler ar-table-sort-change pour éviter les tris cumulatifs.
  • element.order = 'none' — silencieux, pour les réinitialisations programmatiques (rafraîchissement de données, changement de contexte) où une annonce AT ne serait pas pertinente.

Voir la variante Multi-colonnes pour un exemple complet. Pour permettre un tri sur plusieurs axes simultanément, ne pas appeler reset() sur les autres colonnes — chaque aria-sort reflètera alors son état réel, et l’utilisateur peut naviguer entre les en-têtes pour connaître l’état de chaque colonne.

Piloté par l’application

#Lien direct vers cette section

order et pending peuvent aussi être pilotés par l’application, par exemple liés à un état de framework. Le composant pose lui-même pending au clic et annonce l’attente. Il se lève dès que l’application affecte order (même à la même valeur) ou remet pending à false : “tri appliqué” est annoncé si order est devenu l’ordre demandé, “échec du tri” sinon. En cas d’échec, réaffectez l’ordre actuel. confirm() et reject() restent disponibles et équivalent à ces affectations.

reject(reason) annonce reason tel quel : le texte n’est pas traduit par le composant, à vous de le localiser. Un pending posé sans clic (chargement initial par exemple) annonce l’attente mais pas d’issue.

Utilisation

#Lien direct vers cette section

Détail de l’événement

#Lien direct vers cette section

L’événement ar-table-sort-change porte un objet detail structuré ainsi :

Champ Type Description
type 'alpha' | 'numeric' | 'date' Type de tri du composant qui a émis l’événement.
currentOrder 'none' | 'asc' | 'desc' Ordre de tri actuel avant le clic.
requestedOrder 'none' | 'asc' | 'desc' Ordre demandé — le cycle suivant dans la séquence.
columnLabel string Libellé textuel de la colonne (contenu du slot du composant).

Consulter les variantes Alphabétique, Numérique et Date pour un exemple d’écouteur ar-table-sort-change.

Exemples

#Lien direct vers cette section

Les exemples de cette page sont affichés avec le thème neutre du starter-kit.

Alphabétique

#Lien direct vers cette section

Tri alphabétique (A → Z / Z → A). Cliquer sur l'entête émet `ar-table-sort-change`. Appeler `confirm()` pour valider le tri ou `reject()` pour annuler.

Nom
Alice
Bob
Voir le code
<table style="border-collapse:collapse;font-family:inherit;">
    <thead>
        <tr>
            <th style="padding:.5rem 1rem;text-align:left;border-bottom:1px solid var(--ar-color-border,#e5e7eb);">
                <ar-table-sort type="alpha" id="demo-alpha">Nom</ar-table-sort>
            </th>
        </tr>
    </thead>
    <tbody>
        <tr><td style="padding:.5rem 1rem;">Alice</td></tr>
        <tr><td style="padding:.5rem 1rem;">Bob</td></tr>
    </tbody>
</table>
<script type="module">
    document.getElementById('demo-alpha').addEventListener('ar-table-sort-change', (e) => {
        setTimeout(() => e.target.confirm(), 300);
    });
</script>

Numérique

#Lien direct vers cette section

Tri numérique (croissant / décroissant).

Prix
10 €
42 €
Voir le code
<table style="border-collapse:collapse;font-family:inherit;">
    <thead>
        <tr>
            <th style="padding:.5rem 1rem;text-align:left;border-bottom:1px solid var(--ar-color-border,#e5e7eb);">
                <ar-table-sort type="numeric" id="demo-numeric">Prix</ar-table-sort>
            </th>
        </tr>
    </thead>
    <tbody>
        <tr><td style="padding:.5rem 1rem;">10 €</td></tr>
        <tr><td style="padding:.5rem 1rem;">42 €</td></tr>
    </tbody>
</table>
<script type="module">
    document.getElementById('demo-numeric').addEventListener('ar-table-sort-change', (e) => {
        setTimeout(() => e.target.confirm(), 300);
    });
</script>

Date

#Lien direct vers cette section

Tri chronologique (plus ancien / plus récent).

Date
2024-01-15
2024-06-03
Voir le code
<table style="border-collapse:collapse;font-family:inherit;">
    <thead>
        <tr>
            <th style="padding:.5rem 1rem;text-align:left;border-bottom:1px solid var(--ar-color-border,#e5e7eb);">
                <ar-table-sort type="date" id="demo-date">Date</ar-table-sort>
            </th>
        </tr>
    </thead>
    <tbody>
        <tr><td style="padding:.5rem 1rem;">2024-01-15</td></tr>
        <tr><td style="padding:.5rem 1rem;">2024-06-03</td></tr>
    </tbody>
</table>
<script type="module">
    document.getElementById('demo-date').addEventListener('ar-table-sort-change', (e) => {
        setTimeout(() => e.target.confirm(), 300);
    });
</script>

Multi-colonnes

#Lien direct vers cette section

Plusieurs colonnes triables — la coordination entre elles est manuelle (voir la section « Multi-colonnes »).

Nom Prix
Alice 42 €
Voir le code
<table style="border-collapse:collapse;font-family:inherit;" id="demo-multi">
    <thead>
        <tr>
            <th style="padding:.5rem 1rem;text-align:left;border-bottom:1px solid var(--ar-color-border,#e5e7eb);">
                <ar-table-sort type="alpha">Nom</ar-table-sort>
            </th>
            <th style="padding:.5rem 1rem;text-align:right;border-bottom:1px solid var(--ar-color-border,#e5e7eb);">
                <ar-table-sort type="numeric">Prix</ar-table-sort>
            </th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td style="padding:.5rem 1rem;">Alice</td>
            <td style="padding:.5rem 1rem;text-align:right;">42 €</td>
        </tr>
    </tbody>
</table>
<script type="module">
    const sorters = document.getElementById('demo-multi').querySelectorAll('ar-table-sort');
    sorters.forEach((sorter) => {
        sorter.addEventListener('ar-table-sort-change', (e) => {
            sorters.forEach((s) => { if (s !== e.target) s.reset(); });
            setTimeout(() => e.target.confirm(), 300);
        });
    });
</script>

Tri en échec

#Lien direct vers cette section

Si le tri échoue, appeler `reject()` — le composant revient à son état précédent sans avancer dans le cycle. `reject('Texte')` annonce ce texte tel quel aux lecteurs d'écran, sans le traduire : à localiser par l'application. Sans argument, l'annonce par défaut est utilisée.

Nom (échec simulé)
Alice
Voir le code
<table style="border-collapse:collapse;font-family:inherit;">
    <thead>
        <tr>
            <th style="padding:.5rem 1rem;text-align:left;border-bottom:1px solid var(--ar-color-border,#e5e7eb);">
                <ar-table-sort type="alpha" id="demo-reject">Nom (échec simulé)</ar-table-sort>
            </th>
        </tr>
    </thead>
    <tbody>
        <tr><td style="padding:.5rem 1rem;">Alice</td></tr>
    </tbody>
</table>
<script type="module">
    document.getElementById('demo-reject').addEventListener('ar-table-sort-change', (e) => {
        setTimeout(() => e.target.reject(), 500);
    });
</script>

Démo interactive

#Lien direct vers cette section

Manipulez les attributs pour voir le code et la preview se mettre à jour.

Nom
Alice
Bob
 
<table style="border-collapse:collapse;font-family:inherit;">
    <thead>
        <tr>
            <th style="padding:.5rem 1rem;text-align:left;border-bottom:1px solid var(--ar-color-border,#e5e7eb);">
                <ar-table-sort type="alpha" id="pg-demo-alpha">Nom</ar-table-sort>
            </th>
        </tr>
    </thead>
    <tbody>
        <tr><td style="padding:.5rem 1rem;">Alice</td></tr>
        <tr><td style="padding:.5rem 1rem;">Bob</td></tr>
    </tbody>
</table>
<script type="module">
    document.getElementById('pg-demo-alpha').addEventListener('ar-table-sort-change', (e) => {
        setTimeout(() => e.target.confirm(), 300);
    });
</script>

Référence API

#Lien direct vers cette section

Import

#Lien direct vers cette section

Si vous utilisez l'autoloader, les composants détectés dans la pages sont chargés automatiquement, donc pas besoin de les importer individuellement.
Pour un import manuel, voici comment vous y prendre.

CDNnpm

Importez ce composant depuis le CDN.

<script type="module" src="https://unpkg.com/@ariane-ui/core/dist/components/table-sort/index.js"></script>

Après avoir installé le paquet via npm, vous pouvez importer le composant ainsi :

import '@ariane-ui/core/dist/components/table-sort/index.js';

Configuration

#Lien direct vers cette section
Attributs et propriétés 3Slots 1Événements 1Méthodes 3

Attributs et propriétés

1 sur 3
typereflète

Type de tri — influe sur les labels accessibles.

Type 'alpha' | 'numeric' | 'date'Défaut 'alpha'

2 sur 3
orderreflète

Ordre actuel. Pilotable par l'application (`el.order = …`) ou via `confirm()` / `reject()`. L'affecter, même à la même valeur, répond à la demande de tri en attente : `pending` est levé et le résultat annoncé (`sortApplied` si `order` est l'ordre demandé, sinon `sortFailed`).

Type 'none' | 'asc' | 'desc'Défaut 'none'

3 sur 3
pendingreflète

Vrai quand un tri a été demandé et attend confirmation. Le composant le pose au clic ; il se lève par `confirm()`, `reject()`, `reset()`, en affectant `order` ou en le remettant à `false`. L'attente est annoncée (`sortPending`) au passage à `true`. Levé par l'application, le résultat est annoncé : `sortApplied` si `order` est devenu l'ordre demandé, sinon `sortFailed`. Posé sans clic, aucun résultat n'est annoncé.

Type booleanDéfaut false

Slots

1 sur 1(default)

Libellé de la colonne.

Événements

1 sur 1
ar-table-sort-changedetail : { id: string | undefined; type: TableSortType; currentOrder: TableSortOrder; requestedOrder: TableSortOrder; columnLabel: string }

Émis au clic quand pending est false.

Méthodes

1 sur 3
confirm()retour : void

Applique le pending order et avance le cycle. Sans effet si pending est false.

2 sur 3
reset()retour : void

Annule la demande en attente, sans annonce, puis remet le tri à "none" et annonce le reset aux lecteurs d'écran. Sans effet sur l'ordre si déjà "none".

3 sur 3
reject()reason: stringretour : void

Annule le pending order. Sans effet si pending est false.

Personnalisation

#Lien direct vers cette section
CSS Parts 3CSS Custom States 1CSS Custom Properties 4

CSS Parts

Utilisez ::part(name) pour styler ces éléments depuis l'extérieur.
Certaines parts indiquent un rôle transverse, partagé avec d'autres composants — voir Personnalisation avancée.

1 sur 3sort-button

Le bouton déclencheur.

2 sur 3action-button

Porté par `sort-button` : bouton qui déclenche une action ponctuelle.

3 sur 3indicator

L'icône de direction de tri.

CSS Custom States

Utilisez le sélecteur :state(name) sur le tag pour styler ce composant en fonction de son état.
Composable avec ::part() pour cibler un élément interne (ar-table-sort:state(name)::part(x)).
Sous Chrome et Edge 125, l'état est exposé avec le préfixe -- (:--name) : voir Compatibilité.

1 sur 1:state(pending)

Un tri a été demandé et attend confirmation.

CSS Custom Properties

1 sur 4--ar-table-sort-indicator-size

Taille de l'icône indicateur asc / desc.

2 sur 4--ar-table-sort-indicator-color

Couleur état neutre.

3 sur 4--ar-table-sort-indicator-active-color

Couleur état actif (asc/desc).

4 sur 4--ar-table-sort-indicator-pending-color

Couleur état pending.

Le libellé d'action affiché au survol/focus du bouton de tri utilise en interne un tooltip, personnalisable via ses tokens --ar-tooltip-* (sur :root pour toutes les instances, ou sur ar-table-sort pour une seule).
Voir les tokens de ar-tooltip.

Traduction

#Lien direct vers cette section

La langue de ce composant suit l'attribut lang de la page (<html lang>).
Vous pouvez appliquer une langue différente à une instance donnée en posant l'attribut lang directement dessus.
Voir la page Traductions pour le détail du mécanisme et la liste des traductions disponibles.

lang étant un attribut HTML natif, il n'apparaît pas dans le tableau « Attributs & Propriétés ».