关于uni-app pages.json配置详解

uni-app pages.json 配置文件----关于subPackages和pages理解

1. pages.json

pages.json 是 uni-app 的全局配置文件

主要作用包括：

配置页面路由路径：应用由哪些页面组成，哪个是首页。
设置窗口表现：如导航栏样式、背景色、下拉刷新等。
配置底部 Tab 栏：设置具有原生体验的 tabbar。
设置全局样式：所有页面统一的窗口表现。
配置启动模式：开发阶段模拟直达页面。
配置分包预加载等高级功能。

所有页面均需在 pages.json 中注册，否则不会被打包到应用中。

2.pages 页面路径配置

pages 节点是一个数组，用于配置应用的页面路径和每个页面的窗口表现。

数组的第一项代表应用的启动页（首页）。

配置规则：

path 设置 ：只需写页面路径，不需要写 .vue 或 .nvue 后缀。
子目录支持 ：路径支持子目录格式，如 "pages/user/settings/index"。
新增/减少页面 ：都需要修改 pages 数组。

示例：

json 复制代码

"pages": [
  {
    "path": "pages/index/index", // 首页
    "style": {
      "navigationBarTitleText": "首页", // 页面标题
      "enablePullDownRefresh": true ,// 开启下拉刷新
      "backgroundColor": "#F8F8F8",// 导航栏背景颜色
      "onReachBottomDistance": 100,// 设置页面上拉触底事件触发时距离页面底部的距离,默认是50px
      "app-plus": { // 以下是App平台特有配置
            "titleNView": {
                "titleSize": "16px" // App端原生导航栏标题字体大小
                "titleColor": "#fff",
				"buttons": [{//  导航栏右侧按钮，下面是使用icon展示的示例
							"text": "\ue60f",
							"fontSize": "30px",
							"fontSrc": "/static/iconfont.ttf"
						   }]
            }
        }
    }
  },
  {
    "path": "pages/user/user", // 用户页
    "style": {
      "navigationBarTitleText": "个人中心",
      "backgroundColor": "#F5F5F5"
    }
  }
]

onReachBottomDistance：配置位置：可以在 pages.json 的 globalStyle 下进行全局配置，也可以在具体页面的 style 下进行单独配置（页面配置优先级高于全局配置）。

使用场景：常用于实现列表数据的上拉加载更多功能。

注意事项： 1、如果页面使用了 scroll-view 组件并导致了页面没有滚动，则 onReachBottom 事件可能不会被触发9。scroll-view 组件自身有滚动到底部的事件。 2、在小程序和 H5 平台有效。

对于style中的app-plus

他是一个条件编译节点。它内部的所有配置只在打包到 App 平台时生效，在编译到 H5、微信小程序等其他平台时会被忽略
buttons：用于在导航栏的左侧或右侧添加自定义按钮，每个对象代表一个按钮。按钮默认显示在右侧，可以通过 "type" 属性控制左右（"type": "back" 表示后退按钮，显示在左侧）。
"text": "\ue60f"：这里的 \ue60f 是一个 Unicode 码点，它对应的是字体文件（iconfont.ttf）中的某一个具体图标。它优点是矢量、不失真、颜色可通过 CSS 控制、加载快。
"fontSrc": "/static/iconfont.ttf"：按钮图标所使用的自定义字体文件的路径
- 必须使用绝对路径（以 / 开头）。文件必须存放在项目根目录的 static 目录下。
- 这个 .ttf 文件来自 IconFont阿里矢量图标库。选好图标并生成项目后，可以下载到字体文件。

3. subPackages

json 复制代码

{
  "pages": [
    // 主包页面，如首页、TabBar页面
    {
      "path": "pages/index/index",
      "style": { "navigationBarTitleText": "首页" }
    },
    {
      "path": "pages/user/user",
      "style": { "navigationBarTitleText": "我的" }
    }
  ],
  "subPackages": [
    // 这是一个分包配置
    {
      "root": "pages-planManagement", // 分包的根目录名
      name:"planManagement",
      "pages": [ // 此分包下的页面路径，是相对于 root 目录的
        {
          "path": "pages/castAluminumProcessing/receive/index",
          "style": { "navigationBarTitleText": "新闻列表" }
        },
        {
          "path": "news/detail",
          "style": { "navigationBarTitleText": "新闻详情" }
        }
      ]
    },
    // 可以配置多个分包
    {
      "root": "pages-castIron",
      name:"castIron",
      "pages": [
        {
          "path": "mall/home",
          "style": { "navigationBarTitleText": "商城首页" }
        }
      ]
    }
  ],
  // 还可以配置预加载规则，提升浏览体验，这个我还没使用过，使用过的码友可以留言交流一下
  "preloadRule": {
    "pages/index/index": { // 当在首页时
      "network": "all",    // 在所有网络下都预加载
      "packages": ["subpkg_news"] // 预加载名为 "subpkg_news" 的分包
    }
  }
}

配置注意事项：

路径问题 ：subPackages 里 pages 的路径是 root 下的相对路径，不是全路径。

⚠️ 注意事项

跳转分包页面 ：跳转到分包页面时，路径需包含分包的 root 值 。例如，要跳转到上面配置的新闻列表页，应使用 /pages-planManagement/pages/castAluminumProcessing/receive/index。
公共代码与资源：
- 所有分包都会用到的公共JS库 、组件、工具函数 或公共样式 ，最好放在主包中。
- 仅为某个分包使用的静态资源 ，可放入该分包根目录下的 static 文件夹内，以避免增大主包体积。
App平台 ：如果需在App端开启分包，还需在manifest.json中进行配置，
- 打开 manifest.json：位于你 UniApp 项目的根目录下。
- 切换到"源码视图"：在 HBuilder X 中编辑 manifest.json时，通常有"可视化视图"和"源码视图"两种方式，需要切换到源码视图才能进行配置。
- 定位或添加 app-plus 节点：在源码视图中，找到或添加 "app-plus" 节点。
- 配置 optimization 字段：在 "app-plus" 节点下，添加 "optimization" 字段，并设置 "subPackages": true。

json 复制代码

{
  "app-plus": {
    "optimization": {
      "subPackages": true // 开启 App 端的分包优化
    }
    // ... App 平台的其他配置
  }
  // ... manifest.json 的其他配置
}

App 端开启分包的主要目的是优化启动速度（尤其是首页为 Vue 页面时），而不是像小程序那样为了解决包体积大小限制

4. 实用技巧与注意事项

静态资源存放 ：图标等静态资源必须放在 static 目录中才能被打包，非 static 目录资源打包时会丢失。
页面注册 ：在 HBuilderX 中新建页面时，必须勾选"在 pages.json 中注册"选项，否则页面无法被访问。删除页面文件时，HBuilderX 也会提示从 pages.json 中移除注册。
配置修改生效 ：修改 pages.json 后，必须重新编译才能生效。
优先级规则：
- 页面样式 > 全局样式 > 默认样式
- 当同名页面存在于不同目录时，靠前的配置优先级更高
自定义导航栏 ：如果 pages.json 中配置的导航栏和 tabbar 功能无法满足需求，可以不在 pages.json 中配置，自己用 view 做导航栏和 tabbar。
状态栏注意事项：
- 不同手机的状态栏高度并不相同，如需获取本机的状态栏高度，可使用 API uni.getWindowInfo。
- 当 navigationStyle 设为 custom 时，原生导航栏不显示，此时需特别注意顶部状态栏的问题。
下拉刷新：
- pages.json 中下拉刷新是页面级配置，方便使用但灵活度有限。
- 如需自定义下拉刷新，可使用 scroll-view 或 list-view 的下拉刷新功能。