showtime-components

一个面向移动端交互体验的 Vue 3 组件包，当前提供：

• ShowtimeBottomSheet
• ShowtimeActionBar

安装

pnpm add showtime-components

如果你在本地 workspace 中使用，也可以直接通过 workspace 依赖接入。

基础使用

<script setup lang="ts">
import { ref } from 'vue'
import {
  ShowtimeActionBar,
  ShowtimeBottomSheet,
  type ShowtimeBottomSheetDragPayload,
  type ShowtimeSheetSnap
} from 'showtime-components'

const snap = ref<ShowtimeSheetSnap>('peek')
const followed = ref(false)

function handleDrag(payload: ShowtimeBottomSheetDragPayload) {
  console.log('sheet y:', payload.y)
}
</script>

<template>
  <ShowtimeBottomSheet
    v-model:snap="snap"
    @drag="handleDrag"
  >
    <template #header>
      <ShowtimeActionBar v-model:follow-active="followed" />
    </template>

    <div>这里是内容区域</div>
  </ShowtimeBottomSheet>
</template>

样式引入

如果你的构建流程需要显式引入样式，可以加上：

import 'showtime-components/style.css'

ShowtimeBottomSheet

一个支持可配置吸附点列表的移动端底部弹层组件，默认仍提供 peek / half / full 三档体验。

完整 Props（ShowtimeBottomSheetProps）

| 参数 | 说明 | 默认值 | | --- | --- | --- | | snap | 当前吸附点 | peek | | snapPoints | 推荐传数组 [{ key, position }]，兼容 { peek, half, full } 对象写法 | 默认三档数组 | | minDragDistance | 触发切换的最小拖动距离 | 46 | | snapSettleTolerance | 松手位置接近 snap 时直接吸附的容差 | 10 | | contentClass | 追加到面板根节点上的类名 | '' | | headerClass | 追加到 header 插槽容器上的类名 | '' | | bodyClass | 追加到默认内容容器上的类名 | '' | | entranceAnimation | 是否启用首次入场动画 | true | | entranceOffset | 首次入场上浮偏移量，单位 px | 14 | | entranceDuration | 首次入场动画时长，单位 ms | 260 | | snapAnimation | 是否启用 snap 切换动画 | true | | snapAnimationStiffness | snap 弹簧动画刚度，值越大越利落 | 420 | | snapAnimationDamping | snap 弹簧动画阻尼，值越大越稳 | 32 | | snapAnimationMass | snap 弹簧动画质量，值越大越有惯性 | 0.9 | | headerDragOnly | 是否只允许顶部区域触发拖拽；开启时会关闭内容区边界联动 | true | | handleVisible | 是否显示默认拖拽把手 | true | | handleWidth | 默认拖拽把手宽度，单位 px | 62 | | handleHeight | 默认拖拽把手高度，单位 px | 8 | | panelBackground | 面板背景色 | #ffffff | | panelRadius | 面板顶部圆角半径，单位 px | 34 | | contentEdgeSnap | 是否允许内容区边界继续推动 sheet 连续移动（仅在 headerDragOnly=false 时生效） | true | | contentEdgeSnapThreshold | 内容区边界联动触发阈值，单位 px | 26 |

事件

| 事件 | 说明 | | --- | --- | | update:snap | v-model:snap 更新 | | snap-change | 吸附点变化时触发 | | drag | 顶部拖拽过程中持续触发，返回 { y, movementY, isDragging } | | content-touchstart | 内容区 touchstart 原生事件透传 | | content-touchmove | 内容区 touchmove 原生事件透传 | | content-touchend | 内容区 touchend 原生事件透传 | | content-touchcancel | 内容区 touchcancel 原生事件透传 | | content-wheel | 内容区 wheel 原生事件透传 |

特点

• 推荐 API：snapPoints 使用 { key, position }[]
• 兼容 API：旧版 { peek, half, full } 对象仍然可用
• 直接拖拽和内容区边界联动都会在松手后吸附到最近的 snap point
• 当 headerDragOnly 开启时，内容区只保留原生滚动和事件透传，不再触发边界联动
• 内容区滚动和顶部拖拽分离
• 内容区边界可继续推动 sheet 本身移动
• 可通过 drag 事件实时获取当前面板的 y 轴坐标
• 可监听内容区原生 touch / wheel 事件做埋点或联动

ShowtimeActionBar

一个适合内容详情页、弹层顶部、互动区的操作栏组件。

常用参数

| 参数 | 说明 | 默认值 | | --- | --- | --- | | items | 左侧互动按钮列表 | 默认内置三项 | | followLabel | 未关注文案 | 关注 | | followedLabel | 已关注文案 | 已关注 | | followActive | 初始关注状态 | false | | animated | 是否启用点击反馈动画 | true |

事件

| 事件 | 说明 | | --- | --- | | action | 任一按钮点击时触发，返回按钮 key | | update:followActive | 关注状态更新 | | follow-change | 关注状态变化时触发 |

类型导出

包内也导出了常用类型：

import type {
  ShowtimeActionBarProps,
  ShowtimeActionItem,
  ShowtimeBottomSheetDragPayload,
  ShowtimeBottomSheetProps,
  ShowtimeSheetSnap
} from 'showtime-components'

License

MIT