更新记录

1.0.0（2026-03-06） 下载此版本

1.0.0 微信小程序长截图功能

平台兼容性

LongSnapshot 长图生成组件（微信小程序版）

该组件用于在微信小程序中生成“长图”，并提供保存到相册能力。

注意：微信小程序不支持直接把页面 DOM（slot 内容）截图导出。
本组件采用 Canvas 分段绘制 + 合并 的方式生成长图，因此你需要提供一个 draw 绘制函数，把要展示的内容“画”到 Canvas 上。

组件文件

• 组件实现：components/long-snapshot.vue
• 测试页面：pages/test.vue

能力与限制

• 能力

  • 生成超长图片（通过分段导出再合并）。
  • 生成后得到临时文件路径（tempFilePath）。
  • 保存到系统相册：uni.saveImageToPhotosAlbum。

• 限制

  • 组件 slot 内的内容仅用于页面展示，不会自动变成截图内容；截图内容完全取决于 draw 绘制函数。
  • 受小程序 Canvas 限制，单张画布的物理像素边长通常不能过大；组件内通过 maxCanvasSide 与分段策略规避超限，但内容过长仍可能合并失败。
  • 分享给好友（open-type="share"）分享的是小程序卡片；小程序卡片 imageUrl 通常要求网络图片，本地 tempFilePath 不能直接作为分享卡片图。

Props

• image: string

  • 默认：''
  • 说明：外部传入图片路径（一般不需要；生成结果会写入内部 imagePath，并通过 generated 事件抛出）。

• backgroundColor: string

  • 默认：'#0b0b0b'
  • 说明：画布背景色（建议不要透明，避免部分机型导出异常/发黑）。

• quality: number

  • 默认：1
  • 说明：导出 PNG 质量（0~1）。

• segmentHeight: number

  • 默认：1400
  • 说明：分段绘制的逻辑高度（px）。越小越稳，但生成更慢。

• maxCanvasSide: number

  • 默认：8192
  • 说明：单张画布允许的物理像素最大边长。当内容过大时组件会自动降低缩放比例，避免超限导致全黑/截断/导出失败。

Events

• start

  • 开始生成时触发。

• generated(tempFilePath)

  • 生成成功触发，参数为图片临时路径（可用于预览/保存）。

• error(err)

  • 生成失败触发，参数为错误对象。

Methods（通过 ref 调用）

handleGenerate(options)

生成长图。

options 支持：

• width：逻辑宽度（px）
• height：逻辑高度（px）
• draw(ctx, width, height, offsetY, totalHeight)：绘制函数
  • ctx：Canvas 上下文（已按缩放处理，你只需要用逻辑坐标绘制）
  • width / height：当前段的逻辑尺寸
  • offsetY：当前段在整张长图中的逻辑 Y 偏移（用于只绘制可见段内容）
  • totalHeight：整张长图的逻辑总高度

handleSave()

保存当前生成的图片到相册（要求已经生成成功且有有效路径）。

使用示例（推荐写法）

在页面中：

<template>
  <view>
    <long-snapshot
      ref="snapshotRef"
      @start="generating = true"
      @generated="onGenerated"
      @error="onError"
    >
      <template v-slot:snapshot>
        <!-- 仅用于页面展示 -->
        <view>这里展示内容</view>
      </template>
    </long-snapshot>

    <uv-button :loading="generating" @click="gen">
      生成长图
    </uv-button>
  </view>
</template>

<script>
import LongSnapshot from '@/components/long-snapshot.vue'

export default {
  components: { LongSnapshot },
  data() {
    return {
      generating: false,
      img: ''
    }
  },
  methods: {
    gen() {
      const { windowWidth } = uni.getSystemInfoSync()
      this.$refs.snapshotRef.handleGenerate({
        width: windowWidth,
        height: 6750,
        draw: this.drawPoster
      })
    },
    drawPoster(ctx, width, height, offsetY, totalHeight) {
      // 按需绘制：示例仅演示结构，具体内容参考 pages/test.vue 的 drawContent
      ctx.setFillStyle('#ffffff')
      ctx.setFontSize(16)
      ctx.fillText(`offsetY=${offsetY}`, 20, 40)
    },
    onGenerated(tempPath) {
      this.generating = false
      this.img = tempPath
    },
    onError() {
      this.generating = false
    }
  }
}
</script>

常见问题

1) 生成图片全黑 / 不完整

通常原因：

• 画布物理像素尺寸超限（宽/高过大）
• segmentHeight 太大导致单段导出失败
• 合并画布尺寸超限

建议：

• 降低 segmentHeight
• 降低生成逻辑高度（或减少内容）
• 保持 maxCanvasSide 在 8192（更稳）

2) 分享给好友如何带长图？

小程序分享卡片的 imageUrl 通常需要网络图片。

常见做法：

• 生成后将图片上传到服务器，返回一个 https:// 图片 URL
• 在 onShareAppMessage 中把该 URL 作为 imageUrl