uni-app H5端使用注意事项 【跨端开发系列】

 

 🔗 uniapp 跨端开发系列文章：🎀🎀🎀

1. uni-app 组成和跨端原理    【跨端开发系列】 
2. uni-app 各端差异注意事项 【跨端开发系列】
3. uni-app 离线本地存储方案 【跨端开发系列】
4. uni-app UI库、框架、组件选型指南 【跨端开发系列】
5. uni-app 蓝牙开发 【特别专题】
6. uni-app 导航栏开发指南 【跨端开发系列】
7. uni-app 原生控件层级过高无法覆盖的解决方案 【跨端开发系列】
8. uni-app 设置缓存过期时间【跨端开发系列】

---

一、介绍 🎯

uni-app 是一个使用 Vue.js 开发所有前端应用的框架，开发者编写一套代码，可发布到iOS、Android、Web（响应式）、以及各种小程序（微信/支付宝/百度/头条/飞书/QQ/快手/钉钉/淘宝）、快应用等多个平台。

uni-app在开发者数量、案例、跨端抹平度、扩展灵活性、性能体验、周边生态、学习成本、开发成本等8大关键指标上拥有更强的优势。

​

二、功能框架图 📋

从下面 uni-app 功能框架图可看出， uni-app 在跨平台的过程中，不牺牲平台特色，可优雅的调用平台专有能力，真正做到海纳百川、各取所长。

​

三、使用方式 📖

1. 打开 uni-app 项目下的 vue 文件。
2. 点击 菜单 运行-> 运行到浏览器 -> Chrome 。
3. 在 Chrome 內打开 调试模式（右键->检查）开启 设备模拟 ，模拟移动设备 。
4. HBuilderX 修改代码后会自动刷新 chrome 的页面。
5. 审查元素，每个页面都在 page 节点下，pageHead 是 微信 和 app 下的原生导航栏，即   pages.json 里配的导航栏。pageBody 是导航栏下的页面内容。所有标签为了避免和标准H5标签冲突，都加了 U前缀 。
6. 断点 debug ，点 chrome 控制台的 source ，可以给 js 打断点调试。
   找到同名的文件，如果没有同名 vue 文件，一般会有一个同文件名的 js 文件，此时会提示检测到 sourcemap ，是否引入，点允许。然后就会有同名的 vue 文件。如果找不到，则把焦点放到 source 的代码区，然后敲 ctrl+p 打开文件查找窗口，然后敲入 vue 页面名字，然后打开 vue 页面。这个 vue 里，只有 js，没有 tag 和 css  ，但可以打断点 调试。

四、发布方式📤

1. 配置发行后的路径（发行在网站 根目录 可不配置），比如发行网站路径是www.xxx.com/html5，在 manifest.json 可视化界面 - H5配置 - 运行的基础路径中设置，也可以在源码视图内编辑 h5 节点， router 下增加 base 属性为 html5 。可视化界面设置：

源码视图设置：

1. 点击菜单 发行 -> H5 。
2. 在当下项目下的 unpackage/dist/build/h5 目录找到出的资源，部署服务器（或者使用本地服务器预览，不要直接在浏览器打开html文件）。如果发布使用的 history 模式，需要服务端配合，参考：后端配置方式。

五、跨端注意🪡

uni-app由 uni 的通用 api 和平台专有 api 组成，H5版也不例外。可以使用 uni 的通用 api 完成很多工作，也可以在条件编译里调用 H5版 的浏览器专有api。

• 🚫虽然 dom、window 都可以用了，但如果要跨端，还是少写这样的代码好。
• 🚫强烈不建议使用浏览器的跳转页面的api 。
• ✅H5仍应该使用 pages.json 管理页面。
• ✅H5的 条件编译 写法是把之前的 app-plus 换成 H5 。敲 ifdef 会有代码助手提示。

//#ifdef H5  
this.titleHeight = 44  
//#endif

🔸条件编译目前有 7 个平台，APP-PLUS、APP-PLUS-NVUE、MP-WEIXIN、H5、MP、MP-BAIDU、MP-ALIPAY。

🔸其中 APP-PLUS-NVUE 是 APP-PLUS 的子集，用于 weex 下单独写专用代码。
为了方便多平台选择，还引入了 ~#ifndef~ ，也就是 ifdef 的 not ，反向选择。以及或语法，及||。

🔸这些命名都是c语言条件编译的标准命名。

// #ifndef H5  
console.log("这段代码编译到非H5平台");  
// #endif

开发者之前为微信或 app 写的代码，H5的平台不支持时，需要注意把这些代码放到条件编译里。
经过这样的处理，之前做好的App或小程序才能正常运行到H5版里。

小程序版在UI上，尤其是导航栏上限制较多，H5在这里是参考了app，默认解析了pages.json下的app-plus的节点，实现了titleNView、buttons、下拉刷新（下拉刷新只有circle方式，因为只有这样的下拉刷新在H5版上可以保障流畅体验）

六、组件和API支持情况✅

目前的H5版，还没有100%实现uni的所有api，但大部分已经完成，具体参考uniapp文档。

七、第三方组件支持 ✅

• 支持 mpvue 组件
• 支持普通 vue 组件（仅H5平台）
• 支持 微信小程序 组件（HBuilderX2.5.0+开始支持编译到H5）
• 支持 nvue

八、vue语法支持 ✅

H5版支持完整的vue语法，同时校验器也校验了更严格的vue语法，有些写法不规范会报警。比如data后面写对象会报警，必须写 function 。

九、注意事项（必看）🔎

• 编译为H5版后生成的是单页应用，SPA。如果想要 seo 优化，首页可以在 template模板 中配置 keyword 。二级页不支持配置。但一个更酷的方式是用 uni-app 直接发布一版百度小程序，搜索权重更高。
• 编译后看日志和错误，要看浏览器的控制台，而不是HBuilderX的控制台。浏览器的控制台会有错误提示。
• 网络请求（request、uploadFile、downloadFile等）在浏览器存在跨域限制（CORS、Cross-Origin），解决方案详见：uni-app H5跨域问题解决方案（CORS、Cross-Origin） - DCloud问答
• APP 和 微信 的 原生导航栏 和 tabbar 下，元素区域坐标是不包含 原生导航栏 和 tabbar 的。而 H5 里 原生导航栏 和 tabbar 是 div 模拟实现的，所以元素坐标会包含 导航栏 和 tabbar 的高度。为了优雅的解决 多端 高度定位 问题，uni-app 新增了2个 css 变量： --window-top 和   --window-bottom ，这代表了页面的内容区域距离顶部和底部的距离。举个实例，如果你想在原生 tabbar 上方悬浮一个菜单，之前写 bottom:0 。这样的写法编译到 h5 后，这个菜单会和tabbar 重叠，位于屏幕底部。而改为使用 bottom:var(--window-bottom)，则不管在app下还是在h5下，这个菜单都是悬浮在 tabbar 上浮的。这就避免了写条件编译代码。当然你也仍然可以使用 H5 的条件编译处理界面的不同。
• CSS內使用 vh 单位的时候注意 100vh 包含导航栏，使用时需要减去 导航栏 和 tabBar 高度，部分浏览器还包含浏览器操作栏高度，使用时请注意。
• event 对象上使用的 mpvue 独有的属性需调整（比如 event.pageY，可能需要加上44px的导航栏高度）。
• fixed 定位的组件有可能遮挡框架内置UI组件，如果不希望遮挡可以分平台判断，在H5平台避开内置UI。
• 正常支持 rpx 。px是真实物理像素。🚫暂不支持通过设 manifest 的 "transformPx" : true ，把px当动态单位使用。
• 使用 罗盘、地理位置、加速计 等相关接口需要使用 https 协议，本地预览（localhost）可以使用 http 协议。
• PC 端 Chrome 浏览器模拟器设备测试的时候，获取定位 API 需要连接谷歌服务器，需要翻墙。
• 组件内（页面除外）🚫不支持 onLoad 生命周期。
• 为 避免 和内置 组件冲突，自定义组件请 加上前缀（但不能是 u 和 uni ）。比如可使用的自定义组件名称：my-view、m-input、we-icon，🚫例如不可使用的自定义组件名称：u-view、uni-input。如果已有项目使用了可能造成冲突的名称，请修改名称。另外 微信小程序 下自定义组件名称 不能以wx 开头。
• 在 tabBar 页面，如果 page 高度设置为100%时，页面超出滚动会导致底部被 tabbar 遮挡，可在 tabbar 页面 去掉 height:100% 或者改用 min-height:100% 。
• 编写组件时需要遵守vue的规范，之前在app端和小程序端能使用的一些不规范写法需要纠正，比如：🚫不要修改 props 的值、🚫组件最外层 template 节点下不允许包含多个节点。
• 开发App时，🚫不可在H5预览后直接云打包。需在HBuilderX里点运行-选择运行到手机，真机调试无误后再打包。
• H5端 “网络不给力” 原因及解决办法：https://ask.dcloud.net.cn/article/37065。

---

   🔗 uniapp 跨端开发系列文章：🎀🎀🎀

1. uni-app 组成和跨端原理    【跨端开发系列】 
2. uni-app 各端差异注意事项 【跨端开发系列】
3. uni-app 离线本地存储方案 【跨端开发系列】
4. uni-app UI库、框架、组件选型指南 【跨端开发系列】
5. uni-app 蓝牙开发 【特别专题】
6. uni-app 导航栏开发指南 【跨端开发系列】
7. uni-app 原生控件层级过高无法覆盖的解决方案 【跨端开发系列】
8. uni-app 设置缓存过期时间【跨端开发系列】