更新记录

1.0.0（2026-09-18）

平台兼容性

uni-app x(5.25)

其他

st-page-flip-canvas

基于 StPageFlip 核心算法深度移植的 uni-app X 原生 Canvas 2D 3D 仿真翻书组件。
具备逼真的纸张弯曲物理效果、动态高光阴影以及顺滑的手势拖拽体验。

✨ 特性一览

• 📖 仿真 3D 纸张物理形变：精确的纸张翻卷几何与光影计算，逼真模拟真实书本翻阅手感。
• ⚡ 原生 Canvas 2D 高效渲染：基于 uni-app X / UTS 开发，深度适配多端，高帧率平滑过渡。
• 📐 确定性尺寸管线：支持外部容器显式尺寸传入与内部自动计算，彻底杜绝自适应导致的页面重排与闪烁。
• 📱 多端手势体系适配：
  • 内置原生 Touch/Mouse 手势支持（点击翻页、滑动翻页、拖拽卷角）。
  • 提供外部手势注入接口（startTouch、moveTouch、endTouch），完美兼容微信小程序 Skyline 手势协商机制。
• 🔄 智能图片增量更新：内置 URL 差异对比机制，在图片逐步下载、画质升级或按需加载时仅重绘变化页，避免整书重建导致重置回第 0 页。
• 🖥️ 单双页自适应 (Spread Mode)：支持移动端单页竖屏、桌面/平板双页并排横屏显示，支持封面 (Cover) 特殊渲染。

平台兼容性

提示：本组件专为 uni-app X 打造，编写语言为 .uvue 和 .uts。

快速上手

由于基于 uni_modules 规范开发，符合 easycom 自动导入机制，安装后在页面中直接使用 <st-page-flip-canvas> 标签即可。

基础示例

<template>
  <view class="container">
    <st-page-flip-canvas
      ref="flipRef"
      canvas-id="myBookCanvas"
      :images="imageList"
      :canvas-width="700"
      :canvas-height="500"
      :flipping-time="800"
      :show-cover="true"
      @flip="onPageFlip"
      @init="onBookInit"
    />

    <view class="controls">
      <button @click="prev">上一页</button>
      <button @click="next">下一页</button>
    </view>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const flipRef = ref<any | null>(null)

// 准备展示的图片列表（支持本地路径与网络路径）
const imageList = ref<string[]>([
  '/static/pages/cover.jpg',
  '/static/pages/page1.jpg',
  '/static/pages/page2.jpg',
  '/static/pages/page3.jpg',
  '/static/pages/back.jpg'
])

function onBookInit(data: any) {
  console.log('书本初始化完成：', data)
}

function onPageFlip(pageIndex: number) {
  console.log('当前页码变更：', pageIndex)
}

function prev() {
  flipRef.value?.flipPrev()
}

function next() {
  flipRef.value?.flipNext()
}
</script>

<style>
.container {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  padding: 20px;
}
.controls {
  display: flex;
  flex-direction: row;
  margin-top: 20px;
  gap: 16px;
}
</style>

属性说明 (Props)

事件说明 (Events)

实例方法 (Methods)

通过在组件上绑定 ref="flipRef" 即可调用内部提供的实例方法：

进阶：高级手势对接（微信小程序 Skyline）

在微信小程序中，如需配合 <horizontal-drag-gesture-handler> 进行手势冲突管理，可结合组件暴露的方法使用：

<horizontal-drag-gesture-handler
  tag="flipGesture"
  worklet:ongesture="onFlipGesture"
>
  <st-page-flip-canvas
    ref="flipRef"
    canvas-id="flipCanvas"
    :images="images"
    :canvas-width="canvasWidth"
    :canvas-height="canvasHeight"
    :disable-flip-by-click="true"
    @flip="onFlip"
  />
</horizontal-drag-gesture-handler>

注意事项

1. 网络图片跨域：在 Web / 小程序端加载网络图片时，需确保图片 CDN 开启了 CORS 跨域头，小程序端需配置合法域名。
2. 尺寸测量：推荐使用 :canvas-width 与 :canvas-height 传入确切的像素尺寸（可根据屏幕宽高在页面 onReady 时计算出保持书本宽高比的尺寸），避免异步测量导致的视觉抖动。