# 切换按钮组

## 使用方法

`ToggleButtonGroup` 管里面 `ToggleButton` 的按下状态。每个按钮都要有 `value`。组的 `v-model:value` 会盖过按钮自己的按下状态。

`type="single"` 同时只按下一个。再点一次会清空，值变成 `null`。`type="multiple"` 每个按钮各自按下，值是数组。`orientation` 是 `horizontal` 或 `vertical`。`label` 是这一组的无障碍名称。

```vue
<script setup lang="ts">
import { ToggleButton, ToggleButtonGroup } from '@astryx-vue/core/ToggleButton'
import { ref } from 'vue'

const view = ref<string | null>('grid')
</script>

<template>
  <ToggleButtonGroup v-model:value="view" label="View mode">
    <ToggleButton label="List" value="list" />
    <ToggleButton label="Grid" value="grid" />
    <ToggleButton label="Board" value="board" />
  </ToggleButtonGroup>
</template>
```

## 示例

### 分组

单选和多选两种开关组。单选用来切换视图，多选组成格式工具栏。

```vue
<script setup lang="ts">
import { Icon } from '@astryx-vue/core/Icon'
import { Stack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
import { ToggleButton, ToggleButtonGroup } from '@astryx-vue/core/ToggleButton'
import { ref } from 'vue'

const view = ref<string | null>('list')
const formats = ref<string[]>(['bold'])
</script>

<template>
  <Stack direction="vertical" :gap="4">
    <Stack direction="vertical" :gap="1">
      <Text type="supporting" color="secondary">
        Single selection
      </Text>
      <ToggleButtonGroup v-model:value="view" label="View mode">
        <ToggleButton value="list" label="List view" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-list-bullet" />
          </template>
        </ToggleButton>
        <ToggleButton value="grid" label="Grid view" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-squares-2x2" />
          </template>
        </ToggleButton>
        <ToggleButton value="table" label="Table view" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-table-cells" />
          </template>
        </ToggleButton>
      </ToggleButtonGroup>
    </Stack>
    <Stack direction="vertical" :gap="1">
      <Text type="supporting" color="secondary">
        Multiple selections
      </Text>
      <ToggleButtonGroup v-model:value="formats" type="multiple" label="Text formatting">
        <ToggleButton value="bold" label="Bold" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-bold" />
          </template>
        </ToggleButton>
        <ToggleButton value="italic" label="Italic" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-italic" />
          </template>
        </ToggleButton>
        <ToggleButton value="underline" label="Underline" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-underline" />
          </template>
        </ToggleButton>
        <ToggleButton value="strikethrough" label="Strikethrough" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-strikethrough" />
          </template>
        </ToggleButton>
      </ToggleButtonGroup>
    </Stack>
  </Stack>
</template>
```

### 垂直

垂直排列的开关组，同时展示单选和多选。适合侧栏式选项和垂直工具栏。

```vue
<script setup lang="ts">
import { VStack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
import { ToggleButton, ToggleButtonGroup } from '@astryx-vue/core/ToggleButton'
import { ref } from 'vue'

const view = ref<string | null>('grid')
const filters = ref<string[]>(['active'])
</script>

<template>
  <VStack :gap="4">
    <VStack :gap="1">
      <Text type="label" color="secondary">
        Single select
      </Text>
      <ToggleButtonGroup v-model:value="view" orientation="vertical" label="View mode">
        <ToggleButton value="list" label="List" />
        <ToggleButton value="grid" label="Grid" />
        <ToggleButton value="board" label="Board" />
      </ToggleButtonGroup>
    </VStack>
    <VStack :gap="1">
      <Text type="label" color="secondary">
        Multi select
      </Text>
      <ToggleButtonGroup v-model:value="filters" orientation="vertical" type="multiple" label="Status filters">
        <ToggleButton value="active" label="Active" />
        <ToggleButton value="pending" label="Pending" />
        <ToggleButton value="closed" label="Closed" />
      </ToggleButtonGroup>
    </VStack>
  </VStack>
</template>
```

## 属性

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | - | 无障碍名称，写到 `aria-label` 上。 |
| `type` | `'single' \| 'multiple'` | `'single'` | `single` 同时只按下一个。`multiple` 各自按下。 |
| `value` | `string \| null \| string[]` | `null` | 按下的那一个，或多选时的列表。用 `v-model:value` 绑定。 |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 排列方向。 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 成员继承的尺寸。成员自己的 `size` 优先。 |
| `isDisabled` | `boolean` | `false` | 禁用全部成员。成员仍可以单独禁用自己。 |

## 事件

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `update:value` | `string \| null \| string[]` | 下一次的选择。 |
| `change` | `string \| null \| string[]` | 和 `update:value` 一起发出。 |

## 插槽

默认插槽是 `ToggleButton`。参与选择的按钮都要有 `value`。