uniapp pages.json 页面路由

pages.json 页面路由

pages.json 文件用来对 uni-app 进行全局配置，决定页面文件的路径、窗口样式、原生的导航栏、底部的原生tabbar 等。

它类似微信小程序中app.json的页面管理部分。注意定位权限申请等原属于app.json的内容，在uni-app中是在manifest中配置。

配置项列表

以下是一个包含了所有配置选项的 pages.json ：

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

用于设置应用的状态栏、导航条、标题、窗口背景色等。

注意

• 支付宝小程序使用titleImage时必须使用https的图片链接地址，需要真机调试才能看到效果，支付宝开发者工具内无效果
• globalStyle中设置的titleImage也会覆盖掉pages->style内的设置文字标题
• 使用 maxWidth 时，页面内fixed元素需要使用–window-left,–window-right来保证布局位置正确
• dynamicRpx vue3 nvue页面已移除此配置，升级为横竖屏切换自动rpx，如果不需要可以使用 px

topWindow

uni-app 2.9+ 新增 leftWindow, topWindow, rightWindow 配置。用于解决宽屏适配问题。

以现有的手机应用为mainWindow，在左、上、右，可以追加新的页面显示窗体。

整体的宽屏适配思路，参考单独的宽屏适配指南

注意

• 目前 style 节点仅支持配置 width，height 等 css 样式相关属性

• 如果需求当存在 topwindow 时，自动隐藏页面的 navigationBar，根据需求不同在

  App.vue
  

  中配置如下 css：

  • 只需要隐藏某个的页面 navigationBar

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

    复制代码

  • 需要隐藏大部分页面的 navigationBar，显示某个页面的 navigationBar

    /* 隐藏所有页面的 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

通过matchMedia的调节，可以自适应在不同屏幕上显示指定的window。

{
  "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时显示
    }
  }
}

复制代码

案例演示：HBuilderX 2.9.9+，新建项目选择hello uni-app或新闻模板，或直接浏览：https://hellouniapp.dcloud.net.cn/

leftWindow

与topWindow相同

ightWindow

与topWindow相同

窗口通信参考：https://uniapp.dcloud.net.cn/api/window/communication

pages

uni-app 通过 pages 节点配置应用由哪些页面组成，pages 节点接收一个数组，数组每个项都是一个对象，其属性值如下：

Tips：

• pages节点的第一项为应用入口页（即首页）
• 应用中新增/减少页面，都需要对 pages 数组进行修改
• 文件名不需要写后缀，框架会自动寻找路径下的页面资源

代码示例：

开发目录为：

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

则需要在 pages.json 中填写

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

复制代码

style

用于设置每个页面的状态栏、导航条、标题、窗口背景色等。

页面中配置项会覆盖 globalStyle 中相同的配置项

注意

• 使用 maxWidth 时，页面内fixed元素需要使用–window-left,–window-right来保证布局位置正确

代码示例：

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

复制代码

注意

• 支付宝小程序使用titleImage时必须使用https的图片链接地址，需要真机调试才能看到效果，支付宝开发者工具内无效果

自定义导航栏使用注意

当navigationStyle设为custom或titleNView设为false时，原生导航栏不显示，此时要注意几个问题：

• 非H5端，手机顶部状态栏区域会被页面内容覆盖。这是因为窗体是沉浸式的原因，即全屏可写内容。uni-app提供了状态栏高度的css变量–status-bar-height，如果需要把状态栏的位置从前景部分让出来，可写一个占位div，高度设为css变量。

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

复制代码

• 如果原生导航栏不能满足需求，推荐使用uni ui的自定义导航栏NavBar。这个前端导航栏自动处理了状态栏高度占位问题。

• 前端导航栏搭配原生下拉刷新时，会有问题，包括

  • 微信小程序下iOS需要拉更长才能看到下拉刷新的三个点，而Android是从屏幕顶部下拉，无法从导航栏下方下拉。如果一定要从前端导航栏下拉，小程序下只能放弃原生下拉刷新，纯前端模拟，参考mescroll插件，但这样很容易产生性能问题。目前小程序平台自身没有提供更好的方案
  • App和H5下，原生下拉刷新提供了circle样式，可以指定offset偏移量（pages.json的app-plus下配置），自定义下拉圈出现的位置。在hello uni-app的扩展组件中有示例。

• 非H5端，前端导航盖不住原生组件。如果页面有video、map、textarea(仅小程序)等

  原生组件

  ，滚动时会覆盖住导航栏

  • 如果是小程序下，可以使用cover-view来做导航栏，避免覆盖问题
  • 如果是App下，建议使用titleNView或subNVue，体验更好

• 前端组件在渲染速度上不如原生导航栏，原生导航可以在动画期间渲染，保证动画期间不白屏，但使用前端导航栏，在新窗体进入的动画期间可能会整页白屏，越低端的手机越明显。

• 以上讨论的是前端自定义导航栏，但在App侧，原生导航栏也提供了比小程序导航更丰富的自定义性

  • titleNView：给原生导航栏提供更多配置，包括自定义按钮、滚动渐变效果、搜索框等，详见titleNView
  • subNVue：使用nvue原生渲染，所有布局自己开发，具备一切自定义灵活度。详见subNVue

• 页面禁用原生导航栏后，想要改变状态栏的前景字体样式，仍可设置页面的 navigationBarTextStyle 属性（只能设置为 black或white）。如果想单独设置状态栏颜色，App端可使用plus.navigator.setStatusBarStyle设置。注意部分低端Android手机（4.4）自身不支持设置状态栏前景色。

鉴于以上问题，在原生导航能解决业务需求的情况下，尽量使用原生导航。甚至有时需要牺牲一些不是很重要的需求。在App和H5下，uni-app提供了灵活的处理方案：titleNView、subNVue、或整页使用nvue。但在小程序下，因为其自身的限制，没有太好的方案。有必要的话，也可以用条件编译分端处理。

app-plus

配置编译到 App 平台时的特定样式，部分常用配置 H5 平台也支持。以下仅列出常用，更多配置项参考 WebviewStyles。

Tips

• .nvue 页面仅支持 titleNView、pullToRefresh、scrollIndicator 配置，其它配置项暂不支持

导航栏

SplitLineStyles

Tips

• 页面支持通过配置 navigationStyle为custom，或titleNView为false，来禁用原生导航栏。一旦禁用原生导航，请注意阅读自定义导航注意事项。
• titleNView 的 type 值为 transparent 时，导航栏为滚动透明渐变导航栏，默认只有button，滚动后标题栏底色和title文字会渐变出现，不支持自定义按钮设置color属性； type 为 float 时，导航栏为悬浮标题栏，此时页面内容上顶到了屏幕顶部，包括状态栏，但导航栏悬浮盖在页面上方，一般这种场景会同时设置导航栏的背景色为rgba半透明颜色。
• titleNView 的 type 值为 transparent 时，App-nvue 2.4.4+ 支持
• 在 titleNView 配置 buttons 后，监听按钮的点击事件，vue 页面及 nvue 的weex编译模式参考：uni.onNavigationBarButtonTap
• 在 titleNView 配置 searchInput 后，相关的事件监听参考：onNavigationBarSearchInputChanged 等
• 可通过 [<navigation-bar>(/component/navigation-bar)] 配置
• App下原生导航栏的按钮如果使用字体图标，注意检查字体库的名字（font-family）是否使用了默认的 iconfont，这个名字是保留字，不能作为外部引入的字体库的名字，需要调整为自定义的名称，否则无法显示。
• 想了解各种导航栏的开发方法，请详读导航栏开发指南

自定义按钮

自定义返回按钮的样式

当autoBackButton设置为true时生效。 通过此属性可自定义返回按钮样式，如图标大小、红点、角标、标题等。

HBuilderX 2.6.3+ 支持

按钮样式

使用 type 值设置按钮的样式时，会忽略 fontSrc 和 text 属性。

搜索框配置

searchInput可以在titleNView的原生导航栏上放置搜索框。其宽度根据周围元素自适应。

searchInput Tips

searchInput的点击输入框onNavigationBarSearchInputClicked、文本变化onNavigationBarSearchInputChanged、点击搜索按钮onNavigationBarSearchInputConfirmed等生命周期，见文档页面生命周期。

• 在生命周期里通过参数e.text，可获取输入框内容。具体见hello uni-app中模板-顶部导航栏中的示例
• 如需动态修改searchInput，或者获取searchInput的placehold，参考uni-app动态修改App端导航栏

常见titleNView配置代码示例

以下列出部分配置。关于全面的导航栏配置，这里有一个完善的演示工程，演示了导航栏的各种效果，详见：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

• buttons 的 text 推荐使用字体图标。如果使用了汉字或英文，推荐把字体改小一点，否则文字长度增加后，距离屏幕右边距太近。
• App平台，buttons动态修改，详见
• App平台，buttons角标动态修改，见 hello uni-app 中模板-顶部导航标题栏-导航栏带红点和角标
• App平台，设置searchInput的文字动态修改，API见文档。注意disable状态无法设置文字、placehold暂不支持动态设置
• H5平台，如需实现上述动态修改，需在条件编译通过dom操作修改

原生子窗体

subNVues 是 vue 页面的原生子窗体。用于解决App中 vue 页面中的层级覆盖和原生界面灵活自定义用的。

它不是全屏页面，也不是组件，就是一个原生子窗体。它是一个 nvue 页面，使用 weex 引擎渲染，提供了比 cover-view、plus.nativeObj.view 更强大的原生排版能力，方便自定义原生导航或覆盖原生地图、视频等。请详读subNVues 开发指南

subNVue 也可以在 nvue 页面中使用。但目前在纯nvue下（render为native）还不支持。

Tips

• subNVues 的 id 是全局唯一的，不能重复
• 可以通过 uni.getSubNVueById(‘id’) 获取 subNVues 的实例
• subNVues 的 path 属性只能是 nvue 文件路径

原生子窗体样式

代码示例

{
	"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"
					}

				}]
			}
		}
	}]
}

复制代码

下拉刷新

在 App 平台下可以自定义部分下拉刷新的配置 page->style->app-plus->pullToRefresh。

下拉刷新使用注意

• enablePullDownRefresh 与 pullToRefresh->support 同时设置时，后者优先级较高。
• 如果期望在 App 和小程序上均开启下拉刷新的话，请配置页面的 enablePullDownRefresh 属性为 true。
• 若仅期望在 App 上开启下拉刷新，则不要配置页面的 enablePullDownRefresh 属性，而是配置 pullToRefresh->support 为 true。
• 开启原生下拉刷新时，页面里不应该使用全屏高的scroll-view，向下拖动内容时，会优先触发下拉刷新而不是scroll-view滚动
• 原生下拉刷新的起始位置在原生导航栏的下方，如果取消原生导航栏，使用自定义导航栏，原生下拉刷新的位置会在屏幕顶部。如果希望在自定义导航栏下方拉动，只能使用circle方式的下拉刷新，并设置offset参数，将circle圈的起始位置调整到自定义导航栏下方。hello uni-app的扩展组件中有示例。
• 如果想在app端实现更多复杂的下拉刷新，比如美团、京东App那种拉下一个特殊图形，可以使用nvue的<refresh>组件。HBuilderX 2.0.3+起，新建项目选择新闻模板可以体验
• 如果想在vue页面通过web前端技术实现下拉刷新，插件市场有例子，但前端下拉刷新的性能不如原生，复杂长列表会很卡
• iOS上，default模式的下拉刷新和bounce回弹是绑定的，如果设置了bounce:none，会导致无法使用default下拉刷新

代码示例

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

复制代码

h5

配置编译到 H5 平台时的特定样式

导航栏

自定义按钮

按钮样式

使用 type 值设置按钮的样式时，会忽略 fontSrc 和 text 属性。

下拉刷新

h5 平台下拉刷新动画，只有 circle 类型。

搜索框样式

注意事项：

• 如果 h5 节点没有配置，默认会使用 app-plus 下的配置。
• 配置了 h5 节点，则会覆盖 app-plus 下的配置。

navigationBarShadow

注意事项：

• 微信/百度/头条 需要配置: “disableScroll”: true
• 支付宝 “mp-alipay”: { “allowsBounceVertical”: “NO” }

mp-alipay

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

注意事项

• titleImage仅支持https地址，设置了titleImage会替换页面文字标题
• backgroundImageUrl支持网络地址和本地地址，尽量使用绝对地址
• 部分配置可能会只在真机运行的时候生效，支付宝未来应该会改善

mp-weixin

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

mp-baidu

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

FAQ

• Q：如何取消原生导航栏？或自定义导航
• A：参考导航栏开发指南

easycom

HBuilderX 2.5.5起支持easycom组件模式。

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

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

<template>
	<view class="container">
		<comp-a></comp-a>
		<uni-list>
		</uni-list>
	</view>
</template>
<script>
	// 这里不用import引入，也不需要在components内注册uni-list组件。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](/plugin/uni_modules.md)中符合easycom规范的组件
   └─uni_modules
     └─uni-list
       └─components
         └─uni-list
           └─ uni-list.vue
	

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

组件库批量安装，随意使用，自动按需打包。以官方的uni-ui为例，在HBuilderX新建项目界面选择uni-ui项目模板，只需在页面中敲u，拉出大量组件代码块，直接选择，即可使用。大幅提升开发效率，降低使用门槛。

在uni-app插件市场下载符合components/组件名称/组件名称.vue目录结构的组件，均可直接使用。

自定义easycom配置的示例

easycom是自动开启的，不需要手动开启，有需求时可以在pages.json的easycom节点进行个性化设置，如关闭自动扫描，或自定义扫描匹配组件的策略。设置参数如下：

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

如果需要匹配node_modules内的vue文件，需要使用packageName/path/to/vue-file-$1.vue形式的匹配规则，其中packageName为安装的包名，/path/to/vue-file-$1.vue为vue文件在包内的路径。

"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

如果应用是一个多 tab 应用，可以通过 tabBar 配置项指定一级导航栏，以及 tab 切换时显示的对应页。

在 pages.json 中提供 tabBar 配置，不仅仅是为了方便快速开发导航，更重要的是在App和小程序端提升性能。在这两个平台，底层原生引擎在启动时无需等待js引擎初始化，即可直接读取 pages.json 中配置的 tabBar 信息，渲染原生tab。

Tips

• 当设置 position 为 top 时，将不会显示 icon
• tabBar 中的 list 是一个数组，只能配置最少2个、最多5个 tab，tab 按数组的顺序排序。
• tabbar 切换第一次加载时可能渲染不及时，可以在每个tabbar页面的onLoad生命周期里先弹出一个等待雪花（hello uni-app使用了此方式）
• tabbar 的页面展现过一次后就保留在内存中，再次切换 tabbar 页面，只会触发每个页面的onShow，不会再触发onLoad。
• 顶部的 tabbar 目前仅微信小程序上支持。需要用到顶部选项卡的话，建议不使用 tabbar 的顶部设置，而是自己做顶部选项卡，可参考 hello uni-app->模板->顶部选项卡。

属性说明：

其中 list 接收一个数组，数组中的每个项都是一个对象，其属性值如下：

midButton 属性说明

midButton没有pagePath，需监听点击事件，自行处理点击后的行为逻辑。监听点击事件为调用API：uni.onTabBarMidButtonTap，详见https://uniapp.dcloud.io/api/ui/tabbar?id=ontabbarmidbuttontap

iconfont参数说明：

tabbar常见问题

• tabbar 的 js api 见接口-界面-tabbar，可实现动态显示隐藏（如弹出层无法覆盖tabbar）、内容修改（如国际化）、item加角标等功能。hello uni-app中也有示例。

• tabbar 的 item 点击事件见页面生命周期的onTabItemTap。

• 代码跳转到 tabbar 页面，api只能使用uni.switchTab，不能使用uni.navigateTo、uni.redirectTo；使用navigator组件跳转时必须设置open-type=“switchTab”

• tabbar 的默认高度，在不同平台不一样。App端的默认高度在HBuilderX 2.3.4起从56px调整为50px，与H5端统一。开发者也可以自行设定高度，调回56px。详见

• tabbar 在H5端是div模拟的，属于前端屏幕窗口的一部分，如果要使用bottom居底定位方式，应该使用css变量--window-bottom，比如悬浮在tabbar上方10px的按钮，样式如下bottom: calc(var(--window-bottom) + 10px)

• 中间带+号的tabbar模板例子，参考。可跨端，但+号不凸起。如需中间凸起，配置tabbar的midButton。

• 如果是需要先登录、后进入tab页面，不需要把登录页设为首页，首页仍然是tabbar页，可参考云端一体登录模板

• 前端弹出遮罩层挡不住tabbar的问题，跨端处理方式时动态隐藏tabbar。App端可以使用plus.nativeObj.view或subNVue做弹出和遮罩，可参考这个底部原生图标分享菜单例子

• 微信小程序模拟器1.02.1904090版有bug，在缩放模拟器页面百分比后，tabbar点击多次后就会卡死。真机无碍，使用时注意。详见

• PC宽屏上，当页面存在topWindow或leftWindow或rightWindow等多窗体结构时，若想改变 tabbar 显示的位置，请使用 custom-tab-bar组件 配置，若想隐藏 tabbar，可以使用如下 css（好处是可以和 leftwindow 等窗体联动）：

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

  复制代码

代码示例

"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": "接口"
	}]
}

复制代码

自定义tabbar

原生tabBar是相对固定的配置方式，可能无法满足所有场景，这就涉及到自定义tabBar。

但注意除了H5端，自定义tabBar的性能体验会低于原生tabBar。App和小程序端非必要不要自定义。

• H5端的自定义tabBar组件：H5端不存在原生tabBar性能更高的概念，并且宽屏下常见的tabBar在顶部而不是底部，此时可以使用 custom-tab-bar组件 来自定义
• 普通自定义tabBar：使用view自行绘制tabBar。如果页面是多页方式，切换tabBar将无法保持底部tabBar一直显示。所以这种情况建议使用单页方式。单页方式，如果是复杂页面，应用性能会下降明显，需减少页面复杂度。如果是App端，nvue单页的性能会显著高于vue页面
• 微信小程序自定义tabbar：微信提供一直基于webview自定义tabBar的方案。该功能体验不佳，不太推荐使用。如果要使用，参考微信文档，项目根创建 custom-tab-bar 目录，注意里边的代码是 wxml,wxss，不是 vue，uni-app编译器会直接拷贝该目录到微信小程序中
• 原生的tabbar有且只有一个且在首页。二级页如需的tab，需自行编写view来实现。一般二级页面更适合的导航是 segement组件

condition

启动模式配置，仅开发期间生效，用于模拟直达页面的场景，如：小程序转发后，用户点击所打开的页面。

属性说明：

list说明：

注意： 在 App 里真机运行可直接打开配置的页面，微信开发者工具里需要手动改变编译模式，如下图：

代码示例：

"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

分包加载配置，此配置为小程序的分包加载机制。

因小程序有体积和资源加载限制，各家小程序平台提供了分包方式，优化小程序的下载和启动速度。

所谓的主包，即放置默认启动页面/TabBar 页面，以及一些所有分包都需用到公共资源/JS 脚本；而分包则是根据pages.json的配置进行划分。

在小程序启动时，默认会下载主包并启动主包内页面，当用户进入分包内某个页面时，会把对应分包自动下载下来，下载完成后再进行展示。此时终端界面会有等待提示。

App默认为整包。从uni-app 2.7.12+ 开始，也兼容了小程序的分包配置。其目的不用于下载提速，而用于首页是vue时的启动提速。App下开启分包，除在pages.json中配置分包规则外，还需要在manifest中设置在app端开启分包设置，详见：https://uniapp.dcloud.io/collocation/manifest?id=app-vue-optimization

subPackages 节点接收一个数组，数组每一项都是应用的子包，其属性值如下：

注意：

• subPackages 里的pages的路径是 root 下的相对路径，不是全路径。

• 微信小程序每个分包的大小是2M，总体积一共不能超过20M。

• 百度小程序每个分包的大小是2M，总体积一共不能超过8M。

• 支付宝小程序每个分包的大小是2M，总体积一共不能超过8M。

• QQ小程序每个分包的大小是2M，总体积一共不能超过24M。

• 抖音小程序每个分包的大小是2M，总体积一共不能超过16M（抖音小程序基础库 1.88.0 及以上版本开始支持，抖音小程序开发者工具请使用大于等于 2.0.6 且小于 3.0.0 的版本）。

• 快手小程序每个分包的大小是2M，总体积一共不能超过24M。

• 分包下支持独立的 static 目录，用来对静态资源进行分包。

• uni-app内支持对微信小程序、QQ小程序、百度小程序、支付宝小程序、抖音小程序(HBuilderX 3.0.3+)、快手小程序分包优化，即将静态资源或者js文件放入分包内不占用主包大小。详情请参考：关于分包优化的说明

• 针对

  vendor.js
  

  过大的情况可以使用运行时压缩代码

  • HBuilderX创建的项目勾选运行-->运行到小程序模拟器-->运行时是否压缩代码
  • cli创建的项目可以在package.json中添加参数--minimize，示例："dev:mp-weixin": "cross-env NODE_ENV=development UNI_PLATFORM=mp-weixin vue-cli-service uni-build --watch --minimize"

使用方法：

假设支持分包的 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
	

则需要在 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": [""]
		},
		"pagesB/detail/detail": {
			"network": "all",
			"packages": ["pagesA"]
		}
	}
}

复制代码

preloadRule

分包预载配置。

配置preloadRule后，在进入小程序某个页面时，由框架自动预下载可能需要的分包，提升进入后续分包页面时的启动速度

preloadRule 中，key 是页面路径，value 是进入此页面的预下载配置，每个配置有以下几项：

app的分包，同样支持preloadRule，但网络规则无效。文章来源地址https://www.toymoban.com/news/detail-819322.html

FAQ

• Q：为什么在pages.json里配置小程序定位权限描述，无法编译到小程序端，运行后一直提示getLocation需要在app.json中声明
• A：微信小程序的权限描述配置在manifest中，不在pages.json中，具体参考文档：https://uniapp.dcloud.io/collocation/manifest?id=mp-weixin

到了这里，关于uniapp pages.json 页面路由的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！