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

         ┌───────────────────┐
         │   用户交互层        │
         │ (手势事件处理)      │
         └─────────┬─────────┘
                   │
         ┌─────────▼─────────┐
         │   变换控制层        │
         │ (矩阵运算引擎)      │
         └─────────┬─────────┘
                   │
         ┌─────────▼─────────┐
         │   状态管理层        │
         │ (缩放/位移/旋转)    │
         └─────────┬─────────┘
                   │
         ┌─────────▼─────────┐
         │   渲染输出层        │
         │ (ArkUI图像渲染)    │
         └───────────────────┘

class ScaleModel {
    constructor(
        public defaultScaleValue: number,  // 默认缩放比例
        public scaleValue: number,        // 当前缩放值
        public maxScaleValue: number,     // 最大缩放限制
        public extraScaleValue: number    // 缩放缓冲系数
    ) {}
    
    reset() {
        this.scaleValue = this.defaultScaleValue
    }
    
    stash() {
        this.lastValue = this.scaleValue
    }
}

class OffsetModel {
    constructor(
        public currentX: number,  // 当前X轴偏移
        public currentY: number,  // 当前Y轴偏移
        public lastX: number = 0, // 最后一次X偏移
        public lastY: number = 0  // 最后一次Y偏移
    ) {}
    
    reset() {
        this.currentX = 0
        this.currentY = 0
    }
}

当前偏移量 = 上次偏移量 + 手势移动增量

@State matrix: matrix4.Matrix4Transit = matrix4.identity().copy()

matrix4.identity()          // 初始化单位矩阵
   .scale(x, y)            // 应用缩放
   .rotate(z, angle)       // 应用旋转
   .copy()                 // 生成新矩阵

[ sx  0   0   tx ]
[ 0   sy  0   ty ]
[ 0   0   1   0  ]
[ 0   0   0   1  ]

Image(this.imageUrl)
   .onComplete((event: ImageLoadResult) => {
       this.initCurrentImageInfo(event)
   })

interface ImageLoadResult {
    width: number     // 图片原始宽度
    height: number    // 图片原始高度
    status: number    // 加载状态码
    component: any    // 图片组件实例
}

initCurrentImageInfo(event: ImageLoadResult): void {
    // 计算宽高比
    this.imageWHRatio = event.width / event.height
    
    // 计算默认显示尺寸
    const windowSize = windowSizeManager.get()
    this.imageDefaultSize = this.calcImageDefaultSize(
        this.imageWHRatio, 
        windowSize
    )
    
    // 确定适配策略
    this.imageWH = (this.imageDefaultSize.width === windowSize.width)
        ? ImageFitType.TYPE_WIDTH
        : ImageFitType.TYPE_HEIGHT
        
    // 计算动态最大缩放比例
    const extendRatio = (this.imageWH === ImageFitType.TYPE_WIDTH)
        ? windowSize.height / this.imageDefaultSize.height
        : windowSize.width / this.imageDefaultSize.width
    this.imageScaleInfo.maxScaleValue += extendRatio
}

案例1：竖屏图片（9:16）
原始尺寸：1080x1920 → 直接全屏显示

案例2：横屏图片（16:9）
计算过程：
   屏幕比例 = 1080/1920 ≈ 0.5625
   图片比例 = 16/9 ≈ 1.777
   0.5625 < 1.777 → 按高度适配
   显示宽度 = 1920 * 1.777 ≈ 3413px
   显示高度 = 1920px（屏幕高度）
   
最终显示：横向可滑动查看超出部分

Image(this.imageUrl)
   .width(this.imageWH === TYPE_WIDTH ? '100%' : undefined)
   .height(this.imageWH === TYPE_HEIGHT ? '100%' : undefined)
   .aspectRatio(this.imageWHRatio)
   .objectFit(ImageFit.Cover)

.transform(this.matrix)
.offset({
    x: this.imageOffsetInfo.currentX,
    y: this.imageOffsetInfo.currentY
})

// 在build方法中添加调试文本
Text(`矩阵状态：
缩放: ${this.imageScaleInfo.scaleValue.toFixed(2)}
位移: X=${this.imageOffsetInfo.currentX}, Y=${this.imageOffsetInfo.currentY}
旋转: ${this.imageRotateInfo.currentRotate}°`)
.position({ x: 20, y: 20 })
.zIndex(999)

PanGesture()
   .onActionUpdate((event) => {
       console.log(`手势轨迹: 
       X: ${event.offsetX} 
       Y: ${event.offsetY}
       速度: ${event.speed}`)
   })

aboutToAppear() {
    perfMonitor.startTrack('图片初始化')
    // ...初始化代码...
    perfMonitor.stopTrack('图片初始化')
}