Skip to main content

Uni-app 全局配置文件 pages.json 详解

pages.json 是 uni-app 项目的核心全局配置文件，用于配置页面路由、窗口表现、导航栏样式、底部 tab 栏等应用级设置。以下是该文件的全面解析：

一、基本结构

{
  "pages": [],
  "globalStyle": {},
  "tabBar": {},
  "condition": {},
  "subPackages": [],
  "preloadRule": {},
  "easycom": {}
}

二、pages 页面路由配置

1. 基本页面配置

"pages": [
  {
    "path": "pages/index/index",
    "style": {
      "navigationBarTitleText": "首页",
      "enablePullDownRefresh": true
    }
  },
  {
    "path": "pages/user/user",
    "style": {
      "navigationBarTitleText": "个人中心",
      "navigationBarBackgroundColor": "#007AFF"
    }
  }
]

2. 关键配置项

  • path: 页面路径（无需写后缀名）
  • style: 页面窗口表现配置
    • navigationBarTitleText: 导航栏标题文字内容
    • navigationBarBackgroundColor: 导航栏背景颜色（十六进制）
    • navigationBarTextStyle: 导航栏标题颜色（仅 black/white）
    • backgroundColor: 窗口背景色
    • enablePullDownRefresh: 是否开启下拉刷新

三、globalStyle 全局窗口样式

"globalStyle": {
  "navigationBarTextStyle": "black",
  "navigationBarTitleText": "uni-app",
  "navigationBarBackgroundColor": "#F8F8F8",
  "backgroundColor": "#FFFFFF",
  "app-plus": {
    "titleNView": {
      "buttons": [
        {
          "text": "分享",
          "fontSize": "16px",
          "width": "60px"
        }
      ]
    }
  }
}

特殊平台配置

  • h5: H5 特有配置
  • mp-weixin: 微信小程序特有配置
  • app-plus: App 特有配置

四、tabBar 底部选项卡

"tabBar": {
  "color": "#7A7E83",
  "selectedColor": "#007AFF",
  "backgroundColor": "#F8F8F8",
  "borderStyle": "black",
  "list": [
    {
      "pagePath": "pages/index/index",
      "iconPath": "static/tabbar/home.png",
      "selectedIconPath": "static/tabbar/home_selected.png",
      "text": "首页"
    },
    {
      "pagePath": "pages/user/user",
      "iconPath": "static/tabbar/user.png",
      "selectedIconPath": "static/tabbar/user_selected.png",
      "text": "我的"
    }
  ],
  "position": "bottom"
}

配置说明

  • list: 最少2个、最多5个 tab
  • position: 可选 bottom/top（仅微信小程序支持 top）
  • 图标建议尺寸：81px * 81px

五、subPackages 分包加载

"subPackages": [
  {
    "root": "pagesA",
    "pages": [
      {
        "path": "list/list",
        "style": {
          "navigationBarTitleText": "列表页"
        }
      }
    ]
  },
  {
    "root": "pagesB",
    "pages": [
      {
        "path": "detail/detail"
      }
    ]
  }
]

分包优势

  • 提升首次加载速度
  • 按需加载减少包体积
  • 主包不超过 2MB（小程序限制）

六、preloadRule 分包预加载

"preloadRule": {
  "pages/index/index": {
    "network": "all",
    "packages": ["pagesA"]
  }
}

配置说明

  • 进入页面后自动预加载指定分包
  • network: all/wifi（仅wifi下预加载）

七、condition 启动模式配置（仅开发期间生效）

"condition": {
  "current": 0,
  "list": [
    {
      "name": "商品详情页",
      "path": "pages/goods/detail",
      "query": "id=123"
    }
  ]
}

八、easycom 组件自动引入

"easycom": {
  "autoscan": true,
  "custom": {
    "^uni-(.*)": "@dcloudio/uni-ui/lib/uni-$1/uni-$1.vue",
    "^my-(.*)": "components/my-$1.vue"
  }
}

优势

  • 无需手动导入组件
  • 符合 components/组件名/组件名.vue 结构的组件会自动引入

九、多平台差异化配置

{
  "pages": [],
  "globalStyle": {
    "h5": {
      "titleNView": false
    },
    "mp-weixin": {
      "navigationBarTextStyle": "white"
    },
    "app-plus": {
      "animationType": "fade-in"
    }
  }
}

十、注意事项

  1. 文件路径从项目根目录开始计算
  2. 修改 pages.json 后需要重新编译生效
  3. 页面路径不能重复
  4. 首页必须是 pages 数组的第一项
  5. 微信小程序有路径深度限制（最多10层）

十一、最佳实践

  1. 路由管理：合理组织页面结构
"pages": [
  // 主包页面
  {"path": "pages/index/index"},
  {"path": "pages/user/user"},
  
  // 常用页面
  {"path": "pages/common/login"}
]
  1. 样式统一：通过 globalStyle 统一样式
"globalStyle": {
  "navigationBarTextStyle": "white",
  "navigationBarBackgroundColor": "#007AFF",
  "navigationBarTitleText": "统一标题",
  "backgroundColor": "#F4F5F6"
}
  1. 分包策略：按业务模块分包
"subPackages": [
  {
    "root": "packageA",
    "name": "商品模块",
    "pages": [
      {"path": "goods/list"},
      {"path": "goods/detail"}
    ]
  }
]

pages.json 是 uni-app 项目的枢纽文件，合理配置可以显著提升开发效率和用户体验。建议根据项目实际需求灵活组合上述配置项。

No Comments
Back to top