# TimeBar

**Repository Path**: wustcat404/time-bar

## Basic Information

- **Project Name**: TimeBar
- **Description**: 基于harmony os 的Canvas和Video组件实现的时间轴联动视频播放Sample，核心功能是通过手势（平移、捏合缩放）控制视频时间轴，从而实现视频播放进度的快进、快退联动效果。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 2
- **Created**: 2025-10-12
- **Last Updated**: 2025-11-05

## Categories & Tags

**Categories**: harmonyos-multimedia

**Tags**: None

## README

# 实现可缩放时间轴功能

## 介绍

本项目是一个基于Canvas和Video组件实现的时间轴联动视频播放Sample，核心功能是通过手势（平移、捏合缩放）控制视频时间轴，从而实现视频播放进度的快进、快退联动效果。

**该项目已贡献给华为开源项目，bug fix以及功能优化代码将在[HarmonyOS_Samples](https://gitee.com/harmonyos_samples)/[TimeBar](https://gitee.com/harmonyos_samples/timebar)更新**。

## 效果图预览
| 时间轴缩放                                   | 时间轴扩张                                   | 样式调整                                         |
| -------------------------------------------- | -------------------------------------------- |----------------------------------------------|
| <img src='./screenshots/pic1.png' width=320> | <img src='./screenshots/pic2.png' width=320> | <img src='./screenshots/pic3.png' width=320> |

## 功能特性

- **手势控制时间轴**: 支持平移手势（拖动时间轴）和捏合缩放手势（调整时间轴刻度）。
- **视频播放与时间轴同步**: 视频播放进度与时间轴上的当前时间点实时同步，用户拖动时间轴时，视频播放会相应跳转。
- **多视频片段管理**: 能够加载并按时间顺序播放多个视频文件。
- **时间刻度动态调整**: 时间轴的刻度（小时/分钟模式）会根据用户的缩放手势自动或平滑切换，提供合适的视图粒度。
- **播放状态反馈**: 视频播放状态（播放、暂停）与时间轴同步，提升用户体验。

## 工程结构&模块类型

```
├───entry/src/main/ets
│   ├───common                              
│   │   ├───contants                        
│   │   │   └───CommonConstants.ets             // 常量
│   │   └───utils                           
│   │       └───CommonUtils.ets                 // 通用工具类
│   ├───entryability                        
│   │   └───EntryAbility.ets                    // Ability的生命周期回调内容
│   ├───entrybackupability                  
│   │   └───EntryBackupAbility.ets              // Ability的生命周期回调内容
│   ├───components
│   │   └───VideoView.ets                       // 视频播放组件      
│   ├───model
│   │   ├───SegmentIndexInfo.ets                // 时间轴偏移量定位片段的结果信息
│   │   └───VideoInfo.ets                       // 视频信息           
│   ├───pages
│   │   ├───Index.ets                           // 首页
│   │   ├───MultiStyleTimeBar.ets               // 时间轴基础功能演示页面
│   │   └───TimeBarVideoLinkage.ets             // 时间轴视频联动演示页面
├───entry/src/main/resources                    // 静态资源
├───time_bar/src/main/ets                       // 可伸缩时间轴动态共享库
│   ├───components
│   │   ├───interface
│   │   │   ├───CustomDrawCallback.ets          // 自定义绘制回调
│   │   │   ├───CustomDrawItem.ets              // 自定义绘制配置项
│   │   │   ├───MiddleIndicatorOption.ets       // 时间轴中线样式选项
│   │   │   ├───TimeBarOption.ets               // 时间轴样式选项
│   │   │   ├───TimePickedCallBack.ets          // 时间轴回调
│   │   │   ├───TimeScaleOption.ets             // 时间轴刻度样式选项
│   │   │   ├───VideoAreaOption.ets             // 时间轴视频区域样式选项
│   │   │   └───VideoTimeBounds.ets             // 时间轴视频区域时间边界    
│   │   ├───viewModel                           
│   │   │   ├───RecordSegment.ets               // 视频片段信息
│   │   │   └───TimeBarModel.ets                // 时间轴的ViewModel逻辑层            
│   │   └───TimeBarView.ets                     // 时间轴组件
│   ├───contants
│   │   └───CommonConstants.ets                 // 常量     
│   ├───utils
│   │   └───CommonUtils.ets                     // 通用工具类
```

## `TimeBarView` 接口信息

`TimeBarView` 组件通过 `@Prop` 装饰器向外部暴露了以下属性和回调，用于配置其外观和行为：

| 名称                  | 类型                                                         | 默认值                                                       | 说明                                                     |
| --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------------- |
| model                 | TimeBarModel                                                 | 必填（@Require）                                             | 时间轴数据模型，集中管理 timeRange/currentTime 及边界    |
| middleIndicatorOption | MiddleIndicatorOption                                        | `{ length: 100, fillColor: Color.Red }`                      | 中线样式                                                 |
| intervalWidth         | number                                                       | 10                                                           | 邻接小刻度间的像素距离。10px 对应 10 分钟（即 1px=1min） |
| timeScaleOption       | TimeScaleOption                                              | `{ scaleLineWidth: 1, scaleLineHeight: 8, scaleTextColor: '#808080', scaleLineColor: 'rgb(206,206,205)', scaleAlignment: TOP }` | 刻度线与时间文字样式                                     |
| videoAreaOption       | VideoAreaOption                                              | `{ backgroundColor:'#606266', height:20, topOffset:40 }`     | 录制区域（色条）展示样式                                 |
| timeBarOption         | TimeBarOption                                                | `{ width:'100%', height:100, backgroundColor:'rgb(245,245,244)' }` | 容器画布的宽高与背景色                                   |
| onContextReady        | (ctx: CanvasRenderingContext2D, component: TimeBarView) => void | -                                                            | 画布上下文就绪回调，暴露 ctx 及组件 self                 |

## `TimeBarView` 公开方法

| 方法                   | 类型                                                                     | 说明                                                         |
| ---------------------- |------------------------------------------------------------------------| ------------------------------------------------------------ |
| setTimeBarMoveListener | `(listener: TimePickedCallback) => void`                               | 注册时间轴移动/自动滚动回调（返回当前居中时间与状态 START/PLAYING/STOP） |
| registerCustomDraw     | `(callback: CustomDrawCallback, zIndex?: number, id?: string) => void` | 注册自定义绘制，按 zIndex 从小到大绘制                       |
| unregisterCustomDraw   | `(param: string \| CustomDrawCallback) => void`                        | 取消注册自定义绘制                                           |
| clearAllCustomDraw     | `() => void`                                                           | 清空所有自定义绘制回调                                       |
| safeDraw               | `(cb: (ctx: CanvasRenderingContext2D) => void) => void`                | 在内部封装的 save/restore 保护下进行一次性绘制，并触发重绘   |

## 模块依赖

**依赖[dayjs](https://ohpm.openharmony.cn/#/cn/detail/@mui%2Fdayjs)三方库**

## 使用说明

1. 将独立的应用示例工程导入DevEco Studio进行编译构建及运行调试。
2. 安装运行后，即可在设备上查看应用示例运行效果，以及进行相关调试。

## 约束与限制

详细信息可参考[可伸缩时间轴组件开发约束与限制]()。

1.设备限制  
本端设备：华为手机设备。   

2.使用限制  
设备打开WIFI，并可访问网络。

3.HarmonyOS系统：HarmonyOS 6.0.0 Release及以上。

4.DevEco Studio版本：DevEco Studio 6.0.0 Release及以上。

5.HarmonyOS SDK版本：HarmonyOS 6.0.0 Release SDK及以上。