jianghu-ui 1.0.6 → 1.0.8

package/src/components/JhLayout/JhLayout.md

@@ -1,580 +0,0 @@
-# JhLayout - 页面布局组件
-
-基于 Ant Design Pro 的 ProLayout 设计的企业级页面布局组件，提供完整的中后台布局解决方案。
-
-## 功能特性
-
-### 🎨 多种布局模式
-
-- **侧边布局 (side)**: 经典的侧边栏导航布局，适合菜单项较多的场景
-- **顶部布局 (top)**: 顶部导航栏布局，适合菜单项较少的场景
-- **混合布局 (mix)**: 顶部 + 侧边栏混合布局，适合复杂的导航结构
-
-### 🎯 核心功能
-
-- ✅ **响应式设计**: 自动适配移动端和桌面端
-- ✅ **可折叠侧边栏**: 支持侧边栏折叠/展开，节省空间
-- ✅ **自动面包屑**: 根据路由自动生成面包屑导航
-- ✅ **多级菜单**: 支持三级菜单嵌套
-- ✅ **主题切换**: 支持亮色/暗色主题
-- ✅ **页面头部**: 可选的页面标题和描述区域
-- ✅ **底部区域**: 可自定义的页脚内容
-- ✅ **用户菜单**: 内置用户头像和下拉菜单
-- ✅ **设置面板**: 实时调整布局配置
-
-## 基础用法
-
-```vue
-<template>
-  <jh-layout
-    title="我的应用"
-    logo="mdi-view-dashboard"
-    :menu-data="menuData"
-    :current-path="currentPath"
-    @menu-click="handleMenuClick"
-  >
-    <!-- 主内容区域 -->
-    <v-container>
-      <h1>欢迎使用 JhLayout</h1>
-    </v-container>
-  </jh-layout>
-</template>
-
-<script>
-export default {
-  data() {
-    return {
-      currentPath: '/dashboard',
-      menuData: [
-        {
-          name: '工作台',
-          path: '/dashboard',
-          icon: 'mdi-view-dashboard'
-        },
-        {
-          name: '用户管理',
-          icon: 'mdi-account-group',
-          children: [
-            {
-              name: '用户列表',
-              path: '/users/list',
-              icon: 'mdi-account-multiple'
-            }
-          ]
-        }
-      ]
-    };
-  },
-  methods: {
-    handleMenuClick(item) {
-      this.currentPath = item.path;
-      // 路由跳转逻辑
-    }
-  }
-};
-</script>
-```
-
-## Props
-
-| 参数 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| title | 应用标题 | String | 'JianghuJS' |
-| logo | Logo 图标名称（Material Design Icons） | String | '' |
-| menuData | 菜单数据 | Array | [] |
-| currentPath | 当前路由路径 | String | '' |
-| layout | 布局模式：side/top/mix | String | 'side' |
-| sidebarWidth | 侧边栏宽度 | Number | 256 |
-| headerHeight | 头部高度 | Number | 64 |
-| headerTheme | 头部主题：light/dark | String | 'light' |
-| sidebarTheme | 侧边栏主题：light/dark | String | 'dark' |
-| footerTheme | 底部主题：light/dark | String | 'light' |
-| showBreadcrumb | 是否显示面包屑 | Boolean | true |
-| breadcrumbs | 自定义面包屑数据 | Array | [] |
-| showPageHeader | 是否显示页面头部 | Boolean | false |
-| pageTitle | 页面标题 | String | '' |
-| pageDescription | 页面描述 | String | '' |
-| showFooter | 是否显示底部 | Boolean | false |
-| footerText | 底部文字 | String | '' |
-| contentBackground | 内容区域背景色 | String | '#f5f5f5' |
-| contentPadding | 内容区域是否有内边距 | Boolean | true |
-| showAvatar | 是否显示用户头像 | Boolean | true |
-| userInfo | 用户信息对象 | Object | { username: 'Guest', email: '' } |
-| avatarMenuList | 用户菜单列表 | Array | [] |
-| showLogout | 是否显示退出登录 | Boolean | true |
-| showSettings | 是否显示设置按钮 | Boolean | false |
-| defaultCollapsed | 初始折叠状态 | Boolean | false |
-
-## 菜单数据结构
-
-```javascript
-const menuData = [
-  {
-    name: '菜单名称',
-    path: '/path',           // 菜单路径
-    icon: 'mdi-icon-name',   // 图标（可选）
-    children: [              // 子菜单（可选）
-      {
-        name: '子菜单',
-        path: '/path/child',
-        icon: 'mdi-icon-name',
-        children: [          // 三级菜单（可选）
-          {
-            name: '三级菜单',
-            path: '/path/child/grandchild'
-          }
-        ]
-      }
-    ]
-  }
-];
-```
-
-## 插槽
-
-### logo
-自定义 Logo 区域
-
-```vue
-<jh-layout>
-  <template v-slot:logo>
-    <div class="d-flex align-center">
-      <v-avatar color="primary" size="32" class="mr-2">
-        <span class="white--text">JH</span>
-      </v-avatar>
-      <span class="text-h6">JianghuJS</span>
-    </div>
-  </template>
-</jh-layout>
-```
-
-### headerRight
-自定义头部右侧内容
-
-```vue
-<jh-layout>
-  <template v-slot:headerRight>
-    <v-btn icon>
-      <v-badge content="5" color="error">
-        <v-icon>mdi-bell</v-icon>
-      </v-badge>
-    </v-btn>
-  </template>
-</jh-layout>
-```
-
-### pageHeader
-自定义页面头部
-
-```vue
-<jh-layout show-page-header>
-  <template v-slot:pageHeader>
-    <div>
-      <h2>自定义页面头部</h2>
-      <p>这里可以放置统计数据、图表等内容</p>
-    </div>
-  </template>
-</jh-layout>
-```
-
-### pageHeaderExtra
-页面头部额外操作区
-
-```vue
-<jh-layout show-page-header>
-  <template v-slot:pageHeaderExtra>
-    <v-btn color="primary">新增</v-btn>
-  </template>
-</jh-layout>
-```
-
-### default
-主内容区域（默认插槽）
-
-```vue
-<jh-layout>
-  <v-container>
-    <!-- 您的页面内容 -->
-  </v-container>
-</jh-layout>
-```
-
-### footer
-自定义底部内容
-
-```vue
-<jh-layout show-footer>
-  <template v-slot:footer>
-    <div class="text-center">
-      © 2024 My Company
-    </div>
-  </template>
-</jh-layout>
-```
-
-### sidebarFooter
-侧边栏底部内容
-
-```vue
-<jh-layout>
-  <template v-slot:sidebarFooter>
-    <v-btn block small>帮助文档</v-btn>
-  </template>
-</jh-layout>
-```
-
-## 事件
-
-| 事件名 | 说明 | 回调参数 |
-|--------|------|----------|
-| menu-click | 菜单点击事件 | (item: MenuItem) |
-| breadcrumb-click | 面包屑点击事件 | (item: BreadcrumbItem) |
-| avatar-menu-click | 用户菜单点击事件 | (item: MenuItem) |
-| logout | 退出登录事件 | - |
-| sidebar-toggle | 侧边栏切换事件 | { collapsed: Boolean, visible: Boolean } |
-| update:layout | 布局模式更新 | (layout: String) |
-| update:headerTheme | 头部主题更新 | (theme: String) |
-| update:sidebarTheme | 侧边栏主题更新 | (theme: String) |
-| update:showBreadcrumb | 面包屑显示更新 | (show: Boolean) |
-| update:showFooter | 底部显示更新 | (show: Boolean) |
-| update:contentPadding | 内容内边距更新 | (padding: Boolean) |
-
-## 使用示例
-
-### 侧边布局
-
-```vue
-<template>
-  <jh-layout
-    title="管理系统"
-    logo="mdi-view-dashboard"
-    layout="side"
-    :menu-data="menuData"
-    :current-path="currentPath"
-    sidebar-theme="dark"
-    header-theme="light"
-    show-breadcrumb
-    show-page-header
-    :page-title="pageTitle"
-    @menu-click="handleMenuClick"
-  >
-    <v-container>
-      <!-- 页面内容 -->
-    </v-container>
-  </jh-layout>
-</template>
-```
-
-### 顶部布局
-
-```vue
-<template>
-  <jh-layout
-    title="管理系统"
-    layout="top"
-    :menu-data="menuData"
-    header-theme="dark"
-  >
-    <v-container>
-      <!-- 页面内容 -->
-    </v-container>
-  </jh-layout>
-</template>
-```
-
-### 混合布局
-
-```vue
-<template>
-  <jh-layout
-    title="管理系统"
-    layout="mix"
-    :menu-data="menuData"
-    sidebar-theme="light"
-  >
-    <v-container>
-      <!-- 页面内容 -->
-    </v-container>
-  </jh-layout>
-</template>
-```
-
-### 完整示例（带表格）
-
-```vue
-<template>
-  <jh-layout
-    title="用户管理系统"
-    logo="mdi-account-group"
-    :menu-data="menuData"
-    :current-path="currentPath"
-    show-breadcrumb
-    show-page-header
-    page-title="用户列表"
-    page-description="管理系统中的所有用户"
-    show-footer
-    footer-text="Copyright © 2024 My Company"
-    :user-info="userInfo"
-    :avatar-menu-list="avatarMenuList"
-    show-settings
-    @menu-click="handleMenuClick"
-    @logout="handleLogout"
-  >
-    <template v-slot:pageHeaderExtra>
-      <v-btn color="primary" @click="handleAdd">
-        <v-icon left>mdi-plus</v-icon>
-        新增用户
-      </v-btn>
-    </template>
-
-    <v-card>
-      <v-data-table
-        :headers="headers"
-        :items="users"
-        :loading="loading"
-      >
-        <!-- 表格内容 -->
-      </v-data-table>
-    </v-card>
-  </jh-layout>
-</template>
-
-<script>
-export default {
-  data() {
-    return {
-      currentPath: '/users/list',
-      menuData: [
-        {
-          name: '工作台',
-          path: '/dashboard',
-          icon: 'mdi-view-dashboard'
-        },
-        {
-          name: '用户管理',
-          icon: 'mdi-account-group',
-          children: [
-            {
-              name: '用户列表',
-              path: '/users/list',
-              icon: 'mdi-account-multiple'
-            },
-            {
-              name: '角色管理',
-              path: '/users/roles',
-              icon: 'mdi-shield-account'
-            }
-          ]
-        }
-      ],
-      userInfo: {
-        username: '管理员',
-        email: 'admin@example.com'
-      },
-      avatarMenuList: [
-        {
-          name: '个人中心',
-          icon: 'mdi-account-circle',
-          path: '/profile'
-        },
-        {
-          name: '账户设置',
-          icon: 'mdi-cog',
-          path: '/settings'
-        }
-      ],
-      headers: [
-        { text: 'ID', value: 'id' },
-        { text: '用户名', value: 'username' },
-        { text: '邮箱', value: 'email' }
-      ],
-      users: [],
-      loading: false
-    };
-  },
-  methods: {
-    handleMenuClick(item) {
-      if (item.path) {
-        this.currentPath = item.path;
-        // 路由跳转
-      }
-    },
-    handleLogout() {
-      // 退出登录逻辑
-    },
-    handleAdd() {
-      // 新增用户逻辑
-    }
-  }
-};
-</script>
-```
-
-## 响应式设计
-
-JhLayout 组件会自动适配不同屏幕尺寸：
-
-- **桌面端（>= 960px）**: 显示完整的侧边栏和菜单
-- **移动端（< 960px）**: 侧边栏自动转换为抽屉式，通过按钮控制显示/隐藏
-
-## 主题定制
-
-### 使用内置主题
-
-```vue
-<jh-layout
-  header-theme="dark"
-  sidebar-theme="dark"
-  footer-theme="dark"
->
-</jh-layout>
-```
-
-### 自定义背景色
-
-```vue
-<jh-layout
-  content-background="#ffffff"
->
-</jh-layout>
-```
-
-## 最佳实践
-
-1. **菜单数据管理**: 建议将菜单数据统一管理，可以从后端获取或在配置文件中定义
-2. **路由同步**: 使用 `currentPath` 属性与路由保持同步
-3. **权限控制**: 在菜单数据中添加权限字段，根据用户权限动态过滤菜单
-4. **面包屑**: 如果路由结构复杂，建议自定义 `breadcrumbs` 数据
-5. **移动端优化**: 在移动端建议隐藏页面头部和底部，保持界面简洁
-
-## 与其他组件配合
-
-JhLayout 可以与其他 JianghuJS 组件完美配合：
-
-- **JhPageContainer**: 推荐在 JhLayout 的内容区域使用 JhPageContainer 作为页面容器，提供统一的页面头部和内容布局
-- **JhTable**: 在内容区域展示数据表格
-- **JhForm**: 在内容区域展示表单
-- **JhQueryFilter**: 在页面头部额外操作区添加搜索过滤
-- **JhDrawer**: 作为侧边抽屉使用
-- **JhModal**: 作为弹窗使用
-
-### 推荐的组件组合
-
-**JhLayout + JhPageContainer + JhTable**
-
-这是最常用的页面结构组合，适用于大多数列表页面：
-
-```vue
-<template>
-  <jh-layout
-    title="管理系统"
-    :menu-data="menuData"
-    :current-path="currentPath"
-    show-breadcrumb
-    :content-padding="false"
-  >
-    <jh-page-container
-      page-name="用户管理"
-      :show-help-button="true"
-    >
-      <template v-slot:search-bar>
-        <jh-query-filter
-          :keyword.sync="keyword"
-          :keywordFieldList.sync="keywordFieldList"
-          :headers="headers"
-          @search="handleSearch"
-        />
-      </template>
-
-      <template v-slot:content>
-        <jh-table
-          :headers="headers"
-          :items="items"
-          :loading="loading"
-        />
-      </template>
-    </jh-page-container>
-  </jh-layout>
-</template>
-```
-
-**说明**：
-- `JhLayout` 提供应用级布局（导航、头部、侧边栏）
-- `JhPageContainer` 提供页面级容器（页面标题、搜索栏）
-- `JhTable` 提供数据表格展示
-- 当使用 `JhPageContainer` 时，建议设置 `JhLayout` 的 `content-padding="false"` 和 `show-page-header="false"`，避免重复的内边距和头部
-
-## 常见问题
-
-### 如何自定义面包屑？
-
-通过 `breadcrumbs` 属性传入自定义面包屑数据：
-
-```vue
-<jh-layout
-  :breadcrumbs="[
-    { text: '首页', path: '/', icon: 'mdi-home' },
-    { text: '用户管理', path: '/users' },
-    { text: '用户列表', disabled: true }
-  ]"
->
-</jh-layout>
-```
-
-### 如何隐藏某些功能？
-
-通过对应的 `show*` 属性控制：
-
-```vue
-<jh-layout
-  :show-breadcrumb="false"
-  :show-page-header="false"
-  :show-footer="false"
-  :show-avatar="false"
-  :show-settings="false"
->
-</jh-layout>
-```
-
-### 如何实现路由跳转？
-
-在 `menu-click` 事件中处理路由跳转：
-
-```javascript
-handleMenuClick(item) {
-  if (item.path) {
-    this.$router.push(item.path);
-    this.currentPath = item.path;
-  }
-}
-```
-
-### 如何保存用户的布局设置？
-
-监听 `update:*` 事件，将设置保存到 localStorage 或后端：
-
-```vue
-<jh-layout
-  @update:layout="saveLayoutSetting"
-  @update:headerTheme="saveThemeSetting"
->
-</jh-layout>
-```
-
-## 更新日志
-
-### v1.0.0 (2024-01-01)
-
-- ✨ 初始版本发布
-- ✨ 支持侧边、顶部、混合三种布局模式
-- ✨ 支持亮色/暗色主题
-- ✨ 自动生成面包屑导航
-- ✨ 响应式设计
-- ✨ 设置面板
-- ✨ 多级菜单支持
-
-## 参考资料
-
-- [Ant Design Pro - ProLayout](https://procomponents.ant.design/components/layout)
-- [Vuetify - Application](https://vuetifyjs.com/en/components/application/)
-- [Material Design Icons](https://materialdesignicons.com/)