Primitivele

Prezentare generală

Primitivele sunt controalele fundamentale din Twenty UI. Acestea includ elemente de intrare, elemente de afișare, navigare și controale compuse, cum ar fi Select, Popover și AlertDialog. Fiecare primitivă primește date și funcții callback de la aplicația dvs. Importați primitive dintr-un punct de intrare al familiei, cum ar fi twenty-ui/primitives/input. Punctul de intrare agregat twenty-ui/primitives exportă, de asemenea, fiecare familie de primitive. Consultați Noțiuni introductive pentru instalare și configurarea temei. Componente combină aceste primitive în presetări de design partajate și elemente reutilizabile de construcție a aplicațiilor.

Proprietatea asupra stării

Folosiți starea necontrolată atunci când un component își poate gestiona propriile interacțiuni. O proprietate implicită furnizează starea inițială. Folosiți starea controlată atunci când aplicația trebuie să coordoneze acea stare cu alte controale, navigarea sau datele aplicației.

Stare	Stare inițială necontrolată	Stare controlată	Callback de schimbare
Câmp de introducere, selecție sau filă activă	`defaultValue`	`valoare`	`onValueChange`
Casetă de selectare sau comutator	`defaultChecked`	`checked`	`onCheckedChange`
Vizibilitatea ferestrei popup	`defaultOpen`	`open`	`onOpenChange`

În modul controlat, transmiteți starea curentă și actualizați-o în callbackul de schimbare. În modul necontrolat, puteți în continuare să monitorizați modificările fără a prelua proprietatea asupra stării. Adăugarea unui callback singur nu face ca un component să fie controlat. Alegeți un mod pentru fiecare stare și păstrați-l pe durata de viață a componentului. Proprietățile implicite inițializează starea; modificarea lor ulterioară nu înlocuiește starea curentă. Evitați transmiterea atât a proprietății implicite, cât și a celei controlate pentru aceeași stare. Unele componente au mai multe stări independente. De exemplu, Select poate avea o valoare controlată și o vizibilitate necontrolată a ferestrei popup. Starea aparține părții care gestionează interacțiunea. Configurați selecția butoanelor radio în RadioGroup, nu în fiecare Radio. Componentele de afișare, precum Text, nu au un mod controlat sau necontrolat. Toast deleagă aplicației gestionarea vizibilității și eliminării sale.

Compoziție

Primitivele compuse expun părți precum Select.Root, Select.Trigger și Select.Popup. Păstrați părțile asociate sub aceeași rădăcină în arborele de componente, astfel încât să partajeze starea și relațiile de accesibilitate. Secțiunea de anatomie a fiecărei componente identifică părțile necesare și conținutul opțional. Sloturile precum InputGroup.startElement și ListItem.actions acceptă noduri React ca props. Acestea adaugă conținut în structura unei componente. Părțile și sloturile sunt API-uri diferite; utilizați numele enumerate în ghidul componentei.

Compoziția popupului

Select, Popover și Autocomplete expun părți separate Portal, Positioner și Popup:

Parte	Responsabilitate
`Portal`	Containerul de destinație și montarea
`Positioner`	Poziționarea, ancora, decalajele și gestionarea coliziunilor
`Popup`	Conținutul, comportamentul de focalizare, atributele native și ref
`Arrow`	Săgeată opțională în interiorul popupului

Imbricați Popup în Positioner și Positioner în Portal. Plasați conținutul în Popup și adăugați Arrow în mod explicit atunci când este necesar. Portal poate muta DOM-ul randat într-un alt container, păstrând ierarhia și contextul componentelor. Consultați tematizarea pentru containere portal cu domeniu de aplicare. Fiecare parte randată își păstrează propriile atribute native, ținta ref și compoziția de randare. Autocomplete păstrează, de asemenea, părțile instalate upstream pentru colecție, grupare, grilă, filtrare și stare. Dialog și AlertDialog expun părți separate Portal, Backdrop, Viewport și Popup. Configurează montarea și destinația pentru Portal, aspectul suprapunerii pentru Backdrop și Viewport, precum și dimensiunea și focalizarea conținutului pentru Popup. Fiecare parte își păstrează propriile atribute native, ținta ref și compoziția de randare. Aceste API-uri de dialog sunt pentru UI independentă și gazda Twenty. Componentele Front utilizează API-ul de dialog al gazdei SDK.

Componente personalizate

Pentru părțile care acceptă render, transmiteți un element sau o componentă compatibilă pentru a înlocui elementul implicit. De exemplu, Popover.Trigger poate utiliza un Button Twenty UI, păstrându-și comportamentul de declanșator. Un înveliș personalizat trebuie să transmită proprietățile și ref furnizate către elementul interactiv. Acest lucru păstrează gestionarele de evenimente, atributele de accesibilitate, poziționarea și restabilirea focalizării. Acest exemplu le redirecționează prin Button, care le atașează butonului său nativ.

import { type ComponentPropsWithRef } from 'react';
import { Button } from 'twenty-ui/primitives/input';
import { Popover } from 'twenty-ui/primitives/surfaces';

type HelpButtonProps = ComponentPropsWithRef<typeof Button>;

const HelpButton = ({ ref, ...props }: HelpButtonProps) => (
  <Button {...props} ref={ref} variant="outline" />
);

export const ImportHelp = () => (
  <Popover.Root>
    <Popover.Trigger render={<HelpButton>Import help</HelpButton>} />
    <Popover.Portal>
      <Popover.Positioner>
        <Popover.Popup>
          <Popover.Title>Import a CSV file</Popover.Title>
          <Popover.Description>
            Use a header row to identify your columns.
          </Popover.Description>
          <Popover.Close render={<Button>Got it</Button>} />
        </Popover.Popup>
      </Popover.Positioner>
    </Popover.Portal>
  </Popover.Root>
);

Transmiteți butonul prin render și păstrați fiecare acțiune ca un singur control interactiv. Păstrați gestionarele și ref furnizate învelișului dvs. când adăugați propriul comportament. Ref trebuie să ajungă la elementul care primește focalizarea. Utilizați un buton nativ pentru părțile de tip buton. Pentru părțile care expun nativeButton, setați nativeButton={false} numai atunci când elementul randat nu este un buton nativ. O componentă personalizată care randează în cele din urmă un buton, precum HelpButton, păstrează comportamentul implicit al butonului.

Răsfoiți primitivele

Fiecare pagină include exemple de utilizare, recomandări privind interacțiunea și o referință API generată.

Familie	Primitive
Accesibilitate	Ascuns vizual
Date afișate	Avatar, Etichetă, Eșantion de culoare, Insignă, Stare, Etichetă
Feedback	Banner, Încărcător, Progres, Bară de progres, Inel de progres, Schelet
Formulare	Completare automată, Buton, Grup de butoane, Casetă de selectare, Câmp, Intrare, Grup de intrări, Câmp numeric, Buton radio, Grup de butoane radio, Selectare, Glisor, Comutator, Zonă de text
Aspect	Pliabil, Separator, Mâner de redimensionare, Furnizor de direcție
Navigare	Fir de navigare, Element de listă, File
Suprafețe	Dialog de alertă, Card, Dialog, Popover, Indiciu
Tipografie	Titlu, Text depășit cu indicație, Furnizor de mod pentru indicația textului depășit, Comandă rapidă, Text

Dezvoltatori

Aplicații

API

Autogazda

Contribuie

Biblioteca UI

Prezentare generală

Proprietatea asupra stării

Compoziție

Compoziția popupului

Componente personalizate

Răsfoiți primitivele

​Prezentare generală

​Proprietatea asupra stării

​Compoziție

​Compoziția popupului

​Componente personalizate

​Răsfoiți primitivele

Prezentare generală

Proprietatea asupra stării

Compoziție

Compoziția popupului

Componente personalizate

Răsfoiți primitivele