鸿蒙开发：刷新库V2装饰器适配

原创

程序员一鸣

发布于 2025-03-24 09:49:55

540

文章被收录于专栏：HarmonyOS点石成金HarmonyOS点石成金

前言

本文基于Api13

之前开发过一个刷新库，是基于V1版本装饰器的，可是，最近V2版本的呼声还比较高，在github上有好几个留言，本来打算月底有时间再进行适配，索性，直接提上日程。

其实打算直接在V1的版本上直接修改，发现改动量还比较大，不能为了升级V2而改造V1，再造成V1版本用户无法使用，这样下来得不偿失，索性和官方一致，也整一个V2版本出来。

如果你打算使用V2版本，直接依赖V2版本即可，除了依赖和导包不同，其它使用方式是一模一样。

中心仓库地址：https://ohpm.openharmony.cn/#/cn/detail/@abner%2Frefresh_v2

方式一：在Terminal窗口中，执行如下命令安装三方包，DevEco Studio会自动在工程的oh-package.json5中自动添加三方包依赖。

建议：在使用的模块路径下进行执行命令。

ohpm install @abner/refresh_v2

方式二：在工程的oh-package.json5中设置三方包依赖，配置示例如下：

"dependencies": { "@abner/refresh_v2": "^1.0.0"}

依赖由原来的refresh改为了refresh_v2。

V1和V2主要不同

这里的不同并不是指的刷新库不同，而是两个版本的装饰器不同，首先可以想到的是，官方开发人员肯定一开始没有设计好，而V1版本又是先入为主，在V1基础上优化，影响太大，最后就搞了一个V2版本的装饰器，和之前的进行隔离，也便于后续的维护和优化。

之前的文章中，对V2版本的装饰器也介绍了几个，确实可以发现，V2版本在V1版本之上，优化了很多，功能也强大了很多，比如@Monitor装饰器，可以直接监听某一个元素是否发生了变化，这对于针对性监听来说，是无比的便捷。

总体来说，V2版本装饰器，是将观察能力增强到数据本身，状态变量独立于UI，更改数据会触发相应视图的更新，支持对象的深度观测和深度监听，且深度观测机制不影响观测性能，也支持对象中属性级精准更新及数组中元素的最小化更新，同样，易用性高、拓展性强，在组件中明确输入与输出，有利于组件化。

V1和V2迁移对照表

V1装饰器名	V2装饰器名	说明
@Observed	@ObservedV2	表明当前对象为可观察对象。但两者能力并不相同。
@Track	@Trace	V1装饰器@Track为精确观察，不使用则无法做到类属性的精准观察。V2@Trace装饰的属性可以被精确跟踪观察。
@Component	@ComponentV2	@Component为搭配V1状态变量使用的自定义组件装饰器。@ComponentV2为搭配V2状态变量使用的自定义组件装饰器。
@State	无外部初始化：@Local外部初始化一次：@Param@Once	@State和@Local类似都是数据源的概念，在不需要外部传入初始化时，可直接迁移。
@Prop	@Param	@Prop和@Param类似都是自定义组件参数的概念。
@Link	@Param@Event	@Link是框架自己封装实现的双向同步，对于V2开发者可以通过@Param@Event自己实现双向同步。
@ObjectLink	@Param	直接兼容，@ObjectLink需要被@Observed装饰的class的实例初始化，@Param没有此限制。
@Provide	@Provider	兼容。
@Consume	@Consumer	兼容。
@Watch	@Monitor	@Monitor用于监听V2状态变量的变化，搭配@Trace使用，可有深层监听的能力。状态变量在一次事件中多次变化时，仅会以最终的结果判断是否触发@Monitor监听事件。
LocalStorage	全局@ObservedV2@Trace	兼容。
AppStorage	AppStorageV2	兼容。
Environment	调用Ability接口获取系统环境变量	Environment获取环境变量能力和AppStorage耦合。在V2中可直接调用Ability接口获取系统环境变量。
PersistentStorage	PersistenceV2	PersistentStorage持久化能力和AppStorage耦合，PersistenceV2持久化能力可独立使用。

适配

其实最优解就是，V2版本和V1版本完全隔离，也就是，如果使用V2就统一使用V2，毕竟V2的功能更加强大，当然了，这里我也是建议，如果你是新的项目，或者新的功能，完全使用V2。

对于一些老的项目，已经存在了大量了V1装饰器代码，让大家一次性迁移，这个有点不符合实际，不过官方也支持混合使用的。

但是在混合使用的时候，需要注意：

1、自定义组件中不可以混用，否则编译报错，所谓混用，就是你V1自定义组件使用V2装饰器，V2自定义组件使用V1装饰器。

2、如果组件间不存在变量传递时，无论V1版本还是V2版本，均可使用不同版本的自定义组件，包括import第三方Component或者ComponentV2装饰的自定义组件。

3、组件间存在变量传递时，V1的变量传递给V2的自定义组件，有如下限制：

V1中未被装饰器装饰的变量（后称普通变量）：V2只能使用@Param接收。

V1中被装饰器装饰的变量（后称状态变量）：V2存在只能通过@Param装饰器接收，且仅限于boolean、number、enum、string、undefined、null这些简单类型数据。

4、组件间存在变量传递时，V2的变量传递给V1的自定义组件，有如下限制：

V2中未被装饰器装饰的变量（后称普通变量）：若V1使用装饰器装饰接收的数据，只能通过@State、@Prop、@Provide。

V2中被装饰器装饰的变量（后称状态变量）：若V1使用装饰器装饰接收的数据，不支持内置类型数据：Array、Set、Map、Date。