nvue介绍 | uni-app

Expand All

# nvue介绍

The uni-app App has a built-in native rendering engine based on weex, which provides native rendering capabilities.

On the App side, if you use vue pages, use webview rendering; if you use nvue pages (abbreviation for native vue), use native rendering. Two kinds of pages can be used at the same time in an App. For example, the first page uses nvue, and the second page uses vue page. This is the case for the hello uni-app example.

Although nvue can also compile multi-terminally, output H5 and applet, but nvue's css writing is limited, so if you don't develop an app, you don't need to use nvue.

In the past, a big problem with weex was that it was only a high-performance renderer without sufficient API capabilities (such as various push sdk integration, Bluetooth and other capability calls), which made development very dependent on the collaboration of native engineers. Originally I wanted to save costs, but the result required front-end, iOS, and Android development, which was counterproductive. nvue solves this problem, allowing front-end engineers to directly develop complete apps, and provide a rich plug-in ecosystem and cloud packaging. These combined solutions help developers to effectively improve efficiency and reduce costs.

At the same time, uni-app extends many typeset capabilities of the weex native rendering engine and fixes many bugs. for example

Good support for border shadows on Android, Details
iOS supports Gaussian blur, details
It can realize the complex typesetting effect of area scrolling long list+left and right dragging list+ceiling
Optimize the rendering performance of border-radius
extended more css

# Applicable scene

The components and API of nvue are written in the same way as the vue page, and its built-in components are more than the built-in components of the vue page, see details.

If you are familiar with weex or react native development, then nvue is your better choice, which can effectively improve your development efficiency and reduce costs.

If you are a web front-end and are not familiar with native typesetting, it is recommended that you still use vue pages as the mainstay, and use nvue as a supplement in scenarios where some vue pages on the app side perform poorly. These scenarios are as follows:

Area long list or waterfall scrolling that requires high performance. The page-level long list scrolling of webview has no performance problems (that is, the scroll bar covers the overall height of the webview), but to scroll a long list in a certain area of the page, you need to use nvue's list, recycle-list, waterfall and other components (see details). The performance of these components is higher than the area scrolling component scroll-view in vue pages.
Complex and high-performance custom pull-down refresh. The native pull-down refresh can be configured in pages.json of uni-app, but the built-in pull-down refresh styles of the engine are only two styles: snowflake and circle. If you need to do complex pull-down refresh by yourself, it is recommended to use nvue's refresh component. Of course, there are many in Plugin Market The custom pull-down refresh plug-in under vue, as long as it is based on renderjs or wxs, the performance can also be commercialized, but the refresh component without nvue is more extreme.
Long list by dragging left and right. In webview, the long list of dragging left and right is realized through swiper+scroll-view, and the front-end simulates pull-down refresh. The performance of this scheme is not good. At this time, it is recommended to use nvue, such as the news sample template when creating a new uni-app project, and nvue is used, and the switching is very smooth.
Realize the complex typesetting effect of area scrolling long list + left and right dragging list + ceiling suction. For the effect, please refer to the swiper-list in the hello uni-app template. See details
If you want to change the button text in the lower right corner of the soft keyboard to "Send", you need to use nvue. For example, in the chat scene, in addition to the button word processing in the lower right corner of the soft keyboard, it also involves scrolling a long list in the chat record area, which is suitable for nvue.
Solve the level problem that front-end controls cannot cover native controls. When you use native components such as map, video, live-pusher, etc., you will find that the view and other components written in the front end cannot cover the native components, and it is more troublesome to deal with hierarchical problems. In this case, it is better to use nvue. Alternatively, a subnvue (a non-full-screen nvue page overlaid on a webview) can also be overlaid on the vue page to solve the problem of the native control level on the app. See details
If you deeply use the map component, it is recommended to use nvue. In addition to the level problem, the map function of the nvue file on the app side is more complete, the alignment with the applet is higher, and the multi-end consistency is better.
If you use video in depth, it is recommended to use nvue. For example, in the following two scenarios: video is embedded in swiper to realize Douyin-style video sliding switching. For example, see [Plugin Market](https://ext.dcloud.net.cn/search?q=%E4%BB% BF%E6%8A%96%E9%9F%B3); After the nvue video is full screen, the content is covered by cover-view, such as adding text titles and sharing buttons.
Live streaming: There is a live-pusher component under nvue, which is aligned with the applet, with more complete functions and no hierarchy problems.
Maximize the app startup speed. If the home page uses nvue and the fast mode is configured in the manifest on the App side, the startup speed of the App can be controlled in about 1 second. If you use the vue page, the startup speed of the app is generally 3 seconds, depending on your code performance and volume.

But note that in some scenarios, nvue is not as good as vue page, as follows:

canvas. The canvas performance of nvue is not high, especially the Android App platform, so this component is not built-in at all, but needs to be introduced separately. To manipulate canvas animations, the most performant way is to use the renderjs technology of the vue page, as is the case with the canvas example in the hello uni-app.
Dynamic horizontal and vertical screen. The CSS of the nvue page does not support media queries, so it is very difficult to dynamically switch between horizontal and vertical screens and dynamically adapt to the screen.

# Pure native rendering mode

On the App side, uni-app supports the mashup of vue pages and nvue pages, and jumps to each other. Pure nvue native rendering is also supported.

Enabling the pure native rendering mode can reduce the package size on the App side and reduce the memory usage during use. Because the related modules of the webview rendering mode will be removed.

Configure "renderer":"native" under "app-plus" in the manifest.json source view, which means that the pure native rendering mode is enabled on the App side. At this point, the vue page registered in pages.json will be ignored, and the vue component will also be rendered by the native rendering engine.

If this value is not specified, pure native rendering will not be started by default.

	// manifest.json
	{
	   // ...
		// App platform specific configuration
	   "app-plus": {
	   }
	}

# Compilation mode

weex build mode and uni-app build mode

If you are a weex developer before, you can continue to read this chapter, otherwise you can skip to the next section [Quick Start](#%E5%BF%AB%E9%80%9F%E4%B8%8A%E6%89 %8B).

Weex's components and JS API are different from uni-app. uni-app is the same as WeChat applet.

Considering the migration of weex users, uni-app also supports the code writing of weex. In manifest.json, you can configure to use weex compilation mode or uni-app compilation mode. When the weex compilation mode is selected, the uni-app components and jsapi will not be supported, and the developer needs to refer to the writing method of the weex official document to write the code. For example, weex compilation mode uses <div> . uni-app compilation mode uses <view> .

In general, it is recommended to use the uni-app mode, unless there is a lot of historical weex code and a gradual transition is required. At the same time, note that the switching of the weex compilation mode is project-level, and it is not supported to use the weex mode for one nvue page under the same project, and the uni-app mode for another nvue page.

	weex compilation mode	uni-app compilation mode
Platform	App only	All terminals, including Mini Programs and H5
Components	Weex components such as div	uni-app components such as view
JS API	weex API、uni API、Plus API	weex API、uni API、Plus API
Units	750px is the screen width, wx is the fixed pixel unit	750rpx is the screen width, px is the fixed pixel unit
Global style	Manual introduction	The style of app.vue is the global style
page scrolling	must be given to page sets or components	default support for page scrolling

Modify 2 compilation modes in manifest.json, manifest.json -> app-plus -> nvueCompiler to switch the compilation mode.

nvueCompiler has two values:

weex
uni-app

	// manifest.json
	{
		// ...
		// App platform specific configuration
		"app-plus": {
		}
	}

In the manifest.json configuration file, before HBuilderX2.4, the default value is weex mode, and the default value of HBuilderX2.4+ version is changed to uni-app mode.

Weex compilation mode does not support the writing of onNavigationBarButtonTap life cycle function. To monitor native title bar button click events in nvue, see: uni.onNavigationBarButtonTap.

The weex compilation mode does not support the onShow life cycle, but if you are familiar with 5+, you can use the addEventListener show event of listening to the webview to achieve the onShow effect.

weex compilation mode does not support vuex.

Unlike weex, the page jump of nvue still follows the routing model of uni-app. The model is followed no matter how you jump between vue page and nvue page. Including nvue page jumping to nvue page. Each page needs to be registered in pages.json and call uni-app's route API to jump.

Native development does not have the concept of page scrolling. When the page content is higher than the screen height, the content will not scroll automatically; only the content of the page is placed under the components of list, waterfall, scroll-view/scroller to scroll. This is not in line with the habit of front-end development, so when nvue is compiled into uni-app mode, the uni-app framework will automatically nest a scroller outside the nvue page, so as to achieve automatic scrolling of page content.

Notice:

The uni-app framework only nests the scroller container for nvue pages, and does not automatically nest the scroller container for components;
If the nvue page has the recycle-list component, the uni-app framework will not automatically nest the scroller container for the page
If you don't want to automatically nest the scroller container, you can turn it off in pages.json with the following configuration:

{
    "path": "",
    "style": {
    }
}

Weex ui is supported in weex compilation mode, for example see details. However, compared to the uni-app plugin market and the official uni ui, the component ecology of weex syntax is still relatively lacking.

From HBuilderX 3.1.0+, new style compilation mode is supported

weex compilation mode: the old mode, with the same style support as ordinary weex
uni-app compilation mode: a new mode, which supports combination selectors (adjacent brother selector, common brother selector, child selector and descendant selector) based on the original weex style. See details

  // manifest.json
  {
      // ...
      // App platform specific configuration
      "app-plus":  {
          "nvueStyleCompiler": "uni-app"
      }
  }

# Quick Start

# 1. Create a new nvue page

In the uni-app project of HBuilderX, create a new page, and in the upper right corner of the pop-up interface, you can choose whether to build a vue page or a nvue page, or two at the same time.

Whether it is a vue page or an nvue page, it needs to be registered in pages.json. If you create a new page in HBuilderX, it will be automatically registered. If you use other editors, you need to register it in pages.json by yourself.

If there is both a vue page and an nvue page under a page route, the vue and nvue files with the same name will appear. Then on the App side, only the nvue page will be used, and the vue file with the same name will not be compiled to the App side. On the non-App side, the vue page will be used first.

If the name is different, only the nvue page, on the non-app side, only the nvue file in the uni-app compilation mode will be compiled.

# 2. Develop nvue page

nvue page structure is the same as vue, which consists of template, style, script.

template: Template writing and data binding are the same as vue. The component supports 2 modes,
- weex component, the same as weex writing, reference: weex built-in components;
- uni-app component, same as uni-app.
- App-side nvue-specific components, see https://uniapp.dcloud.io/component/barcode.
style: Due to the native rendering, not all browsers' css support, the layout model only supports flex layout, although it will not cause some interface layouts to be impossible to achieve, but you should pay attention to the writing method. See: style
script: written in the same way as vue, and supports 3 APIs:
- uni API：https://uniapp.dcloud.io/api/README
- plus API: only supports the App side. http://www.html5plus.org/doc/h5p.html

# 3. Debugging nvue page

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

# render-whole

Starting from HBuilder X 3.1.0, nvue adds a render-whole property, of type Boolean.

When render-whole="true" is set, the view layer communicates the information structure of components and sub-components with the native layer at one time, and improves the layout rendering performance by redrawing the entire node.
When set render-whole="false", the view layer will communicate with the native layer one by one with child nodes and then redraw. The overall render time may be longer.

Enable render-whole as a component list of true by default

text
cell
header
cell-slot
recycle-list

Usage

<swiper :render-whole="true"></swiper>

Demo

The effect of this demo on Android 5.1 version mobile phones, the effect of high version mobile phones is not so obvious

示例工程点击下载

# Common differences between nvue development and vue development

Rendering based on native engine is still a front-end technology stack, but it is definitely different from web development.

nvue page control display and hide can only use v-if but not v-show
The nvue page only supports the flex layout and does not support any other layout methods. Before developing the page, you should first figure out what the vertical content of this page is and which contents are to be scrolled, then what is the horizontal axis arrangement of each vertical content, and design the interface according to flex layout.
The default layout direction of the nvue page is vertical (column). If you need to change the layout direction, you can modify it under the node manifest.json -> app-plus -> nvue -> flex-direction, which only takes effect in uni-app mode. Details.
When the nvue page is compiled into H5 and applet, it will do a work of aligning the default css values. Because the weex rendering engine only supports flex, and the default flex direction is vertical. The H5 and applet side, using web rendering, is not flex by default, and after setting display:flex, its flex direction is horizontal instead of vertical by default. Therefore, when nvue is compiled into H5 and applet, it will automatically set the default layout of the page to flex and the direction to be vertical. Of course, the default settings will be overwritten by the developer after manual settings.
The text content must and can only be under the <text> component. You cannot write text directly in the text area of <div> and <view>. Otherwise, even if rendered, the variables in js cannot be bound.
Only the text tag can set the font size and font color.
Layout cannot use percentage and there is no media query.
nvue 切换横竖屏时可能导致样式出现问题，建议有 nvue 的页面锁定手机方向。
支持的css有限，不过并不影响布局出你需要的界面，flex还是非常强大的。详见
不支持背景图。但可以使用image组件和层级来实现类似web中的背景效果。因为原生开发本身也没有web这种背景图概念
css选择器支持的比较少，只能使用 class 选择器。详见
Each component of nvue is transparent by default on the Android side. If background-color is not set, ghosting problems may occur.
class only supports array syntax when binding.
Using a large number of border-radius in a page of the Android side will cause performance problems, especially if the styles of multiple borders are not the same, which will consume more performance. Such use should be avoided.
The nvue page does not have the bounce rebound effect, only a few list components have the bounce effect, including list, recycle-list, and waterfall.
There is no concept of page scrolling in native development. The page content will not scroll automatically if it is higher than the screen height. Only some components can be scrolled (list, waterfall, scroll-view /scroller), the content to be scrolled needs to be wrapped under the scrollable component. This is not in line with the habit of front-end development, so when nvue is compiled into uni-app mode, a scroller is automatically placed on the outer layer of the page, and the page content is too high and it will scroll automatically. (The component will not be nested, and the page will not be nested when there is a recycle-list). The configuration will be provided later, and it can be set to not automatically set.
The global js variables defined in App.vue will not take effect on the nvue page. globalData and vuex are effective.
App.vue 中定义的全局css，对nvue和vue页面同时生效。如果全局css中有些css在nvue下不支持，编译时控制台会报警，建议把这些不支持的css包裹在条件编译里，APP-PLUS-NVUE
不能在 style 中引入字体文件，nvue 中字体图标的使用参考：加载自定义字体。如果是本地字体，可以用plus.io的API转换路径。
typescript/ts is currently not supported on the nvue page.
When the native navigation bar is closed on the nvue page, if you want to simulate the status bar, you can refer to the article. However, it is still strongly recommended to use native navigation bar on nvue pages. However fast nvue rendering is, it will not be as fast as the native navigation bar. Native typesetting engine analysisjson. It takes little time to draw the native navigation bar, but it takes much longer to draw the whole page by analyzing the js of nvue, especially when the new page enters the animation period. For complex pages, there is no native navigation bar that will generate the white screen or splash screen of the whole screen during the animation period.

# iOS platform drop-down component refresh component attention

By default on the iOS platform, when the content of the scrolling container components (such as list, waterfall components) is insufficient, it will not be able to scroll up and down because the visible area of the container is not full. At this time, the pull-down refresh function cannot be operated, and refresh cannot be triggered. Component's @refresh, @pullingdownevents. At this time, you can configure thealwaysScrollableVerticalproperty value oftrue` in the container component to set support for up and down scrolling and support for pull-down refresh operations.

# Usage

<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>