pages

uni-app 通过 pages 节点配置应用由哪些页面组成，pages 节点接收一个数组，数组每个项都是一个对象，其属性值如下：

Tips：

• pages节点的第一项为应用入口页（即首页）
• 应用中新增/减少页面，都需要对 pages 数组进行修改
• 文件名不需要写后缀，框架会自动寻找路径下的页面资源代码示例：

开发目录为：

    
┌─pages               
│  ├─index
│  │  └─index.vue    
│  └─login
│     └─login.vue    
├─static             
├─main.js       
├─App.vue          
├─manifest.json  
└─pages.json            
    

则需要在 pages.json 中填写

{
    "pages": [
        {
            "path": "pages/index/index", 
            "style": { ... }
        }, {
            "path": "pages/login/login", 
            "style": { ... }
        }
    ]
}

style

用于设置每个页面的状态栏、导航条、标题、窗口背景色等。

页面中配置项会覆盖 globalStyle 中相同的配置项

代码示例：

{
  "pages": [{
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",//设置页面标题文字
        "enablePullDownRefresh":true//开启下拉刷新
      }
    },
    ...
  ]
}

自定义导航栏使用注意

当navigationStyle设为custom或titleNView设为false时，原生导航栏不显示，此时要注意几个问题：

• 非H5端，手机顶部状态栏区域会被页面内容覆盖。这是因为窗体是沉浸式的原因，即全屏可写内容。uni-app提供了状态栏高度的css变量—status-bar-height，如果需要把状态栏的位置从前景部分让出来，可写一个占位div，高度设为css变量。

<template>
  <view>
      <view class="status_bar">
          <!-- 这里是状态栏 -->
      </view>
      <view> 状态栏下的文字 </view>
  </view>
</template>    
<style>
  .status_bar {
      height: var(--status-bar-height);
      width: 100%;
  }
</style>

• 如果原生导航栏不能满足需求，推荐使用uni ui的自定义导航栏NavBar。这个前端导航栏自动处理了状态栏高度占位问题。
• 前端导航栏搭配原生下拉刷新时，会有问题，包括
  • 微信小程序下iOS需要拉更长才能看到下拉刷新的三个点，而Android是从屏幕顶部下拉，无法从导航栏下方下拉。如果一定要从前端导航栏下拉，小程序下只能放弃原生下拉刷新，纯前端模拟，参考mescroll插件，但这样很容易产生性能问题。目前小程序平台自身没有提供更好的方案
  • App和H5下，原生下拉刷新提供了circle样式，可以指定offset偏移量（pages.json的app-plus下配置），自定义下拉圈出现的位置。在hello uni-app的扩展组件中有示例。
• 非H5端，前端导航盖不住原生组件。如果页面有video、map、textarea(仅小程序)等原生组件，滚动时会覆盖住导航栏
  • 如果是小程序下，可以使用cover-view来做导航栏，避免覆盖问题
  • 如果是App下，建议使用titleNView或subNVue，体验更好
• 前端组件在渲染速度上不如原生导航栏，原生导航可以在动画期间渲染，保证动画期间不白屏，但使用前端导航栏，在新窗体进入的动画期间可能会整页白屏，越低端的手机越明显。
• 以上讨论的是前端自定义导航栏，但在App侧，原生导航栏也提供了比小程序导航更丰富的自定义性
  • titleNView：给原生导航栏提供更多配置，包括自定义按钮、滚动渐变效果、搜索框等，详见titleNView
  • subNView：使用nvue原生渲染，所有布局自己开发，具备一切自定义灵活度。详见subNVue
• 页面禁用原生导航栏后，想要改变状态栏的前景字体样式，仍可设置页面的 navigationBarTextStyle 属性（只能设置为 black或white）。如果想单独设置状态栏颜色，App端可使用plus.navigator.setStatusBarStyle设置。注意部分低端Android手机（4.4）自身不支持设置状态栏前景色。鉴于以上问题，在原生导航能解决业务需求的情况下，尽量使用原生导航。甚至有时需要牺牲一些不是很重要的需求。在App和H5下，uni-app提供了灵活的处理方案：titleNView、subNVue、或整页使用nvue。但在小程序下，因为其自身的限制，没有太好的方案。有必要的话，也可以用条件编译分端处理。

app-plus

配置编译到 App 平台时的特定样式，部分常用配置 H5 平台也支持。以下仅列出常用，更多配置项参考 WebviewStyles。

Tips

• .nvue 页面仅支持 titleNView 配置，其它配置项暂不支持

导航栏

Tips

• 每个页面均支持通过配置 titleNView:false 来禁用原生导航栏。一旦禁用原生导航，请注意阅读自定义导航注意事项。
• titleNView 不能设置 autoBackButton、homeButton等属性
• titleNView 的 type 值为 transparent 时，导航栏为透明渐变导航栏
• 在 titleNView 配置 buttons 后，监听按钮的点击事件，vue 页面参考：onNavigationBarButtonTap、nvue 页面参考：uni.onNavigationBarButtonTap
• 在 titleNView 配置 searchInput 后，相关的事件监听参考：onNavigationBarSearchInputChanged 等
• App下原生导航栏的按钮如果使用字体图标，注意检查字体库的名字（font-family）是否使用了默认的 iconfont，这个名字是保留字，不能作为外部引入的字体库的名字，需要调整为自定义的名称，否则无法显示。
• 想了解各种导航栏的开发方法，请详读导航栏开发指南

自定义按钮

按钮样式

使用 type 值设置按钮的样式时，会忽略 fontSrc 和 text 属性。

搜索框配置

searchInput可以在titleNView的原生导航栏上放置搜索框。其宽度根据周围元素自适应。

searchInput Tips

searchInput的点击输入框onNavigationBarSearchInputClicked、文本变化onNavigationBarSearchInputChanged、点击搜索按钮onNavigationBarSearchInputConfirmed等生命周期，见文档页面生命周期。

• 在生命周期里通过参数e.text，可获取输入框内容。具体见hello uni-app中模板-顶部导航栏中的示例
• 如需动态修改searchInput，或者获取searchInput的placehold，参考uni-app动态修改App端导航栏常见titleNView配置代码示例

{
    "pages": [{
            "path": "pages/index/index", //首页
            "style": {
                "app-plus": {
                    "titleNView": false //禁用原生导航栏
                }
            }
        }, {
            "path": "pages/log/log", //日志页面
            "style": {
                "app-plus": {
                    "bounce": "none", //关闭窗口回弹效果
                    "titleNView": {
                        "buttons": [ //原生标题栏按钮配置,
                            {
                                "text": "分享" //原生标题栏增加分享按钮，点击事件可通过页面的 onNavigationBarButtonTap 函数进行监听
                            }
                        ]
                    }
                }
            }
        }, {
            "path": "pages/detail/detail", //详情页面
            "style": {
                "navigationBarTitleText": "详情",
                "app-plus": {
                    "titleNView": {
                        "type": "transparent"//透明渐变导航栏
                    }
                }
            }
        }, {
            "path": "pages/search/search", //搜索页面
            "style": {
                "app-plus": {
                    "titleNView": {
                        "type": "transparent",//透明渐变导航栏
                        "searchInput": {
                            "backgroundColor": "#fff",
                            "borderRadius": "6px", //输入框圆角
                            "placeholder": "请输入搜索内容",
                            "disabled": true //disable时点击输入框不置焦，可以跳到新页面搜索
                        }
                    }
                }
            }
        }
        ...
    ]
}

Tips

• buttons 的 text 推荐使用字体图标。如果使用了汉字或英文，推荐把字体改小一点，否则文字长度增加后，距离屏幕右边距太近。
• App平台，buttons动态修改，详见
• App平台，buttons角标动态修改，见 hello uni-app 中模板-顶部导航标题栏-导航栏带红点和角标
• App平台，设置searchInput的文字动态修改，API见文档。注意disable状态无法设置文字、placehold暂不支持动态设置
• H5平台，如需实现上述动态修改，需在条件编译通过dom操作修改

原生子窗体

subNVues 是 vue 页面的原生子窗体。用于解决 vue 页面中的层级覆盖和原生界面灵活自定义用的。

它不是全屏页面，也不是组件，就是一个原生子窗体。它是一个 nvue 页面，使用 weex 引擎渲染，提供了比 cover-view、plus.nativeObj.view 更强大的原生排版能力，方便自定义原生导航或覆盖原生地图、视频等。请详读subNVues 开发指南

Tips

• subNVues 的 id 是全局唯一的，不能重复
• 可以通过 uni.getSubNVueById('id') 获取 subNVues 的实例
• subNVues 的 path 属性只能是 nvue 文件路径

原生子窗体样式

代码示例

{
    "pages": [{
        "path": "pages/index/index", //首页
        "style": {
            "app-plus": {
                "titleNView": false , //禁用原生导航栏
                "subNVues":[{//侧滑菜单
                    "id": "drawer", //subNVue 的 id，可通过 uni.getSubNVueById('drawer') 获取
                    "path": "pages/index/drawer.nvue", // nvue 路径
                    "style": { //webview style 子集，文档可暂时开放出来位置，大小相关配置
                        "position": "popup", //除 popup 外，其他值域参考 5+ webview position 文档
                        "width": "50%"
                    }
                }, {//弹出层
                    "id": "popup",
                    "path": "pages/index/popup",
                    "style": {
                        "position": "popup",
                        "margin":"auto",
                        "width": "150px",
                        "height": "150px"
                    }
                }, {//自定义头
                    "id": "nav",
                    "path": "pages/index/nav",
                    "style": {
                        "position": "dock",
                        "height": "44px"
                    }
                }]
            }
        }
    }]
}

下拉刷新

在 App 平台下可以自定义部分下拉刷新的配置 page->app-plus->pullToRefresh。

下拉刷新使用注意

• enablePullDownRefresh 与 pullToRefresh->support 同时设置时，后者优先级较高。
• 如果期望在 App 和小程序上均开启下拉刷新的话，请配置页面的 enablePullDownRefresh 属性为 true。
• 若仅期望在 App 上开启下拉刷新，则不要配置页面的 enablePullDownRefresh 属性，而是配置 pullToRefresh->support 为 true。
• 开启原生下拉刷新时，页面里不应该使用全屏高的scroll-view，向下拖动内容时，会优先触发下拉刷新而不是scroll-view滚动
• 原生下拉刷新的起始位置在原生导航栏的下方，如果取消原生导航栏，使用自定义导航栏，原生下拉刷新的位置会在屏幕顶部。如果希望在自定义导航栏下方拉动，只能使用circle方式的下拉刷新，并设置offset参数，将circle圈的起始位置调整到自定义导航栏下方。hello uni-app的扩展组件中有示例。
• 如果想在app端实现更多复杂的下拉刷新，比如美团、京东App那种拉下一个特殊图形，可以使用nvue的组件。HBuilderX 2.0.3+起，新建项目选择新闻模板可以体验
• 如果想在vue页面通过web前端技术实现下拉刷新，插件市场有例子，但前端下拉刷新的性能不如原生，复杂长列表会很卡
• iOS上，default模式的下拉刷新和bounce回弹是绑定的，如果设置了bounce:none，会导致无法使用default下拉刷新代码示例

{
    "pages": [
        {
            "path": "pages/index/index", //首页
            "style": {
                "app-plus": {
                    "pullToRefresh": {
                        "support": true,
                        "color": "#ff3333",
                        "style": "default",
                        "contentdown": {
                            "caption": "下拉可刷新自定义文本"
                        },
                        "contentover": {
                            "caption": "释放可刷新自定义文本"
                        },
                        "contentrefresh": {
                            "caption": "正在刷新自定义文本"
                        }
                    }
                }
            }
        }
    ]
}

h5

配置编译到 H5 平台时的特定样式

导航栏

自定义按钮

按钮样式

使用 type 值设置按钮的样式时，会忽略 fontSrc 和 text 属性。

下拉刷新

h5 平台下拉刷新动画，只有 circle 类型。

搜索框样式

注意事项：

• 如果 h5 节点没有配置，默认会使用 app-plus 下的配置。
• 配置了 h5 节点，则会覆盖 app-plus 下的配置。

navigationBarShadow