# quick-preveiw

**Repository Path**: leggodd/quick-preveiw

## Basic Information

- **Project Name**: quick-preveiw
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-26
- **Last Updated**: 2026-01-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MediaPreview

#### 介绍

- 鸿蒙原生，唯一支持按需加载，消耗资源最小的图片预览插件
- 简单易用，支持图片、视频、动图（或者自定义其他)等预览
- 可完全自定义使用，非常方便
- 超多 API 可实现全部需求，比如缩放，长图，视频播放，live 图预览
- 基于 V2 版本开发，精细控制渲染性能，大型应用开发，跨层级状态共享，复杂的状态管理需求

#### 安装教程

执行安装命令
`ohpm install @xcx/quick-preview`
#### >=1.0.1效果预览
![preview](src/main/resources/base/media/preview2.gif)
#### 1.0.0效果预览
![preview](src/main/resources/base/media/preview.gif)

#### API
# QuickPreviewOptions 配置参数手册

`QuickPreviewOptions` 是一个基于 Builder 模式设计的图片/视频预览配置类，支持链式调用，用于快速构建沉浸式的媒体预览体验。

---

### 1. 基础属性配置

| 属性名 | 类型 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| **dataList** | `T[]` | `[]` | 预览的数据源列表，要求继承自 `MediaModel`。 |
| **initIndex** | `number` | `0` | 初始化显示的媒体索引（从 0 开始）。 |
| **backgroundColor** | `ResourceColor` | `'#000000'` | 预览页面的背景色。 |
| **duration** | `number` | `300` | 动画执行时长（单位：ms）。 |
| **showPageText** | `boolean` | `true` | 是否在顶部中央显示分页文字（如：1 / 5）。 |
| **indicator** | `DotIndicator \| DigitIndicator \| boolean` | `false` | 设置指示器样式（圆点/数字）或关闭。 |

### 2. 交互控制

| 属性名 | 类型 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| **dismissOnTap** | `boolean` | `true` | 是否支持点击屏幕任意位置关闭预览。 |
| **dismissOnDrag** | `boolean` | `true` | 是否支持通过下拉或拖动操作关闭预览。 |
| **dismissOnSystemBack** | `boolean` | `true` | 是否支持通过系统物理返回键/手势关闭。 |
| **minScale** | `number` | `0.5` | 最小缩放比例。 |
| **maxScale** | `number` | `3` | 最大缩放比例。 |
| **extraScale** | `number` | `0.5` | 额外缩放比例（用于提升缩放时的回弹体验）。 |

### 3. 事件监听 (Listeners)

| 属性名 | 类型 | 说明 |
| :--- | :--- | :--- |
| **onZoomEnable** | `(item: T, index: number) => boolean` | 是否允许特定项进行缩放操作，默认全开启。 |
| **onPageChangedListener** | `(item: T, index: number) => void` | 翻页后的回调，返回当前项数据和索引。 |
| **onLongPressListener** | `(item: T, index: number) => void` | 长按事件回调（常用于弹出保存图片、识别二维码菜单）。 |
| **onBackListener** | `() => void` | 预览页关闭或返回时的自定义业务回调。 |


---


#### 使用说明
简单使用，使用作者默认效果
```
import { DefaultMediaModel, DefaultMediaType, QuickPreview, QuickPreviewOptions } from '@xcx/quick-preview'
@ComponentV2
struct Test2 {
  @Local resources: DefaultMediaModel[] = [
    new DefaultMediaModel({
      src: 'http资源'
    }),
    new DefaultMediaModel({
      src: 'http资源',
    }),
    new DefaultMediaModel({
      src: 'http资源',
      type: DefaultMediaType.VIDEO
    }),
    new DefaultMediaModel({
      src: 'http资源',
      video: 'http资源',
      type: DefaultMediaType.LIVE_PHOTO
    })
  ]
  @Local options: QuickPreviewOptions<DefaultMediaModel> = new QuickPreviewOptions()

  build() {
    Button("图片预览")
      .onClick(() => {
        this.options
          .setInitIndex(0)
          .setMedias(this.resources)
        QuickPreview.open(this.getUIContext(), this.options)
      })
  }
}
```


#### 完全自定义

重写这些， 包括你要预览的类型，包括预览类型（图片、动图、视频），比如，复制下面的代码，如果只想图片预览，可以自己实现 `DefaultImageItem` 即可。

```c
import {
  MediaModel,
  MediaPreviewComponent,
  QuickPreviewOptions,
  PreviewCloseParam,
  PromptActionTool
} from "@xcx/quick-preview"
//下面3个完全自定义
import { DefaultImageItem } from "./DefaultImageItem";
import { DefaultLivePhotoItem } from "./DefaultLivePhotoItem";
import { DefaultVideoItem } from "./DefaultViedeoItem";
//这个非必须，不自定义，就在最上面的 import 引入
import { DefaultMediaModel, DefaultMediaType } from "./DefaultMediaModel";
@ComponentV2
export struct DefaultPreview {
  @Require @Param option: QuickPreviewOptions<DefaultMediaModel>

  build() {
    MediaPreviewComponent({
      options: this.option,
      contentBuilder: this.option.contentBuilder ? this.option.contentBuilder :
        (item: DefaultMediaModel, index: number) => {
          if (item.type == DefaultMediaType.IMAGE) {
            this.imageBuilder(item, index)
          } else if (item.type == DefaultMediaType.VIDEO) {
            this.videoBuilder(item, index)
          } else if (item.type == DefaultMediaType.LIVE_PHOTO) {
            this.livePhotoBuilder(item, index)
          }
        },
      // thumbBuilder: this.option.thumbBuilder,
      toolBuilder: this.option.toolBuilder,
    })
      .width('100%')
      .height('100%')
  }

  @Builder
  imageBuilder(item: DefaultMediaModel, index: number) {
    DefaultImageItem({
      resource: item,
      index: index,
    })
  }

  @Builder
  videoBuilder(item: DefaultMediaModel, index: number) {
    DefaultVideoItem({
      resource: item,
      index: index,
    })
  }

  @Builder
  livePhotoBuilder(item: DefaultMediaModel, index: number) {
    DefaultLivePhotoItem({
      resource: item,
      index: index,
    })
  }
}

@Builder
export function DefaultPreviewBuilder(option: QuickPreviewOptions<ESObject>) {
  DefaultPreview({
    option: option,
  })
}

```

自定义上面内容之后，再像`简单使用`使用中的例子一样使用即可做到完全自定义
#### 开源协议

[Apache-2.0](LICENSE)