更新记录

1.0.0（2026-05-31）

-UTS多屏异显异触-主副屏相互通讯 安卓收银机 POS 机 UTS 插件

平台兼容性

uni-app(4.18)

ly028-Screen 多屏异显异触 · 主副屏相互通讯

适用于安卓收银机、POS 机等需要多块屏幕独立显示、独立触控、相互通讯的场景。

本插件为 UTS 插件，支持 HBuilderX 云打包和自定义基座调试。 旧版原生插件请移步：https://ext.dcloud.net.cn/plugin?id=6739

📦 功能概览

• 打开/关闭副屏 WebView，支持多块屏幕同时显示不同内容
• 主屏 → 指定副屏 / 所有副屏 发送数据
• 副屏 → 主屏 发送数据（通过 lyjsdk 桥接）
• 副屏 ↔ 副屏 相互发送消息
• 屏幕热插拔检测（HDMI 拔插自动响应）
• 断线重连：屏幕重新接入后自动恢复上次页面
• 悬浮窗权限自动申请，授权后自动继续操作
• 列出所有可用屏幕，按 ID 选择操作

🏗️ 架构

                        ┌─────────────────────┐
                        │    你的 App 页面      │
                        │   (uni-app Vue/JS)   │
                        └──────────┬──────────┘
                                   │
                                   ▼
                        ┌─────────────────────┐
                        │   ly028-Screen 插件   │
                        │    （通讯中枢）        │
                        └──┬────┬────┬────────┘
                           │    │    │
              ┌────────────┘    │    └────────────┐
              ▼                 ▼                 ▼
        ┌──────────┐     ┌──────────┐     ┌──────────┐
        │  副屏 1   │     │  副屏 2   │     │  副屏 3   │
        │  WebView  │     │  WebView  │     │  WebView  │
        │  菜单/广告 │     │  支付码   │     │  其他内容  │
        │  独立触控  │     │  独立触控  │     │  独立触控  │
        └──────────┘     └──────────┘     └──────────┘

数据流向

主屏 → 副屏:  sendDataToSecondScreen({ displayId: 1, ... })
副屏 → 主屏:  lyjsdk.sendToFirstScreen(data)
副屏 → 副屏:  lyjsdk.sendToFirstScreen({ target: 2, ... })

🔄 新老插件对比

调用方式对比

// ---- 老插件（原生） ----
var LySDK = uni.requireNativePlugin('LY028-NativeSdk')
LySDK.openSecondScreen({ url: 'http://www.baidu.com' }, callback)
LySDK.sendDataToSecondScreen({ ... }, callback)
LySDK.closeSecondScreen({ ... }, callback)

// ---- 本插件（UTS） ----
import { openSecondScreen, closeSecondScreen, sendDataToSecondScreen,
         hasMultiScreen, listScreens, onReceiveData } from '@/uni_modules/ly028-Screen'

openSecondScreen({ url: 'http://www.baidu.com' }, callback)           // 自动选择副屏
openSecondScreen({ url: 'http://...', displayId: 1 }, callback)       // 指定副屏
sendDataToSecondScreen({ msg: 'hello' }, callback)                     // 发到所有副屏
sendDataToSecondScreen({ displayId: 1, msg: 'hello' }, callback)       // 发到指定副屏
closeSecondScreen({}, callback)                                        // 关闭所有
closeSecondScreen({ displayId: 1 }, callback)                          // 关闭指定副屏
onReceiveData((event) => { console.log('收到:', event.data) })          // 接收副屏数据
listScreens((res) => { console.log('可用屏幕:', res.data) })            // 列出所有屏幕

📱 单机调试（无物理副屏）

在 一台手机上 即可模拟双屏效果：

方法一：开发者选项模拟副屏（推荐）

设置 → 开发者选项 → 模拟辅助显示设备 → 选择 720p 或 1080p

开启后手机屏幕顶部会出现状态栏图标，表示已启用模拟副屏。此时调用本插件即可在模拟副屏上显示 WebView 内容。

注意：部分 ROM（如 MIUI）需要额外开启「USB 调试（安全设置）」才能使用模拟副屏。

方法二：外接显示器/投屏

• 通过 Type-C 转 HDMI 连接外接显示器
• 或使用 无线投屏（Miracast，部分设备支持）
• 连接后系统会自动识别为副屏，插件的 listScreens() 即可检测到

检测屏幕是否可用

listScreens((res) => {
    if (res.code === 0) {
        console.log('可用副屏:', res.data) // 如 "[28]"
    } else if (res.code === 401) {
        console.log('需要悬浮窗权限')
    }
})

📖 API 文档

状态码

openSecondScreen(options, callback)

打开副屏 WebView。

// 自动选第一个可用副屏
openSecondScreen({ url: 'http://www.baidu.com' }, (res) => {
    console.log(res.code, res.msg)
})
// 指定 displayId
openSecondScreen({ url: 'http://...', displayId: 1 }, callback)

closeSecondScreen(options, callback)

关闭副屏。

closeSecondScreen({}, callback)          // 关闭所有
closeSecondScreen({ displayId: 1 }, callback)  // 关闭指定

sendDataToSecondScreen(options, callback)

向副屏发送数据。

// 发到所有副屏
sendDataToSecondScreen({ msg: '你好副屏!' }, callback)
// 发到指定副屏
sendDataToSecondScreen({ displayId: 1, msg: '只发给屏1' }, callback)

hasMultiScreen(callback)

检测是否有可用副屏。

hasMultiScreen((res) => {
    if (res.code === 0) {
        console.log('有副屏:', res.data) // "true"
    } else if (res.code === 404) {
        console.log('无副屏')
    }
})

listScreens(callback)

列出所有可用副屏，返回 JSON 数组。

listScreens((res) => {
    if (res.code === 0 && res.data) {
        const ids = JSON.parse(res.data) // [28, 29]
        ids.forEach(id => console.log('屏幕:', id))
    }
})

onReceiveData(callback)

注册副屏数据接收监听（副屏通过 lyjsdk.sendToFirstScreen(data) 发送时触发）。

onReceiveData((event) => {
    console.log('收到副屏数据:', event.data)
})

兼容旧版方式（老插件迁移时使用）：

plus.globalEvent.addEventListener('receiveData', (e) => {
    console.log('收到:', e)
})

🔐 权限说明

本插件需要 SYSTEM_ALERT_WINDOW（悬浮窗权限）才能在副屏上显示内容。

权限申请流程全自动：

调用任意需要权限的方法
  → 没有权限?
    → 保存当前操作（记住你在做什么）
    → 跳转系统设置页
    → 用户授权后返回 app
      → 自动检测权限已获取
      → 继续执行之前保存的操作

用户只需要在系统设置页点击「允许」，其他一切自动完成。

❓ 热点问答

Q：老项目怎么迁移？

老项目用的是 uni.requireNativePlugin('LY028-NativeSdk')，迁移到本插件只需三步：

1. 从 manifest.json 的 nativePlugins 中移除旧插件配置
2. 安装本插件到 uni_modules
3. 将代码中的 uni.requireNativePlugin 改为 import { ... } from '@/uni_modules/ly028-Screen'

详见上方「新老插件对比」和「调用方式对比」。

Q：支持 iOS 吗？

目前仅支持 Android。iOS 不支持多屏异显异触。

Q：最多支持几块副屏？

取决于设备硬件。Android 通过 DisplayManager 枚举，支持多块副屏同时连接。每块副屏独立显示不同内容、独立触控。

Q：屏幕 ID 是固定的吗？

不是。displayId 由系统在屏幕连接时分配，每次连接可能不同。请通过 listScreens() 获取当前可用的屏幕列表和 ID。

Q：副屏上的 WebView 支持触控吗？

支持。每块副屏有独立的触控事件响应，与主屏互不干扰。

Q：副屏断开再连接会怎样？

插件会自动检测屏幕插入事件，如果该屏幕之前打开过页面，会自动恢复显示上次的 URL，无需手动操作。

Q：本地网页怎么在副屏打开？

使用 plus.io.convertLocalFileSystemURL() 转换本地路径：

const url = plus.io.convertLocalFileSystemURL('/hybrid/html/index.html')
openSecondScreen({ url }, callback)

Q：云打包需要配置什么？

不需要额外配置。本插件是 UTS 插件，HBuilderX 云打包会自动编译 UTS 代码。只需要在 manifest.json 中确保权限声明：

"permissions": [
    "<uses-permission android:name=\"android.permission.INTERNET\"/>",
    "<uses-permission android:name=\"android.permission.SYSTEM_ALERT_WINDOW\"/>"
]

🔗 相关链接

• 新版 UTS 插件市场: https://ext.dcloud.net.cn/plugin?id=28155
• 旧版原生插件（非 UTS）: https://ext.dcloud.net.cn/plugin?id=6739
• 技术支持 QQ: 277407835

📱 扫码体验