跨平台移动开发前端【免费下载链接】HippyHippy is designed to easily build cross-platform dynamic apps. 项目地址https://gitcode.com/gh_mirrors/hi/Hippy点击查看免费下载扩展组件Native Components是 Hippy 终端侧提供给 hippy-vue 的一批高价值原生容器由hippy/vue-native-components包统一注册源码位于 hippy-vue-native-components 包。本文以官方文档《终端扩展组件》为骨架完整覆盖animation、dialog、swiper/swiper-slide、pull-header/pull-footer、waterfall/waterfall-item的参数、事件与方法并结合仓库源码剖析它们如何将声明式 Vue 模板映射到原生ViewPager、Modal、RefreshWrapper等组件同时附上可运行的官方示例路径帮助你在 Hippy-Vue 3.0 项目中直接落地这些跨端能力。什么是终端扩展组件扩展组件是终端提供的一些非常方便的组件它们封装了 Web/普通 JS 组件难以高效实现的交互形态声明式动画、模态弹窗、ViewPager 翻页、下拉/上拉刷新、瀑布流等。在 hippy-vue 中这些组件由 npm 包hippy/vue-native-components提供仓库内源码见 src/index.ts包描述明确写着 Native components middleware for Hippy-Vue, the components only for native, cant compatible with web——即这些组件仅面向原生端渲染无法与 Web 端兼容。从 index.ts 可以看到插件的安装入口const HippyVueNativeComponents { install(Vue: any) { AnimationComponent(Vue); DialogComponent(Vue); ListRefreshComponent(Vue); SwiperComponent(Vue); PullsComponents(Vue); WaterfallComponent(Vue); }, }; export default HippyVueNativeComponents; // Export specific component for TreeSharking. export { AnimationComponent, DialogComponent, ListRefreshComponent, SwiperComponent, PullsComponents, WaterfallComponent, };也就是说Vue.use(HippyVueNativeComponents)会一次性注册全部六组组件源码同时按组件单独导出了各register函数便于按需引入并配合 TreeShaking 裁剪包体积。各组件在源文件中的注册方式有两种Vue.registerElement(hi-xxx, {...})声明底层原生元素如hi-dialog对应原生组件名Modal、hi-swiper对应ViewPagerVue.component(Xxx, {...})在其上构建 Vue 层面的组件 APIprops 校验、事件重定向、方法封装。下文按文档顺序逐个展开。animation声明式动画组件animation是 hippy-vue 的动画解决方案直接传入一个样式值 动画方案数组即可触发动效。官方范例见 demo-animation.vue更完整的动画场景循环动画、渐变背景色、贝塞尔曲线在 animations 目录。需要特别注意animation本身就是一个 Viewtagprop 默认值为div它会带动所有子节点一起动画。如果需要分开控制动画必须在界面层级上拆分。这一点在源码中可以直接印证——animation.ts 的组件模板component :istag :useAnimationtrue :stylestyle v-bindprops slot / /component组件最终渲染为一个可配置标签默认div并通过:useAnimationtrue告知终端该节点携带动画属性slot/中的子节点随之整体参与动画。参数参数描述类型支持平台playing控制动画是否播放booleanAndroid、iOS、Web-Renderer、Voltronactions*动画方案一个样式值跟上它的动画方案详情请参考下文示例ObjectAndroid、iOS、Web-Renderer、Voltron*actions详解与 HippyReact 不同HippyVue 将单个动画Animation和动画序列AnimationSet合二为一——如果某个样式属性对应的是一个对象就用Animation处理如果是数组动画序列就用AnimationSet处理。动画参数还可参考 HippyReact Animation 模块 与 animations 范例。完整用法示例下面这段代码来自官方文档覆盖单个动画与动画序列的混合用法以及全部事件回调template div animation refanimationRef :actionsactionsConfig :playingtrue startanimationStart endanimationEnd repeatanimationRepeat cancelanimationCancel actionsDidUpdateactionsDidUpdate / /div /template script export default { data() { return { actionsConfig: { // AnimationSet top: [ { startValue: 14, toValue: 8, duration: 125, // 动画持续时间 }, { startValue: 8, toValue: 14, duration: 250, timingFunction: linear, // 动画插值器类型可选 linear、ease-in、ease-out、ease-in-out、cubic-bezier(最低支持版本 2.9.0) delay: 750, // 动画延迟开始的时间单位为毫秒 repeatCount: -1, // 动画的重复次数0 为不重复-1(loop) 为重复播放如果在数组中整个动画数组的重复次数以最后一个动画的值为准 }, ], transform: { // 单个 Animation rotate: { startValue: 0, toValue: 90, duration: 250, timingFunction: linear, valueType: deg, // 动画的开始和结束值的单位类型默认为 undefined, 可设为 rad、deg、color }, }, }, }; }, methods: { animationStart() { console.log(animation-start callback); }, animationEnd() { console.log(animation-end callback); }, animationRepeat() { console.log(animation-repeat callback); }, animationCancel() { console.log(animation-cancel callback); }, actionsDidUpdate() { this.animationRef.start(); } }, }; /script对照 demo-animation.vue 中的注释每个动画项的完整参数与默认值如下参数默认值说明valueTypeundefined动画起止值的单位类型可设为rad、deg、colordelay0动画延迟开始的时间单位毫秒startValue0动画开始时的值toValue0动画结束时的值duration0动画运行时间directioncenter动画运行方向timingFunctionlinear插值器类型linear、ease-in、ease-out、ease-in-out、cubic-bezier最低支持版本 2.9.0repeatCount0重复次数0不重复-1或loop无限重复在数组中时整个序列以最后一个动画的值为准这些默认值与源码中的DEFAULT_OPTION完全一致animation.tsconst DEFAULT_OPTION { valueType: undefined, delay: 0, startValue: 0, toValue: 0, duration: 0, direction: center, timingFunction: linear, repeatCount: 0, inputRange: [], outputRange: [], };事件事件描述类型支持平台start动画开始时触发最低支持版本2.5.2FunctionAndroid、iOS、Web-Renderer、Voltronend动画结束时触发最低支持版本2.5.2FunctionAndroid、iOS、Web-Renderer、Voltronrepeat每次循环播放时触发最低支持版本2.5.2FunctionAndroid、VoltronactionsDidUpdate替换actions且动画对象创建成功后触发可在此时机重新启动动画最低支持版本2.14.0FunctionAndroid、iOS、Voltron补充源码中的事件映射表animation.ts还包含cancel→ 原生animationcancel事件即模板中cancel的绑定来源。方法最低支持版本2.5.2start()() void手动触发动画开始playing置为true也会自动触发start调用pause()() void手动触发动画暂停playing置为false也会自动触发pause调用resume()() void手动触发动画继续playing置为false后再置为true会自动触发resume调用create()() void手动触发动画创建reset()() void重置开始标记destroy()() void销毁动画从源码看animation.ts 的 methodsstart()内部以$alreadyStarted作为状态标记首次调用会收集全部animationId、挂载事件监听并逐个start()若已处于启动态则转调resume()。playing的 watcher 也印证了文档描述false→true调start()true→false调pause()组件mounted后若初始playing为true会延迟一个宏任务再start()以确保原生节点已创建。替换 actions 后的重启策略特别说明对actions替换后会重新创建动画需手动启动新动画。有两种处理方式替换actions→ 延迟一定时间如setTimeout后或者在actionsDidUpdate钩子内2.14.0版本后支持调用this.[animation ref].start()推荐设置playing false→ 替换actions→ 延迟一定时间后或者在actionsDidUpdate钩子内2.14.0版本后支持设置playing true对应源码行为actions的 watcher 先destroy()再create()随后用setTimeout触发actionsDidUpdate监听器——注释写明这是make sure node style updated即保证节点样式更新后再交由业务侧重启动画。高级能力与版本要求渐变色动画2.6.0及以上版本支持backgroundColor背景色渐变参考 color-change.vue 范例。用法对backgroundColor设置actions将valueType设为colorstartValue和toValue使用 color 值。源码中valueType color时起止值会经过Vue.Native.parseColor()转换animation.ts。循环播放2.12.2及以上版本支持repeatCount: loop写法低版本请使用repeatCount: -1。源码中的repeatCountDict函数负责把字符串loop归一化为-1animation.ts。cubic-bezier 插值器最低支持版本2.9.0范例见 cubic-bezier.vue。源码视角actions 如何变成原生动画createStyle 函数 是合二为一的关键实现遍历actions的每个键样式属性若值为数组则把每个子项构造成独立的AnimationrepeatCount强制置 0、follow: true再以最后一个子项的repeatCount构造一个AnimationSet若值为对象则直接构造单个Animation。最终产出的 style 形如{ top: { animationId: 42 }, transform: [{ rotate: { animationId: 43 } }] }即把动画以animationId的形式挂到样式值上由终端侧按 ID 驱动插值。动画实例本身通过new global.Hippy.Animation(option)与new global.Hippy.AnimationSet({ children, repeatCount })创建animation.tsgetId()返回的 ID 同时用于start/pause/destroy与事件订阅addEventListener(animationstart | animationend | animationrepeat | animationcancel)。dialog模态弹窗组件dialog用于模态弹窗默认透明背景色需要加一个带背景色的div填充。官方范例见 demo-dialog.vue。参数参数描述类型支持平台animationType动画效果enum(none, slide, fade, slide_fade)Android、iOS、Web-Renderer、VoltronsupportedOrientations支持屏幕翻转方向enum(portrait, portrait-upside-down, landscape, landscape-left, landscape-right)[]iOSimmersionStatusBar是否是沉浸式状态栏default: truebooleanAndroid、VoltrondarkStatusBarText是否是亮色主体文字。默认字体是黑色的改成true后会认为 Modal 背景为暗色调字体就会改成白色booleanAndroid、iOS、VoltronautoHideStatusBar是否在Modal显示时自动隐藏状态栏。Android 中仅 api28 以上生效default: falsebooleanAndroidautoHideNavigationBar是否在Modal显示时自动隐藏导航栏default: falsebooleanAndroidtransparent背景是否是透明的default: truebooleanAndroid、iOS、Web-Renderer、Voltron事件事件名称描述类型支持平台show在Modal显示时会执行此回调函数FunctionAndroid、iOS、Web-Renderer、VoltronorientationChange屏幕旋转方向改变FunctionAndroid、iOSrequestClose在Modal请求关闭时执行此回调一般在 Android 系统里按下硬件返回按钮时触发一般要在里面处理关闭弹窗FunctionAndroid、Voltron源码层面dialog.ts有两个值得注意的实现细节hi-dialog元素注册为原生组件Modal且defaultNativeStyle为position: absolute即弹窗默认绝对定位覆盖在页面上Dialog组件的render函数会给第一个子元素打上__modalFirstChild__标记marked to remove absolute position to be compatible with hippy 2.0——所以文档要求加一个带背景色的div填充时该div会作为首个子节点被解除绝对定位正常撑开弹窗内容区。swiper / swiper-slide翻页容器swiper是支持翻页的容器它的每一个子容器组件会被视作一个单独的页面对应终端ViewPager组件里面只能包含swiper-slide组件。官方范例见 demo-swiper.vue。参数参数描述类型支持平台bounces是否开启回弹效果默认truebooleaniOS、Voltroncurrent实时改变当前所处页码numberAndroid、iOS、Web-Renderer、VoltroninitialPage指定一个数字用于决定初始化后默认显示的页面 index默认不指定时是0numberAndroid、iOS、Web-Renderer、VoltronneedAnimation切换页面时是否需要动画booleanAndroid、iOS、VoltronscrollEnabled指定 ViewPager 是否可以滑动默认为truebooleanAndroid、iOS、Web-Renderer、Voltrondirection设置 viewPager 滚动方向不设置默认横向滚动设置vertical为竖向滚动stringAndroid、Voltron事件事件名称描述类型支持平台dragging拖动时触发FunctionAndroid、iOS、Web-Renderer、Voltrondropped拖拽松手时触发即确定了滚动的页面时触发FunctionAndroid、iOS、Web-Renderer、VoltronstateChanged*手指行为发生改变时触发包含idle、dragging、settling三种状态通过state参数返回FunctionAndroid、iOS、Web-Renderer、Voltron*stateChanged三种值的意思idle空闲状态dragging拖拽中settling松手后触发然后马上回到idle。从源码swiper.ts可以看清事件与原生事件的映射关系hi-swiper注册为原生ViewPager其processEventData把onPageSelected映射为currentSlide、onPageScroll映射为nextSlide/offset、onPageScrollStateChanged映射为stateVue 层再通过事件重定向器把业务侧的dropped/dragging/stateChanged分别对齐到pageSelected/pageScroll/pageScrollStateChanged。组件watch了currentpropneedAnimation为真时调用Vue.Native.callUIFunction(ref, setPage, [index])否则调用setPageWithoutAnimation即编程式翻页的两种模式都落到原生函数上。另外swiper-slide被注册为ViewPagerItem默认样式是position: absolute且四边为 0保证每页铺满整个翻页容器。swiper-slide本身没有额外参数它就是翻页子容器组件容器。pull-header / pull-footer下拉与上拉刷新pull-header下拉刷新组件嵌套在ul中作为第一个子元素使用。官方范例见 demo-pull-header-footer.vue。事件事件名称描述类型支持平台idle滑动距离在 pull-header 区域内触发一次参数contentOffsetFunctionAndroid、iOS、Voltronpulling滑动距离超出 pull-header 后触发一次参数contentOffsetFunctionAndroid、iOS、Voltronreleased滑动超出距离松手后触发一次FunctionAndroid、iOS、Voltron方法collapsePullHeader(options: { time: number }) void收起顶部刷新条pull-header。使用pull-header后每当下拉刷新结束都需要主动调用该方法收回 pull-header。options参数最低支持版本2.14.0其中time: number可指定延迟多久后收起 PullHeader单位 ms。pull-footer上拉刷新组件嵌套在ul中作为最后一个子元素使用。事件事件名称描述类型支持平台idle滑动距离在 pull-footer 区域内触发一次参数contentOffsetFunctionAndroid、iOS、Voltronpulling滑动距离超出 pull-footer 后触发一次参数contentOffsetFunctionAndroid、iOS、Voltronreleased滑动超出距离松手后触发一次FunctionAndroid、iOS、Voltron方法collapsePullFooter() void收起底部刷新条pull-footer。源码pulls.ts揭示了idle/pulling的判定机制组件在layout事件中记录自身内容高度$contentHeight当原生的onXxxPulling事件携带的contentOffset大于该内容高度时发出pulling否则发出idle并通过$lastEvent去重保证每种状态只在跨入时触发一次——这正对应文档中触发一次的表述。而collapsePullHeader在传入options时会调用原生的collapsePullHeaderWithOptions否则走无参的collapsePullHeader与文档2.14.0 起支持 options的版本线一致。waterfall / waterfall-item瀑布流最低支持版本2.9.0waterfall是瀑布流组件子元素必须是waterfall-item。瀑布流组件的下拉刷新需在最外层用ul-refresh-wrapper可在waterfall内用pull-footer展示上拉加载文案。官方范例见 demo-waterfall.vue。参数参数描述类型支持平台columnSpacing瀑布流每列之前的水平间距numberAndroid、iOS、VoltroninterItemSpacingitem 间的垂直间距numberAndroid、iOS、VoltroncontentInset内容缩进默认值{ top:0, left:0, bottom:0, right:0 }ObjectAndroid、iOS、VoltroncontainBannerView是否包含bannerView只能有一个 bannerViewAndroid 暂不支持iOS 3.3.2 版本起已废弃该属性请使用waterfall-item组件isHeader/isFooter属性代替booleaniOS、VoltroncontainPullHeader是否包含pull-headerAndroid 暂不支持可以用ul-refresh组件替代booleaniOS、VoltroncontainPullFooter是否包含pull-footerbooleanAndroid、iOS、VoltronnumberOfColumns瀑布流列数量默认2numberAndroid、iOS、VoltronpreloadItemNumber滑动到瀑布流底部前提前预加载的 item 数量numberAndroid、iOS、VoltronshowScrollIndicator是否显示滚动条iOS 3.3.2 版本起支持default: truebooleaniOS以上默认值与 waterfall.ts 中的 props 声明 一一对应numberOfColumns默认 2、contentInset默认四边 0、columnSpacing/interItemSpacing/preloadItemNumber默认 0、三个contain*布尔值默认 false。事件事件名称描述类型支持平台endReached当所有数据都已经渲染过并且列表被滚动到最后一条时将触发onEndReached回调FunctionAndroid、iOS、Voltronscroll当触发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源码中hi-waterfall注册为原生WaterfallView其onScroll事件处理函数逐字段解构startEdgePos、endEdgePos、firstVisibleRowIndex、lastVisibleRowIndex、visibleRowFrames后写入事件对象waterfall.ts与文档参数说明完全吻合。方法scrollToIndex(obj: { index: number, animated: boolean }) void通知 Waterfall 滑动到第几个 item。index: number —— 滑动到的第 index 个 itemanimated: boolean —— 滑动过程是否使用动画默认truescrollToContentOffset(obj: { xOffset: number, yOffset: number, animated: boolean }) void通知 Waterfall 滑动到某个具体坐标偏移值offset的位置。xOffset: number —— 滑动到 X 方向的 offsetyOffset: number —— 滑动到 Y 方向的 offsetanimated: boolean —— 滑动过程是否使用动画默认true这些方法在源码中通过Vue.Native.callUIFunction(this.$refs.waterfall, action, params)统一桥接到原生函数。waterfall-item瀑布流 Cell 容器即瀑布流子元素。参数描述类型支持平台type指定一个函数在其中返回对应条目的类型返回 Number 类型的自然数默认是 0List 将对同类型条目进行复用所以合理的类型拆分可以很好地提升 List 性能numberAndroid、iOS、Voltronkey指定一个函数在其中返回对应条目的 Key 值Vue 列表渲染语义stringAndroid、iOS、VoltronisHeader指定该 Item 是否为 Header即 bannerView显示在内容区顶部booleaniOS3.3.2 版本起支持、OhosisFooter指定该 Item 是否为 Footer显示在内容区底部booleaniOS3.3.2 版本起支持、Ohos综合示例waterfall pull-footer header/footerdemo-waterfall.vue 展示了这些参数、事件与子组件如何组合。其模板结构要点waterfall refgridView :content-insetcontentInset :column-spacingcolumnSpacing :contain-banner-view!isAndroid !-- Android 暂不支持 bannerView -- :contain-pull-footertrue :inter-item-spacinginterItemSpacing :number-of-columnsnumberOfColumns :preload-item-number4 endReachedonEndReached scrollonScroll pull-header refpullHeader idle pulling released p classul-refresh-text{{ headerRefreshText }}/p /pull-header waterfall-item :fullSpantrue :isHeadertrue classbanner-view spanBanner View/span /waterfall-item waterfall-item v-for(ui, index) in dataSource :keyindex :style{width: itemWidth} :typeui.style !-- 按条目类型拆分提升复用性能 -- ... /waterfall-item waterfall-item :fullSpantrue :isFootertrue classbanner-view spanFooter View/span /waterfall-item pull-footer refpullFooter idle pulling releasedonEndReached p classpull-footer-text{{ footerRefreshText }}/p /pull-footer /waterfall可以看到isHeader/isFooter的waterfall-item承担了 iOS 3.3.2 起对containBannerView的替代方案pull-footer放在瀑布流末尾承担上拉加载刷新结束按前文方法调用collapsePullHeader/collapsePullFooter收回。对于 Android 的下拉刷新文档建议在最外层使用ul-refresh-wrapper——对应源码 ul-refresh.ts 中注册的hi-ul-refresh-wrapper原生RefreshWrapper与UlRefresh组件提供startRefresh()/refreshCompleted()等刷新生命周期方法。小结跨端支持与版本基线速查平台矩阵上述组件覆盖Android、iOS、Web-Renderer、Voltron部分如pull-*、waterfall系列面向Android/iOS/Voltron个别参数如supportedOrientations仅iOS、autoHideStatusBar仅Android具体以各参数/事件表格中的支持平台列为准waterfall-item的isHeader/isFooter额外支持 Ohos。版本基线waterfall/waterfall-item要求最低2.9.0cubic-bezier插值器2.9.0backgroundColor渐变色动画2.6.0start/end/repeat事件与动画方法2.5.2repeatCount: loop写法2.12.2actionsDidUpdate事件与collapsePullHeader(options)参数2.14.0。源码导航全部实现集中在 driver/js/packages/hippy-vue-native-components/srcindex.ts、animation.ts、dialog.ts、swiper.ts、pulls.ts、ul-refresh.ts、waterfall.ts可运行范例集中在 native-demos 目录两者对照阅读即可把文档参数落到具体实现上。掌握以上内容后你就可以在 Hippy-Vue 项目中用声明式模板驱动原生动画、弹窗、翻页与瀑布流交互并通过源码路径进一步验证每个参数在终端侧的真实行为。赞分享跨平台移动开发前端【免费下载链接】HippyHippy is designed to easily build cross-platform dynamic apps. 项目地址https://gitcode.com/gh_mirrors/hi/Hippy点击查看免费下载相关推荐Hippy hippy-vue 核心组件 API 详解div、ul、input、img 等标签到原生组件的映射、属性、事件与方法全解Hippy hippy vue 核心组件 API 详解div、ul、input、img 等标签到原生组件的映射、属性、事件与方法全解 本文基于 Hippy 官跨平台移动开发前端shadcn-vue Avatar 组件完整指南安装、源码解析与实战用法shadcn vue Avatar 组件完整指南安装、源码解析与实战用法 导读 Avatar头像是 shadcn vue 中表示用户身份的图片元素组件其UI组件前端Element UI Dialog 组件详解从基本用法到源码级实现原理Element UI Dialog 组件详解从基本用法到源码级实现原理 Dialog对话框是 Element 中用于在不离开当前页面的前提下向用户传递信息前端UI组件设计系统上一篇three.quarks物理效果开发重力、湍流与碰撞模拟下一篇掌握AG-UI命令模式的终极指南如何封装复杂操作实现高效AI协作创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考