UniApp pages.json 配置完全指南」：页面路由、导航栏、全局样式一次学会！「新手必备！手把手带你解析 UniApp 的 pages.json 文件」「UniApp 配置文件详解：快速

最新推荐文章于 2025-03-12 10:10:50 发布

南北极之间

最新推荐文章于 2025-03-12 10:10:50 发布

阅读量1.7k

点赞数 14

分类专栏：小程序文章标签：前端 uni-app vue.js 微信小程序小程序

本文链接：https://blog.youkuaiyun.com/qq_22182989/article/details/144746531

版权

小程序专栏收录该内容

54 篇文章

订阅专栏

效果图

在这里插入图片描述

博客正文：UniApp `pages.json` 配置文件详解与新手教程

什么是 pages.json 文件？
为什么 pages.json 是 UniApp 的核心？
pages.json 的基础结构详解
- pages 配置：定义页面路径与路由
- globalStyle 配置：全局样式设置
- tabBar 配置：底部导航栏
- 其他属性详解（subPackages、condition 等）
示例代码：手把手实现 pages.json 基础配置
常见问题与解决方案
总结与学习建议

1. 什么是 `pages.json` 文件？

在 UniApp 项目中，pages.json 是一个核心配置文件，用来定义项目的页面路径、页面样式、导航栏设置和底部导航栏等全局信息。简单来说，它相当于项目的“大脑”，负责管理页面的路由和样式。

2. 为什么 `pages.json` 是 UniApp 的核心？

管理页面路由：所有页面的路径、页面之间的跳转，都需要在 pages.json 中声明。
设置全局样式：可以统一设置导航栏、背景色等全局样式。
定义底部导航栏：如果项目需要一个固定的底部导航栏（TabBar），也需要在 pages.json 中配置。
支持分包加载：当项目较大时，可以通过分包来优化加载速度。
条件编译：支持多平台的配置，通过 condition 设置适配不同的平台（如微信小程序、H5）。

3. `pages.json` 的基础结构详解

以下是一个典型的 pages.json 文件结构：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "navigationBarBackgroundColor": "#3b82f6",
        "navigationBarTextStyle": "white"
      }
    },
    {
      "path": "pages/about/about",
      "style": {
        "navigationBarTitleText": "关于我们"
      }
    }
  ],
  "globalStyle": {
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "backgroundColor": "#f8f8f8"
  },
  "tabBar": {
    "color": "#7a7e83",
    "selectedColor": "#3b82f6",
    "backgroundColor": "#ffffff",
    "borderStyle": "black",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "static/icon_home.png",
        "selectedIconPath": "static/icon_home_active.png"
      },
      {
        "pagePath": "pages/about/about",
        "text": "关于",
        "iconPath": "static/icon_about.png",
        "selectedIconPath": "static/icon_about_active.png"
      }
    ]
  }
}

3.1 `pages` 配置

pages 是整个项目的页面路由配置，每一个页面都必须在这里声明。

path：页面路径，相对于 src 文件夹。
style：单个页面的样式配置，优先级高于 globalStyle。

示例：

"pages": [
  {
    "path": "pages/index/index",
    "style": {
      "navigationBarTitleText": "首页"
    }
  }
]

3.2 `globalStyle` 配置

globalStyle 用来配置全局样式，所有页面默认继承这些样式。可以配置以下内容：

navigationBarBackgroundColor：顶部导航栏背景颜色。
navigationBarTextStyle：顶部导航栏文字颜色，可选 black 或 white。
navigationBarTitleText：导航栏的默认标题。
backgroundColor：页面背景颜色。

示例：

"globalStyle": {
  "navigationBarBackgroundColor": "#ffffff",
  "navigationBarTextStyle": "black",
  "backgroundColor": "#f8f8f8"
}

3.3 `tabBar` 配置

tabBar 用来配置底部导航栏。适用于多页面项目中需要固定底部导航栏的场景。

color：未选中状态下的字体颜色。
selectedColor：选中状态下的字体颜色。
backgroundColor：导航栏背景色。
list：底部导航项，最多支持 5 个。

示例：

"tabBar": {
  "color": "#7a7e83",
  "selectedColor": "#3b82f6",
  "backgroundColor": "#ffffff",
  "list": [
    {
      "pagePath": "pages/index/index",
      "text": "首页",
      "iconPath": "static/icon_home.png",
      "selectedIconPath": "static/icon_home_active.png"
    }
  ]
}

3.4 其他属性

subPackages：分包加载配置，优化项目性能。
condition：条件编译，适配不同平台。
preloadRule：预加载规则，用于提升页面加载速度。

4. 示例代码：手把手实现 `pages.json` 配置

4.1 基础页面配置

"pages": [
  {
    "path": "pages/home/home",
    "style": {
      "navigationBarTitleText": "我的主页",
      "navigationBarBackgroundColor": "#3b82f6",
      "navigationBarTextStyle": "white"
    }
  }
]

4.2 添加全局样式

"globalStyle": {
  "navigationBarBackgroundColor": "#3b82f6",
  "navigationBarTextStyle": "white",
  "backgroundColor": "#f8f8f8"
}

4.3 配置 TabBar

"tabBar": {
  "color": "#7a7e83",
  "selectedColor": "#3b82f6",
  "backgroundColor": "#ffffff",
  "list": [
    {
      "pagePath": "pages/home/home",
      "text": "首页",
      "iconPath": "static/icon_home.png",
      "selectedIconPath": "static/icon_home_active.png"
    },
    {
      "pagePath": "pages/about/about",
      "text": "关于",
      "iconPath": "static/icon_about.png",
      "selectedIconPath": "static/icon_about_active.png"
    }
  ]
}