Skip to content

KvDrawer ​

通用右侧抽屉,用于详情展示及自定义操作。默认 mode="drawer",宽度为 720px;mode="page" 时宽度为视口宽度减去当前菜单占用宽度,再减去 10px。两种模式均上下贴边,左侧 16px 圆角。标题栏只显示标题和关闭按钮,背景色跟随主题。

使用 ​

vue
<KvDrawer v-model="visible" title="资源详情">
  <ResourceDetails />
</KvDrawer>

默认的 drawer 模式适合简单详情或较少字段的操作,宽度为 720px。复杂工作台可显式设置 mode="page" 占满菜单旁的内容区;传入 size 可覆盖两种模式的默认宽度。宽度始终受菜单旁的可用空间限制,视口 ≤640px 时两种模式均全宽。

默认启用 Element Plus 内置调宽,可拖动左边缘调整宽度,最小宽度为 500px;设置 :resizable="false" 可关闭。宽度不超过菜单旁的可用空间,可用空间不足 500px 时以可用空间为准,小屏全宽时隐藏拖动手柄。

关闭动画结束后重置拖拽宽度,下次打开恢复默认 720px;传入 size 时恢复该宽度,page 模式恢复菜单旁的可用宽度。

vue
<KvDrawer v-model="visible" title="资源详情" mode="page">
  <ResourceDetails />
</KvDrawer>

仅提供 footer 插槽时才渲染底栏。标题栏为 44px 起,内边距 7px 20px(视口 ≤640px 时为 7px 16px),标题 14px。底部按钮栏内边距统一为 12px 20px,小屏保持一致,按钮 36px 高、字号 14px。内容超出时仅正文滚动。

vue
<KvDrawer v-model="visible" title="资源操作">
  <ResourceDetails />
  <template #footer="{ close }">
    <ElButton @click="close">取消</ElButton>
    <ElButton type="primary" @click="submit">提交</ElButton>
  </template>
</KvDrawer>

完整演示:

vue
<template>
  <div class="drawer-demo-controls">
    <ElButton type="primary" @click="open(false)">查看详情</ElButton>
    <ElButton @click="open(true)">带操作区</ElButton>
    <ElRadioGroup v-model="mode" aria-label="抽屉模式">
      <ElRadioButton value="page">page 模式</ElRadioButton>
      <ElRadioButton value="drawer">drawer 模式(500px)</ElRadioButton>
    </ElRadioGroup>
    <label
      >菜单宽度 <ElInputNumber v-model="sidebarWidth" :min="0" :max="320" :step="10" /> px</label
    >
  </div>
  <KvDrawer v-model="visible" :mode="mode" :title="withFooter ? '资源操作' : '资源详情'">
    <ElCard shadow="never">
      <KvSectionTitle title="基本信息" size="small" />
      <dl class="drawer-demo-fields">
        <div><dt>资源名称</dt><dd>事件中心</dd></div>
        <div><dt>资源编码</dt><dd>event-center</dd></div>
        <div><dt>负责人</dt><dd>平台团队</dd></div>
        <div
          ><dt>状态</dt><dd><ElTag type="success">运行中</ElTag></dd></div
        >
      </dl>
    </ElCard>
    <template v-if="withFooter" #footer="{ close }">
      <ElButton @click="close">取消</ElButton>
      <ElButton type="primary" @click="submit(close)">提交</ElButton>
    </template>
  </KvDrawer>
</template>

<script setup lang="ts">
  import { ref } from 'vue'
  import {
    ElButton,
    ElCard,
    ElInputNumber,
    ElMessage,
    ElRadioButton,
    ElRadioGroup,
    ElTag
  } from 'element-plus'
  import { KvDrawer, KvSectionTitle } from '@kevairy/components'
  import { provideKvDrawerLayout } from '@kevairy/components/core'

  const visible = ref(false)
  const mode = ref<'page' | 'drawer'>('drawer')
  const withFooter = ref(false)
  const sidebarWidth = ref(230)
  provideKvDrawerLayout(sidebarWidth)

  const open = (footer: boolean) => {
    withFooter.value = footer
    visible.value = true
  }
  const submit = (close: () => void) => {
    ElMessage.success('操作效果演示,未写入实际数据')
    close()
  }
</script>

<style scoped>
  .drawer-demo-controls {
    display: flex;
    flex-wrap: wrap;
    gap: 12px;
    align-items: center;
  }

  .drawer-demo-controls > .el-button {
    margin: 0;
  }

  .drawer-demo-controls label {
    display: flex;
    gap: 8px;
    align-items: center;
  }

  .drawer-demo-fields {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr));
    gap: 24px;
    margin: 24px 0 0;
  }

  .drawer-demo-fields dt {
    margin-bottom: 8px;
    color: var(--el-text-color-secondary);
  }

  .drawer-demo-fields dd {
    margin: 0;
    overflow-wrap: anywhere;
  }
</style>

菜单宽度接入 ​

模板布局已通过 ResizeObserver 提供侧栏的实际占用宽度,支持收起、展开、调整宽度、双栏和顶部菜单;页面通常无需传 sidebarWidth。宽度变化时已打开的抽屉也会更新。

独立项目在布局 setup 中提供响应式宽度,所有后代抽屉共用;Teleport 到 body 不影响该上下文。宽度包含菜单边框,数字单位为 px。组件不读取应用 Store 或查询应用 DOM。

ts
import { ref } from 'vue'
import { provideKvDrawerLayout } from '@kevairy/components/core'

const sidebarWidth = ref(230)
provideKvDrawerLayout(sidebarWidth)
// 菜单收起后更新为实际占用宽度,例如 sidebarWidth.value = 64。

单个抽屉可用 :sidebar-width="230" 覆盖。无布局上下文时菜单宽度为 0。视口 ≤640px 时全宽且取消圆角,避免内容区过窄;模板移动端覆盖式导航不占用抽屉宽度。

Props ​

属性类型默认值说明
modelValue / v-modelboolean必填是否打开
titlestring必填可见标题及无障碍名称
mode'page' | 'drawer''drawer'drawer 默认 720px;page 占满菜单旁的内容区
sizenumber | string—可选显式宽度,优先于 mode 的默认宽度,数字按 px;不超过菜单旁的可用宽度;小屏仍全宽
resizablebooleantrue启用 Element Plus 内置的左边缘拖拽调宽,最小 500px,不超过可用宽度
sidebarWidthnumber | string布局提供,未提供时 0菜单实际占用宽度,支持 CSS 长度
gapnumber10抽屉与菜单之间的间距,px
headerBackgroundstring主题浅色背景标题栏背景色,也可用 --kv-drawer-header-bg 覆盖
closeOnClickModalbooleantrue点击抽屉外部关闭
closeOnPressEscapebooleantrueEsc 关闭
showClosebooleantrue显示右上角关闭按钮
destroyOnClosebooleantrue关闭动画结束后销毁正文
beforeCloseDrawerProps['beforeClose']—关闭前拦截,接受 done 回调;调用后才关闭

从 @kevairy/components 或 @kevairy/components/core 导出 KvDrawerProps。容器补充属性如 class、aria-label 可透传;右侧打开、挂载到 body、标题栏和自适应宽度为固定行为,不提供 Element Plus 全量 Props 契约。

Slots、Events 和实例方法 ​

  • default:正文,参数 { close: () => void }。
  • footer:可选操作区,参数 { close: () => void };未提供时不预留空白底栏。
  • update:modelValue(boolean):受控打开状态更新。
  • open / opened / close / closed:生命周期事件。
  • openAutoFocus / closeAutoFocus:焦点进入和恢复事件。
  • requestClose():实例关闭方法。与插槽 close()、关闭按钮、遮罩、Esc 一样经过 beforeClose。父组件直接设置 v-model = false 不经过该拦截。

保留 Element Plus 的焦点管理、遮罩滚动锁定及生命周期;支持系统“减少动态效果”。只需在应用入口导入一次 @kevairy/components/style.css。

KvDrawer 不内置提交、取消、未保存确认或业务状态。KvFormDrawer 复用本组件的布局与样式,并在此基础上提供标准表单操作和修改保护。