HumanBreak/docs/api/user-client-modules/组件 List.md

List 列表组件 API 文档

本文档由 DeepSeek 生成并微调。

组件描述

列表组件用于展示可选择的项目列表，内置滚动条功能和选中项高亮效果。适用于菜单选择、内容导航、设置选项等场景。

---

Props 属性说明

属性名	类型	默认值	描述
list	[string, string][]	必填	列表内容，[id, 显示文本] 的数组
selected	string	必填	当前选中的项 ID
loc	ElementLocator	必填	列表的位置和尺寸
lineHeight	number	18	每行的高度
font	Font	-	列表项的字体样式
winskin	ImageIds	-	使用 winskin 作为光标背景
color	CanvasStyle	-	使用指定样式作为光标背景
border	CanvasStyle	-	使用指定样式作为光标边框
alphaRange	[number, number]	-	选择图标的不透明度范围

---

Events 事件说明

事件名	参数类型	触发时机
update	(key: string)	当用户选中某一项时触发
update:selected	(value: string)	v-model 双向绑定事件

---

Slots 插槽说明

无插槽

---

Exposed Methods 暴露方法

无暴露方法

---

使用示例

基础用法 - 简单列表

import { defineComponent, ref } from 'vue';
import { List } from '@user/client-modules';

export const MyCom = defineComponent(() => {
    const selectedItem = ref('item1');

    // 列表数据：[id, 显示文本]
    const listData = [
        ['item1', '第一项'],
        ['item2', '第二项'],
        ['item3', '第三项'],
        ['item4', '第四项']
    ];

    const handleSelect = (key: string) => {
        console.log('选中项:', key);
        selectedItem.value = key;
    };

    return () => (
        <List
            list={listData}
            v-model:selected={selectedItem.value}
            loc={[0, 0, 100, 300, 0, 0]}
            selected={selectedItem.value}
            onUpdate={handleSelect}
        />
    );
});

带样式的列表

import { defineComponent, ref } from 'vue';
import { List } from '@user/client-modules';

export const StyledListCom = defineComponent(() => {
    const selected = ref('opt2');

    const options = [
        ['opt1', '开始游戏'],
        ['opt2', '游戏设置'],
        ['opt3', '帮助文档'],
        ['opt4', '关于我们']
    ];

    return () => (
        <List
            list={options}
            v-model:selected={selected.value}
            loc={[0, 0, 100, 300, 0, 0]}
            lineHeight={24}
            color="#e3f2fd"
            border="#2196f3"
            borderWidth={1}
        />
    );
});

使用皮肤图片的列表

import { defineComponent, ref } from 'vue';
import { List } from '@user/client-modules';

export const SkinnedListCom = defineComponent(() => {
    const currentSelection = ref('cat');

    const animalList = [
        ['cat', '猫咪'],
        ['dog', '小狗'],
        ['bird', '小鸟'],
        ['fish', '小鱼']
    ];

    const handleUpdate = key => {
        const item = animalList.find(item => item[0] === key)?.[1];
        currentSelection.value = key;
        console.log('选择了:', item);
    };

    return () => (
        <List
            list={animalList}
            selected={currentSelection.value}
            loc={[0, 0, 100, 300, 0, 0]}
            winskin="winskin.png"
            lineHeight={20}
            onUpdate={handleUpdate}
        />
    );
});

长列表滚动示例

import { defineComponent, ref } from 'vue';
import { List } from '@user/client-modules';

export const ScrollListCom = defineComponent(() => {
    const selected = ref('item5');

    // 创建长列表数据
    const longList = Array.from({ length: 20 }, (_, i) => [
        `item${i + 1}`,
        `列表项 ${i + 1}`
    ]);

    return () => (
        <List
            list={longList}
            v-model:selected={selected.value}
            loc={[0, 0, 100, 300, 0, 0]}
            lineHeight={20}
            color="#fff3e0"
            border="#ff9800"
        />
    );
});

---

注意事项

1. 数据格式: list 属性需要 [id, text] 格式的二维数组
2. 选中状态: selected 需要与列表项中的 id 匹配
3. 滚动支持: 自动显示滚动条
4. 样式优先级: 如果设置了 winskin，则 color 和 border 设置将失效