66.Harmonyos NEXT 图片预览组件使用指南

全栈若城

发布于 2025-03-15 13:10:37

6500

代码可运行

文章被收录于专栏：若城技术专栏若城技术专栏

运行总次数：0

代码可运行

Harmonyos NEXT 图片预览组件使用指南

效果预览

一、组件使用概述

图片预览组件是一个功能完善的图片查看器，支持图片的缩放、旋转、滑动切换等功能。本文将详细介绍如何在HarmonyOS应用中集成和使用图片预览组件，帮助开发者快速实现高质量的图片预览功能。

1. 组件功能特点

功能	说明	实现方式
图片缩放	支持双指缩放和双击缩放	PinchGesture和TapGesture
图片旋转	支持双指旋转，自动对齐到90度倍数	RotationGesture
图片拖动	支持单指拖动，边界约束	PanGesture
图片切换	支持水平和垂直方向滑动切换	List和ListScroller
懒加载	支持图片的懒加载，提高性能	CommonLazyDataSourceModel

2. 组件依赖关系

使用图片预览组件需要以下依赖：

组件文件：PicturePreview.ets、PicturePreviewImage.ets
数据模型：ScaleModel.ets、RotateModel.ets、OffsetModel.ets、CommonLazyDataSourceModel.ets
工具类：Constrain.ets、FuncUtils.ets、Managers.ets
常量定义：ImageViewerConstants.ets

二、基本使用方法

1. 引入组件

import { PicturePreview } from "../../components/ImagePreview/PicturePreview";

2. 准备图片数据

@State imageList: string[] = [];

aboutToAppear(): void {
    let imageSource: string = $r("app.media.02") as ESObject;
    this.imageList.push(
        imageSource,
        imageSource,
        imageSource
    )
}

3. 使用组件

build() {
    RelativeContainer() {
        PicturePreview({ 
            imageList: this.imageList, 
            listDirection: Axis.Horizontal 
        })
    }
    .height('100%')
    .width('100%')
}

三、组件参数说明

1. PicturePreview组件参数

参数名	类型	默认值	说明
imageList	string[]	必填	图片数据列表，支持资源引用和网络URL
listDirection	Axis	Axis.Vertical	图片预览的主轴方向，支持水平和垂直滑动

2. 内部状态说明

状态名	类型	说明
listBGColor	Color	背景颜色，点击可切换黑白背景
lazyImageList	CommonLazyDataSourceModel	图片懒加载数据源
listIndex	number	当前视图下标
listMaxLength	number	图片数量

四、使用示例

1. 基本示例

@Entry
@Component
struct PicturePreviewSample {
    @State imageList: string[] = [];
    @State listDirection: Axis = Axis.Horizontal;

    aboutToAppear(): void {
        let imageSource: string = $r("app.media.02") as ESObject;
        this.imageList.push(
            imageSource,
            imageSource,
            imageSource
        )
    }

    build() {
        RelativeContainer() {
            PicturePreview({ imageList: this.imageList, listDirection: this.listDirection })
        }
        .height('100%')
        .width('100%')
    }
}

2. 网络图片示例

@Entry
@Component
struct PicturePreviewNetworkSample {
    @State imageList: string[] = [];
    @State listDirection: Axis = Axis.Horizontal;

    aboutToAppear(): void {
        // 添加网络图片URL
        this.imageList.push(
            "https://example.com/image1.jpg",
            "https://example.com/image2.jpg",
            "https://example.com/image3.jpg"
        )
    }

    build() {
        RelativeContainer() {
            PicturePreview({ imageList: this.imageList, listDirection: this.listDirection })
        }
        .height('100%')
        .width('100%')
    }
}

3. 垂直滑动示例

@Entry
@Component
struct PicturePreviewVerticalSample {
    @State imageList: string[] = [];
    @State listDirection: Axis = Axis.Vertical; // 设置为垂直滑动

    aboutToAppear(): void {
        let imageSource: string = $r("app.media.02") as ESObject;
        this.imageList.push(
            imageSource,
            imageSource,
            imageSource
        )
    }

    build() {
        RelativeContainer() {
            PicturePreview({ imageList: this.imageList, listDirection: this.listDirection })
        }
        .height('100%')
        .width('100%')
    }
}