更新记录

1.0.0（2026-06-26） 下载此版本

v1.0.0

重构（Breaking Changes）

• 从 jz-video-flow 重构为通用容器 jz-custom-flow
  • 主容器 不再耦合任何内容形态，仅负责上下滑动手势、三槽位调度、切换动画、边界阻尼、触顶刷新、加载更多
  • 内容完全由 default 插槽决定，作用域提供 item / index / isCurrent / isPrev / isNext / slotIndex
  • 删除主容器全部视频 / 进度条相关 props 与事件：auto / muted / objectFit / progress / showFullScreen / fullScreenText / showLoading / errorMessage / play / pause / waiting / ended / error / timeupdate / loadedmetadata / fullscreenchange / changing / changeed
  • 删除主容器 ref 方法：play / pause / seek / setPlaybackRate / pageShow / pageHide
  • 新增 props：disabled / horizontalRatio / bounce
  • 新增 ref 方法：next / prev / switchList（取代 switchEpisode）/ getCurrentItem
  • 新增事件：changeStart

新增组件

• jz-flow-video — 视频 cell 子组件（替代旧 jz-video-player，更轻、active 驱动、内置 HLS / 单双击 / 进度条）
• jz-flow-images — 左右轮播图集 cell 子组件，自带 update:lock 机制配合父级 disabled 避免手势冲突

升级

• jz-progress-bar 新增 props：height / barColor / playedColor / bufferedColor / showTime，新增 change 事件（与 changeed 同义）

核心模块

• 新增 core/slot-pool.js（替代 core/video-pool.js，与内容形态无关的三槽位调度）
• 新增 core/hls-loader.js（H5 按需加载 hls.js，避免小程序 / nvue 打包错误）
• core/swiper-controller.js 新增 horizontalRatio / bounce 配置

入口

• index.js 默认导出 JzCustomFlow，具名导出 JzFlowVideo / JzFlowImages / JzProgressBar，未引用的子组件不会打包

平台兼容性

uni-app(4.45)

jz-video-flow

抖音风格短视频滑动组件，支持上下滑动切换、三槽位渲染、HLS流媒体、进度条控制、自动连播、多端兼容

核心特性

快速开始

1. 安装

将 jz-video-flow 目录置于项目的 src/uni_modules/ 下。

2. 组件注册

全局注册（推荐）：

// main.js / App.vue
import JzVideoFlow from '@/uni_modules/jz-video-flow'

// Vue 3
app.component('JzVideoFlow', JzVideoFlow)

页面内注册：

<script setup>
import JzVideoFlow from '@/uni_modules/jz-video-flow'
</script>

3. 基础用法

<template>
  <JzVideoFlow
    ref="videoFlowRef"
    :list="videoList"
    :current="currentIndex"
    :width="windowWidth"
    :height="windowHeight"
    :muted="false"
    :auto="true"
    :progress="true"
    :upper-tip-message="下拉刷新"
    @change="onVideoChange"
    @loadmore="onLoadMore"
    @refresh="onRefresh"
    @click="onVideoClick"
    @dblclick=""
    @timeupdate=""
  >
    <!-- 默认插槽：覆盖层（视频信息、点赞按钮等） -->
    <template #default="{ video, index }">
      <view class="video-overlay">
        <text class="video-title">{{ video.title }}</text>
      </view>
    </template>
  </JzVideoFlow>
</template>

<script setup>
import { ref } from 'vue'

const videoList = ref([
  { src: 'https://example.com/video1.mp4', poster: '', title: '视频1' },
  { src: 'https://example.com/video2.m3u8', poster: '', title: '视频2' },
])
const currentIndex = ref(0)

function onVideoChange(ev) {
  currentIndex.value = ev.detail.current
}
function onLoadMore(ev) {
  // 加载更多视频
}
function onRefresh(ev) {
  // 刷新视频列表
}
</script>

Props

Events

Slots

方法（通过 ref 调用）

目录结构

src/uni_modules/jz-video-flow/
├── package.json                    # 插件配置
├── readme.md                       # 说明文档
├── changelog.md                    # 更新日志
├── index.js                        # 主入口
├── components/                     # 组件目录
│   ├── jz-video-flow.vue           # H5 / 小程序 主组件
│   ├── jz-video-flow.nvue          # App-Nvue 主组件
│   ├── jz-video-player.vue         # 视频播放器（H5/小程序）
│   ├── jz-video-player.nvue        # 视频播放器（Nvue）
│   ├── jz-progress-bar.vue         # 进度条（H5/小程序）
│   └── jz-progress-bar.nvue        # 进度条（Nvue）
└── core/                           # 核心模块
    ├── video-pool.js               # 三槽位调度器
    ├── swiper-controller.js        # 滑动状态机
    └── utils.js                    # 工具函数

注意事项

HLS 支持

• H5 平台自动集成 hls.js，支持 m3u8 格式
• 小程序原生支持 HLS（微信/支付宝等）
• App-Nvue 需确保视频格式兼容

自动播放限制

• H5 平台受浏览器自动播放政策限制，首次需静音或用户交互
• 建议初始设置 muted: true，用户点击后取消静音

nvue 特殊处理

• nvue 使用 weex.requireModule('animation') 实现切换动画
• nvue 不支持 transition CSS 属性，需用 animation 模块
• nvue 进度条事件需阻止冒泡（@touchstart.stop）

许可证

MIT License

相关文档

• docs/jz-video-flow-plugin-dev.md — 插件开发文档