diff --git a/docs/page-container.md b/docs/page-container.md index 6f3849e..ac478a2 100644 --- a/docs/page-container.md +++ b/docs/page-container.md @@ -2,16 +2,17 @@ ## 概述 -PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件，提供了统一的导航栏和内容区域布局，简化了小程序页面的开发流程。组件自动处理返回按钮显示逻辑、安全区域适配等常见需求。 +PageContainer 是一个基于 TDesign `t-navbar` 封装的页面容器组件，提供统一的导航栏与内容区域布局。组件内部已引入 `t-navbar`，并通过样式变量透传导航栏与容器背景配置，适用于需要自定义导航栏的页面。 ## 功能特性 - 基于 TDesign Navbar 组件，样式统一美观 -- 自动判断返回按钮显示（根据页面栈深度） -- 支持安全区域适配（适配刘海屏等特殊设备） +- 根据页面栈深度与属性配置，自动计算返回按钮显示 +- 支持安全区域适配（顶部安全区由 `t-navbar` 处理，底部安全区由容器处理） - 支持固定导航栏和占位符 - 支持自定义导航栏样式（背景色、文本颜色） -- 提供多个插槽支持自定义内容 +- 支持自定义内容区域背景色 +- 提供多个插槽支持自定义导航栏内容与页面内容 - 支持返回事件回调 ## 引入组件 @@ -31,7 +32,7 @@ PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件 ### 最简单的用法 ```xml - + 页面内容 ``` @@ -39,10 +40,11 @@ PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件 ### 自定义导航栏样式 ```xml - + 页面内容 ``` @@ -50,7 +52,7 @@ PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件 ### 隐藏返回按钮 ```xml - + 页面内容 ``` @@ -58,38 +60,80 @@ PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件 ### 隐藏导航栏 ```xml - + 页面内容 ``` +### 关闭底部安全区适配 + +```xml + + 页面内容 + +``` + +## 样式与主题 + +### 容器背景色 + +组件通过样式变量 `--pg-container-bg-color` 设置容器背景色，对应属性 `containerBackgroundColor`。 + +### 导航栏颜色 + +组件通过 `t-navbar` 的样式变量设置导航栏颜色： + +- `--td-navbar-bg-color`：对应 `navBarBackgroundColor` +- `--td-navbar-color`：对应 `navBarTextColor` + ## 属性说明 +### 导航栏相关 + | 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| -| 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' | 导航栏文本颜色（标题、返回按钮等） | +| 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` 内）： + +```xml + + 页面内容 + +``` ### left 插槽 自定义左侧内容（返回按钮区域）： ```xml - + 自定义左侧内容 页面内容 @@ -100,7 +144,7 @@ PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件 自定义胶囊区域内容： ```xml - + 自定义胶囊内容 页面内容 @@ -111,7 +155,7 @@ PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件 自定义标题区域内容： ```xml - + 自定义标题内容 页面内容 @@ -121,18 +165,19 @@ PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件 | 事件名 | 说明 | 回调参数 | |--------|------|----------| -| success | 返回成功时触发 | event.detail | -| fail | 返回失败时触发 | event.detail | -| complete | 返回完成时触发（无论成功或失败） | event.detail | +| success | `wx.navigateBack` 成功时触发 | `event.detail`（navigateBack 成功回调参数） | +| fail | `wx.navigateBack` 失败时触发 | `event.detail`（navigateBack 失败回调参数） | +| complete | `wx.navigateBack` 完成时触发（无论成功或失败） | `event.detail`（success/fail 的参数之一） | ### 事件使用示例 ```xml - + bind:complete="onBackComplete" +> 页面内容 ``` @@ -153,16 +198,15 @@ Page({ ## 返回按钮显示逻辑 -组件会自动判断是否显示返回按钮，判断规则如下： +组件在实例进入页面节点树时，根据以下条件计算返回按钮是否显示： -1. 如果页面栈中只有一个页面（首页），则不显示返回按钮 -2. 如果 `leftArrow` 属性为 `false`，则不显示返回按钮 -3. 如果 `visible` 属性为 `false`，则不显示返回按钮 -4. 其他情况显示返回按钮 +```text +showLeftArrow = getCurrentPages().length > 1 && navBarLeftArrow && navBarVisible +``` ## 注意事项 -1. 组件依赖 TDesign 的 `t-navbar` 组件，确保已正确安装和构建 TDesign 组件库 +1. 组件内部依赖 TDesign 的 `t-navbar`（组件自身已在 `usingComponents` 中引入），确保项目已正确集成 `tdesign-miniprogram` 2. 使用组件时，建议在页面的 `json` 配置中关闭原生导航栏： ```json @@ -173,21 +217,25 @@ Page({ 3. 组件会自动处理返回按钮的显示逻辑，无需手动判断页面栈 4. 如需自定义返回行为，可以通过监听 `success`、`fail`、`complete` 事件来实现 -5. 使用 `delta` 属性可以控制返回的页面层数，默认为 1（返回上一页） ## 完整示例 ```xml - + 这是页面内容区域 @@ -210,5 +258,11 @@ Page({ onBackSuccess(res) { console.log('页面返回成功', res) }, + onBackFail(err) { + console.log('页面返回失败', err) + }, + onBackComplete(res) { + console.log('页面返回完成', res) + }, }) ``` diff --git a/miniprogram/components/page-container/page-container.ts b/miniprogram/components/page-container/page-container.ts index 8c24071..821aef7 100644 --- a/miniprogram/components/page-container/page-container.ts +++ b/miniprogram/components/page-container/page-container.ts @@ -123,6 +123,7 @@ Component({ * 返回按钮点击事件 */ goBack() { + console.warn('点击了箭头按钮') wx.navigateBack({ success: (res) => { // 转发成功事件 @@ -138,26 +139,5 @@ Component({ }, }) }, - - /** - * 处理返回成功事件（从 t-navbar 转发） - */ - handleBackSuccess(e: WechatMiniprogram.CustomEvent) { - this.triggerEvent('success', e.detail) - }, - - /** - * 处理返回失败事件（从 t-navbar 转发） - */ - handleBackFail(e: WechatMiniprogram.CustomEvent) { - this.triggerEvent('fail', e.detail) - }, - - /** - * 处理返回完成事件（从 t-navbar 转发） - */ - handleBackComplete(e: WechatMiniprogram.CustomEvent) { - this.triggerEvent('complete', e.detail) - }, }, }) diff --git a/miniprogram/components/page-container/page-container.wxml b/miniprogram/components/page-container/page-container.wxml index ccfe69f..1a170f2 100644 --- a/miniprogram/components/page-container/page-container.wxml +++ b/miniprogram/components/page-container/page-container.wxml @@ -15,9 +15,6 @@ title-max-length="{{navBarTitleMaxLength}}" visible="{{navBarVisible}}" bind:go-back="goBack" - bind:success="handleBackSuccess" - bind:fail="handleBackFail" - bind:complete="handleBackComplete" style="--td-navbar-color: {{navBarTextColor}};--td-navbar-bg-color: {{navBarBackgroundColor}};" >