大家好，我是鱼樱！！！

关注公众号【鱼樱AI实验室】持续分享更多前端和AI辅助前端编码新知识~~

不定时写点笔记写点生活~写点前端经验。

在当前环境下，纯前端开发者可以通过技术深化、横向扩展、切入新兴领域（MCP TOOLS AI应用产品方向 等）以及产品化思维找到突破口。（不管写多久的代码，技术深度广度如何一定要具备独立赚钱的能力呀！！老铁们，因为总有一天你不在职场总有一天会面对选择和职场的无情）

著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

前端最卷的开发语言一点不为过，三天一小更，五天一大更。。。一年一个框架升级~=嗯，要的就是这样感觉！与时俱进~ 接下来会逐步分享uni-app的一些开发经验。从文档到基础到实战以及遇到的问题~时间节点不限。

最近依旧比较忙，技术文章还是会不定时更新一些核心的技术分享，和大家一起学习前端路程。

前言须知

uni-app App 端内置了一个基于 weex 改进的原生渲染引擎，提供了原生渲染能力，在 App 端，如果使用 vue 页面，则使用 webview 渲染；如果使用 nvue 页面(native vue 的缩写)，则使用原生渲染。一个 App 中可以同时使用两种页面，比如首页使用 nvue，二级页使用 vue 页面

虽然 nvue 也可以多端编译，输出 H5 和小程序，但 nvue 的 css 写法受限，所以如果你不开发 App，那么不需要使用 nvue

nvue 的组件和 API 写法与 vue 页面一致

如果你熟悉 weex 或 react native 开发，那么 nvue 是你的更优选择，能切实提升你的开发效率，降低成本

如果你是 web 前端，不熟悉原生排版，那么建议你仍然以使用 vue 页面为主，在 App 端某些 vue 页面表现不佳的场景下使用 nvue 作为强化补充。

uni-app 在 App 端，支持 vue 页面和 nvue 页面混搭、互相跳转。也支持纯 nvue 原生渲染。

启用纯原生渲染模式，可以减少 App 端的包体积、减少使用时的内存占用。因为 webview 渲染模式的相关模块将被移除。

在 manifest.json 源码视图的"app-plus"下配置"renderer":"native"，即代表 App 端启用纯原生渲染模式。此时 pages.json 注册的 vue 页面将被忽略，vue 组件也将被原生渲染引擎来渲染。

如果不指定该值，默认是不启动纯原生渲染的。

// manifest.json
{
   // ...
// App平台特有配置
   "app-plus": {
      "renderer": "native", //App端纯原生渲染模式
   }
}

编译模式

weex 编译模式和 uni-app 编译模式（推荐）

weex 的组件和 JS API，与 uni-app 不同。uni-app 与微信小程序相同 主要介绍 uni-app 方式 weex自行了解

在 manifest.json 中修改 2 种编译模式，manifest.json -> app-plus -> nvueCompiler 切换编译模式。 nvueCompiler 有两个值：

• weex
• uni-app

// manifest.json
{
// ...
// App平台特有配置
"app-plus": {
"nvueCompiler":"uni-app" //是否启用 uni-app 模式
}
}

原生开发没有页面滚动的概念，页面内容高过屏幕高度时，内容并不会自动滚动；只有将页面内容放在list、waterfall、scroll-view/scroller这几个组件下内容才可滚动。这不符合前端开发的习惯，所以在 nvue 编译为 uni-app模式时，uni-app框架会给 nvue 页面外层自动嵌套一个 scroller，从而实现页面内容的自动滚动。

注意：

• uni-app框架仅对 nvue 页面嵌套scroller容器，不会给组件自动套scroller容器；
• 若 nvue 页面有recycle-list组件时，uni-app框架也不会自动给页面嵌套scroller容器
• 若你不希望自动嵌套scroller容器，可在pages.json中通过如下配置进行关闭：

{
    "path": "",
    "style": {
        "disableScroll": true // 不嵌套 scroller
    }
}

HBuilderX 3.1.0+ 开始支持新的样式编译模式

• weex 编译模式：老模式，样式支持与普通 weex 相同
• uni-app 编译模式：新模式，在 weex 原有样式基础上支持组合选择器（相邻兄弟选择器、普通兄弟选择器、子选择器、后代选择器）详见

  // manifest.json
  {
      // ...
      // App平台特有配置
      "app-plus":  {
          "nvueStyleCompiler": "uni-app"
      }
  }

快速上手

在 HBuilderX 的 uni-app 项目中，新建页面，弹出界面右上角可以选择是建立vue页面还是nvue页面，或者 2 个同时建

不管是 vue 页面还是 nvue 页面，都需要在pages.json中注册。如果在 HBuilderX 中新建页面是会自动注册的，如果使用其他编辑器，则需要自行在 pages.json 里注册。

如果一个页面路由下同时有 vue 页面和 nvue 页面，即出现同名的 vue 和 nvue 文件。那么在 App 端，会仅使用 nvue 页面，同名的 vue 文件将不会被编译到 App 端。而在非 App 端，会优先使用 vue 页面。

如果不同名，只有 nvue 页面，则在非 app 端，只有 uni-app 编译模式的 nvue 文件才会编译。

开发 nvue 页面需注意

nvue 页面结构同 vue, 由 template、style、script 构成。

• template： 模板写法、数据绑定同 vue。组件支持 2 种模式，

  • uni-app 组件，同 uni-app 写法。
  • App 端 nvue 专用组件，详见uniapp.dcloud.io/component/b…。

• style：由于采用原生渲染，并非所有浏览器的 css 均支持，布局模型只支持 flex 布局，虽然不会造成某些界面布局无法实现，但写法要注意。详见：样式

• script：写法同 vue，并支持 3 种 API：

  • nvue API ：仅支持 App 端，uni-app 编译模式也可使用。使用前需先引入对应模块，参考：模块引入 API
  • uni API：uniapp.dcloud.io/api/README
  • plus API：仅支持 App 端。www.html5plus.org/doc/h5p.htm…

调试 nvue 页面

HBuilderX 内置了 weex 调试工具的强化版，包括审查界面元素、看 log、debug 打断点，详见

注意事项

• vue 和 nvue 页面均支持断点调试
• 目前仅支持 nvue 页面审查元素，vue 页面暂不支持，以及 Android 平台的 nvue 审查元素暂不支持查看 style
• App 端提供真机运行的console.log日志输出，运行到真机或模拟器时，不用点debug按钮，运行手机 App，会在HBuilderX的控制台直接输出日志。
• 如果是调试App的界面和常规 API，推荐编译到 H5 端，点HBuilderX右上角的预览，在内置浏览器里调Dom，保存后立即看到结果，调试更方便。并且 H5 端也支持titleNView的各种复杂设置。唯一要注意的就是css兼容性，使用太新的css在pc上预览可能正常，但低端Android上异常，具体可查询caniuse等网站。
• 常用的开发模式就是pc上使用内置浏览器预览调 dom，运行到真机上看console.log。如果是很复杂的问题才使用debug。
• uni-app 的 App 端的 webkit remote debug，只能调试视图层，不能调试逻辑层。因为 uni-app 的 js 不是运行在 webview 里，而是独立的 jscore 里。
• 部分 manifest 配置，如三方 sdk 配置，需要打包后生效的，可以打包一个自定义运行基座。打包自定义基座后运行这个自定义基座，同样可以真机运行和 debug。打包正式包将无法真机运行和 debug。
• 调试依赖 chrome 安装位置，找不到可能会导致调试报错。社区反馈中有用户主动修改了 chrome 的安装位置，导致内置的 puppeteer 查找 chrome失败，如果你修改了 chrome 的安装位置，请参考 《HBuilderX APP端 uni/nvue 调试报错问题》

nvue开发与vue开发的常见区别

1. nvue 页面控制显隐只可以使用v-if不可以使用v-show
2. nvue 页面只能使用flex布局，不支持其他布局方式。页面开发前，首先想清楚这个页面的纵向内容有什么，哪些是要滚动的，然后每个纵向内容的横轴排布有什么，按 flex 布局设计好界面。
3. nvue 页面的布局排列方向默认为竖排（column），如需改变布局方向，可以在 manifest.json -> app-plus -> nvue -> flex-direction 节点下修改，仅在 uni-app 模式下生效。详情。
4. nvue页面编译为H5、小程序时，会做一件css默认值对齐的工作。因为weex渲染引擎只支持flex，并且默认flex方向是垂直。而H5和小程序端，使用web渲染，默认不是flex，并且设置display:flex后，它的flex方向默认是水平而不是垂直的。所以nvue编译为H5、小程序时，会自动把页面默认布局设为flex、方向为垂直。当然开发者手动设置后会覆盖默认设置。
5. 文字内容，必须、只能在<text>组件下。不能在<div>、<view>的text区域里直接写文字。否则即使渲染了，也无法绑定js里的变量。
6. 只有text标签可以设置字体大小，字体颜色。
7. 布局不能使用百分比、没有媒体查询。
8. nvue 切换横竖屏时可能导致样式出现问题，建议有 nvue 的页面锁定手机方向。
9. 支持的css有限，不过并不影响布局出你需要的界面，flex还是非常强大的。详见
10. 不支持背景图。但可以使用image组件和层级来实现类似web中的背景效果。因为原生开发本身也没有web这种背景图概念
11. css选择器支持的比较少，只能使用 class 选择器。详见
12. nvue 的各组件在安卓端默认是透明的，如果不设置background-color，可能会导致出现重影的问题。
13. class 进行绑定时只支持数组语法。
14. Android端在一个页面内使用大量圆角边框会造成性能问题，尤其是多个角的样式还不一样的话更耗费性能。应避免这类使用。
15. nvue页面没有bounce回弹效果，只有几个列表组件有bounce效果，包括 list、recycle-list、waterfall。
16. 原生开发没有页面滚动的概念，页面内容高过屏幕高度并不会自动滚动，只有部分组件可滚动（list、waterfall、scroll-view/scroller），要滚的内容需要套在可滚动组件下。这不符合前端开发的习惯，所以在 nvue 编译为 uni-app模式时，给页面外层自动套了一个 scroller，页面内容过高会自动滚动。（组件不会套，页面有recycle-list时也不会套）。后续会提供配置，可以设置不自动套。
17. 在 App.vue 中定义的全局js变量不会在 nvue 页面生效。globalData和vuex是生效的。
18. App.vue 中定义的全局css，对nvue和vue页面同时生效。如果全局css中有些css在nvue下不支持，编译时控制台会报警，建议把这些不支持的css包裹在条件编译里，APP-PLUS-NVUE
19. 不能在 style 中引入字体文件，nvue 中字体图标的使用参考：加载自定义字体。如果是本地字体，可以用plus.io的API转换路径。
20. 目前不支持在 nvue 页面使用 typescript/ts。 21. nvue 页面关闭原生导航栏时，想要模拟状态栏，可以参考文章。但是，仍然强烈建议在nvue页面使用原生导航栏。nvue的渲染速度再快，也没有原生导航栏快。原生排版引擎解析json绘制原生导航栏耗时很少，而解析nvue的js绘制整个页面的耗时要大的多，尤其在新页面进入动画期间，对于复杂页面，没有原生导航栏会在动画期间产生整个屏幕的白屏或闪屏。

iOS 平台下拉组件 refresh 组件注意问题

iOS 平台默认情况下滚动容器组件（如list、waterfall组件）内容不足时，由于没有撑满容器的可视区域会导致无法上下滚动，此时无法操作下拉刷新功能，无法触发refresh组件的@refresh、@pullingdown事件。 此时可在容器组件中配置alwaysScrollableVertical属性值为true来设置支持上下滚动，支持下拉刷新操作。

Android 平台不存在此问题

用法

<list class="scroll-v list" enableBackToTop="true" scroll-y alwaysScrollableVertical="true">
<refresh class="refresh" @refresh="onrefresh()" @pullingdown="onpullingdown">
<!-- refresh content -->
</refresh>
<cell v-for="(newsitem,index) in list" :key="newsitem.id">
<!-- cell content -->
</cell>
</list>

HTML5+ 能力

uni-app App 端内置 HTML5+ 引擎，让 js 可以直接调用丰富的原生能力

条件编译调用 HTML5+

小程序及 H5 等平台是没有 HTML5+ 扩展规范的，因此在 uni-app 调用 HTML5+ 的扩展规范时，需要注意使用条件编译。否则运行到h5、小程序等平台会出现 plus is not defined错误。

// #ifdef APP-PLUS
var appid = plus.runtime.appid;
console.log('应用的 appid 为：' + appid);
// #endif

uni-app不需要 plus ready

在html中使用plus的api，需要等待plus ready。 而uni-app不需要等，可以直接使用。而且如果你调用plus ready，反而不会触发。

uni-app 中的事件监听

在普通的 H5+ 项目中，需要使用 document.addEventListener 监听原生扩展的事件。

uni-app 中，没有 document。可以使用 plus.globalEvent.addEventListener 来实现。

// #ifdef APP-PLUS
// 监听新意图事件
plus.globalEvent.addEventListener('newintent', function(){});
// #endif

复制代码

同理，在 uni-app 中使用 Native.js 时，一些 Native.js 中对于原生事件的监听同样需要按照上面的方法去实现。

Native.js 能力

Native.js技术，简称NJS，是一种将手机操作系统的原生对象转义，映射为JS对象，在JS里编写原生代码的技术。 如果说Node.js把js扩展到服务器世界，那么Native.js则把js扩展到手机App的原生世界。 HTML/JS/Css全部语法只有7万多，而原生语法有几十万，Native.js大幅提升了HTML5的能力。 NJS突破了浏览器的功能限制，也不再需要像Hybrid那样由原生语言开发插件才能补足浏览器欠缺的功能。 NJS编写的代码，最终需要在HBuilder里打包发行为App安装包，或者在支持Native.js技术的浏览器里运行。目前Native.js技术不能在普通手机浏览器里直接运行。

• NJS大幅扩展了HTML5的能力范围，原本只有原生或Hybrid App的原生插件才能实现的功能如今可以使用JS实现。
• NJS大幅提升了App开发效率，将iOS、Android、Web的3个工程师组队才能完成的App，变为1个web工程师就搞定。
• NJS不再需要配置原生开发和编译环境，调试、打包均在HBuilder里进行。没有mac和xcode一样可以开发iOS应用。
• 如果不熟悉原生API也没关系，我们汇总了很多NJS的代码示例，复制粘贴就可以用。ask.dcloud.net.cn/article/114

再次强调，Native.js不是一个js库，不需要下载引入到页面的script中，也不像nodejs那样有单独的运行环境，Native.js的运行环境是集成在5+runtime里的，使用HBuilder打包的app或流应用都可以直接使用Native.js。

注意事项：

• Uni-app不支持Native.js执行UI相关操作的API调用及webview相关API调用。将失效无法正常使用。Uni-app不推荐使用Native.js

• Native API具有平台依赖性，所以需要通过以下方式判断当前的运行平台

function judgePlatform(){
switch ( plus.os.name ) {
case "Android":
// Android平台: plus.android.*
break;
case "iOS":
// iOS平台: plus.ios.*
break;
default:
// 其它平台
break;
}
}

• 在NJS中调用Native API或从Native API返回数据到NJS时会自动转换数据类型

技术要求

由于NJS是直接调用Native API，需要对Native API有一定了解，知道所需要的功能调用了哪些原生API，能看懂原生代码并参考原生代码修改为JS代码。 否则只能直接copy别人写好的NJS代码。

renderjs能力

renderjs是一个运行在视图层的js。它比WXS更加强大。它只支持app-vue和web。

renderjs的主要作用有2个：

1. 大幅降低逻辑层和视图层的通讯损耗，提供高性能视图交互能力
2. 在视图层操作dom，运行 for web 的 js库

• nvue的视图层是原生的，无法运行js。但提供了bindingx技术来解决通信阻塞。详见
• 微信小程序下替代方案是wxs，这是微信提供的一个裁剪版renderjs。详见
• web下不存在逻辑层和视图层的通信阻塞，也可以直接操作dom，所以在web端使用renderjs主要是为了跨端复用代码。如果只开发web端，没有必要使用renderjs。

<script module="test" lang="renderjs">
export default {
mounted() {
// ...
},
methods: {
// ...
}
}
</script>

过去的问题

• H5端流行的echart报表因为涉及大量dom操作，无法跨端使用
• wx-chart在跨端和更新方面都不足
• 插件市场提供了比wx-chart更好的、全端可用的uChart。但受限于小程序架构逻辑层和视图层分离，导致的通信折损，图表的动画性能不佳。并且uchart只实现了echart的常用功能，还有一些功能没有实现。

新的解决方案

从uni-app 2.5.5+起，新提供了renderjs技术。它是wxs的升级版，一种可以运行在视图层的js。

通过renderjs编写的代码，直接运行在视图层（也就是webview中），可以完整的运行echart等库，并且没有了逻辑层和视图层频繁通行的折损，让动画不再卡顿。

renderjs支持app-vue和h5，不支持其他平台。如果你只考虑这2个平台，可以直接使用本示例，使用完整版的echart。如果还要兼容多端小程序，建议仍然使用uchart。

renderjs，不止能运行echart，其他如F2、threejs等web库都可以运行。

renderjs使用注意事项

• 目前仅支持内联使用。
• 不要直接引用大型类库，推荐通过动态创建 script 方式引用。
• 可以使用 vue 组件的生命周期(不支持 beforeDestroy、destroyed、beforeUnmount、unmounted)，不可以使用 App、Page 的生命周期
• 视图层和逻辑层通讯方式与 WXS 一致，另外可以通过 this.$ownerInstance 获取当前组件的 ComponentDescriptor 实例。
• this.$ownerInstance.callMethod() 仅支持调用逻辑层vue选项式中的 methods 中定义的方法。
• 注意逻辑层给数据时最好一次性给到渲染层，而不是不停从逻辑层向渲染层发消息，那样还是会产生逻辑层和视图层的多次通信，还是会卡
• 观测更新的数据在视图层可以直接访问到。
• APP 端视图层的页面引用资源的路径相对于根目录计算，例如：./static/test.js。
• APP 端可以使用 dom、bom API，不可直接访问逻辑层数据，不可以使用 uni 相关接口（如：uni.request）
• H5 端逻辑层和视图层实际运行在同一个环境中，相当于使用 mixin 方式，可以直接访问逻辑层数据。
• vue3 项目不支持 setup script 用法。

APP 离线 SDK

App离线开发工具包，即App离线SDK，是把App运行环境（runtime）封装为原生开发调用接口，开发者可以在自己的 Android 及 iOS 原生开发环境配置工程使用，包括 Android离线开发SDK 及 iOS离线开发SDK。

注意：本SDK仅限于uni-app项目使用

• Android 离线SDK-正式版 nativesupport.dcloud.net.cn/AppDocs/dow…
• iOS 离线SDK - 正式版 nativesupport.dcloud.net.cn/AppDocs/dow…
• AppKey申请配置 nativesupport.dcloud.net.cn/AppDocs/use…