SKU Selector 规格选择器

电商核心组件，用于商品详情页的规格选择。内置「文字 / 图片 / 色块」三种展示模态、基于 SKU 矩阵的库存联动算法、已选汇总展示及完整的主题自定义能力。

基础用法

支持根据选中项自动计算可选状态，库存为 0 的规格组合将自动置灰。

颜色

中国红

星际蓝

冬日白

尺寸

S热卖

M

L

当前价格：请选择完整规格

实时剩余库存: --

规格筛选与库存联动

图片预览模式

支持在规格值中传入 image 属性，渲染为预览图。

颜色

红色

蓝色

白色

尺寸

S

M

L

图片预览模式

色块模式

将 mode 设为 'color' 并为每个规格值传入 color 属性，即可渲染为色块选择器。

颜色

中国红

星际蓝

月光白

曜石黑

色块规格选择

已选规格汇总

开启 show-selected-summary 后，会在顶部显示当前选中的规格汇总文本，适合电商详情页场景。

请选择规格

颜色

中国红

星际蓝

尺寸

S

M

已选汇总展示

在 Nuxt 中使用

YhSkuSelector 完全兼容 Nuxt 3 SSR 环境，无需额外配置。

颜色

典雅白

幻影黑

Nuxt 集成

// nuxt.config.ts — 已通过 yh-ui 插件自动注册，无需额外导入
export default defineNuxtConfig({
  modules: ['yh-ui/nuxt']
})

---

API

Props

属性名	说明	类型	默认值
model-value / v-model	当前选中的规格值 ID 数组	Array<string | number>	[]
specs	规格列表	SkuSpec[]	[]
skus	SKU 列表	SkuItem[]	[]
check-stock	是否开启库存联动（库存为0自动置灰）	boolean	true
disabled	整体禁用	boolean	false
allow-unselect	是否允许点击已选中项来取消	boolean	true
size	规格按钮大小	'small' | 'default' | 'large'	'default'
image-size	图片模式下图片区域尺寸（px）	number	80
show-selected-summary	是否显示顶部已选规格汇总	boolean	false
summary-prefix	已选汇总文字前缀	string	''
theme-overrides	CSS 主题变量覆盖	Record<string, string>	{}

Events

事件名	说明	回调参数
update:modelValue	v-model 双向绑定	(value: Array<string | number>) => void
change	选中结果变化，sku 为 null 表示未完整选中	(sku: SkuItem | null, selectedValues: Array<string | number>) => void
select	点击某个规格值时触发（包含不可选的）	(spec: SkuSpec, value: SkuSpecValue) => void

Slots

插槽名	说明	作用域参数
label	自定义规格标题	{ spec: SkuSpec }
value	完全自定义规格值格子	{ value: SkuSpecValue, spec: SkuSpec, active: boolean, disabled: boolean }
summary	自定义已选规格汇总区域	{ summary: string, sku: SkuItem | null }

Expose

当前组件未暴露公开实例方法或属性。

SkuSpec 类型

interface SkuSpec {
  id: string | number
  name: string
  values: SkuSpecValue[]
  /** 展示模式：'text'（默认）| 'image' | 'color' */
  mode?: 'text' | 'image' | 'color'
}

SkuSpecValue 类型

interface SkuSpecValue {
  id: string | number
  name: string
  image?: string // mode='image' 时使用
  color?: string // mode='color' 时使用
  disabled?: boolean
  tag?: string // 右上角标签，如 "热卖"
  [key: string]: unknown // 支持扩展任意自定义字段
}

SkuItem 类型

interface SkuItem {
  id: string | number
  specValueIds: Array<string | number>
  price: number
  stock: number
  marketPrice?: number
  image?: string
  skuNo?: string
  [key: string]: unknown // 支持任意扩展字段
}

主题变量

通过 theme-overrides 传入对象可以覆盖以下 CSS 变量：

变量名	说明	默认值
--yh-sku-label-color	规格标题颜色	var(--yh-text-color-secondary)
--yh-sku-label-size	规格标题字号	var(--yh-font-size-sm)
--yh-sku-label-weight	规格标题字重	var(--yh-font-weight-medium)
--yh-sku-value-bg	规格值默认背景	var(--yh-fill-color-light)
--yh-sku-value-color	规格值默认文字颜色	var(--yh-text-color-primary)
--yh-sku-value-border	规格值默认边框颜色	var(--yh-border-color-light)
--yh-sku-value-hover-bg	规格值悬浮背景	var(--yh-fill-color-dark)
--yh-sku-value-active-bg	选中态背景	var(--yh-color-primary-light-9)
--yh-sku-value-active-color	选中态文字/边框颜色	var(--yh-color-primary)
--yh-sku-value-active-border	选中态边框颜色	var(--yh-color-primary)
--yh-sku-value-disabled-bg	禁用态背景	var(--yh-fill-color-extra-light)
--yh-sku-value-disabled-color	禁用态文字颜色	var(--yh-text-color-disabled)
--yh-sku-value-radius	规格格子圆角	var(--yh-radius-base)
--yh-sku-img-size	图片规格的图片尺寸	80px
--yh-sku-color-swatch-size	色块规格的色块尺寸	24px
--yh-sku-gap	规格行间距	var(--yh-spacing-md)

类型导出

名称	说明
YhSkuSelectorProps	组件 Props 类型
YhSkuSelectorEmits	组件事件类型
YhSkuSelectorSlots	组件插槽类型
YhSkuSpec	规格组类型
YhSkuSpecValue	规格值类型
YhSkuItem	SKU 数据类型
YhSkuSelectorInstance	组件实例类型