Checkbox チェックボックス - Vant 4

☑️ 紹介

Checkbox チェックボックスは日常生活の「買い物リスト」📝のようなもので、ユーザーはたくさんのオプションの中から気に入った内容を自由に選択することができます！

フォーム記入時の複数選択、商品検索時の条件組み合わせ、一括操作時の簡単な管理など、どのような場面でも、Checkbox は直感的で使いやすいインタラクティビティを提供します。まるで「これも欲しい、あれも欲しい」というニーズを簡単に表現できる親切な「アシスタント」のようです✨。

📦 導入

以下の方法でグローバルにコンポーネントを登録します。詳細な登録方法については、コンポーネント登録を参照してください。

import { createApp } from'vue'; import { Checkbox, CheckboxGroup } from'vant'; const app = createApp(); app.use(Checkbox); app.use(CheckboxGroup);

🎯 コード例

基本的な使い方

v-model で簡単にチェックボックスの選択状態をバインドできます。まるでスイッチに「リモコン」🎮を取り付けたようなものです！

シンプルな双方向バインディングにより、アプリケーションとユーザーの選択が完璧に同期し、状態管理の悩みから解放されます✨。

html

<van-checkbox v-model="checked">チェックボックス</van-checkbox>

```js
import { ref } from 'vue';
export default {
  setup() {
    const checked = ref(true);
    return { checked };
  },
};

無効状態

時々、あるオプションは「一時的に休む」必要がありますか？🛌 disabled 属性を設定することで、チェックボックスを無効にすることができます。

これはまるでチェックボックスに「邪魔しないでください」のラベルを貼るようなもので、ユーザーにこのオプションが現在利用できないことを知らせながら、インターフェースの完全性と美しさを維持します🚫。

html

<van-checkbox v-model="checked" disabled>無効なチェックボックス</van-checkbox>

### カスタム形状

チェックボックスにもっと個性を持たせたいですか？🎨 `shape` 属性を `square` に設定すると、チェックボックスは丸みのある「小さな点」から四角い「小さなブロック」に変わります！

異なる形状は異なるデザイン言語を伝え、インターフェースをブランドの調性に合わせることができます📐。

```html
<van-checkbox v-model="checked" shape="square">四角いチェックボックス</van-checkbox>

```js
import { ref } from 'vue';
export default {
  setup() {
    const checked = ref(['a', 'b']);
    return { checked };
  },
};

カスタムカラー

チェックボックスに「新しい服」を着せたいですか？👗 checked-color 属性で選択状態の専用色を設定できます！

チェックボックスをブランドカラーに合わせて、全体のデザインスタイルと完璧に融合させ、独特の視覚体験を作り出しましょう🌈。

html

<van-checkbox v-model="checked" checked-color="#07c160">緑色チェックボックス</van-checkbox>

### カスタムサイズ

チェックボックスにも「大中小サイズ」があります！📏 `icon-size` 属性でアイコンのサイズを自由に調整できます。

精巧で小さなミニバージョンでも、目立つ大きなバージョンでも、デザインニーズに完璧に適合します🎯。

```html
<van-checkbox v-model="checked" icon-size="24">大きいアイコン</van-checkbox>

### カスタムアイコン

普通のチェックアイコンに満足していませんか？✨ `icon` スロットを使用すると、好きなどんなアイコンも使用できます！

可愛い絵文字や美しい画像を使って、選択の度に驚きを感じさせることもできます。`slotProps` を使えば現在の選択状態を判断し、動的なアイコン切り替えも実現できます🎭。

```html
<van-checkbox v-model="checked">
  カスタムアイコン
  <template #icon="{ checked }">
    <img :src="checked ? activeIcon : inactiveIcon" />
  </template>
</van-checkbox>

```js
import { ref } from 'vue';
export default {
  setup() {
    const checked = ref(true);
    return {
      checked,
      activeIcon: 'https://fastly.jsdelivr.net/npm/@vant/assets/user-active.png',
      inactiveIcon: 'https://fastly.jsdelivr.net/npm/@vant/assets/user-inactive.png',
    };
  },
};

左側のテキスト

従来のレイアウトを打破したいですか？🔄 label-position 属性を 'left' に設定すると、テキストをチェックボックスの左側に「移動」させることができます！

この逆レイアウトは特定のデザインシーンで思いがけない視覚効果をもたらし、インターフェースをより柔軟に多様にすることができます🎨。

html

<van-checkbox v-model="checked" label-position="left">左側のテキスト</van-checkbox>

### テキストのクリックを無効にする

チェックボックスをもっと「一途」にしたいですか？🎯 `label-disabled` 属性を設定すると、アイコン自体をクリックした場合にのみ切り替えがトリガーされます！

まるでチェックボックスに「精密モード」を設定したようで、ユーザーがテキストエリアを誤ってクリックするのを防ぎ、より正確に制御可能なインタラクションを実現します🔒。

```html
<van-checkbox v-model="checked" label-disabled>テキストクリック不可</van-checkbox>

### チェックボックスグループ

チェックボックスたちが「チームで戦う」必要があるとき、CheckboxGroup は最高の「指揮官」です！👥 

`v-model` 配列バインディングにより、グループのチェックボックスの選択状態を簡単に管理できます。まるで「願望リスト」を管理するように、選択された各アイテムは自動的に配列に追加されます📋。

```html
<van-checkbox-group v-model="checked">
  <van-checkbox name="a">オプション A</van-checkbox>
  <van-checkbox name="b">オプション B</van-checkbox>
  <van-checkbox name="c">オプション C</van-checkbox>
</van-checkbox-group>

```js
import { ref } from'vue'; exportdefault { setup() { const checked = ref(['a', 'b']); return { checked }; }, };

水平配置

チェックボックスたちが「並んで立つ」のが好きではないですか？🚶‍♂️ direction 属性を horizontal に設定すると、それらは「手を繋いで」水平に並びます！

この横向きのレイアウトはオプションが少なく、テキストが短い場面に特に適しており、インターフェースをよりコンパクトで美しくします➡️。

html

<van-checkbox-group v-model="checked" direction="horizontal">
  <van-checkbox name="a">オプション A</van-checkbox>
  <van-checkbox name="b">オプション B</van-checkbox>
  <van-checkbox name="c">オプション C</van-checkbox>
</van-checkbox-group>

```js
import { ref } from 'vue';
export default {
  setup() {
    const checked = ref([]);
    return { checked };
  },
};

最大選択数の制限

ユーザーが多くを選択するのを心配していますか？🛡️ max 属性でチェックボックスグループの「選択上限」を設定できます！

まるで「最大3つの願いしか選べない」と制限するように、ユーザーがより賢明な選択をするのを助けると同時に、システムのパフォーマンスも保護します⚖️。

html

<van-checkbox-group v-model="checked" :max="2">
  <van-checkbox name="a">オプション A</van-checkbox>
  <van-checkbox name="b">オプション B</van-checkbox>
  <van-checkbox name="c">オプション C</van-checkbox>
</van-checkbox-group>

### 全選択と逆選択

すべてのオプションを一撃でコントロールしたいですか？🎮 `CheckboxGroup` インスタンスの `toggleAll` メソッドで全選択と逆選択の「魔法の操作」を実現できます！

まるで「万能リモコン」を持っているように、すべてのチェックボックスを瞬時に指令に従わせ、一括操作の効率を大幅に向上させます⚡。

```html
<van-checkbox-group v-model="checked" ref="checkboxGroup">
  <van-checkbox name="a">オプション A</van-checkbox>
  <van-checkbox name="b">オプション B</van-checkbox>
  <van-checkbox name="c">オプション C</van-checkbox>
</van-checkbox-group>
<div class="demo-checkbox-button">
  <van-button type="primary" @click="checkAll">全選択</van-button>
  <van-button @click="toggleAll">逆選択</van-button>
</div>

```js
import { ref } from 'vue';
export default {
  setup() {
    const checked = ref([]);
    const checkboxGroup = ref(null);
    const checkAll = () => {
      checkboxGroup.value.toggleAll(true);
    };
    const toggleAll = () => {
      checkboxGroup.value.toggleAll();
    };
    return { checked, checkAll, toggleAll, checkboxGroup };
  },
};

セルコンポーネントとの組み合わせ

より優雅なリスト選択体験を作りたいですか？✨ Checkbox を Cell コンポーネントと完璧に組み合わせましょう！

この組み合わせはまるでリストに「正装」を着せるようなもので、選択機能を維持しながら、より豊富な情報表示スペースも提供します。設定ページや選択リストに特に適しています📱。

html

<van-checkbox-group v-model="checked">
  <van-cell
    v-for="(item, index) in list"
    :key="item"
    :title="`オプション ${item}`"
    @click="toggle(index)"
  >
    <template #right-icon>
      <van-checkbox
        :ref="el => checkboxRefs[index] = el"
        :name="item"
        @click.stop
      />
    </template>
  </van-cell>
</van-checkbox-group>

```js
import { ref, onBeforeUpdate } from 'vue';
export default {
  setup() {
    const checked = ref([]);
    const checkboxRefs = ref([]);
    const toggle = (index) => {
      checkboxRefs.value[index].toggle();
    };
    onBeforeUpdate(() => {
      checkboxRefs.value = [];
    });
    return {
      list: ['a', 'b'],
      toggle,
      checked,
      checkboxRefs,
    };
  },
};

不確定状態

時々、選択状態は「全選択でもなく、全未選択でもない」ことを表現する必要がありますか？🤔 indeterminate 属性でこのような「曖昧」な状態を完璧に表現できます！

まるでチェックボックスが「ちょっと迷っている」と言っているようで、部分的に選択された親オプションを表すのに特に適しており、ユーザーは一眼で現在の選択状況を理解することができます🎭。

html

<van-checkbox
  v-model="isCheckAll"
  :indeterminate="isIndeterminate"
  @change="checkAllChange"
>全選択</van-checkbox>
<van-checkbox-group
  v-model="checkedResult"
  @change="checkedResultChange"
>
  <van-checkbox
    v-for="item in list"
    :key="item"
    :name="item"
  >オプション {{ item }}</van-checkbox>
</van-checkbox-group>

```js
import { ref } from 'vue';
export default {
  setup() {
    const list = ['a', 'b', 'c', 'd'];
    const isCheckAll = ref(false);
    const checkedResult = ref(['a', 'b', 'd']);
    const isIndeterminate = ref(true);
    const checkAllChange = (val: boolean) => {
      checkedResult.value = val ? list : [];
      isIndeterminate.value = false;
    };
    const checkedResultChange = (value: string[]) => {
      const checkedCount = value.length;
      isCheckAll.value = checkedCount === list.length;
      isIndeterminate.value = checkedCount > 0 && checkedCount < list.length;
    };
    return {
      list,
      isCheckAll,
      checkedResult,
      checkAllChange,
      isIndeterminate,
      checkedResultChange,
    };
  },
};


## API

### Checkbox Props

| パラメータ | 説明 | 型 | デフォルト値 |
| --- | --- | --- | --- |
| v-model | 選択状態かどうか | *boolean* | `false` |
| name | 識別子、通常は一意の文字列または数値 | *any* | \- |
| shape | 形状、`square` が使用可能 | *string* | `round` |
| disabled | チェックボックスを無効にするかどうか | *boolean* | `false` |
| label-disabled | チェックボックスのテキストのクリックを無効にするかどうか | *boolean* | `false` |
| label-position | テキストの位置、`left` が使用可能 | *string* | `right` |
| icon-size | アイコンのサイズ、デフォルトの単位は `px` | *number \| string* | `20px` |
| checked-color | 選択状態の色 | *string* | `#1989fa` |

| bind-group | チェックボックスグループにバインドするかどうか | *boolean* | `true` |
| indeterminate | 不確定状態かどうか | *boolean* | `false` |

### CheckboxGroup Props

| パラメータ | 説明 | 型 | デフォルト値 |
| --- | --- | --- | --- |
| v-model | すべての選択アイテムの識別子 | *any\[\]* | \- |
| disabled | すべてのチェックボックスを無効にするかどうか | *boolean* | `false` |
| max | 最大選択数、`0` は制限なし | *number \| string* | `0` |
| direction | 配置方向、`horizontal` が使用可能 | *string* | `vertical` |
| icon-size | すべてのチェックボックスのアイコンサイズ、デフォルトの単位は `px` | *number \| string* | `20px` |
| checked-color | すべてのチェックボックスの選択状態の色 | *string* | `#1989fa` |

| shape `v4.6.3` | 形状、`square` が使用可能 | *string* | `round` |

### Checkbox Events

| イベント名 | 説明 | コールバックパラメータ |
| --- | --- | --- |
| change | バインドされた値が変更されたときにトリガーされるイベント | *checked: boolean* |
| click | チェックボックスをクリックしたときにトリガーされます | *event: MouseEvent* |

### CheckboxGroup Events

| イベント名 | 説明 | コールバックパラメータ |
| --- | --- | --- |
| change | バインドされた値が変更されたときにトリガーされるイベント | *names: any\[\]* |

### Checkbox Slots

| 名前 | 説明 | パラメータ |
| --- | --- | --- |
| default | カスタムテキスト | *{ checked: boolean, disabled: boolean }* |
| icon | カスタムアイコン | *{ checked: boolean, disabled: boolean }* |

### CheckboxGroup メソッド

ref を使用して CheckboxGroup インスタンスを取得し、インスタンスメソッドを呼び出すことができます。詳細については、[コンポーネントインスタンスメソッド](./advanced-usage)を参照してください。

| メソッド名 | 説明 | パラメータ | 戻り値 |
| --- | --- | --- | --- |
| toggleAll | すべてのチェックボックスを切り替える、`true` を渡すと選択、`false` を渡すと選択解除、パラメータなしでは反転 | *options?: boolean \| object* | \- |

### toggleAll メソッドの例

```js
import { ref } from'vue'; import type { CheckboxGroupInstance } from'vant'; const checkboxGroupRef = ref<CheckboxGroupInstance>(); // すべて反転 checkboxGroupRef?.value.toggleAll(); // すべて選択 checkboxGroupRef?.value.toggleAll(true); // すべて解除 checkboxGroupRef?.value.toggleAll(false); // すべて反転し、無効なチェックボックスをスキップする checkboxGroupRef?.value.toggleAll({ skipDisabled: true, }); // すべて選択し、無効なチェックボックスをスキップする checkboxGroupRef?.value.toggleAll({ checked: true, skipDisabled: true, });

Checkbox メソッド

ref を使用して Checkbox インスタンスを取得し、インスタンスメソッドを呼び出すことができます。詳細については、コンポーネントインスタンスメソッドを参照してください。

メソッド名	説明	パラメータ	戻り値
toggle	選択状態を切り替える、`true` を渡すと選択、`false` を渡すと選択解除、パラメータなしでは反転	checked?: boolean	-

タイプ定義

コンポーネントは次のタイプ定義をエクスポートしています：

importtype { CheckboxProps, CheckboxShape, CheckboxInstance, CheckboxLabelPosition, CheckboxGroupProps, CheckboxGroupInstance, CheckboxGroupDirection, CheckboxGroupToggleAllOptions, } from'vant';

CheckboxInstance と CheckboxGroupInstance はコンポーネントインスタンスのタイプで、次のように使用します：

import { ref } from'vue'; importtype { CheckboxInstance, CheckboxGroupInstance } from'vant'; const checkboxRef = ref<CheckboxInstance>(); const checkboxGroupRef = ref<CheckboxGroupInstance>(); checkboxRef.value?.toggle(); checkboxGroupRef.value?.toggleAll();

テーマカスタマイズ

スタイル変数

コンポーネントは次のCSS変数を提供し、カスタムスタイルに使用できます。使用方法については、ConfigProvider コンポーネントを参照してください。

名称	デフォルト値	説明
--van-checkbox-size	20px	-
--van-checkbox-border-color	var(--van-gray-5)	-
--van-checkbox-duration	var(--van-duration-fast)	-
--van-checkbox-label-margin	var(--van-padding-xs)	-
--van-checkbox-label-color	var(--van-text-color)	-
--van-checkbox-checked-icon-color	var(--van-primary-color)	-
--van-checkbox-disabled-icon-color	var(--van-gray-5)	-
--van-checkbox-disabled-label-color	var(--van-text-color-3)	-
--van-checkbox-disabled-background	var(--van-border-color)	-

ベストプラクティス

オプションのデザイン原則

チェックボックスのオプションをデザインする際は、次の原則に従うべきです📋：

html

<!-- ✅ 推奨：簡潔明確なオプションテキスト -->
<van-checkbox-group v-model="checked">
  <van-checkbox name="apple">リンゴ</van-checkbox>
  <van-checkbox name="banana">バナナ</van-checkbox>
  <van-checkbox name="orange">オレンジ</van-checkbox>
</van-checkbox-group>

<!-- ❌ 避ける：長すぎるまたはあいまいなオプションの説明 -->
<van-checkbox name="fruit">
  これは非常に美味しく栄養豊富な熱帯果物のオプションです
</van-checkbox>

状態管理のベストプラクティス

チェックボックスの状態を適切に管理することで、ユーザーエクスペリエンスを向上させることができます✨：

javascript

// ✅ 推奨：リアクティブデータを使用して状態を管理する
const selectedItems = ref([]);
const allItems = ['item1', 'item2', 'item3'];

// 全選択状態の計算
const isAllSelected = computed(() => 
  selectedItems.value.length === allItems.length
);

// 部分選択状態の計算
const isIndeterminate = computed(() => 
  selectedItems.value.length > 0 && !isAllSelected.value
);

フォーム検証の統合

html

<!-- フォーム検証との完璧な統合 -->
<van-form @submit="onSubmit">
  <van-field name="agreement" label="ユーザー規約">
    <template #input>
      <van-checkbox 
        v-model="form.agreement"
        :rules="[{ required: true, message: 'ユーザー規約に同意してください' }]"
      >
        ユーザー規約を読み、同意しました
      </van-checkbox>
    </template>
  </van-field>
</van-form>

パフォーマンス最適化のヒント

大量のオプションの最適化

大量のチェックボックスを処理する場合、以下の最適化戦略を検討してください🚀：

html

<!-- 仮想スクロールを使用して大量のオプションを処理する -->
<van-list v-model:loading="loading" @load="onLoad">
  <van-checkbox-group v-model="checked">
    <van-checkbox 
      v-for="item in visibleItems" 
      :key="item.id"
      :name="item.id"
    >
      {{ item.label }}
    </van-checkbox>
  </van-checkbox-group>
</van-list>

イベント処理の最適化

javascript

// ✅ 推奨：デバウンスを使用して頻繁な変更を処理する
import { debounce } from 'lodash-es';

const handleChange = debounce((value) => {
  // 選択の変更を処理
  console.log('選択されたアイテム:', value);
}, 300);


## デザインの推奨事項

### 視覚的階層

- **グループタイトル**：明確なタイトルで異なるオプショングループを区別します 📚
- **オプションの間隔**：誤ったタッチを避けるために適切な間隔を維持します 📏
- **状態のフィードバック**：明確な選択/未選択の視覚フィードバックを提供します 👁️
- **無効状態**：灰色などの視覚的ヒントを使用して使用不可の状態を示します 🚫

### インタラクティブな体験

- **応答速度**：選択操作に即座のフィードバックがあることを確認します ⚡
- **タッチフレンドリー**：モバイルデバイスで十分な大きさのタッチ領域を提供します 📱
- **キーボードナビゲーション**：キーボード操作をサポートしてアクセシビリティを向上させます ⌨️

## よくある質問の解決

### Q: チェックボックスの動的な無効化をどのように実装しますか？

```html
<van-checkbox-group v-model="selected">
  <van-checkbox 
    v-for="item in options" 
    :key="item.id"
    :name="item.id"
    :disabled="item.disabled || isMaxSelected"
  >
    {{ item.label }}
  </van-checkbox>
</van-checkbox-group>

<script>
const isMaxSelected = computed(() => 
  selected.value.length >= maxCount && maxCount > 0
);
</script>

Q: チェックボックスの条件表示をどのように実装しますか？

html

<van-checkbox-group v-model="selected">
  <van-checkbox 
    v-for="item in filteredOptions" 
    :key="item.id"
    :name="item.id"
  >
    {{ item.label }}
  </van-checkbox>
</van-checkbox-group>

<script>
const filteredOptions = computed(() => 
  options.filter(item => item.visible !== false)
);
</script>

Q: チェックボックスのカスタムスタイルをどのように実装しますか？

html

<van-checkbox 
  v-model="checked"
  :checked-color="customColor"
  :icon-size="customSize"
>
  <template #icon="{ checked }">
    <img :src="checked ? activeIcon : inactiveIcon" />
  </template>
  カスタムアイコンチェックボックス
</van-checkbox>

Q: チェックボックスの非同期データをどのように処理しますか？

javascript

// 非同期でオプションデータをロードする
const loadOptions = async () => {
  loading.value = true;
  try {
    const response = await api.getOptions();
    options.value = response.data;
  } catch (error) {
    console.error('オプションのロードに失敗しました:', error);
  } finally {
    loading.value = false;
  }
};

高度な使用例

ツリー構造のチェックボックス

html

<template>
  <div class="tree-checkbox">
    <van-checkbox 
      v-model="parentChecked"
      :indeterminate="isIndeterminate"
      @change="handleParentChange"
    >
      すべてのオプション
    </van-checkbox>
    
    <van-checkbox-group 
      v-model="childrenChecked"
      @change="handleChildrenChange"
    >
      <van-checkbox 
        v-for="child in children" 
        :key="child.id"
        :name="child.id"
      >
        {{ child.label }}
      </van-checkbox>
    </van-checkbox-group>
  </div>
</template>

検索フィルター付きチェックボックス

html

<template>
  <div>
    <van-search 
      v-model="searchText" 
      placeholder="オプションを検索"
      @input="handleSearch"
    />
    
    <van-checkbox-group v-model="selected">
      <van-checkbox 
        v-for="item in filteredOptions" 
        :key="item.id"
        :name="item.id"
      >
        <span v-html="highlightText(item.label)"></span>
      </van-checkbox>
    </van-checkbox-group>
  </div>
</template>

Checkbox チェックボックス - Vant 4

☑️ 紹介

📦 導入

🎯 コード例

基本的な使い方

無効状態

カスタムカラー

左側のテキスト

水平配置

最大選択数の制限

セルコンポーネントとの組み合わせ

不確定状態

Checkbox メソッド

タイプ定義

テーマカスタマイズ

スタイル変数

ベストプラクティス

オプションのデザイン原則

状態管理のベストプラクティス

フォーム検証の統合

パフォーマンス最適化のヒント

大量のオプションの最適化

イベント処理の最適化

Q: チェックボックスの条件表示をどのように実装しますか？

Q: チェックボックスのカスタムスタイルをどのように実装しますか？

Q: チェックボックスの非同期データをどのように処理しますか？

高度な使用例

ツリー構造のチェックボックス

検索フィルター付きチェックボックス

関連コンポーネント

拡張リーディング

Checkbox チェックボックス - Vant 4 ​

☑️ 紹介 ​

📦 導入 ​

🎯 コード例 ​

基本的な使い方 ​

無効状態 ​

カスタムカラー ​

左側のテキスト ​

水平配置 ​

最大選択数の制限 ​

セルコンポーネントとの組み合わせ ​

不確定状態 ​

Checkbox メソッド ​

タイプ定義 ​

テーマカスタマイズ ​

スタイル変数 ​

ベストプラクティス ​

オプションのデザイン原則 ​

状態管理のベストプラクティス ​

フォーム検証の統合 ​

パフォーマンス最適化のヒント ​

大量のオプションの最適化 ​

イベント処理の最適化 ​

Q: チェックボックスの条件表示をどのように実装しますか？ ​

Q: チェックボックスのカスタムスタイルをどのように実装しますか？ ​

Q: チェックボックスの非同期データをどのように処理しますか？ ​

高度な使用例 ​

ツリー構造のチェックボックス ​

検索フィルター付きチェックボックス ​

関連コンポーネント ​

拡張リーディング ​

Checkbox チェックボックス - Vant 4

☑️ 紹介

📦 導入

🎯 コード例

基本的な使い方

無効状態

カスタムカラー

左側のテキスト

水平配置

最大選択数の制限

セルコンポーネントとの組み合わせ

不確定状態

Checkbox メソッド

タイプ定義

テーマカスタマイズ

スタイル変数

ベストプラクティス

オプションのデザイン原則

状態管理のベストプラクティス

フォーム検証の統合

パフォーマンス最適化のヒント

大量のオプションの最適化

イベント処理の最適化

Q: チェックボックスの条件表示をどのように実装しますか？

Q: チェックボックスのカスタムスタイルをどのように実装しますか？

Q: チェックボックスの非同期データをどのように処理しますか？

高度な使用例

ツリー構造のチェックボックス

検索フィルター付きチェックボックス

関連コンポーネント

拡張リーディング