vue3-time-playbar

一个 Vue 3 时间播放器组件，包含交互式时间轴、播放控制和刻度标记。零依赖。

安装

npm install vue3-time-playbar

基本用法

<template>
  <vue3TimePlaybar
    v-model="currentTime"
    :start-time="startTime"
    :end-time="endTime"
    @change="onTimeChange"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import vue3TimePlaybar from 'vue3-time-playbar'
import 'vue3-time-playbar/style.css'
import type { TimeChangePayload } from 'vue3-time-playbar'

const startTime = new Date('2025-01-01T00:00:00')
const endTime = new Date('2025-01-03T00:00:00')
const currentTime = ref<number>(startTime.getTime())

function onTimeChange(payload: TimeChangePayload) {
  console.log('Time:', payload.time, 'Index:', payload.index)
}
</script>

注意： 必须导入 CSS 文件，组件才能正确渲染。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | modelValue | number \| string \| Date | — | 当前时间（v-model） | | startTime | number \| string \| Date | 必填 | 时间轴起始时间 | | endTime | number \| string \| Date | 必填 | 时间轴结束时间 | | interval | number | 1 | 刻度间隔（小时） | | playInterval | number | 1000 | 基准播放间隔（毫秒），即 1x 倍速时每步的时间间隔 | | speed | number | 1 | 默认播放倍率，值必须是 speedOptions 中的一项 | | speedOptions | number[] | [0.5, 1, 2, 3] | 可选的播放倍率列表，显示在速度选择器中 | | minTickSpacing | number | 自动 | 刻度之间的最小像素间距。未指定时根据 tickLabelMode 自动选择：'all' 模式为 15，'major' 模式为 5 | | tickLabelMode | 'all' \| 'major' | 'all' | 刻度标签显示模式。'all'：所有刻度均显示小时数字；'major'：仅在 02、08、14、20 时显示数字标签，其余刻度线仍全部保留 | | formatTooltip | (ts: number) => string | 内置 | 自定义 tooltip 格式化函数 |

事件

| 事件 | 载荷 | 说明 | |------|------|------| | update:modelValue | number | 时间变化时触发（v-model） | | change | { time: number, index: number } | 时间变化时触发，包含时间戳和刻度索引 |

交互特性

• 点击定位：点击时间轴任意位置，自动吸附到最近的刻度
• 轨道拖动：在时间轴轨道上按住拖动可连续调整时间
• Tooltip 拖动：鼠标悬浮至 Tooltip 时显示拖动图标（grab），按住拖动可直接带动播放位置
• 日期分界线：0 点刻度自动显示加长的分界线和日期标签，隐藏多余的 "00" 小时标签
• 滚轮滚动：当时间跨度较长产生溢出时，支持滚轮横向滚动浏览

插槽

| 插槽 | 参数 | 说明 | |------|------|------| | prev | — | 自定义"上一步"按钮内容 | | play | { isPlaying: boolean } | 自定义"播放/暂停"按钮内容 | | next | — | 自定义"下一步"按钮内容 |

类型导出

import type {
  TimeInput,
  TickLabelMode,
  FormatTooltipFn,
  TimeChangePayload,
  Tick,
} from 'vue3-time-playbar'

工具函数导出

包中还导出了一些实用的工具函数：

import {
  toTimestamp,
  getHour,
  getDayOfWeek,
  getWeekdayShort,
  formatHH,
  formatMD,
  formatHHmm,
  defaultTooltipFormat,
  getDateKey,
  formatDayLabel,
  addHours,
  diffHours,
  getNextMidnight,
  findNearestTickIndex,
  findTickIndex,
} from 'vue3-time-playbar'

许可证

MIT