外观
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-model | boolean | 必填 | 是否打开 |
title | string | 必填 | 可见标题及无障碍名称 |
mode | 'page' | 'drawer' | 'drawer' | drawer 默认 720px;page 占满菜单旁的内容区 |
size | number | string | — | 可选显式宽度,优先于 mode 的默认宽度,数字按 px;不超过菜单旁的可用宽度;小屏仍全宽 |
resizable | boolean | true | 启用 Element Plus 内置的左边缘拖拽调宽,最小 500px,不超过可用宽度 |
sidebarWidth | number | string | 布局提供,未提供时 0 | 菜单实际占用宽度,支持 CSS 长度 |
gap | number | 10 | 抽屉与菜单之间的间距,px |
headerBackground | string | 主题浅色背景 | 标题栏背景色,也可用 --kv-drawer-header-bg 覆盖 |
closeOnClickModal | boolean | true | 点击抽屉外部关闭 |
closeOnPressEscape | boolean | true | Esc 关闭 |
showClose | boolean | true | 显示右上角关闭按钮 |
destroyOnClose | boolean | true | 关闭动画结束后销毁正文 |
beforeClose | DrawerProps['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 复用本组件的布局与样式,并在此基础上提供标准表单操作和修改保护。