Merge branch 'main' into main

README.md

@@ -17,7 +17,7 @@ Hippy is now applied in [Tencent](http://www.tencent.com/) major apps such as Mo
 * Excellent performance with JS engine binding communication.
 * Build-in recyclable component with better performance.
 * Smoothly and gracefully migrate to Web browser.
-* Fully supported Flex [Layout engine](./layout).
+* Fully supported Flex [Layout engine](https://github.com/Tencent/taitank).
 
 ## 🔨 Getting started
 

devtools/devtools-integration/native/src/v8/trace_control.cc

@@ -67,6 +67,15 @@ void TraceControl::StartTracing() {
     auto trace_config = v8::platform::tracing::TraceConfig::CreateDefaultTraceConfig();
     trace_config->SetTraceRecordMode(v8::platform::tracing::TraceRecordMode::RECORD_CONTINUOUSLY);
     trace_config->AddIncludedCategory(kTraceIncludedCategoryV8);
+    trace_config->EnableSystrace();
+    trace_config->AddIncludedCategory("devtools.timeline");
+    trace_config->AddIncludedCategory("v8.execute");
+    trace_config->AddIncludedCategory("disabled-by-default-devtools.timeline");
+    trace_config->AddIncludedCategory("disabled-by-default-devtools.timeline.frame");
+    trace_config->AddIncludedCategory("disabled-by-default-devtools.timeline.stack");
+    trace_config->AddIncludedCategory("disabled-by-default-v8.cpu_profiler");
+    trace_config->AddIncludedCategory("disabled-by-default-v8.cpu_profiler.hires");
+    trace_config->AddIncludedCategory("latencyInfo");
     v8_trace_control_->StartTracing(trace_config);
     tracing_has_start_ = true;
   }

docs/README.md

@@ -1,8 +1,8 @@
 # Hippy 简介
 
-版本：3.3.0
+版本：3.3.2
 
-更新时间：2024-6-26
+更新时间：2024-11-12
 
 SDK介绍：Hippy 是 TDF 腾讯端框架（Tencent Device-oriented Framework）下的开源跨平台应用开发解决方案。Hippy 可以理解为一个精简版的浏览器，从底层做了大量工作，抹平了 iOS 和 Android 双端差异，提供了接近 Web 的开发体验，目前上层支持了 React 和 Vue 两套界面框架，前端开发人员可以通过它，将前端代码转换为终端的原生指令，进行原生终端 App 的开发。同时，Hippy 从底层进行了大量优化，在启动速度、渲染性能、动画速度、内存占用、包体积等方面都提供了业内顶尖的性能表现。
 

docs/api/_sidebar.md

@@ -8,6 +8,7 @@
   * [手势系统](api/hippy-react/gesture.md)
   * [自定义组件和模块](api/hippy-react/customize.md)
   * [转 Web](api/hippy-react/web.md)
+  * [React 常见反馈](api/hippy-react/feedback.md)
 * hippy-vue
   * [介绍](api/hippy-vue/introduction.md)
   * [核心组件](api/hippy-vue/components.md)
@@ -19,12 +20,15 @@
   * [路由](api/hippy-vue/router.md)
   * [转 Web](api/hippy-vue/web.md)
   * [Vue 3.x](api/hippy-vue/vue3.md)
+  * [Vue 常见反馈](api/hippy-vue/feedback.md)
 * 样式
   * [布局](api/style/layout.md)
   * [外观](api/style/appearance.md)
   * [颜色](api/style/color.md)
   * [变形](api/style/transform.md)
   * [更改终端属性](api/style/setNativeProps.md)
+  * [样式常见反馈](api/style/feedback.md)
 * [网络请求](api/network-request.md)
 * [性能监控](api/performance.md)
 * [定时器](api/timer.md)
+* [常见反馈](api/feedback.md)

docs/api/feedback.md

@@ -0,0 +1,92 @@
+# 常见反馈
+
+## 1. Hippy提供了@hippy/react-web和Web Renderer两套方案，哪一套方案转web的能力更完整一些呢？Hippy后续会重点支持哪一个方向？
+
+两套方案都有一些业务在用,  组件和属性支持可以参考这两个文档
+
+https://iwiki.woa.com/p/1478044741
+
+https://iwiki.woa.com/p/1410007954
+
+Hippy 会继续维护 Web Renderer，基于 Web Render，更容易对接 kbone 等来扩展小程序
+
+## 2. Hippy 如何支持小程序
+
+可以Hippy 对接 Kbone、taro、uniapp 等框架，腾讯内部业务可参考其他[业务方案](https://doc.weixin.qq.com/doc/w3_ANsAsgZ1ACcxxR1G3KPR0K85XYnmP?scode=AJEAIQdfAAoD1a4bp0ANsAsgZ1ACc)：
+
+## 3. Hippy 的组件库有推荐吗
+
+[开源仓库](https://github.com/hippy-contrib)
+
+[腾讯内部仓库](https://raftx.woa.com/hippy)
+
+## 4. Hippy 如何做曝光上报
+
+目前 Hippy 还没有对外的曝光上报方案，腾讯内部的业务，可以使用大同来做曝光上报
+
+### 方案
+
+hippy本质上使用的还是客户端原生组件 以及一部分自绘组件。客户端已集成的的大同sdk能够对原生组件、Activity等做检测上报，自然也可以对hippy的组件做检测上报。重点处理上报id绑定到组件的逻辑就可以。
+
+### 接入指引
+
+[Hippy Android 曝光上报指引](https://iwiki.woa.com/p/956352478)
+
+[Hippy iOS 曝光上报指引](https://iwiki.woa.com/p/589637144)
+
+有疑问可以咨询企业微信 TDF小助手
+
+
+## 5. 启动时, Hippy 如何从终端获取参数
+
+React 通过根节点的 props 获取启动参数
+
+Vue 通过 Vue.$start 回调获取启动参数
+
+## 6. Hippy 页面支持 width: auto 吗
+
+不支持的，可以用imageloader加载读图片尺寸，https://hippyjs.org/#/hippy-vue/vue-native?id=imageloader
+
+## 7. Hippy 背景透明是否支持毛玻璃效果呢
+
+腾讯业务可参考[社区组件](https://raftx.woa.com/hippy/detail/578)
+
+## 8. Hippy 如何实现暗黑模式
+
+有两种方案：
+
+方案一：设置2套css属性，然后切换时整体切换，性能较差
+
+方案二：初始化节点时，把两套属性都带下去，然后终端渲染时切换
+
+## 9. Hippy 有提供类似 IntersectionObserver 方法吗
+
+react 还不支持，vue有封装了一个，可以参考封装下 [hippy-vue-intersection-observer](https://www.npmjs.com/package/hippy-vue-intersection-observer) 不过这个库是基于hippy的Measure API实现的，对bridge通信性能会有一定性能影响，使用时注意评估下
+
+## 10. Hippy 有 Clipboard 的复制剪切功能吗
+
+剪切板相关的能力应该是在3.2移出的，其他版本可以参考文档：https://github.com/Tencent/Hippy/blob/v2.15.x/docs/hippy-react/modules.md#clipboard
+
+## 11. 我们现在前端用的是React技术栈，我们想一部分业务用Vue，一部分业务用React，Hippy支持这种用法吗
+
+支持的，但是react 和 vue得是不同的hippy引擎实例
+
+## 12. Hippy 如何判断横屏
+
+进入app后，横屏切换会触发 onSizeChanged 事件
+
+进入app前已经横屏，这个可以读 Vue.Native.Dimensions ,获取当前窗口长宽来计算，可以参考这个帖子 https://mk.woa.com/q/293192?ADTAG=search
+
+## 13. Hippy 图片必须要设定宽高吗？希望宽度和父级view一样，高度自适应怎么写呢
+
+可以用 ImageLoaderModule.getSize 这个接口先获取图片大小 https://hippyjs.org/#/hippy-react/modules?id=imageloadermodule
+
+## 14. 执行报错 startBatch is not a function, 可能是什么原因
+
+startBatch是 Hippy2 才有的版本，如果前端使用 Hippy2 终端使用 Hippy3 会不兼容，检查下@hippy/hippy-vue 的版本，确保和终端版本一致
+
+## 15. Hippy 是否支持动态加载
+
+支持，参考 https://doc.openhippy.com/#/feature/feature2.0/dynamic-import
+
+

docs/api/hippy-react/_sidebar.md

@@ -8,6 +8,7 @@
   * [手势系统](api/hippy-react/gesture.md)
   * [自定义组件和模块](api/hippy-react/customize.md)
   * [转 Web](api/hippy-react/web.md)
+  * [React 常见反馈](api/hippy-react/feedback.md)
 * hippy-vue
   * [介绍](api/hippy-vue/introduction.md)
   * [核心组件](api/hippy-vue/components.md)
@@ -19,12 +20,15 @@
   * [路由](api/hippy-vue/router.md)
   * [转 Web](api/hippy-vue/web.md)
   * [Vue 3.x](api/hippy-vue/vue3.md)
+  * [Vue 常见反馈](api/hippy-vue/feedback.md)
 * 样式
   * [布局](api/style/layout.md)
   * [外观](api/style/appearance.md)
   * [颜色](api/style/color.md)
   * [变形](api/style/transform.md)
   * [更改终端属性](api/style/setNativeProps.md)
+  * [样式常见反馈](api/style/feedback.md)
 * [网络请求](api/network-request.md)
 * [性能监控](api/performance.md)
 * [定时器](api/timer.md)
+* [常见反馈](api/feedback.md)

docs/api/hippy-react/components.md

@@ -157,6 +157,12 @@ import icon from './qb_icon_new.png';
 >
 >* time: number: 可指定延迟多久后收起 PullHeader，单位ms
 
+### expandPullHeader
+
+> 最低支持版本 `2.14.0`
+
+`() => void` 展开顶部下拉刷新条 PullHeader。当设置了`renderPullHeader`后，可以通过该方法来主动触发下拉刷新的效果。
+
 ### collapsePullFooter
 
 > 最低支持版本 `2.14.0`
@@ -503,6 +509,7 @@ import icon from './qb_icon_new.png';
 | ------------------------ | ------------------------------------------------------------ | -------------------------------------------- | -------- |
 | bounces | 是否开启回弹效果，默认 `true` | `boolean`                                                  | `iOS、Voltron`    |
 | initialPage              | 指定一个数字，用于决定初始化后默认显示的页面 index，默认不指定的时候是0 | `number`                                     | `Android、iOS、hippy-react-web、Web-Renderer、Voltron` |
+| offscreenPageLimit       | 指定一个数字，用于设置最大挂载到view tree的page item数量，默认为1，如果在间隔较大的item之间切换遇到一些刷新闪动问题，可以尝试设置该属性为最大page item count来解决 | `number`    | `Android` |
 | scrollEnabled            | 指定 ViewPager 是否可以滑动，默认为 `true`                        | `boolean`                                    | `Android、iOS、hippy-react-web、Web-Renderer、Voltron` |
 | onPageSelected           | 指定一个函数，当 page 被选中时进行回调。回调参数是一个 event 对象，回调参数： `position: number` - 表示即将滑到的目标 page 的索引 | `(obj: {position: number}) => void`      | `Android、iOS、hippy-react-web、Web-Renderer、Voltron` |
 | onPageScroll             | 指定一个函数，当 page 被滑动时进行回调。回调参数是一个 event 对象，回调参数 `position: number` - 表示即将滑到的目标 page 的索引，`offset: number` - 当前被选中的 page 的相对位移，取值范围 -1 到 1 | `(obj: {position: number, offset: number}) => void` | `Android、iOS、Web-Renderer、Voltron`    |
@@ -543,7 +550,8 @@ 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` |  `Android、iOS、Voltron`
+| renderBanner | 如何渲染 Banner (即Header，显示在内容顶部) | `() => React.ReactElement` |  `Android、iOS、Voltron` |
+| renderFooter | 如何渲染 Footer（与renderBanner对应，Footer显示在内容底部） | `() => React.ReactElement` |  `iOS`（3.3.2版本起支持） |
 | 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`    |

docs/api/hippy-react/customize.md

@@ -36,14 +36,20 @@ export class MyView extends React.Component {
 
 # 自定义模块
 
-> 该范例仅可以在 Android 下运行。
-
 前端扩展模块分为三步：
 
 1. 第一步导入 callNative 或者 callNativeWithPromise 接口
 2. 封装调用接口
 3. 导出模块
 
+注: callNative 代表前端调用客户端接口，无需返回
+callNativeWithPromise 代表前端调用客户端接口，需要返回，返回一个 Promise 对象
+
+callNtive/callNativeWithPromise 参数含义:
+moduleName: 代表和终端约定的模块名字，为 string 类型
+functionName: 代表和终端约定的模块函数名字，为 string 类型
+params: 实际携带参数, 为 Object 类型
+
 ```javascript
 // TestModule.js
 import { callNative, callNativeWithPromise } from "@hippy/react"

docs/api/hippy-react/feedback.md

@@ -0,0 +1,18 @@
+# Hippy-React 常见反馈
+
+## 1. 如何开始一个hippy react 项目
+
+可以先参考我们的文档 和 demo
+
+https://hippyjs.org/#/hippy-react/introduction
+
+https://github.com/Tencent/Hippy/tree/master/examples/hippy-react-demo
+
+## 2. Hippy 是否支持 React 函数式写法
+
+目前 Hippy 已适配 React 17，已支持函数式写法，未来会持续 React 18、9
+
+## 3. Hippy-React支持class吗，就向下面这样传统react开发一样
+
+Hippy-React 不支持 classname, 只能通过内联 Style
+

docs/api/hippy-react/modules.md

@@ -433,6 +433,10 @@ AsyncStorage 是一个简单的、异步的、持久化的 Key-Value 存储系
 > - method：方法名称，如 ListView 的 `scrollToIndex`
 > - options: 需传递的数据，如 ListView 的 `[xIndex, yIndex, animated]`，空时显式写 `[]`
 
+注: 也可以传入 callback 参数，这个是 Hippy 内部 API, 不推荐使用，源码可参考：
+
+[callUIFunction接口实现源码](https://github.com/Tencent/Hippy/blob/main/driver/js/packages/hippy-react/src/modules/ui-manager-module.ts)
+
 ### UIManagerModule.getElementFromFiberRef
 
 获取元素 Ref 对应的 Element(类似DOM)。`hippy-react-web` 不支持。

docs/api/hippy-vue/_sidebar.md

@@ -8,6 +8,7 @@
   * [手势系统](api/hippy-react/gesture.md)
   * [自定义组件和模块](api/hippy-react/customize.md)
   * [转 Web](api/hippy-react/web.md)
+  * [常见反馈](api/hippy-react/feedback.md)
 * hippy-vue
   * [介绍](api/hippy-vue/introduction.md)
   * [核心组件](api/hippy-vue/components.md)
@@ -19,12 +20,14 @@
   * [路由](api/hippy-vue/router.md)
   * [转 Web](api/hippy-vue/web.md)
   * [Vue 3.x](api/hippy-vue/vue3.md)
+  * [常见反馈](api/hippy-vue/feedback.md)
 * 样式
   * [布局](api/style/layout.md)
   * [外观](api/style/appearance.md)
   * [颜色](api/style/color.md)
   * [变形](api/style/transform.md)
   * [更改终端属性](api/style/setNativeProps.md)
+  * [常见反馈](api/style/feedback.md)
 * [网络请求](api/network-request.md)
 * [性能监控](api/performance.md)
 * [定时器](api/timer.md)

docs/api/hippy-vue/customize.md

@@ -124,10 +124,16 @@ component: {
 
 # 自定义模块
 
-> 该范例仅可以在 Android 下运行。
-
 hippy-vue 的模块其实只是一个 `Vue.Native.callNative` 调用，写个 `function` 即可。
 
+注: callNative 代表前端调用客户端接口，无需返回
+callNativeWithPromise 代表前端调用客户端接口，需要返回，返回一个 Promise 对象
+
+callNtive/callNativeWithPromise 参数含义:
+moduleName: 代表和终端约定的模块名字，为 string 类型
+functionName: 代表和终端约定的模块函数名字，为 string 类型
+params: 实际携带参数, 为 Object 类型
+
 ```js
 import Vue from 'vue';
 

docs/api/hippy-vue/external-components.md

@@ -280,7 +280,7 @@ export default {
 | columnSpacing     | 瀑布流每列之前的水平间距                                      | `number`   | `Android、iOS、Voltron`    |
 | interItemSpacing  | item 间的垂直间距                                        | `number`   | `Android、iOS、Voltron`    |
 | contentInset      | 内容缩进 ，默认值 `{ top:0, left:0, bottom:0, right:0 }`  | `Object`   | `Android、iOS、Voltron`    |
-| containBannerView | 是否包含`bannerView`，只能有一个bannerView，`Android` 暂不支持  | `boolean`  | `iOS、Voltron`    |
+| containBannerView | 是否包含`bannerView`，只能有一个bannerView， (`Android` 暂不支持，`iOS` 3.3.2版本起已废弃该属性，请使用`waterfall-item`组件`isHeader/isFooter`属性代替)  | `boolean`  | `iOS、Voltron`    |
 | containPullHeader | 是否包含`pull-header`；`Android` 暂不支持，可以用 `ul-refresh` 组件替代  | `boolean`  | `iOS、Voltron`    |
 | containPullFooter | 是否包含 `pull-footer` | `boolean`  | `Android、iOS、Voltron` |
 | numberOfColumns   | 瀑布流列数量，Default: 2                                               | `number`   | `Android、iOS、Voltron`    |
@@ -323,3 +323,5 @@ export default {
 | --------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- | -------- |
 | type            | 指定一个函数，在其中返回对应条目的类型（返回Number类型的自然数，默认是0），List 将对同类型条目进行复用，所以合理的类型拆分，可以很好地提升 List 性能。 | `number`              | `Android、iOS、Voltron`    |
 | key             | 指定一个函数，在其中返回对应条目的 Key 值，详见 [Vue 官网](//vuejs.org/v2/guide/list.html) | `string`                                    | `Android、iOS、Voltron`    |
+| isHeader | 指定该Item是否为Header（即bannerView，显示在内容区顶部） | `boolean` | `iOS`（3.3.2版本起支持） |
+| isFooter | 指定该Item是否为Footer（显示在内容区底部） | `boolean` | `iOS`（3.3.2版本起支持） |

docs/api/hippy-vue/feedback.md

@@ -0,0 +1,28 @@
+# Hippy-Vue 常见反馈
+
+## 1. 如何开始一个hippy vue 项目
+
+可以先参考我们的文档 和 demo
+
+https://hippyjs.org/#/hippy-vue/introduction
+https://github.com/Tencent/Hippy/tree/master/examples/hippy-vue-demo
+
+## 2. Hippy Vue中span的换行符会被 trim
+
+3.x hippy-vue的版本，Hippy默认开启了 Vue.config.trimWhitespace 这个参数。而 hippy-vue 2.x的版本是不开的, 这个也是为了和未来 vue3 版本的规划对齐
+https://github.com/vuejs/core/pull/1600
+
+方案建议：
+a.  在 hippy.js 文件加一句 Vue.config.trimWhitespace = false，这样配置就和安卓版本完全对齐了。这个参数会对产物有一些影响，也可以让你们前端同事再重新评估一下。
+
+b. 因为现在 hippy 没有提供换行组件 br标签 或者 white-space 的 css，如果需要换行，则不适用span，而是重新创建一个 text文本组件
+
+## 3. hippy-vue-next-style-parser，这个包的作用
+
+这个包用于处理 vue-next 的 css parse 和 match 逻辑
+
+## 4. Hippy 是否支持 Vite 构建
+
+已支持，目前只有腾讯内部版，腾讯业务可联系 TDF小助手
+
+

docs/api/hippy-vue/vue-native.md

@@ -194,6 +194,10 @@ Vue.Native.AsyncStorage.getItem('itemKey');
 > * method：方法名称，如 ListView 的 `scrollToIndex`
 > * options: 需传递的数据，如 ListView 的 `[xIndex, yIndex, animated]`
 
+注: 也可以传入 callback 参数，这个是 Hippy 内部 API, 不推荐使用，源码可参考：
+
+[callUIFunction接口实现源码](https://github.com/Tencent/Hippy/blob/main/driver/js/packages/hippy-vue/src/runtime/native.ts)
+
 ---
 
 # Clipboard

docs/api/hippy-vue/web.md

@@ -2,4 +2,4 @@
 
 ## WebRenderer 方案
 
-Hippy 全新 [`WebRenderer`](web/integration.md) 方案，增加基于公共通信协议的转换层，业务开发者可以使用同一套 Hippy 语法开发的业务代码，映射成 JS 实现的组件和模块，上层无论使用 React，Vue 或者其他第三方框架，都可以实现兼容，可参考。
+Hippy 全新 [`WebRenderer`](development/web-integration-guidelines.md) 方案，增加基于公共通信协议的转换层，业务开发者可以使用同一套 Hippy 语法开发的业务代码，映射成 JS 实现的组件和模块，上层无论使用 React，Vue 或者其他第三方框架，都可以实现兼容，可参考。