ドキュメントを検索

Controlled & Uncontrolled

コンポーネント自身に状態を管理させるか、シグナルで制御します。

Switch(checked)、Collapsible(open)、Tabs(value)などの状態を持つすべてのコンポーネントは、同じ3つのpropsで両方のモードをサポートします。

Propモード例
default<State>非制御:初期値defaultChecked, defaultOpen, defaultValue
bind:<state>制御:値を保持するSignalbind:checked, bind:open, bind:value
on<State>Change$ユーザーが値を変更したときのコールバックonCheckedChange$, onOpenChange$, onValueChange$

各コンポーネントの正確なpropsは、それぞれのAPIリファレンスに記載されています。

非制御#

default<State>を渡すか何も指定しないと、コンポーネント自身が状態を保持します。

<Switch.Root defaultChecked>
  <Switch.Label>Notifications</Switch.Label>
  <Switch.Control>
    <Switch.Thumb />
  </Switch.Control>
</Switch.Root>

状態を所有せずに変更を検知するには、on<State>Change$を使用します。

<Switch.Root onCheckedChange$={(checked) => console.log(checked)}>

Controlled#

bind:<state>でシグナルを渡します。コンポーネントがそのシグナルを読み書きするため、シグナルとコンポーネントは双方向に同期された状態を保ちます。コンポーネントを変更するには、シグナル自身を変更します。

import { component$, useSignal } from '@builder.io/qwik';
import { Collapsible } from '@leve-ui/collapsible';

export default component$(() => {
  const open = useSignal(false);

  return (
    <>
      <button type="button" onClick$={() => (open.value = !open.value)}>
        {open.value ? 'Close' : 'Open'} from outside
      </button>

      <Collapsible.Root bind:open={open}>
        <Collapsible.Trigger>Controlled collapsible</Collapsible.Trigger>
        <Collapsible.Content>
          This collapsible state is controlled by an external signal.
        </Collapsible.Content>
      </Collapsible.Root>
    </>
  );
});
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Collapsible } from '@leve-ui/collapsible';
import { LuChevronDown } from '@qwikest/icons/lucide';
import styles from './controlled.css?inline';

export default component$(() => {
  useStyles$(styles);
  const open = useSignal(false);

  return (
    <div class="collapsible-controlled-wrapper">
      <button
        type="button"
        class="collapsible-controlled-external-button"
        onClick$={() => {
          open.value = !open.value;
        }}
      >
        {open.value ? 'Close' : 'Open'} from outside
      </button>

      <Collapsible.Root bind:open={open} class="collapsible-controlled-root">
        <Collapsible.Trigger class="collapsible-controlled-trigger">
          <span>Controlled collapsible</span>
          <LuChevronDown class="collapsible-controlled-chevron" aria-hidden="true" />
        </Collapsible.Trigger>
        <Collapsible.Content class="collapsible-controlled-content">
          This collapsible state is controlled by an external signal.
        </Collapsible.Content>
      </Collapsible.Root>
    </div>
  );
});

bind:<state>が指定されている場合、default<State>は無視され、サーバー上でもシグナルの値が初期値として使用されます。

on<State>Change$が呼び出されるタイミング#

on<State>Change$は、ユーザーがスイッチをクリックしたときなど、コンポーネントが値を変更したときにのみ呼び出されます。以下の場合には呼び出されません。

  • バインドされたシグナル自身に手動で書き込んだとき
  • 新しい値が現在の値と同じであるとき

そのため、ループを引き起こすことなく、on<State>Change$や他の任意の場所からシグナルを更新できます。自身の変更を含むすべての変更を検知するには、代わりにuseTask$などを使用してシグナルを追跡してください。

モードの選択#

  • ユーザーが開閉するディスクロージャーなど、コンポーネント自身のみが状態を必要とする場合は、非制御を使用します。
  • Collapsibleを開くボタンや、保存・復元する値など、ページの他の部分が状態を読み取ったり変更したりする場合は、制御を使用します。

レンダリング後に、コンポーネントの制御(controlled)と非制御(uncontrolled)を切り替えないでください。