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

注意：部分鸿蒙真机（尤其是企业版平板）默认禁用了 UDP 多播发现。如果搜索不到设备，请检查系统设置或 DeviceManager API，确认当前局域网是否存在防火墙隔离或 AP 隔离。

核心 API 详解

设备发现

这是流程的起点。使用 DeviceDiscoverer 类指定设备类型进行搜索。

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}");
  });
}

服务控制

如果你正在开发视频 App，可以通过 AVTransport 服务将内容投射到电视。

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("鸿蒙投屏指令已发送！");
  }
}

典型应用场景

1. 智能家居自动关联：配合鸿蒙分布式能力，自动扫描附近智能灯泡或网关。
2. NAS 存储挂载：在文件管理器内部，自动发现并挂载支持 UPnP 的存储服务器。
3. 办公演示：一键投屏 PPT 的核心后盾，快速发现投影仪。

平台适配挑战与优化

UDP 多播包丢包

在信号不稳时，单次多播可能无法覆盖所有设备。

• 策略：设置定时器重试，每次间隔 2 秒；根据 Wi-Fi 质量动态调整超时时间。

XML 解析性能

部分设备的描述文件长达几千行，低配设备上解析可能导致 UI 卡顿。

• 方案：分时解析，只拉取基础 Header；利用 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 隔离功能。