70.HarmonyOS NEXT PicturePreview组件深度剖析：从架构设计到核心代码实现

HarmonyOS ETS + 自定义手势 + 矩阵变换 + 懒加载

@Prop listDirection: Axis = Axis.Vertical // 滑动方向（默认垂直）
@Link @Watch('getListMaxLength') imageList: string[] // 双向绑定的图片数据源

@State listBGColor: Color = Color.White // 背景色状态
@State lazyImageList: CommonLazyDataSourceModel<string> // 懒加载数据源

private listScroll: ListScroller = new ListScroller() // 列表滚动控制器
private listAnimationDuration: number = 500 // 滑动动画时长

aboutToAppear(): void {
    this.getListMaxLength()
}

getListMaxLength() {
    this.listMaxLength = this.imageList.length
    this.lazyImageList.clearAndPushAll(this.imageList)
}

setListOffset(offset: number, animationDuration: number = 0) {
    const WIN_SIZE = windowSizeManager.get()
    // 计算主轴尺寸
    let principalAxisSize = this.listDirection === Axis.Horizontal 
        ? WIN_SIZE.width 
        : WIN_SIZE.height
    // 计算偏移量
    let principalAxisOffset = principalAxisSize * this.listIndex + this.listSpace * this.listIndex
    // 执行滚动
    this.listScroll.scrollTo({
        yOffset: this.listDirection === Axis.Horizontal ? 0 : principalAxisOffset,
        xOffset: this.listDirection === Axis.Horizontal ? principalAxisOffset : 0,
        animation: { duration: animationDuration }
    })
}

setListToIndex(index: number) {
    // 边界检查
    let nIndex = Math.max(0, Math.min(index, this.listMaxLength - 1))
    // 计算目标位置
    const principalAxisSize = this.listDirection === Axis.Horizontal 
        ? windowSizeManager.get().width 
        : windowSizeManager.get().height
    const calculatedOffset = nIndex * (principalAxisSize + this.listSpace)
    // 执行跳转
    this.listScroll.scrollTo({
        xOffset: this.listDirection === Axis.Horizontal ? calculatedOffset : 0,
        yOffset: this.listDirection === Axis.Vertical ? calculatedOffset : 0,
        animation: { duration: this.listAnimationDuration }
    })
}

List({ 
    scroller: this.listScroll, 
    space: this.listSpace 
}) {
    LazyForEach(this.lazyImageList, (imageUrl: string, index: number) => {
        ListItem() {
            PicturePreviewImage({
                imageUrl: imageUrl,
                // 传递参数...
            })
        }
        .width("100%")
    })
}

.enableScrollInteraction(false) // 禁用默认滑动
.scrollSnapAlign(ScrollSnapAlign.START) // 对齐方式
.cachedCount(1) // 缓存数量
.listDirection(this.listDirection) // 滑动方向
.scrollBar(BarState.Off) // 隐藏滚动条
.expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])

.borderWidth(1)
.borderColor(Color.Transparent)

.onClick(() => {
    this.listBGColor = this.listBGColor === Color.White 
        ? Color.Black 
        : Color.White
})

@Entry
@Component
struct Example {
    @State images: string[] = [
        "common/image1.jpg",
        "common/image2.jpg",
        "common/image3.jpg"
    ]

    build() {
        Column() {
            PicturePreview({
                imageList: $rawfile(this.images),
                listDirection: Axis.Horizontal
            })
        }
    }
}