跨平台移动开发前端【免费下载链接】HippyHippy is designed to easily build cross-platform dynamic apps. 项目地址https://gitcode.com/gh_mirrors/hi/Hippy点击查看免费下载hippy-vue 允许开发者把终端Android/iOS/鸿蒙等上的原生组件映射为 Vue template 中的标签把终端事件转成 Vue 事件并把终端能力封装成前端可调用的模块。本文以仓库文档docs/api/hippy-vue/customize.md为主线结合driver/js/packages/hippy-vue与driver/js/packages/hippy-vue-native-components的源码完整讲解Vue.registerElement、processEventData事件返回值处理、Vue.component复杂组件封装以及基于Vue.Native.callNative的自定义模块开发。读完本篇你将能够独立注册一个终端组件为 hippy-vue 元素、手动对齐双端事件参数、用 render/template 两种模式封装带事件重定向的复合组件并实现“前端调终端”的无返回/带 Promise 返回的模块接口。1. 自定义能力总览三个层次hippy-vue 的自定义体系按复杂度分为三层文档中依次给出了对应方案层次机制适用场景能力边界元素映射Vue.registerElement把 template 中的 tag 与终端原生组件建立映射元素名称到组件的映射、基本参数映射支持processEventData修正事件返回值复合组件Vue.component需要处理更复杂的交互、事件、生命周期完整的 Vue 组件能力props、watch、ref、render/template可把终端事件重定向为任意用户事件模块调用Vue.Native.callNative/callNativeWithPromise前端调用客户端接口callNative无需返回callNativeWithPromise返回 Promise 由终端回调其中registerElement只能做到很基本的元素名称到组件的映射和基本的参数映射当需要处理更加复杂的交互、事件、生命周期时必须通过Vue.component注册一个单独的组件。2. Vue.registerElement把 tag 映射到终端组件hippy-vue 提供了registerElement方法来注册组件将 template 中的 tag 和原生组件映射起来。有两种典型用法。2.1 直接注册一个组件名到终端组件import Vue from vue; /* * 直接注册一个 ComponentName 到终端组件这里推荐单词首字母大写的拼写。 * template 里可以直接用 ComponentName / * ComponentName 必须跟终端组件名称一致且不能包含 Hippy 字符。 */ Vue.registerElement(MyView);这种方式下 template 里可以直接使用MyView /MyView必须与终端上注册的原生组件名称完全一致且不能包含 “Hippy” 字符。2.2 注册小写 tag 并映射到终端组件/* * 也可以注册一个小写的 tagname然后通过参数映射到 ComponentName 终端组件 * 但是 tagname 忽略大小写后也不能和 ComponentName 相同。(如 tag name 命名为 my-view, component name 不能命名为 MyView) * template 里可以直接用 tagname /同样会映射 ComponentName 组件上。 * ComponentName 必须跟终端组件名称一致不能包含 Hippy 字符。 */ Vue.registerElement(h-my-view, { component: { name: MyView, }, });命名约束有两点值得注意其一ComponentName必须与终端组件名称一致不能包含 “Hippy” 字符其二kebab-case 的 tag name 在忽略大小写后不能与component.name相同——例如 tag 命名为my-view时component name 就不能叫MyView。2.3 源码视角registerElement 如何工作从源码结构看registerElement在 runtime 入口 被挂载到 Vue 原型上Vue.registerElement registerElement。其核心实现在 elements/index.ts可以做几点印证注册表elementMap以小写归一化的元素名为键normalizeElementName返回elementName.toLowerCase()这就是为什么h-my-view与H-My-View会命中同一个元素重复注册同一元素会直接抛出Element for ${elementName} already registered.错误空名称会抛出RegisterElement cannot set empty name未提供component时会生成一个函数式默认组件getDefaultComponent其 render 就是把收到的data和children透传给归一化标签名——即完成 “tag → 终端组件” 的最短映射路径对 2.2 中提到的命名冲突源码里有一条明确的告警逻辑若component.name与 kebab-case 元素名转 camelCase 后相同如my-view与MyView会打印Cannot registerElement with kebab-case name ... please make them different与文档约束一一对应。3. processEventData手动对齐双端事件返回值hippy-vue 采用了和浏览器一致的事件模型但又希望统一双端事件有时双端事件的返回值不一样所以采取了手动修改事件返回值的方案需要显式声明每个事件的返回值。这一步是在注册组件时通过processEventData方法处理的它有三个参数event终端回调函数里接收到的事件实例需要对它进行修改nativeEventName终端的原生事件名称nativeEventParams终端的原生事件返回体。文档给出的示例是hi-swiper组件——swiper 实际渲染的对应节点component: { name: ViewPager, processEventData(event, nativeEventName, nativeEventParams) { switch (nativeEventName) { case onPageSelected: // 显式将 native 的事件参数 nativeEventParams 的值赋予 hippy-vue 真正绑定的事件 event event.currentSlide nativeEventParams.position; break; case onPageScroll: event.nextSlide nativeEventParams.position; event.offset nativeEventParams.offset; break; default: break; } return event; } }仓库中该组件的真实实现位于 hippy-vue-native-components/src/swiper.ts与文档示例一致并额外处理了滚动状态事件onPageScrollStateChanged时把nativeEventParams.pageScrollState写入event.state。这说明processEventData返回的event就是最终派发给用户监听器的事件对象你可以在其中自由增补、重命名终端返回体里的字段从而抹平 Android 与 iOS 之间同名事件参数不一致的问题。配合事件名转换机制看在 native/index.ts 的事件处理中非手势事件会通过translateToNativeEventName(name)计算终端事件名手势事件则走NativeEventMap映射。这与后文 render 示例中 “pageScroll传输给终端时会被自动转成onPageScroll” 的说明互为印证前端监听驼峰事件名终端侧收到的是on前缀的大驼峰事件名。4. Vue.component封装复杂组件与事件重定向当需要处理更加复杂的交互、事件、生命周期时需要通过Vue.component注册一个单独的组件。registerElement只能做到很基本的元素名称到组件的映射和基本的参数映射Vue.component则提供完整的 Vue 组件能力props、watch、methods、ref、插槽等。组件的注册方式遵循 Vue 2 的常规用法仓库配套文档中 扩展组件 也基于此机制实现。通过Vue.component自定义的组件若需要将终端事件传给组件外层需要做额外处理文档给出两种方式。4.1 方式一使用 render 函数推荐Vue.component(Swiper, { /* * 可以用 render 函数的方式 * pageScroll是传输给终端的事件名传输终端时会被自动转成转成onPageScroll * dragging 是真正暴露给用户使用的事件名 */ render(h) { const on { pageSelected: evt this.$emit(dropped, evt), pageScroll: evt this.$emit(dragging, evt), pageScrollStateChanged: evt this.$emit(stateChanged, evt), }; return h(hi-swiper, { on, ref: swiper, attrs: { initialPage: this.$initialSlide, }, }, this.$slots.default); }, });4.2 方式二使用 templateVue.component(Swiper, { /* * 可以用 template 的方式HippyVue会在运行时将其转换成 render 函数 * pageScroll是传输给终端的事件名传输终端时会被自动转成onPageScroll * dragging 是真正暴露给用户使用的事件名 */ template: hi-swiper :initialPage$initialSlide refswiper pageScroll$emit(dragging, $event) pageScrollStateChanged$emit(stateChanged, $event) pageSelected$emit(dropped, $event) slot / /hi-swiper, });两种方式的本质相同在hi-swiper上监听终端侧事件名驼峰形式如pageScroll再用this.$emit重命名为对外暴露的用户事件名如dragging。template 写法在运行时会被 HippyVue 转换成 render 函数。仓库中 swiper.ts 里的真实Swiper组件是这一模式的完整工程化示例值得展开看它用getEventRedirector工具来自 native-components 的 utils.ts统一生成事件重定向映射[[dropped, pageSelected], [dragging, pageScroll], [stateChanged, pageScrollStateChanged]]与文档示例一一对应它注册了两个registerElement元素hi-swiper映射终端组件ViewPager并附带processEventData第 3 节内容swiper-slide映射ViewPagerItem并通过defaultNativeStyle指定默认的绝对定位铺满样式它通过watch: { current }监听分页变化调用setSlide/setSlideWithoutAnimation二者内部使用Vue.Native.callUIFunction(this.$refs.swiper, setPage, [slideIndex])——这展示了第三种调用形态拿到元素 ref 后直接调用该终端实例上的方法setPage、setPageWithoutAnimation无需走模块名/函数名通道。也就是说完整的封装链路是registerElement完成 tag 与终端组件的映射 →processEventData对齐事件返回体 →Vue.component用 ref callUIFunction暴露命令式 API 事件重定向最终用户只需写Swiper dragging...这样的纯 Vue 代码。5. 自定义模块Vue.Native.callNative 系列hippy-vue 的模块其实只是一个Vue.Native.callNative调用写个function即可。callNative前端调用客户端接口无需返回callNativeWithPromise前端调用客户端接口需要返回返回一个 Promise 对象。callNative/callNativeWithPromise的参数含义参数类型含义moduleNamestring和终端约定的模块名字functionNamestring和终端约定的模块函数名字paramsObject实际携带参数文档给出的完整示例import Vue from vue; function log(msg) { Vue.Native.callNative(TestModule, log, msg) } function helloNative(msg) { Vue.Native.callNative(TestModule, helloNative, msg) } // 这个是需要终端回调的 function helloNativeWithPromise(msg) { return Vue.Native.callNativeWithPromise(TestModule, helloNativeWithPromise, msg); }使用方式就是把上面的function暴露给用户前端按普通函数调用终端侧按moduleName functionName约定实现对应处理若需要回传结果则通过callNativeWithPromise的 Promise 链路回调。模块机制的更多约定如模块注册方式可继续阅读 模块文档。6. 小结与延伸阅读把 hippy-vue 的自定义能力串起来看元素映射用Vue.registerElement直接注册组件名或注册小写 tag 并通过component.name映射命名冲突会被源码中的告警/抛错机制拦截elements/index.ts事件对齐用processEventData(event, nativeEventName, nativeEventParams)显式修改事件实例抹平双端返回体差异参考 hi-swiper 的真实实现复杂组件用Vue.componentrender推荐或 template 两种方式把终端事件重定向为用户事件并可借助ref与Vue.Native.callUIFunction调用终端实例方法模块用Vue.Native.callNative/callNativeWithPromise封装为前端函数按 moduleName/functionName/params 三元组与终端约定。延伸阅读路径均为仓库内相对路径自定义组件和模块原文档hippy-vue 模块文档扩展组件文档hippy-vue 运行时代码入口native 渲染桥节点批量操作与事件处理hippy-vue-native-components 扩展组件库赞分享跨平台移动开发前端【免费下载链接】HippyHippy is designed to easily build cross-platform dynamic apps. 项目地址https://gitcode.com/gh_mirrors/hi/Hippy点击查看免费下载相关推荐Unity UI渐变效果全攻略从基础应用到高级技巧Unity UI渐变效果全攻略从基础应用到高级技巧 Unity UIGradient是一款专为UGUI设计的轻量级渐变效果插件通过纯C 脚本实现丰富的UI色vim-airline鼠标事件绑定自定义事件处理vim airline鼠标事件绑定自定义事件处理 在使用Vim编辑器时你是否曾想过通过鼠标与状态栏进行交互vim airline作为一款轻量级的状态栏插件开发工具UI组件Semi Design HotKeys 快捷键组件实战指南全局事件绑定、按键校验与自定义渲染Semi Design HotKeys 快捷键组件实战指南全局事件绑定、按键校验与自定义渲染 HotKeys 是 Semi Designdouyinfe/前端UI组件设计系统上一篇Cuckoo3错误排查手册常见问题与解决方案大全下一篇System-Design设计模式大全23种经典模式及应用场景创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考