文章目录
-
-
- 画中画的工作方式
- ArkTS 侧：极简配置
- HTML 侧：画中画逻辑
- 视频来源的处理方式
- 进阶：用 JS 监听画中画窗口尺寸
- 画中画 vs 系统 PiP
- 常见问题
- 写在最后
-
画中画（Picture-in-Picture）就是把视频变成一个小悬浮窗，可以在桌面上到处拖，用户边看视频边做其他事。在 ArkWeb 里，网页里的
<video> 标签可以直接触发画中画，ArkTS 这边只需要简单配置，前端 HTML 写好对应逻辑就行了。
画中画的工作方式
ArkWeb 的画中画依赖 Web 标准的 Picture-in-Picture API（W3C 标准），所以核心逻辑写在 HTML/JavaScript 里，ArkTS 侧主要负责创建 Web 组件并允许相关权限。
ArkTS 侧：极简配置
ArkTS 这边真的很简单，核心就是加载 HTML 文件：
import { webview } from '@kit.ArkWeb';
@Entry
@Component
struct WebPictureInPictureDemo {
// 加载包含画中画逻辑的 HTML 页面
@State videoSrc: Resource = $rawfile('PictureInPicture.html');
controller: webview.WebviewController = new webview.WebviewController();
build() {
Column() {
Web({ src: this.videoSrc, controller: this.controller })
.width('100%')
.height('100%')
}
.width('100%')
.height('100%')
}
}
就这？对，就这。画中画的核心逻辑在 HTML/JS 里。
HTML 侧：画中画逻辑
配合 ArkTS 使用的 HTML 文件，需要包含 <video> 标签和画中画 API 调用：
<!DOCTYPE html>
<html lang="zh">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>画中画示例</title>
<style>
body { margin: 0; padding: 16px; font-family: sans-serif; background: #f5f5f5; }
video { width: 100%; border-radius: 8px; }
.controls { margin-top: 12px; display: flex; gap: 8px; flex-wrap: wrap; }
button {
padding: 10px 20px;
border: none;
border-radius: 6px;
background: #007AFF;
color: white;
font-size: 14px;
cursor: pointer;
}
button:active { opacity: 0.8; }
#status { margin-top: 8px; font-size: 13px; color: #666; }
</style>
</head>
<body>
<video id="myVideo" controls src="video.mp4" playsinline>
您的浏览器不支持 video 标签
</video>
<div class="controls">
<button onclick="enterPiP()">开启画中画</button>
<button onclick="exitPiP()">退出画中画</button>
</div>
<p id="status">就绪</p>
<script>
const video = document.getElementById('myVideo');
const status = document.getElementById('status');
// 检查浏览器支持
if (!document.pictureInPictureEnabled) {
status.textContent = '当前环境不支持画中画';
}
// 开启画中画
async function enterPiP() {
try {
if (document.pictureInPictureElement) {
status.textContent = '已经在画中画模式了';
return;
}
await video.requestPictureInPicture();
status.textContent = '已进入画中画模式';
} catch (err) {
status.textContent = '开启失败：' + err.message;
console.error('PiP 开启失败：', err);
}
}
// 退出画中画
async function exitPiP() {
try {
if (!document.pictureInPictureElement) {
status.textContent = '当前不在画中画模式';
return;
}
await document.exitPictureInPicture();
status.textContent = '已退出画中画模式';
} catch (err) {
status.textContent = '退出失败：' + err.message;
}
}
// 监听画中画状态变化
video.addEventListener('enterpictureinpicture', () => {
status.textContent = '画中画：开启中 🎬';
});
video.addEventListener('leavepictureinpicture', () => {
status.textContent = '画中画：已关闭';
});
</script>
</body>
</html>
把这个文件放到 entry/src/main/resources/rawfile/PictureInPicture.html，ArkTS 里用 $rawfile('PictureInPicture.html') 加载。
视频来源的处理方式
1. 使用 rawfile 里的本地视频
<video id="myVideo" controls src="test_video.mp4" playsinline>
把 test_video.mp4 放进 rawfile/ 目录，直接用相对路径引用。
2. 使用网络视频
<video id="myVideo" controls
src="https://www.example.com/video.mp4"
playsinline>
需要在 ArkTS 侧的 Web 组件上开启网络访问：
Web({ src: …, controller: … })
.onlineImageAccess(true) // 允许加载在线图片
.javaScriptAccess(true) // 允许 JS（画中画 API 需要）
进阶：用 JS 监听画中画窗口尺寸
画中画窗口的尺寸可以通过 JS 获取，用于调整 UI 布局：
video.addEventListener('enterpictureinpicture', (event) => {
const pipWindow = event.pictureInPictureWindow;
console.log('PiP 窗口宽：', pipWindow.width);
console.log('PiP 窗口高：', pipWindow.height);
// 监听 PiP 窗口尺寸变化
pipWindow.addEventListener('resize', (e) => {
console.log('PiP 窗口尺寸变化：', e.target.width, 'x', e.target.height);
});
});
画中画 vs 系统 PiP
HarmonyOS 还有一个系统级的 PiP（通过 PiPController 实现），和这里讲的 Web 画中画是两回事：
| 控制层 | HTML/JavaScript | ArkTS |
| 内容范围 | 仅限 Web 内的 video 元素 | 可以是任意原生视图 |
| 触发方式 | JS 调用 | ArkTS 代码 |
| 适用场景 | 网页内嵌视频 | 原生视频播放器 |
常见问题
Q：画中画按钮点了没反应
检查 document.pictureInPictureEnabled 是否为 true。部分场景下，视频未播放时调 requestPictureInPicture() 会报错，需要先确保视频已经开始播放。
Q：视频用 file:// 路径无法播放
在 ArkTS 侧开启 .fileAccess(true) 允许 Web 访问本地文件。
写在最后
Web 画中画的 ArkTS 侧真的极简，几行代码搞定。核心工作在 HTML/JS 侧，按照 W3C 标准写就行。如果你的 App 有视频功能，给用户加上画中画支持，体验提升立竿见影。
