更新记录

1.0.7（2026-05-22） 下载此版本

修改参数副屏发送主屏，message改为data字段，可接受字符串、对象、json

1.0.6（2026-05-21） 下载此版本

更新文档

1.0.5（2026-05-20） 下载此版本

优化副屏未检测到的返回提示信息

查看更多

平台兼容性

uni-app(4.85)

Vue2 Vue3 Vue3插件版本 Chrome Safari app-vue app-vue插件版本 app-nvue Android Android插件版本 iOS 鸿蒙
- √ 1.0.0 - - √ 1.0.0 - 5.0 1.0.0 - -
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
- - - - - - - - - - - -

uni-app x(4.85)

Chrome Safari Android Android插件版本 iOS 鸿蒙 微信小程序
- - 5.0 1.0.0 - - -

dual-screen

UTS插件 双屏管理插件，支持双屏设备的副屏显示、主副屏消息通信、显示器变化监听等功能。

⚠️ 若需要原生语言 aar 插件包，请留言。

常见使用场景：

  • 会议演示：主屏显示控制界面，副屏显示演示内容
  • 广告展示：主屏用于交互操作，副屏循环播放广告内容
  • 多屏游戏：主屏显示游戏操作，副屏显示游戏地图或数据统计
  • 零售展示：主屏用于商品选择，副屏展示商品详情或促销信息
  • 医疗监护：主屏显示控制界面，副屏实时显示患者生命体征数据

功能特性

  • 副屏显示：支持 URL、HTML 内容、本地资源文件三种模式
  • 主屏 → 副屏消息通信
  • 副屏 → 主屏消息通信
  • 显示器变化监听（连接/断开/分辨率变化）
  • 副屏加载完成回调

安装

下载导入项目即可

使用方法

引入插件

import * as dualScreen from "@/uni_modules/dual-screen";

初始化

onLoad(() => {
  // 注册事件监听
  dualScreen.on("onDisplayChange", handleDisplayChange);
  dualScreen.on("onSecondaryScreenMessage", handleSecondaryScreenMessage);
  dualScreen.on("onPrimaryScreenMessage", handlePrimaryScreenMessage);
  dualScreen.on("onSecondaryScreenLoaded", handleSecondaryScreenLoaded);
});

onUnload(() => {
  // 移除事件监听
  dualScreen.off("onDisplayChange");
  dualScreen.off("onSecondaryScreenMessage");
  dualScreen.off("onPrimaryScreenMessage");
  dualScreen.off("onSecondaryScreenLoaded");
});

API 方法

showSecondaryScreen(options)

显示副屏内容，支持三种内容来源：URL、HTML 内容、本地资源文件。

参数

参数 类型 说明
url string 网络 URL 地址
html string HTML 内容字符串
asset string 本地资源路径（相对路径）

返回结果

属性 类型 说明
code string 结果状态码
message string 结果描述信息
displayId number 副屏显示器 ID

示例

// 方式一：加载网络 URL
const result1 = await dualScreen.showSecondaryScreen({
  url: "https://example.com",
});

// 方式二：加载 HTML 内容
const result2 = await dualScreen.showSecondaryScreen({
  html: "<html><body><h1>Hello</h1></body></html>",
});

// 方式三：加载本地资源html文件，相对路径，目录在 hybrid 下，无需加hybrid
const result3 = await dualScreen.showSecondaryScreen({
  asset: "html/index.html",
});

hideSecondaryScreen()

隐藏副屏，关闭副屏显示器上的内容显示。

返回结果

属性 类型 说明
code string 结果状态码
message string 结果描述信息

示例

await dualScreen.hideSecondaryScreen();

sendMessageToSecondary(options)

向副屏发送消息，副屏页面可通过 window.receiveMessageFromPrimary 或 window.dualScreen.onPrimaryMessage 接收。

参数

参数 类型 说明
data string object 消息内容

返回结果

属性 类型 说明
code string 结果状态码
data string 结果描述信息

示例

const result = await dualScreen.sendMessageToSecondary({
  data: "Hello Secondary Screen",
});
if (result.code === "success") {
  console.log("消息发送成功");
}

getDisplays()

获取所有显示器列表信息。

返回结果

属性 类型 说明
code string 结果状态码
displays DisplayInfo[] 显示器数组

示例

const displays = dualScreen.getDisplays();
displays.forEach((display) => {
  console.log(
    `显示器: ${display.name}, ID: ${display.displayId}, 是否主屏: ${display.isPrimary}, 分辨率: ${display.width}x${display.height}`,
  );
});

事件说明

事件名 说明 回调参数
onDisplayChange 显示器变化 { event: "displayChange", displays: DisplayInfo[] }
onSecondaryScreenMessage 收到副屏消息 { data: string, source: "secondary" }
onPrimaryScreenMessage 收到主屏消息 { data: string, source: "secondary" }
onSecondaryScreenLoaded 副屏加载完成 { url: string, success: boolean }

DisplayInfo 类型

属性 类型 说明
displayId number 显示器 ID
name string 显示器名称
isPrimary boolean 是否为主屏
width number 显示器宽度（像素）
height number 显示器高度（像素）
refreshRate number 刷新率

副屏页面与主屏通信

副屏 → 主屏：发送消息

// 副屏页面中
function sendToPrimary(message) {
  if (window.uniWebView && window.uniWebView.replyMessage) {
    window.uniWebView.replyMessage(
      JSON.stringify({
        data: "发给主屏的消息" + message,
      }),
    );
  }
}

副屏 → 主屏：接收消息

副屏页面需要定义全局函数 window.receiveMessageFromPrimary 来接收主屏发送的消息：

// 副屏页面中
window.receiveMessageFromPrimary = function (message) {
  console.log("收到主屏消息:", message);
  // 处理消息...
};

或者使用 window.dualScreen.onPrimaryMessage：

// 副屏页面中
window.dualScreen = window.dualScreen || {};
window.dualScreen.onPrimaryMessage = function (message) {
  console.log("收到主屏消息:", message);
  // 处理消息...
};

注意事项

  1. 仅支持 Android 平台
  2. 需要设备支持副屏显示（通过 HDMI、MiraCast 等连接外接显示器）
  3. 副屏页面需要在主屏页面初始化插件并注册事件监听后再打开
  4. 建议在 onLoad 中注册事件，在 onUnload 中移除事件监听

开发文档

隐私、权限声明

1. 本插件需要申请的系统权限列表：

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

无

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

许可协议

MIT协议
评论列表 撰写评论 向官方投诉

暂无用户评论。