Feat/3.0 upgrade guidelines (#3805)

* refactor(docs): update 3.0 upgrade guidelines * refactor(docs): update iOS 3.0 upgrade guidelines --------- Co-authored-by: maxli <maxli@tencent.com>
Tencent · Apr 1, 2024 · 4ac9966 · 4ac9966
1 parent 74c5d81
commit 4ac9966
Show file tree

Hide file tree

Showing 10 changed files with 1,204 additions and 15 deletions.
diff --git a/docs/development/_sidebar.md b/docs/development/_sidebar.md
@@ -1,14 +1,21 @@
 <!-- docs/_sidebar.md -->
-* [Demo体验](development/demo.md)
-* [前端接入](development/web-integration.md)
-* [环境搭建](development/native-integration.md)
-* [3.0升级指引](development/3.0-upgrade-guidelines.md)
-* [自定义组件](development/native-component.md)
-* [自定义模块](development/native-module.md)
-* [事件](development/native-event.md)
-* [终端能力适配](development/native-adapter.md)
-* [数据类型映射](development/type-mapping.md)
-* [V8 API](development/v8-api.md)
-* [调试](development/debug.md)
-* [技术支持](development/support.md)
-* [隐私政策](development/privacy.md)
+- [Demo体验](development/demo.md)
+- 前端接入
+  - [Hippy React&Vue接入指引](development/react-vue-integration-guidelines.md)
+  - [Hippy React&Vue 3.x升级指引](development/react-vue-3.0-upgrade-guidelines.md)
+  - [Web同构接入指引](development/web-integration-guidelines.md)
+- 终端接入
+  - [Android 3.x SDK集成指引](development/android-3.0-integration-guidelines.md)
+  - [Android 3.x SDK升级指引](development/android-3.0-upgrade-guidelines.md)
+  - [iOS 3.x SDK集成指引](development/ios-3.0-integration-guidelines.md)
+  - [iOS 3.x SDK升级指引](development/ios-3.0-upgrade-guidelines.md)
+  - [Voltron/Flutter集成指引](development/voltron-flutter-integration-guidelines.md)
+- [自定义组件](development/native-component.md)
+- [自定义模块](development/native-module.md)
+- [事件](development/native-event.md)
+- [终端能力适配](development/native-adapter.md)
+- [数据类型映射](development/type-mapping.md)
+- [V8 API](development/v8-api.md)
+- [调试](development/debug.md)
+- [技术支持](development/support.md)
+- [隐私政策](development/privacy.md)
diff --git a/docs/development/android-3.0-integration-guidelines.md b/docs/development/android-3.0-integration-guidelines.md
@@ -0,0 +1,54 @@
+# Hippy Android 3.x SDK集成指引
+
+这篇教程，讲述了如何将 Hippy 3.x SDK 集成到一个现有的 Android 工程。
+
+> 注：以下文档都是假设您已经具备一定的 Android 开发经验。
+
+---
+
+## 前期准备
+
+- 已经安装了 JDK version>=1.7 并配置了环境变量
+- 已经安装 Android Studio 最新版本
+- 运行 Demo 工程前需要完成 NDK，CMAKE，gradle 与相关插件的安装
+
+## Demo 体验
+
+若想快速体验，可以直接基于我们的 [Android Demo](https://github.com/Tencent/Hippy/tree/v3.0-dev/framework/examples/android-demo) 来开发
+
+## 快速接入
+
+1. 创建一个 Android 工程
+
+2. Maven 集成
+
+   - 查询 [Maven Central Hippy 版本](https://search.maven.org/search?q=com.tencent.hippy)，其中 `hippy-release` 为 `release` 版本（不携带 `inspector`），`hippy-debug` 为 `debug` 版本
+
+   - 配置 build.gradle
+
+     下面引用Hippy最新版本号可在上述链接中查询
+
+   ```java
+    // implementation 'com.tencent.hippy:hippy-debug:3.2.0-beta'
+    implementation 'com.tencent.hippy:hippy-release:3.2.0-beta'
+    implementation 'androidx.legacy:legacy-support-v4:1.0.0'
+    implementation 'androidx.recyclerview:recyclerview:1.1.0'
+    implementation 'androidx.viewpager:viewpager:1.0.0'
+   ```
+
+3. 本地集成（可选）
+
+   - [hippy-framework](https://github.com/Tencent/Hippy/tree/v3.0-dev/framework/android) 工程运行 Gradle Task `other => assembleRelease` 或者 `other => assembleDebug` 后会在 `framework/android/build/outputs/aar` 目录下生成 `release` 或者 `debug` 模式的`android-sdk.aar`，将 `android-sdk.aar` 拷贝到你项目的 `libs` 目录下。
+
+     !> 通过 `assembleRelease` task 生成的 AAR 默认不携带 `inspector` 模块，不能在前端通过 Devtools 对代码进行调试，若需要集成 `inspector`，请执行 `assembleDebug` task
+
+   - 配置 build.gradle
+
+   ```java
+    api (name:'android-sdk', ext:'aar')
+    implementation 'androidx.legacy:legacy-support-v4:1.0.0'
+    implementation 'androidx.recyclerview:recyclerview:1.1.0'
+    implementation 'androidx.viewpager:viewpager:1.0.0'
+   ```
+
+4. 在宿主 APP 工程中增加引擎初始化与 `hippyRootView` 挂载逻辑，具体可以参考 [Demo](https://github.com/Tencent/Hippy/tree/v3.0-dev/framework/examples/android-demo) 工程中 `HippyEngineWrapper` 实现
diff --git a/docs/development/android-3.0-upgrade-guidelines.md b/docs/development/android-3.0-upgrade-guidelines.md
@@ -0,0 +1,91 @@
+# Hippy Android 3.x SDK升级指引
+
+> 这篇教程，主要介绍Hippy Android SDK 从2.x升级3.x版本如何进行适配以及2.x和3.x在使用上的一些差异化。
+</br>
+
+---
+
+1. 废弃HippyImageLoader相关实现
+
+   HippyImageLoader在2.0中作为引擎初始化必设项是不合理的，在3.0版本中由于图片数据拉取和解码解耦为不同的子模块，HippyImageLoader已经被移除，图片请求会和其它所有IO相关的资源请求统一走VFS模块进行分发，如果是网络请求最终会由VFS模块会分发到HttpAdapter完成请求的处理。  
+   获取到图片数据后，解码模块新增加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);
+
+   // 解码结束后，宿主通过该接口回调还可以获得二次处理bitmap的机会，比如要对bitmap做高斯模糊。
+   void afterDecode(@Nullable Map<String, Object> initProps, 
+                    @NonNull ImageDataHolder imageHolder, 
+                    @NonNull BitmapFactory.Options options);
+
+   // 引擎退出销毁时调用，释放adapter可能占用的资源
+   void destroyIfNeeded();
+   ```
+
+2. 引擎初始化完成callback线程变更
+
+   2.0中initEngine初始化结果SDK内部会切换到UI线程再callback onInitialized给宿主，但我们发现在很多APP内业务反馈的使用场景下，callback切UI线程执行具有很大的延迟，所以3.0中callback onInitialized直接在子线程回调并继续执行loadModule会有更好的效率，之前2.0在callback中对hippyRootView相关的UI操作需要开发者自己来切UI线程保证。
+
+3. 引擎销毁
+
+    3.0中destroyModule增加了回调接口，destroyEngine需要等destroyModule执行完成回调以后才能调用，否则可能有CRASH的风险，宿主可以参考下面代码示例进行引擎销毁：
+
+    ```java
+    fun destroyEngine(hippyEngine: HippyEngine?, hippyRootView: ViewGroup?) {
+        hippyEngine?.destroyModule(hippyRootView,
+                Callback<Boolean> { result, e -> hippyEngine.destroyEngine() })
+    }
+    ```
+
+4. HippyEngine中的接口不再直接引用HippyRootView
+
+    destroyModule接口参数以及loadModule接口返回值均使用系统ViewGroup类型替代，尽量减少对SDK的耦合。
+
+5. loadModule接口参数ModuleListener接口有所变更
+   - 我们发现之前2.0在onLoadCompleted回调接口中返回的root view参数其实在各多业务场景都不会去用到，所以在3.0中我们简化了这个接口，移除了root view参数的返回
+   - 增加onFirstViewAdded接口回调，返回第一view挂载到Hippy root view的回调时机
+
+6. 引擎初始化参数增加资源请求自定义processor的设置
+
+    ```java
+    public List<Processor> processors;
+    ```
+
+    关于VFS特性以及Processor接口使用的介绍可以详见 [VFS](feature/feature3.0/vfs.md)。
+
+7. 关于UI Component事件发送  
+   Hippy终端事件的发送分为全局事件和UI Component事件2种，全局事件和2.0保持一致，使用HippyEngine中暴露的sendEvent接口发送，而UI Component事件的发送可以使用在3.0新增工具类EventUtils中封装的事件发送接口:
+
+    ```java
+    @MainThread
+    public static void sendComponentEvent(@Nullable View view, 
+                                          @NonNull String eventName,
+                                          @Nullable Object params);
+    ```
+
+8. HippyInstanceContext已经被废弃  
+   2.0中基于系统ContextWrapper封了Hippy自己的HippyInstanceContext，并将其作为所有Hippy view的初始化参数，随着3.0 framework和renderer两个子模块的解耦，我们发现HippyInstanceContext设计过于臃肿，已经不再适用于最新的3.0架构，所以我们在最新的3.0版本中废弃了HippyInstanceContext，改用更加轻量化的NativeRenderContext取代，也就是说3.0中所有Hippy相关的view中保存的context都是NativeRenderContext类型。
+
+9. HippyEngine中新增render node缓存特性接口  
+   2.0中我们支持了dom node缓存特性，但dom node缓存针对复杂页面场景性能还是存在一定的性能瓶颈，所有我们在3.0重新实现了性能更好的render node缓存特性，关于render node缓存特性与接口使用的介绍可以详见 [RenderNode Snapshot](feature/feature3.0/render-node-snapshot.md)。
+
+10. 关于自定义UI组件的Controller中dispatchFunction参数说明
+    在2.0中dispatchFunction接收事件属性的参数类型为HippyArray类型，由于在2.0的后续版本中HippyMap和HippyArray就已经被标记为@Deprecated，所以在3.0的重构中，SDK内部也逐渐替换一些使用HippyMap或HippyArray类型参数的接口，所以针对Controller的dispatchFunction接口SDK内部默认替换成List类型参数
+
+    ```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.0升级的成本原来使用HippyArray类型的接口还是保留，只是标记为@Deprecated，所以升级3.0对于原来定义的dispatchFunction接口不需要做任何修改，但建议后续升级到3.0版本的同学，定义新UI组件的时候，直接Override使用List参数类型的新接口。
diff --git a/docs/development/ios-3.0-integration-guidelines.md b/docs/development/ios-3.0-integration-guidelines.md
@@ -0,0 +1,213 @@
+# Hippy iOS 3.x SDK集成指引
+
+这篇教程，讲述了如何将 Hippy 3.x SDK 集成到一个现有的 iOS 工程。
+
+> 注：以下文档都是假设您已经具备一定的 iOS 开发经验。
+
+---
+
+## 一、环境准备
+
+- 安装 Xcode
+
+- 安装 [CMake](https://cmake.org/)
+
+  推荐使用Homebrew安装CMake，安装命令如下：
+
+  ```shell
+  brew install cmake
+  ```
+
+- 安装 [CocoaPods](https://cocoapods.org/)
+
+  [CocoaPods](https://cocoapods.org/) 是一个iOS和macOS开发中流行的包管理工具。我们将使用它把Hippy的iOS Framework添加到现有iOS项目中。
+
+  推荐使用Homebrew安装CocoaPods，安装命令如下：
+
+  ```shell
+  brew install cocoapods
+  ```
+
+ > 若想快速体验，可以直接基于Hippy仓库中的 [iOS Demo](https://github.com/Tencent/Hippy/tree/main/framework/examples/ios-demo) 来开发
+
+## 二、使用 Cocoapods 集成 iOS SDK
+
+具体的操作步骤如下：
+
+1. 首先，确定要集成的Hippy iOS SDK版本，如3.2.0，将其记录下来，接下来将在Podfile中用到。
+   > 可到「[版本查询地址](https://github.com/Tencent/Hippy/releases)」查询最新的版本信息
+
+2. 其次，准备好现有iOS工程的 Podfile 文件
+
+    Podfile 文件是CocoaPods包管理工具的配置文件，如果当前工程还没有该文件，最简单的创建方式是通过CocoaPods init命令，在iOS工程文件目录下执行如下命令：
+
+    ```shell
+    pod init
+    ```
+
+    生成的Podfile将包含一些demo设置，您可以根据集成的目的对其进行调整。
+
+    为了将Hippy SDK集成到工程，我们需要修改Podfile，将 hippy 添加到其中，并指定集成的版本。修改后的Podfile应该看起来像这样:
+
+    ```text
+    #use_frameworks!
+    platform :ios, '11.0'
+
+    # TargetName大概率是您的项目名称
+    target TargetName do
+
+        # 在此指定步骤1中记录的hippy版本号，可访问 https://github.com/Tencent/Hippy/releases 查询更多版本信息
+        pod 'hippy', '3.2.0'
+
+    end
+    ```
+
+    !> 请注意，由于hippy3.x中大量使用了 #include"path/to/file.h" 的方式引用C++头文件，因此如果开启了 CocoaPods 的 framework 格式集成选项（即Podfile中 `use_frameworks!` 配置为开启状态），则必须在 Podfile 文件中加入如下配置：
+
+    ```text
+    # 工程开启 use_frameworks! 后需添加此环境变量，用于hippy使用正确设置项
+    ENV["use_frameworks"] = "true"
+    ```
+
+    > 默认配置下，Hippy SDK使用布局引擎是[Taitank](https://github.com/Tencent/Taitank)，JS引擎是系统的`JavaScriptCore`，如需切换使用其他引擎，请参照下文[《引擎切换（可选）》](#四引擎切换可选)一节调整配置。
+
+3. 最后，在命令行中执行
+
+    ```shell
+    pod install
+    ```
+
+    命令成功执行后，使用 CocoaPods 生成的 `.xcworkspace` 后缀名的工程文件来打开工程。
+
+## 三、编写SDK接入代码，加载本地或远程的Hippy资源包
+
+Hippy SDK的代码接入简单来说只需两步：
+
+1、初始化一个HippyBridge实例，HippyBridge是Hippy最重要的概念，它是终端渲染侧与前端驱动侧进行通信的`桥梁`，同时也承载了Hippy应用的主要上下文信息。
+
+2、通过HippyBridge实例初始化一个HippyRootView实例，HippyRootView是Hippy应用另一个重要概念，Hippy应用将由它显示出来，因此可以说创建业务也就是创建一个 `HippyRootView`。
+
+目前，Hippy 提供了分包加载接口以及不分包加载接口,使用方式分别如下：
+
+### 方式1. 使用分包加载接口
+
+``` objectivec
+/** 此方法适用于以下场景：
+ * 在业务还未启动时先准备好JS环境，并加载包1，当业务启动时加载包2，减少包加载时间
+ * 我们建议包1作为基础包，与业务无关，只包含一些通用基础组件，所有业务通用
+ * 包2作为业务代码加载
+*/
+
+// 先加载包1，创建出一个HippyBridge实例
+// 假设commonBundlePath为包1的路径
+// Tips：详细参数说明请查阅头文件: HippyBridge.h
+NSURL *commonBundlePath = getCommonBundlePath();
+HippyBridge *bridge = [[HippyBridge alloc] initWithDelegate:self
+                                                  bundleURL:commonBundlePath
+                                             moduleProvider:nil
+                                              launchOptions:your_launchOptions
+                                                executorKey:nil];
+
+// 再通过上述bridge以及包2地址创建HippyRootView实例
+// 假设businessBundlePath为包2的路径
+// Tips：详细参数说明请查阅头文件: HippyRootView.h
+HippyRootView *rootView = [[HippyRootView alloc] initWithBridge:bridge
+                                                    businessURL:businessBundlePath
+                                                     moduleName:@"Your_Hippy_App_Name"
+                                              initialProperties:@{}
+                                                   shareOptions:nil
+                                                       delegate:nil];
+
+// 最后，给生成的rootView设置好frame，并将其挂载到指定的VC上。
+rootView.frame = self.view.bounds;
+rootView.autoresizingMask = UIViewAutoresizingFlexibleHeight | UIViewAutoresizingFlexibleWidth;
+[self.view addSubview:rootView];
+
+// 至此，您已经完成一个Hippy应用的初始化，SDK内部将自动加载资源并开始运行Hippy应用。
+```
+
+### 方式2. 使用不分包加载接口
+
+``` objectivec
+// 与上述使用分包加载接口类似，首先需要创建一个HippyBridge实例，
+// 区别是在创建HippyRootView实例时，无需再传入业务包，即businessBundlePath，直接使用如下接口创建即可
+// Tips：详细参数说明请查阅头文件: HippyRootView.h
+- (instancetype)initWithBridge:(HippyBridge *)bridge
+                    moduleName:(NSString *)moduleName
+             initialProperties:(nullable NSDictionary *)initialProperties
+                  shareOptions:(nullable NSDictionary *)shareOptions
+                      delegate:(nullable id<HippyRootViewDelegate>)delegate;
+```
+
+> 在Hippy仓库中提供了一个简易示例项目，包含上述全部接入代码，以及更多注意事项。
+>
+> 建议参考该示例完成SDK到已有项目的集成：[iOS Demo](https://github.com/Tencent/Hippy/tree/main/framework/examples/ios-demo)，更多设置项及使用方式请查阅上述头文件中的具体API说明。
+
+!> 使用分包加载可以结合一系列策略，比如提前预加载bridge, 全局单bridge等来优化页面打开速度。
+
+到这里，您已经完成了接入一个默认配置下的Hippy iOS SDK的全部过程。
+
+## 四、引擎切换（可选）
+
+Hippy 3.x的一个重要特性是支持了多引擎的便捷切换，目前，可切换的引擎有两个，一是布局引擎，二是JS引擎。默认配置下，Hippy使用布局引擎是[Taitank](https://github.com/Tencent/Taitank)，JS引擎是iOS系统内置的`JavaScriptCore`。
+
+如需使用其他布局引擎，如[Yoga](https://github.com/facebook/yoga)，或使用其他JS引擎，如V8，可参考如下指引调整Hippy接入配置。
+
+> Hippy3.x提供了iOS环境下默认的v8引擎实现，如需使用其他JS引擎需用户自行实现相关napi接口。
+
+### 4.1 切换JS引擎
+
+如需使用V8引擎，在Podfile文件中添加如下环境变量即可：
+
+```ruby
+ENV['js_engine'] = 'v8'
+```
+
+修改后的Podfile应该看起来像这样:
+
+```text
+#use_frameworks!
+platform :ios, '11.0'
+ENV['js_engine'] = 'v8' #切换为V8引擎
+
+# TargetName大概率是您的项目名称
+target TargetName do
+
+    pod 'hippy', 'your_specified_version'
+
+end
+```
+
+之后，重新执行`pod install`命令更新项目依赖即可。
+
+如需使用其他第三方JS引擎，需要做如下操作：
+
+#### 1.修改Podfile配置为第三方JS引擎
+
+将Podfile中的js_engine环境变量配置为other，这样在拉取代码时，jsc或者v8的代码将不会被添加到工程中。
+
+```ruby
+ENV['js_engine'] = 'other'
+```
+
+> Hippy3.0中使用napi抽象了不同JS引擎的接口。其中，JSC与V8的接口进行了实现。用户若使用JSC或者V8，可直接切换，Hippy默认进行了实现。
+
+#### 2.自行实现napi抽象接口
+
+napi将js引擎接口抽象化，由js driver层调用。接入方自行实现napi接口，即可实现对第三方JS引擎的支持。
+
+napi文件位于 `/driver/js/napi*` 目录下。
+
+#### 3.将实现文件添加到工程中
+
+接入方自行将对应的napi实现文件添加到工程中。
+
+## 4.2 切换布局引擎
+
+用户若想使用Yoga布局引擎，直接在Podfile文件中指定layout_engine为Yoga即可：
+
+```ruby
+ENV['layout_engine'] = 'Yoga'
+```
+
+之后，重新执行`pod install`命令更新项目依赖即可。