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

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）

---

使用示例

基础用法 - 多页文本展示

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>
    );
});

监听页面修改

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>
    );
});

动态配置示例

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>
    );
});

边缘检测示例

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] 范围内