@beta-lib/energy-progress

@beta-lib/energy-progress

一个基于 TypeScript 开发的能量进度条库，用于可视化时间线数据和历史观看记录。它通过 SVG 技术实现了一个具有贝塞尔曲线效果的进度条，支持交互和动画效果。

功能特性

• 时间线数据可视化：根据输入的时间线数据自动生成分段信息，通过贝塞尔曲线的高低来表示不同时间段的数据密集程度
• 历史观看记录管理：自动合并重叠的历史观看段落，通过不同颜色显示已观看和未观看的部分
• 交互功能：支持点击进度条任意位置进行跳转，点击跳转后触发回调
• 自定义配置：可自定义颜色、透明度、分段数量等参数
• 响应式设计：自动适应容器尺寸变化

安装

使用 npm

npm install @beta-lib/energy-progress

使用 yarn

yarn add @beta-lib/energy-progress

使用 pnpm

pnpm add @beta-lib/energy-progress

基本使用

import EnergyPro from '@beta-lib/energy-progress';

// 创建进度条实例
const progress = new EnergyPro({
  timeLine: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100],
  endTime: 100,
  activeColor: '#00a1d6',
  normalCorlor: 'white',
  opacity: 0.2,
  segCount: 20,
  canClickJump: true,
  onClickCall: (percent) => {
    console.log('Jump to:', percent);
  },
  onFinish: (history) => {
    console.log('Completed! History:', history);
  }
});

// 挂载到 DOM 元素
progress.mount('#progress-container');

// 控制进度
progress.timeRun(50); // 运行到 50%
progress.timeJump(80); // 跳转到 80%

API 文档

构造函数

new EnergyPro(options: ProgressOptionsParams, segment?: Array<number> | null)

参数

• options：配置选项，包含以下属性：

  • activeColor：已激活部分（历史观看段落）的颜色，默认值为 '#00a1d6'
  • normalCorlor：未激活部分的颜色，默认值为 'white'
  • opacity：整个进度条的透明度，默认值为 0.2
  • scaleFactor：缩放因子，值越大高低差越不明显，默认值为 1
  • timeLine：时间线数据，用于记录时间轴中数据分布密集度，可以是数字数组或对象数组
  • timeKey：时间轴数组中对象的时间关键字，若 timeLine 为对象数组时必传
  • segCount：需要平均分割成几段，默认值为 20
  • endTime：结束时间，用于计算时间分片
  • startPoint：开始点位，用于设置初始时间线，默认值为 0
  • useDefaultSize：是否启用默认边界值，用于限制当数量过少或过多时时间片绘制的范围，默认值为 false
  • defaultMaxHeight：最大高度，用于设置最大值的高度，默认值为 200
  • defaultMinHeight：最小高度，用于设置最小值的高度，默认值为 10
  • history：历史观看段落，默认值为 []
  • canClickJump：是否可以点击跳转，默认值为 true
  • onClickCall：点击跳转后的回调函数，默认值为 () => {}
  • onFinish：到达结束点的回调函数，默认值为 () => {}

• segment：分段信息，点位数等于分段数+1，默认值为 null

方法

mount(entry: string | HTMLElement)

挂载进度条到指定元素。

• entry：挂载的元素，可以是选择器字符串或 HTMLElement 对象

reload(options: ProgressOptionsParams, segment?: Array | null)

重新加载进度条配置。

• options：新的配置选项
• segment：新的分段信息

timeJump(percent: number)

设置进度线位置，用于点击跳转。

• percent：进度百分比，范围为 0-100

timeRun(percent: number)

设置进度线行进，用于播放时的自动推进，并记录历史段落信息。

• percent：进度百分比，范围为 0-100

getCurrentHistoryRange()

返回当前历史段落，已合并重叠范围。

• 返回值：历史段落数组，每个元素包含 s（开始位置）和 e（结束位置）属性

类型定义

Point

坐标点接口。

interface Point {
  x: number; // 坐标x
  y: number; // 坐标y
}

TimeDataItem

时间数据项接口。

interface TimeDataItem {
  [key: string]: number;
}

HistoryObj

历史观看段落接口。

interface HistoryObj {
  s: number; // 开始位置
  e: number; // 结束位置
}

ProgressOptions

进度条配置选项接口。

interface ProgressOptions {
  activeColor: string; // 已激活，历史观看段落的颜色
  normalCorlor: string; // 未观看颜色
  opacity: number; // 整个进度条透明度
  scaleFactor: number; // 缩放因子，这个值越大高低差越不明显，为1时高低差最明显
  timeLine: Array<TimeDataItem> | Array<number>; // 时间线，用于记录时间轴中数据分步密集度
  timeKey: string; // 时间轴数组中对象的时间关键字，若Array<T> T为对象时，必传
  segCount: number; // 需要平均分割成几段
  endTime: number; // 结束时间
  startPoint: number; // 开始点位
  history: Array<HistoryObj>; // 历史观看段落
  canClickJump: boolean; // 是否可以点击跳转
  onClickCall: (p: number) => void; // 点击svg后的触发函数
  onFinish: (arr: Array<HistoryObj>) => void; // 到达结束点的触发函数
}

ProgressOptionsParams

进度条配置选项参数接口（所有属性可选）。

interface ProgressOptionsParams {
  activeColor?: string; // 已激活，历史观看段落的颜色
  normalCorlor?: string; // 未观看颜色
  opacity?: number; // 整个进度条透明度
  scaleFactor?: number; // 缩放因子，这个值越大高低差越不明显，为1时高低差最明显
  timeLine: Array<TimeDataItem> | Array<number>; // 时间线，用于记录时间轴中数据分步密集度
  timeKey?: string; // 时间轴数组中对象的时间关键字，若Array<T> T为对象时，必传
  segCount?: number; // 需要平均分割成几段
  endTime: number; // 结束时间
  startPoint?: number; // 开始点位
  history?: Array<HistoryObj>; // 历史观看段落
  canClickJump?: boolean; // 是否可以点击跳转
  onClickCall?: (p: number) => void; // 点击svg后的触发函数
  onFinish?: (arr: Array<HistoryObj>) => void; // 到达结束点的触发函数
}

示例

基本示例

import EnergyPro from '@beta-lib/energy-progress';

// 创建进度条实例
const progress = new EnergyPro({
  timeLine: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100],
  endTime: 100
});

// 挂载到 DOM 元素
progress.mount('#progress-container');

带历史记录的示例

import EnergyPro from '@beta-lib/energy-progress';

// 创建进度条实例
const progress = new EnergyPro({
  timeLine: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100],
  endTime: 100,
  history: [
    { s: 0, e: 25 },
    { s: 50, e: 75 }
  ]
});

// 挂载到 DOM 元素
progress.mount('#progress-container');

// 模拟播放
let currentProgress = 0;
const interval = setInterval(() => {
  currentProgress += 1;
  progress.timeRun(currentProgress);
  if (currentProgress >= 100) {
    clearInterval(interval);
  }
}, 100);

带点击回调的示例

import EnergyPro from '@beta-lib/energy-progress';

// 创建进度条实例
const progress = new EnergyPro({
  timeLine: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100],
  endTime: 100,
  canClickJump: true,
  onClickCall: (percent) => {
    console.log('User clicked at:', percent, '%');
    // 可以在这里添加跳转逻辑
  }
});

// 挂载到 DOM 元素
progress.mount('#progress-container');

使用已有的segment的示例

const ep = new EnergyPro({
    segCount: 10, // 需要平均分割成几段
    useDefaultSize: true, // 是否启用默认极限值
    defaultMaxHeight: 200, // 最大高度，用于设置最大值的高度(数量)
    defaultMinHeight: 10, // 最小高度，用于设置最小值的高度(数量)
}, [55, 54, 50, 58, 46, 10, 44, 50, 52, 45, 6]);

// 挂载到 DOM 元素
progress.mount('#progress-container');