Merge remote-tracking branch 'upstream/main' into 3.0_doc

PUBLISH.md

@@ -44,6 +44,12 @@ Android
 
 * [gradle.properties](https://github.com/Tencent/Hippy/blob/master/android/sdk/gradle.properties#L25)
 
+修改安卓的abi配置，支持armeabi-v7a和arm64-v8a
+```
+INCLUDE_ABI_ARMEABI_V7A=true
+INCLUDE_ABI_ARM64_V8A=true
+```
+
 ## 4. Update built-in packages and verify functionality
 
 The new front-end SDK is then compiled with
@@ -93,8 +99,8 @@ git tag -a [VERSION] -m "version release xxx"
 Commit the code and prepare to publish the PR merge into the master branch.
 
 ```bash
-git push        # 提交代码
-git push --tags # 提交 tag
+git push origin branch       # 提交代码
+git push origin tag          # 提交 tag
 ```
 
 ## 6. Publish

docs/api/hippy-react/components.md

@@ -516,15 +516,13 @@ import icon from './qb_icon_new.png';
 | interItemSpacing  | item 间的垂直间距  | `number`   | `Android、iOS、Voltron`  |
 | contentInset      | 内容缩进 ，默认值 `{ top:0, left:0, bottom:0, right:0 }`  | `Object`   | `Android、iOS、Voltron`   |
 | renderItem             | 这里的入参是当前 item 的 index，在这里可以凭借 index 获取到瀑布流一个具体单元格的数据，从而决定如何渲染这个单元格。 | `(index: number) => React.ReactElement`                                   | `Android、iOS、Voltron`    |
-| renderBanner | 如何渲染 Banner。 | `() => React.ReactElement` |  `iOS、Voltron`
+| renderBanner | 如何渲染 Banner。 | `() => React.ReactElement` |  `Android、iOS、Voltron`
 | getItemStyle           | 设置`WaterfallItem`容器的样式。  | `(index: number) => styleObject`                                    | `Android、iOS、Voltron`    |
 | getItemType            | 指定一个函数，在其中返回对应条目的类型（返回Number类型的自然数，默认是0），List 将对同类型条目进行复用，所以合理的类型拆分，可以很好地提升list 性能。 | `(index: number) => number`                                    | `Android、iOS、Voltron`    |
 | getItemKey             | 指定一个函数，在其中返回对应条目的 Key 值，详见 [React 官文](//reactjs.org/docs/lists-and-keys.html) | `(index: number) => any`                                    | `Android、iOS、Voltron`    |
 | preloadItemNumber     | 滑动到瀑布流底部前提前预加载的 item 数量 | `number` | `Android、iOS、Voltron` |
 | onEndReached          | 当所有的数据都已经渲染过，并且列表被滚动到最后一条时，将触发 `onEndReached` 回调。 | `Function`                                                  | `Android、iOS、Voltron`    |
-| containPullHeader | 是否包含`PullHeader`组件，默认 `false` ；`Android` 暂不支持，可暂时用 `RefreshWrapper` 组件替代  | `boolean`  | `iOS、Voltron`    |
-| renderPullHeader | 如何渲染 `PullHeader`，此时 `containPullHeader` 默认设置成 `true` |  `() => React.ReactElement` | `iOS、Voltron`    |
-| containPullFooter | 是否包含`PullFooter`组件，默认 `false`  | `boolean`  | `Android、iOS、Voltron`    |
+| renderPullHeader | 如何渲染 `PullHeader`，此时 `containPullHeader` 默认设置成 `true` |  `() => React.ReactElement` | `Android、iOS、Voltron`    |
 | renderPullFooter | 如何渲染 `PullFooter`，此时 `containPullFooter` 默认设置成 `true` |  `() => React.ReactElement` | `Android、iOS、Voltron` |
 | onScroll              | 当触发 `WaterFall` 的滑动事件时回调。`startEdgePos`表示距离 List 顶部边缘滚动偏移量；`endEdgePos`表示距离 List 底部边缘滚动偏移量；`firstVisibleRowIndex`表示当前可见区域内第一个元素的索引；`lastVisibleRowIndex`表示当前可见区域内最后一个元素的索引；`visibleRowFrames`表示当前可见区域内所有 item 的信息(x，y，width，height)    | `nativeEvent: { startEdgePos: number, endEdgePos: number, firstVisibleRowIndex: number, lastVisibleRowIndex: number, visibleRowFrames: Object[] }` | `Android、iOS、Voltron`
 

docs/development/ios-3.0-upgrade-guidelines.md

@@ -1,22 +1,50 @@
 # Hippy iOS 3.x SDK升级指引
 
-> 这篇教程，主要介绍Hippy iOS SDK 从2.x升级3.x版本如何进行适配以及2.x和3.x在使用上的一些差异化。
+> 这篇教程，主要介绍Hippy iOS SDK 从2.x升级3.x版本如何进行适配以及2.x和3.x在使用上的一些差异。
 </br>
 
 ---
 
+## 兼容性说明
+
 从设计上，`Hippy3.0`尽可能保持了与`Hippy2.0`的兼容性。大部分`Hippy2.0`的自定义组件和自定义模块均可无需任何修改，兼容`Hippy3.0`。
 
-同时在SDK接入API方面，`Hippy3.0`也尽可能保持了一致。因此，如果您未曾在业务中深度扩展`Hippy内置组件`或模块，升级SDK的过程将非常简单，一般情况下仅会遇到少许编译问题，甚至无需修改任何代码。
+同时在SDK的接入API方面，`Hippy3.0`也与`2.17`保持了一致。因此，如果您未曾在业务中深度扩展`Hippy内置组件`或模块，升级SDK的过程将非常简单，一般情况下仅会遇到少许编译问题，甚至无需修改任何代码。
 
 然而由于3.0的架构改进和一致性优化等原因，部分内在实现会不可避免的发生变化。如果您在业务中存在较多深度定制的自定义组件，如对ListView组件、Image组件进行了深度扩展，那将可能会遇到一些编译问题，本文将做详细说明。
 
-改动较大的组件/模块的说明如下：
+## 升级操作步骤
+
+1. 安装必要工具
+
+   由于3.0的hippy podspec中使用到了CMake构建工具，因此除了必要的`Xcode`和`Cocoapods`外，您还需安装`CMake`。 详细安装方法可参考：[Hippy iOS 3.x SDK集成指引](development/ios-3.0-integration-guidelines.md)。
+
+2. 升级依赖的Hippy iOS SDK版本
+
+   如果您使用的是Cocoapods集成，那么仅需将Podfile中指定的Hippy版本升级至3.x即可（可访问 [版本发布地址](https://github.com/Tencent/Hippy/releases) 查询更多版本信息）。
+
+3. 编译 & 运行。
+
+    确保已经完成前端包的更新后，重新编译运行即可完成SDK的升级。请注意，Hippy3.0的前端包与2.0并不兼容，在Hippy3.x SDK中运行2.0的包将出现错误提示。
+
+    如在编译阶段遇到问题，请参考如下说明进行适当的修改。
+
+## 改动较大的组件及模块说明
+
+1. 删除了`HippyVirtualNode`、`HippyVirtualList`、`HippyVirtualCell`等相关类和API：
+
+   `HippyVirtualNode`在2.0中作为列表等组件的虚拟对象和数据源，其作用与`HippyShadowView`存在重复，因此`Hippy3.0`删除了这一冗余虚拟对象。
+   如果您在扩展组件中使用到了这些类，请将其替换为对应的 `ShadowView`。
+
+2. 基于UICollectionView实现的ListView组件：
+
+   为支持横滑(`horizontal: true`)相关特性，ListView的渲染实现从2.0中的`UITableView`切换为了3.0中的`UICollectionView`。相应的，列表中Cell的基类也由`UITableViewCell`变更为了`UICollectionViewCell`。
+   如果您有强依赖ListView实现细节的组件扩展逻辑，那么将需做一些适当的修改。
 
-1. 删除了`HippyVirtualNode`、`HippyVirtualList`、`HippyVirtualCell`等相关类和API：`HippyVirtualNode`在2.0中作为列表等组件的虚拟对象和数据源，其作用与`HippyShadowView`存在重复，因此`Hippy3.0`删除了这一冗余虚拟对象。
+3. Image组件source属性调用约定变更：
 
-2. ListView组件：为支持横滑(`horizontal: true`)相关特性，ListView的渲染实现从`UITableView`切换为了`UICollectionView`。相应的，列表中Cell的基类也由`UITableViewCell`变更为了`UICollectionViewCell`。
+   由于3.0中关于image source的调用约定发生了变化（从 `NSArray` 类型的 `source` 调整为了 `NSString` 类型的 `src`），因此，如自定义了Image组件，请注意在对应的ViewManager中补充实现 `src` 属性，否则图片可能无法正常显示。
 
-3. Image组件source属性：由于3.0中关于image source的调用约定发生了变化（从 `NSArray` 类型的 `source` 调整为了 `NSString` 类型的 `src`），因此，如自定义了Image组件，请注意在对应的ViewManager中补充实现 `src` 属性，否则图片可能无法正常显示。
+4. 删除Image组件的内置图片缓存：
 
-4. Image组件内置图片缓存：删除了2.0中内置的背景图片缓存管理类，即`HippyBackgroundImageCacheManager`，图片缓存逻辑交由业务方自行定制。
+   3.0中删除了2.0内置的背景图片缓存管理类，即`HippyBackgroundImageCacheManager`，图片缓存逻辑交由业务方自行定制。如果您有缓存图片的需求，请通过自定义ImageLoader来实现。

docs/development/react-vue-3.0-upgrade-guidelines.md

@@ -6,7 +6,7 @@
 
 # 依赖升级
 
-### hippy-react
+## hippy-react
 
 >如果业务目前使用 React 来开发 Hippy，可以参考当前章节升级指引。
 </br>
@@ -31,7 +31,7 @@
 
 Hippy-React 在升级3.0可以完全兼容之前的版本，除了升级如上依赖，业务代码不需要做修改。
 
-### hippy-vue
+## hippy-vue
 
 >如果业务目前使用 Vue 2.x 来开发 Hippy，可以参考当前章节升级指引。
 </br>
@@ -51,7 +51,7 @@ Hippy-Vue 在升级3.0可以完全兼容之前的版本，除了升级如上依
 
 
 
-### hippy-vue-next
+## hippy-vue-next
 
 >如果业务目前使用 Vue 3.x 来开发 Hippy，可以参考当前章节升级指引。
 </br>
@@ -74,13 +74,15 @@ Hippy-Vue-Next 在升级3.0可以完全兼容之前的版本，除了升级如
 
 一、Hippy 3.0 前端架构升级主要有如下改动点：
 </br>
+
 1. JS 驱动上屏的方式由 UIManagerModule 变为了 SceneBuilder。
 2. Node API 重新实现了 Move 计算逻辑。
 3. Event 由前端分发变为 DOM 分发。
 4. 动画由 bridge 模块变为 C++ DOM 模块实现。
 
 二、需要验证关注点：
 </br>
+
 1. 界面的UI视图渲染正常 （UI结构、样式属性等），特别关注 Hippy-React/Vue 中因为条件渲染语句，产生的节点`Move`操作，表现是否正常。
 2. UI事件（点击、滑动）等表现正常，特别关注事件`冒泡`、`捕获`等表现是否正常。
 3. 关注`动画`表现是否正常。
@@ -90,8 +92,10 @@ Hippy-Vue-Next 在升级3.0可以完全兼容之前的版本，除了升级如
 
 # 新特性
 
-### Performance API
+## Performance API
+
 Hippy 3.0 我们实现了基于前端规范设计的性能 API，接入方式可参考 [performance](feature/feature3.0/performance.md)。
 
-### Layout 引擎支持切换
+## Layout 引擎支持切换
+
 Hippy 3.0 我们支持了 Layout 引擎的无缝切换，项目可保持`Yoga`引擎，也可以选择Hippy自研的`Taitank`引擎。详情可参考 [layout](feature/feature3.0/layout.md)