miniapp-template-ts/docs/page-container.md

PageContainer 组件使用手册

概述

PageContainer 是一个基于 TDesign t-navbar 封装的页面容器组件，提供统一的导航栏与内容区域布局。组件内部已引入 t-navbar，并通过样式变量透传导航栏与容器背景配置，适用于需要自定义导航栏的页面。

功能特性

• 基于 TDesign Navbar 组件，样式统一美观
• 根据页面栈深度与属性配置，自动计算返回按钮显示
• 支持安全区域适配（顶部安全区由 t-navbar 处理，底部安全区由容器处理）
• 支持固定导航栏和占位符
• 支持自定义导航栏样式（背景色、文本颜色）
• 支持自定义内容区域背景色
• 提供多个插槽支持自定义导航栏内容与页面内容
• 支持返回事件回调

引入组件

在页面的 json 配置文件中引入组件：

{
  "usingComponents": {
    "page-container": "../../components/page-container/page-container"
  }
}

基础用法

最简单的用法

<page-container nav-bar-title="页面标题">
  <view>页面内容</view>
</page-container>

自定义导航栏样式

<page-container
  nav-bar-title="页面标题"
  nav-bar-background-color="#123321"
  nav-bar-text-color="#ffffff"
>
  <view>页面内容</view>
</page-container>

隐藏返回按钮

<page-container nav-bar-title="页面标题" nav-bar-left-arrow="{{false}}">
  <view>页面内容</view>
</page-container>

隐藏导航栏

<page-container nav-bar-title="页面标题" nav-bar-visible="{{false}}">
  <view>页面内容</view>
</page-container>

关闭底部安全区适配

<page-container
  nav-bar-title="页面标题"
  container-safe-area-inset-bottom="{{false}}"
>
  <view>页面内容</view>
</page-container>

样式与主题

容器背景色

组件通过样式变量 --pg-container-bg-color 设置容器背景色，对应属性 containerBackgroundColor。

导航栏颜色

组件通过 t-navbar 的样式变量设置导航栏颜色：

• --td-navbar-bg-color：对应 navBarBackgroundColor
• --td-navbar-color：对应 navBarTextColor

属性说明

导航栏相关

属性名	类型	默认值	说明
navBarTitle	String	''	导航栏标题
navBarLeftArrow	Boolean	true	是否显示返回按钮
navBarFixed	Boolean	true	导航栏是否固定
navBarPlaceholder	Boolean	true	导航栏占位
navBarSafeAreaInsetTop	Boolean	true	是否适配安全区域顶部
navBarZIndex	Number	10000	导航栏层级
navBarAnimation	Boolean	true	是否带动画效果
navBarTitleMaxLength	Number	undefined	标题最大长度，超出用 "…" 表示
navBarVisible	Boolean	true	是否显示导航栏
navBarBackgroundColor	String	'#ffffff'	导航栏背景色
navBarTextColor	String	'#000000'	导航栏文本颜色（标题、返回按钮等）

内容容器相关

属性名	类型	默认值	说明
containerSafeAreaInsetBottom	Boolean	true	是否开启底部安全区适配
containerBackgroundColor	String	'#f5f5f5'	内容区域背景色

插槽说明

组件提供导航栏插槽与默认插槽，用于自定义页面内容布局。

默认插槽

默认插槽用于渲染页面主体内容（位于内容区域 page-container__content 内）：

<page-container nav-bar-title="页面标题">
  <view>页面内容</view>
</page-container>

left 插槽

自定义左侧内容（返回按钮区域）：

<page-container nav-bar-title="页面标题">
  <view slot="left">自定义左侧内容</view>
  <view>页面内容</view>
</page-container>

capsule 插槽

自定义胶囊区域内容：

<page-container nav-bar-title="页面标题">
  <view slot="capsule">自定义胶囊内容</view>
  <view>页面内容</view>
</page-container>

title 插槽

自定义标题区域内容：

<page-container nav-bar-title="页面标题">
  <view slot="title">自定义标题内容</view>
  <view>页面内容</view>
</page-container>

事件说明

事件名	说明	回调参数
success	wx.navigateBack 成功时触发	event.detail（navigateBack 成功回调参数）
fail	wx.navigateBack 失败时触发	event.detail（navigateBack 失败回调参数）
complete	wx.navigateBack 完成时触发（无论成功或失败）	event.detail（success/fail 的参数之一）

事件使用示例

<page-container
  nav-bar-title="页面标题"
  bind:success="onBackSuccess"
  bind:fail="onBackFail"
  bind:complete="onBackComplete"
>
  <view>页面内容</view>
</page-container>

Page({
  onBackSuccess(res) {
    console.log('返回成功', res)
  },
  onBackFail(err) {
    console.log('返回失败', err)
  },
  onBackComplete(res) {
    console.log('返回完成', res)
  },
})

返回按钮显示逻辑

组件在实例进入页面节点树时，根据以下条件计算返回按钮是否显示：

showLeftArrow = getCurrentPages().length > 1 && navBarLeftArrow && navBarVisible

注意事项

1. 组件内部依赖 TDesign 的 t-navbar（组件自身已在 usingComponents 中引入），确保项目已正确集成 tdesign-miniprogram
2. 使用组件时，建议在页面的 json 配置中关闭原生导航栏：

{
  "navigationStyle": "custom"
}

3. 组件会自动处理返回按钮的显示逻辑，无需手动判断页面栈
4. 如需自定义返回行为，可以通过监听 success、fail、complete 事件来实现

完整示例

<!-- pages/example/index.wxml -->
<page-container
  nav-bar-title="示例页面"
  nav-bar-background-color="#ffffff"
  nav-bar-text-color="#000000"
  nav-bar-left-arrow="{{true}}"
  nav-bar-fixed="{{true}}"
  nav-bar-placeholder="{{true}}"
  nav-bar-safe-area-inset-top="{{true}}"
  container-background-color="#f5f5f5"
  container-safe-area-inset-bottom="{{true}}"
  bind:success="onBackSuccess"
  bind:fail="onBackFail"
  bind:complete="onBackComplete"
>
  <view class="content">
    <view>这是页面内容区域</view>
  </view>
</page-container>

// pages/example/index.json
{
  "navigationStyle": "custom",
  "usingComponents": {
    "page-container": "../../components/page-container/page-container"
  }
}

// pages/example/index.ts
Page({
  onBackSuccess(res) {
    console.log('页面返回成功', res)
  },
  onBackFail(err) {
    console.log('页面返回失败', err)
  },
  onBackComplete(res) {
    console.log('页面返回完成', res)
  },
})