更新记录

1.0.0（2026-07-29）

支持app三端p2p方案，ios为普通wifi

平台兼容性

uni-app x(5.0)

uninext-peer-link

uninext-peer-link 是一个面向设备热点接入、P2P 直连和局域网调试场景的 UTS 插件，统一封装 Android、iOS、Harmony 三端的连接入口、回调结构和错误码。

适用场景

• 连接设备热点后，通过 TCP / UDP / HTTP 与设备通信
• Android / Harmony 下按设备标识尝试发起 P2P 直连
• iOS 下通过系统热点接入能力连接设备热点
• 业务层希望统一处理连接状态、错误提示和重试逻辑

当前能力概览

说明：

• Android / Harmony 的 BSSID 更接近“目标设备地址”语义，不是传统路由器 BSSID。
• Harmony 当前是 P2P 方案，不是普通 STA WiFi 切换方案。
• 如果 Harmony 普通应用无法走通 p2pConnect，建议改为“用户在系统 WiFi 页手动连接，App 只负责后续通信”。

安装与导入

插件目录：uni_modules/uninext-peer-link

import { useUninextPeerLink } from '@/uni_modules/uninext-peer-link'

const uninextPeerLink = useUninextPeerLink()

API 列表

• hasPositionPermission(): Promise<boolean>
• getCapabilities(): UninextPeerLinkCapabilities
• isWifiEnabled(): boolean
• prepare(options: UninextPeerLinkPrepareOptions): Promise<void>
• connect(options: UninextPeerLinkConnectOptions): Promise<void>
• disconnect(options: UninextPeerLinkDisconnectOptions): Promise<void>
• getConnectionInfo(options: UninextPeerLinkGetConnectionOptions): Promise<void>

推荐接入流程

1. 调用 getCapabilities() 判断当前平台支持情况
2. 调用 prepare() 检查当前连接能力和网络上下文
3. 调用 connect() 发起连接
4. 在成功回调里再启动设备通信
5. 页面回前台或步骤切换时调用 getConnectionInfo() 刷新状态

快速开始

1. 检查位置权限需求

const hasPositionPermission = await uninextPeerLink.hasPositionPermission()
console.log('has position permission', hasPositionPermission)

说明：

• Android / Harmony 某些 WiFi / P2P 能力依赖位置权限或系统等价授权
• iOS 是否需要额外位置权限，取决于你的业务是否还要读取更详细的系统网络信息

2. 检查平台能力

const capabilities = uninextPeerLink.getCapabilities()
console.log('peer link capabilities', JSON.stringify(capabilities))

返回字段：

3. 获取 WiFi 开关状态

const wifiEnabled = uninextPeerLink.isWifiEnabled()
console.log('connection enabled', wifiEnabled)

说明：

• Android / Harmony 返回系统 WiFi 或当前能力层面的开关状态
• iOS 公开原生 API 无法稳定获取系统 WiFi 开关真值，当前返回的是插件内部基于连接信息推导的近似状态

4. 连接前准备

uninextPeerLink.prepare({
  success: (res) => {
    console.log('prepare success', JSON.stringify(res))
  },
  fail: (err) => {
    console.log('prepare fail', JSON.stringify(err))
  },
  complete: (res) => {
    console.log('prepare complete', JSON.stringify(res))
  }
})

5. 发起连接

uninextPeerLink.connect({
  SSID: 'ZEEHO-DASHBOARD',
  password: '12345678',
  BSSID: null,
  hiddenSSID: false,
  joinOnce: true,
  timeoutMillis: 15000,
  bindProcessToNetwork: true,
  success: (res) => {
    console.log('connect success', JSON.stringify(res))
  },
  fail: (err) => {
    console.log('connect fail', JSON.stringify(err))
  },
  complete: (res) => {
    console.log('connect complete', JSON.stringify(res))
  }
})

6. 获取连接信息

uninextPeerLink.getConnectionInfo({
  success: (res) => {
    console.log('connection info', JSON.stringify(res))
  },
  fail: (err) => {
    console.log('connection info fail', JSON.stringify(err))
  }
})

7. 断开连接

uninextPeerLink.disconnect({
  SSID: 'ZEEHO-DASHBOARD',
  success: (res) => {
    console.log('disconnect success', JSON.stringify(res))
  },
  fail: (err) => {
    console.log('disconnect fail', JSON.stringify(err))
  }
})

参数说明

connect(options)

prepare(options)

disconnect(options)

getConnectionInfo(options)

hasPositionPermission()

返回值：

说明：

• 这是一个快捷检查方法，便于业务层在连接前决定是否先引导用户授权
• 具体是否必须依赖位置权限，仍受平台版本、系统策略和插件底层实现影响

回调结构

成功回调

所有成功回调统一返回 UninextPeerLinkBaseSuccess：

wifi 字段说明：

失败回调

失败回调返回 IUninextPeerLinkError：

错误码表

平台差异与限制

Android

• 当前实现走 WiFi Direct / P2P，适合设备直连。
• BSSID 建议传设备地址。
• Android 10+ 下 WiFi / 扫描 / P2P 相关能力通常还要结合位置权限一起判断。
• 页面连接成功后再访问设备接口，避免系统还未切网完成。

iOS

• 当前走 NEHotspotConfiguration，由系统接管接入。
• joinOnce 在 iOS 上意义最明确。
• BSSID、ipV4 等字段可能因为系统限制返回 null。

Harmony

• 当前实现基于 @ohos.wifiManager 的 P2P 能力。
• BSSID 表示目标 P2P 设备地址。
• getCurrentGroup() 能成功不代表最终一定连通，仍需结合 getConnectionInfo() 判断。
• 普通三方应用在部分机型或系统版本上可能无法完整获得 P2P 管理权限。
• 如果 p2pConnect 长时间无回调，优先检查系统能力、权限级别和机型开放范围。
• 如果设备同时在普通 WiFi 列表可见，Harmony 上可优先考虑“系统手动连接 + App 后续通信”的替代方案。

权限与配置建议

Android

Android 端当前实现基于 WifiP2pManager。这里要同时满足两件事：

• 包内已声明所需权限
• 用户在运行时已授权相关权限

配置位置

推荐在项目根目录 manifest.json 的 app-android.distribute.permissions 中声明：

{
  "app-android": {
    "distribute": {
      "permissions": [
        "<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"/>",
        "<uses-permission android:name=\"android.permission.NEARBY_WIFI_DEVICES\"/>",
        "<uses-permission android:name=\"android.permission.ACCESS_WIFI_STATE\"/>",
        "<uses-permission android:name=\"android.permission.CHANGE_WIFI_STATE\"/>",
        "<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\"/>",
        "<uses-permission android:name=\"android.permission.CHANGE_NETWORK_STATE\"/>",
        "<uses-permission android:name=\"android.permission.INTERNET\"/>",
        "<uses-feature android:name=\"android.hardware.wifi.direct\" android:required=\"false\" />"
      ]
    }
  }
}

推荐权限说明

运行时授权说明

插件内部会在需要时申请：

• ACCESS_FINE_LOCATION
• NEARBY_WIFI_DEVICES

但前提是这些权限已经打进安装包。也就是说：

• 只写运行时代码、不配 manifest.json，系统不会正常授权
• 只配 manifest.json、用户拒绝授权，扫描和连接依然可能失败

额外说明

• 某些 ROM 要求系统“定位服务”总开关本身也处于开启状态。
• uses-feature 建议设置 required="false"，避免不支持 WiFi Direct 的设备在商店直接被过滤。
• 如果项目还涉及传统 WiFi 扫描或更复杂的网络状态读取，建议保留 ACCESS_WIFI_STATE、CHANGE_WIFI_STATE、ACCESS_NETWORK_STATE。

iOS

iOS 端当前实现依赖 NetworkExtension.framework，并且区分两类配置：

• entitlement / capability
• Info.plist 隐私说明

插件内已包含的 capability

插件目录 utssdk/app-ios/UTS.entitlements 已声明：

• com.apple.developer.networking.wifi-info
• com.apple.developer.networking.HotspotConfiguration

这两项分别对应：

• 读取当前 WiFi 相关信息的 capability
• 使用 NEHotspotConfiguration 发起热点接入的 capability

工程侧建议补充的 Info.plist

推荐在项目根目录新增 Info.plist，至少补下面内容：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>NSLocalNetworkUsageDescription</key>
  <string>用于连接设备热点后访问局域网设备服务</string>
  <key>NSLocationWhenInUseUsageDescription</key>
  <string>用于识别当前 WiFi 信息并辅助设备连接</string>
</dict>
</plist>

配置项说明

额外说明

• 插件带有 entitlement，不等于 Apple 开发者签名能力已经在你的目标环境中完全可用。
• 真机上如果拿不到 SSID、BSSID 或 ipV4，不一定是插件错误，很多情况是 iOS 公开 API 的系统限制。
• joinOnce 只影响接入策略，不替代 capability、签名和隐私说明配置。

Harmony

Harmony 端建议把“权限声明”和“系统能力开放范围”分开理解。当前插件使用 @ohos.wifiManager 的 P2P 能力，常见卡点不只是权限，还包括机型和系统策略。

配置位置

推荐在项目根目录维护：harmony-configs/entry/src/main/module.json5

权限声明放在：module.requestPermissions

示例：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.LOCATION",
        "usedScene": {
          "when": "inuse"
        },
        "reason": "$string:EntryAbility_label"
      },
      {
        "name": "ohos.permission.APPROXIMATELY_LOCATION",
        "usedScene": {
          "when": "inuse"
        },
        "reason": "$string:EntryAbility_label"
      }
    ]
  }
}

推荐权限说明

为什么建议定位权限成对配置

• Harmony 文档里定位类权限通常建议一起声明
• WiFi / 周边发现一类场景，经常会走到位置授权链路
• 少配其中一个时，更容易出现“能编译、但真机行为不稳定”的问题

还需要检查的系统能力

推荐至少关注：

• module.json5 中的 WiFi / 网络权限声明
• syscap.json 中的 SystemCapability.Communication.WiFi.P2P

额外说明

• 系统能力声明不等于普通应用一定能获得完整 P2P 管理权限。
• 如果目标接口要求系统应用或企业应用权限，普通应用即使声明了权限也可能无法生效。
• 某些机型上 startDiscoverDevices()、getCurrentGroup()、p2pConnect() 可能表现为超时、无回调或字段不完整。

三端对照表

接入建议

• 先调用 getCapabilities()，再决定页面是否展示连接入口
• 业务层保存 SSID + BSSID，便于后续重连
• 将“WiFi 未开启”“权限不足”“连接超时”“P2P 忙碌”分别提示给用户
• Harmony 上不要只看 getCurrentGroup，要以 getConnectionInfo().wifi.connected 和设备通信结果一起判断
• 自动重连前先做 prepare()，避免旧状态残留

示例文档

更完整的业务接入示例见 uni_modules/uninext-peer-link/使用示例.md。