HarmonyOS NEXT 视频选择、播放与上传实战指南

在 HarmonyOS NEXT 应用开发中视频处理是构建社交、内容创作等场景应用的核心能力。本文将从视频选择、播放控制、上传服务三个维度结合实际代码案例系统讲解如何构建完整的视频处理链路。HarmonyOS NEXT 的一大设计理念是隐私安全优先——系统提供了 Picker 组件允许应用在不申请相册或存储权限的情况下让用户主动选择并授权访问特定媒体资源。这一机制贯穿视频选择与播放的全流程。一、视频选择从相册获取视频文件在 HarmonyOS NEXT 中通过photoAccessHelper.PhotoViewPicker即可从系统相册选择视频无需申请ohos.permission.READ_MEDIA权限。1.1 基础选择流程以下代码演示如何从相册中选择单个视频并获取其 URI 路径typescriptimport { photoAccessHelper } from kit.MediaLibraryKit; import { BusinessError } from kit.BasicServicesKit; async function selectVideoFromAlbum(): Promisestring { try { // 1. 配置选择参数 const photoSelectOptions new photoAccessHelper.PhotoSelectOptions(); // 仅显示视频文件 photoSelectOptions.MIMEType photoAccessHelper.PhotoViewMIMETypes.VIDEO_TYPE; // 单次最多选择 1 个 photoSelectOptions.maxSelectNumber 1; // 2. 创建选择器并拉起系统相册 const photoPicker new photoAccessHelper.PhotoViewPicker(); const result: photoAccessHelper.PhotoSelectResult await photoPicker.select(photoSelectOptions); // 3. 返回选中视频的 URI if (result.photoUris result.photoUris.length 0) { console.info(选中的视频 URI:, result.photoUris[0]); return result.photoUris[0]; } } catch (error) { const err error as BusinessError; console.error(选择视频失败: ${err.code}, ${err.message}); } return ; }1.2 获取视频元信息当选中的 URI 需要进一步获取视频的时长、宽高等元数据时可通过photoAccessHelper.getAssets配合查询条件实现typescriptimport { photoAccessHelper } from kit.MediaLibraryKit; import { dataSharePredicates } from kit.ArkData; async function getVideoMetadata(uri: string): PromisephotoAccessHelper.PhotoAsset | undefined { try { const context getContext(this) as common.UIAbilityContext; const phAccessHelper photoAccessHelper.getPhotoAccessHelper(context); const predicates new dataSharePredicates.DataSharePredicates(); predicates.equalTo(uri, uri); const fetchOptions: photoAccessHelper.FetchOptions { fetchColumns: [ photoAccessHelper.PhotoKeys.WIDTH, photoAccessHelper.PhotoKeys.HEIGHT, photoAccessHelper.PhotoKeys.DURATION, photoAccessHelper.PhotoKeys.TITLE ], predicates: predicates }; const fetchResult await phAccessHelper.getAssets(fetchOptions); const asset await fetchResult.getFirstObject(); console.info(视频时长(ms):, asset.get(photoAccessHelper.PhotoKeys.DURATION)); console.info(视频宽高:, asset.get(photoAccessHelper.PhotoKeys.WIDTH), x, asset.get(photoAccessHelper.PhotoKeys.HEIGHT)); return asset; } catch (error) { console.error(获取元数据失败:, JSON.stringify(error)); } return undefined; }1.3 多选与预览场景若需实现类似朋友圈的多图/多视频发布功能可配置maxSelectNumber并监听选择回调。开源案例publishmultimediaupdates展示了完整的懒加载列表与媒体发布流程typescript// 支持多选最大可选 9 个媒体文件 photoSelectOptions.maxSelectNumber 9; photoSelectOptions.MIMEType photoAccessHelper.PhotoViewMIMETypes.IMAGE_VIDEO_TYPE; // 图片和视频混合二、视频播放从基础组件到专业 SDKHarmonyOS NEXT 提供了两种视频播放方案系统 Video 组件轻量、快速集成和专业播放器 SDK如阿里云播放器支持加密、倍速、清晰度切换等高级功能。2.1 使用系统 Video 组件Video组件封装了完整的播放控制 UI 和生命周期事件适用于大多数常规场景typescriptEntry Component struct VideoPlayerPage { State videoSrc: string ; // 从相册选择的视频 URI State isAutoPlay: boolean true; State showControls: boolean true; private controller: VideoController new VideoController(); build() { Column() { Video({ src: this.videoSrc, controller: this.controller }) .width(100%) .aspectRatio(16/9) .autoPlay(this.isAutoPlay) .controls(this.showControls) .loop(false) .onPrepared((e?: DurationObject) { console.info(视频准备完成时长:, e?.duration); }) .onUpdate((e?: TimeObject) { // 播放进度更新 }) .onFinish(() { console.info(播放结束); }) .onError(() { console.error(播放出错); }); Row() { Button(播放).onClick(() this.controller.start()); Button(暂停).onClick(() this.controller.pause()); Button(跳转10s).onClick(() this.controller.setCurrentTime(10, SeekMode.Accurate)); } } } }组件限制系统 Video 组件暂不支持直接控制音量若需音量调节建议使用AVPlayer或AudioRenderer进行开发。2.2 使用阿里云播放器 SDK高级场景对于需要支持加密视频播放VidAuth/VidSts、多清晰度切换、倍速播放的商业应用可集成阿里云播放器 SDK。URL 直接播放typescriptimport { AliPlayerFactory, UrlSource } from premierlibrary; const aliyunPlayer AliPlayerFactory.createAliPlayer(getContext(), ); const urlSource new UrlSource(); urlSource.setUri(https://example.com/video.mp4); aliyunPlayer.setUrlDataSource(urlSource); aliyunPlayer.setAutoPlay(true); aliyunPlayer.prepare();VidAuth 加密播放推荐typescriptimport { VidAuth, VidPlayerConfigGen } from premierlibrary; const vidAuthSource new VidAuth(); vidAuthSource.setVid(your-video-id); // 视频 ID vidAuthSource.setPlayAuth(your-play-auth); // 播放凭证 aliyunPlayer.setVidAuthDataSource(vidAuthSource);播放控制与监听typescript// 倍速播放 aliyunPlayer.setRate(1.5); // 跳转 aliyunPlayer.seekTo(30000); // 30秒 // 状态监听 aliyunPlayer.setOnPreparedListener(() { console.info(准备完成开始播放); aliyunPlayer.start(); }); aliyunPlayer.setOnErrorListener((error) { console.error(播放错误:, error); });2.3 进阶视频剪辑与压缩在实际发布场景中往往需要对视频进行剪辑或压缩以节省流量和存储。HarmonyOS 生态提供了基于 FFmpeg 的解决方案参考开源案例videotrimmer通过MP4Parser.getFrameAtTimeRange获取关键帧截图利用 FFmpeg 命令对沙箱中的视频进行裁剪和压缩最后通过request.agent上传处理后的视频。三、视频上传从沙箱到服务器视频上传涉及两个核心步骤将相册视频拷贝至应用沙箱Picker 返回的 URI 是临时只读权限以及通过request模块进行断点续传。3.1 拷贝视频到沙箱缓存目录Picker 返回的 URI 为临时授权访问若需持久化操作压缩、上传应先将文件拷贝至应用沙箱typescriptimport { fileIo as fs } from kit.CoreFileKit; async function copyVideoToCache(sourceUri: string): Promisestring { const context getContext(this); const cacheDir context.cacheDir; const fileName sourceUri.split(/).pop() || temp_video.mp4; const destPath ${cacheDir}/${fileName}; try { // 以只读方式打开源文件 const sourceFile fs.openSync(sourceUri, fs.OpenMode.READ_ONLY); // 创建目标文件写入 const destFile fs.openSync(destPath, fs.OpenMode.CREATE | fs.OpenMode.WRITE_ONLY); // 分片拷贝 const buffer new ArrayBuffer(8192); let readLen 0; while ((readLen fs.readSync(sourceFile.fd, buffer)) 0) { fs.writeSync(destFile.fd, buffer.slice(0, readLen)); } fs.closeSync(sourceFile.fd); fs.closeSync(destFile.fd); console.info(视频已拷贝至沙箱:, destPath); return destPath; } catch (error) { console.error(拷贝失败:, JSON.stringify(error)); } return ; }3.2 使用 request.uploadFile 上传request.uploadFile支持 multipart/form-data 格式上传可同时携带文本字段标题、描述和文件字段视频文件、封面图。关键注意事项文件路径必须位于沙箱 cache 目录且使用internal://cache/前缀推荐监听progress事件展示上传进度监听complete事件处理完成回调typescriptimport { request } from kit.BasicServicesKit; import { BusinessError } from kit.BasicServicesKit; function uploadVideo( videoPath: string, // 沙箱中的视频路径如 /data/.../cache/video.mp4 coverPath: string, // 封面图路径 title: string, desc: string, uploadUrl: string, callback: (success: boolean, msg: string) void ) { // 构建内部缓存 URI必须使用 internal://cache/ 前缀 const videoFileName videoPath.split(/).pop() || video.mp4; const videoCacheUri internal://cache/${videoFileName}; const coverCacheUri internal://cache/${coverPath.split(/).pop()}; const config: request.UploadConfig { method: POST, url: uploadUrl, header: { Content-Type: multipart/form-data }, files: [ { filename: videoFileName, name: video, uri: videoCacheUri, type: video/mp4 }, { filename: coverPath.split(/).pop() || cover.jpg, name: cover, uri: coverCacheUri, type: image/jpeg } ], data: [ { name: title, value: title }, { name: description, value: desc }, { name: timestamp, value: Date.now().toString() } ] }; request.uploadFile(getContext(this), config) .then((task: request.UploadTask) { // 监听上传进度 task.on(progress, (progress: request.UploadProgress) { const percent (progress.uploadedSize / progress.totalSize) * 100; console.info(上传进度: ${percent.toFixed(1)}%); }); // 监听完成事件 task.on(complete, () { console.info(上传完成); callback(true, 上传成功); }); }) .catch((err: BusinessError) { console.error(上传失败:, err.message); callback(false, err.message); }); }3.3 使用专业上传 SDK火山引擎对于视频点播场景火山引擎提供了 HarmonyOS NEXT 上传 SDK支持分片上传、断点续传、自动抽帧等高级功能typescriptimport { TTUploaderUtil, TTVideoUploader } from bytedance/bduploader; // 1. 初始化 SDK应用启动时执行一次 TTUploaderUtil.init(getContext(this).getApplicationContext()); // 2. 创建上传实例 const videoUploader new TTVideoUploader(); videoUploader.setPathName(videoFilePath); videoUploader.setSpaceName(your-space); videoUploader.setTopAccessKey(accessKey); videoUploader.setTopSecretKey(secretKey); videoUploader.setTopSessionToken(stsToken); // 3. 设置回调监听 const listener new UploaderVideoListener(); videoUploader.setVideoInfoListener(listener); // 4. 开始上传 await videoUploader.start(); // 监听类示例 class UploaderVideoListener implements VideoInfoListener { async onNotify(what: number, info: BDVideoInfo): Promisevoid { if (what TTVideoUploadNotifier.MsgIsComplete) { console.info(上传完成); } else if (what TTVideoUploadNotifier.MsgIsUpdateProgress) { // 进度更新 } } }四、完整实战视频发布流程将以上三部分串联一个完整的视频发布场景应包含以下步骤选择通过PhotoViewPicker让用户从相册选择视频预览使用Video组件或播放器 SDK 进行播放预览处理将视频拷贝至沙箱 cache 目录若需剪辑/压缩则在此步骤处理上传调用request.uploadFile或专业上传 SDK展示进度条完成上传成功后更新 UI释放资源完整代码框架可参考开源案例publishmultimediaupdates多媒体发布和videotrimmer视频剪辑上传已在 Gitee 鸿蒙案例库中提供。五、注意事项与最佳实践维度建议权限管理优先使用 Picker 组件避免申请敏感权限相机拍摄需动态授权ohos.permission.CAMERA性能优化大文件上传使用分片策略列表视频使用懒加载LazyForEach和缓存cachedCount沙箱路径上传时需将文件置于cache目录URI 前缀为internal://cache/播放器选型常规场景选系统Video组件加密、多清晰度、商业需求选阿里云/火山引擎 SDK错误处理务必监听onError播放和catch上传给用户友好提示