Skip to main content
Version: Next

页面配置

每一个小程序页面都可以使用 .config.js 文件来对本页面的窗口表现进行配置。页面中配置项在当前页面会覆盖全局配置 app.config.jsonwindow 中相同的配置项。

文件需要 export 一个默认对象,配置项遵循微信小程序规范,并且对所有平台进行统一。

注意:

  1. Taro v3.4 之前,page.config.js 里引用的 JS 文件没有经过 Babel 编译。(Taro v3.4 开始支持)
  2. Taro v3.4 支持在页面 JS 中使用 definePageConfig 宏函数定义页面配置,代替 page.config.js 文件。
  3. 多端差异化逻辑可以使用 process.env.TARO_ENV 变量作条件判断来实现。
  4. page.config.js 不支持多端文件的形式,如 index.weapp.js 这样是不起作用的。

definePageConfig 宏函数

info

Taro v3.4+ 支持

开发者可以使用编译时宏函数 definePageConfig 包裹配置对象,以获得类型提示自动补全

在页面配置文件中使用

page.config.ts
export default definePageConfig({
navigationBarTitleText: '首页'
})

在页面 JS 文件中使用

支持在页面 JS 中使用 definePageConfig 定义页面配置,而不需要提供 page.config.js 文件。

但是需要注意的是,使用 definePageConfig 定义的页面配置对象不能使用变量

page.ts
definePageConfig({
navigationBarTitleText: '首页'
})

export default function Index () {}

配置项列表

属性类型默认值描述
navigationBarBackgroundColorHexColor(十六进制颜色值)#000000导航栏背景颜色,如 #000000
navigationBarTextStyleStringwhite导航栏标题颜色,仅支持 black / white
navigationBarTitleTextString导航栏标题文字内容
navigationStyleStringdefault导航栏样式,仅支持以下值:default 默认样式;custom 自定义导航栏,只保留右上角胶囊按钮
transparentTitleStringnone导航栏透明设置。支持 always 一直透明 / auto 滑动自适应 / none 不透明
backgroundColorString窗口的背景色
backgroundTextStyleStringdark下拉 loading 的样式,仅支持 dark / light
backgroundColorTopString#ffffff顶部窗口的背景色,仅 iOS 支持
backgroundColorBottomString#ffffff底部窗口的背景色,仅 iOS 支持
enablePullDownRefreshbooleanfalse是否开启当前页面的下拉刷新。
onReachBottomDistanceNumber50页面上拉触底事件触发时距页面底部距离,单位为 px
pageOrientationStringportrait屏幕旋转设置,支持 auto / portrait / landscape 详见 响应显示区域变化
disableScrollBooleanfalse设置为 true 则页面整体不能上下滚动。
只在页面配置中有效,无法在 app.json 中设置
disableSwipeBackBooleanfalse禁止页面右滑手势返回
usingComponentsObject页面自定义组件配置

其中,usingComponents 一般不需要配置,只有在需要与引用原生小程序组件的时候才需要配置。

各端支持程度

属性微信小程序百度小程序字节跳动小程序支付宝小程序H5RN
navigationBarBackgroundColor✔️✔️✔️✔️✔️✔️
navigationBarTextStyle✔️✔️✔️✔️✔️
navigationBarTitleText✔️✔️✔️✔️✔️✔️
navigationStyle✔️(微信客户端 6.6.0)✔️(百度 App 版本 11.1.0)✔️✔️
transparentTitle---✔️--
backgroundColor✔️✔️✔️✔️
backgroundTextStyle✔️✔️✔️✔️
backgroundColorTop✔️(微信客户端 6.5.16)✔️
backgroundColorBottom✔️(微信客户端 6.5.16)✔️
enablePullDownRefresh✔️✔️✔️✔️
onReachBottomDistance✔️✔️✔️
pageOrientation✔️2.4.0 (auto) / 2.5.0 (landscape)
disableScroll✔️✔️
disableSwipeBack✔️
usingComponents✔️✔️✔️✔️