Table · Documentation

UITableau

Données structurées pour les interfaces SaaSLien vers la section

Les Tableau Le composant affiche des données structurées et comparables.

Utilisez-le pour:

utilisateurs
projets
factures
Abonnements
logs
rapports
événements audit
admin records

Le tableau fournit une base visuelle cohérente pour les données produit denses :

Structure sémantique de table
design-token style
Débordement horizontal
retour hover ligne
état vide intégré
état de chargement intégré

Idée de base

Utilisez Table lorsque les utilisateurs ont besoin de comparer des enregistrements structurés entre colonnes. Utilisez des cartes lorsque le contenu est plus éditorial, visuel ou axé sur l'action.

ImportationLien vers la section

table-import.tsx

import { Table } from "@pycolors/ui";

Utilisation de baseLien vers la section

Nom	Email	Rôle
Jane Doe	jane — example.com	Admin
John Smith	john — example.com	Utilisateur

Quand utiliser la tableLien vers la section

Utilisez Table lorsque l'interface a besoin de numérisation, de comparaison et de densité opérationnelle.

Enregistrements reproductibles

Utiliser pour les utilisateurs, les projets, les factures, les abonnements, les journaux et les enregistrements d'administration.

Données comparables

À utiliser lorsque les utilisateurs comparent des valeurs entre des colonnes stables.

Vues opérationnelles

Utiliser avec les filtres, la pagination, les actions en ligne et les opérations en bloc.

LégendeLien vers la section

Utilisation TableCaption lorsque la table a besoin d'un résumé concis.

table-caption.tsx

<Table>
  <TableCaption>List of active users</TableCaption>
  {/* rows */}
</Table>

Les sous-titres doivent expliquer ce que contient le tableau, et non répéter le titre de la page.

État videLien vers la section

Utilisation TableEmpty lorsque la requête a réussi mais qu'aucune ligne n'est disponible.

table-empty.tsx

<TableBody>
  <TableEmpty colSpan={3} />
</TableBody>

Règle d'état vide

Vide n'est pas une erreur. Expliquez pourquoi la table est vide et ce que l'utilisateur peut faire ensuite.

État de chargementLien vers la section

Utilisation TableLoading lorsque la structure de la table est connue mais que les données sont toujours en cours de chargement.

table-loading.tsx

<TableBody>
  <TableLoading colSpan={3} />
</TableBody>

Utilisez le chargement des lignes au lieu de supprimer la table de la page.

Cela préserve la mise en page et réduit le saut visuel.

Composition du tableauLien vers la section

Une table de production appartient généralement à une plus grande composition de caractéristiques.

projects-table-section.tsx

export function ProjectsTableSection() {
  return (
    <section className="space-y-4">
      <ProjectsToolbar />
      <Table>
        <ProjectsTableHeader />
        <ProjectsTableBody />
      </Table>
      <ProjectsPagination />
    </section>
  );
}

La table rend la structure.

La couche de fonctionnalité possède:

récupération de données
filtres
tri
pagination
autorisations
mutations
actions en ligne

Règle d'architecture

La table ne doit pas posséder la source de données. Continuez à récupérer, filtrer, trier et les mutations dans le calque de fonctionnalités.

UtilisationsLien vers la section

Définir les colonnes

Choisissez des colonnes stables qui aident les utilisateurs à analyser et à comparer les enregistrements.

Ajouter des états de chargement et de vide

Ne laissez pas la zone de la table vide en attendant les données ou lorsqu'il n'y a pas de données.

Gardez les actions de rangée compactes

Utilisez un menu déroulant pour les actions secondaires et une boîte de dialogue pour la confirmation destructive.

Ajouter la pagination si nécessaire

Utilisez Pagination lorsque le jeu de données est supérieur à une seule page.

Déplacer un comportement complexe dans un motif

Utilisez le modèle de tableau de données lorsque vous avez besoin de filtres, d'actions, d'états de pagination, de chargement, de vide et d'erreur ensemble.

Modèle de table vs carte vs table de donnéesLien vers la section

Situation	Utilisation
Données structurées comparables	Tableau
Éléments visuels ou lourds de contenu	Carte
Petite liste avec une action principale par élément	Carte ou liste personnalisée
Filtres, pagination, actions en ligne, états	Tableaux de données
Chronologie ou flux d'activité	Liste personnalisée
Navigation mobile-first	Cartes ou liste responsive

Règle de décision

La table est primitive. Data Table Pattern est l'expérience produit complète qui l'entoure.

APILien vers la section

Composante

Composante	Désignation
`Table`	Enveloppeur avec traitement de bordure et de débordement
`TableHeader`	Section d'en-tête du tableau
`TableBody`	Partie du corps du tableau
`TableRow`	Ligne de table avec hover feedback
`TableHead`	Cellule de tête
`TableCell`	Cellule de données
`TableCaption`	Légende facultative
`TableEmpty`	Ligne d'état vide
`TableLoading`	Chargement de la ligne d'état

Accessoires TableEmpty

Prop	Type	Par défaut	Désignation
`colSpan`	`number`	—	Nombre de colonnes à couvrir
`title`	`string`	copie par défaut	Titre à l'état vide
`description`	`string`	copie par défaut	État vide description
`className`	`string`	—	Classes personnalisées

Accessoires de table

Prop	Type	Par défaut	Désignation
`colSpan`	`number`	—	Nombre de colonnes à couvrir
`label`	`string`	copie par défaut	Message de chargement
`className`	`string`	—	Classes personnalisées

Tous les composants de la table de base étendent leurs props d'éléments HTML natifs respectifs.

table-props.ts

React.HTMLAttributes<HTMLTableElement>;
React.HTMLAttributes<HTMLTableSectionElement>;
React.HTMLAttributes<HTMLTableRowElement>;
React.ThHTMLAttributes<HTMLTableCellElement>;
React.TdHTMLAttributes<HTMLTableCellElement>;
React.HTMLAttributes<HTMLTableCaptionElement>;

AccessibilitéLien vers la section

Les tables doivent préserver la structure sémantique.

Directives :

utilisation TableHead pour les en-têtes de colonne - il vaut par défaut scope="col", ainsi l'association de colonne est correcte sans n'importe quels accessoires supplémentaires
pass scope="row" explicitement sur a TableHead utilisé comme en-tête de ligne
inclure une légende lorsque le contexte n'est pas évident
éviter d'utiliser des tables pour la mise en page
Gardez les cellules lisibles et concises
s'assurer que les actions de ligne interactives sont accessibles au clavier
éviter de rendre la ligne entière cliquable à moins que l'interaction ne soit claire
utiliser des étiquettes visibles pour les actions de ligne icon-only

Règle d'accessibilité

Les tableaux sont pour les données tabulaires. N'utilisez pas de balisage de tableau uniquement pour aligner visuellement le contenu.

Préférez/évitezLien vers la section

Préférez

clear column headers
Nombre raisonnable de colonnes
états de vide et de chargement
Menu déroulant pour les actions de ligne
Pagination pour de plus grands ensembles de données

Éviter

tables pour le contenu non-tabulaire
trop de colonnes dans des dispositions étroites
blank states pendant le chargement
Dispositions complexes à l'intérieur des cellules
récupération des données à l'intérieur de la table primitive

Directives de copie du produitLien vers la section

Les étiquettes de table doivent être courtes et scannables.

En-têtes de colonne

Prefer concise labels such as Name, Email, Role, Status, Amount, Created, and Actions.

Headers should stay short, stable, and easy to scan across dense tables.

Questions courantesLien vers la section

Tableaux de donnéesCréez des tables SaaS complètes avec des filtres, des paginations, des états et des actions de lignes.Menu déroulantUtilisez le menu déroulant pour les actions de ligne compactes.PaginationNaviguez dans des ensembles de données plus volumineux avec un état de page contrôlé.Vide, chargement et états d'erreurGérer les états de table asynchrones de manière claire et cohérente.