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

PageContainer 组件使用手册

概述

PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件，提供了统一的导航栏和内容区域布局，简化了小程序页面的开发流程。组件自动处理返回按钮显示逻辑、安全区域适配等常见需求。

功能特性

• 基于 TDesign Navbar 组件，样式统一美观
• 自动判断返回按钮显示（根据页面栈深度）
• 支持安全区域适配（适配刘海屏等特殊设备）
• 支持固定导航栏和占位符
• 支持自定义导航栏样式（背景色、文本颜色）
• 提供多个插槽支持自定义内容
• 支持返回事件回调

引入组件

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

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

基础用法

最简单的用法

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

自定义导航栏样式

<page-container 
  title="页面标题" 
  backgroundColor="#123321" 
  textColor="#ffffff">
  <view>页面内容</view>
</page-container>

隐藏返回按钮

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

隐藏导航栏

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

属性说明

属性名	类型	默认值	说明
title	String	''	导航栏标题
leftArrow	Boolean	true	是否显示返回按钮
fixed	Boolean	true	导航栏是否固定
placeholder	Boolean	true	导航栏占位
safeAreaInsetTop	Boolean	true	是否适配安全区域顶部
zIndex	Number	10000	导航栏层级
animation	Boolean	true	是否带动画效果
delta	Number	1	后退的层数
titleMaxLength	Number	undefined	标题最大长度，超出用 "…" 表示
visible	Boolean	true	是否显示导航栏
backgroundColor	String	'#ffffff'	导航栏背景色
textColor	String	'#000000'	导航栏文本颜色（标题、返回按钮等）

插槽说明

组件提供了三个插槽用于自定义导航栏内容：

left 插槽

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

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

capsule 插槽

自定义胶囊区域内容：

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

title 插槽

自定义标题区域内容：

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

事件说明

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

事件使用示例

<page-container 
  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)
  },
})

返回按钮显示逻辑

组件会自动判断是否显示返回按钮，判断规则如下：

1. 如果页面栈中只有一个页面（首页），则不显示返回按钮
2. 如果 leftArrow 属性为 false，则不显示返回按钮
3. 如果 visible 属性为 false，则不显示返回按钮
4. 其他情况显示返回按钮

注意事项

1. 组件依赖 TDesign 的 t-navbar 组件，确保已正确安装和构建 TDesign 组件库
2. 使用组件时，建议在页面的 json 配置中关闭原生导航栏：

{
  "navigationStyle": "custom"
}

3. 组件会自动处理返回按钮的显示逻辑，无需手动判断页面栈
4. 如需自定义返回行为，可以通过监听 success、fail、complete 事件来实现
5. 使用 delta 属性可以控制返回的页面层数，默认为 1（返回上一页）

完整示例

<!-- pages/example/index.wxml -->
<page-container 
  title="示例页面"
  backgroundColor="#ffffff"
  textColor="#000000"
  left-arrow="{{true}}"
  fixed="{{true}}"
  placeholder="{{true}}"
  safe-area-inset-top="{{true}}"
  bind:success="onBackSuccess">
  <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)
  },
})