YqCollapseSidebar

YqCollapseSidebar 是一个可折叠侧边栏控制组件，用于管理应用侧边栏的展开/折叠状态。该组件提供以下核心功能：

• 通过点击按钮切换侧边栏状态
• 支持自定义展开/折叠图标
• 支持状态持久化存储
• 提供丰富的交互反馈和动画效果
• 完全响应式设计，适配不同屏幕尺寸

1 使用示例

<template>
  <YqCollapseSidebar
    v-model="isCollapsed"
    class="sidebar-toggle"
    @toggle="handleToggle"
    collapsedIcon="fa-solid fa-angles-right"
    expandedIcon="fa-solid fa-angles-left"
  />

  <div class="demo-container">
    <!-- 侧边栏 -->
    <div
      class="demo-sidebar"
      :class="{ collapsed: isCollapsed }"
      :style="{ width: isCollapsed ? '60px' : '250px' }"
    >
      <div class="sidebar-content">
        <h3 v-show="!isCollapsed">菜单标题</h3>
        <ul>
          <li>
            <YqIcon icon="fa-solid fa-home" />
            <span v-show="!isCollapsed">首页</span>
          </li>
          <li>
            <YqIcon icon="fa-solid fa-user" />
            <span v-show="!isCollapsed">用户</span>
          </li>
          <li>
            <YqIcon icon="fa-solid fa-cog" />
            <span v-show="!isCollapsed">设置</span>
          </li>
        </ul>
      </div>
    </div>

    <!-- 主内容区 -->
    <div class="demo-main">
      <h1>主内容区</h1>
      <p>当前侧边栏状态: {{ isCollapsed ? "折叠" : "展开" }}</p>
      <p>尝试点击左侧的折叠按钮</p>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
const isCollapsed = ref(false);

const handleToggle = (collapsed: boolean) => {
  isCollapsed.value = collapsed;
};
</script>

<style scoped lang="scss">
.demo-container {
  display: flex;
  height: 400px;
  border: 1px solid #eee;
  position: relative;
}

.demo-sidebar {
  position: relative;
  background-color: #f8f8f8;
  border-right: 1px solid #ddd;
  transition: width 0.3s ease;
  overflow: hidden;

  &.collapsed {
    .sidebar-content h3,
    .sidebar-content ul li span {
      display: none;
    }
  }
}

.sidebar-content {
  padding: 20px;

  h3 {
    margin-bottom: 20px;
    color: var(--yq-color-primary);
    transition: opacity 0.3s ease;
  }

  ul {
    list-style: none;
    padding: 0;

    li {
      padding: 10px 0;
      display: flex;
      align-items: center;
      gap: 10px;
      color: #666;

      &:hover {
        color: var(--yq-color-primary);
        cursor: pointer;
      }
    }
  }
}

.demo-main {
  flex: 1;
  padding: 20px;
  background-color: white;
}

.sidebar-toggle {
  position: absolute;
  left: 0px;
  top: 50px;
  z-index: 101;
}
</style>

2 组件属性

属性名	类型	默认值	说明
modelValue	Boolean	false	使用 v-model 绑定的侧边栏状态
initialCollapsed	Boolean	false	初始折叠状态
expandedIcon	String	'fa-solid fa-angles-left'	展开状态下显示的图标
collapsedIcon	String	'fa-solid fa-angles-right'	折叠状态下显示的图标
sidebarWidth	Number	250	侧边栏展开时的宽度(px)
persistState	Boolean	false	是否持久化存储状态
storageKey	String	'yq-sidebar-state'	本地存储使用的键名

3 组件事件

事件名	参数	说明
update:modelValue	Boolean	状态变更时触发(用于 v-model)
toggle	Boolean	状态切换时触发

4 样式定制

4.1 通过 CSS 变量定制

:root {
  --yq-color-primary: #409eff; /* 主色调 */
  --yq-color-primary-light-3: #79bbff; /* 悬停色调 */
}

4.2 通过类名覆盖

.yq-collapse-sidebar {
  /* 覆盖默认样式 */
  background-color: #ff0000;
  width: 30px;
  height: 30px;
}

5 高级用法

5.1 状态持久化

启用状态持久化后，组件会将折叠状态保存到 localStorage 中：

<YqCollapseSidebar
  v-model="isCollapsed"
  :persistState="true"
  storageKey="custom-storage-key"
/>

5.2 自定义图标

使用 FontAwesome 或其他图标库自定义图标：

<YqCollapseSidebar
  v-model="isCollapsed"
  collapsedIcon="fa-solid fa-chevron-right"
  expandedIcon="fa-solid fa-chevron-left"
/>

5.3 插槽内容

通过默认插槽添加自定义文本：

<YqCollapseSidebar v-model="isCollapsed">
  {{ isCollapsed ? '展开' : '折叠' }}
</YqCollapseSidebar>

6 最佳实践

6.1 与侧边栏配合使用

<template>
  <YqCollapseSidebar v-model="isCollapsed" />

  <div class="app-layout">
    <div class="sidebar" :style="{ width: isCollapsed ? '60px' : '250px' }">
      <!-- 侧边栏内容 -->
    </div>

    <div
      class="main-content"
      :style="{ marginLeft: isCollapsed ? '60px' : '250px' }"
    >
      <!-- 主内容区 -->
    </div>
  </div>
</template>

<style>
.app-layout {
  transition: margin-left 0.3s ease;
}

.sidebar {
  transition: width 0.3s ease;
}
</style>

6.2 响应式设计

结合媒体查询实现响应式：

@media (max-width: 768px) {
  .yq-collapse-sidebar {
    display: none; /* 在小屏幕上隐藏折叠按钮 */
  }

  .sidebar {
    width: 100% !important;
  }

  .main-content {
    margin-left: 0 !important;
  }
}

6.3 重置持久化存储的状态

localStorage.removeItem("yq-sidebar-state"); // 或自定义的storageKey

6.4 控制按钮的位置

.yq-collapse-sidebar {
  top: 20px !important; /* 调整垂直位置 */
  left: auto !important;
  right: 10px !important; /* 调整水平位置 */
}