mirror of
https://github.com/unanmed/HumanBreak.git
synced 2025-05-06 07:33:25 +08:00
193 lines
5.8 KiB
Markdown
193 lines
5.8 KiB
Markdown
# Page 分页组件 API 文档
|
||
|
||
本文档由 `DeepSeek R1` 模型生成并微调。
|
||
|
||
## 组件描述
|
||
|
||
分页组件用于将大量内容分割为多个独立页面展示，支持通过编程控制或用户交互进行页面切换。适用于存档界面、多步骤表单等场景。
|
||
|
||
---
|
||
|
||
## Props 属性说明
|
||
|
||
| 属性名 | 类型 | 默认值 | 描述 |
|
||
| -------------- | ---------------- | ----------------- | -------------------------------- |
|
||
| `pages` | `number` | 必填 | 总页数 |
|
||
| `loc` | `ElementLocator` | 必填 | 页码组件定位配置（坐标系及位置） |
|
||
| `font` | `Font` | `Font.defaults()` | 页码文本字体配置（可选） |
|
||
| `hideIfSingle` | `boolean` | `false` | 当总页数为 1 时是否隐藏页码组件 |
|
||
|
||
---
|
||
|
||
## Events 事件说明
|
||
|
||
| 事件名 | 参数类型 | 触发时机 |
|
||
| ------------ | ---------------- | ------------------------------- |
|
||
| `pageChange` | `(page: number)` | 当前页码变化时触发（从 0 开始） |
|
||
|
||
---
|
||
|
||
## Slots 插槽说明
|
||
|
||
### `default`
|
||
|
||
接收当前页码（从 0 开始）并返回需要渲染的内容
|
||
**参数**
|
||
|
||
- `page: number` 当前页码索引（0-based）
|
||
|
||
---
|
||
|
||
## Exposed Methods 暴露方法
|
||
|
||
| 方法名 | 参数 | 返回值 | 描述 |
|
||
| ------------ | --------------- | -------- | --------------------------------------------------- |
|
||
| `changePage` | `page: number` | `void` | 跳转到指定页码（0-based，自动约束在有效范围内） |
|
||
| `movePage` | `delta: number` | `void` | 基于当前页码进行偏移切换（如 +1 下一页，-1 上一页） |
|
||
| `now` | - | `number` | 获取当前页码索引（0-based） |
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 基础用法 - 多页文本展示
|
||
|
||
```tsx
|
||
import { defineComponent } from 'vue';
|
||
import { Page, PageExpose } from '@user/client-modules';
|
||
|
||
export const MyCom = defineComponent(() => {
|
||
return () => (
|
||
<Page pages={3} loc={[208, 208, 208, 208, 0.5, 0.5]}>
|
||
{page => (
|
||
<text
|
||
text={`第 ${page + 1} 页内容`}
|
||
loc={[104, 104, void 0, void 0, 0.5, 0.5]}
|
||
/>
|
||
)}
|
||
</Page>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 监听页面修改
|
||
|
||
```tsx
|
||
import { defineComponent, ref } from 'vue';
|
||
import { Page, PageExpose } from '@user/client-modules';
|
||
|
||
export const MyCom = defineComponent(() => {
|
||
// 示例数据
|
||
const pages = [
|
||
{ content: '第一页内容' },
|
||
{ content: '第二页内容' },
|
||
{ content: '第三页内容' }
|
||
];
|
||
|
||
// 分页组件引用
|
||
const pageRef = ref<PageExpose>();
|
||
|
||
// 页码变化回调
|
||
const handlePageChange = (currentPage: number) => {
|
||
// 可以使用参数获得当前页码，加一是因为页码是从 0 开始的
|
||
console.log(`当前页码：${currentPage + 1}`);
|
||
// 或者也可以使用 Page 组件的接口获得当前页码
|
||
console.log(`当前页码：${pageRef.value!.now() + 1}`);
|
||
};
|
||
|
||
return () => (
|
||
<Page
|
||
pages={pages.length}
|
||
loc={[208, 208, 208, 208, 0.5, 0.5]} // 游戏画面居中
|
||
onPageChange={handlePageChange}
|
||
ref={pageRef}
|
||
>
|
||
{page => <text text={pages[page].content} />}
|
||
</Page>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 动态配置示例
|
||
|
||
```tsx
|
||
import { defineComponent, ref } from 'vue';
|
||
import { Page, PageExpose } from '@user/client-modules';
|
||
|
||
// 带统计面板的复杂分页
|
||
export const MyCom = defineComponent(() => {
|
||
const dataPages = [
|
||
/* 复杂数据结构 */
|
||
];
|
||
|
||
// 暴露方法实现翻页逻辑
|
||
const pageRef = ref<PageExpose>();
|
||
const jumpToAnalysis = () => pageRef.value?.changePage(3); // 1-based
|
||
|
||
return () => (
|
||
<container>
|
||
{/* 分页内容 */}
|
||
<Page
|
||
pages={dataPages.length}
|
||
loc={[208, 208, 208, 208, 0.5, 0.5]}
|
||
hideIfSingle // 如果只有一个页面，那么隐藏底部的页码显示
|
||
ref={pageRef}
|
||
>
|
||
{page => (
|
||
<container>
|
||
{/* 这里面可以写一些复杂的渲染内容，或者单独写成一个组件，把页码作为参数传入 */}
|
||
<text text="渲染内容" />
|
||
<g-rect loc={[50, 50, 100, 50]} stroke />
|
||
</container>
|
||
)}
|
||
</Page>
|
||
|
||
{/* 自定义跳转按钮 */}
|
||
<text
|
||
loc={[108, 180, void 0, void 0, 0.5, 1]} // 左右居中，靠下对齐
|
||
onClick={jumpToAnalysis}
|
||
text="跳转到分析页"
|
||
/>
|
||
</container>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 边缘检测示例
|
||
|
||
```tsx
|
||
import { defineComponent, ref } from 'vue';
|
||
|
||
// 边界处理逻辑
|
||
export const MyCom = defineComponent(() => {
|
||
const pageRef = ref<PageExpose>();
|
||
|
||
// 自定义边界提示
|
||
const handleEdge = () => {
|
||
const current = pageRef.value?.now() ?? 0;
|
||
const total = pageRef.value?.pages ?? 0;
|
||
|
||
// 到达边界时提示（可以换成其他提示方式）
|
||
if (current === 0) core.drawTip('已经是第一页');
|
||
if (current === total - 1) core.drawTip('已经是最后一页');
|
||
};
|
||
|
||
return () => (
|
||
<Page
|
||
pages={8}
|
||
ref={pageRef}
|
||
onPageChange={handleEdge}
|
||
loc={[208, 208, 208, 208, 0.5, 0.5]}
|
||
>
|
||
{page => <text text={`第${page}页`} />}
|
||
</Page>
|
||
);
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **自动约束**：切换页码时会自动约束在 `[0, pages-1]` 范围内
|