Controlled & Uncontrolled
コンポーネント自身に状態を管理させるか、シグナルで制御します。
Switch(checked)、Collapsible(open)、Tabs(value)などの状態を持つすべてのコンポーネントは、同じ3つのpropsで両方のモードをサポートします。
| Prop | モード | 例 |
|---|---|---|
default<State> | 非制御:初期値 | defaultChecked, defaultOpen, defaultValue |
bind:<state> | 制御:値を保持するSignal | bind: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>
</>
);
});
This collapsible state is controlled by an external signal.
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>
);
});.collapsible-controlled-wrapper {
display: flex;
flex-direction: column;
align-items: flex-start;
gap: 12px;
font-family: inherit;
}
.collapsible-controlled-external-button {
height: 32px;
padding: 0 12px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font: inherit;
font-size: 13px;
font-weight: 500;
cursor: pointer;
}
.collapsible-controlled-external-button:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.collapsible-controlled-external-button:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.collapsible-controlled-root {
display: flex;
flex-direction: column;
gap: 8px;
width: 320px;
}
.collapsible-controlled-trigger {
display: flex;
align-items: center;
justify-content: space-between;
width: 100%;
padding: 10px 14px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
text-align: left;
cursor: pointer;
}
.collapsible-controlled-trigger:hover:not(:disabled) {
background: light-dark(#f1f5f9, #ffffff14);
}
.collapsible-controlled-trigger:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.collapsible-controlled-trigger:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* Rotate the chevron while the collapsible is open */
.collapsible-controlled-chevron {
flex-shrink: 0;
width: 16px;
height: 16px;
color: light-dark(#475569, #c9ddf0);
transition: transform 200ms ease;
}
.collapsible-controlled-trigger[data-state="open"] .collapsible-controlled-chevron {
transform: rotate(180deg);
}
.collapsible-controlled-content {
padding: 10px 14px;
border-radius: 6px;
background: light-dark(#f1f5f9, #ffffff14);
font-size: 13px;
line-height: 1.6;
color: light-dark(#475569, #c9ddf0);
}bind:<state>が指定されている場合、default<State>は無視され、サーバー上でもシグナルの値が初期値として使用されます。
on<State>Change$が呼び出されるタイミング#
on<State>Change$は、ユーザーがスイッチをクリックしたときなど、コンポーネントが値を変更したときにのみ呼び出されます。以下の場合には呼び出されません。
- バインドされたシグナル自身に手動で書き込んだとき
- 新しい値が現在の値と同じであるとき
そのため、ループを引き起こすことなく、on<State>Change$や他の任意の場所からシグナルを更新できます。自身の変更を含むすべての変更を検知するには、代わりにuseTask$などを使用してシグナルを追跡してください。
モードの選択#
- ユーザーが開閉するディスクロージャーなど、コンポーネント自身のみが状態を必要とする場合は、非制御を使用します。
- Collapsibleを開くボタンや、保存・復元する値など、ページの他の部分が状態を読み取ったり変更したりする場合は、制御を使用します。
レンダリング後に、コンポーネントの制御(controlled)と非制御(uncontrolled)を切り替えないでください。