docs: 更新 page-container 组件文档，重命名导航栏属性，添加样式变量说明及示例，优化返回按钮逻辑

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
-<page-container title="页面标题">
+<page-container nav-bar-title="页面标题">
   <view>页面内容</view>
 </page-container>
 ```
@@ -39,10 +40,11 @@ PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件
 ### 自定义导航栏样式
 
 ```xml
-<page-container 
+<page-container
-  title="页面标题" 
+  nav-bar-title="页面标题"
-  backgroundColor="#123321" 
+  nav-bar-background-color="#123321"
-  textColor="#ffffff">
+  nav-bar-text-color="#ffffff"
+>
   <view>页面内容</view>
 </page-container>
 ```
@@ -50,7 +52,7 @@ PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件
 ### 隐藏返回按钮
 
 ```xml
-<page-container title="页面标题" left-arrow="{{false}}">
+<page-container nav-bar-title="页面标题" nav-bar-left-arrow="{{false}}">
   <view>页面内容</view>
 </page-container>
 ```
@@ -58,38 +60,80 @@ PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件
 ### 隐藏导航栏
 
 ```xml
-<page-container title="页面标题" visible="{{false}}">
+<page-container nav-bar-title="页面标题" nav-bar-visible="{{false}}">
   <view>页面内容</view>
 </page-container>
 ```
 
+### 关闭底部安全区适配
+
+```xml
+<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`
+
 ## 属性说明
 
+### 导航栏相关
+
 | 属性名 | 类型 | 默认值 | 说明 |
 |--------|------|--------|------|
-| title | String | '' | 导航栏标题 |
+| navBarTitle | String | '' | 导航栏标题 |
-| leftArrow | Boolean | true | 是否显示返回按钮 |
+| navBarLeftArrow | Boolean | true | 是否显示返回按钮 |
-| fixed | Boolean | true | 导航栏是否固定 |
+| navBarFixed | Boolean | true | 导航栏是否固定 |
-| placeholder | Boolean | true | 导航栏占位 |
+| navBarPlaceholder | Boolean | true | 导航栏占位 |
-| safeAreaInsetTop | Boolean | true | 是否适配安全区域顶部 |
+| navBarSafeAreaInsetTop | Boolean | true | 是否适配安全区域顶部 |
-| zIndex | Number | 10000 | 导航栏层级 |
+| navBarZIndex | Number | 10000 | 导航栏层级 |
-| animation | Boolean | true | 是否带动画效果 |
+| navBarAnimation | Boolean | true | 是否带动画效果 |
-| delta | Number | 1 | 后退的层数 |
+| navBarTitleMaxLength | Number | undefined | 标题最大长度，超出用 "…" 表示 |
-| titleMaxLength | Number | undefined | 标题最大长度，超出用 "…" 表示 |
+| navBarVisible | Boolean | true | 是否显示导航栏 |
-| visible | Boolean | true | 是否显示导航栏 |
+| navBarBackgroundColor | String | '#ffffff' | 导航栏背景色 |
-| backgroundColor | String | '#ffffff' | 导航栏背景色 |
+| navBarTextColor | String | '#000000' | 导航栏文本颜色（标题、返回按钮等） |
-| textColor | String | '#000000' | 导航栏文本颜色（标题、返回按钮等） |
+
+### 内容容器相关
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| containerSafeAreaInsetBottom | Boolean | true | 是否开启底部安全区适配 |
+| containerBackgroundColor | String | '#f5f5f5' | 内容区域背景色 |
 
 ## 插槽说明
 
-组件提供了三个插槽用于自定义导航栏内容：
+组件提供导航栏插槽与默认插槽，用于自定义页面内容布局。
+
+### 默认插槽
+
+默认插槽用于渲染页面主体内容（位于内容区域 `page-container__content` 内）：
+
+```xml
+<page-container nav-bar-title="页面标题">
+  <view>页面内容</view>
+</page-container>
+```
 
 ### left 插槽
 
 自定义左侧内容（返回按钮区域）：
 
 ```xml
-<page-container title="页面标题">
+<page-container nav-bar-title="页面标题">
   <view slot="left">自定义左侧内容</view>
   <view>页面内容</view>
 </page-container>
@@ -100,7 +144,7 @@ PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件
 自定义胶囊区域内容：
 
 ```xml
-<page-container title="页面标题">
+<page-container nav-bar-title="页面标题">
   <view slot="capsule">自定义胶囊内容</view>
   <view>页面内容</view>
 </page-container>
@@ -111,7 +155,7 @@ PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件
 自定义标题区域内容：
 
 ```xml
-<page-container title="页面标题">
+<page-container nav-bar-title="页面标题">
   <view slot="title">自定义标题内容</view>
   <view>页面内容</view>
 </page-container>
@@ -121,18 +165,19 @@ PageContainer 是一个基于 TDesign Navbar 组件封装的页面容器组件
 
 | 事件名 | 说明 | 回调参数 |
 |--------|------|----------|
-| success | 返回成功时触发 | event.detail |
+| success | `wx.navigateBack` 成功时触发 | `event.detail`（navigateBack 成功回调参数） |
-| fail | 返回失败时触发 | event.detail |
+| fail | `wx.navigateBack` 失败时触发 | `event.detail`（navigateBack 失败回调参数） |
-| complete | 返回完成时触发（无论成功或失败） | event.detail |
+| complete | `wx.navigateBack` 完成时触发（无论成功或失败） | `event.detail`（success/fail 的参数之一） |
 
 ### 事件使用示例
 
 ```xml
-<page-container 
+<page-container
-  title="页面标题"
+  nav-bar-title="页面标题"
   bind:success="onBackSuccess"
   bind:fail="onBackFail"
-  bind:complete="onBackComplete">
+  bind:complete="onBackComplete"
+>
   <view>页面内容</view>
 </page-container>
 ```
@@ -153,16 +198,15 @@ Page({
 
 ## 返回按钮显示逻辑
 
-组件会自动判断是否显示返回按钮，判断规则如下：
+组件在实例进入页面节点树时，根据以下条件计算返回按钮是否显示：
 
-1. 如果页面栈中只有一个页面（首页），则不显示返回按钮
+```text
-2. 如果 `leftArrow` 属性为 `false`，则不显示返回按钮
+showLeftArrow = getCurrentPages().length > 1 && navBarLeftArrow && navBarVisible
-3. 如果 `visible` 属性为 `false`，则不显示返回按钮
+```
-4. 其他情况显示返回按钮
 
 ## 注意事项
 
-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
 <!-- pages/example/index.wxml -->
-<page-container 
+<page-container
-  title="示例页面"
+  nav-bar-title="示例页面"
-  backgroundColor="#ffffff"
+  nav-bar-background-color="#ffffff"
-  textColor="#000000"
+  nav-bar-text-color="#000000"
-  left-arrow="{{true}}"
+  nav-bar-left-arrow="{{true}}"
-  fixed="{{true}}"
+  nav-bar-fixed="{{true}}"
-  placeholder="{{true}}"
+  nav-bar-placeholder="{{true}}"
-  safe-area-inset-top="{{true}}"
+  nav-bar-safe-area-inset-top="{{true}}"
-  bind:success="onBackSuccess">
+  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>
@@ -210,5 +258,11 @@ Page({
   onBackSuccess(res) {
     console.log('页面返回成功', res)
   },
+  onBackFail(err) {
+    console.log('页面返回失败', err)
+  },
+  onBackComplete(res) {
+    console.log('页面返回完成', res)
+  },
 })
 ```

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

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}};"
   >
     <!-- 左侧自定义内容插槽 -->