ASCF Wi-Fi 信息获取与连接 API 实战：权限、列表与踩坑

鸿蒙专家

在鸿蒙元服务开发中，Wi-Fi 相关的操作场景很常见，比如读取当前连接的网络信息、扫描周边可用热点、或者主动连接指定 Wi-Fi。ASCF 提供了一套覆盖这些场景的 Wi-Fi API，整体上手不算复杂，但权限配置和异步回调模式有一些容易踩的坑。本文基于实际使用经验，梳理 Wi-Fi 信息获取与连接的 API 用法、权限申请方式，以及开发过程中需要注意的关键点。

## 权限配置：四个权限一个都不能少

ASCF Wi-Fi API 的权限体系比较繁琐，大部分接口除了 Wi-Fi 自身权限外，还要申请位置权限。原因是 Wi-Fi 列表和热点信息可以被用来做定位，系统因此将其归入位置权限管理。在 module.json5 中，通常需要声明以下四个权限：

2. {
3.   "requestPermissions": [
4.     {
5.       "name": "ohos.permission.GET_WIFI_INFO",
6.       "reason": "用于获取Wi-Fi信息",
7.       "usedScene": {
8.         "abilities": ["EntryAbility"],
9.         "when": "inuse"
10.       }
11.     },
12.     {
13.       "name": "ohos.permission.SET_WIFI_INFO",
14.       "reason": "用于连接Wi-Fi",
15.       "usedScene": {
16.         "abilities": ["EntryAbility"],
17.         "when": "inuse"
18.       }
19.     },
20.     {
21.       "name": "ohos.permission.LOCATION",
22.       "reason": "用于获取Wi-Fi位置信息",
23.       "usedScene": {
24.         "abilities": ["EntryAbility"],
25.         "when": "inuse"
26.       }
27.     },
28.     {
29.       "name": "ohos.permission.APPROXIMATELY_LOCATION",
30.       "reason": "用于获取Wi-Fi位置信息",
31.       "usedScene": {
32.         "abilities": ["EntryAbility"],
33.         "when": "inuse"
34.       }
35.     }
36.   ]
37. }

复制代码

除了静态声明，运行时还需要申请 scope.userLocation 授权。只有在授权成功后才能正常调用 Wi-Fi API。这一点很容易被忽略，尤其是当业务逻辑本身不涉及地图或定位时，开发者可能会觉得位置权限多余，但实际不申请就会直接调用失败。

2. has.authorize({
3.   scope: 'scope.userLocation',
4.   success: () => {
5.     console.info('位置授权成功');
6.     // 现在可以调用 Wi-Fi API 了
7.   },
8.   fail: (err) => {
9.     console.error('位置授权失败:', err);
10.   }
11. });

复制代码

## 获取当前连接的 Wi-Fi 信息

授权通过后，通过 has.getConnectedWifi 可以拿到当前连接的热点信息，包括 SSID、BSSID、信号强度、频段和是否加密等。

2. has.authorize({
3.   scope: 'scope.userLocation',
4.   success: () => {
5.     has.getConnectedWifi({
6.       success: (res) => {
7.         const wifi = res.wifi;
8.         console.info('SSID:', wifi.SSID);
9.         console.info('BSSID:', wifi.BSSID);
10.         console.info('信号强度:', wifi.signalStrength);
11.         console.info('频段:', wifi.frequency, 'MHz');
12.         console.info('是否安全:', wifi.secure);
13.       },
14.       fail: (err) => {
15.         console.error('获取失败:', err);
16.       }
17.     });
18.   }
19. });

复制代码

如果业务场景只需要展示当前 Wi-Fi 的名称，不需要信号强度等信息，可以将 partialInfo 参数设为 true，这样只会返回 SSID 和 BSSID，减少不必要的数据传输，同时也能降低部分权限要求。

2. has.getConnectedWifi({
3.   partialInfo: true,
4.   success: (res) => {
5.     console.info('SSID:', res.wifi.SSID);
6.     // 其他字段不会返回
7.   }
8. });

复制代码

## 获取 Wi-Fi 列表：先注册监听，再发起请求

扫描周围 Wi-Fi 列表的接口设计比较特殊：has.getWifiList 的 success 回调只代表列表请求已经发出，真正的 Wi-Fi 列表数据需要通过 has.onGetWifiList 监听返回。也就是说，必须先注册监听器，再调用 getWifiList，否则会收不到列表数据。

2. has.authorize({
3.   scope: 'scope.userLocation',
4.   success: () => {
5.     // 先注册监听，再请求列表
6.     has.onGetWifiList(function (res) {
7.       const wifiList = res.wifiList;
8.       console.info('发现', wifiList.length, '个 Wi-Fi');
9.       wifiList.forEach(function (wifi) {
10.         console.info(wifi.SSID, wifi.signalStrength);
11.       });
12.     });
14.     // 请求获取列表
15.     has.getWifiList({
16.       success: () => {
17.         console.info('Wi-Fi 列表请求成功');
18.       },
19.       fail: (err) => {
20.         console.error('获取列表失败:', err);
21.       }
22.     });
23.   }
24. });

复制代码

这种“监听回调 + 请求触发”的模式，在 AS CF 的异步接口中比较常见，和普通的“请求-响应”模型不太一样。建议在页面加载时注册监听，在页面销毁时记得移除，避免内存泄漏。

## 连接指定 Wi-Fi

has.connectWifi 用于主动连接某个热点。需要注意的是，password 参数是必填的，即使是开放网络也要传空字符串，不能省略。

2. has.authorize({
3.   scope: 'scope.userLocation',
4.   success: () => {
5.     has.connectWifi({
6.       SSID: 'MyWiFi',
7.       password: 'mypassword123',
8.       success: () => {
9.         console.info('Wi-Fi 连接成功');
10.         has.showToast({ title: '连接成功' });
11.       },
12.       fail: (err) => {
13.         console.error('连接失败:', err);
14.       }
15.     });
16.   }
17. });

复制代码

connectWifi 还有一个 manual 参数。如果设为 true，API 不会直接发起连接，而是跳转到系统 Wi-Fi 设置页面，让用户手动选择网络并输入密码。这种模式适合不确定密码、或者需要用户主动确认的场景，体验上更像是“引导用户去设置”，而不是应用内直接控制。

## 监听 Wi-Fi 连接状态

如果需要在连接状态变化时收到通知，可以使用 onWifiConnected 注册监听。注意，移除监听时要传入同一个函数对象，否则无法移除。用匿名函数注册的话，后续就没法单独解除监听，所以建议把回调函数保存成变量。

2. // 定义回调函数（需要保存引用才能移除）
3. const onConnected = function (res) {
4.   const wifi = res.wifi;
5.   console.info('Wi-Fi 已连接:', wifi.SSID);
6. };
8. // 注册监听
9. has.onWifiConnected(onConnected);
11. // 移除监听（需要传同一个函数对象）
12. has.offWifiConnected(onConnected);
14. // 或者移除所有监听
15. has.offWifiConnected();

复制代码

另外，ASCF 还提供了 onWifiConnectedWithPartialInfo 接口，这个 API 从 1.0.14 版本才开始支持。它和 onWifiConnected 的区别在于只返回部分 Wi-Fi 信息，适用于只需要知道当前连接了哪个热点的场景，权限要求也更低。在不需要完整信息时，优先使用这个接口会更轻量。

## 实际开发中容易踩的坑

结合上面的 API 使用，有几个问题在开发时尤其容易遇到：

1. 必须先授权再操作。大部分 Wi-Fi API 依赖 scope.userLocation 授权，不授权直接调用会失败。很多开发者以为只有获取位置才需要位置权限，结果在 Wi-Fi 接口上栽了跟头。

2. getWifiList 的结果在监听回调里返回。getWifiList 的 success 回调只表示请求发出去了，真正的数据要等 onGetWifiList 触发。顺序必须是先注册监听，再调用 getWifiList。

3. 移除监听要传同一个函数对象。如果注册时用的是匿名函数，就无法单独移除，只能调用 offWifiConnected 不带参数来移除所有监听。这会带来潜在的风险，建议始终用变量保存回调引用。

4. signalStrength 不是 dBm。返回的信号强度是一个 0 到 1 之间的浮点数，1 表示最强，0 表示最弱。如果要显示信号图标，可以按 0.25 一档来划分等级，而不是直接用 dBm 去套。

5. connectWifi 的密码必填。即使连接的是开放网络，password 参数也必须传，传空字符串 '' 即可。

## API 方法速查

- has.getConnectedWifi：获取当前连接的 Wi-Fi 信息，支持 partialInfo 精简返回。
- has.getWifiList + has.onGetWifiList：获取并监听 Wi-Fi 列表，先注册监听再请求。
- has.connectWifi：连接指定 Wi-Fi，支持 manual 跳转系统设置。
- has.onWifiConnected / has.offWifiConnected：监听/移除 Wi-Fi 连接状态。
- has.onWifiConnectedWithPartialInfo：轻量级连接状态监听，仅返回部分信息，1.0.14 起可用。

整体来看，ASCF Wi-Fi API 的权限要求确实偏多，module.json5 里需要声明四个权限，运行时还要再申请位置授权。但接口本身的设计逻辑并不复杂，只要理解了“先注册监听再请求”这个模式，再注意权限和回调用引用的问题，日常的 Wi-Fi 获取与连接需求基本都能顺利实现。