Pole tekstowe

Są tu dwie warstwy. input() i textarea() to gołe kontrolki; textField() i textareaField() opakowują jedną w etykietę, tekst pomocy i komunikat błędu, i łączą je przez for oraz aria-describedby. Sięgaj po te drugie, chyba że budujesz układ samodzielnie.

Podstawowe pole

textField({ label: 'Imię i nazwisko', name: 'name', placeholder: 'Ada Lovelace' })

Tekst pomocy

Tekst pomocy jest powiązany przez aria-describedby, więc czytnik ekranu czyta go jako część pola, a nie jako luźny tekst po nim.

Używamy go tylko do powiadomień o nieudanych buildach.
textField({
  label: 'E-mail',
  name: 'email',
  type: 'email',
  help: 'Używamy go tylko do powiadomień o nieudanych buildach.',
})

Wymagane i błąd

error oznacza pole jako niepoprawne, koloruje obramowanie, ustawia aria-invalid i kieruje aria-describedby na komunikat — jeden props, wszystkie cztery rzeczy.

To nie jest URL.
stack({ gap: 'lg' },
  textField({ label: 'Projekt', name: 'project', required: true, value: '' }),
  textField({
    label: 'Witryna',
    name: 'site',
    error: 'To nie jest URL.',
    value: 'sitelo kropka dev',
  }),
)

Rozmiary

stack({ gap: 'md' },
  textField({ label: 'Małe', name: 'small', size: 'sm', placeholder: 'sm' }),
  textField({ label: 'Średnie', name: 'medium', size: 'md', placeholder: 'md' }),
  textField({ label: 'Duże', name: 'large', size: 'lg', placeholder: 'lg' }),
)

Ozdobniki

Przedrostek albo przyrostek dołączony do samej kontrolki, na jednostki i stałe fragmenty wartości.

https://
sekund
stack({ gap: 'md' },
  textField({ label: 'Witryna', name: 'url', startAdornment: 'https://', placeholder: 'example.com' }),
  textField({ label: 'Limit czasu buildu', name: 'timeout', endAdornment: 'sekund', value: '30' }),
)

Wyłączone i tylko do odczytu

stack({ gap: 'md' },
  textField({ label: 'Wyłączone', name: 'disabled', value: 'Nie do edycji', disabled: true }),
  textField({ label: 'Tylko do odczytu', name: 'readonly', value: 'dist/', readonly: true }),
)

Wielowierszowe

textareaField() to to samo pole wokół <textarea>. Jego wartość jest treścią elementu, a nie atrybutem, czym komponent zajmuje się za Ciebie.

Pokazywany w wynikach wyszukiwania i w kartach społecznościowych.
textareaField({
  label: 'Opis',
  name: 'description',
  rows: 4,
  help: 'Pokazywany w wynikach wyszukiwania i w kartach społecznościowych.',
  value: 'Generowanie stron statycznych bez konfiguracji, napędzane przez Vite.',
})

W formularzu

card(
  cardBody(
    stack({ gap: 'md' },
      textField({ label: 'Imię i nazwisko', name: 'contact-name', required: true }),
      textField({ label: 'E-mail', name: 'contact-email', type: 'email', required: true }),
      textareaField({ label: 'Wiadomość', name: 'message', rows: 3 }),
    ),
  ),
  cardFooter({ divided: true, style: 'justify-content: flex-end' },
    button({ variant: 'ghost', color: 'neutral' }, 'Anuluj'),
    button({ type: 'submit' }, 'Wyślij'),
  ),
)

Budowanie samodzielnie

field() to samo opakowanie — przyjmuje jako dzieci dowolną kontrolkę, więc możesz umieścić dwa pola w jednym wierszu albo kontrolkę, której ta biblioteka nie ma, pod tym samym potraktowaniem etykiety i błędu.

Jedna etykieta nie może nazwać dwóch kontrolek, więc każde pole potrzebuje tu własnej dostępnej nazwy. Robią to właśnie atrybuty aria-label: widoczna etykieta nazywa parę, a każde pole mówi, którym jest końcem.

Oba końce są wliczane.
field({ label: 'Zakres dat', help: 'Oba końce są wliczane.' },
  stack({ direction: 'row', gap: 'sm' },
    input({ type: 'date', name: 'from', 'aria-label': 'Od' }),
    input({ type: 'date', name: 'to', 'aria-label': 'Do' }),
  ),
)

Propsy

textField i textareaField

PropTypDomyślnieOpis
labelChild—Etykieta pola. Gdy nie ma name, wyprowadzany jest z niej też id kontrolki.
namestring—Nazwa pola formularza; z niej wyprowadzany jest id.
helpChild—Wskazówka pod kontrolką, powiązana przez aria-describedby.
errorChild | false—Komunikat błędu. Ustawia też aria-invalid na kontrolce.
requiredbooleanfalseOznacza etykietę i kontrolkę.
size'sm' | 'md' | 'lg''md'Wysokość kontrolki i rozmiar tekstu.
typestring'text'Dowolny typ pola. Tylko textField.
startAdornmentChild—Przedrostek dołączony do kontrolki. Tylko textField.
endAdornmentChild—Przyrostek dołączony do kontrolki. Tylko textField.
valuestring | number—Wartość początkowa.
fieldClassstring—Klasa dla opakowania, a nie dla kontrolki.

Identyfikatory wyprowadzane są z name — albo z label, gdy nazwy nie ma — a nie z licznika, więc ta sama strona daje przy każdym buildzie ten sam HTML. Podaj id, żeby je nadpisać.

field

PropTypDomyślnieOpis
labelChild—Tekst etykiety.
helpChild—Wskazówka pod kontrolką.
errorChild | false—Komunikat błędu; dodaje też opakowaniu stan niepoprawności.
requiredbooleanfalseDodaje etykiecie znacznik wymagalności.
forstring—Id opisywanej kontrolki.