Construit sur l’UI SDK 0.1.0-beta.1 de Vercel. Son API peut changer.
Token input
Un champ de texte sur l’UI SDK de Vercel qui mêle texte saisi et tokens pour des personnes, fichiers et commandes, avec suggestions sur @ et /.
- Composants de formulaire
- 15 parties
- 10 exemples
@tabler/icons-react@ui-sdk/core@ui-sdk/react
pnpm dlx shadcn@latest add https://hextaui.com/r/ui-sdk-token-input.jsonAjoute le composant, les tokens de thème HextaUI et les composants HextaUI dont il dépend.
Ajoutez les tokens de thème à votre CSS global, si ce n’est pas déjà fait.
Installez les dépendances.
pnpm add @ui-sdk/react@0.1.0-beta.1 @ui-sdk/core@0.1.0-beta.1 @tabler/icons-react cnCopiez et collez le code suivant dans votre projet.
components/ui/ui-sdk-token-input.tsx Mettez à jour les chemins d’import selon la configuration de votre projet.
UI SDK ajoute un peu de CSS dans une couche de cascade nommée ui-sdk. Déclarez cette couche en haut de votre feuille de style globale, au-dessus de l’import Tailwind, pour que vos classes l’emportent.
Une valeur est un tableau de texte et de tokens. Chaque token a un type, une value pour votre app et un label lisible. L’éditeur gère son contenu, la sélection et l’annulation, laissez-le donc afficher et passez renderToken pour changer l’apparence d’un token. Sans lui, chaque token affiche son label et un bouton de retrait.
Un TriggerMenu dans l’input propose des tokens quand on tape un déclencheur comme @ ou /. Omettez-le quand votre code fournit les tokens.
Tapez @ pour les fichiers ou / au début pour les skills. Un fichier reste en attente pendant son chargement, et l’envoi marque chaque skill en cours puis terminé avec updateToken(). Entrée envoie et Maj+Entrée ajoute une ligne.
tokenDeletion règle l’effet de Retour arrière sur un token. whole le retire, select le sélectionne d’abord et revert le retransforme en texte.
Un contrôleur issu de createTokenInputController() insère, met à jour et retire des tokens depuis le code. Passez une promesse en resolve pour garder un token en attente jusqu’à sa résolution.
Avec un name, l’input envoie son texte avec chaque token écrit [@label](type:value). required bloque un envoi vide, et la réinitialisation revient à defaultValue.
Avec submitShortcut="mod+enter", Entrée ajoute une ligne et Commande ou Ctrl+Entrée envoie, ce que préfèrent beaucoup de personnes qui écrivent en japonais et en chinois.
Un codec transforme les tokens en texte et inversement, ici en <@id>. Avec copy="label", la copie écrit ce qu’on lit, et le collage restaure quand même les tokens.
Un input désactivé ne prend pas le focus, ne change pas, masque les boutons de retrait et n’envoie rien.
Avec readOnly, le texte reste focalisable, sélectionnable et envoyé, mais la saisie, le collage et le dépôt n’y touchent pas.
L’éditeur suit la direction de la page, et un token reste d’un seul tenant dans un texte de droite à gauche.
| Touche | Action |
|---|---|
| BackspaceDelete | Retire le token avant ou après le curseur, selon tokenDeletion. |
| ←→ | Fait passer le curseur au-delà d’un token en une pression. Il ne s’arrête jamais dedans. |
| ↑↓ | Parcourt les suggestions tant que le menu est ouvert. |
| Enter | Envoie. Menu ouvert, choisit la suggestion en surbrillance. |
| Shift + Enter | Commence une nouvelle ligne. |
| ⌘ + EnterCtrl + Enter | Envoie quand submitShortcut vaut mod+enter. Entrée commence alors une nouvelle ligne. |
| ⌘ + ZCtrl + Z | Annule la dernière étape. La saisie est regroupée, et les collages et changements de token sont des étapes à part. |
| Esc | Ferme les suggestions. |
L’éditeur est une zone de texte multiligne. Un menu de déclencheurs à l’intérieur ajoute aria-autocomplete et aria-haspopup, et le focus reste dans le texte pendant que les flèches parcourent les suggestions. Chaque token se lit avec son label et son type, comme « routes.ts fichier », et son insertion ou son retrait est annoncé. Nommez l’éditeur avec aria-label ou un libellé autour.
Les boutons de retrait sont masqués aux lecteurs d’écran, car Retour arrière retire un token au clavier. Leur zone tactile s’agrandit sur écran tactile, un token en attente ne pulse que si l’animation est autorisée, et un token sélectionné reçoit une bordure de surbrillance système en mode couleurs forcées.
Chaque partie enveloppe la partie UI SDK du même nom et accepte toutes ses props, y compris render et un className qui peut être une fonction de son état.
| Prop | Type | Par défaut |
|---|---|---|
value | TokenInputValue | – |
defaultValue | TokenInputValue | – |
onValueChangeS’exécute à la saisie, au collage, via les menus, l’annulation et les appels du contrôleur. details donne la raison et les tokens retirés. | (value, details) => void | – |
onSubmitS’exécute au raccourci d’envoi, sauf si un menu est ouvert ou qu’une méthode de saisie compose. | (value, details) => void | – |
submitShortcut | "enter" | "mod+enter" | "enter" |
tokenDeletion | "whole" | "select" | "revert" | "whole" |
renderTokenAffiche un token. Par défaut, un TokenInputToken avec son label et un bouton de retrait. | (token: Token) => ReactNode | – |
copy | "codec" | "label" | "codec" |
codec | TokenCodec | – |
getTokenDescriptionCe qu’un token dit aux lecteurs d’écran en plus de son label. | (token: Token) => string | – |
history | { limit, groupDelay } | – |
name | string | – |
form | string | – |
required | boolean | false |
disabled | boolean | false |
readOnly | boolean | false |
controllerIssu de createTokenInputController(). | TokenInputController | – |
| Prop | Type | Par défaut |
|---|---|---|
placeholderAffiché via aria-placeholder tant que l’input est vide. | string | – |
render | ReactElement | (props, state) => ReactElement | – |
| Attribut | Description |
|---|---|
data-slot="token-input-editor" | Pour cibler l’éditeur en CSS. |
data-empty | Présent tant que l’input est vide. |
data-disabled | Présent lorsque l’élément est désactivé. |
data-readonly | Présent en lecture seule. |
| Attribut | Description |
|---|---|
data-slot="token-input-token" | Pour cibler un token en CSS. |
data-token-type | Le type du token, comme file ou mention. |
data-selected | Présent tant que le token est dans la sélection ou sélectionné pour être retiré. |
data-pending | Présent pendant le chargement du token. |
data-unresolved | Présent tant que le token demande une action, comme une mention ambiguë. |
Retire son token et garde le focus dans l’éditeur. Il affiche une icône X de Tabler sauf si vous passez des children, et se masque quand l’input est désactivé ou en lecture seule.
| Prop | Type | Par défaut |
|---|---|---|
triggersLes caractères qui ouvrent le menu, le type de token que chacun insère et ses éléments. | TriggerDefinition[] | – |
onSelectS’exécute quand un élément est choisi. Renvoyez une promesse pour insérer le token en attente. | (value, details) => void | Promise | – |
autoHighlight | boolean | true |
loop | boolean | true |
| Prop | Type | Par défaut |
|---|---|---|
align | "start" | "center" | "end" | "start" |
sideOffset | number | 6 |
collisionPadding | number | 8 |
| Attribut | Description |
|---|---|
data-slot="trigger-menu-content" | Pour cibler le popup en CSS. |
data-trigger | Le déclencheur de la correspondance actuelle, comme @, pour que chaque liste puisse avoir son style. |
data-starting-style | Présent pendant l'animation d'entrée de la popup. |
data-ending-style | Présent pendant l'animation de sortie de la popup. |
| Prop | Type | Par défaut |
|---|---|---|
value | T | – |
labelLe texte inséré et comparé, quand le contenu n’est pas du texte brut. | string | – |
disabled | boolean | false |
| Attribut | Description |
|---|---|
data-highlighted | Présent sur l’élément en surbrillance. Le focus reste dans l’éditeur. |
data-disabled | Présent quand l’élément ne peut pas être choisi. |
- CalendarUne grille de dates pour la sélection simple, de plage et multiple, avec des mois qui défilent, des aperçus de plage et des jours à taille tactile.
- CheckboxUne case à cocher dont la coche se dessine, avec des parents indéterminés, des groupes et des libellés qui partagent son survol.
- ComboboxUn select filtrable avec chips, groupes et résultats asynchrones, dans un popup qui se redimensionne pendant la saisie.
- Date pickerUn bouton qui ouvre un calendrier dans un popover, ou une bottom sheet sur mobile, pour des dates simples et des plages.
- FieldDes libellés, descriptions et erreurs reliés à leur contrôle, avec états de validation et mises en page pour les formulaires.
- InputUn champ de saisie texte en trois tailles, avec états invalide et lecture seule, style de validation natif et police tactile de 16px pour que les téléphones ne zooment jamais.