更新记录

1.0.0（2025-10-24）

1.0.0 (2025-10-24)

平台兼容性

uni-app(3.6.12)

uni-app x(3.6.12)

其他

hy-manga-flow

漫画阅读器组件，支持左右分页滑动、双指/双击缩放、图片预加载等功能

功能特性

✨ 核心功能

• 📖 左右滑动翻页 - 流畅的分页阅读体验
• 🔍 双指缩放 - 支持双指手势缩放查看细节
• 👆 双击缩放 - 双击快速放大/缩小
• 🎯 智能交互 - 缩放时自动禁用翻页，保证交互不冲突
• 🖼️ 图片拖动 - 放大后可拖动查看不同区域
• 📊 页码指示器 - 实时显示当前阅读进度
• ⚡ 图片预加载 - 智能预加载相邻页面
• 🔄 加载状态 - 优雅的加载动画和错误处理
• 🛠️ 工具栏 - 可选的快捷操作工具栏

安装方式

方式一：通过uni_modules导入（推荐）

在 DCloud插件市场 搜索 hy-manga-flow 直接导入到项目中

方式二：手动导入

1. 下载组件源码
2. 复制 hy-manga-flow 文件夹到项目的 uni_modules 目录下

基础用法

快速开始

<template>
  <view class="container">
    <hy-manga-flow 
      :images="imageList"
      :current="currentPage"
      @change="onPageChange"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      currentPage: 0,
      imageList: [
        'https://example.com/manga/page1.jpg',
        'https://example.com/manga/page2.jpg',
        'https://example.com/manga/page3.jpg',
        // ...更多图片
      ]
    }
  },
  methods: {
    onPageChange(e) {
      console.log('当前页码：', e.current)
      this.currentPage = e.current
    }
  }
}
</script>

<style>
.container {
  width: 100vw;
  height: 100vh;
}
</style>

API 文档

Props

Events

Methods

通过 ref 调用组件方法：

示例：

<template>
  <hy-manga-flow ref="mangaFlow" :images="imageList" />
</template>

<script>
export default {
  methods: {
    jumpToPage() {
      // 跳转到第5页
      this.$refs.mangaFlow.goToPage(4)
    },
    getCurrentInfo() {
      const current = this.$refs.mangaFlow.getCurrentPage()
      const total = this.$refs.mangaFlow.getImageCount()
      console.log(`当前 ${current + 1} / ${total}`)
    }
  }
}
</script>

使用场景

场景一：基础漫画阅读器

<template>
  <hy-manga-flow 
    :images="mangaPages"
    :current="0"
    :show-indicator="true"
    @change="onPageChange"
  />
</template>

<script>
export default {
  data() {
    return {
      mangaPages: [
        'https://cdn.example.com/manga/ch1/p1.jpg',
        'https://cdn.example.com/manga/ch1/p2.jpg',
        'https://cdn.example.com/manga/ch1/p3.jpg',
      ]
    }
  },
  methods: {
    onPageChange(e) {
      // 保存阅读进度
      uni.setStorageSync('readProgress', e.current)

      // 快读完时加载下一章
      if (e.current >= this.mangaPages.length - 2) {
        this.loadNextChapter()
      }
    },
    loadNextChapter() {
      // 加载下一章逻辑
    }
  }
}
</script>

场景二：带工具栏的阅读器

<template>
  <hy-manga-flow 
    :images="imageList"
    :show-toolbar="true"
    :show-indicator="true"
    :max-scale="5"
    @scale="onImageScale"
  />
</template>

<script>
export default {
  methods: {
    onImageScale(e) {
      console.log(`第${e.index + 1}页缩放到 ${e.scale.toFixed(2)}倍`)

      // 记录用户缩放行为
      if (e.scale > 2) {
        console.log('用户正在查看细节')
      }
    }
  }
}
</script>

场景三：自定义样式

<template>
  <hy-manga-flow 
    :images="imageList"
    :show-indicator="true"
    indicator-bottom="100rpx"
    toolbar-bottom="180rpx"
    loading-text="拼命加载中..."
    error-text="图片走丢了"
  />
</template>

场景四：动态加载图片

<template>
  <view>
    <hy-manga-flow 
      ref="reader"
      :images="currentChapterImages"
      :current="currentPage"
      @change="onPageChange"
    />

    <view class="chapter-nav">
      <button @click="prevChapter">上一章</button>
      <button @click="nextChapter">下一章</button>
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      currentChapter: 1,
      currentPage: 0,
      chapters: {
        1: ['page1.jpg', 'page2.jpg', 'page3.jpg'],
        2: ['page4.jpg', 'page5.jpg', 'page6.jpg'],
      }
    }
  },
  computed: {
    currentChapterImages() {
      return this.chapters[this.currentChapter] || []
    }
  },
  methods: {
    onPageChange(e) {
      this.currentPage = e.current

      // 自动翻章
      if (e.current === this.currentChapterImages.length - 1) {
        setTimeout(() => {
          this.nextChapter()
        }, 1000)
      }
    },
    prevChapter() {
      if (this.currentChapter > 1) {
        this.currentChapter--
        this.currentPage = 0
      }
    },
    nextChapter() {
      if (this.chapters[this.currentChapter + 1]) {
        this.currentChapter++
        this.currentPage = 0
      }
    }
  }
}
</script>

交互说明

手势操作

1. 左右滑动 - 切换上一页/下一页
2. 双指缩放 - 放大/缩小图片查看细节
3. 双击 - 快速放大到预设倍数，再次双击恢复
4. 拖动 - 图片放大后可拖动查看不同区域
5. 单击 - 显示/隐藏工具栏（需开启showToolbar）

交互逻辑

• 图片缩放比例为 1 时：可以左右滑动翻页
• 图片缩放比例 > 1 时：禁用翻页，只能拖动查看当前图片
• 图片缩放接近 1 时：自动重置为 1
• 切换页面时：自动重置所有缩放状态

性能优化

图片优化建议

1. 压缩图片 - 建议使用 WebP 格式，压缩率更高
2. 分辨率控制 - 根据设备宽度提供合适分辨率的图片
3. CDN加速 - 使用 CDN 服务加速图片加载
4. 渐进式加载 - 使用渐进式JPEG提升加载体验

性能优化提示

// 推荐：根据屏幕宽度动态拼接图片URL
const systemInfo = uni.getSystemInfoSync()
const screenWidth = systemInfo.screenWidth
const dpr = systemInfo.pixelRatio || 2

// 计算合适的图片宽度
const imageWidth = Math.ceil(screenWidth * dpr)

// 使用图片处理服务（以阿里云OSS为例）
const optimizedUrl = `${originalUrl}?x-oss-process=image/resize,w_${imageWidth}/quality,q_90/format,webp`

常见问题

Q: 图片显示不完整？

A: 请检查 imageMode 属性设置，默认为 widthFix（宽度固定，高度自适应），如需其他模式请参考 image组件文档

Q: 如何实现长按保存图片？

A: 可以在 page-wrapper 上添加 @longpress 事件：

<template>
  <!-- 需要修改组件源码，或者在外层包装一个组件 -->
  <view @longpress="onLongPress">
    <hy-manga-flow :images="imageList" />
  </view>
</template>

<script>
export default {
  methods: {
    onLongPress() {
      uni.showActionSheet({
        itemList: ['保存图片'],
        success: (res) => {
          if (res.tapIndex === 0) {
            this.saveImage()
          }
        }
      })
    },
    saveImage() {
      // 保存图片逻辑
    }
  }
}
</script>

Q: 如何监听用户阅读时长？

A: 可以在页面生命周期中记录：

export default {
  data() {
    return {
      startTime: 0,
      readDuration: 0
    }
  },
  onShow() {
    this.startTime = Date.now()
  },
  onHide() {
    const duration = Date.now() - this.startTime
    this.readDuration += duration
    console.log('本次阅读时长：', duration, '总时长：', this.readDuration)
  }
}

Q: 能否支持竖向滚动？

A: 当前版本专注于横向翻页的漫画阅读场景。如需竖向滚动，建议使用 scroll-view 或其他滚动组件。