BottomSheet 底部弹窗

介绍

底部弹起的模态面板，可通过顶部把手拖拽调整高度，适用于展示列表、表单等自定义内容。

导入

import BottomSheet from '@/components/dialog/BottomSheet.vue'

用法

基础用法

最简单的 BottomSheet 用法，设置 show 控制显示，通过 #content 插槽传入内容，插槽会注入 close 方法用于关闭面板。

<template>
  <BottomSheet
    :show="show1"
    :height="320"
    closeable
    @close="show1 = false"
  >
    <template #content="{ close }">
      <FlexCol :padding="24">
        <view style="font-size: 36rpx; font-weight: 600; margin-bottom: 24rpx;">基础用法</view>
        <view style="color: #666; margin-bottom: 32rpx;">底部弹起的模态面板，可通过顶部把手拖拽调整高度。</view>
        <view style="padding: 24rpx; background: #f5f5f5; border-radius: 12rpx; margin-bottom: 32rpx;">
          内容区域可放置列表、表单等任意内容。
        </view>
        <Button text="关闭" type="primary" size="large" @click="close" />
      </FlexCol>
    </template>
  </BottomSheet>
</template>

禁用拖拽

设置 enable-drag 为 false 可隐藏顶部把手并禁用拖拽。

<template>
  <BottomSheet
    :show="show2"
    :height="280"
    :enable-drag="false"
    closeable
    @close="show2 = false"
  >
    <template #content="{ close }">
      <FlexCol :padding="24">
        <view style="font-size: 36rpx; font-weight: 600; margin-bottom: 24rpx;">禁用拖拽</view>
        <view style="color: #666; margin-bottom: 32rpx;">设置 enableDrag 为 false 可隐藏顶部把手并禁用拖拽。</view>
        <Button text="关闭" type="primary" size="large" @click="close" />
      </FlexCol>
    </template>
  </BottomSheet>
</template>

吸附高度

通过 drag-snap-heights 设置松手后吸附的高度档位（单位 px），拖拽结束时会自动吸附到最近的一档。

<template>
  <BottomSheet
    :show="show3"
    :height="300"
    :drag-snap-heights="[200, 400, 600]"
    closeable
    @close="show3 = false"
  >
    <template #content="{ close }">
      <FlexCol :padding="24">
        <view style="font-size: 36rpx; font-weight: 600; margin-bottom: 24rpx;">吸附高度</view>
        <view style="color: #666; margin-bottom: 32rpx;">通过 dragSnapHeights 设置松手后吸附的高度档位（如 200、400、600px）。</view>
        <Button text="关闭" type="primary" size="large" @click="close" />
      </FlexCol>
    </template>
  </BottomSheet>
</template>

自定义面板

使用 #content 插槽可完全自定义面板内容，例如配合 Cell、CellGroup 等组件。

<template>
  <BottomSheet
    :show="show4"
    :height="450"
    closeable
    @close="show4 = false"
  >
    <template #content="{ close }">
      <FlexCol :padding="24">
        <view style="font-size: 36rpx; font-weight: 600; margin-bottom: 24rpx;">自定义面板</view>
        <view style="color: #666; margin-bottom: 24rpx;">可使用默认插槽 #content 完全自定义内容布局。</view>
        <CellGroup round>
          <Cell title="选项 A" showArrow touchable />
          <Cell title="选项 B" showArrow touchable />
          <Cell title="选项 C" showArrow touchable />
        </CellGroup>
        <Button text="关闭" type="primary" size="large" @click="close" />
      </FlexCol>
    </template>
  </BottomSheet>
</template>

API 参考

BottomSheet

底部弹窗组件，基于 Popup 实现，固定从底部弹出并支持拖拽调节高度。

Props

名称	说明	类型	必填	默认值
show	是否显示	boolean	是	false
height	初始高度（px）	number	-	300
enableDrag	是否启用拖拽（显示顶部把手）	boolean	-	true
dragSnapHeights	拖拽松手后吸附的高度档位（px 数组）	number[]	-	-
dragMinHeight	拖拽时最小高度（px）	number	-	100
dragMaxHeight	拖拽时最大高度（px）	number	-	1000
dragHandleColor	顶部把手颜色	string	-	'grey'
dragHandleSize	顶部把手尺寸（rpx/px）	number	-	200
innerStyle	面板内容区域自定义样式	ViewStyle	-	-
closeable	是否显示关闭按钮且点击遮罩可关闭	boolean	-	-
closeIcon	关闭图标，设为 false 不显示	string | false	-	'close'
closeIconSize	关闭图标大小	number	-	40
closeIconPosition	关闭按钮位置	PopupCloseButtonPosition	-	'right'
mask	是否显示遮罩	boolean	-	true
maskColor	遮罩颜色	string	-	'background.mask'
duration	动画时长（ms）	number	-	230
zIndex	层级	number	-	0
backgroundColor	弹出层背景色	string	-	'white'
safeArea	是否考虑安全区	boolean	-	true
margin	对话框偏移边距	number[]	-	[0,0,0,0]
inset	整体边距（含遮罩）	(number | string | undefined)[]	-	-

说明：除上表外，BottomSheet 继承 Popup 的其余属性（如 round 已固定为 true，position 固定为 bottom，size 由内部高度控制）。

Slots

名称	说明
content	自定义面板内容，作用域参数：{ close }，close 用于关闭面板

Events

名称	说明	参数
close	关闭时触发	$event

方法（通过 ref 调用）

方法名	说明	参数 / 返回值
setDragHeight	设置当前拖拽高度	(height: number) => void
getDragHeight	获取当前拖拽高度	() => number
setDragHeightToMax	将高度设为最大	() => void
setDragHeightToMin	将高度设为最小	() => void

主题变量

名称	类型	默认值	说明
BottomSheetHeight	number	300	默认高度（px）
BottomSheetDragHandleColor	string	'grey'	拖拽把手颜色
BottomSheetDragHandleSize	number	200	拖拽把手尺寸
BottomSheetDragMaxHeight	number	1000	拖拽最大高度（px）
BottomSheetDragMinHeight	number	100	拖拽最小高度（px）
BottomSheetCenterWidth	string	'600rpx'	居中宽度（由 Popup 继承）
BottomSheetBorderRadius	number/string	10	面板圆角
BottomSheetBackgroundColor	string	'white'	面板背景色
BottomSheetDragHandleBorderRadius	number/string	10	把手圆角
BottomSheetDragHandleMarginVertical	number/string	25	把手上下边距