From c76ed97602b46b80928ce18debdb5e1e94f06d61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=86=8A=E7=86=8A=E7=86=8A=E5=AD=90=E8=B7=AF?= Date: Fri, 16 Jan 2026 16:02:18 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20PageContainer=20?= =?UTF-8?q?=E7=BB=84=E4=BB=B6=E4=BD=BF=E7=94=A8=E6=89=8B=E5=86=8C=E5=8F=8A?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=20README=20=E6=96=87=E6=A1=A3=E4=BB=A5?= =?UTF-8?q?=E5=8C=85=E5=90=AB=E7=BB=84=E4=BB=B6=E4=BB=8B=E7=BB=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 14 +++ docs/page-container.md | 214 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 228 insertions(+) create mode 100644 docs/page-container.md diff --git a/README.md b/README.md index 0729c27..b0998ab 100644 --- a/README.md +++ b/README.md @@ -230,6 +230,20 @@ const strDate = formatDateTime('2024-01-15', 'YYYY年MM月DD日') - `A`: 上午/下午 - `a`: 上午/下午(小写) +### PageContainer 页面容器组件 + +项目提供了基于 TDesign Navbar 封装的页面容器组件，位于 `miniprogram/components/page-container/` 目录。 + +**主要特性：** + +- 基于 TDesign Navbar 组件，提供统一的导航栏和内容区域布局 +- 自动判断返回按钮显示（根据页面栈深度） +- 支持安全区域适配，适配不同设备 +- 支持自定义导航栏样式和插槽内容 +- 完整的返回事件回调支持 + +详细使用说明请参考 [PageContainer 组件使用手册](docs/page-container.md)。 + ### 自定义 TabBar 项目提供了基于 TDesign 组件的自定义 TabBar 实现，位于 `miniprogram/custom-tab-bar/` 目录。 diff --git a/docs/page-container.md b/docs/page-container.md new file mode 100644 index 0000000..6f3849e --- /dev/null +++ b/docs/page-container.md @@ -0,0 +1,214 @@ +# PageContainer 组件使用手册 + +## 概述 + +PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件，提供了统一的导航栏和内容区域布局，简化了小程序页面的开发流程。组件自动处理返回按钮显示逻辑、安全区域适配等常见需求。 + +## 功能特性 + +- 基于 TDesign Navbar 组件，样式统一美观 +- 自动判断返回按钮显示（根据页面栈深度） +- 支持安全区域适配（适配刘海屏等特殊设备） +- 支持固定导航栏和占位符 +- 支持自定义导航栏样式（背景色、文本颜色） +- 提供多个插槽支持自定义内容 +- 支持返回事件回调 + +## 引入组件 + +在页面的 `json` 配置文件中引入组件： + +```json +{ + "usingComponents": { + "page-container": "../../components/page-container/page-container" + } +} +``` + +## 基础用法 + +### 最简单的用法 + +```xml + + 页面内容 + +``` + +### 自定义导航栏样式 + +```xml + + 页面内容 + +``` + +### 隐藏返回按钮 + +```xml + + 页面内容 + +``` + +### 隐藏导航栏 + +```xml + + 页面内容 + +``` + +## 属性说明 + +| 属性名 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| 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 插槽 + +自定义左侧内容（返回按钮区域）： + +```xml + + 自定义左侧内容 + 页面内容 + +``` + +### capsule 插槽 + +自定义胶囊区域内容： + +```xml + + 自定义胶囊内容 + 页面内容 + +``` + +### title 插槽 + +自定义标题区域内容： + +```xml + + 自定义标题内容 + 页面内容 + +``` + +## 事件说明 + +| 事件名 | 说明 | 回调参数 | +|--------|------|----------| +| success | 返回成功时触发 | event.detail | +| fail | 返回失败时触发 | event.detail | +| complete | 返回完成时触发（无论成功或失败） | event.detail | + +### 事件使用示例 + +```xml + + 页面内容 + +``` + +```typescript +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` 配置中关闭原生导航栏： + +```json +{ + "navigationStyle": "custom" +} +``` + +3. 组件会自动处理返回按钮的显示逻辑，无需手动判断页面栈 +4. 如需自定义返回行为，可以通过监听 `success`、`fail`、`complete` 事件来实现 +5. 使用 `delta` 属性可以控制返回的页面层数，默认为 1（返回上一页） + +## 完整示例 + +```xml + + + + 这是页面内容区域 + + +``` + +```json +// pages/example/index.json +{ + "navigationStyle": "custom", + "usingComponents": { + "page-container": "../../components/page-container/page-container" + } +} +``` + +```typescript +// pages/example/index.ts +Page({ + onBackSuccess(res) { + console.log('页面返回成功', res) + }, +}) +```