From 463d7921c1d1ef038ab852f176ddd39102fbf2e4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BC=A0=E6=88=90?= <light.zhang@ysinc.com>
Date: Wed, 26 Nov 2025 17:50:14 +0800
Subject: [PATCH] 1

---
 _doc/使用说明.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++-
 _doc/快速开始.md |   1 +
 2 files changed, 162 insertions(+), 1 deletion(-)

diff --git a/_doc/使用说明.md b/_doc/使用说明.md
index 95148cc..c9f3c8a 100644
--- a/_doc/使用说明.md
+++ b/_doc/使用说明.md
@@ -11,7 +11,7 @@
 - ✅ **登录和权限管理** - 完整的登录流程和权限控制
 - ✅ **动态路由管理** - 基于权限菜单的动态路由生成
 - ✅ **Vuex 状态管理** - 用户、应用状态管理
-- ✅ **全局组件库** - Tables、Editor、Upload、TreeGrid、FieldRenderer 等
+- ✅ **全局组件库** - Tables、Editor、Upload、TreeGrid、FieldRenderer、FloatPanel 等
 - ✅ **工具库** - HTTP、日期、Token、Cookie 等工具
 - ✅ **内置样式** - base.less、animate.css、iconfont 等
 - ✅ **响应式布局** - 支持移动端适配
@@ -450,6 +450,166 @@ export default {
 - ✅ **浏览器兼容**：支持所有现代浏览器
 - ✅ **内存管理**：自动清理临时 URL 对象
 
+## 🎨 全局组件使用
+
+### FloatPanel - 浮动面板组件
+
+`FloatPanel` 是一个浮动在父窗体上的面板组件，类似于抽屉效果，常用于详情展示、表单编辑等场景。
+
+**基本使用：**
+
+```vue
+<template>
+  <div>
+    <Button @click="showPanel">打开浮动面板</Button>
+    
+    <FloatPanel
+      ref="floatPanel"
+      title="详情面板"
+      position="right"
+      :show-back="true"
+      back-text="返回"
+      @back="handleBack"
+    >
+      <div>这里是面板内容</div>
+    </FloatPanel>
+  </div>
+</template>
+
+<script>
+export default {
+  methods: {
+    showPanel() {
+      // 通过 ref 调用 show 方法显示面板
+      this.$refs.floatPanel.show()
+    },
+    hidePanel() {
+      // 通过 ref 调用 hide 方法隐藏面板
+      this.$refs.floatPanel.hide()
+    },
+    handleBack() {
+      console.log('返回按钮被点击')
+      this.hidePanel()
+    }
+  }
+}
+</script>
+```
+
+**属性说明：**
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `title` | String | `''` | 面板标题 |
+| `width` | String/Number | `'100%'` | 面板宽度（字符串或数字），默认占满父容器 |
+| `height` | String/Number | `'100%'` | 面板高度（字符串或数字），默认占满父容器 |
+| `position` | String | `'right'` | 面板位置：`left`、`right`、`top`、`bottom`、`center` |
+| `showBack` | Boolean | `true` | 是否显示返回按钮 |
+| `showClose` | Boolean | `false` | 是否显示关闭按钮 |
+| `backText` | String | `'返回'` | 返回按钮文字 |
+| `closeOnClickBackdrop` | Boolean | `false` | 点击遮罩是否关闭 |
+| `mask` | Boolean | `false` | 是否显示遮罩（默认不显示） |
+| `zIndex` | Number | `1000` | 层级 |
+
+**方法：**
+
+| 方法 | 说明 | 参数 |
+|------|------|------|
+| `show(callback)` | 显示面板 | `callback`: 可选的回调函数 |
+| `hide()` | 隐藏面板 | - |
+
+**事件：**
+
+| 事件 | 说明 | 参数 |
+|------|------|------|
+| `back` | 点击返回按钮时触发 | - |
+
+**插槽：**
+
+| 插槽 | 说明 |
+|------|------|
+| `default` | 面板主体内容 |
+| `header-right` | 头部右侧内容（可用于添加自定义按钮） |
+
+**位置说明：**
+
+- `left`: 从左侧滑入
+- `right`: 从右侧滑入（默认）
+- `top`: 从顶部滑入
+- `bottom`: 从底部滑入
+- `center`: 居中显示，带缩放动画
+
+**完整示例：**
+
+```vue
+<template>
+  <div>
+    <Button @click="openDetailPanel">查看详情</Button>
+    
+    <FloatPanel
+      ref="detailPanel"
+      title="用户详情"
+      position="right"
+      :show-back="true"
+      :show-close="true"
+      back-text="返回"
+      @back="handleBack"
+    >
+      <template #header-right>
+        <Button type="primary" @click="handleSave">保存</Button>
+      </template>
+      
+      <div class="detail-content">
+        <Form :model="formData" :label-width="100">
+          <FormItem label="用户名">
+            <Input v-model="formData.username" />
+          </FormItem>
+          <FormItem label="邮箱">
+            <Input v-model="formData.email" />
+          </FormItem>
+        </Form>
+      </div>
+    </FloatPanel>
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      formData: {
+        username: '',
+        email: ''
+      }
+    }
+  },
+  methods: {
+    openDetailPanel() {
+      this.$refs.detailPanel.show()
+    },
+    handleBack() {
+      this.$refs.detailPanel.hide()
+    },
+    handleSave() {
+      // 保存逻辑
+      console.log('保存数据', this.formData)
+      this.$Message.success('保存成功')
+      this.$refs.detailPanel.hide()
+    }
+  }
+}
+</script>
+```
+
+**特性说明：**
+
+- ✅ 基于父元素定位，不会遮挡菜单
+- ✅ 宽度和高度默认 100%，占满父容器
+- ✅ 无遮罩背景，完全浮在父页面上
+- ✅ 路由切换或组件销毁时自动关闭
+- ✅ 支持多种位置和动画效果
+- ✅ 支持自定义头部右侧内容
+
 ## 📝 业务开发示例
 
 ### 创建业务页面
diff --git a/_doc/快速开始.md b/_doc/快速开始.md
index 9fa19a7..1fa2abe 100644
--- a/_doc/快速开始.md
+++ b/_doc/快速开始.md
@@ -172,6 +172,7 @@ app.$mount('#app')
 - ✅ `<AsyncModal>` - 异步弹窗
 - ✅ `<Editor>` - 富文本编辑器
 - ✅ `<CommonIcon>` - 图标选择器
+- ✅ `<FloatPanel>` - 浮动面板
 
 ### 4. 工具方法