mirror of
https://github.com/unanmed/HumanBreak.git
synced 2025-10-21 05:22:58 +08:00
227 lines
7.1 KiB
Markdown
227 lines
7.1 KiB
Markdown
# ListPage 列表页面组件 API 文档
|
|
|
|
本文档由 `DeepSeek` 生成并微调。
|
|
|
|
## 组件描述
|
|
|
|
列表页面组件结合了列表选择和内容展示功能，左侧显示可选项列表，右侧显示选中项的详细内容。适用于说明文档、设置界面、内容导航等场景。
|
|
|
|
---
|
|
|
|
## Props 属性说明
|
|
|
|
| 属性名 | 类型 | 默认值 | 描述 |
|
|
| ------------------ | ---------------- | ------- | ---------------------------------------------- |
|
|
| `loc` | `ElementLocator` | 必填 | 组件整体位置和尺寸 |
|
|
| `basis` | `number` | - | 列表区域所占比例 |
|
|
| `right` | `boolean` | `false` | 列表是否排列在右侧 |
|
|
| `close` | `boolean` | `false` | 是否显示关闭按钮 |
|
|
| `closeLoc` | `ElementLocator` | - | 关闭按钮的位置（相对于组件定位） |
|
|
| 继承自 `ListProps` | - | - | [查看完整属性](./组件%20List#Props%20属性说明) |
|
|
|
|
---
|
|
|
|
## Events 事件说明
|
|
|
|
| 事件名 | 参数类型 | 触发时机 |
|
|
| ----------------- | ----------------- | ------------------------------------ |
|
|
| `close` | - | 当用户点击关闭按钮时触发 |
|
|
| `update` | `(key: string)` | 继承自 List - 当用户选中某一项时触发 |
|
|
| `update:selected` | `(value: string)` | 继承自 List - v-model 双向绑定事件 |
|
|
|
|
---
|
|
|
|
## Slots 插槽说明
|
|
|
|
### `default`
|
|
|
|
接收当前选中的 key 并返回对应的内容
|
|
|
|
**参数**
|
|
|
|
- `key: string` 当前选中的项 ID
|
|
|
|
### 具名插槽
|
|
|
|
以列表项 ID 为名称的具名插槽，用于定义每个选项对应的详细内容
|
|
|
|
---
|
|
|
|
## 使用示例
|
|
|
|
### 基础用法 - 说明文档界面
|
|
|
|
```tsx
|
|
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>
|
|
);
|
|
});
|
|
```
|
|
|
|
### 使用默认插槽
|
|
|
|
```tsx
|
|
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>
|
|
);
|
|
});
|
|
```
|
|
|
|
### 带关闭按钮的弹窗
|
|
|
|
```tsx
|
|
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>
|
|
);
|
|
});
|
|
```
|
|
|
|
### 列表在右侧的布局
|
|
|
|
```tsx
|
|
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. **内容更新**: 切换列表选项时，右侧内容会自动更新为对应插槽的内容
|