SettingsRow

Panoramica

SettingsRow combina l’aspetto di ListItem con Switch. Esegue il rendering di un’etichetta nativa associata al relativo interruttore. La tua applicazione fornisce il contenuto della riga e gestisce eventuali aggiornamenti delle preferenze.

Utilizzo

import { SettingsRow } from 'twenty-ui/components/settings';
import { IconBell } from 'twenty-ui/icon';

export const NotificationSetting = () => (
  <SettingsRow startElement={<IconBell aria-hidden />}>
    Notifications
  </SettingsRow>
);

Opzioni visive

Confronta le dimensioni dell’interruttore e gli stati selezionato, disabilitato e di sola lettura.

Configura l’interruttore

Passa le prop di Switch direttamente a SettingsRow. Lo stato selezionato, i dettagli dell’evento, il comportamento disabilitato e di sola lettura, le dimensioni, la configurazione del modulo nativo, gli handler, i ref e la composizione del rendering configurano l’interruttore. children fornisce l’etichetta visibile della riga. Usa checked e onCheckedChange quando la tua applicazione gestisce il valore. Il gestore riceve lo stato selezionato successivo e i dettagli dell’evento Base UI. Facendo clic sull’etichetta o sull’interruttore viene richiamato una sola volta. Chiama eventDetails.cancel() per rifiutare una modifica e mantieni invariato il valore controllato quando la modifica viene annullata.

import { useState } from 'react';
import { SettingsRow } from 'twenty-ui/components/settings';
import { IconBell } from 'twenty-ui/icon';

export const NotificationSetting = () => {
  const [enabled, setEnabled] = useState(false);

  return (
    <SettingsRow
      startElement={<IconBell aria-hidden />}
      checked={enabled}
      onCheckedChange={setEnabled}
    >
      Notifications
    </SettingsRow>
  );
};

Usa defaultChecked per un’impostazione non controllata. Gli utenti della tastiera attivano lo stato attivo dell’interruttore e premono Spazio. disabled disabilita il controllo e applica l’aspetto disabilitato della riga. readOnly impedisce le modifiche mantenendo l’interruttore attivabile.

import { SettingsRow } from 'twenty-ui/components/settings';

export const WorkspaceSettings = () => (
  <>
    <SettingsRow disabled>Notifications</SettingsRow>
    <SettingsRow readOnly defaultChecked>
      Activity history
    </SettingsRow>
  </>
);

Contenuto della riga e testo accessibile

children, startElement e description accettano nodi gestiti dal chiamante. I children forniscono il nome accessibile dell’interruttore, mentre la descrizione fornisce la relativa descrizione accessibile. Mantieni non interattivo il contenuto all’interno dell’etichetta. Usa ListItemButton per le righe di azione, oppure componi ListItem con un link per la navigazione.

import { SettingsRow } from 'twenty-ui/components/settings';

export const WeeklyDigestSetting = () => (
  <SettingsRow defaultChecked description="Sent every Monday" name="digest">
    Weekly digest
  </SettingsRow>
);

Imposta aria-label, aria-labelledby o aria-describedby per fornire il tuo testo accessibile per l’interruttore. Un valore aria-label esplicito sostituisce l’associazione del nome generata; i valori aria-labelledby e aria-describedby espliciti sostituiscono le associazioni generate corrispondenti.

Destinazioni native e composizione

Le normali prop native configurano il controllo. La personalizzazione dell’etichetta ha due nomi espliciti:

Props	Destinazione
Attributi nativi, handler, `className`, `style`, `ref` e `render`	La radice Switch visibile
`inputRef`, `name`, `value`, `uncheckedValue`, `required` e `form`	La casella di controllo nativa sottostante di Switch
`labelRef` e attributi, handler, classi e stili forniti tramite `labelRender`	L’etichetta nativa esterna

htmlFor dell’etichetta viene gestito internamente e segue id, oppure un ID di controllo generato quando non viene fornito alcun ID. Con la composizione Switch predefinita, questo ID identifica la casella di controllo sottostante. Con nativeButton, identifica il pulsante visibile. ref fa riferimento alla radice visibile in entrambi i casi. Usa labelRender per personalizzare l’etichetta nativa della riga. Mantieni un elemento label e inoltra le prop della callback di rendering al tuo elemento. Il relativo props.children contiene l’intera riga, incluso l’interruttore. La composizione dell’elemento unisce le relative classi e stili con quelli predefiniti della riga.

import { useRef } from 'react';
import { SettingsRow } from 'twenty-ui/components/settings';

export const ComposedNotificationSetting = () => {
  const labelRef = useRef<HTMLLabelElement>(null);
  const controlRef = useRef<HTMLElement>(null);
  const inputRef = useRef<HTMLInputElement>(null);

  return (
    <SettingsRow
      id="notification-control"
      ref={controlRef}
      inputRef={inputRef}
      nativeButton
      render={<button />}
      labelRef={labelRef}
      labelRender={<label id="notification-row" data-setting="notifications" />}
    >
      Notifications
    </SettingsRow>
  );
};

onClick riceve i clic sul controllo. Gli handler nativi forniti tramite labelRender ricevono gli eventi dell’etichetta e gli eventi del controllo propagati. La chiamata a preventDefault() su un clic dell’etichetta impedisce l’attivazione nativa del relativo controllo. Usa onCheckedChange per gli aggiornamenti delle preferenze, anziché dedurre lo stato da un clic sull’etichetta. L’interruttore usa per impostazione predefinita size="sm"; usa "md" per un interruttore più grande. L’altezza della riga rimane invariata. focused applica l’aspetto evidenziato della riga senza spostare lo stato attivo della tastiera. className, style e render accettano callback dello stato di Switch e personalizzano il controllo. Fornisci classi e stili dell’etichetta tramite labelRender per personalizzare la riga.

Renderer del componente front-end

All’interno di un componente front-end, usa la composizione del pulsante nativo per un interruttore annidato nell’etichetta della riga:

import { SettingsRow } from 'twenty-ui/components/settings';

export const FrontComponentNotificationSetting = () => (
  <SettingsRow nativeButton render={<button />}>
    Notifications
  </SettingsRow>
);

Questa composizione si attiva una sola volta quando si fa clic sull’etichetta o sul controllo. Il bridge asincrono degli eventi del renderer non può annullare in tempo l’attivazione predefinita dell’etichetta host per un controllo basato su span, il che può produrre callback di modifica duplicate quando si fa clic direttamente sul controllo. Gli attributi di convalida del modulo nativo, come required, vengono anch’essi filtrati dal renderer corrente. SettingsRow autonomo mantiene il contratto completo del modulo Switch.

Moduli e reimpostazione

name, value e required configurano la casella di controllo sottostante per l’invio e la convalida del modulo. Un interruttore selezionato invia il proprio valore. Un interruttore non selezionato omette il valore, a meno che non venga fornito uncheckedValue. Usa form per associare l’input a un modulo esterno all’albero padre della riga. Per la reimpostazione di un modulo controllato, ripristina il valore selezionato gestito dall’applicazione nell’handler onReset del modulo. Base UI 1.8 non ripristina lo stato dell’interruttore non controllato alla reimpostazione del modulo nativo. SettingsRow mantiene questo comportamento upstream.

import { useState } from 'react';
import { SettingsRow } from 'twenty-ui/components/settings';
import { Button } from 'twenty-ui/primitives/input';

export const NotificationPreferences = () => {
  const [enabled, setEnabled] = useState(true);

  return (
    <form onReset={() => setEnabled(true)}>
      <SettingsRow
        checked={enabled}
        onCheckedChange={setEnabled}
        name="notifications"
        value="enabled"
        uncheckedValue="disabled"
      >
        Notifications
      </SettingsRow>
      <Button type="reset">Reset</Button>
    </form>
  );
};

Props

boolean

Whether the switch is currently active.To render an uncontrolled switch, use the defaultChecked prop instead.

ReactNode

obbligatorio

Visible label and default accessible name of the switch. Use non-interactive node content.

string | ((state: SwitchRootState) => string | undefined)

Customizes the visible Switch root and accepts a Switch state callback.

boolean

predefinito:"false"

Whether the switch is initially active.To render a controlled switch, use the checked prop instead.

ReactNode

Non-interactive supporting node content, used as the default accessible description of the switch.

boolean

predefinito:"false"

Whether the component should ignore user interaction.

boolean

predefinito:"false"

Applies the highlighted row style without moving keyboard focus.

string

Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.

string

Identifies the associated checkbox, or the visible root with nativeButton. The label association follows this ID.

Ref<HTMLInputElement>

Targets the underlying native checkbox.

Ref<HTMLLabelElement>

Targets the outer native label.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

Customizes the outer native label with its complete composed row children. Preserve a label element and forward its props to retain control association.

string

Identifies the field when a form is submitted.

boolean

predefinito:"false"

Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.

((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)

Receives the next checked value and Base UI event details. Controlled callers own accepted state updates; cancellation prevents a change.

((event: BaseUIEvent<MouseEvent<HTMLSpanElement, MouseEvent>>) => void)

Native click handler for the visible Switch root.

boolean

predefinito:"false"

Whether the user should be unable to activate or deactivate the switch.

Ref<HTMLSpanElement>

Targets the visible Switch root, which defaults to a span.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>

Customizes the visible Switch root with control props and Switch state. Use nativeButton when composing a button.

boolean

predefinito:"false"

Whether the user must activate the switch before submitting a form.

"md" | "sm"

predefinito:"sm"

Visual size of the switch. Defaults to sm.

ReactNode

Non-interactive node content before the label.

CSSProperties | ((state: SwitchRootState) => CSSProperties | undefined)

Customizes the visible Switch root and accepts a Switch state callback.

string

The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior.

string

The value submitted with the form when the switch is on. By default, switch submits the “on” value, matching native checkbox behavior.

Sviluppatori

App

API

Auto-ospitazione

Contribuire

Libreria UI

Panoramica

Utilizzo

Opzioni visive

Configura l’interruttore

Contenuto della riga e testo accessibile

Destinazioni native e composizione

Renderer del componente front-end

Moduli e reimpostazione

Props

​Panoramica

​Utilizzo

​Opzioni visive

​Configura l’interruttore

​Contenuto della riga e testo accessibile

​Destinazioni native e composizione

​Renderer del componente front-end

​Moduli e reimpostazione

​Props

Panoramica

Utilizzo

Opzioni visive

Configura l’interruttore

Contenuto della riga e testo accessibile

Destinazioni native e composizione

Renderer del componente front-end

Moduli e reimpostazione

Props