This page is translated by Google Cloud Translation API

Switch to Chinese

pages.json 页面路由

The pages.json file is used to configure uni-app globally, to determine the path of the page file, window style, native navigation bar, native tabbar at the bottom, etc.

It is similar to the page management part of app.json in the WeChat MiniApp. Note that the application for location permissions and other content that originally belonged to app.json are configured in the manifest in uni-app.

Configuration item list

Attribute	Type	Required	Description	Platform Compatibility
globalStyle	Object	No	Set the window performance of the default page
pages	Object Array	Yes	Set page path and window performance
easycom	Object	No	Component automatic import rules	2.5.5+
tabBar	Object	No	Set the performance of the bottom tab
condition	Object	No	Start mode configuration
subPackages	Object Array	No	Subpackage loading configuration
preloadRule	Object	No	Subcontract preload rule	WeChat MiniApp
workers	String	No	The directory where Worker code is placed	WeChat MiniApp
leftWindow	Object	No	The left window of the big screen	H5
topWindow	Object	No	The top window of the large screen	H5
rightWindow	Object	No	The right window of the big screen	H5
uniIdRouter	Object	否	自动跳转相关配置，新增于HBuilderX 3.5.0
entryPagePath	String	否	默认启动首页，新增于HBuilderX 3.7.0	微信小程序、支付宝小程序

Here is a pages.json with all configuration options:

{
	"pages": [{
		"path": "pages/component/index",
		"style": {
			"navigationBarTitleText": "组件"
		}
	}, {
		"path": "pages/API/index",
		"style": {
			"navigationBarTitleText": "接口"
		}
	}, {
		"path": "pages/component/view/index",
		"style": {
			"navigationBarTitleText": "view"
		}
	}],
	"condition": { //模式配置，仅开发期间生效
		"current": 0, //当前激活的模式（list 的索引项）
		"list": [{
			"name": "test", //模式名称
			"path": "pages/component/view/index" //启动页面，必选
		}]
	},
	"globalStyle": {
		"navigationBarTextStyle": "black",
		"navigationBarTitleText": "演示",
		"navigationBarBackgroundColor": "#F8F8F8",
		"backgroundColor": "#F8F8F8",
		"usingComponents":{
			"collapse-tree-item":"/components/collapse-tree-item"
		},
		"renderingMode": "seperated", // 仅微信小程序，webrtc 无法正常时尝试强制关闭同层渲染
		"pageOrientation": "portrait", //横屏配置，全局屏幕旋转设置(仅 APP/微信/QQ小程序)，支持 auto / portrait / landscape
		"rpxCalcMaxDeviceWidth": 960,
		"rpxCalcBaseDeviceWidth": 375,
		"rpxCalcIncludeWidth": 750
	},
	"tabBar": {
		"color": "#7A7E83",
		"selectedColor": "#3cc51f",
		"borderStyle": "black",
		"backgroundColor": "#ffffff",
		"height": "50px",
		"fontSize": "10px",
		"iconWidth": "24px",
		"spacing": "3px",
    	"iconfontSrc":"static/iconfont.ttf", // app tabbar 字体.ttf文件路径 app 3.4.4+
		"list": [{
			"pagePath": "pages/component/index",
			"iconPath": "static/image/icon_component.png",
			"selectedIconPath": "static/image/icon_component_HL.png",
			"text": "组件",
      		"iconfont": { // 优先级高于 iconPath，该属性依赖 tabbar 根节点的 iconfontSrc
       			"text": "\ue102",
        		"selectedText": "\ue103",
        		"fontSize": "17px",
        		"color": "#000000",
        		"selectedColor": "#0000ff"
      		}
		}, {
			"pagePath": "pages/API/index",
			"iconPath": "static/image/icon_API.png",
			"selectedIconPath": "static/image/icon_API_HL.png",
			"text": "接口"
		}],
		"midButton": {
			"width": "80px",
			"height": "50px",
			"text": "文字",
			"iconPath": "static/image/midButton_iconPath.png",
			"iconWidth": "24px",
			"backgroundImage": "static/image/midButton_backgroundImage.png"
		}
	},
  "easycom": {
    "autoscan": true, //是否自动扫描组件
    "custom": {//自定义扫描规则
      "^uni-(.*)": "@/components/uni-$1.vue"
    }
  },
  "topWindow": {
    "path": "responsive/top-window.vue",
    "style": {
      "height": "44px"
    }
  },
  "leftWindow": {
    "path": "responsive/left-window.vue",
    "style": {
      "width": "300px"
    }
  },
  "rightWindow": {
    "path": "responsive/right-window.vue",
    "style": {
      "width": "300px"
    },
    "matchMedia": {
      "minWidth": 768
    }
  }
}

globalStyle

Used to set the status bar, navigation bar, title, window background color, etc. of the application.

Properties	Type	Default Value	Description	Platform Difference Description
navigationBarBackgroundColor	HexColor	#F8F8F8	导航栏背景颜色（同状态栏背景色）	APP与H5为#F8F8F8，小程序平台请参考相应小程序文档
navigationBarTitleText	String		Navigation bar title text
navigationStyle	String	default	Navigation bar style, only default/custom is supported. Custom is to cancel the default native navigation bar, please see Use Note	WeChat MiniApp 7.0+, Baidu MiniApp, H5, App (2.0.3+)
backgroundColor	HexColor	#ffffff	The background color of the window displayed in the pull-down	WeChat MiniApp
backgroundTextStyle	String	dark	The style of drop-down loading, only supports dark/light	WeChat MiniApp
enablePullDownRefresh	Boolean	false	Whether to enable pull-down refresh, see Page Lifecycle for details.
onReachBottomDistance	Number	50	The distance from the bottom of the page when the pull-up bottom event is triggered. The unit only supports px. For details, see Page Lifecycle
backgroundColorTop	HexColor	#ffffff	Background color of the top window (bounce area)	iOS only
backgroundColorBottom	HexColor	#ffffff	Background color of the bottom window (bounce area)	iOS only
titleImage	String		Navigation bar image address (replace the current text title), Alipay MiniApp must use https image link address	Alipay MiniApp, H5, APP
transparentTitle	String	none	The overall (foreground, background) transparency setting of the navigation bar. Support always always transparent/auto sliding adaptive/none opaque	Alipay MiniApp, H5, APP
titlePenetrate	String	NO	Click to penetrate the navigation bar	Alipay MiniApp, H5
pageOrientation	String	portrait	Landscape screen configuration, screen rotation setting, only supports auto / portrait / landscape For details, see Response to display area changes	App 2.4.7+, WeChat MiniApp, QQ MiniApp
animationType	String	pop-in	Animation effect of window display, see: Window Animation	App
animationDuration	Number	300	Window display animation duration, the unit is ms	App
app-plus	Object		Set the specific style compiled to the App platform, the configuration items refer to the following app-plus	App
h5	Object		Set the specific style compiled to the H5 platform, the configuration items refer to H5	H5
mp-alipay	Object		设置编译到 mp-alipay 平台的特定样式，配置项参考下方 MP-ALIPAY	支付宝小程序
mp-weixin	Object		设置编译到 mp-weixin 平台的特定样式，配置项参考下方 MP-WEIXIN	微信小程序
mp-toutiao	Object		Set the specific style compiled to mp-toutiao platform	ByteDance MiniApp
mp-lark	Object		Set the specific style compiled to the mp-lark platform	Feishu MiniApp
mp-qq	Object		Set the specific style compiled to mp-qq platform	QQ MiniApp
mp-kuaishou	Object		Set the specific style compiled to mp-kuaishou platform	Kuaishou MiniApp
mp-jd	Object		Set the specific style compiled to mp-jd platform	Jingdong MiniApp
usingComponents	Object		Reference MiniApp components, refer to [MiniApp Components](/tutorial/miniprogram-subject.html# MiniApp Custom Component Support)
renderingMode	String		Same-layer rendering, webrtc (real-time audio and video) cannot work normally, try to configure seperated to forcibly turn off the same layer	WeChat MiniApp
leftWindow	Boolean	true	When leftWindow exists, whether to display leftWindow by default	H5
topWindow	Boolean	true	When topWindow exists, whether to display topWindow by default	H5
rightWindow	Boolean	true	When rightWindow exists, whether to display rightWindow by default	H5
rpxCalcMaxDeviceWidth	Number	960	The maximum device width supported by rpx calculation, unit px	App (vue2 and nvue not included), H5 (2.8.12+)
rpxCalcBaseDeviceWidth	Number	375	The base device width used in rpx calculation. When the actual width of the device exceeds the maximum device width supported by rpx calculation, it will be calculated according to the base width. The unit is px	App (vue2 and nvue not included), H5 (2.8. 12+)
rpxCalcIncludeWidth	Number	750	rpx calculates the specially processed value, always calculated according to the actual device width, unit rpx	App (vue2 and nvue not included), H5 (2.8.12+)
dynamicRpx	Boolean	false	Dynamic rpx, the screen size changes will re-render rpx	App-nvue (vue3 fixed value is true) 3.2.13+
maxWidth	Number		unit px, when the width of the visible area of the browser is greater than maxWidth, the two sides are left blank; when it is less than or equal to maxWidth, the page is full; different pages support different maxWidth configurations; maxWidth = leftWindow(optional)+ page(page body)+rightWindow(optional)	H5（2.9.9+）

Notice

• Alipay MiniApp must use the image link address of https when using titleImage. It needs to be debugged on the real machine to see the effect, and there is no effect in the Alipay developer tool
• The titleImage set in globalStyle will also override the text title set in pages->style
• When using maxWidth, the fixed elements in the page need to use --window-left, --window-right to ensure the correct layout position
• dynamicRpx This configuration has been removed from the vue3 nvue page, and it is upgraded to automatic rpx for horizontal and vertical screen switching. If you don’t need it, you can use px

topWindow

uni-app 2.9+ adds leftWindow, topWindow, rightWindow configuration. Used to solve widescreen adaptation problems.

With the existing mobile application as the mainWindow, a new page display form can be added on the left, top, and right.

For the overall widescreen adaptation idea, refer to the separate Widescreen Adaptation Guide

Attribute	Type	Default	Description
path	String		Configuration page path
style	Object		Configure page window performance, configuration items refer to the following pageStyle
matchMedia	Object		Configure the rules for displaying this window, refer to the configuration items below matchMedia

Notice

• Currently, the style node only supports configuration of CSS style-related properties such as width and height
• If you need to automatically hide the navigationBar of the page when there is a topwindow, configure the following css in App.vue according to different requirements:
  • Only need to hide a certain page navigationBar

    /* 隐藏路径为 pages/component/view/view 页面的 navigationBar */
    .uni-app--showtopwindow [data-page="pages/component/view/view"] uni-page-head {
    	display: none;
    }
    

  • It is necessary to hide the navigationBar of most pages and display the navigationBar of a certain page

    /* 隐藏所有页面的 navigationBar */
    .uni-app--showtopwindow uni-page-head {
    	display: none;
    }
    
    /* 显示路径为 pages/component/view/view 页面的 navigationBar */
    .uni-app--showtopwindow [data-page="pages/component/view/view"] uni-page-head {
    	display: block;
    }
    

matchMedia

Attribute	Type	Default	Description
minWidth	Number	768	When the width of the visible area of the device is >= minWidth, this window will be displayed

Through the adjustment of matchMedia, the specified window can be adaptively displayed on different screens.

{
  "pages": [
    {
      "path": "pages/login/login",
      "style": {
        "topWindow": false // 当前页面不显示 topWindow
        "leftWindow": false // 当前页面不显示 leftWindow
        "rightWindow": false // 当前页面不显示 rightWindow
      }
    }
  ],
  "topWindow": {
    "path": "responsive/top-window.vue", // 指定 topWindow 页面文件
    "style": {
      "height": "44px"
    }
  },
  "leftWindow": {
    "path": "responsive/left-window.vue", // 指定 leftWindow 页面文件
    "style": {
      "width": "300px"
    }
  },
  "rightWindow": {
    "path": "responsive/right-window.vue", // 指定 rightWindow 页面文件
    "style": {
      "width": "300px" // 页面宽度
    },
    "matchMedia": {
      "minWidth": 768 //生效条件，当窗口宽度大于768px时显示
    }
  }
}

Case demonstration: HBuilderX 2.9.9+, select hello uni-app or news template for new projects, or browse directly: [https://hellouniapp.dcloud.net.cn/](https://hellouniapp.dcloud.net.cn /)

leftWindow

Same as topWindow

rightWindow

Same as topWindow

Window communication reference: https://uniapp.dcloud.net.cn/api/window/communication

pages

uni-app configures which pages the application consists of through the pages node. The pages node receives an array, and each item in the array is an object, and its attribute values are as follows:

Attribute	Type	Default	Description
path	String		Configuration page path
style	Object		Configure page window performance, configuration items refer to the following pageStyle

Tips：

• The first item of the pages node is the application entry page (i.e. the home page)
• Add/reduce pages in the application, you need to modify the pages array
• The file name ** does not need to write a suffix **, the framework will automatically find the page resources under the path

Code sample:

The development directory is:

┌─pages
│  ├─index
│  │  └─index.vue
│  └─login
│     └─login.vue
├─static
├─main.js
├─App.vue
├─manifest.json
└─pages.json

You need to fill in pages.json

{
    "pages": [
        {
            "path": "pages/index/index",
            "style": { ... }
        }, {
            "path": "pages/login/login",
            "style": { ... }
        }
    ]
}

style

Used to set the status bar, navigation bar, title, window background color, etc. of each page.

The configuration items in the page will override the same configuration items in globalStyle

Properties	Type	Default Value	Description	Platform Difference Description
navigationBarBackgroundColor	HexColor	#F8F8F8	导航栏背景颜色（同状态栏背景色）	APP与H5为#F8F8F8，小程序平台请参考相应小程序文档
navigationBarTitleText	String		Navigation bar title text
navigationBarShadow	Object		Navigation bar shadow, configuration reference below navigation bar shadow
navigationStyle	String	default	Navigation bar style, only default/custom is supported. Custom is to cancel the default native navigation bar, please see Use Note	WeChat MiniApp 7.0+, Baidu MiniApp, H5, App (2.0.3+)
disableScroll	Boolean	false	Set to true, the page cannot scroll up and down as a whole (bounce effect), it is only valid in the page configuration, and the setting in globalStyle is invalid	WeChat MiniApp(iOS), Baidu MiniApp(iOS)
backgroundColor	HexColor	#ffffff	The background color of the window	WeChat MiniApp, Baidu MiniApp, ByteDance MiniApp, Feishu MiniApp, Jingdong MiniApp
backgroundTextStyle	String	dark	The style of drop-down loading, only dark/light is supported
enablePullDownRefresh	Boolean	false	Whether to enable pull-down refresh, see Page Lifecycle for details.
onReachBottomDistance	Number	50	The distance from the bottom of the page when the pull-up bottom event is triggered. The unit only supports px. For details, see Page Lifecycle
backgroundColorTop	HexColor	#ffffff	Background color of the top window (bounce area)	iOS only
backgroundColorBottom	HexColor	#ffffff	Background color of the bottom window (bounce area)	iOS only
disableSwipeBack	Boolean	false	Whether to disable swipe back	App-iOS (3.4.0+)
titleImage	String		Navigation bar picture address (replace the current text title), Alipay MiniApp must use https image link address	Alipay MiniApp, H5, App
transparentTitle	String	none	Navigation bar transparent setting. Support always always transparent/auto sliding adaptive/none opaque	Alipay MiniApp, H5, APP
titlePenetrate	String	NO	Click to penetrate the navigation bar	Alipay MiniApp, H5
app-plus	Object		Set the specific style compiled to the App platform, the configuration items refer to the following app-plus	App
h5	Object		Set the specific style compiled to the H5 platform, the configuration items refer to H5	H5
mp-alipay	Object		Set the specific style compiled to the mp-alipay platform, the configuration items refer to MP-ALIPAY	Alipay MiniApp
mp-weixin	Object		Set the specific style compiled to mp-weixin platform	WeChat MiniApp
mp-baidu	Object		Set the specific style compiled to mp-baidu platform	Baidu MiniApp
mp-toutiao	Object		Set the specific style compiled to mp-toutiao platform	ByteDance MiniApp
mp-lark	Object		Set the specific style compiled to the mp-lark platform	Feishu MiniApp
mp-qq	Object		Set the specific style compiled to mp-qq platform	QQ MiniApp
mp-kuaishou	Object		Set the specific style compiled to mp-kuaishou platform	Kuaishou MiniApp
mp-jd	Object		Set the specific style compiled to mp-jd platform	Jingdong MiniApp
usingComponents	Object		Referring to MiniApp components, refer to [MiniApp Components](/tutorial/miniprogram-subject.html# MiniApp Custom Component Support)	App, WeChat MiniApp, Alipay MiniApp, Baidu MiniApp, JD.com MiniApp
leftWindow	Boolean	true	When leftWindow exists, whether the current page displays leftWindow	H5
topWindow	Boolean	true	When topWindow exists, whether to display topWindow	H5
rightWindow	Boolean	true	When rightWindow exists, whether the current page displays rightWindow	H5
maxWidth	Number		unit px, when the width of the visible area of the browser is greater than maxWidth, the two sides are left blank; when it is less than or equal to maxWidth, the page is full; different pages support different maxWidth configurations; maxWidth = leftWindow(optional)+ page(page body)+rightWindow(optional)	H5（2.9.9+）

Notice

• When using maxWidth, the fixed elements in the page need to use --window-left, --window-right to ensure the correct layout position

Code sample:

{
  "pages": [{
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",//设置页面标题文字
        "enablePullDownRefresh":true//开启下拉刷新
      }
    },
    ...
  ]
}

Notice

• Alipay MiniApp must use the image link address of https when using titleImage. It needs to be debugged on the real machine to see the effect, and there is no effect in the Alipay developer tool

Custom navigation bar use attention

When navigationStyle is set to custom or titleNView is set to false, the native navigation bar is not displayed. At this time, several issues should be paid attention to:

• For non-H5 terminals, the status bar area at the top of the mobile phone will be covered by the page content. This is because the form is immersive, i.e. full screen writable content. uni-app provides the css variable --status-bar-height of the status bar height, if you need to put the status The position of the column is given away from the foreground part, and a placeholder div can be written, and the height is set to a css variable.

<template>
    <view>
        <view class="status_bar">
            <!-- This is the status bar -->
        </view>
        <view> 状态栏下的文字 </view>
    </view>
</template>
<style>
    .status_bar {
        height: var(--status-bar-height);
        width: 100%;
    }
</style>

• If the native navigation bar cannot meet the needs, it is recommended to use uni ui's custom navigation bar NavBar. This front-end navigation bar automatically handles the status bar height occupation problem.
• When the front-end navigation bar is paired with native pull-down refresh, there will be problems, including
  • Under the WeChat MiniApp, iOS needs to be pulled longer to see the three points of pull-to-refresh, while Android pulls down from the top of the screen and cannot pull down from the bottom of the navigation bar. If you must pull down from the front-end navigation bar, you can only give up the native pull-down refresh under the MiniApp, pure front-end simulation, refer to mescroll plugin,but this It is easy to have performance problems. At present , the MiniApp platform itself does not provide a better solution
  • Under App and H5, the native pull-down refresh provides circle style, you can specify the offset offset (configured under app-plus in pages.json), and customize the drop-down circle where it appears. There are examples in the extension component of hello uni-app.
• On the non-H5 side, the front-end navigation cannot cover the native components. If the page has native components such as video, map, textarea (MiniApp only), etc., the navigation bar will be covered when scrolling
  • If it is a MiniApp, you can use cover-view as the navigation bar to avoid coverage problems
  • If it is under App, it is recommended to use titleNView or subNVue for a better experience
• The rendering speed of the front-end components is not as good as that of the native navigation bar. The native navigation can be rendered during the animation to ensure that there is no white screen during the animation. However, when using the front-end navigation bar, the entire page may be blank during the animation of the new form. The lower the The phone at the end is more obvious.
• The above discussion is the front-end custom navigation bar, but on the App side, the native navigation bar also provides richer customization than the MiniApp navigation
  • titleNView: Provide more configurations for the native navigation bar, including custom buttons, scrolling gradient effects, search boxes, etc., see titleNView for details
  • subNVue: Use nvue native rendering, develop all layouts by yourself, with all customization flexibility. See subNVue for details
• After the native navigation bar is disabled on the page, if you want to change the foreground font style of the status bar, you can still set the navigationBarTextStyle property of the page (can only be set to black or white). If you want to set the status bar color separately, you can use plus.navigator.setStatusBarStyle setting on the App side. Note that some low-end Android phones (4.4) do not support setting the foreground color of the status bar.

In view of the above problems, try to use native navigation when native navigation can solve business needs. Sometimes it is even necessary to sacrifice some less important needs. Under App and H5, uni-app provides flexible solutions: titleNView, subNVue, or the whole The page uses nvue. But under the MiniApp, because of its own limitations, there is no good solution. If necessary, you can also use conditional compilation to split the processing.

app-plus

Configure the specific style when compiling to the App platform, and some commonly used configurations are also supported by the H5 platform. The following are only common ones. For more configuration items, please refer to WebviewStyles.

Properties	Type	Default	Description	Platform Compatibility
titleNView	Object		Navigation Bar, see: Navigation Bar	App、H5
subNVues	Object		Native sub-form, see: Native sub-form	App 1.9.10+
bounce	String		page bounce effect, set to "none" to disable the effect.	App-vue (nvue Android has no page-level bounce effect, only list, recycle-list, waterfall and other scrolling components have bounce effect)
popGesture	String	close	Slide back function, optional values: "close" (enable slide back), "none" (disable slide back)	App-iOS
softinputNavBar	String	auto	The display mode of the completion toolbar on the iOS soft keyboard. When set to "none", the toolbar is turned off.	App-iOS
softinputMode	String	adjustPan	soft keyboard pop-up mode, support adjustResize, adjustPan two modes	App
pullToRefresh	Object		pull to refresh	App
scrollIndicator	String		Scroll bar display policy, when set to "none", no scroll bar will be displayed.	App
animationType	String	pop-in	The animation effect of window display, see: window animation for details.	App
animationDuration	Number	300	The duration of the window display animation, in ms.	App

Tips

• The .nvue page only supports titleNView, pullToRefresh, scrollIndicator configuration, other configuration items are not currently supported

Navigation Bar

Attribute	Type	Default	Description	Version Compatibility
backgroundColor	String	#F7F7F7	Background color, supports hexadecimal color or RGBA color.	Only the floating navigation bar on the App side supports RGBA colors
buttons	Array		custom buttons, see buttons	pure nvue, that is, render:native is not supported temporarily
titleColor	String	#000000	title text color
titleOverflow	String	ellipsYes	The processing method when the title text exceeds the display area. "clip" - the content clips when it exceeds the display area; "ellipsis" - the trailing ellipsis mark (...) is displayed when it exceeds the display area.
titleText	String		title text content
titleSize	String		title text font size
type	String	default	Navigation bar style. "default" - default style; "transparent" - scroll transparent gradient; "float" - floating navigation bar.	App-nvue 2.4.4+ support, App-vue, H5
tags	Array		Native View enhancements, see: 5+ View Controls
searchInput	Object		The configuration of the search box on the native navigation bar, see: searchInput	1.6.0
homeButton	Boolean	false	Whether the title bar control displays the Home button
autoBackButton	Boolean	true	Whether the title bar control displays the left back button	App 2.6.3+
backButton	Object		The style of the back button, see: backButton	App 2.6.3
backgroundImage	String		Supports the following types: background image path - such as "/static/img. Gradient of two colors, such as "linear-gradient(to top, #a80077, #66ff00)", where the first parameter is the direction of the gradient, which can take values: "to right" means gradient from left to right, "to left" Indicates a gradient from right to left, "to bottom" indicates a gradient from top to bottom, "to top" indicates a gradient from bottom to top, "to bottom right" indicates a gradient from upper left to lower right, and "to top left" indicates a gradient from right Bottom to top left	2.6.3
backgroundRepeat	String		is only valid when backgroundImage is set as an image path. Possible values: "repeat" - background image is tiled vertically and horizontally; "repeat-x" - background image is tiled horizontally and vertically stretched; "repeat-y" - background image is tiled vertically tiled, stretched horizontally; "no-repeat" - the background image is stretched both vertically and horizontally. Defaults to "no-repeat"	2.6.3
titleAlign	String	"auto"	Possible values: "center"-center alignment; "left"-left alignment; "auto"-automatic selection according to the platform (Android platform left alignment, iOS platform center alignment)	2.6.3
blurEffect	String	"none"	This effect will Gaussian blur the content behind the title bar, only valid when type is "transparent" or "float". Possible values: "dark" - dark style blur, corresponding to iOS native UIBlurEffectStyleDark effect; "extralight" - highlight style blur, corresponding to iOS native UIBlurEffectStyleExtraLight effect; "light" - light style blur, corresponding to iOS native UIBlurEffectStyleLight effect; "none" - No blur effect. Note: You should avoid setting the background color when using the blur effect, setting the background color may cover the blur effect.	2.4.3
coverage	String	"132px"	The change scope of the title bar control is only valid when the type value is transparent, and the background transparency of the title bar will change when the page is scrolled. The title bar background becomes fully opaque when the page is scrolled to the specified offset. Support percentage, pixel value
splitLine	Boolean	false	The split line at the bottom of the title bar (SplitLineStyles), setting this property will display the split line at the bottom of the title bar control, and the color can be configured value and height. Setting this property value to undefined or null hides the dividing line. Bottom divider not shown by default	2.6.6
subtitleColor	String		Subtitle text color, the color value format is "#RRGGBB" and "rgba(R,G,B,A)", such as "#FF0000" means the title text color is red. The default value is the same as the main title text color	2.6.6
subtitleSize	String	"auto"	The subtitle text font size, the font size unit is pixel, such as "14px" means the font size is 14 pixels, and the default value is 12 pixels.	2.6.6
subtitleOverflow	String	"ellipsis"	The processing method when the title text exceeds the display area, possible values: "clip" - the content is clipped when it exceeds the display area; "ellipsis" - the ellipsis mark is displayed at the end when it exceeds the display area (...) .	2.6.6
subtitleText	String		Subtitle text content, after setting the subtitle, two lines of titles will be displayed, and the subtitle will be displayed under the main title (titleText). Note: After setting the subtitle, it will be displayed on the left	2.6.6
titleIcon	String		Title icon, icon path such as "./img/t.png", only supports local file path, relative path, relative to the host position of the current page, fixed width and height are logical pixel value "34px". The image width and height are required to be the same. Note: After setting the title icon, the title will be displayed on the left.	2.6.6
titleIconRadius	String	No rounded corners	The rounded corners of the title icon, the value format is "XXpx", where XX is the pixel value (logical pixel), such as "10px" means a rounded corner with a radius of 10 pixels.	2.6.6

SplitLineStyles

Attribute	Type	Default	Description	Version Compatibility
color	String	#CCCCCC	The color of the bottom dividing line, possible values: "#RRGGBB" format string, such as "#FF0000" means drawing a red dividing line; "rgba(R,G,B,A)", where R/G/B represent red value/green value/blue value respectively, positive integer type, the value range is 0-255, A is transparency, floating point type, the value range is 0-1 (0 is fully transparent, 1 is opaque), such as "rgba(255,0,0,0.5)", which means red is translucent
height	String	"1px"	Possible values: pixel value (logical pixel), support decimal point, such as "1px" means 1 pixel height; percentage, such as "1%", relative to the height of the title bar control.

Tips

• The page supports disabling the native navigation bar by configuring navigationStyle as custom or titleNView as false. Once native navigation is disabled, please read Custom Navigation Considerations.
• When the type value of titleNView is transparent, the navigation bar is a scrolling transparent gradient navigation bar. By default, there are only buttons. After scrolling, the background color of the title bar and the title text will appear gradually. Custom buttons are not supported to set the color attribute; When type is float, the navigation bar is a floating title bar. At this time, the page content is pushed up to the top of the screen, including the status bar, but the navigation bar is suspended above the page. Generally, the background of the navigation bar will be set at the same time in this scenario The color is the rgba translucent color.
• App-nvue 2.4.4+ supports when the type value of titleNView is transparent
• After configuring buttons in titleNView, listen to the click event of the button, refer to the weex compilation mode of the vue page and nvue: uni.onNavigationBarButtonTap
• After configuring searchInput in titleNView, related event monitoring reference: [onNavigationBarSearchInputChanged, etc.](/collocation/frame/lifecycle?id=%E9%A1%B5%E9%9D%A2%E7%94%9F% E5%91%BD%E5%91%A8%E6%9C%9F)
• configurable via [<navigation-bar>(/component/navigation-bar)]
• If the button of the native navigation bar under the app uses a font icon, pay attention to check whether the name of the font library (font-family) uses the default iconfont. This name is a reserved word and cannot be used as the name of an externally imported font library. It needs to be adjusted to A custom name, otherwise it cannot be displayed.
• To learn about the development methods of various navigation bars, please read Navigation Bar Development Guide

Custom Buttons

Attribute	Type	Default	Description
type	String	none	button style, see: buttons style
color	String	The default is the same as the title text color	The color of the text on the button
background	String	The default value is gray translucent	The background color of the button, it only takes effect when the title bar type=transparent
colorPressed	String	The default value is the color attribute value, and the transparency is automatically adjusted to 0.3	The text color of the pressed status button
float	String	right	The display position of the button on the title bar, which can be "left", "right"
fontWeight	String	normal	The thickness of the text on the button. Possible values are "normal" - standard font, "bold" - bold font.
fontSize	String		The text size on the button
fontSrc	String		The font file path used for the text on the button. Network addresses are not supported, please use local addresses uniformly.
select	String	false	Whether to display the selection indicator icon (down arrow), often used for city selection
text	String		The text to display on the button. When using a font icon, the unicode character representation must start with '\u', such as "\ue123" (note that it cannot be written as "\e123").
width	String	44px	The width of the button, possible values: "*px" - logical pixel value, such as "10px" means 10 logical pixel value, rpx is not supported. The content of the button is displayed in the center; "auto" - custom calculation width, automatically adjusts the width of the button according to the content

Customize the style of the back button

It takes effect when autoBackButton is set to true. Through this attribute, you can customize the style of the back button, such as icon size, red dot, corner mark, title, etc.

HBuilderX 2.6.3+ support

Attribute	Type	Default	Description
background	String	none	Background color, only valid when the title bar type=transparent, when the title bar is transparent, the background color of the button. Possible values are #RRGGBB and rgba format color strings, and the default value is gray translucent.
badgeText	String		Badge text, up to 3 characters can be displayed, if it exceeds, it will be displayed as...
color	String	The title text color of the window title bar control.	Icon and title color, possible values: "#RRGGBB" format string, such as "#FF0000" means red; "rgba(R,G,B,A)", where R/G/B represent red value/ Green value/blue value, positive integer type, the value range is 0-255, A is transparency, floating point type, the value range is 0-1 (0 is fully transparent, 1 is opaque), such as "rgba(255 ,0,0,0.5)", indicating that the red color is translucent.
colorPressed	String		Pressed state button text color, possible values: "#RRGGBB" format string, such as "#FF0000" means red; "rgba(R,G,B,A)", where R/G /B stands for red value/green value/blue value respectively, positive integer type, the value range is 0-255, A is transparency, floating point type, the value range is 0-1 (0 is fully transparent, 1 is opaque ), such as "rgba(255,0,0,0.5)", which means red is translucent. The default value is the color attribute value automatically adjusts the opacity to 0.3.
fontWeight	String	"normal"	Returns the weight of the icon, possible values: "normal" - standard font; "bold" - bold font.
fontSize	String		Returns the font size of the icon, possible values: font height pixel value, number plus "px" format string, such as "22px". When the window title bar is a transparent style (type="transparent"), the default value is "22px"; when the window title bar is a default style (type="default"), the default value is "27px".
redDot	Boolean	false	Whether to display red dots, set to true to display red dots, false to not display red dots. The default value is false. Note: The red dot is not displayed when the subtitle text is set.
title	String		Returns the title on the button, displayed after the return icon (font icon), defaults to an empty string.
titleWeight	String	"normal"	Returns the weight of the title on the button, possible values: "normal" - standard font; "bold" - bold font.

Button style

When styling a button with a type value, the fontSrc and text properties are ignored.

value	description
forward	forward button
back	back button
share	Share button
favorite	Favorite button
home	Home button
menu	menu button
close	close button
none	No style, you need to set the content displayed on the button through the text attribute, and set the font library used through the fontSrc attribute.

Search box configuration

searchInput can place a search box on the native navigation bar of titleNView. Its width adapts to surrounding elements.

Attribute	Type	Default	Description
autoFocus	Boolean	false	whether to automatically get the focus
align	String	center	The alignment of the text in the non-input state. Possible values: "left" - align left; "right" - align right; "center" - align center.
backgroundColor	String	rgba(255,255,255,0.5)	background color
borderRadius	String	0px	The fillet radius of the input box, the value format is "XXpx", where XX is the pixel value (logical pixel), rpx is not supported.
placeholder	String		hint text.
placeholderColor	String	#CCCCCC	Prompt text color
disabled	Boolean	false	Is it possible to input

searchInput Tips

For the life cycle of searchInput click input box onNavigationBarSearchInputClicked, text change onNavigationBarSearchInputChanged, click search button onNavigationBarSearchInputConfirmed, etc., see the document Page Life Cycle.

• In the life cycle, the content of the input box can be obtained through the parameter e.text. For details, see the template in hello uni-app - the example in the top navigation bar
• If you need to dynamically modify the searchInput, or obtain the placehold of the searchInput, refer to uni-app dynamically modify the App-side navigation bar

Common titleNView configuration code example

Some configurations are listed below. Regarding the comprehensive navigation bar configuration, here is a complete demonstration project that demonstrates various effects of the navigation bar. For details, see: [https://ext.dcloud.net.cn/plugin?id=1765](https:/ /ext.dcloud.net.cn/plugin?id=1765)

{
	"pages": [{
			"path": "pages/index/index", //首页
			"style": {
				"app-plus": {
					"titleNView": false //禁用原生导航栏
				}
			}
		}, {
			"path": "pages/log/log", //日志页面
			"style": {
				"app-plus": {
					"bounce": "none", //关闭窗口回弹效果
					"titleNView": {
						"buttons": [ //原生标题栏按钮配置,
							{
								"text": "分享" //原生标题栏增加分享按钮，点击事件可通过页面的 onNavigationBarButtonTap 函数进行监听
							}
						],
						"backButton": { //自定义 backButton
							"background": "#00FF00"
						}
					}
				}
			}
		}, {
			"path": "pages/detail/detail", //详情页面
			"style": {
				"navigationBarTitleText": "详情",
				"app-plus": {
					"titleNView": {
						"type": "transparent"//透明渐变导航栏 App-nvue 2.4.4+ 支持
					}
				}
			}
		}, {
			"path": "pages/search/search", //搜索页面
			"style": {
				"app-plus": {
					"titleNView": {
						"type": "transparent",//透明渐变导航栏 App-nvue 2.4.4+ 支持
						"searchInput": {
							"backgroundColor": "#fff",
							"borderRadius": "6px", //输入框圆角
							"placeholder": "请输入搜索内容",
							"disabled": true //disable时点击输入框不置焦，可以跳到新页面搜索
						}
					}
				}
			}
		}
		...
	]
}

Tips

• It is recommended to use font icons for the text of buttons. If Chinese characters or English are used, it is recommended to change the font to a smaller size, otherwise the length of the text will be too close to the right margin of the screen.
• App platform, buttons are dynamically modified, see details
• App platform, dynamic modification of buttons corner mark, see template in hello uni-app - top navigation title bar - navigation bar with red dot and corner mark
• App platform, set the dynamic modification of searchInput text, API see Documentation. Note that text cannot be set in the disable state, and placehold does not support dynamic settings for the time being
• For the H5 platform, if you need to implement the above dynamic modification, you need to modify it through dom operation in conditional compilation

Native subform

subNVues is a native subwindow for vue pages. It is used to solve the hierarchical coverage in the vue page in the App and the flexible customization of the native interface.

It is not a full-screen page, nor a component, but a native subform. It is an nvue page, rendered with the weex engine, which provides more powerful native layout capabilities than cover-view, plus.nativeObj.view, and is convenient for customizing native navigation or overlaying native maps, videos, etc. Please read subNVues Development Guide

subNVue can also be used in nvue pages. But currently it is not supported under pure nvue (render is native).

Attribute	Type	Description
id	String	ID of subNVue's native subwindow
path	String	Configure the nvue file path, the nvue file needs to be placed in the page file directory using subNvue
type	String	Built-in style of native sub-window, possible values: 'popup', popup layer; "navigationBar", navigation bar
style	Object	subNVue The style of the native sub-window, refer to the configuration item below subNVuesStyle

Tips

• The id of subNVues is globally unique and cannot be repeated
• An instance of subNVues can be obtained via uni.getSubNVueById('id')
• path property of subNVues can only be nvue file path

Native sub-form style

Attribute	Type	Default	Description
position	String	absolute	The typesetting position of the native sub-form, the typesetting position determines the positioning method of the native sub-form in the parent window. Possible values: "static", the native subform is positioned normally on the page, and scrolls along with the window content if there is a scroll bar on the page; "absolute", the native subform is positioned absolutely on the page, and does not follow the window if there is a scroll bar on the page Content scrolling; "dock", the native child form is docked on the page, and the docking position is determined by the value of the dock property. The default value is "absolute".
dock	String	bottom	The docking method of the native sub-form, it will only take effect when the "position" attribute value of the native sub-form is set to "dock", the possible value: "top", the native sub-form docks the page Top; "bottom", the native subform is docked at the bottom of the page; "right", the native subform is docked at the right side of the page; "left", the native subform is docked at the left side of the page. The default value is "bottom".
mask	HexColor	rgba(0,0,0,0.5)	The mask layer of the native sub-form, it will only take effect when the "type" attribute value of the native sub-form is set to "popup", and the possible values are: rgba Format string, which defines the style of the solid color mask layer, such as "rgba(0,0,0,0.5)", which means black translucence;
width	String	100%	The width of the native sub-window, support percentage, pixel value, the default is 100%. When the width attribute value is not set, the default width of the window can be changed by setting the left and right attribute values at the same time.
height	String	100%	The height of the native sub-form, support percentage, pixel value, the default is 100%. When the value of the height attribute is not set, the height of the native subform is first calculated by the values of the top and bottom attributes.
top	String	0px	The vertical downward offset of the native sub-window, which supports percentage and pixel value, and the default value is 0px. When the top property value is not set, the top position of the native subform is calculated first by the bottom and height property values.
bottom	String		The vertical upward offset of the native sub-form, which supports percentage and pixel values, and the default value is no value (automatically calculated according to the top and height attribute values). When the top and height values are set at the same time, this attribute value is ignored; when the height value is not set, the height of the native subform can be determined by the top and bottom attribute values.
left	String	0px	The horizontal offset to the left of the native sub-window. It supports percentage and pixel value. The default value is 0px. When the left property value is not set, the left position of the native subform is calculated by the right and width property values first.
right	String		The horizontal offset to the right of the native sub-window, which supports percentage and pixel values, and defaults to no value (automatically calculated according to the left and width attribute values). When the left and width values are set, this property value is ignored; when the width value is not set, the left and bottom property values can be used to determine the width of the native subform.
margin	String		The margin of the native sub-form, used to locate the position of the native sub-form, supports auto, and auto means centering. If left, right, top, and bottom are set, the corresponding margin values will be invalid.
zindex	Number		The stacking order value of the window of the native subform, the window with a higher stacking order will always be in front of the window with a lower stacking order, and the window with the same stacking order after calling the show method will be in front .
background	String	#FFFFFF	The background color of the window, and only Android platform 4.0 and above systems support the "transparent" background transparency style. For example, when subnvue is rounded, it needs to be set to transparent to see the correct effect

code example

{
	"pages": [{
		"path": "pages/index/index", //首页
		"style": {
			"app-plus": {
				"titleNView": false , //禁用原生导航栏
				"subNVues":[{//侧滑菜单
					"id": "drawer", //subNVue 的 id，可通过 uni.getSubNVueById('drawer') 获取
					"path": "pages/index/drawer.nvue", // nvue 路径
					"style": { //webview style 子集，文档可暂时开放出来位置，大小相关配置
						"position": "popup", //除 popup 外，其他值域参考 5+ webview position 文档
						"width": "50%"
					}

				}, {//弹出层
					"id": "popup",
					"path": "pages/index/popup",
					"style": {
						"position": "popup",
						"margin":"auto",
						"width": "150px",
						"height": "150px"
					}

				}, {//自定义头
					"id": "nav",
					"path": "pages/index/nav",
					"style": {
						"position": "dock",
						"height": "44px"
					}

				}]
			}
		}
	}]
}

pull down to refresh

Under the App platform, you can customize the partial pull-to-refresh configuration page->style->app-plus->pullToRefresh.

Attribute	Type	Default	Description
support	Boolean	false	whether to enable the pull-down refresh function of the window
color	String	#2BD009	The format of the color value is "#RRGGBB", only the "circle" style pull-down refresh supports this property.
style	String	The Android platform is circle; the iOS platform is default.	Possible values: "default" - classic pull-down refresh style (the page content follows when you pull down and drag); "circle" - circle style pull-down refresh control style (only the refresh control follows when you pull down and drag).
height	String		The drag height of the window's pull-down refresh control to enter the refresh state. Support percentage, such as "10%"; pixel value, such as "50px", does not support rpx.
range	String		The range that the window can drop down and drag. Support percentage, such as "10%"; pixel value, such as "50px", does not support rpx.
offset	String	0px	The starting position of the pull-to-refresh control. Only valid for the "circle" style pull-down refresh control, it is used to define the starting position of the refresh control when it is pulled down. Support percentage, such as "10%"; pixel value, such as "50px", does not support rpx. If a non-native title is used and a native pull-down refresh is required, the circle method is generally used and the offset is adjusted to the height of the custom title
contentdown	Object		Currently supports one attribute: caption——the title content displayed on the control when it is pulled down to refresh. Only valid for "default" style pull-to-refresh controls.
contentover	Object		currently supports one attribute: caption——pull down to refresh the title content displayed on the control when the refreshable state is released. Only valid for "default" style pull-to-refresh controls.
contentrefresh	Object		currently supports one attribute: caption——pull down to refresh the title content displayed on the control when it is in the refresh state. Only valid for "default" style pull-to-refresh controls.

Pull down to refresh use note

• When enablePullDownRefresh and pullToRefresh->support are set at the same time, the latter takes precedence.
• If you want to enable pull-down refresh on both the App and the MiniApp, please configure the enablePullDownRefresh property of the page to true.
• If you only want to enable pull-to-refresh on the App, do not configure the enablePullDownRefresh property of the page, but configure pullToRefresh->support to true.
• When the native pull-down refresh is enabled, the scroll-view with full screen height should not be used in the page. When dragging the content down, the pull-down refresh will be triggered first instead of scroll-view scrolling
• The starting position of the native pull-to-refresh is below the native navigation bar. If the native navigation bar is canceled and a custom navigation bar is used, the native pull-to-refresh position will be at the top of the screen. If you want to pull under the custom navigation bar, you can only use the pull-down refresh of the circle method, and set the offset parameter to adjust the starting position of the circle circle to the bottom of the custom navigation bar. There are examples in the extension component of hello uni-app.
• If you want to implement more complex pull-down refreshes on the app side, such as pulling down a special graphic like Meituan and JD App, you can use nvue's <refresh> component. From HBuilderX 2.0.3+, you can experience the news template by selecting a new project
• If you want to implement pull-down refresh on the Vue page through the web front-end technology, there are examples in the plug-in market, but the performance of the front-end pull-down refresh is not as good as the original one, and the complex and long list will be very stuck
• On iOS, the pull-down refresh in default mode is bound to the bounce rebound. If bounce:none is set, the default pull-down refresh cannot be used

code example

{
    "pages": [
        {
            "path": "pages/index/index", //首页
            "style": {
                "app-plus": {
                    "pullToRefresh": {
                        "support": true,
                        "color": "#ff3333",
                        "style": "default",
                        "contentdown": {
                            "caption": "下拉可刷新自定义文本"
                        },
                        "contentover": {
                            "caption": "释放可刷新自定义文本"
                        },
                        "contentrefresh": {
                            "caption": "正在刷新自定义文本"
                        }
                    }
                }
            }
        }
    ]
}

h5

Configure specific styles when compiling to the H5 platform

Attribute	Type	Description
titleNView	Object	Navigation Bar
pullToRefresh	Object	pull to refresh

Navigation bar

Attribute	Type	Default	Description	Minimum Version
backgroundColor	String	#F7F7F7	The background color, the format of the color value is "#RRGGBB".
buttons	Array		custom buttons, refer to buttons
titleColor	String	#000000	title text color
titleText	String		title text content
titleSize	String		title text font size
type	String	default	Navigation bar style. "default" - default style; "transparent" - transparent gradient.
searchInput	Object		The style of the search box on the navigation bar, see: searchInput	1.6.5

Custom buttons

Attribute	Type	Default	Description
type	String	none	button style, see: buttons style
color	String	The default is the same as the title text color	The color of the text on the button
background	String	The default value is gray translucent	The background color of the button, it only takes effect when the title bar type=transparent
badgeText	String		The badge text displayed on the button, up to 3 characters, if it exceeds, it will be displayed as...
colorPressed (not supported yet)	String	The default value is the color attribute value, and the transparency is automatically adjusted to 0.3	The text color of the pressed status button
float	String	right	The display position of the button on the title bar, which can be "left", "right"
fontWeight	String	normal	The thickness of the text on the button. Possible values are "normal" - standard font, "bold" - bold font.
fontSize	String		The text size on the button
fontSrc	String		The font file path used for the text on the button.
select	String	false	Whether to display the selection indicator icon (down arrow)
text	String		The text to display on the button. When using a font icon, the unicode character representation must start with '\u', such as "\ue123" (note that it cannot be written as "\e123").
width	String	44px	The width of the button, possible values: "*px" - logical pixel value, such as "10px" means 10 logical pixel value, rpx is not supported, and the content of the button is displayed in the center; "auto" - customized Calculate the width, automatically adjust the button width according to the content

Button style

When styling a button with a type value, the fontSrc and text properties are ignored.

value	description
forward	forward button
back	back button
share	Share button
favorite	Favorite button
home	Home button
menu	menu button
close	close button
none	No style, you need to set the content displayed on the button through the text attribute, and set the font library used through the fontSrc attribute.

pull down to refresh

H5 platform pull down refresh animation, only circle type.

Attribute	Type	Default	Description
color	String	#2BD009	The format of the color value is "#RRGGBB"
offset	String	0px	The starting position of the pull-to-refresh control. Support percentage, such as "10%"; pixel value, such as "50px", does not support rpx.

Search box style

Attribute	Type	Default	Description
autoFocus	Boolean	false	whether to automatically get the focus
align	String	center	The alignment of the text in the non-input state. Possible values: "left" - align left; "right" - align right; "center" - align center.
backgroundColor	String	rgba(255,255,255,0.5)	background color
borderRadius	String	0px	The fillet radius of the input box, the value format is "XXpx", where XX is the pixel value (logical pixel), rpx is not supported.
placeholder	String		hint text
placeholderColor	String	#CCCCCC	Prompt text color
disabled	Boolean	false	Is it possible to input

Precautions:

• If the h5 node is not configured, the configuration under app-plus will be used by default.
• If the h5 node is configured, it will override the configuration under app-plus.

navigationBarShadow

Attribute	Type	Description
colorType	String	Shadow color, support: gray, blue, green, orange, red, yellow

Precautions:

• WeChat/Baidu/Toutiao need to configure: "disableScroll": true
• Alipay "mp-alipay": { "allowsBounceVertical": "NO" }

mp-alipay

Configure specific styles when compiling to the MP-ALIPAY platform

Attribute	Type	Default	Description
allowsBounceVertical	String	YES	Whether to allow BounceVertical. Support YES / NO
titleImage	String		Navigation bar image address (replacing the current text title), must use https image link address
transparentTitle	String	none	Navigation bar transparent setting. Support always always transparent / auto sliding adaptive / none opaque
titlePenetrate	String	NO	Navigation bar click penetration
showTitleLoading	String	NO	Whether to display the loading of the navigation bar when entering. Support YES / NO
backgroundImageUrl	String		drop down to reveal the displayed background image link
backgroundImageColor	HexColor		Drop down to reveal the background color of the displayed background image
gestureBack	String	NO	For iOS, whether to support gesture back. Support YES / NO
enableScrollBar	String	YES	For Android, whether to display the WebView scroll bar. Support YES / NO

Precautions

• titleImage only supports https addresses, setting titleImage will replace the page text title
• backgroundImageUrl supports network address and local address, try to use absolute address
• Some configurations may only take effect when the real machine is running, and Alipay should improve it in the future

mp-weixin

配置编译到 MP-WEIXIN 平台时的特定样式

属性	类型	默认值	描述
homeButton	Boolean	false	在非首页、非页面栈最底层页面或非tabbar内页面中的导航栏展示home键
backgroundColorTop	HexColor	#ffffff	顶部窗口的背景色，仅 iOS 支持
backgroundColorBottom	HexColor	#ffffff	底部窗口的背景色，仅 iOS 支持
restartStrategy	String	homePage	重新启动策略配置。支持 homePage / homePageAndLatestPage
initialRenderingCache	String		页面初始渲染缓存配置。支持 static / dynamic
visualEffectInBackground	String	none	切入系统后台时，隐藏页面内容，保护用户隐私。支持 hidden / none
handleWebviewPreload	String	static	控制预加载下个页面的时机。支持 static / manual / auto

mp-baidu

配置编译到 MP-BAIDU 平台时的特定样式

属性	类型	默认值	描述
textSizeAdjust	String	auto	小程序页面是否禁止响应字体大小的设。支持 auto 默认响应 / none 不响应

FAQ

• Q: How to cancel the native navigation bar? or custom navigation
• A: Refer to Navigation Bar Development Guide

easycom

HBuilderX 2.5.5 supports easycom component mode.

Traditional vue components need to be installed, referenced, registered, and the components can be used after three steps. easycom boils it down to one step. As long as the component is installed in the root directory of the project or under the components directory of uni_modules, it conforms to the components/component name/component name.vue or uni_modules/plugin ID/components/component name/component name.vue directory structure. It can be used directly on the page without reference or registration. as follows:

<template>
	<view class="container">
		<uni-list>
			<uni-list-item title="第一行"></uni-list-item>
			<uni-list-item title="第二行"></uni-list-item>
		</uni-list>
	</view>
</template>
<script>
	// There is no need to import here, and there is no need to register the uni-list component in components. It can be used directly in the template
	export default {
		data() {
			return {

			}
		}
	}
</script>

No matter how many components are installed in the components directory, easycom will automatically remove unused components after packaging, which is especially friendly to the use of component libraries.

The component library is installed in batches, used at will, and automatically packaged on demand. Take the official uni-ui as an example, select the uni-ui project template on the HBuilderX new project interface, just type u on the page, pull out a large number of component code blocks, select directly, and you can use it. Greatly improve development efficiency and lower the threshold for use.

In the uni-app plug-in market, download components that conform to the components/component name/component name.vue directory structure, and you can use them directly.

easycom is automatically enabled and does not need to be manually enabled. When necessary, you can personalize settings in the easycom node of pages.json, such as disabling automatic scanning, or customizing the strategy of scanning and matching components. Set the parameters as follows:

Attribute	Type	Default Value	Description
autoscan	Boolean	true	Whether to enable auto-scanning, after it is enabled, it will automatically scan components that match the directory structure of components/component name/component name.vue
custom	Object	-	Customize component matching rules in a regular way. If autoscan does not meet your needs, you can use custom to customize the matching rules

Example of custom easycom configuration

If you need to match the vue files in node_modules, you need to use the matching rule in the form of packageName/path/to/vue-file-$1.vue, where packageName is the installed package name, /path/to/vue-file -$1.vue is the path of the vue file in the package.

"easycom": {
  "autoscan": true,
  "custom": {
    "^uni-(.*)": "@/components/uni-$1.vue", // 匹配components目录内的vue文件
    "^vue-file-(.*)": "packageName/path/to/vue-file-$1.vue" // 匹配node_modules内的vue文件
  }
}

illustrate

• Components introduced by easycom can be used on any page without import in the page, or declared in components
• Importing components in the easycom method is not a global import, but a local import. For example, on the H5 side, the components used will only be loaded when the corresponding page is loaded.
• When the component names are exactly the same, the priority of easycom import is lower than that of manual import (distinguish between hyphen form and camel case form)
• Considering the compilation speed, modifying easycom directly in pages.json will not trigger recompilation, it needs to be triggered by changing the page content.
• easycom only handles vue components, not MiniApp specific components (such as WeChat’s wxml format components). Components with the suffix .nvue are not processed. But vue components can also run full-end, including MiniApp and app-nvue. You can refer to uni ui, use the vue suffix, and be compatible with nvue pages.
• Components with .vue suffix in the nvue page will use native rendering in the nvue way, and unsupported css will be ignored. This case also supports easycom

tabBar

If the application is a multi-tab application, the tabBar configuration item can be used to specify the first-level navigation bar and the corresponding page displayed when tab switching.

Providing tabBar configuration in pages.json is not only to facilitate rapid development of navigation, but more importantly, to improve performance on the App and MiniApp side. On these two platforms, the underlying native engine can directly read the tabBar information configured in pages.json and render native tabs without waiting for the js engine to initialize when starting.

Tips

• When setting position to top, the icon will not be displayed
• The list in the tabBar is an array, and only a minimum of 2 and a maximum of 5 tabs can be configured, and the tabs are sorted according to the order of the array.
• Tabbar switching may not be rendered in time when it is loaded for the first time. You can pop up a waiting snowflake in the onLoad life cycle of each tabbar page (hello uni-app uses this method)
• After the tabbar page is displayed once, it will be kept in memory. Switching the tabbar page again will only trigger the onShow of each page, and will not trigger onLoad again.
• The tabbar at the top is currently only supported on the WeChat MiniApp. If you need to use the top tab, it is recommended not to use the top setting of the tabbar, but to make the top tab yourself, please refer to hello uni-app->template->top tab.

Property Description:

Properties	Type	Required	Default Value	Description	Platform Difference Description
color	HexColor	Yes		the default color of the text on the tab
selectedColor	HexColor	Yes		the color when the text on the tab is selected
backgroundColor	HexColor	is the background color of		tab
borderStyle	String	No	black	The color of the upper border of the tabbar, the optional value is black/white, and other color values are also supported	App 2.3.4+, H5 3.0.0+
blurEffect	String	No	none	iOS Gaussian blur effect, optional value dark/extralight/light/none (Reference: Instructions for use)	App 2.4.0+ support, H5 3.0.0+ (only supported by the latest version of the browser)
list	Array	is a list of		tabs, see the list property description for details, at least 2 and at most 5 tabs
position	String	No	bottom	Optional values bottom, top	The top value is only supported by WeChat MiniApp
fontSize	String	No	10px	Default text size	App 2.3.4+, H5 3.0.0+
iconWidth	String	No	24px	The default width of the icon (the height is proportionally scaled)	App 2.3.4+, H5 3.0.0+
spacing	String	No	3px	Space between icon and text	App 2.3.4+, H5 3.0.0+
height	String	No	50px	default height of tabBar	App 2.3.4+, H5 3.0.0+
midButton	Object	No		The middle button is only valid when the item in the list is even	App 2.3.4+, H5 3.0.0+
iconfontSrc	String	No		list When setting the iconfont attribute, you need to specify the path of the font file

Among them, list receives an array, each item in the array is an object, and its attribute values are as follows:

Attribute	Type	Required	Description	Platform Difference
pagePath	String	Yes	page path, must be defined in pages
text	String	is the text of the button on the tab, it is optional on App and H5 platforms. For example, a + icon without text can be placed in the middle
iconPath	String	No	Image path, the icon size is limited to 40kb, the recommended size is 81px * 81px, when the position is top, this parameter is invalid, does not support network images, does not support font icons
selectedIconPath	String	No	The image path when selected, the icon size is limited to 40kb, the recommended size is 81px * 81px, when the position is top, this parameter is invalid
visible	Boolean	No	Whether to display the item, the default display	App (3.2.10+), H5 (3.2.10+)
iconfont	Object	No	Font icon, priority is higher than iconPath	App (3.4.4+), H5 (3.5.3+)

midButton property description

Attribute	Type	Required	Default	Description
width	String	No	80px	The width of the middle button, the other items of the tabBar are divided equally after subtracting this width, and the default value is to divide the width equally with other items
height	String	No	50px	The height of the middle button can be greater than the height of the tabBar to achieve the raised effect in the middle
text	String	No		The text of the middle button
iconPath	String	No		The image path of the middle button
iconWidth	String	No	24px	Width of the picture (the height is proportionally scaled)
backgroundImage	String	No		The background image path of the middle button
iconfont	Object	No		Font icon, priority is higher than iconPath

midButton does not have a pagePath, it needs to monitor the click event, and handle the behavior logic after the click by itself. Listening to the click event is calling the API: uni.onTabBarMidButtonTap, see [https://uniapp.dcloud.io/api/ui/tabbar?id=ontabbarmidbuttontap](https://uniapp.dcloud.io/api/ui/tabbar ?id=ontabbarmidbuttontap)

iconfont parameter description:

Attribute	Type	Description
text	String	Font Unicode code
selectedText	String	Unicode code of selected font
fontSize	String	Font icon font size (px)
color	String	font icon color
selectedColor	String	font icon selected color

tabbar FAQ

• See Interface-Interface-tabbar for the js api of the tabbar, which can realize dynamic display and hiding (such as the pop-up layer cannot cover the tabbar), content modification (such as international Transformation), item plus corner mark and other functions. There are also examples in the hello uni-app.

• See onTabItemTap of the page life cycle for the item click event of the tabbar.

• The code jumps to the tabbar page, the api can only use uni.switchTab, cannot use uni.navigateTo, uni.redirectTo; use the navigator component open-type="switchTab" must be set when jumping

• The default height of the tabbar is different on different platforms. The default height of the App side is adjusted from 56px to 50px since HBuilderX 2.3.4, which is unified with the H5 side. Developers can also set the height by themselves and adjust it back to 56px. See details

• The tabbar is a div simulation on the H5 side, which is part of the front-end screen window. If you want to use the bottom positioning method, you should use the css variable --window-bottom, such as a button floating 10px above the tabbar, the style is as followsbottom: calc(var(--window-bottom) + 10px)

• An example of a tabbar template with a + sign in the middle, Reference. It can cross the end, but the + sign is not raised. If the middle is raised, configure the midButton of the tabbar.

• If you need to log in first and then enter the tab page, you don’t need to set the login page as the homepage, the homepage is still the tabbar page, you can refer to [Cloud-integrated login template](https://ext.dcloud.net.cn/plugin? id=13)

• The problem that the front-end pop-up mask layer cannot block the tabbar, and the tabbar is dynamically hidden during cross-end processing. You can use plus.nativeObj.view or subNVue on the App side to make pop-ups and masks. You can refer to this example of the sharing menu of native icons at the bottom

• Wechat MiniApp simulator version 1.02.1904090 has a bug. After zooming the simulator page percentage, the tabbar will freeze after clicking multiple times. There is no problem with the real machine, please pay attention when using it. See details

• On PC widescreen, when the page has a multi-window structure such as topWindow, leftWindow, or rightWindow, if you want to change the display position of the tabbar, please use [custom-tab-bar component](https://uniapp.dcloud.io/component /custom-tab-bar) configuration, if you want to hide the tabbar, you can use the following css (the advantage is that it can be linked with leftwindow and other forms):

    .uni-app--showleftwindow + .uni-tabbar-bottom {
    	display: none;
    }
  

code example

"tabBar": {
	"color": "#7A7E83",
	"selectedColor": "#3cc51f",
	"borderStyle": "black",
	"backgroundColor": "#ffffff",
	"list": [{
		"pagePath": "pages/component/index",
		"iconPath": "static/image/icon_component.png",
		"selectedIconPath": "static/image/icon_component_HL.png",
		"text": "组件"
	}, {
		"pagePath": "pages/API/index",
		"iconPath": "static/image/icon_API.png",
		"selectedIconPath": "static/image/icon_API_HL.png",
		"text": "接口"
	}]
}

Custom tabbar

The native tabBar is a relatively fixed configuration method, which may not satisfy all scenarios, which involves customizing the tabBar.

But note that except for the H5 side, the performance experience of the custom tabBar will be lower than that of the native tabBar. Do not customize the app and MiniApp unless necessary.

• Custom tabBar component on the H5 side: There is no concept of higher performance of the native tabBar on the H5 side, and the common tabBar under widescreen is at the top instead of the bottom. At this time, you can use [custom-tab-bar component](https://uniapp .dcloud.io/component/custom-tab-bar) to customize
• Ordinary custom tabBar: use view to draw tabBar by yourself. If the page is multi-page, switching the tabBar will not keep the bottom tabBar always displayed. Therefore, it is recommended to use the single-page method in this case. In the single-page mode, if it is a complex page, the application performance will drop significantly, and the page complexity needs to be reduced. If it is on the App side, the performance of nvue single page will be significantly higher than that of vue page
• WeChat MiniApp custom tabbar: WeChat provides a solution to customize tabBar based on webview. This function has a poor experience and is not recommended. If you want to use it, refer to WeChat Documentation,create a custom-tab-bar directory at the root of the project, and pay attention to the The code is wxml, wxss, not vue, and the uni-app compiler will directly copy the directory to the WeChat MiniApp
• There is only one native tabbar and it is on the home page. If you need tabs on the second-level page, you need to write a view to achieve it. Generally, the more suitable navigation for secondary pages is segment component

condition

The startup mode configuration takes effect only during the development period, and is used to simulate the scenario of direct access to the page, such as: after the MiniApp is forwarded, the user clicks on the opened page.

Property Description:

Attribute	Type	Required	Description
current	Number	Yes	the current active mode, the index value of the list node
list	Array	yes	list of boot modes

list description:

Attribute	Type	Required	Description
name	String	yes	boot mode name
path	String	Yes	Path of startup page
query	String	No	Startup parameters, which can be obtained in the onLoad function of the page

Note: You can directly open the configuration page when running on the real machine in the app. You need to manually change the compilation mode in the WeChat developer tools, as shown in the figure below:

Code sample:

"condition": { //模式配置，仅开发期间生效
	"current": 0, //当前激活的模式（list 的索引项）
	"list": [{
			"name": "swiper", //模式名称
			"path": "pages/component/swiper/swiper", //启动页面，必选
			"query": "interval=4000&autoplay=false" //启动参数，在页面的onLoad函数里面得到。
		},
		{
			"name": "test",
			"path": "pages/component/switch/switch"
		}
	]
}

subPackages

Subpackage loading configuration, this configuration is the subpackage loading mechanism of the MiniApp.

Because MiniApp have size and resource loading limitations, each MiniApp platform provides a subpackage method to optimize the download and startup speed of MiniApp.

The so-called main package is to place the default startup page/TabBar page, and all subpackages need to use public resources/JS scripts; and the subpackages are divided according to the configuration of pages.json.

When the MiniApp is started, the main package will be downloaded by default and the pages in the main package will be launched. When the user enters a page in the subpackage, the corresponding subpackage will be downloaded automatically, and then displayed after the download is complete. At this time, there will be a waiting prompt on the terminal interface.

App defaults to the whole package. Starting from uni-app 2.7.12+, it is also compatible with subpackage configuration of MiniApp. Its purpose is not to speed up the download, but to speed up the startup when the home page is vue. To enable subcontracting under App, in addition to configuring subcontracting rules in pages.json, you also need to set subcontracting settings on the app side in the manifest. For details, see: https://uniapp.dcloud.io/collocation/manifest?id=app-vue-optimization

The subPackages node receives an array, each item in the array is a sub-package of the application, and its attribute values are as follows:

Attribute	Type	Required	Description
root	String	Yes	the root directory of the subpackage
pages	Array	Yes	What pages are the subpackages composed of? The parameters are the same as pages

Notice:

• The path of pages in subPackages is a relative path under root, not a full path.
• The size of each subpackage of the WeChat MiniApp is 2M, and the total volume cannot exceed 20M.
• The size of each subpackage of the Baidu MiniApp is 2M, and the total volume cannot exceed 8M.
• The size of each subpackage of the Alipay MiniApp is 2M, and the total volume cannot exceed 8M.
• The size of each subpackage of the QQ MiniApp is 2M, and the total volume cannot exceed 24M.
• The size of each subpackage of the byte MiniApp is 2M, and the total volume cannot exceed 16M (the byte MiniApp basic library is supported by version 1.88.0 and above, and the byte MiniApp developer tool should be greater than or equal to 2.0.6 and versions less than 3.0.0). -The size of each subpackage of the Kuaishou MiniApp is 2M, and the total volume cannot exceed 24M.
• Support independent static directory under subpackage, which is used to subpackage static resources.
• uni-app supports WeChat applet, QQ MiniApp ,Baidu applet,Alipay MiniApp , MiniApp ( HBuilderX 3.0.3+ ), Kuaishou MiniApp MiniAppsubpackage optimization, that is, putting static resources or js files into subpackages does not occupy the size of the main package. For details, please refer to: [Instructions on Subcontract Optimization](/collocation/manifest?id=%E5%85%B3%E4%BA%8E%E5%88%86%E5%8C%85%E4%BC%98 %E5%8C%96%E7%9A%84%E8%AF%B4%E6%98%8E)
• When vendor.js is too large, you can use runtime compression code
  • For the project created by HBuilderX, check Run-->Run to MiniApp Simulator-->Whether to compress the code at runtime
  • The project created by cli can add the parameter --minimize in package.json, example: "dev:mp-weixin": "cross-env NODE_ENV=development UNI_PLATFORM=mp-weixin vue-cli- service uni-build --watch --minimize"

Instructions:

Assume that the directory structure of uni-app that supports subpackaging is as follows:

┌─pages
│  ├─index
│  │  └─index.vue
│  └─login
│     └─login.vue
├─pagesA
│  ├─static
│  └─list
│     └─list.vue
├─pagesB
│  ├─static
│  └─detail
│     └─detail.vue
├─static
├─main.js
├─App.vue
├─manifest.json
└─pages.json

You need to fill in pages.json

{
	"pages": [{
		"path": "pages/index/index",
		"style": { ...}
	}, {
		"path": "pages/login/login",
		"style": { ...}
	}],
	"subPackages": [{
		"root": "pagesA",
		"pages": [{
			"path": "list/list",
			"style": { ...}
		}]
	}, {
		"root": "pagesB",
		"pages": [{
			"path": "detail/detail",
			"style": { ...}
		}]
	}],
	"preloadRule": {
		"pagesA/list/list": {
			"network": "all",
			"packages": ["__APP__"]
		},
		"pagesB/detail/detail": {
			"network": "all",
			"packages": ["pagesA"]
		}
	}
}

preloadRule

Subpackage preload configuration.

After the preloadRule is configured, when entering a certain page of the MiniApp, the framework will automatically pre-download the subpackages that may be required to improve the startup speed when entering subsequent subpackage pages

In preloadRule, key is the page path, and value is the pre-download configuration for entering this page. Each configuration has the following items:

Field	Type	Required	Default	Description
packages	StringArray	Yes	None	The root or name of the pre-download subpackage after entering the page. __APP__ represents the main package.
network	String	No	wifi	Pre-download under the specified network, optional values are: all (unlimited network), wifi (only pre-download under wifi)

App subcontracting also supports preloadRule, but network rules are invalid.

FAQ

• Q: Why is the MiniApp location permission description configured in pages.json, but cannot be compiled to the MiniApp side? After running, it keeps prompting that getLocation needs to be declared in app.json
• A: The permission description of the WeChat MiniApp is configured in the manifest, not in pages.json. For details, refer to the document: https://uniapp.dcloud.io/collocation/manifest?id=mp-weixin