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	否	设置底部 tab 的表现
condition	Object	否	启动模式配置
subPackages	Object Array	否	分包加载配置	H5、uni-app x 不支持
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	否	大屏右侧窗口	H5
uniIdRouter	Object	否	自动跳转相关配置，新增于HBuilderX 3.5.0	uni-app x 不支持
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，小程序平台请参考相应小程序文档
navigationBarTextStyle	String	black	导航栏标题颜色及状态栏前景颜色，仅支持 black/white	支付宝小程序不支持，请使用 my.setNavigationBar
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	是否开启下拉刷新，详见页面生命周期。
onReachBottomDistance	Number	50	页面上拉触底事件触发时距页面底部距离，单位只支持px，详见页面生命周期	uni-app x 不支持
backgroundColorTop	HexColor	#ffffff	Background color of the top window (bounce area)	iOS only
backgroundColorBottom	HexColor	#ffffff	底部窗口的背景色（bounce回弹区域）	仅 iOS 平台
titleImage	String		导航栏图片地址（替换当前文字标题），支付宝小程序内必须使用https的图片链接地址	支付宝小程序、H5、APP(uni-app x 不支持)
transparentTitle	String	none	导航栏整体（前景、背景）透明设置。支持 always 一直透明 / auto 滑动自适应 / none 不透明	支付宝小程序、H5、APP(uni-app x 不支持)
titlePenetrate	String	NO	导航栏点击穿透	支付宝小程序、H5
pageOrientation	String	portrait	横屏配置，屏幕旋转设置，仅支持 auto / portrait / landscape 详见 响应显示区域变化	App 2.4.7+(uni-app x 不支持)、微信小程序、QQ小程序
animationType	String	pop-in	窗口显示的动画效果，详见：窗口动画	App(uni-app x 不支持)
animationDuration	Number	300	窗口显示动画的持续时间，单位为 ms	App(uni-app x 不支持)
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-baidu	Object		设置编译到 mp-baidu 平台的特定样式，配置项参考下方 MP-BAIDU	百度小程序
mp-toutiao	Object		设置编译到 mp-toutiao 平台的特定样式	抖音小程序
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		设置编译到 mp-jd 平台的特定样式	京东小程序
usingComponents	Object		引用小程序组件，参考 小程序组件	uni-app x 不支持
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		配置页面路径
style	Object		配置页面窗口表现，配置项参考下方 pageStyle
needLogin	Boolean	false	是否需要登录才可访问

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:

开发目录为：

	
┌─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，小程序平台请参考相应小程序文档
navigationBarTextStyle	String	black	导航栏标题颜色及状态栏前景颜色，仅支持 black/white
navigationBarTitleText	String		导航栏标题文字内容
navigationBarShadow	Object		导航栏阴影，配置参考下方 导航栏阴影	uni-app x 不支持
navigationStyle	String	default	导航栏样式，仅支持 default/custom。custom即取消默认的原生导航栏，需看使用注意	微信小程序 7.0+、百度小程序、H5、App（2.0.3+）
disableScroll	Boolean	false	设置为 true 则页面整体不能上下滚动（bounce效果），只在页面配置中有效，在globalStyle中设置无效	微信小程序（iOS）、百度小程序（iOS）
backgroundColor	HexColor	#ffffff	窗口的背景色	微信小程序、百度小程序、抖音小程序、飞书小程序、京东小程序
backgroundTextStyle	String	dark	下拉 loading 的样式，仅支持 dark/light	uni-app x 不支持
enablePullDownRefresh	Boolean	false	是否开启下拉刷新，详见页面生命周期。
onReachBottomDistance	Number	50	页面上拉触底事件触发时距页面底部距离，单位只支持px，详见页面生命周期	uni-app x 不支持
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	是否禁用滑动返回	App-iOS（3.4.0+）
titleImage	String		导航栏图片地址（替换当前文字标题），支付宝小程序内必须使用https的图片链接地址	支付宝小程序、H5、App(uni-app x 不支持)
transparentTitle	String	none	导航栏透明设置。支持 always 一直透明 / auto 滑动自适应 / none 不透明	支付宝小程序、H5、APP(uni-app x 不支持)
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		设置编译到 mp-baidu 平台的特定样式	百度小程序
mp-toutiao	Object		设置编译到 mp-toutiao 平台的特定样式	抖音小程序
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		设置编译到 mp-jd 平台的特定样式	京东小程序
usingComponents	Object		引用小程序组件，参考 小程序组件	App(uni-app x 不支持)、微信小程序、支付宝小程序、百度小程序、京东小程序
leftWindow	Boolean	true	When leftWindow exists, whether the current page displays leftWindow	H5
topWindow	Boolean	true	When topWindow exists, whether to display topWindow	H5	on the current page
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
background	HexColor	#FFFFFF	窗体背景色。无论vue页面还是nvue页面，在App上都有一个父级原生窗体，该窗体的背景色生效时间快于页面里的css生效时间	App (vue 页面需要将 body 背景色设为透明，uni-app x 不支持)
titleNView	Object		导航栏 ，详见:导航栏	App(uni-app x 不支持)、H5
subNVues	Array		原生子窗体，详见:原生子窗体	App 1.9.10+(uni-app x 不支持)
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	iOS软键盘上完成工具栏的显示模式，设置为 "none" 时关闭工具栏。	App-iOS
softinputMode	String	adjustPan	软键盘弹出模式，支持 adjustResize、adjustPan 两种模式	App(uni-app x 不支持)
pullToRefresh	Object		下拉刷新	App(uni-app x 不支持)
scrollIndicator	String		滚动条显示策略，设置为 "none" 时不显示滚动条。	App(uni-app x 不支持)
animationType	String	pop-in	窗口显示的动画效果，详见：窗口动画。	App(uni-app x 不支持)
animationDuration	Number	300	窗口显示动画的持续时间，单位为 ms。	App(uni-app x 不支持)

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		副标题文字颜色，颜色值格式为"#RRGGBB"和"rgba(R,G,B,A)"，如"#FF0000"表示标题文字颜色为红色。 默认值与主标题文字颜色一致	2.6.6
subtitleSize	String	"auto"	副标题文字字体大小，字体大小单位为像素，如"14px"表示字体大小为14像素，auto表示自动计算，约为12像素。	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		按钮上文字使用的字体文件路径。不支持网络地址，请统一使用本地地址。
select	Boolean	false	是否显示选择指示图标（向下箭头），常用于城市选择
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	是否允许向下拉拽。支持 YES / NO
titleImage	String		导航栏图片地址（替换当前文字标题），必须使用https的图片链接地址
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.

传统vue组件，需要安装、引用、注册，三个步骤后才能使用组件。easycom将其精简为一步。

只要组件路径符合规范（具体见下），就可以不用引用、注册，直接在页面中使用。如下：

<template>
	<view class="container">
		<comp-a></comp-a>
		<uni-list>
		</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>

路径规范指：

1. 安装在项目根目录的components目录下，并符合components/组件名称/组件名称.vue
2. 安装在uni_modules下，路径为uni_modules/插件ID/components/组件名称/组件名称.vue

工程目录：

	
┌─components            
│  └─comp-a
│    └─comp-a.vue      符合easycom规范的组件
└─uni_modules          [uni_module](/uni_modules)中符合easycom规范的组件
   └─uni_modules
     └─uni-list
       └─components
         └─uni-list
           └─ uni-list.vue
	

不管components目录下安装了多少组件，easycom打包会自动剔除没有使用的组件，对组件库的使用尤为友好。

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配置的示例

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

如果你的组件，不符合easycom前述的路径规范。可以在pages.json的easycom节点中自行定义路径规范。

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文件
  }
}

说明

• easycom方式引入的组件无需在页面内import，也不需要在components内声明，即可在任意页面使用。
• easycom方式引入组件不是全局引入，而是局部引入。例如在H5端只有加载相应页面才会加载使用的组件。
• 在组件名完全一致的情况下，easycom引入的优先级低于手动引入（区分连字符形式与驼峰形式）。
• 考虑到编译速度，直接在pages.json内修改easycom不会触发重新编译，需要改动页面内容触发。
• easycom只处理vue组件，不处理小程序专用组件（如微信的wxml格式组件）。不处理后缀为.nvue的组件。因为nvue页面引入的组件也是.vue组件。可以参考uni ui，使用vue后缀，同时兼容nvue页面。
• nvue页面里引用.vue后缀的组件，会按照nvue方式使用原生渲染，其中不支持的css会被忽略掉。这种情况同样支持easycom。
• vue 与 uvue 组件优先级，详见。

Bug & Tips

• HBuilderX 3.96 版本以下uni-app x项目，当页面文件名与easycom的组件名一样时，会渲染异常，可以通过调整页面文件名规避该Bug。

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	否	black	tabbar 上边框的颜色，可选值 black/white，也支持其他颜色值	App 2.3.4+ 、H5 3.0.0+
blurEffect	String	否	none	iOS 高斯模糊效果，可选值 dark/extralight/light/none（参考:使用说明）	App 2.4.0+ 支持(uni-app x 不支持)、H5 3.0.0+（只有最新版浏览器才支持）
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	否		list设置 iconfont 属性时，需要指定字体文件路径	App 3.4.4+、H5 3.5.3+
backgroundImage	String	否		设置背景图片,优先级高于 backgroundColor	App
backgroundRepeat	String	否		设置标题栏的背景图平铺方式，可取值："repeat" - 背景图片在垂直方向和水平方向平铺；"repeat-x" - 背景图片在水平方向平铺，垂直方向拉伸；"repeat-y" - 背景图片在垂直方向平铺，水平方向拉伸；"no-repeat" - 背景图片在垂直方向和水平方向都拉伸。 默认使用 "no-repeat"	App
redDotColor	String	否		tabbar上红点颜色	App

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	App (3.4.4+)

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.
• QQ小程序每个分包的大小是2M，总体积一共不能超过24M。
• 抖音小程序每个分包的大小是2M，总体积一共不能超过16M（抖音小程序基础库 1.88.0 及以上版本开始支持，抖音小程序开发者工具请使用大于等于 2.0.6 且小于 3.0.0 的版本）。 -The size of each subpackage of the Kuaishou MiniApp is 2M, and the total volume cannot exceed 24M.
• 分包下支持独立的 static 目录，用来对静态资源进行分包。
• uni-app内支持对微信小程序、QQ小程序、百度小程序、支付宝小程序、抖音小程序(HBuilderX 3.0.3+)、快手小程序分包优化，即将静态资源或者js文件放入分包内不占用主包大小。详情请参考：关于分包优化的说明
• 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:

假设支持分包的 uni-app 目录结构如下：

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