jianghu-ui 1.0.1

package/src/components/JhMask/JhMask.vue

@@ -0,0 +1,123 @@
+<template>
+  <v-overlay
+    :value="value"
+    :opacity="opacity"
+    :color="color"
+    :z-index="zIndex"
+    @click="handleClick"
+  >
+    <slot>
+      <v-progress-circular
+        v-if="showLoading"
+        :size="loadingSize"
+        :width="loadingWidth"
+        :color="loadingColor"
+        indeterminate
+      ></v-progress-circular>
+    </slot>
+  </v-overlay>
+</template>
+
+<script>
+export default {
+  name: 'JhMask',
+  props: {
+    // 是否显示遮罩
+    value: {
+      type: Boolean,
+      default: false,
+    },
+    // 背景颜色
+    color: {
+      type: String,
+      default: '#e3e3e3',
+    },
+    // 透明度 (0-1)
+    opacity: {
+      type: [Number, String],
+      default: 0.8,
+      validator: (v) => {
+        const num = parseFloat(v);
+        return num >= 0 && num <= 1;
+      },
+    },
+    // z-index
+    zIndex: {
+      type: [Number, String],
+      default: 300,
+    },
+    // 是否显示 loading 动画
+    showLoading: {
+      type: Boolean,
+      default: false,
+    },
+    // loading 大小
+    loadingSize: {
+      type: [Number, String],
+      default: 64,
+    },
+    // loading 宽度
+    loadingWidth: {
+      type: [Number, String],
+      default: 7,
+    },
+    // loading 颜色
+    loadingColor: {
+      type: String,
+      default: 'primary',
+    },
+    // 点击遮罩是否关闭
+    closeOnClick: {
+      type: Boolean,
+      default: false,
+    },
+    // 自动关闭时间 (毫秒), 0 表示不自动关闭
+    timeout: {
+      type: Number,
+      default: 0,
+    },
+  },
+  data() {
+    return {
+      timer: null,
+    };
+  },
+  watch: {
+    value(newVal) {
+      if (newVal && this.timeout > 0) {
+        this.startTimer();
+      } else if (!newVal) {
+        this.clearTimer();
+      }
+    },
+  },
+  beforeDestroy() {
+    this.clearTimer();
+  },
+  methods: {
+    handleClick() {
+      if (this.closeOnClick) {
+        this.$emit('input', false);
+        this.$emit('click');
+      }
+    },
+    startTimer() {
+      this.clearTimer();
+      this.timer = setTimeout(() => {
+        this.$emit('input', false);
+        this.$emit('timeout');
+      }, this.timeout);
+    },
+    clearTimer() {
+      if (this.timer) {
+        clearTimeout(this.timer);
+        this.timer = null;
+      }
+    },
+  },
+};
+</script>
+
+<style scoped>
+/* 自定义样式可以在这里添加 */
+</style>

package/src/components/JhMenu/JhMenu.md

@@ -0,0 +1,85 @@
+# JhMenu - 响应式导航菜单
+
+JhMenu 提供桌面/移动端统一的导航栏，集成多级菜单、右侧自定义菜单及用户头像菜单，适合后台管理与工作台场景。
+
+## 功能特性
+
+- 📱 **响应式布局**：自动在移动端显示抽屉菜单与头像抽屉
+- 🌲 **多级菜单**：支持至多三级结构，含折叠/展开交互
+- 🧭 **多入口组合**：左侧主菜单、右侧快捷菜单、头像下拉菜单可同时存在
+- 🔔 **状态同步**：通过 `activeMenuIndex/activeSecondMenuId` 控制当前高亮
+- 🔒 **账号信息展示**：内置用户名、角色标签、登出操作
+
+## 基础用法
+
+```vue
+<template>
+  <jh-menu
+    :app-title="'工作台'"
+    :menu-list="menus"
+    :right-menu-list="[{ title: '帮助', icon: 'mdi-help-circle' }]"
+    :avatar-menu-list="[{ title: '个人设置', id: 'profile' }]"
+    :user-info="user"
+    @menu-click="handleMenu"
+    @logout="logout"
+  />
+</template>
+```
+
+## API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| appTitle | 应用标题 | string | `JianghuJS` |
+| menuList | 左侧多级菜单数据 | Array | [] |
+| rightMenuList | 顶部右侧快捷菜单数据 | Array | [] |
+| avatarMenuList | 头像下拉菜单数据 | Array | [] |
+| userInfo | 用户信息 `{ username,userId,roles }` | Object | `{ username: 'Guest', userId: '', roles: [] }` |
+| showAvatar | 是否展示头像区域 | boolean | true |
+| activeMenuIndex | 当前激活的一级菜单索引 | number | -1 |
+| activeSecondMenuId | 当前激活的二级/三级菜单 id | string | null |
+| temporary | 移动端抽屉是否点击遮罩关闭 | boolean | true |
+| hideDrawers | Storybook 模式下隐藏抽屉 | boolean | false |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| menu-click | 任意菜单被点击时触发 | (menuItem: object, index?: number) |
+| logout | 点击登出按钮时触发 | - |
+
+### Slots
+
+该组件不暴露插槽，如需扩展请在 `menuList/rightMenuList` 数据中配置。
+
+## 数据结构示例
+
+```js
+const menus = [
+  {
+    title: '首页',
+    id: 'home',
+    path: '/dashboard'
+  },
+  {
+    title: '系统管理',
+    children: [
+      { title: '用户管理', id: 'user', path: '/user' },
+      {
+        title: '审批',
+        children: [
+          { title: '流程列表', id: 'flow', path: '/flow' }
+        ]
+      }
+    ]
+  }
+];
+```
+
+## 使用建议
+
+- 通过 `menu-item.active` 字段可默认展开某个有子级的菜单
+- 所有菜单项建议带上唯一 `id`，方便与二级高亮、埋点等逻辑关联
+- 移动端建议搭配 `temporary=true`，以便点击遮罩快速收起抽屉

package/src/components/JhMenu/JhMenu.stories.js

@@ -0,0 +1,384 @@
+import JhMenu from './JhMenu.vue';
+
+// 示例菜单数据
+const sampleMenuList = [
+  {
+    id: 'dashboard',
+    title: '首页',
+    path: '/dashboard',
+  },
+  {
+    id: 'users',
+    title: '用户管理',
+    children: [
+      { id: 'user-list', title: '用户列表', path: '/users/list' },
+      { id: 'user-roles', title: '角色管理', path: '/users/roles' },
+      { id: 'user-permissions', title: '权限管理', path: '/users/permissions' },
+    ],
+  },
+  {
+    id: 'content',
+    title: '内容管理',
+    children: [
+      { id: 'articles', title: '文章管理', path: '/content/articles' },
+      { id: 'categories', title: '分类管理', path: '/content/categories' },
+      { id: 'tags', title: '标签管理', path: '/content/tags' },
+    ],
+  },
+  {
+    id: 'settings',
+    title: '系统设置',
+    path: '/settings',
+  },
+  {
+    id: 'help',
+    title: '帮助文档',
+    path: '/help',
+  },
+];
+
+const sampleRightMenuList = [
+  {
+    id: 'notifications',
+    title: '消息',
+    icon: 'mdi-bell-outline',
+    path: '/notifications',
+  },
+  {
+    id: 'docs',
+    title: '文档',
+    icon: 'mdi-book-open-outline',
+    path: '/docs',
+  },
+];
+
+const sampleAvatarMenuList = [
+  {
+    id: 'profile',
+    title: '个人资料',
+    path: '/profile',
+  },
+  {
+    id: 'account',
+    title: '账号设置',
+    path: '/account',
+  },
+];
+
+const sampleUserInfo = {
+  username: '张三',
+  userId: 'zhangsan',
+  roles: ['管理员', '编辑者'],
+};
+
+export default {
+  title: '基础组件/JhMenu - 导航菜单',
+  component: JhMenu,
+  tags: ['autodocs'],
+  argTypes: {
+    appTitle: {
+      control: 'text',
+      description: '应用标题',
+    },
+    showAvatar: {
+      control: 'boolean',
+      description: '是否显示用户头像和菜单',
+    },
+    temporary: {
+      control: 'boolean',
+      description: '移动端抽屉是否临时显示（点击外部关闭）',
+    },
+    hideDrawers: {
+      control: 'boolean',
+      description: '隐藏抽屉（用于Storybook预览时避免抽屉遮挡）',
+    },
+    activeMenuIndex: {
+      control: { type: 'number', min: -1, max: 10 },
+      description: '当前激活的菜单索引',
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component: `
+
+一个功能完整的导航菜单组件，支持：
+- 响应式设计（PC端和移动端不同布局）
+- 一级和二级菜单
+- 用户信息和头像菜单
+- 右侧工具菜单
+- 移动端抽屉菜单
+
+## 菜单数据结构
+
+\`\`\`javascript
+// 一级菜单
+{
+  id: 'menu-id',
+  title: '菜单标题',
+  path: '/menu/path',
+}
+
+// 二级菜单
+{
+  id: 'parent-menu',
+  title: '父菜单',
+  children: [
+    { id: 'child-1', title: '子菜单1', path: '/path1' },
+    { id: 'child-2', title: '子菜单2', path: '/path2' },
+  ]
+}
+\`\`\`
+
+## 事件
+
+- \`menu-click\`: 点击菜单时触发，参数为 (menuItem, menuIndex)
+- \`logout\`: 点击登出时触发
+        `,
+      },
+    },
+  },
+};
+
+// 基础示例
+export const 基础示例 = {
+  args: {
+    appTitle: 'JianghuJS Admin',
+    menuList: sampleMenuList,
+    rightMenuList: sampleRightMenuList,
+    avatarMenuList: sampleAvatarMenuList,
+    userInfo: sampleUserInfo,
+    showAvatar: true,
+    temporary: true,
+    hideDrawers: false,
+    activeMenuIndex: 0,
+    activeSecondMenuId: null,
+  },
+  render: (args) => ({
+    components: { JhMenu },
+    data() {
+      return { args };
+    },
+    template: `
+      <div>
+        <jh-menu
+          v-bind="args"
+          @menu-click="handleMenuClick"
+          @logout="handleLogout"
+        >
+          <template v-slot:title>{{ args.appTitle }}</template>
+        </jh-menu>
+        <v-main class="mt-15">
+          <v-container>
+            <h3>菜单组件演示</h3>
+            <p>点击菜单项查看效果</p>
+            <v-alert type="info" dense text>
+              <strong>提示：</strong>在小屏幕下，菜单会自动切换为移动端抽屉模式
+            </v-alert>
+          </v-container>
+        </v-main>
+      </div>
+    `,
+    methods: {
+      handleMenuClick(menu, index) {
+        console.log('Menu clicked:', menu, index);
+        if (index !== undefined) {
+          this.args.activeMenuIndex = index;
+        }
+        if (menu.id) {
+          this.args.activeSecondMenuId = menu.id;
+        }
+      },
+      handleLogout() {
+        console.log('Logout clicked');
+        alert('登出功能被触发');
+      },
+    },
+  }),
+};
+
+// 活动菜单
+export const 活动菜单 = {
+  args: {
+    ...基础示例.args,
+    activeMenuIndex: 1,
+    activeSecondMenuId: 'user-list',
+  },
+  render: 基础示例.render,
+};
+
+// 无用户头像
+export const 无用户头像 = {
+  args: {
+    ...基础示例.args,
+    showAvatar: false,
+  },
+  render: 基础示例.render,
+};
+
+// 最小化菜单
+export const 最小化菜单 = {
+  args: {
+    appTitle: 'Simple App',
+    menuList: [
+      { id: 'home', title: '首页', path: '/' },
+      { id: 'about', title: '关于', path: '/about' },
+      { id: 'contact', title: '联系', path: '/contact' },
+    ],
+    rightMenuList: [],
+    avatarMenuList: [],
+    userInfo: sampleUserInfo,
+    showAvatar: false,
+    hideDrawers: false,
+  },
+  render: 基础示例.render,
+};
+
+// 一级菜单
+export const 一级菜单 = {
+  args: {
+    ...基础示例.args,
+    menuList: [
+      { id: 'dashboard', title: '仪表盘', path: '/dashboard' },
+      { id: 'analytics', title: '数据分析', path: '/analytics' },
+      { id: 'reports', title: '报表', path: '/reports' },
+      { id: 'settings', title: '设置', path: '/settings' },
+    ],
+  },
+  render: 基础示例.render,
+};
+
+// 二级菜单
+export const 二级菜单 = {
+  args: {
+    ...基础示例.args,
+    menuList: [
+      {
+        id: 'system',
+        title: '系统管理',
+        children: [
+          { id: 'users', title: '用户管理', path: '/system/users' },
+          { id: 'roles', title: '角色管理', path: '/system/roles' },
+          { id: 'logs', title: '日志管理', path: '/system/logs' },
+        ],
+      },
+      {
+        id: 'content',
+        title: '内容管理',
+        children: [
+          { id: 'posts', title: '文章', path: '/content/posts' },
+          { id: 'pages', title: '页面', path: '/content/pages' },
+          { id: 'media', title: '媒体', path: '/content/media' },
+        ],
+      },
+    ],
+  },
+  render: 基础示例.render,
+};
+
+// 自定义标题
+export const 自定义标题 = {
+  args: {
+    ...基础示例.args,
+  },
+  render: (args) => ({
+    components: { JhMenu },
+    data() {
+      return { args };
+    },
+    template: `
+      <div>
+        <jh-menu
+          v-bind="args"
+          @menu-click="handleMenuClick"
+          @logout="handleLogout"
+        >
+          <template v-slot:title>
+            <v-icon color="success" class="mr-2">mdi-account-group</v-icon>
+            <span class="success--text">{{ args.appTitle }}</span>
+          </template>
+          <template v-slot:subtitle>
+            欢迎使用
+          </template>
+        </jh-menu>
+        <v-main class="mt-15">
+          <v-container>
+            <h3>自定义标题插槽演示</h3>
+            <p>标题区域可以通过插槽自定义内容</p>
+          </v-container>
+        </v-main>
+      </div>
+    `,
+    methods: {
+      handleMenuClick(menu, index) {
+        console.log('Menu clicked:', menu, index);
+      },
+      handleLogout() {
+        console.log('Logout clicked');
+        alert('登出功能被触发');
+      },
+    },
+  }),
+};
+
+// 长菜单列表
+export const 长菜单列表 = {
+  args: {
+    ...基础示例.args,
+    menuList: [
+      { id: 'menu1', title: '菜单1', path: '/menu1' },
+      { id: 'menu2', title: '菜单2', path: '/menu2' },
+      { id: 'menu3', title: '菜单3', path: '/menu3' },
+      { id: 'menu4', title: '菜单4', path: '/menu4' },
+      { id: 'menu5', title: '菜单5', path: '/menu5' },
+      { id: 'menu6', title: '菜单6', path: '/menu6' },
+      { id: 'menu7', title: '菜单7', path: '/menu7' },
+      { id: 'menu8', title: '菜单8', path: '/menu8' },
+      {
+        id: 'menu9',
+        title: '菜单9',
+        children: [
+          { id: 'submenu1', title: '子菜单1', path: '/menu9/sub1' },
+          { id: 'submenu2', title: '子菜单2', path: '/menu9/sub2' },
+        ],
+      },
+      { id: 'menu10', title: '菜单10', path: '/menu10' },
+    ],
+  },
+  render: 基础示例.render,
+};
+
+// 三级菜单
+export const 三级菜单 = {
+  args: {
+    ...基础示例.args,
+    menuList: [
+      {
+        id: 'system',
+        title: '系统管理',
+        children: [
+          {
+            id: 'users',
+            title: '用户管理',
+            children: [
+              { id: 'user-list', title: '用户列表', path: '/system/users/list' },
+              { id: 'user-add', title: '新增用户', path: '/system/users/add' },
+            ],
+          },
+          { id: 'roles', title: '角色管理', path: '/system/roles' },
+        ],
+      },
+      {
+        id: 'content',
+        title: '内容管理',
+        children: [
+          { id: 'posts', title: '文章', path: '/content/posts' },
+          { id: 'pages', title: '页面', path: '/content/pages' },
+        ],
+      },
+    ],
+    activeMenuIndex: 0,
+    activeSecondMenuId: 'user-list',
+  },
+  render: 基础示例.render,
+};