温馨提示：本篇博客的详细代码已发布到 git : https://gitcode.com/nutpi/HarmonyosNext 可以下载运行哦！

Harmonyos NEXT 图片预览组件之工具类实现

效果预览

一、工具类概述

图片预览组件中的工具类是支撑组件功能实现的重要基础设施，它们提供了约束计算、动画效果、窗口管理等核心功能。本文将详细介绍图片预览组件中的三个核心工具类：Constrain、FuncUtils和Managers。

1. 工具类的作用

在图片预览组件中，工具类主要承担以下职责：

1. 约束计算：确保图片在缩放和移动过程中不会超出合理范围
2. 动画处理：提供平滑的动画效果，提升用户体验
3. 窗口管理：提供窗口尺寸信息，用于计算图片的适配大小
4. 旋转计算：提供旋转角度的计算和简化功能

2. 工具类的设计原则

设计原则	说明	实现方式
功能聚焦	每个工具类专注于特定的功能领域	按功能划分为不同的工具类
无状态设计	工具类方法不依赖于内部状态	使用纯函数实现核心功能
参数明确	明确定义参数类型和返回值	使用TypeScript类型系统
复用性高	工具类方法可在多处复用	提供通用的功能接口

二、Constrain - 约束工具

1. 功能概述

Constrain工具类主要负责图片的边界约束和切换判断，确保图片在交互过程中的合理显示。

2. 核心枚举和接口

// 图片适配类型枚举
export enum ImageFitType {TYPE_WIDTH = 'width',TYPE_HEIGHT = 'height',TYPE_DEFAULT = 'default'
}// 约束偏移计算接口
export interface ConstrainOffsetAndAnimationType {// 此次计算的方向 宽或者高dimensionWH: ImageFitType,// 此次图片的默认尺寸imageDefaultSize: image.Size,// 此次图片相对应的偏移信息imageOffsetInfo: OffsetModel,// 此次图片的放大尺寸scaleValue: number,// 当前图片的旋转角度rotate: number,// 当超出限制多少时去判断，取值：0 ~ 1TogglePercent: number,// List 偏移量imageListOffset: number,// 主轴方向listDirection: Axis
}

3. 最大偏移量计算

// 获取最大偏移量
export function getMaxAllowedOffset(winSize: number, imageSize: number, scale: number) {const maxNum = Math.max(imageSize * scale, winSize);const minNum = Math.min(imageSize * scale, winSize);return (maxNum - minNum) / 2;
}

这个函数计算图片在特定方向上可以移动的最大距离。计算逻辑如下：

1. 当图片尺寸大于窗口尺寸时（imageSize * scale > winSize）：

   • maxNum = imageSize * scale
   • minNum = winSize
   • 最大偏移量 = (imageSize * scale - winSize) / 2

2. 当图片尺寸小于窗口尺寸时（imageSize * scale < winSize）：

   • maxNum = winSize
   • minNum = imageSize * scale
   • 最大偏移量 = (winSize - imageSize * scale) / 2

4. 偏移约束函数

function constrainOffset(offset: number, winSize: number, imageSize: number, scale: number): number {let maxAllowedOffset = getMaxAllowedOffset(winSize, imageSize, scale);return Math.min(Math.max(offset, -maxAllowedOffset), maxAllowedOffset);
}

这个函数确保图片的偏移量不会超出允许的范围，通过Math.min和Math.max函数将偏移量限制在[-maxAllowedOffset, maxAllowedOffset]区间内。

5. 切换判断函数

function isToggle(offset: number, winSize: number, imageSize: number, scale: number, TogglePercent: number): boolean {let maxAllowedOffset = getMaxAllowedOffset(winSize, imageSize, scale);const deviation = Math.abs(offset) - maxAllowedOffset;const switchThreshold = winSize * TogglePercent;if (deviation > switchThreshold) {return true}return false
}

这个函数判断是否需要切换图片，通过计算当前偏移量与最大允许偏移量的差值，并与切换阈值（窗口尺寸 * TogglePercent）进行比较。当差值大于阈值时，触发图片切换。

6. 综合约束与动画处理

export function constrainOffsetAndAnimation(info: ConstrainOffsetAndAnimationType): [boolean, boolean] {if (info.dimensionWH === ImageFitType.TYPE_DEFAULT) {return [false, false]}const WIN_SIZE = windowSizeManager.get();const IMG_SIZE = getImgSize(info.imageDefaultSize, info.rotate, info.dimensionWH);const WIN_AXIS_SIZE = WIN_SIZE[info.dimensionWH];let currentOffset = (info.imageOffsetInfo as object)[`last${info.dimensionWH === ImageFitType.TYPE_WIDTH ? 'X' : 'Y'}`];// 计算最后的图片偏移量if (info.dimensionWH === (info.listDirection === Axis.Horizontal ? ImageFitType.TYPE_WIDTH : ImageFitType.TYPE_HEIGHT)) {currentOffset += info.imageListOffset;}const CLAMPED_OFFSET = constrainOffset(currentOffset, WIN_AXIS_SIZE, IMG_SIZE, info.scaleValue);// 如果偏移量发生了变化（即需要修正）if (CLAMPED_OFFSET !== currentOffset) {let updateFn = () => {(info.imageOffsetInfo as object)[`current${info.dimensionWH == ImageFitType.TYPE_WIDTH ? 'X' : 'Y'}`] = CLAMPED_OFFSET;info.imageOffsetInfo.stash();}runWithAnimation(updateFn);// 判断是否需要切换图片let bol = isToggle(currentOffset, WIN_AXIS_SIZE, IMG_SIZE, info.scaleValue, info.TogglePercent);if (bol) {const BOL = currentOffset >= 0 ? true : falsereturn [BOL, !BOL]}}return [false, false]
}

这个函数是边界处理的核心，它综合了偏移约束和动画处理，并返回是否需要切换图片的判断结果。返回值是一个布尔数组：

• 如果dimensionWH是"width"，返回值为[左边超出，右边超出]
• 如果dimensionWH是"height"，返回值为[上边超出，下边超出]

三、FuncUtils - 功能工具

1. 动画执行函数

export function runWithAnimation(fn: Function, duration: number = 300) {animateTo({duration: duration,curve: Curve.Ease,iterations: 1,playMode: PlayMode.Normal,}, fn);
}

这个函数为其他函数执行添加动画效果，使用animateTo API实现平滑的动画过渡。参数说明：

• fn：需要执行的函数
• duration：动画持续时间，默认300毫秒

2. 旋转角度简化函数

export function simplestRotationQuarter(angle: number): number {// 将角度转换为0-360范围内let normalizedAngle = angle % 360;if (normalizedAngle < 0) {normalizedAngle += 360;}// 计算最接近的90度倍数let quarter = Math.round(normalizedAngle / 90) * 90;return quarter;
}

这个函数将任意角度转换为最接近的90度倍数（0°、90°、180°、270°），用于图片旋转时的角度对齐。实现步骤：

1. 将角度归一化到0-360度范围内
2. 计算最接近的90度倍数

四、Managers - 窗口管理器

1. 窗口尺寸管理器

class WindowSizeManager {private size: window.Size = { width: 0, height: 0 };constructor() {// 初始化窗口尺寸this.size = { width: window.getLastWindowSize().width, height: window.getLastWindowSize().height };// 监听窗口尺寸变化window.on('sizeChange', (size: window.Size) => {this.size = size;});}get(): window.Size {return this.size;}
}// 创建单例实例
export const windowSizeManager = new WindowSizeManager();

窗口尺寸管理器是一个单例类，用于获取和管理窗口尺寸信息。它的主要功能包括：

1. 初始化时获取当前窗口尺寸
2. 监听窗口尺寸变化事件，实时更新尺寸信息
3. 提供get()方法获取当前窗口尺寸

五、工具类在组件中的应用

1. 约束工具在边界处理中的应用

evaluateBound(): void {const xBol = constrainOffsetAndAnimation({dimensionWH: ImageFitType.TYPE_WIDTH,imageDefaultSize: this.imageDefaultSize,imageOffsetInfo: this.imageOffsetInfo,scaleValue: this.imageScaleInfo.scaleValue,rotate: this.imageRotateInfo.lastRotate,TogglePercent: this.TogglePercent,imageListOffset: this.imageListOffset,listDirection: this.listDirection});// 根据返回结果决定是否切换图片if (this.listDirection === Axis.Horizontal) {if (xBol[0] || xBol[1]) {if (xBol[0]) {this.setListToIndex(this.imageIndex - 1);}if (xBol[1]) {this.setListToIndex(this.imageIndex + 1);}}}
}

2. 动画工具在状态重置中的应用

resetCurrentImageInfo(): void {runWithAnimation(() => {this.imageScaleInfo.reset();this.imageOffsetInfo.reset();this.imageRotateInfo.reset();this.matrix = matrix4.identity().copy();}, this.restImageAnimation);
}

3. 窗口管理器在尺寸计算中的应用

initCurrentImageInfo(event: ImageLoadResult): void {let imageW = event.width;let imageH = event.height;let windowSize = windowSizeManager.get();// 图片宽高比this.imageWHRatio = imageW / imageH;// 图片默认大小this.imageDefaultSize = this.calcImageDefaultSize(this.imageWHRatio, windowSize);
}

六、总结

图片预览组件中的工具类是组件功能实现的重要支撑，它们通过提供约束计算、动画效果、窗口管理等核心功能，确保了组件的高性能和良好用户体验。

工具类的设计遵循了功能聚焦、无状态设计、参数明确和复用性高的原则，使得代码结构清晰、易于维护。通过合理的工具类抽象，图片预览组件实现了复杂交互逻辑的模块化和可复用性。

在实际应用中，这些工具类不仅服务于图片预览组件，还可以在其他需要类似功能的组件中复用，提高了代码的复用率和开发效率。