List 列表

可选中列表，用于展示一组选项供用户挑选。支持无选中状态、单选和多选三种模式。单选和多选模式分别使用 McRadio 和 McCheckbox 作为选中指示器。

列表项作为 McList 的子节点声明：在 <mc-list> 内使用 <mc-list-item>，让结构更接近组件本身的层级关系。

McList 根节点负责整体 surface 与统一 4px（内置 pa-1 spacing）内边距，隔开列表内容和外部页面；McListItem 负责统一行高、内边距、边框、悬浮/按下/选中状态，所有行保持同一组视觉节奏，不会像独立卡片一样割裂。多选指示器与 Checkbox 共用 crispEdges 像素勾号，不依赖字体字符。

不设置 mode 时默认为无选中模式，列表项可正常点击触发事件，但不显示选中状态、无选中指示器。

基础用法

不设置 mode 时，列表项可点击并触发 change 事件，但不会高亮选中项、不显示选中指示器。适用于导航菜单、命令入口等场景。

• 打开存档
• 新建世界
• 导入地图

列表项可点击（查看控制台输出），但没有选中高亮

import { reactive, ref } from 'vue'

const selected = ref('world1')
const multiSelected = ref(['coords', 'autosave'])
const switchStates = reactive({
  music: true,
  sfx: true,
  ambient: false,
})
const dynamicItems = [
  { label: '世界一 · 生存模式', value: 'w1', subtitle: '本地存档' },
  { label: '世界二 · 创造模式', value: 'w2', subtitle: '测试地图' },
  { label: '服务器入口', value: 'server', iconRight: 'mc-server' },
]

单选模式

设置 mode="single"，使用 v-model 绑定选中值。每个选项左侧显示单选指示器。

• 世界一 · 生存存档
• 世界二 · 创造模式
• 世界三 · 服务器入口

当前选中：world1

import { reactive, ref } from 'vue'

const selected = ref('world1')
const multiSelected = ref(['coords', 'autosave'])
const switchStates = reactive({
  music: true,
  sfx: true,
  ambient: false,
})
const dynamicItems = [
  { label: '世界一 · 生存模式', value: 'w1', subtitle: '本地存档' },
  { label: '世界二 · 创造模式', value: 'w2', subtitle: '测试地图' },
  { label: '服务器入口', value: 'server', iconRight: 'mc-server' },
]

多选模式

设置 mode="multiple"，v-model 绑定一个数组。每个选项左侧显示复选框指示器。

• 
  显示坐标在 HUD 上显示玩家坐标
• 显示帧率
• 
  自动保存每 5 分钟自动保存世界

当前选中：coords, autosave

import { reactive, ref } from 'vue'

const selected = ref('world1')
const multiSelected = ref(['coords', 'autosave'])
const switchStates = reactive({
  music: true,
  sfx: true,
  ambient: false,
})
const dynamicItems = [
  { label: '世界一 · 生存模式', value: 'w1', subtitle: '本地存档' },
  { label: '世界二 · 创造模式', value: 'w2', subtitle: '测试地图' },
  { label: '服务器入口', value: 'server', iconRight: 'mc-server' },
]

带选项副标题

每个 mc-list-item 支持 subtitle 属性，在选项标签下方显示灰色辅助说明文字。

• 生存模式收集资源、合成物品、生存下去
• 创造模式无限资源，自由建造
• 冒险模式探索世界，无法破坏方块

import { reactive, ref } from 'vue'

const selected = ref('world1')
const multiSelected = ref(['coords', 'autosave'])
const switchStates = reactive({
  music: true,
  sfx: true,
  ambient: false,
})
const dynamicItems = [
  { label: '世界一 · 生存模式', value: 'w1', subtitle: '本地存档' },
  { label: '世界二 · 创造模式', value: 'w2', subtitle: '测试地图' },
  { label: '服务器入口', value: 'server', iconRight: 'mc-server' },
]

带图标

• 生存模式
• 创造模式
• 设置

import { reactive, ref } from 'vue'

const selected = ref('world1')
const multiSelected = ref(['coords', 'autosave'])
const switchStates = reactive({
  music: true,
  sfx: true,
  ambient: false,
})
const dynamicItems = [
  { label: '世界一 · 生存模式', value: 'w1', subtitle: '本地存档' },
  { label: '世界二 · 创造模式', value: 'w2', subtitle: '测试地图' },
  { label: '服务器入口', value: 'server', iconRight: 'mc-server' },
]

通过 icon 在左侧放置图标，icon-right 在右侧放置图标。

自定义左右侧插槽

在单个 mc-list-item 内使用 #left 和 #right 插槽，可以在列表项左右侧放置任意组件（如 McSwitch、McButton 等），插槽会覆盖 icon / icon-right 属性。

插槽区域会与列表项选择事件隔离：点击或键盘操作插槽内的交互组件时，只触发插槽组件自身事件，不会额外触发列表项的 change 事件或列表点击音效。

• 音乐背景音乐音量
  
• 音效游戏内音效
  
• 环境音洞穴、天气等环境音效
  

import { reactive, ref } from 'vue'

const selected = ref('world1')
const multiSelected = ref(['coords', 'autosave'])
const switchStates = reactive({
  music: true,
  sfx: true,
  ambient: false,
})
const dynamicItems = [
  { label: '世界一 · 生存模式', value: 'w1', subtitle: '本地存档' },
  { label: '世界二 · 创造模式', value: 'w2', subtitle: '测试地图' },
  { label: '服务器入口', value: 'server', iconRight: 'mc-server' },
]

插槽参数 { item } 为当前行的 McListItemProps 对象，可据此条件渲染不同内容。

动态列表

需要从数组渲染列表项时，直接使用 Vue 的 v-for。

• 世界一 · 生存模式本地存档
• 世界二 · 创造模式测试地图
• 服务器入口

import { reactive, ref } from 'vue'

const selected = ref('world1')
const multiSelected = ref(['coords', 'autosave'])
const switchStates = reactive({
  music: true,
  sfx: true,
  ambient: false,
})
const dynamicItems = [
  { label: '世界一 · 生存模式', value: 'w1', subtitle: '本地存档' },
  { label: '世界二 · 创造模式', value: 'w2', subtitle: '测试地图' },
  { label: '服务器入口', value: 'server', iconRight: 'mc-server' },
]

隐藏单选框指示器

单选模式下可通过 :show-radio="false" 隐藏左侧单选框，仅通过高亮背景表示选中状态。

• 世界一 · 生存存档最后游玩：2 小时前
• 世界二 · 创造模式最后游玩：昨天
• 世界三 · 服务器入口最后游玩：3 天前

import { reactive, ref } from 'vue'

const selected = ref('world1')
const multiSelected = ref(['coords', 'autosave'])
const switchStates = reactive({
  music: true,
  sfx: true,
  ambient: false,
})
const dynamicItems = [
  { label: '世界一 · 生存模式', value: 'w1', subtitle: '本地存档' },
  { label: '世界二 · 创造模式', value: 'w2', subtitle: '测试地图' },
  { label: '服务器入口', value: 'server', iconRight: 'mc-server' },
]

带禁用项

• 可用的选项
• 已锁定的选项
• 另一个选项

import { reactive, ref } from 'vue'

const selected = ref('world1')
const multiSelected = ref(['coords', 'autosave'])
const switchStates = reactive({
  music: true,
  sfx: true,
  ambient: false,
})
const dynamicItems = [
  { label: '世界一 · 生存模式', value: 'w1', subtitle: '本地存档' },
  { label: '世界二 · 创造模式', value: 'w2', subtitle: '测试地图' },
  { label: '服务器入口', value: 'server', iconRight: 'mc-server' },
]

关闭点击响应样式

每个列表项可设置 :interactive="false"，关闭该项的鼠标指针、悬浮、按下和焦点响应样式。该属性只影响视觉反馈，不会禁用点击、键盘选择或 change 事件；如需彻底禁用请使用 disabled。

• 正常响应样式悬浮和按下时有反馈
• 不响应点击样式仍可点击，但没有悬浮/按下反馈
• 已禁用不可点击

import { reactive, ref } from 'vue'

const selected = ref('world1')
const multiSelected = ref(['coords', 'autosave'])
const switchStates = reactive({
  music: true,
  sfx: true,
  ambient: false,
})
const dynamicItems = [
  { label: '世界一 · 生存模式', value: 'w1', subtitle: '本地存档' },
  { label: '世界二 · 创造模式', value: 'w2', subtitle: '测试地图' },
  { label: '服务器入口', value: 'server', iconRight: 'mc-server' },
]

交互状态

• 悬浮：顶部凸起高光、底部阴影，背景变亮
• 选中：顶部凹陷、底部高光，背景加深（仅 mode="single" / mode="multiple" 时显示）
• 按下：顶部更深凹陷、底部更暗阴影，背景最深

mode 为空时，悬浮和按下效果正常显示，但不会出现选中高亮。

列表项设置 :interactive="false" 时，不显示悬浮、按下、焦点和鼠标指针响应样式。

可用项支持 roving tabindex：当前活动项 tabindex="0"，其余为 -1。任意项都能接收方向键、Home、End、Enter 和 Space。

API

Props

名称	类型	默认	说明
modelValue	string | number | (string | number)[]	''	当前选中值，多选模式为数组（v-model）
mode	'single' | 'multiple' | ''	''	选择模式：空为无选中（可点击），single 单选 / multiple 多选
showRadio	boolean	true	单选模式下是否显示单选框指示器

Item Props

名称	类型	默认	说明
label	string	-	列表项主文本
value	string | number	-	列表项值
disabled	boolean	false	是否禁用该项
interactive	boolean	true	是否显示鼠标悬浮、按下、焦点等响应样式
icon	string	-	左侧图标名称
icon-right	string	-	右侧图标名称
subtitle	string	-	列表项副标题

Events

名称	参数	说明
update:modelValue	(value: McListValue | McListValue[])	v-model 更新事件
change	(value: McListValue | McListValue[])	选中值变化时触发

Slots

名称	作用域	说明
default	-	放置 <mc-list-item> 子节点

Item Slots

名称	作用域	说明
left	{ item: McListItemProps }	自定义当前列表项左侧内容，覆盖 icon 属性
right	{ item: McListItemProps }	自定义当前列表项右侧内容，覆盖 icon-right 属性