Flutter upnp_client 组件鸿蒙适配：跨设备发现与投屏控制

2.2 权限与网络环境

在鸿蒙工程的 module.json5 中，需要根据具体业务开启如下权限：

{
  "module": {
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" },
      { "name": "ohos.permission.GET_WIFI_INFO" }
    ]
  }
}

⚠️ 注意：部分鸿蒙真机（尤其是企业版平板）默认禁用了 UDP 多播发现，需要在系统设置或特定的 DeviceManager API 中确认当前局域网是否有防火墙隔离。

三、核心 API / 组件详解

3.1 核心类：DeviceDiscoverer

这是发现流程的起点。

3.2 基础实战：在鸿蒙端搜索所有设备

import 'package:upnp_client/upnp_client.dart';

void startHarmonyDiscovery() async {
  final discoverer = DeviceDiscoverer();
  print("正在鸿蒙网络环境下扫描设备...");
  // 监听发现流
  discoverer.discoverDevices().listen((device) async {
    print("发现新设备：${device.friendlyName}");
    print("设备地址：${device.urlBase}");
    // 获取更详细的描述 (XML)
    final profile = await device.getActualDevice();
    print("制造商：${profile.manufacturer}");
  });
}

3.3 高级定制：控制 DLNA 投屏器播放

如果你正在开发一款鸿蒙端的视频 App，可以通过此方法将内容投射到电视。

import 'package:upnp_client/upnp_client.dart';

Future<void> harmonyCast(Device device, String videoUrl) async {
  // 查找 AVTransport 服务
  final service = await device.getService("urn:schemas-upnp-org:service:AVTransport:1");
  if (service != null) {
    // 执行 SetAVTransportURI 动作
    await service.invokeAction("SetAVTransportURI", {
      "InstanceID": "0",
      "CurrentURI": videoUrl,
      "CurrentURIMetaData": ""
    });
    // 执行 Play 动作
    await service.invokeAction("Play", {"InstanceID": "0", "Speed": "1"});
    print("鸿蒙投屏指令已发送！");
  }
}

四、典型应用场景

4.1 场景一：鸿蒙智能家居生态自动关联

利用鸿蒙的分布式能力，配合 UPnP 自动扫描附近所有智能灯泡或网关。

void scanHomeDevices() {
  final disco = DeviceDiscoverer();
  disco.discoverDevices(type: "urn:schemas-upnp-org:device:BinaryLight:1").listen((light) {
    // 自动加入设备列表
    bindDeviceToHarmonyId(light);
  });
}

4.2 场景二：鸿蒙本地文件预览并发现 NAS 存储

在系统级文件管理器内部，自动发现并挂载支持 UPnP 的存储服务器。

4.3 场景三：鸿蒙办公演示——发现投影仪

一键投屏 PPT 的核心后盾。

五、OpenHarmony 平台适配挑战

5.1 UDP 多播包丢包与重发

在鸿蒙设备移动或 Wi-Fi 信号不稳时，单次多播发送可能无法发现所有设备。

适配策略：

1. 设置定时器重试：手动触发 discovery 逻辑多次，每次间隔 2 秒。
2. 动态超时：根据鸿蒙端检测到的 Wi-Fi 质量（RSSI），动态调整等待响应的超时时间。

5.2 大量 XML 解析导致的 UI 阻塞

部分 UPnP 设备的描述文件（description.xml）长达几千行且层级复杂。在低配鸿蒙手表上解析此类文件可能导致界面卡顿。

解决方案：

1. 分时解析：只拉取基础 Header，业务需要时再通过 URL 获取完整明细。
2. 利用 Isolate：将 XML 字符串传回后台 Worker 线程进行结构化转换。

六、综合实战演示：开发一个'鸿蒙跨平台设备发现大屏'

下面的代码展示了一个完整的列表页逻辑，能够实时刷新并展示局域网内所有发现的 UPnP 设备。

import 'package:flutter/material.dart';
import 'package:upnp_client/upnp_client.dart';

class HarmonyUpnpScanner extends StatefulWidget {
  @override
  _HarmonyUpnpScannerState createState() => _HarmonyUpnpScannerState();
}

class _HarmonyUpnpScannerState extends State<HarmonyUpnpScanner> {
  final List<UPnPDevice> _devices = [];
  bool _isSearching = false;

  void _scan() {
    setState(() {
      _devices.clear();
      _isSearching = true;
    });
    final disco = DeviceDiscoverer();
    disco.discoverDevices().timeout(Duration(seconds: 10)).listen((d) {
      if (!_devices.any((existing) => existing.urlBase == d.urlBase)) {
        setState(() => _devices.add(d));
      }
    }, onDone: () => setState(() => _isSearching = false));
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text("鸿蒙全连接：跨设备服务中心")),
      floatingActionButton: FloatingActionButton(
        onPressed: _isSearching ? null : _scan,
        child: Icon(Icons.refresh),
      ),
      body: ListView.builder(
        itemCount: _devices.length,
        itemBuilder: (ctx, i) => ListTile(
          leading: Icon(Icons.router, color: Colors.indigo),
          title: Text(_devices[i].friendlyName),
          subtitle: Text("地址：${_devices[i].urlBase}"),
          trailing: Icon(Icons.arrow_forward_ios, size: 14),
          onTap: () => _showDetail(_devices[i]),
        ),
      ),
    );
  }

  void _showDetail(UPnPDevice d) {
    // 逻辑演示：展示设备详细服务列表
  }
}

七、总结

upnp_client 在鸿蒙适配的过程中，不仅展现了其协议层面的严密性，更为我们开启了通往'万物智联'的大门。虽然在追求极致流畅和权限管控的道路上还存在挑战，但只要掌握了 UDP 通信和自动化 XML 处理的精髓，任何鸿蒙开发者都能在内网互联中游刃有余。

使每个鸿蒙应用具备内网互联能力。

💡 技巧：在鸿蒙真机测试时，如果发现一直搜索不到设备，请先通过第三方工具确认当前 Wi-Fi 是否开启了'AP 隔离'功能。