

English
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.
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
}
}
}
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
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 tooltitleImage
set in globalStyle
will also override the text title set in pages
->style
maxWidth
, the fixed elements in the page need to use --window-left, --window-right to ensure the correct layout positiondynamicRpx
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 pxuni-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
App.vue
according to different requirements:
/* 隐藏路径为 pages/component/view/view 页面的 navigationBar */
.uni-app--showtopwindow [data-page="pages/component/view/view"] uni-page-head {
display: none;
}
/* 隐藏所有页面的 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;
}
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 /)
Same as topWindow
Same as topWindow
Window communication reference: https://uniapp.dcloud.net.cn/api/window/communication
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:
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": { ... }
}
]
}
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
maxWidth
, the fixed elements in the page need to use --window-left, --window-right to ensure the correct layout positionCode sample:
{
"pages": [{
"path": "pages/index/index",
"style": {
"navigationBarTitleText": "首页",//设置页面标题文字
"enablePullDownRefresh":true//开启下拉刷新
}
},
...
]
}
Notice
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 toolWhen 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:
<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>
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.
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
.nvue
page only supports titleNView, pullToRefresh, scrollIndicator
configuration, other configuration items are not currently supportedAttribute | 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 |
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
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.type
value of titleNView
is transparent
buttons
in titleNView
, listen to the click event of the button, refer to the weex compilation mode of the vue page and nvue: uni.onNavigationBarButtonTapsearchInput
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)[<navigation-bar>(/component/navigation-bar)]
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 |
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. |
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. |
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.
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
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
id
of subNVues
is globally unique and cannot be repeatedsubNVues
can be obtained via uni.getSubNVueById('id')path
property of subNVues
can only be nvue
file pathAttribute | 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"
}
}]
}
}
}]
}
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
enablePullDownRefresh
and pullToRefresh->support
are set at the same time, the latter takes precedence.enablePullDownRefresh
property of the page to true.enablePullDownRefresh
property of the page, but configure pullToRefresh->support
to true.<refresh>
component. From HBuilderX 2.0.3+, you can experience the news template by selecting a new projectcode example
{
"pages": [
{
"path": "pages/index/index", //首页
"style": {
"app-plus": {
"pullToRefresh": {
"support": true,
"color": "#ff3333",
"style": "default",
"contentdown": {
"caption": "下拉可刷新自定义文本"
},
"contentover": {
"caption": "释放可刷新自定义文本"
},
"contentrefresh": {
"caption": "正在刷新自定义文本"
}
}
}
}
}
]
}
Configure specific styles when compiling to the H5 platform
Attribute | Type | Description |
---|---|---|
titleNView | Object | Navigation Bar |
pullToRefresh | Object | pull to refresh |
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 |
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 |
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. |
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. |
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:
h5
node is not configured, the configuration under app-plus
will be used by default.h5
node is configured, it will override the configuration under app-plus
.Attribute | Type | Description |
---|---|---|
colorType | String | Shadow color, support: gray, blue, green, orange, red, yellow |
Precautions:
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 titlebackgroundImageUrl
supports network address and local address, try to use absolute address配置编译到 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 平台时的特定样式
属性 | 类型 | 默认值 | 描述 |
---|---|---|---|
textSizeAdjust | String | auto | 小程序页面是否禁止响应字体大小的设。支持 auto 默认响应 / none 不响应 |
HBuilderX 2.5.5
supportseasycom
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
easycom
can be used on any page without import
in the page, or declared in components
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.easycom
import is lower than that of manual import (distinguish between hyphen form and camel case form)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..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
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
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 |
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": "接口"
}]
}
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.
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"
}
]
}
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:
subPackages
is a relative path under root
, not a full path.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 MiniApp
subpackage 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)vendor.js
is too large, you can use runtime compression code
HBuilderX
, check Run-->Run to MiniApp Simulator-->Whether to compress the code at runtime
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"]
}
}
}
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.