> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# video

视频播放组件，支持本地和网络视频资源的播放控制。

<iframe src="https://developer.doubao.com/docs-preview/component-simulator/?caseId=video"
  title="组件示例 video"
  width="100%"
  height="700"
  loading="lazy"
  style="width:100%;height:700px;border:0;border-radius:16px;overflow:hidden;"
></iframe>

## 扫码预览

![扫码预览 video](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fcomponent%252Fvideo%252Findex)

## Props

<table>
<thead>
<tr><th width="140">属性名</th><th width="240">类型</th><th width="120">默认值</th><th width="80">必填</th><th width="360">说明</th></tr>
</thead>
<tbody>
<tr><td>as</td><td><code>&quot;Audio&quot; | &quot;Video&quot;</code></td><td>'Video'</td><td>否</td><td>媒体的类型</td></tr>
<tr><td>attached</td><td><code>boolean</code></td><td>-</td><td>否</td><td>是否按需加载播放器实例，用于性能优化，常用于列表场景，其他情况无需设置</td></tr>
<tr><td>autoPlay</td><td><code>boolean</code></td><td>false</td><td>否</td><td>流数据变化后自动播放。</td></tr>
<tr><td>autoPrepare</td><td><code>boolean</code></td><td>true</td><td>否</td><td>在资源准备完成后自动预渲染播放器（显示首帧）</td></tr>
<tr><td>domain</td><td><code>string</code></td><td>undefined</td><td>否</td><td>使用 vid 播放视频需要同时传入 token 和 domain。头条支持仅传入 vid。查看更多.</td></tr>
<tr><td>fullscreenMode</td><td><code>&quot;landscape&quot; | &quot;portrait&quot;</code></td><td>'landscape'</td><td>否</td><td>全屏模式下是否旋转</td></tr>
<tr><td>initTime</td><td><code>number</code></td><td>false</td><td>否</td><td>在资源准备完成后自动预渲染播放器（显示首帧）</td></tr>
<tr><td>loop</td><td><code>boolean</code></td><td>false</td><td>否</td><td>循环播放。视频开始播放后，循环状态变化不会改变视频的当前播放/暂停状态。</td></tr>
<tr><td>mute</td><td><code>boolean</code></td><td>false</td><td>否</td><td>是否静音实时播放器。</td></tr>
<tr><td>objectfit</td><td><code>&quot;scaleToFill&quot; | &quot;aspectFit&quot; | &quot;aspectFill&quot;</code></td><td>'aspectFit'</td><td>否</td><td>指定视频裁剪/缩放模式。</td></tr>
<tr><td>onAppear</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器可见。应该指定 <code>scene</code> 和 <code>videoengineId</code>。</td></tr>
<tr><td>onDisappear</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器不可见。应该指定 <code>scene</code> 和 <code>videoengineId</code>。</td></tr>
<tr><td>onEnded</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器播放结束。</td></tr>
<tr><td>onError</td><td><code>(e: { errorCode: number; errorMsg: string }) =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器接收到错误信息。</td></tr>
<tr><td>onFirstFrame</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>视频开始渲染首帧时触发</td></tr>
<tr><td>onPause</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器暂停。</td></tr>
<tr><td>onPlay</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器开始播放。</td></tr>
<tr><td>onPrepared</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器准备好播放。</td></tr>
<tr><td>onRedirected</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>如果访问 gecko 资源，加载是异步的</td></tr>
<tr><td>onSeek</td><td><code>(willPlay: boolean) =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器搜索。</td></tr>
<tr><td>onSrcChanged</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>源文件发生变化</td></tr>
<tr><td>onStop</td><td><code>() =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器停止。</td></tr>
<tr><td>onTimeUpdate</td><td><code>(e: { detail: { current: number; total: number } }) =&gt; void</code></td><td>undefined<br>@eventProperty</td><td>否</td><td>播放器进度更新</td></tr>
<tr><td>pauseOnHide</td><td><code>boolean</code></td><td>false</td><td>否</td><td>指定当 LynxView 退出背景或移出屏幕后是否暂停视频，以防止声音泄漏</td></tr>
<tr><td>playbackSpeed</td><td><code>number</code></td><td>1.0</td><td>否</td><td>指定播放速度</td></tr>
<tr><td>playerType</td><td><code>string &amp; {} | &quot;light&quot; | &quot;default&quot;</code></td><td>'default'</td><td>否</td><td>自定义播放器后端。宿主可注入其自己的播放器。playerType === 'light' 不支持 <code>preloadKey</code>。</td></tr>
<tr><td>playUrl</td><td><code>string</code></td><td>undefined</td><td>否</td><td>指定视频播放源，一旦设置 play-url，播放器将尝试异步加载资源。在绑定重定向之前，所有播放控制逻辑将无效。</td></tr>
<tr><td>poster</td><td><code>string</code></td><td>undefined</td><td>否</td><td>海报。播放后将被取消显示。</td></tr>
<tr><td>preloadKey</td><td><code>string</code></td><td>undefined</td><td>否</td><td>指定视频预加载的键（不支持 playerType === 'light'）。如果未填写，则为 iOS 的 URL 的 md5 和 Android 的 hashcode。视频预加载方案</td></tr>
<tr><td>ref</td><td><code>ForwardedRef&lt;VideoEngineRef&gt;</code></td><td>-</td><td>否</td><td>-</td></tr>
<tr><td>resolution</td><td><code>&quot;auto&quot;<br>| &quot;240p&quot;<br>| &quot;360p&quot;<br>| &quot;480p&quot;<br>| &quot;540p&quot;<br>| &quot;720p&quot;<br>| &quot;1080p&quot;<br>| &quot;4k&quot;<br>| &quot;hdr&quot;<br>| &quot;2k&quot;<br>| &quot;1080p 50fps&quot;<br>| &quot;2k 50fps&quot;<br>| &quot;4k 50fps&quot;<br>| &quot;1080p 60fps&quot;<br>| &quot;2k 60fps&quot;<br>| &quot;4k 60fps&quot;<br>| &quot;1080p 120fps&quot;<br>| &quot;2k 120fps&quot;<br>| &quot;4k 120fps&quot;</code></td><td>'auto'</td><td>否</td><td>指定播放分辨率。</td></tr>
<tr><td>scene</td><td><code>string</code></td><td>'videoengine'</td><td>否</td><td>用于标记曝光时间点。请确保在整个页面中唯一。</td></tr>
<tr><td>style</td><td><code>CSSProperties</code></td><td>undefined</td><td>否</td><td>包装器的样式，特别用于设置圆角</td></tr>
<tr><td>token</td><td><code>string</code></td><td>undefined</td><td>否</td><td>使用 vid 播放视频需要同时传入 token 和 domain。头条支持仅传入 vid。</td></tr>
<tr><td>videoEngineId</td><td><code>string</code></td><td>'videoengine'</td><td>否</td><td>用于选择 <code>x-video-engine</code>。请确保在整个页面中唯一。</td></tr>
<tr><td>videoId</td><td><code>string</code></td><td>undefined</td><td>否</td><td>使用 vid 指定视频播放源。大多数主机会使用 vid 来播放。你需要同时传入 token 和 domain。头条支持仅传入 vid。</td></tr>
<tr><td>videoModel</td><td><code>string</code></td><td>undefined</td><td>否</td><td>指定视频播放源，使用公司推荐的视频模型数据结构播放资源，表现为 JSON 字符串。</td></tr>
<tr><td>volume</td><td><code>number</code></td><td>1.0</td><td>否</td><td>指定音量，范围：[0.0, 1.0]</td></tr>
</tbody>
</table>
