更新记录

1.0.0（2026-10-15）

出版提交

平台兼容性

uni-app(5.26)

short-video-item · 短剧 / 短视频 Feed 原生列表项（uni-app）

抖音 / 红果 式「上下滑动刷视频」的 App 原生列表项组件（兼容模式 UTS 组件，Android ExoPlayer / iOS AVPlayer）。

• ✅ 画面跟着 swiper 真实滚动（原生视图在 View 层级内，不像 webview 的 <video> 那样脱离文档流）
• ✅ 每个列表项自带一个播放器：非当前项已预装载停在首帧，滑过去即播
• ✅ 进度 / 时长 / 缓冲二级条 / 首帧耗时 / 播放真实态 / 错误分类 全套事件
• ✅ 倍速、清晰度、画面缩放、音量增强、外挂字幕、磁盘缓存、预加载、截图存相册
• ✅ 全屏横屏、后台小窗（Android 自绘悬浮窗 / iOS 系统画中画）
• ✅ 500ms 看门狗自愈：切页不播、输出面丢失、缓冲卡死都能自己爬起来

只支持 App 端的 nvue 页面（.nvue）。Web / 小程序 / HarmonyOS 不支持。
内部实现、双端差异、排障手册见同目录 docs/DEV.md（工程内文档，不必随插件发布）。

目录

1. 快速开始（5 分钟）
2. 宿主工程必须做的配置
3. 完整示例页面（nvue）
4. API 参考
5. 必须遵守的 8 条约定
6. 双端能力边界
7. 常见问题排查
8. 目录结构与版本

1. 快速开始（5 分钟）

1.1 安装

把 short-video-item 目录拷进项目的 uni_modules/（或从插件市场导入）：

uni_modules/
└── short-video-item/
    ├── package.json
    └── utssdk/
        ├── interface.uts
        ├── app-android/  (config.json / index.vue / index.uts / ShortVideoItemBridge.kt)
        └── app-ios/      (config.json / Info.plist / index.vue / index.uts / ShortVideoItemBridge.swift)

组件标签名是 sv-video-item（由 name 字段决定），编译器自动注册，不需要写进 pages.json 的 usingComponents，也不需要 import 组件本身。

1.2 最小可用页面（pages/index/index.nvue）

<template>
  <view class="page">
    <swiper class="pager" vertical="true" :current="current" @change="onChange">
      <swiper-item v-for="(item, i) in list" :key="i">
        <view class="cell">
          <view class="video-box">
            <sv-video-item
              class="video"
              :url="item.url"
              :format="item.format"
              :active="i === current"
              @event="onPlayerEvent"
            />
          </view>
        </view>
      </swiper-item>
    </swiper>
  </view>
</template>

<script>
export default {
  data() {
    return {
      current: 0,
      curMs: 0,
      duration: 0,
      list: [
        { url: 'https://media.w3.org/2010/05/bunny/trailer.mp4', format: 'mp4' },
        { url: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8', format: 'hls' }
      ]
    };
  },
  methods: {
    onChange(e) { this.current = e.detail.current; },
    onPlayerEvent(detail) {
      const raw = (detail && detail.json) ? detail.json : detail;
      if (!raw || typeof raw !== 'string') return;
      const e = JSON.parse(raw);
      if (e.type === 'time') {
        if (e.dur > 0) this.duration = e.dur;   // ⚠️ 必须判 > 0，否则会把已知时长抹回 0
        this.curMs = e.cur;
      }
    }
  }
};
</script>

<style>
.page { flex: 1; background-color: #000000; }
.pager { flex: 1; }
.cell { flex: 1; }
.video-box { flex: 1; }                                  /* 容器给 flex:1 */
.video { position: absolute; left: 0; top: 0; right: 0; bottom: 0; }  /* 组件铺满容器 */
</style>

⚠️ 必须是 .nvue 文件。App-vue 页面里原生组件无法在 swiper / scroll-view 中使用，画面不会跟着滚。
⚠️ 改完原生代码（utssdk/**）后必须重新制作自定义调试基座或云打包，「运行到手机」只同步 JS/UTS，不会更新原生壳。

2. 宿主工程必须做的配置

2.1 manifest.json（源码视图）

"app-plus": {
  "nvueStyleCompiler": "uni-app",        // 必须是 uni-app 编译模式
  "statusbar": { "immersed": "supportedDevice" },   // 沉浸式：视频才能顶到屏幕最上沿
  "distribute": {
    // iOS 屏幕方向必须是数组，单字符串会被忽略
    "orientation": ["portrait-primary", "landscape-primary", "landscape-secondary"],
    "android": {
      "screenOrientation": ["portrait-primary", "landscape-primary", "landscape-secondary"],
      "minSdkVersion": 26,
      "targetSdkVersion": 33,
      "permissions": [
        "<uses-permission android:name=\"android.permission.SYSTEM_ALERT_WINDOW\"/>",   // 小窗（自绘悬浮窗）必需
        "<uses-permission android:name=\"android.permission.MODIFY_AUDIO_SETTINGS\"/>"  // 音量增强 boost 必需
      ]
    },
    "ios": {
      "UIBackgroundModes": ["audio"]     // 后台继续播 / 画中画
    }
  }
}

⚠️ 不要再声明 WRITE_EXTERNAL_STORAGE（DCloud 基座和项目根 AndroidManifest.xml 已声明过）。
重复声明（尤其带 android:maxSdkVersion 属性的）会让云端 manifest 合并失败，连带把 uni_modules 的 Gradle 子工程注册搞挂，报一串误导性的 Project with path ':uni_modules:xxx' could not be found。

2.2 pages.json：页面去导航栏

{
  "path": "pages/index/index",
  "style": {
    "navigationStyle": "custom",
    "backgroundColor": "#000000",
    "app-plus": { "titleNView": false }
  }
}

2.3 iOS 截图存相册

插件 utssdk/app-ios/Info.plist 已带 NSPhotoLibraryAddUsageDescription，云打包会自动合并；若你的工程自定义了 Info.plist，请确认包含该键。

3. 完整示例页面（nvue）

完整可运行页面在 pages/demo/demo.nvue（本项目内），覆盖：上下滑切集、单击播放/暂停、双击点赞、长按 2 倍速、进度条 + 缓冲二级条、倍速、清晰度、字幕、全屏横屏、小窗、截图、清缓存、选集、播完自动下一集、加载失败重试。

下面按功能分段讲，每段都是可直接抄的代码。

3.1 模板：组件怎么摆、属性怎么给

<swiper class="pager" vertical="true" :current="current" :duration="0" @change="onChange">
  <swiper-item v-for="(item, i) in list" :key="i">
    <view class="cell" @touchstart="" @touchend="">
      <view class="video-box">
        <sv-video-item
          ref="vid"
          class="video"
          :url="item.url"
          :format="item.format"
          :active="i === current && playing"
          :repeat="autoNext ? 'off' : 'one'"
          :rate="i === current ? rate : 1"
          :fit="fit"
          :quality="quality"
          :subtitle="i === current && subtitleOn ? item.subtitle : ''"
          :cache="cacheOn"
          :floating="i === current && floatingOn"
          :seek-seq="seekSeq"
          :seek-ms="seekMs"
          :cmd="i === current ? cmd : ''"
          @event="onPlayerEvent"
        />
      </view>
    </view>
  </swiper-item>
</swiper>

要点：

🚨 属性区里绝对不要写 HTML 注释。weex 编译器遇到注释会终止该标签的属性解析，整个 <sv-video-item> 退化成文本节点：画面全黑、@event 收不到、所有 prop 失效，而且编译不报错。注释一律写到标签外面。

手势绑定要按平台分开（安卓的滑动体验全靠这一条）：

<!-- iOS：原生视频层层级高、会吞 touch，必须在组件上再挂一处 -->
<!-- #ifdef APP-IOS -->
<sv-video-item ...
  @event="onPlayerEvent"
  @touchstart="onTapStart" @touchmove="" @touchend="onTapEnd" @touchcancel="onTapCancel" />
<!-- #endif -->

<!-- 安卓：绝不能给组件绑 @touch*，否则 swiper 收不到 MOVE、上下滑切集失效 -->
<!-- #ifndef APP-IOS -->
<sv-video-item ... @event="onPlayerEvent" />
<!-- #endif -->

条件编译注释必须写在标签外面（属性区里连注释都不能有，见上）。安卓的手势由 .cell / .ui 这两个普通 view 承担，它们不会阻断 swiper。

3.2 事件分发：一个 handler 收全部状态

onPlayerEvent(detail) {
  const raw = (detail && detail.json) ? detail.json : detail;  // 兼容两种形态
  if (!raw || typeof raw !== 'string') return;
  const e = JSON.parse(raw);

  if (e.type === 'time') {                 // 500ms 一次：进度 / 时长 / 已缓冲
    if (e.dur > 0) this.duration = e.dur;  // ⚠️ 必须判 > 0
    if (e.buf !== undefined) this.bufMs = e.buf;
    if (!this.dragging) this.curMs = e.cur;
    if (e.cur > 0) { this.everPlayed = true; this.loadFail = false; }
  } else if (e.type === 'ended') {         // 播完（loop 也照发）→ 连播交给页面
    this.onEnded();
  } else if (e.type === 'cue') {           // 字幕文本：原生只推文本，页面负责画
    this.cueText = e.text || '';
  } else if (e.type === 'error') {         // 装载/播放失败
    if (!this.everPlayed) this.loadFail = true;
  }
}

3.3 命令通道：页面 → 原生

所有一次性动作用自包含字符串 verb#seq：seq 每次递增 → 字符串必变 → 组件 watcher 必触发 → 原生按 seq 去重执行。

sendCmd(c) {
  this.cmdSeq = this.cmdSeq + 1;
  this.cmd = c + '#' + this.cmdSeq;     // 例如 "pause#7" / "reload#8" / "fwd-15000#9"
},
togglePlay() {
  this.playing = !this.playing;
  this.sendCmd(this.playing ? 'play' : 'pause');
},
retryLoad() {
  this.sendCmd('reload');               // 强制重新装载（绕开"url 没变就不重载"的去重）
}

3.4 进度条 + 缓冲二级条

nvue 的 <slider> 没有「已缓冲」轨道，自己叠一条：

<view class="track">
  <slider class="slider" :value="sliderValue" :min="0" :max="sliderMax" :step="1"
          :disabled="duration <= 0" @changing="Changing" @change="Change" />
  <view v-if="duration > 0" class="buf" :style="bufStyle"></view>
</view>

onSeekChanging(e) {
  if (!this.dragging) { this.dragging = true; this.sendCmd('pause'); }  // 拖动期间先停
  this.dragValue = e.detail.value;
},
Change(e) {
  this.curMs = this.dragValue = e.detail.value;
  this.dragging = false;
  this.seekMs = Math.round(this.dragValue);
  this.seekSeq = this.seekSeq + 1;      // seq 递增 → 触发一次精确跳转
  if (this.playing) this.sendCmd('play');
}

3.5 全屏横屏

import { setScreenLandscape, onHostWindowSizeChanged } from '@/uni_modules/short-video-item';

toggleFullscreen() {
  this.landscape = !this.landscape;
  const r = setScreenLandscape(this.landscape);
  // r: landscape / portrait / landscape_unsupported_plist（iOS 工程没声明横屏）/ no_activity
  if (r === 'landscape_unsupported_plist') {
    uni.showToast({ title: '工程未声明横屏，请配 manifest 后重制基座', icon: 'none' });
  }
  setTimeout(() => this.refreshSize(), 400);
}

横屏后必须把新窗口尺寸告诉原生（否则安卓画面仍是竖屏尺寸）：

onReady() {
  uni.onWindowResize((res) => {
    this.refreshSize(res.size.windowWidth, res.size.windowHeight);
    onHostWindowSizeChanged();      // 安卓必需：重算画面缩放 / 重挂全屏容器
  });
}

🚨 uni.getSystemInfoSync() 在 App 内是缓存值，旋转那一刻读到的可能还是旋转前的尺寸。尺寸只认 uni.onWindowResize 推来的真值。

全屏的两条硬规则（已内置，页面不用管）

想要别的观感用 fit 覆盖：fit="contain"（强制完整显示）、fit="cover"（强制填满）。

3.6 小窗（后台悬浮播放）

import { canUseFloatingWindow, openFloatingWindowSetting } from '@/uni_modules/short-video-item';

toggleFloating() {
  if (this.floatingOn) { this.floatingOn = false; this.sendCmd('float-off'); return; }
  if (!canUseFloatingWindow()) {          // Android: 无「显示在其他应用上层」权限 / iOS: 不支持画中画
    uni.showModal({
      title: '小窗',
      content: '小窗需要「显示在其他应用上层」权限，去开启？',
      success: (res) => { if (res.confirm) openFloatingWindowSetting(); }
    });
    return;
  }
  this.floatingOn = true;
  this.sendCmd('float-on');   // 只开开关：切到后台才显示小窗，回 App 自动收回
}

小窗的实际行为（两端不同，调用方式相同）：

3.7 组件方法（通过 ref 调）

v-for 里 ref 拿到的是数组，按索引取当前项：

curVideo() {
  const r = this.$refs.vid;
  if (!r) return null;
  return (r.length !== undefined) ? r[this.current] : r;
},
snapshot()      { this.curVideo() && this.curVideo().capture(-1); },        // -1 = 当前帧，存相册
clearCache()    { this.curVideo() && this.curVideo().clearCache(); },
preloadNextEp() {
  const v = this.curVideo(), next = this.list[this.current + 1];
  if (v && next) v.preloadNext(next.url, next.format);                      // 切集那一刻是最佳时机
}

3.8 完整文件

4. API 参考

4.1 属性（props）

两类参数别混：
播放参数（rate volume fit repeat quality boost）→ 独立通道，改了不重载片源；
片源参数（url format subtitle cache）→ 参与装载，改了会重载（画面闪一下、进度 seek 回原位）。

4.2 事件（@event）

统一一个 event 事件，载荷是 JSON 字符串：e.detail.json → JSON.parse → 按 type 分发。

4.3 组件方法（ref 调用）

4.4 命令（cmd 的 verb）

4.5 宿主环境能力 API（从插件 import）

import {
  setScreenLandscape,       // (enabled: boolean) => string
  canUseFloatingWindow,     // () => boolean
  openFloatingWindowSetting,// () => void
  onHostWindowSizeChanged,  // () => void  窗口尺寸变了通知原生重算缩放（安卓必需）
  enterPictureInPicture,    // () => string  立刻进系统画中画（高级用法）
  exitPictureInPicture,     // () => string  主动退出系统画中画
  pipState                  // () => string  诊断串 active,supported,preWidth,preHeight
} from '@/uni_modules/short-video-item';

5. 必须遵守的 8 条约定

1. 只能在 .nvue 页面用。App-vue 下原生组件不跟随 swiper 滚动（这是选 nvue 的唯一原因）。
2. 属性区里不要写注释（会导致整个节点失效，见 3.1）。
3. active 与 playing 分开：active 表示「谁是当页」，playing 表示「要不要播」，一次性动作用 cmd 补一刀。
4. cmd / seek / frame 都用「自包含字符串 + seq 递增」，别用两个 prop 组合（更新顺序不保证，会把旧命令当新命令下发）。
5. 消费 time.dur 必须判 > 0，否则装载未就绪时会把已拿到的时长抹回 0，进度条永远禁用。
6. 失败提示只认确定性 error，且必须 && !everPlayed：error 载荷不带 url，「下一集」装载失败也会发到同一个 handler，没有仲裁就会让正在播的这集顶着失败提示。换集必须复位 loadFail / everPlayed。
7. 改 `utssdk/后必须重制自定义基座 / 云打包**；只改pages/**` 才能热更。
8. 不要重复声明权限（尤其 WRITE_EXTERNAL_STORAGE），见第 2 节。

6. 双端能力边界

7. 常见问题排查

8. 目录结构与版本

uni_modules/short-video-item/
├── package.json                        # dcloudext.type = component-uts（组件入口 + API 入口并存）
└── utssdk/
    ├── interface.uts                   # API 入口的类型声明
    ├── app-android/
    │   ├── config.json                 # media3 依赖 + minSdkVersion
    │   ├── index.vue                   # 【组件入口】标签名 sv-video-item
    │   ├── index.uts                   # 【API 入口】横屏 / 小窗相关
    │   └── ShortVideoItemBridge.kt     # ExoPlayer + TextureView（勿删）
    └── app-ios/
        ├── config.json                 # frameworks: AVFoundation / AVKit / Photos
        ├── Info.plist                  # NSPhotoLibraryAddUsageDescription
        ├── index.vue
        ├── index.uts
        └── ShortVideoItemBridge.swift  # AVPlayer + AVPlayerLayer（勿删）

平台门槛

当前版本：1.0.0 ｜ 示例页面：pages/demo/demo.nvue ｜ 工程内开发文档：docs/DEV.md