Feature/update vue-next api docs

docs/api/_sidebar.md

@@ -1,4 +1,3 @@
-<!-- docs/hippy-vue/_sidebar.md -->
 * hippy-react
   * [介绍](api/hippy-react/introduction.md)
   * [组件](api/hippy-react/components.md)
@@ -18,7 +17,16 @@
   * [自定义组件和模块](api/hippy-vue/customize.md)
   * [路由](api/hippy-vue/router.md)
   * [转 Web](api/hippy-vue/web.md)
-  * [Vue 3.x](api/hippy-vue/vue3.md)
+* hippy-vue-next
+  * [介绍](api/hippy-vue-next/introduction.md)
+  * [核心组件](api/hippy-vue-next/components.md)
+  * [扩展组件](api/hippy-vue-next/external-components.md)
+  * [模块](api/hippy-vue-next/vue-native.md)
+  * [样式](api/hippy-vue-next/style.md)
+  * [事件](api/hippy-vue-next/native-event.md)
+  * [自定义组件和模块](api/hippy-vue-next/customize.md)
+  * [路由](api/hippy-vue-next/router.md)
+  * [转 Web](api/hippy-vue-next/web.md)
 * 样式
   * [布局](api/style/layout.md)
   * [外观](api/style/appearance.md)

docs/api/hippy-react/_sidebar.md

@@ -1,4 +1,4 @@
-<!-- docs/hippy-vue/_sidebar.md -->
+<!-- docs/hippy-react/_sidebar.md -->
 * hippy-react
   * [介绍](api/hippy-react/introduction.md)
   * [组件](api/hippy-react/components.md)
@@ -18,7 +18,16 @@
   * [自定义组件和模块](api/hippy-vue/customize.md)
   * [路由](api/hippy-vue/router.md)
   * [转 Web](api/hippy-vue/web.md)
-  * [Vue 3.x](api/hippy-vue/vue3.md)
+* hippy-vue-next
+  * [介绍](api/hippy-vue-next/introduction.md)
+  * [核心组件](api/hippy-vue-next/components.md)
+  * [扩展组件](api/hippy-vue-next/external-components.md)
+  * [模块](api/hippy-vue-next/vue-native.md)
+  * [样式](api/hippy-vue-next/style.md)
+  * [事件](api/hippy-vue-next/native-event.md)
+  * [自定义组件和模块](api/hippy-vue-next/customize.md)
+  * [路由](api/hippy-vue-next/router.md)
+  * [转 Web](api/hippy-vue-next/web.md)
 * 样式
   * [布局](api/style/layout.md)
   * [外观](api/style/appearance.md)

docs/api/hippy-react/web.md

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

docs/api/hippy-vue-next/_sidebar.md

@@ -0,0 +1,39 @@
+<!-- docs/hippy-vue-next/_sidebar.md -->
+* hippy-react
+  * [介绍](api/hippy-react/introduction.md)
+  * [组件](api/hippy-react/components.md)
+  * [模块](api/hippy-react/modules.md)
+  * [样式](api/hippy-react/style.md)
+  * [事件](api/hippy-react/native-event.md)
+  * [手势系统](api/hippy-react/gesture.md)
+  * [自定义组件和模块](api/hippy-react/customize.md)
+  * [转 Web](api/hippy-react/web.md)
+* hippy-vue
+  * [介绍](api/hippy-vue/introduction.md)
+  * [核心组件](api/hippy-vue/components.md)
+  * [扩展组件](api/hippy-vue/external-components.md)
+  * [模块](api/hippy-vue/vue-native.md)
+  * [样式](api/hippy-vue/style.md)
+  * [事件](api/hippy-vue/native-event.md)
+  * [自定义组件和模块](api/hippy-vue/customize.md)
+  * [路由](api/hippy-vue/router.md)
+  * [转 Web](api/hippy-vue/web.md)
+* hippy-vue-next
+  * [介绍](api/hippy-vue-next/introduction.md)
+  * [核心组件](api/hippy-vue-next/components.md)
+  * [扩展组件](api/hippy-vue-next/external-components.md)
+  * [模块](api/hippy-vue-next/vue-native.md)
+  * [样式](api/hippy-vue-next/style.md)
+  * [事件](api/hippy-vue-next/native-event.md)
+  * [自定义组件和模块](api/hippy-vue-next/customize.md)
+  * [路由](api/hippy-vue-next/router.md)
+  * [转 Web](api/hippy-vue-next/web.md)
+* 样式
+  * [布局](api/style/layout.md)
+  * [外观](api/style/appearance.md)
+  * [颜色](api/style/color.md)
+  * [变形](api/style/transform.md)
+  * [更改终端属性](api/style/setNativeProps.md)
+* [网络请求](api/network-request.md)
+* [性能监控](api/performance.md)
+* [定时器](api/timer.md)

docs/api/hippy-vue-next/customize.md

@@ -0,0 +1,152 @@
+# 自定义组件和模块
+
+---
+
+# registerElement
+
+@hippy/vue-next 提供了 `registerElement` 方法来注册组件，可以将 template 中的 tag 和原生组件映射起来。
+
+## 示例
+
+```javascript
+import { registerElement } from '@hippy/vue-next';
+
+/*
+ * 直接注册一个 ComponentName 到终端组件，这里推荐单词首字母大写的拼写。
+ * template 里可以直接用 <ComponentName />
+ * ComponentName 必须跟终端组件名称一致，且不能包含 Hippy 字符。
+ */
+registerElement('MyView');
+
+/*
+ * 也可以注册一个小写的 tagname，然后通过参数映射到 ComponentName 终端组件
+ * 但是 tagname 忽略大小写后也不能和 ComponentName 相同。(如 tag name 命名为 my-view, component name 不能命名为 MyView)
+ * template 里可以直接用 <tagname />，同样会映射 ComponentName 组件上。
+ * ComponentName 必须跟终端组件名称一致，不能包含 Hippy 字符。
+ */
+registerElement('h-my-view', {
+  component: {
+    name: 'MyView',
+  },
+});
+```
+
+## 绑定终端事件返回值
+
+因为 @hippy/vue-next 采用了和浏览器一致的事件模型，又希望能统一双端的事件（有的时候双端事件返回值不一样），所以采取了手动修改事件返回值的方案，需要显式声明每个事件的返回值。
+
+这一步是在注册组件时通过 `processEventData` 方法进行处理的，它有三个参数：
+
+* evtData: 包括终端回调函数里接收到的事件实例，需要对它进行修改。以及终端的原生事件名称
+* nativeEventParams：终端的原生事件返回体
+
+例如，@hippy/vue-next 的 [hi-swiper 组件](//github.com/Tencent/Hippy/blob/master/packages/hippy-vue-next/src/native-component/swiper.ts#L38)，它是 swiper 实际渲染的对应节点。
+
+```javascript
+    component: {
+      name: 'ViewPager',
+      processEventData(
+        evtData: EventsUnionType,
+        nativeEventParams: { [key: string]: NeedToTyped },
+      ) {
+        // handler 及事件示例，可以对其进行修改。__evt则是终端的原生事件名称
+        const { handler: event, __evt: nativeEventName } = evtData;
+
+        switch (nativeEventName) {
+          case 'onPageSelected':
+            event.currentSlide = nativeEventParams.position;
+            break;
+          case 'onPageScroll':
+            event.nextSlide = nativeEventParams.position;
+            event.offset = nativeEventParams.offset;
+            break;
+          case 'onPageScrollStateChanged':
+            event.state = nativeEventParams.pageScrollState;
+            break;
+          default:
+        }
+        return event;
+      },
+    }
+```
+
+# app.component
+
+当你需要处理更加复杂的交互、事件、生命周期的时候，需要通过 `app.component` 注册一个单独的组件，registerElement 只能做到很基本的元素名称到组件的映射，和基本的参数映射。
+
+[详情参考](//cn.vuejs.org/guide/components/registration.html)
+
+## 事件处理
+
+通过 `app.component` 自定义的组件，若需要将终端事件传给组件外层，需要做额外处理，有两种方式：
+
+* 使用 `render` 函数（推荐）
+
+```javascript
+  // 这里的 vueApp 是通过 createApp 创建得到的 hippyVueApp 实例
+  vueApp.component('Swiper', {
+    /*
+     * 可以用 render 函数的方式
+     * 'pageScroll'是传输给终端的事件名（传输终端时会被自动转成转成onPageScroll）
+     * 'dragging' 是真正暴露给用户使用的事件名
+     */
+    render(h) {
+        const on = {
+            onPageSelected: this.$attrs['onDropped'],
+            onPageScroll: this.$attrs['onDragging'],
+            onPageScrollStateChanged: this.$attrs['onStateChanged'],
+        };
+        return h('hi-swiper', {
+            ...on,
+            ref: 'swiper',
+            initialPage: this.$initialSlide,
+        // 需要注意 Vue3.x 相比 2.x，slots这里参数有所变化，default是方法而不是属性了
+        }, this.$slots.default ? this.$slots.default() : null);
+    },
+});
+```
+
+* 使用 `template`
+
+```javascript
+  vueApp.component('Swiper', {
+    /*
+     * 可以用 template 的方式，HippyVue会在运行时将其转换成 render 函数
+     * 'pageScroll'是传输给终端的事件名（传输终端时会被自动转成onPageScroll）
+     * 'dragging' 是真正暴露给用户使用的事件名
+     */
+    template: `
+      <hi-swiper
+          :initialPage="$initialSlide"
+          ref="swiper"
+          @pageScroll="$emit('dragging', $event)"
+          @pageScrollStateChanged="$emit('stateChanged', $event)"
+          @pageSelected="$emit('dropped', $event)"
+      >
+      <slot />
+      </hi-swiper>`,
+});
+```
+
+# 自定义模块
+
+> 该范例仅可以在 Android 下运行。
+
+@hippy/vue-next 的模块其实只是一个 `Native.callNative` 调用，写个 `function` 即可。
+
+```js
+import { Native } from  '@hippy/vue-next';
+
+function log(msg) {
+  Native.callNative("TestModule", "log", msg)
+}
+
+function helloNative(msg) {
+  Native.callNative("TestModule", "helloNative", msg)
+}
+
+// 这个是需要终端回调的
+function helloNativeWithPromise(msg) {
+  return Native.callNativeWithPromise("TestModule", "helloNativeWithPromise", msg);
+}
+```