---
title: "PillGroup"
description: "胶囊式单选/多选选项组，支持字符串与对象选项、数量约束、字段映射和插槽定制。"
seo_title: "PillGroup"
seo_description: "A pill-style single/multiple selection group supporting string and object items, min/max constraints, custom field mapping, per-item color and slot customization."
canonical_url: "https://nuxt.mhaibaraai.cn/docs/components/pill-group"
---
# PillGroup
> 胶囊式单选/多选选项组，支持字符串与对象选项、数量约束、字段映射和插槽定制。
## 简介
`MPillGroup` 是一个胶囊（pill）样式的选项组组件，支持单选与多选。接受字符串数组或对象数组作为选项，通过 `labelKey`、`valueKey`、`descriptionKey` 映射业务对象字段，支持数量约束、按项语义色、激活 / 未激活样式区分以及插槽定制。
## 用法
传入字符串数组即可生成单选胶囊，选中值直接写入 v-model：
```vue
```
### `items` 结构化选项
对象 `items` 可通过 `label`、`description` 与 `icon` 渲染复合内容，同时保留原始对象作为值：
```vue
```
### `multiple` 多选模式
开启 `multiple` 后 `modelValue` 变为数组；配合 `valueKey` 让选中值只保存稳定字段：
```vue
```
### `deselectable` 单选可取消
`deselectable` 允许再次点击当前项清空选择，适合非必选筛选条件（多选模式下忽略该属性）：
```vue
```
### `orientation` 排列方向
`orientation` 设为 `vertical` 将选项纵向堆叠，适合描述较长或窄容器场景：
```vue
```
### `activeVariant` 激活样式
`activeVariant` 与 `inactiveVariant` 分别控制选中与未选状态的视觉变体：
```vue
```
### `size` 尺寸
通过 `size` 切换胶囊尺寸；放入 `UFormField` 时会自动继承上下文中的 `size`：
```vue
```
### `color` 主色
通过 `color` 统一组件主色，便于与外部 `UFieldGroup` 或按钮组配色协调：
```vue
```
### `min` 与 `max` 数量约束
`min` 与 `max` 约束多选数量：触顶时未选项变灰，触底时已选项不可取消：
```vue
```
### `labelKey` 展示字段
`labelKey` 指定从业务对象读取的展示字段，未传时回退到 `label`：
```vue
```
### `valueKey` 值字段
`valueKey` 指定 `modelValue` 写回的字段，便于只保存稳定 id 而非整个对象：
```vue
```
### `color` 选项语义色
每个选项可携带独立 `color`，渲染时按项应用，便于表达状态差异：
```vue
```
### `disabled` 禁用
单项 `disabled` 阻止该项交互；组件级 `disabled` 冻结整组并保留当前值：
```vue
```
## 示例
### 插槽定制选项内容
`item-label`、`item-trailing` 等插槽可接管单项的局部渲染，选中标记随 `selected` slot prop 更新：
```vue [ComponentsPillGroupSlotsExample.vue]
{{ getItemLabel(item) }}
```
### 事件回调
点击选项依次触发 `update:modelValue`、`change` 与 `select`，`select` 的 payload 含 `item`、`value`、`selected`、`index`：
```vue [ComponentsPillGroupEventsExample.vue]
```
## API
### Props
```ts
/**
* Props for the MPillGroup component
*/
interface MPillGroupProps {
items?: T[] | undefined;
valueKey?: VK | undefined;
/**
* @default "\"label\""
*/
labelKey?: GetItemKeys | undefined;
/**
* @default "\"description\""
*/
descriptionKey?: GetItemKeys | undefined;
/**
* 对象模式下判定 selected 的比较依据。string 走 `getPath` 比较（multiple=true 时启用 Map O(1)）；
* function 自定义比较；不传则按 [valueKey, 'value', labelKey] 启发式回退。
*/
by?: string | ((a: T, b: T) => boolean) | undefined;
/**
* 排列方向
* @default "\"horizontal\""
*/
orientation?: "horizontal" | "vertical" | undefined;
/**
* 按钮尺寸
*/
size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
/**
* 按钮颜色
*/
color?: "primary" | "secondary" | "info" | "success" | "warning" | "error" | "important" | "neutral" | undefined;
/**
* 选中态单项视觉变体
* @default "\"solid\""
*/
activeVariant?: "link" | "solid" | "outline" | "soft" | "subtle" | "ghost" | undefined;
/**
* 未选中态单项视觉变体
* @default "\"soft\""
*/
inactiveVariant?: "link" | "solid" | "outline" | "soft" | "subtle" | "ghost" | undefined;
disabled?: boolean | undefined;
/**
* 是否可以多选
*/
multiple?: M | undefined;
/**
* 单选：再次点击当前选中项清空（多选模式下被忽略）
* @default "false"
*/
deselectable?: boolean | undefined;
/**
* 多选：最多可选数量
*/
max?: number | undefined;
/**
* 多选：最少需保留数量
*/
min?: number | undefined;
defaultValue?: GetModelValue | undefined;
modelValue?: (GetModelValue & GetModelValue) | undefined;
ui?: (Record & { root?: SlotClass; list?: SlotClass; item?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; }) | undefined;
}
```
### Emits
```ts
/**
* Emitted events for the MPillGroup component
*/
interface MPillGroupEmits {
blur: (payload: [event: FocusEvent]) => void;
focus: (payload: [event: FocusEvent]) => void;
change: (payload: [value: GetModelValue]) => void;
update:modelValue: (payload: [value: GetModelValue]) => void;
select: (payload: [payload: PillSelectPayload]) => void;
update:modelValue: (payload: [value: GetModelValue | undefined]) => void;
}
```
### Slots
```ts
/**
* Slots for the MPillGroup component
*/
interface MPillGroupSlots {
leading(): any;
default(): any;
trailing(): any;
item(): any;
item-leading(): any;
item-label(): any;
item-description(): any;
item-trailing(): any;
}
```
## Theme
## Changelog
See commit history for [src/runtime/components/PillGroup.vue](https://github.com/mhaibaraai/movk-nuxt/commits/main/src/runtime/components/PillGroup.vue).
## Sitemap
See the full [sitemap](/sitemap.md) for all pages.