更新记录

1.0.0（2026-10-14）

• 从 uni-8266 示例项目独立出 UDP UTS 插件。
• 支持 Android/iOS UDP UTF-8、十六进制发送。
• 支持 UDP 端口侦听与停止。
• 补充 DCloud 插件市场元数据、平台配置和使用文档。

平台兼容性

uni-app(4.75)

ll-udp-tools

面向 uni-app App 的 Android/iOS UDP 插件，适合局域网设备发现、广播控制和 UDP 数据接收。

功能

• UTF-8 或十六进制 UDP 单播/广播发送。
• UDP 端口侦听，返回来源地址、来源端口、UTF-8 文本、十六进制报文和接收时间。
• Android 5.0（API 21）及以上。
• iOS 12 及以上。

安装

将本目录复制到项目的 uni_modules/ll-udp-tools，或通过 HBuilderX 导入插件。原生依赖变更后，请重新制作自定义调试基座或重新云打包。

API

import { sendUdp, startUdpListener, stopUdpListener } from '@/uni_modules/ll-udp-tools'

sendUdp

sendUdp({
  address: '255.255.255.255',
  port: 8266,
  message: 'ESP8266',
  encoding: 'utf8', // utf8 | hex；默认 utf8
  success: (res) => {},
  fail: (res) => {},
  complete: (res) => {}
})

hex 模式示例：message: '01 FF A0'。空格和换行会被忽略，报文必须由偶数个十六进制字符组成。

startUdpListener

startUdpListener({
  port: 8266,
  onMessage: (packet) => {
    console.log(packet.address, packet.port, packet.text, packet.hex, packet.receivedAt)
  },
  success: (res) => {},
  fail: (res) => {},
  complete: (res) => {}
})

同一时间插件只维护一个侦听器。再次启动会先停止旧侦听器。页面卸载、页面隐藏或不再需要接收时，应主动调用 stopUdpListener()。

stopUdpListener

stopUdpListener({
  success: (res) => {},
  complete: (res) => {}
})

返回值

成功回调：{ errCode: 0, errMsg: string }。

失败回调：{ errCode: 1910001, errMsg: string }。端口范围为 1-65535，发送地址必须为 IPv4 地址。

平台说明

Android

插件声明 INTERNET、网络状态和 Wi-Fi 状态权限。部分设备或系统版本需要用户已连接 Wi-Fi，广播接收还可能受路由器隔离策略影响。插件使用普通 UDP 单播/广播，不申请 Android 组播锁，也不支持 IP Multicast。

iOS

首次访问局域网时系统会请求本地网络权限。请在宿主 App 的隐私说明中保留本地网络用途描述。iOS 原生 UDP 实现当前只支持 IPv4 和 arm64 真机架构，不支持 iOS 模拟器；发布前请按目标设备准备对应的调试基座。

• 本插件使用普通 IPv4 UDP 单播/广播，不使用 IP Multicast，因此不需要 com.apple.developer.networking.multicast Entitlement。iOS 仅需本地网络隐私说明 NSLocalNetworkUsageDescription。

  注意事项

• 插件仅支持 App-Android 和 App-iOS，不支持 H5、小程序和 nvue。

• UDP 不保证送达、顺序或去重，业务层需要自行设计确认和重试。

• 不要在频繁渲染或短生命周期回调中重复启动侦听器。

• 插件不采集、不上传用户数据。

开源与依赖

本插件中的 UDP 原生实现随插件源码分发。插件不依赖第三方 UDP 网络库。