《UniApp 页面配置文件pages.json》
🧩 一、pages.json 是什么？
pages.json是 UniApp 项目中非常重要的全局配置文件，用来：
注册页面路径；
定义页面窗口样式；
设置底部 tabBar；
配置路由、导航栏、动画等。
它控制着整个 App 的页面结构和外观。
修改
pages.json后要重新编译才能生效；如果页面路径错误，会直接报错 “找不到页面”；
pages.json的顺序决定了 首页（第一个页面）；不同平台有些属性不生效（如
gestureBack只在 App 有效）。
📘 二、基本结构
{"pages": [{"path": "pages/index/index","style": {"navigationBarTitleText": "首页","navigationBarBackgroundColor": "#ffffff","navigationBarTextStyle": "black"}},{"path": "pages/user/user","style": {"navigationBarTitleText": "我的"}}],"tabBar": {"color": "#666666","selectedColor": "#007AFF","backgroundColor": "#ffffff","borderStyle": "black","list": [{"pagePath": "pages/index/index","text": "首页","iconPath": "static/icon/home.png","selectedIconPath": "static/icon/home-active.png"},{"pagePath": "pages/user/user","text": "我的","iconPath": "static/icon/user.png","selectedIconPath": "static/icon/user-active.png"}]},"globalStyle": {"navigationBarTextStyle": "white","navigationBarTitleText": "UniApp示例","navigationBarBackgroundColor": "#007AFF","backgroundColor": "#F8F8F8"}
}
⚙️ 三、常用配置项讲解
1️⃣ pages（页面注册）
每个页面都必须在这里注册，否则不会被编译。
path：页面路径（必须与实际文件路径一致）；style：页面样式配置（相当于页面级page.json）。
2️⃣ style（页面配置）
控制单个页面的窗口表现。
常用属性：
| 属性名 | 说明 | 示例 |
|---|---|---|
| navigationBarTitleText | 导航栏标题 | "我的页面" |
| navigationBarBackgroundColor | 导航栏背景色 | "#ffffff" |
| navigationBarTextStyle | 导航栏文字颜色 | "black" 或 "white" |
| navigationStyle | 自定义导航栏 | "custom"（用于自定义导航栏） |
| enablePullDownRefresh | 是否开启下拉刷新 | true |
| backgroundColor | 页面背景颜色 | "#f8f8f8" |
| backgroundTextStyle | 下拉 loading 样式 | "dark" 或 "light" |
| disableScroll | 禁止页面滚动 | true |
| onReachBottomDistance | 触底距离触发加载事件 | 50 |
| gestureBack | 是否开启 iOS 侧滑返回 | true |
3️⃣ globalStyle（全局默认样式）
对所有页面生效，除非单页覆盖：
"globalStyle": {"navigationBarTextStyle": "white","navigationBarBackgroundColor": "#007AFF","backgroundColor": "#F8F8F8"
}
4️⃣ tabBar（底部导航栏）
配置应用底部的固定导航栏：
| 属性 | 含义 |
|---|---|
| color | 默认文字颜色 |
| selectedColor | 选中时文字颜色 |
| backgroundColor | 背景颜色 |
| borderStyle | 上边框颜色（black/white） |
| list | tab 列表，每项包含 pagePath、text、iconPath、selectedIconPath |
5️⃣ 其他重要配置
| 配置项 | 说明 |
|---|---|
subPackages | 分包加载配置（用于大项目） |
preloadRule | 预加载页面 |
condition | 启动调试时的默认启动页面 |
animationType | 页面切换动画类型 |
animationDuration | 页面切换动画时长（ms） |
🧱 四、navigationStyle: custom（自定义导航栏）
如果你想使用自定义导航栏（比如封装的 CustomNavBar），要在对应页面的 style 中加上：
{"navigationStyle": "custom"
}
⚠️ 这样系统的导航栏会被隐藏，需要自己手动适配状态栏和标题栏高度。
⚠️ 五、单页面 page.json（Vue 文件内）
在 Vue 页面文件中，你也可以写 export default 内的 navigationBarTitleText 配置，但推荐放在 pages.json 里。