Imageplayer 图片序列播放器

GB.Imageplayer 将一组连续图片作为帧序列播放，适合产品 360° 展示、逐帧演示和图片动画。它支持正向或反向播放、暂停、停止、倍速、拖动切帧、进度与时间显示，并会预解码图片以减少首次显示闪烁。

安装与引入

浏览器直接引入

<script src="https://cloud.m775.net/js/imageplayer.js"></script>

npm 项目

npm i @gentbo/imageplayer

import '@gentbo/imageplayer';

快速开始

播放容器的每个直接子元素代表一帧，每帧中放置一张图片。完成配置后直接调用 start() 即可启动播放器。

<div id="productFrames">
  <figure><img src="frame-01.jpg" alt=""></figure>
  <figure><img src="frame-02.jpg" alt=""></figure>
  <figure><img src="frame-03.jpg" alt=""></figure>
</div>

<script>
GB.Imageplayer('#productFrames')
  .speed(100)
  .start(true, true);
// true, true：立即自动播放，并在结束后循环
</script>

组织播放器结构

GB.Imageplayer(target)通过 CSS 选择器或 HTMLElement 创建实例；目标不存在时抛出初始化错误。

.content(selector)指定目标容器内部的帧列表；未设置时，主容器的直接子元素就是帧列表。

.loading(selector)指定初始化和预加载期间显示的元素。

.complete(selector)指定非循环播放完成后显示的元素。

.hidden(className)指定统一的隐藏类名；未设置时通过元素的 display 样式控制显隐。

帧列表不能为空，每个帧元素中应包含一个 img。同一个主容器只能初始化一次。

播放参数

.speed(msPerFrame)设置基础帧间隔，单位为毫秒，默认 100ms/帧；只接受正数。

.scale(pixelsPerFrame)设置横向拖动多少像素切换一帧，默认 10px/帧。

.cache(maxSeconds, startSeconds)设置最大预解码时长和播放前预热时长，默认分别为 5 秒和 2 秒。

.reverse()将初始播放方向改为反向，从最后一帧开始。

预解码数量会根据缓存秒数和基础帧间隔自动换算。倍速只影响实际播放间隔，不改变显示的基础总时长。

启动与控制对象

start(auto = false, loop = true) 是链式配置的收尾方法，用于初始化并启动播放器，可以直接调用，不需要使用 await。默认只显示第一帧，不会自动播放；传入 true 可在初始化后自动播放。

只有需要在业务代码中取得播放控制对象时，才需要等待 start() 完成。控制对象提供以下方法：

controls.play()按当前方向继续播放。

controls.right()切换为正向播放。

controls.left()切换为反向播放。

controls.pause()暂停并保留当前帧。

controls.stop()停止播放，并回到当前方向的起始帧。

controls.times(value)设置播放倍速，例如 0.5、1、2；0 不会生效。

const player = GB.Imageplayer('#viewer')
  .content('.frames');

const controls = await player.start(false, false);

controls.right();
controls.times(2);
controls.pause();

run() 是无参数兼容入口，等价于使用默认参数调用 start()，也可以直接调用。需要取得控制对象时，再处理它的异步返回值。

配置控制条

先用 control() 指定控制条，再配置控制条内部的按钮选择器。按钮可逐项设置，也可以通过 button() 批量设置。

GB.Imageplayer('#viewer')
  .content('.frames')
  .control('.controls', 3000)
  .button({
    play: '.play',
    pause: '.pause',
    left: '.reverse',
    right: '.forward',
    stop: '.stop',
    stopped: '.stopped'
  })
  .start();

.control(selector, timeout = 0)设置控制条；timeout 单位为毫秒，非正数表示常显。

.playButton / pauseButton分别设置播放和暂停按钮。

.rightButton / leftButton分别设置正向和反向播放按钮。

.stopButton / stoppedButton设置停止按钮和用于表示已停止状态的元素。

.showControlButton / hideControlButton设置控制条外部的显示和隐藏按钮。

进度与时间

.progress(selector)设置进度条。容器有一个子元素时取第一个，有两个时取第二个作为实际进度层。

.time(total, current, format?)设置总时间、当前时间元素和格式，默认格式为 h:i:s。

GB.Imageplayer('#viewer')
  .progress('.progress')
  .time('.duration', '.current', 'i:s')
  .start();

时间是按“帧数 × 基础帧间隔”换算的播放时间，不是图片文件自身携带的媒体时长。

状态通知与自定义按钮

.notice(callback)状态变化时调用 callback(nextState, previousState)。

.click(selector, callback)为播放器容器内的自定义按钮添加点击处理。

状态包括 ready、left、right、pause、stop 和 complete。

GB.Imageplayer('#viewer')
  .notice((state, previous) => {
    console.log(`${previous} -> ${state}`);
  })
  .click('.help', () => openHelp())
  .start(true, false);

拖动切帧与使用边界

初始化后可在内容区域横向拖动切换帧。拖动开始时自动暂停计时器，结束后根据原播放状态决定是否恢复。该能力依赖 Pointer Events，并会为内容区域设置 touch-action: none。

start() 只执行一次初始化，之后再次调用会返回同一个控制对象，不会重新读取 DOM 或配置。请在首次启动前完成所有链式设置，并确保图片列表已经写入页面。