• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Wi-Fi扫描开发指南
2
3<!--Kit: Connectivity Kit-->
4<!--Subsystem: Communication-->
5<!--Owner: @qq_43802146-->
6<!--Designer: @qq_43802146-->
7<!--Tester: @furryfurry123-->
8<!--Adviser: @zhang_yixin13-->
9
10## 简介
11Wi-Fi扫描是指设备（如手机、电脑、路由器等）搜索周围可用Wi-Fi网络的过程。通过扫描，设备可以获取附近网络的基本信息（如网络名称、信号强度、加密方式等），从而实现连接、管理或分析周围网络。
12
13## 场景介绍
14
15- [Wi-Fi扫描](#wi-fi扫描)
16- [PNO扫描](#pno扫描)
17- [周期扫描](#周期扫描)
18- [扫描管控](#扫描管控)
19
20## 接口说明
21
22扫描接口说明如下表所示。具体API说明详见[接口文档](../../reference/apis-connectivity-kit/js-apis-wifiManager.md)。
23
24| 接口名 | 功能描述 |
25| -------- | -------- |
26| getScanInfoList() | 获取包含当前时间点前30s内的缓存扫描结果。|
27| on(type: 'wifiScanStateChange') | 注册扫描状态改变事件。|
28| off(type: 'wifiScanStateChange') | 取消注册扫描状态改变事件。|
29
30
31## 开发步骤
32
33### Wi-Fi扫描
341. 导入需要的Wi-Fi模块。
352. 需要SystemCapability.Communication.WiFi.STA系统能力。
363. 需要权限ohos.permission.GET_WIFI_INFO。
374. 开启设备的Wi-Fi。
385. 示例代码：
39
40> **说明：**
41> 主动扫描接口，从API version 10开始废弃。替代接口仅向系统应用开放。
42
43   ```ts
44   import { wifiManager } from '@kit.ConnectivityKit';
45
46   try {
47     let recvWifiScanStateChangeFunc = (result:number) => {
48         console.info("Receive Wifi scan state change event: " + result);
49     }
50
51     // 获取扫描状态 0：扫描失败；1：扫描成功。
52     wifiManager.on("wifiScanStateChange", recvWifiScanStateChangeFunc);
53
54     let isWifiActive = wifiManager.isWifiActive();
55     if (!isWifiActive) {
56       console.error("wifi not enable"); // 请先手动打开WiFi
57       return;
58     }
59
60     let scanInfoList = wifiManager.getScanInfoList();
61
62     let len = scanInfoList.length;
63     console.info("wifi received scan info: " + len);
64     if(len > 0){
65       for (let i = 0; i < len; ++i) {
66         console.info("ssid: " + scanInfoList[i].ssid);
67         console.info("bssid: " + scanInfoList[i].bssid);
68         console.info("capabilities: " + scanInfoList[i].capabilities);
69         console.info("securityType: " + scanInfoList[i].securityType);
70         console.info("rssi: " + scanInfoList[i].rssi);
71         console.info("band: " + scanInfoList[i].band);
72         console.info("frequency: " + scanInfoList[i].frequency);
73         console.info("channelWidth: " + scanInfoList[i].channelWidth);
74         console.info("timestamp: " + scanInfoList[i].timestamp);
75         console.info("supportedWifiCategory: " + scanInfoList[i].supportedWifiCategory);
76         console.info("isHiLinkNetwork: " + scanInfoList[i].isHiLinkNetwork);
77       }
78     }
79
80     // 取消注册，停止获取扫描状态。
81     wifiManager.off("wifiScanStateChange", recvWifiScanStateChangeFunc);
82   } catch (error) {
83     console.error(`WiFi scan fail. ${error.message}`);
84   }
85   ```
86
87 5. 错误码详情请参见[WIFI错误码](../../reference/apis-connectivity-kit/errorcode-wifi.md)。
88
89 ### PNO扫描
90
91  PNO扫描即首选分流网络扫描（Preferred Network Offload scanning），是一种用于降低移动设备功耗的Wi-Fi扫描技术。<br>
92  触发PNO扫描条件：当设备未连接Wi-Fi且屏幕关闭后，会触发PNO扫描，支持设备在后台寻找并连接首选的Wi-Fi网络。
93
94 ### 周期扫描
95
96  WiFi周期扫描是指无线设备（如智能手机、平板电脑、笔记本电脑等）按照一定的时间间隔，自动搜索周围可用的WiFi网络的过程。<br>
97  触发场景描述：<br>
98  1. 设备亮屏且与Wi-Fi已连接：判断当前链路是否支持上网。支持上网，扫描间隔1h；不支持上网，判断是否静止，静止场景下扫描周期从20s开始倍增，最大300s；非静止场景扫描周期从20s开始，最大160s。<br>
99  2. 设备亮屏且与Wi-Fi未连接：静止场景扫描周期从20s开始倍增，最大300s；非静止场景扫描周期从20s开始，最大160s。
100
101### 扫描管控
102
103  WiFi扫描管控是指对无线设备扫描WiFi网络的行为进行管理和控制。<br>
104
105  以下是一些常见的管控方式和应用场景：<br>
106  1. WiFi在关闭的情况下不触发周期扫描和PNO扫描。<br>
107  2. WiFi连接过程中不允许触发扫描。<br>
108  3. 前台应用2分钟内最多发起4次扫描。<br>
109  4. 设备温度达到阈值，设备扫描会被管控。<br>
110  5. 扫描接口从API version 9开始支持，从API version 10开始废弃，替代接口仅向系统应用开放。<br>
111  6. 扫描结果获取真实bssid，需要申请ohos.permission.GET_WIFI_PEERS_MAC权限。
112