投屏（ScreenCast）使用指导
投屏会话组件 - 管理鸿蒙设备的投屏与媒体播放控制。 鸿蒙独有组件，基于 AVSession / Cast API。
运行前提与搭建步骤
这些案例在包含该组件的鸿蒙 AI 伴侣或 HAP 中运行。Android 侧是供网页编辑器生成积木的声明，不能用安卓伴侣验证鸿蒙系统能力。
- 在设计器拖入
ScreenCast，保留名称ScreenCast1；拖入案例涉及的按钮、文本输入框以及一个标签标签1，按代码中的名称重命名。 - 根据下面的业务说明准备素材、JSON 或系统目标。案例中的按钮代表分步操作，先等初始化、加载或创建成功，再执行下一步。
- 接住完成事件与错误事件，将原始 JSON 或错误显示在标签。先确认原始结果，再编写业务处理。
先完成案例一并选择实际可用的投屏设备，再执行案例二。会话激活与远端开始播放不是同一结果，观察输出设备和播放状态。
案例一：创建并激活投屏会话
各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。
when 按钮_创建.Click() {
ScreenCast1.CreateSession()
}
when ScreenCast1.SessionCreated() {
ScreenCast1.ActivateSession()
}
when ScreenCast1.SessionActivated() {
标签1.Text = "会话已激活"
}
when ScreenCast1.CastError(错误信息) {
标签1.Text = 错误信息
}
案例二：播放媒体并停止
when 按钮_播放.Click() {
ScreenCast1.SetMediaMetadata("演示视频", "演示", 文本输入框_媒体地址.Text)
ScreenCast1.StartCastPlayback()
}
when 按钮_停止.Click() {
ScreenCast1.StopCastPlayback()
}
when ScreenCast1.PlaybackStateChanged(状态) {
标签1.Text = 状态
}
参数与返回值速查
JSON 参数是文本，不能直接传字典；需要字典时可用 Web 客户端的 JSON 解码积木转换返回文本。完整默认值与类型见组件参考。
| 方法或事件 | 参数与用途 |
|---|---|
激活会话（ActivateSession） |
无参数。激活已创建的投屏会话，连接到投屏设备。 |
创建会话（CreateSession） |
无参数。创建一个新的投屏会话。 |
获取输出设备（GetOutputDevice） |
无参数。获取当前投屏输出设备的信息，返回JSON格式。 |
发送投屏指令（命令）（SendCastCommand） |
命令：文本。向投屏设备发送自定义控制命令，返回命令执行结果。 |
设置媒体信息（标题，艺术家，媒体地址）（SetMediaMetadata） |
标题：文本, 艺术家：文本, 媒体地址：文本。设置投屏媒体的元数据信息，包括标题、艺术家和媒体地址。 |
开始投屏播放（StartCastPlayback） |
无参数。开始在投屏设备上播放媒体内容。 |
停止投屏播放（StopCastPlayback） |
无参数。停止投屏设备上的媒体播放。 |
投屏设备变化时（设备信息）（CastDeviceChanged） |
设备信息：文本。投屏目标设备发生变化时触发。 |
投屏出错时（错误信息）（CastError） |
错误信息：文本。投屏过程中发生错误时触发，返回错误信息。 |
媒体信息变化时（MediaMetadataChanged） |
无参数。媒体元数据发生变化时触发。 |
播放状态变化时（状态）（PlaybackStateChanged） |
状态：文本。媒体播放状态发生变化时触发。 |
会话已激活时（SessionActivated） |
无参数。投屏会话激活完成时触发。 |
会话已创建时（SessionCreated） |
无参数。投屏会话创建完成时触发。 |
会话已销毁时（SessionDestroyed） |
无参数。投屏会话被销毁时触发。 |
常见问题与验收
| 现象 | 检查与预期 |
|---|---|
| 安卓运行没有结果 | 切换到鸿蒙伴侣或 HAP；Android 的声明不会执行该鸿蒙系统能力。 |
| 方法已调用但界面没变化 | 生成 JSON 的方法只是构建数据；按业务流程交给渲染、启动或同步入口，不能将数据生成当成系统操作完成。 |
| 初始化、权限或设备失败 | 记录错误事件，确认系统服务、授权、目标应用或设备可用；只在成功事件后继续下一步。 |
| JSON 解析失败 | 使用上一组件的原始输出，检查引号和字段类型；空对象用于默认模板演示，不能代替真实目标信息。 |
| 两个案例验收 | 每个按钮单独操作一次，核对对应返回或事件；输入错误目标或取消操作时查看失败事件，不应显示成功提示。 |
扫码添加客服咨询
