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

ListPage 列表页面组件 API 文档

本文档由 DeepSeek 生成并微调。

组件描述

列表页面组件结合了列表选择和内容展示功能，左侧显示可选项列表，右侧显示选中项的详细内容。适用于说明文档、设置界面、内容导航等场景。

---

Props 属性说明

属性名	类型	默认值	描述
loc	ElementLocator	必填	组件整体位置和尺寸
basis	number	-	列表区域所占比例
right	boolean	false	列表是否排列在右侧
close	boolean	false	是否显示关闭按钮
closeLoc	ElementLocator	-	关闭按钮的位置（相对于组件定位）
继承自 ListProps	-	-	查看完整属性

---

Events 事件说明

事件名	参数类型	触发时机
close	-	当用户点击关闭按钮时触发
update	(key: string)	继承自 List - 当用户选中某一项时触发
update:selected	(value: string)	继承自 List - v-model 双向绑定事件

---

Slots 插槽说明

default

接收当前选中的 key 并返回对应的内容

参数

• key: string 当前选中的项 ID

具名插槽

以列表项 ID 为名称的具名插槽，用于定义每个选项对应的详细内容

---

使用示例

基础用法 - 说明文档界面

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

export const HelpCom = defineComponent(() => {
    const selected = ref('intro');

    const helpTopics = [
        ['intro', '功能介绍'],
        ['usage', '使用方法'],
        ['settings', '设置说明'],
        ['faq', '常见问题']
    ];

    return () => (
        <ListPage
            list={helpTopics}
            v-model:selected={selected.value}
            loc={[208, 208, 400, 300, 0.5, 0.5]}
            basis={0.3}
        >
            {{
                // 使用具名插槽定义每个选项的内容
                intro: () => (
                    <container>
                        <text text="这里是最新版本的功能介绍..." loc={[0, 0]} />
                        <text text="欢迎使用本系统" loc={[0, 40]} />
                    </container>
                ),
                usage: () => (
                    <container>
                        <text text="使用方法指南" loc={[0, 0]} />
                        <text text="1. 点击左侧菜单选择功能" loc={[0, 40]} />
                        <text text="2. 在右侧查看详细说明" loc={[0, 80]} />
                    </container>
                ),
                settings: () => <text text="设置说明内容..." loc={[0, 0]} />,
                faq: () => <text text="常见问题解答..." loc={[0, 0]} />
            }}
        </ListPage>
    );
});

使用默认插槽

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

export const SimpleCom = defineComponent(() => {
    const selected = ref('item1');

    const items = [
        ['item1', '选项一'],
        ['item2', '选项二'],
        ['item3', '选项三']
    ];

    return () => (
        <ListPage
            list={items}
            v-model:selected={selected.value}
            loc={[208, 208, 350, 250, 0.5, 0.5]}
        >
            {key => (
                <container>
                    <text
                        text={`当前选中: ${items.find(item => item[0] === key)?.[1]}`}
                        loc={[0, 0]}
                    />
                    <text text={`ID: ${key}`} loc={[0, 30]} />
                </container>
            )}
        </ListPage>
    );
});

带关闭按钮的弹窗

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

export const ModalCom = defineComponent(props => {
    const selected = ref('weapon');

    const gameItems = [
        ['weapon', '武器'],
        ['armor', '防具'],
        ['potion', '药水'],
        ['material', '材料']
    ];

    const handleClose = () => {
        props.controller.close(props.instance);
        console.log('关闭物品栏');
    };

    return () => (
        <ListPage
            list={gameItems}
            v-model:selected={selected.value}
            loc={[208, 208, 400, 320, 0.5, 0.5]}
            close
            // 设定关闭按钮的位置
            closeLoc={[0, 300]}
            basis={0.35}
            onClose={handleClose}
        >
            {{
                weapon: () => (
                    <container>
                        <text text="武器列表" loc={[0, 0]} />
                        <text text="• 长剑" loc={[0, 30]} />
                        <text text="• 弓箭" loc={[0, 60]} />
                        <text text="• 法杖" loc={[0, 90]} />
                    </container>
                ),
                armor: () => <text text="防具装备信息..." loc={[0, 0]} />,
                potion: () => <text text="药水效果说明..." loc={[0, 0]} />,
                material: () => <text text="合成材料列表..." loc={[0, 0]} />
            }}
        </ListPage>
    );
});

列表在右侧的布局

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

export const RightListCom = defineComponent(() => {
    const selected = ref('profile');

    const menuItems = [
        ['profile', '个人资料'],
        ['security', '安全设置'],
        ['privacy', '隐私设置'],
        ['notifications', '通知设置']
    ];

    return () => (
        <ListPage
            list={menuItems}
            v-model:selected={selected.value}
            loc={[240, 240, 500, 280, 0.5, 0.5]}
            right
            basis={0.4}
        >
            {key => (
                <container>
                    <text text="显示一些内容..." loc={[0, 60]} />
                    <text text="这里是详细的设置内容..." loc={[0, 0]} />
                </container>
            )}
        </ListPage>
    );
});

---

注意事项

1. 插槽使用: 可以使用具名插槽（以列表项 ID 为名）或默认插槽来定义内容
2. 布局控制: 通过 basis 控制列表区域比例，right 控制列表位置
3. 关闭功能: 设置 close 为 true 显示关闭按钮，通过 closeLoc 自定义位置
4. 事件处理: close 事件需要手动处理界面关闭逻辑
5. 内容更新: 切换列表选项时，右侧内容会自动更新为对应插槽的内容