更新记录

1.0.3（2026-07-09） 下载此版本

• 新增 onUserSubStreamAvailable 回调，支持监听远端屏幕共享（辅流）发布/取消
• 新增 setRemoteRenderParams，辅流可用 TRTCVideoFillMode_Fit 完整显示（允许黑边、不裁剪）
• 支持通过 startRemoteView(userId, TRTCVideoStreamTypeSub, viewId) 订阅并渲染屏幕共享画面
• TrtcRemoteView 支持 embedWidth / embedHeight，避免 XComponent 超出容器被裁切
• 业务参考：pages-learningPlan/live/index.vue 屏幕共享三栏布局

1.0.2（2026-07-07） 下载此版本

• 修复 destroy 时未释放摄像头导致快速重进本地预览黑屏

1.0.0（2026-07-07） 下载此版本

1.0.0（2026-07-06）

• 初始版本：封装 @tencentcloud/liteavsdk_professional
• 支持 defineNativeEmbed + XComponent 视频渲染
• 提供 TrtcCloud 对齐 API 与跨平台 services/trtc 入口

平台兼容性

uni-app(4.45)

uni-app x(4.45)

trtc-harmony

鸿蒙端 TRTC 实时音视频 UTS 插件，封装 @tencentcloud/liteavsdk_professional，通过 defineNativeEmbed 嵌入 XComponent 实现视频渲染。

依赖

• HBuilderX >= 4.62（支持鸿蒙原生组件 embed）
• 鸿蒙真机（TRTC 不支持模拟器）

首次编译时 HBuilderX 会根据 utssdk/app-harmony/config.json 自动拉取 ohpm 依赖。若版本号失效，可在 腾讯云 SDK 下载页 查看最新版本并更新 config.json。

目录结构

trtc-harmony/
├── components/
│   ├── trtc-local-view/    # 本地视频 embed 组件
│   └── trtc-remote-view/   # 远端视频 embed 组件
└── utssdk/app-harmony/
    ├── config.json         # ohpm 依赖
    ├── module.json5        # 权限声明
    ├── index.uts           # TRTC API 封装
    ├── trtc-video-view.ets # XComponent + defineNativeEmbed
    └── embed-init.uts      # 注册原生组件

使用示例

<script setup>
import { ref, onMounted } from 'vue'
import { createTrtcInstance, destroyTrtcInstance, TRTCAppScene, TRTCVideoStreamType } from '@/services/trtc'
import TrtcLocalView from '@/uni_modules/trtc-harmony/components/trtc-local-view/trtc-local-view.vue'
import TrtcRemoteView from '@/uni_modules/trtc-harmony/components/trtc-remote-view/trtc-remote-view.vue'
import { requestHarmonyUserPermissions, HARMONY_PERMISSION_CAMERA, HARMONY_PERMISSION_MICROPHONE } from '@/uni_modules/harmony-permissions'

const trtc = ref(null)
const localViewId = 'trtc_local_1'
const remoteViewId = 'trtc_remote_1'

onMounted(async () => {
  // #ifdef APP-HARMONY
  await new Promise<void>((resolve) => {
    requestHarmonyUserPermissions([HARMONY_PERMISSION_CAMERA, HARMONY_PERMISSION_MICROPHONE], (ok) => resolve())
  })
  // #endif

  trtc.value = createTrtcInstance()
  trtc.value.on('onEnterRoom', (result) => {
    if (result > 0) {
      trtc.value.startLocalPreview(true, localViewId)
      trtc.value.startLocalAudio()
    }
  })
  trtc.value.enterRoom({ sdkAppId, userId, userSig, roomId }, TRTCAppScene.TRTCAppSceneVideoCall)
})

onUnload(() => {
  trtc.value?.exitRoom()
  destroyTrtcInstance()
})
</script>

<template>
  <!-- #ifdef APP-HARMONY -->
  <TrtcLocalView :view-id="localViewId" />
  <TrtcRemoteView :view-id="remoteViewId" :user-id="remoteUserId" />
  <!-- #endif -->
</template>

支持的事件

屏幕共享（辅流）

当老师端开启屏幕共享时，会收到 onUserSubStreamAvailable 事件。此时需用 辅流类型 订阅远端画面，并与主流（摄像头）使用不同的 viewId：

import { TRTCVideoStreamType } from '@/services/trtc'

const screenShareUserId = ref('')
const screenShareViewId = computed(() =>
  screenShareUserId.value ? `${screenShareUserId.value}_sub_harmony` : '',
)

trtc.value.on('onUserSubStreamAvailable', async ({ userId, available }) => {
  if (available) {
    screenShareUserId.value = userId
    await nextTick()
    // Fit：完整显示屏幕内容，短边留黑边，不裁剪
    trtc.value.setRemoteRenderParams?.(
      userId,
      TRTCVideoStreamType.TRTCVideoStreamTypeSub,
      { fillMode: TRTCVideoFillMode.TRTCVideoFillMode_Fit },
    )
    trtc.value.startRemoteView(
      userId,
      TRTCVideoStreamType.TRTCVideoStreamTypeSub,
      screenShareViewId.value,
    )
    return
  }

  if (screenShareUserId.value === userId) {
    trtc.value.stopRemoteView(userId, TRTCVideoStreamType.TRTCVideoStreamTypeSub)
    screenShareUserId.value = ''
  }
})

模板中需为辅流单独挂载 TrtcRemoteView：

<TrtcRemoteView
  v-if="screenShareUserId"
  :view-id="screenShareViewId"
  :user-id="screenShareUserId"
  :embed-width="screenSharePanelWidth"
  :embed-height="screenSharePanelHeight"
/>

辅流建议使用 TRTCVideoFillMode_Fit（完整显示，可有黑边），避免 Fill 模式裁剪屏幕内容。

流类型说明：

业务示例： 伴学直播间 pages-learningPlan/live/index.vue 在收到辅流后切换为三栏布局——左上本地视频、左下老师视频、右侧屏幕共享。

修改 utssdk/app-harmony/index.uts 后需重新编译鸿蒙原生工程才能生效。

注意事项

1. viewId 必须与 startLocalPreview / startRemoteView 传入的 id 完全一致。
2. 主流与辅流须使用不同 viewId，避免 XComponent 渲染冲突。
3. defineNativeEmbed 标签名 trtcvideoview 须小写。
4. 麦克风/摄像头权限建议通过 harmony-permissions 插件动态申请后再调用 TRTC 接口。