Skip to content

Commit

Permalink
refactor(docs): update 3.0 upgrade guidelines md (Tencent#3908)
Browse files Browse the repository at this point in the history 
Co-authored-by: siguangli <[email protected]>
  • Loading branch information
@siguangli @siguangli2018
siguangli and siguangli2018 committed Jul 12, 2024
1 parent 3fc7178 commit 48893c2
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 106 deletions.
164 changes: 58 additions & 106 deletions docs/development/android-3.0-upgrade-guidelines.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,42 +5,21 @@
---

# Maven依赖项变更
# 升级依赖项变更

3.0 SDK集成依赖项相对2.0有所变更，开发者可以参照[Hippy Android 3.x SDK集成指引](development/android-3.0-integration-guidelines.md)更新自己工程中的依赖项。
</br>
</br>

# 升级基础适配项（required）
# 接入与使用方式变更

1. 废弃引擎初始化参数HippyImageLoader
**3.0针对终端引擎接入，部分类及接口调用方式上做了以下调整：**

HippyImageLoader在2.0中作为引擎初始化必设项是不合理的，在3.0中已经废弃，开发者需要在引擎初始化中移除HippyImageLoader相关的设置参数与实现。</br>
3.0图片资源拉取会和其它所有IO相关的资源一样统一走VFS模块进行分发，远程网络资源请求最终会由VFS模块会分发到HttpAdapter进行处理，如果开发者需要将图片请求和其他资源请求进行区分处理，可以参照下面代码示例在自定义的HttpAdapter中Override fetch接口，通过请求参数来判断是否为图片资源的请求：

```java
@Override
public void fetch(@NonNull final ResourceDataHolder holder,
@Nullable HashMap<String, Object> nativeParams,
@NonNull final VfsManager.ProcessorCallback callback) {
HashMap<String, String> rp = holder.requestParams;
if (rp != null && rp.containsKey(REQUEST_CONTENT_TYPE)
&& rp.get(REQUEST_CONTENT_TYPE).equals(REQUEST_CONTENT_TYPE_IMAGE)) {
// 这里处理图片资源请求
} else {
// 这里处理其它资源的请求
}
}
```

2. 引擎初始化完成callback回调线程调整

2.0中initEngine初始化结果SDK内部会切换到UI线程再callback onInitialized给宿主，但我们发现在一些业务使用场景下，callback切UI线程执行可能具有很大的延迟，所以3.0中callback onInitialized直接在子线程回调并继续执行loadModule会有更好的效率。</br>
在原2.0引擎初始化callback中如果有对hippyRootView挂载等相关的UI操作，需要开发者自己增加UI线程的切换逻辑来保证。
1. 引擎初始化完成callback回调线程调整 <br>
为了提升引擎初始化效率，3.0中引擎初始化完成callback onInitialized直接在子线程回调并继续执行loadModule。2.0在onInitialized中如果有对hippyRootView挂载等相关的UI操作，需要开发者自己增加UI线程的切换逻辑来保证。

3. 引擎销毁调用方式与顺序调整

3.0中destroyModule增加了回调接口，destroyEngine需要等destroyModule执行完成回调以后才能调用，否则可能有CRASH的风险，开发者需要将2.0原有的引擎销毁逻辑按下面的代码示例进行变更：
2. 引擎销毁调用方式与顺序调整 <br>
3.0中destroyModule增加了回调接口，destroyEngine需要等destroyModule执行完成回调以后才能调用，否则可能有CRASH的风险，新的释放流程流程参照以下代码示例：

```java
fun destroyEngine(hippyEngine: HippyEngine?, hippyRootView: ViewGroup?) {
Expand All @@ -49,17 +28,15 @@
}
```

4. HippyEngine中的接口不再直接引用HippyRootView

destroyModule接口参数以及loadModule接口返回值均使用系统ViewGroup类型替代，尽量减少对SDK的耦合，开发者需要对loadModule接口返回值类型做相应的调整。
3. 废弃引擎初始化参数HippyImageLoader <br>
HippyImageLoader在2.0中作为引擎初始化必设项是不合理的，在3.0中已经废弃，开发者需要在引擎初始化中移除HippyImageLoader相关的设置参数与实现。</br>
3.0图片资源拉取会和其它所有IO相关的资源一样统一走VFS模块进行分发，远程网络资源请求最终会由VFS模块会分发到HttpAdapter进行处理。

5. ModuleListener接口定义变更
开发者需要对loadModule接口参数ModuleListener做以下2点适配
- 我们发现之前2.0在onLoadCompleted回调接口中返回的root view参数其实在各多业务场景都不会去用到，所以在3.0中我们简化了这个接口，移除了root view参数的返回
- 增加onFirstViewAdded接口回调，返回第一view挂载到Hippy root view的回调时机
4. 废弃HippyInstanceContext定义及其相关实现 <br>
随着3.0 framework和renderer两个子模块的解耦，我们发现HippyInstanceContext设计过于臃肿，已经不再适用于最新的3.0架构，所以我们在最新的3.0版本中废弃了HippyInstanceContext，改用更加轻量化的NativeRenderContext取代。

6. UI Component事件发送
Hippy终端事件的发送分为全局事件和UI Component事件2种，全局事件和2.0保持一致，使用HippyEngine中暴露的sendEvent接口发送，而UI Component事件的发送，开发者需要统一使用使用3.0新增工具类EventUtils中封装的事件发送接口:
5. UI Component事件发送 <br>
3.0 UI Component事件的发送，开发者需要统一使用使用3.0新增工具类EventUtils中封装的事件发送接口:

```java
@MainThread
Expand All @@ -68,40 +45,52 @@
@Nullable Object params);
```

7. 废弃HippyInstanceContext定义及其相关实现
2.0中基于系统ContextWrapper封了Hippy自己的HippyInstanceContext，并将其作为所有Hippy view的初始化参数，随着3.0 framework和renderer两个子模块的解耦，我们发现HippyInstanceContext设计过于臃肿，已经不再适用于最新的3.0架构，所以我们在最新的3.0版本中废弃了HippyInstanceContext，改用更加轻量化的NativeRenderContext取代，所以开发者需要将自定义组件中使用到HippyInstanceContext的相关实现变更为NativeRenderContext。
</br>

# 组件变更

**3.0针对部分组件做了相应的重构，如果开发者基于老组件扩展了自定义组件，需要做以下适配：**

8. 废弃support ui下面RecyclerView及其派生类HippyListView相关实现，随着瀑布流组件重构完成，HippyWaterfallView已经与HippyRecyclerView共同派生于系统androidX的RecyclerView，老版本的support ui组件已经可以彻底废弃，因此以下2个目录下所有实现文件已经从sdk中移除
- com/tencent/mtt/supportui/views/recyclerview/
- com/tencent/mtt/hippy/views/list/ </br>
1. 废弃support ui下面RecyclerView及其派生类HippyListView组件 <br>
3.0的HippyWaterfallView重构后已经不再依赖support ui相关组件，以下2个目录下所有实现文件已经从sdk中移除 </br>
com/tencent/mtt/supportui/views/recyclerview/ </br>
com/tencent/mtt/hippy/views/list/ </br>
之前开发者如果基于HippyListView派生了自己定义的list view组件，需要修改并适配为继承于HippyRecyclerView

9. HippyRootView下面getLaunchParams方法已被废弃，可以使用HippyEngineContext下面getJsParams接口来替代。

10. 简化HippyHttpRequest类实现，移除了以下接口定义:
</br>

# 接口定义变更

**3.0对部分接口定义及参数了做了调整，如果开发者有使用到以下接口需要做相应适配：**

1. ModuleListener接口定义变更 <br>
- onLoadCompleted回调接口移除了root view参数的返回
- 增加onFirstViewAdded接口回调，返回第一view挂载到Hippy root view的回调时机

2. HippyEngineContext类中部分接口调整 <br>
- 新增findViewById(int nodeId)，可以通过node id查找对应的view
- 移除getDomManager()与getRenderManager()两个接口
- getEngineId()接口转移至HippyEngine类下
- 废弃getInstance(int id)接口，由新增getRootView()接口替代

3. 废弃HippyRootView中getLaunchParams接口 <br>
使用HippyEngineContext下面getJsParams接口来替代。

4. HippyEngine类中接口参数调整 <br>
为尽量减少接入方对SDK的耦合，destroyModule接口参数以及loadModule接口返回值由原来HippyRootView类型改为系统ViewGroup类型替代。

5. HippyHttpRequest类中接口定义变更 <br>
由于mInitParams参数在HippyHttpRequest创建的时候就作为初始化参数传入，后续一些依赖mInitParams获取参数的逻辑封装在HippyHttpRequest内部更合理，所以我们移除了以下set接口，只保留get接口：
- public void setMethod(String method)
- public void setInstanceFollowRedirects(boolean instanceFollowRedirects)
- public void setBody(String body)
- public void setNativeParams(Map<String, Object> nativeParams)
- public void setInitParams(HippyMap initParams)
- public void setInstanceFollowRedirects(boolean instanceFollowRedirects)
</br>
由于mInitParams参数在HippyHttpRequest创建的时候就作为初始化参数传入，后续一些依赖mInitParams获取参数的逻辑封装在HippyHttpRequest内部更合理，所以我们移除了相关的set接口，只保留get接口.
</br>
该项调整对于之前2.x中开发者定义了继承于DefaultHttpAdapter的自定义HippyHttpAdapter，并且使用到HippyHttpRequest相关接口的需要做一定适配，适配过程中也可以参考我们github工程main分支DefaultHttpAdapter与HippyHttpRequest具体实现。

11. HippyEngineContext下部分接口调整:
- 新增findViewById(int nodeId)，可以通过node id查找对应的view
- 移除getDomManager()与getRenderManager()两个接口，之前通过RenderManager查找view的方法通过上述新增接口替代
- getEngineId()接口转移至HippyEngine类下
- 废弃getInstance(int id)接口，由新增getRootView()和getRootView(int rootId)两个接口替代，目前多root view支持还未完善，所以两个getRootView接口调用效果一致
</br>
如果开发者在之前的2.x版本上使用到以上接口，可以根据自己的需要做相应适配调整

12. HippyViewController下面移除getInnerPath(HippyInstanceContext context, String path)接口实现，之前开发者自定义组件Controller中有Override该接口需要重新适配，3.0 image uri local path的转换在ImageComponent中通过convertToLocalPathIfNeeded(String uri)接口实现，目前暂时还不支持开发者自定义。

13. HippyViewController中onManageChildComplete接口已经被废弃，统一使用onBatchComplete接口替代，之前2.x列表滚动过程中，view复用后默认都会调用onManageChildComplete，但3.x中为了减少一些无效的调用逻辑进一步提升列表滚动流畅性，列表滚动view复用的时候默认不会调用onBatchComplete，如果想接收onBatchComplete调用做一些定制逻辑需要做以下适配：
- 定义自定义组件对应的RenderNode(类名自定义)，并Override shouldNotifyNonBatchingChange接口
6. 废弃HippyViewController中onManageChildComplete接口 <br>
统一使用onBatchComplete接口替代，之前2.x列表滚动过程中，view复用后默认都会调用onManageChildComplete，但3.x中为了减少一些无效的调用逻辑进一步提升列表滚动流畅性，列表滚动view复用的时候默认不会调用onBatchComplete，如果想接续接收onBatchComplete调用需要做以下适配： <br>
（1） 定义自定义组件对应的RenderNode(类名自定义)，并Override shouldNotifyNonBatchingChange接口

```java
public class CustomRenderNode extends RenderNode {
Expand All @@ -121,7 +110,7 @@
}
```

- 在自定义组件Controller中Override createRenderNode接口并增加自定义RenderNode的创建逻辑
（2） 在自定义组件Controller中Override createRenderNode接口并增加自定义RenderNode的创建逻辑

```java
@Override
Expand All @@ -134,54 +123,17 @@
}
```

# 新增特性适配项（optional）

1. 引擎初始化参数增加资源请求自定义processor的设置

```java
public List<Processor> processors;
```

关于VFS特性以及Processor接口使用的介绍可以详见 [VFS](feature/feature3.0/vfs.md)。

2. 引擎初始化参数增加ImageDecoderAdapter的设置
如果开发者有自定义格式图片的解码需求，可以在引擎初始化参数中设置ImageDecoderAdapter，ImageDecoderAdapter的具体接口描述如下：

```java
// 解码image原始数据，解码的结果可以通过 image data holder提供的setBitmap或者setDrawable接口
// 置到holder中，如果宿主decode adapter不处理，返回false由SDK走默认解码逻辑
boolean preDecode(@NonNull byte[] data,
@Nullable Map<String, Object> initProps,
@NonNull ImageDataHolder imageHolder,
@NonNull BitmapFactory.Options options);
</br>

// 解码结束后，宿主通过该接口回调还可以获得二次处理bitmap的机会，比如要对bitmap做高斯模糊。
void afterDecode(@Nullable Map<String, Object> initProps,
@NonNull ImageDataHolder imageHolder,
@NonNull BitmapFactory.Options options);
# 新增特性

// 引擎退出销毁时调用，释放adapter可能占用的资源
void destroyIfNeeded();
```
**3.0中新增以下新特性的支持，开发者可以根据自己的需求进行选择性适配：**

3. HippyEngine中新增render node缓存特性接口
2.0中我们支持了dom node缓存特性，但dom node缓存针对复杂页面场景性能还是存在一定的性能瓶颈，所有我们在3.0重新实现了性能更好的render node缓存特性，关于render node缓存特性与接口使用的介绍可以详见 [RenderNode Snapshot](feature/feature3.0/render-node-snapshot.md)。
1. 新增统一资源请求处理模块-VFS，具体使用方式可以详见 [VFS](feature/feature3.0/vfs.md) 特性文档介绍。

4. 关于自定义UI组件的Controller中dispatchFunction参数说明
在2.0中dispatchFunction接收事件属性的参数类型为HippyArray类型，由于在2.0的后续版本中HippyMap和HippyArray就已经被标记为@Deprecated，所以在3.0的重构中，SDK内部也逐渐替换一些使用HippyMap或HippyArray类型参数的接口，所以针对Controller的dispatchFunction接口SDK内部默认替换成List类型参数
2. 新增ImageDecoderAdapter支持接入自定义图片解码器，具体使用方式可以详见 [ImageDecoderAdapter](feature/feature3.0/image-decoder-adapter.md) 特性文档介绍。

```java
public void dispatchFunction(@NonNull T view,
@NonNull String functionName,
@NonNull List params);

public void dispatchFunction(@NonNull T view,
@NonNull String functionName,
@NonNull List params,
@NonNull Promise promise)；
```
3. 新增Render Node缓存特性优化启动速度，具体使用方式可以详见 [RenderNode Snapshot](feature/feature3.0/render-node-snapshot.md) 特性文档介绍。

为了减低3.0升级的成本原来使用HippyArray类型的接口还是保留，只是标记为@Deprecated，所以升级3.0对于原来定义的dispatchFunction接口不需要做任何修改，但建议后续升级到3.0版本定义新UI组件的时候，直接Override使用List参数类型的新接口。
4. 新增Screenshot截屏特性，具体使用方式可以详见 [Screenshot for specific views](feature/feature3.0/screenshot.md) 特性文档介绍。

5. HippyEngine中新增Screenshot截屏特性接口
过去在一些业务的使用场景中需要针对指定的Hippy view进行截图并做分享，之前截图逻辑都是由开发者自己实现，为了进一步降低开发者的适配成本，我们把截图能力下沉到了SDK，为开发者提供更为便捷的使用方式，关于Screenshot截屏特性与接口使用的介绍可以详见 [Screenshot for specific views](feature/feature3.0/screenshot.md)。
35 changes: 35 additions & 0 deletions docs/feature/feature3.0/image-decoder-adapter.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# ImageDecoderAdapter

---

## 背景

3.0我们在HippyEngine引擎初始化参数中增加了ImageDecoderAdapter的设置，如果有开发者业务中有使用到特殊格式的图片，如SharpP、avif等，可以通过设置ImageDecoderAdapter来对接你的自定义图片解码器，具体接口描述如下：

## 3.0 图片解码Adapter接口定义

### ImageDecoderAdapter Public methods

```java
boolean preDecode(@NonNull byte[] data,
@Nullable Map<String, Object> initProps,
@NonNull ImageDataHolder imageHolder,
@NonNull BitmapFactory.Options options);
```

该接口在拉取到图片原始数据的时候会调用，解码的结果可以通过image data holder提供的setBitmap或者setDrawable接口设置到holder中，并且返回true，表示不需要sdk再做解码操作，如果返回false表示需要sdk做默认的解码操作。

```java
void afterDecode(@Nullable Map<String, Object> initProps,
@NonNull ImageDataHolder imageHolder,
@NonNull BitmapFactory.Options options);
```


该接口在解码结束后会调用，为开发者提供二次处理bitmap的机会， 比如要对bitmap做高斯模糊。

```java
void destroyIfNeeded();
```

引擎退出销毁时调用，释放adapter可能占用的资源

0 comments on commit 48893c2

Please sign in to comment.