鸿蒙学习实战之路 - 图片预览功能实现

官方文档永远是你的好伙伴，请收藏!

华为开发者联盟 - 图片预览最佳实践
 华为开发者联盟 - Image 组件使用指南

关于本文

本文主要介绍在 HarmonyOS 中如何实现高性能、高体验的图片预览功能，包含基础实现和高级优化技巧

本文并不能代替官方文档，所有内容基于官方文档+实践记录
所有代码示例都有详细注释，建议自己动手尝试
基本所有关键功能都会附上对应的文档链接，强烈建议你点看看看

概述

图片预览功能是移动应用中常见的功能，用于放大查看图片详情，支持手势操作（缩放、平移等）。在 HarmonyOS 中，我们可以使用 Image 组件结合手势识别来实现图片预览功能，但要实现流畅的预览体验，还需要掌握一些优化技巧。

实现原理

关键技术

图片预览功能主要通过以下核心技术实现：

Image 组件 - 加载和显示图片资源
手势识别 - 实现缩放、平移等交互操作
动画效果 - 实现平滑的过渡和变换
状态管理 - 管理图片的缩放级别、位置等状态

重要提醒！

实现高性能图片预览需要注意：

图片资源需要适当处理，避免占用过多内存

合理设置手势识别的灵敏度和边界条件

考虑大图预览时的性能优化和内存管理

开发流程

实现图片预览的基本步骤：

创建 Image 组件加载图片
配置手势识别（缩放、平移）
实现手势事件处理逻辑
添加过渡动画效果
优化性能和用户体验

华为开发者联盟 - 手势识别参考文档

基础图片预览实现

场景描述

在应用中点击缩略图后，打开大图预览界面，支持手势缩放和平移查看图片详情。

效果如图所示：

开发步骤

1. 创建基础的图片预览页面

首先创建一个基本的页面结构，用于显示预览图片：

typescript 复制代码

@Entry
@Component
struct ImagePreviewPage {
  // 图片地址
  @State imageUrl: string = '';
  // 图片缩放级别
  @State scale: number = 1.0;
  // 图片平移偏移量
  @State offsetX: number = 0;
  @State offsetY: number = 0;

  build() {
    Column() {
      // 预览图片容器
      Stack() {
        // 图片组件
        Image(this.imageUrl)
          .width('100%')
          .height('100%')
          .objectFit(ImageFit.Contain)
          .transform(
            [
              { scale: this.scale },
              { translateX: this.offsetX },
              { translateY: this.offsetY }
            ]
          )
      }
      .width('100%')
      .height('100%')
      .backgroundColor('#000000')
    }
  }
}

2. 添加手势识别

为图片组件添加手势识别，支持缩放和平移操作：

typescript 复制代码

Image(this.imageUrl)
  .width("100%")
  .height("100%")
  .objectFit(ImageFit.Contain)
  .transform([
    { scale: this.scale },
    { translateX: this.offsetX },
    { translateY: this.offsetY },
  ])
  // 添加缩放手势
  .gesture(
    PinchGesture()
      .onActionUpdate((event: GestureEvent) => {
        // 更新缩放级别
        this.scale = event.scale;
      })
      .onActionEnd(() => {
        // 限制最大缩放级别
        if (this.scale > 3.0) {
          this.scale = 3.0;
        }
        // 限制最小缩放级别
        if (this.scale < 1.0) {
          this.scale = 1.0;
        }
      })
  )
  // 添加平移手势
  .gesture(
    PanGesture().onActionUpdate((event: GestureEvent) => {
      // 更新平移偏移量
      this.offsetX += event.offsetX;
      this.offsetY += event.offsetY;
    })
  );

3. 实现双击缩放效果

为图片组件添加双击手势，实现快速缩放功能：

typescript 复制代码

// 添加双击手势
.gesture(
  TapGesture({ count: 2 })
    .onAction(() => {
      // 双击切换缩放级别
      if (this.scale === 1.0) {
        this.scale = 2.0;
      } else {
        this.scale = 1.0;
        this.offsetX = 0;
        this.offsetY = 0;
      }
    })
)

高级图片预览实现

场景描述

实现带有图片切换、加载动画、双击缩放和边界限制的高级图片预览功能。

效果如图所示：

开发步骤

1. 实现图片切换功能

添加图片列表和切换功能：

typescript 复制代码

@Entry
@Component
struct AdvancedImagePreviewPage {
  // 图片列表
  @State imageList: string[] = [];
  // 当前图片索引
  @State currentIndex: number = 0;
  // 图片缩放级别
  @State scale: number = 1.0;
  // 图片平移偏移量
  @State offsetX: number = 0;
  @State offsetY: number = 0;
  // 图片加载状态
  @State isLoading: boolean = true;

  build() {
    Column() {
      // 预览图片容器
      Stack() {
        // 图片组件
        Image(this.imageList[this.currentIndex])
          .width('100%')
          .height('100%')
          .objectFit(ImageFit.Contain)
          .transform(
            [
              { scale: this.scale },
              { translateX: this.offsetX },
              { translateY: this.offsetY }
            ]
          )
          .onLoad(() => {
            // 图片加载完成
            this.isLoading = false;
          })
          .onError(() => {
            // 图片加载失败
            this.isLoading = false;
          })

        // 加载指示器
        if (this.isLoading) {
          LoadingProgress()
            .width(40)
            .height(40)
            .color(Color.White)
        }
      }
      .width('100%')
      .height('100%')
      .backgroundColor('#000000')
      .gesture(
        // 添加滑动切换图片手势
        PanGesture({ direction: PanDirection.Horizontal })
          .onActionEnd((event: GestureEvent) => {
            // 判断滑动方向
            if (event.velocityX > 200 && this.currentIndex < this.imageList.length - 1) {
              // 向右滑动，下一张图片
              this.nextImage();
            } else if (event.velocityX < -200 && this.currentIndex > 0) {
              // 向左滑动，上一张图片
              this.previousImage();
            }
          })
      )

      // 图片切换指示器
      Row() {
        Text(`${this.currentIndex + 1}/${this.imageList.length}`)
          .fontSize(16)
          .fontColor(Color.White)
          .margin({ bottom: 20 })
      }
      .position({ bottom: 0, left: 0, right: 0 })
    }
  }

  // 切换到下一张图片
  private nextImage(): void {
    this.resetImageState();
    this.currentIndex++;
  }

  // 切换到上一张图片
  private previousImage(): void {
    this.resetImageState();
    this.currentIndex--;
  }

  // 重置图片状态
  private resetImageState(): void {
    this.scale = 1.0;
    this.offsetX = 0;
    this.offsetY = 0;
    this.isLoading = true;
  }
}

2. 实现边界限制和自动居中

添加边界限制逻辑，防止图片平移超出合理范围：

typescript 复制代码

// 更新边界限制函数
private updateBounds(): void {
  // 获取图片实际显示尺寸
  const imageWidth = 360 * this.scale; // 假设屏幕宽度为360
  const imageHeight = 640 * this.scale; // 假设屏幕高度为640
  const screenWidth = 360;
  const screenHeight = 640;

  // 计算最大允许的平移偏移量
  const maxOffsetX = (imageWidth - screenWidth) / 2;
  const maxOffsetY = (imageHeight - screenHeight) / 2;

  // 限制X轴偏移量
  if (this.offsetX > maxOffsetX) {
    this.offsetX = maxOffsetX;
  } else if (this.offsetX < -maxOffsetX) {
    this.offsetX = -maxOffsetX;
  }

  // 限制Y轴偏移量
  if (this.offsetY > maxOffsetY) {
    this.offsetY = maxOffsetY;
  } else if (this.offsetY < -maxOffsetY) {
    this.offsetY = -maxOffsetY;
  }

  // 当缩放级别小于等于1时，自动居中
  if (this.scale <= 1.0) {
    this.offsetX = 0;
    this.offsetY = 0;
  }
}

// 在手势结束时调用边界限制
PinchGesture()
  .onActionUpdate((event: GestureEvent) => {
    this.scale = event.scale;
  })
  .onActionEnd(() => {
    // 限制最大缩放级别
    if (this.scale > 3.0) {
      this.scale = 3.0;
    }
    // 限制最小缩放级别
    if (this.scale < 1.0) {
      this.scale = 1.0;
    }
    // 更新边界
    this.updateBounds();
  })

PanGesture()
  .onActionUpdate((event: GestureEvent) => {
    this.offsetX += event.offsetX;
    this.offsetY += event.offsetY;
  })
  .onActionEnd(() => {
    // 更新边界
    this.updateBounds();
  })

3. 添加过渡动画效果

为图片切换和状态变化添加过渡动画：

typescript 复制代码

// 图片组件添加过渡动画
Image(this.imageList[this.currentIndex])
  .width("100%")
  .height("100%")
  .objectFit(ImageFit.Contain)
  .transform([
    { scale: this.scale },
    { translateX: this.offsetX },
    { translateY: this.offsetY },
  ])
  // 添加过渡动画
  .transition(
    TransitionEffect.OPACITY.animation({
      duration: 300,
      curve: Curve.EaseInOut,
    })
  )
  .keyframeAnimation((options: KeyframeAnimationOptions) => {
    // 定义关键帧动画
    options.duration = 300;
    options.curve = Curve.EaseInOut;
  });

性能优化建议

1. 图片资源优化

使用适当分辨率的图片，避免加载过大的图片资源
考虑使用图片压缩和格式优化
实现图片懒加载，只在需要时加载图片

typescript 复制代码

// 图片懒加载示例
Image(this.imageUrl)
  .width("100%")
  .height("100%")
  .objectFit(ImageFit.Contain)
  .placeholder("resources/rawfile/placeholder.png") // 设置占位图
  .interpolation(ImageInterpolation.High) // 设置图片插值质量
  .sourceSize({
    width: 1080, // 期望的图片宽度
    height: 1920, // 期望的图片高度
  });

2. 内存管理优化

及时释放不再使用的图片资源
限制同时加载的图片数量
考虑使用图片缓存策略

typescript 复制代码

// 图片缓存示例
import { ImageCache } from "@ohos/image-cache";

// 创建图片缓存实例
const imageCache = new ImageCache();

// 加载图片并缓存
async function loadImage(url: string): Promise<string> {
  try {
    // 检查缓存
    const cachedImage = imageCache.get(url);
    if (cachedImage) {
      return cachedImage;
    }

    // 加载图片
    const image = await imageCache.load(url);
    // 缓存图片
    imageCache.put(url, image);
    return image;
  } catch (error) {
    console.error("加载图片失败:", error);
    return "";
  }
}

3. 动画性能优化

使用硬件加速的动画效果
避免在动画期间进行复杂的计算
合理设置动画的持续时间和曲线

typescript 复制代码

// 优化动画性能示例
Image(this.imageUrl)
  .width("100%")
  .height("100%")
  .objectFit(ImageFit.Contain)
  .transform([
    { scale: this.scale },
    { translateX: this.offsetX },
    { translateY: this.offsetY },
  ])
  // 使用硬件加速
  .accelerate(true)
  // 优化动画性能
  .animation({
    duration: 300,
    curve: Curve.EaseInOut,
    iterations: 1,
    playMode: PlayMode.Normal,
  });

交互体验优化

1. 添加手势反馈

为手势操作添加视觉反馈
实现平滑的过渡效果
考虑添加声音反馈

2. 优化用户体验

添加图片保存功能
实现图片分享功能
考虑支持多图片预览和切换

typescript 复制代码

// 图片保存功能示例
import { image } from "@ohos.multimedia.image";
import { fileio } from "@ohos.fileio";

async function saveImage(imageUrl: string): Promise<boolean> {
  try {
    // 加载图片
    const imageSource = image.createImageSource(imageUrl);
    // 获取图片编码数据
    const imageData = await imageSource.createPixelMap();
    // 保存图片到本地
    const filePath = `${getContext(this).cacheDir}/saved_image.jpg`;
    const file = await fileio.open(
      filePath,
      fileio.OpenMode.READ_WRITE | fileio.OpenMode.CREATE
    );
    await imageData.writeToStream(file.fd, {
      format: image.Format.JPEG,
      quality: 90,
    });
    await fileio.close(file.fd);
    return true;
  } catch (error) {
    console.error("保存图片失败:", error);
    return false;
  }
}

总结

本文介绍了在 HarmonyOS 中实现图片预览功能的完整流程，从基础实现到高级优化，包含了以下关键内容：

基础实现：创建图片预览页面，添加手势识别（缩放、平移、双击）
高级实现：实现图片切换、加载动画、边界限制和过渡效果
性能优化：图片资源优化、内存管理优化、动画性能优化
交互体验优化：添加手势反馈、优化用户体验

官方文档永远是你的好伙伴！

强烈建议你查看华为开发者联盟 - 图片预览最佳实践获取更详细的信息。

通过本文的学习，你可以在 HarmonyOS 应用中实现高性能、高体验的图片预览功能，提升用户体验和应用质量。