《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 里。