快速入门

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-wifi`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/wifi/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-wifi` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

bun add @capgo/capacitor-wifi
bunx cap sync

导入

import { CapacitorWifi } from '@capgo/capacitor-wifi';

快速入门

import { CapacitorWifi, NetworkSecurityType } from '@capgo/capacitor-wifi';

await CapacitorWifi.addNetwork({
  ssid: 'MyNetwork',
  password: 'mypassword',
  isHiddenSsid: false,
  securityType: NetworkSecurityType.WPA2_PSK
});

示例：连接

import { CapacitorWifi, WifiConnectionErrorCode } from '@capgo/capacitor-wifi';

try {
  await CapacitorWifi.connect({
    ssid: 'MyNetwork',
    password: 'mypassword',
    autoRouteTraffic: true, // Android only
    timeoutMs: 30000,
  });
} catch (error: any) {
  switch (error.code) {
    case WifiConnectionErrorCode.WIFI_DISABLED:
      // Ask the user to enable Wi-Fi
      break;
    case WifiConnectionErrorCode.PERMISSION_DENIED:
      // Request the required permission
      break;
    default:
      // Generic connection error
      break;
  }
}

示例：断开连接

import { CapacitorWifi } from '@capgo/capacitor-wifi';

await CapacitorWifi.disconnect();

常见坑点

权限: 调用 checkPermissions() 然后 requestPermissions() 在需要时。
监听器: 在页面卸载时移除句柄。
唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

API 概览

`addNetwork`

显示系统对话框以向设备添加 Wi-Fi 网络。在 Android SDK 30+ 上，这会打开系统 Wi-Fi 设置并预填网络信息。在 iOS 上，这会直接连接到该网络。

import { CapacitorWifi, NetworkSecurityType } from '@capgo/capacitor-wifi';

await CapacitorWifi.addNetwork({
  ssid: 'MyNetwork',
  password: 'mypassword',
  isHiddenSsid: false,
  securityType: NetworkSecurityType.WPA2_PSK
});

`connect`

连接到 Wi-Fi 网络。在 Android 上，这会创建一个默认不通过该网络路由流量的临时连接。将 autoRouteTraffic 设置为 true，可将应用流量绑定到已连接的网络（适用于本地/设备托管的 AP）。若需在 Android 上建立持久连接，请改用 addNetwork()。在 iOS 上，这会创建一个持久连接。

import { CapacitorWifi } from '@capgo/capacitor-wifi';

await CapacitorWifi.connect({
  ssid: 'MyNetwork',
  password: 'mypassword',
  autoRouteTraffic: true // Android only: route app traffic through this network
});

`disconnect`

断开当前 Wi-Fi 网络连接。在 iOS 上，仅断开通过此插件添加的网络。

import { CapacitorWifi } from '@capgo/capacitor-wifi';

await CapacitorWifi.disconnect();

`getAvailableNetworks`

获取上次扫描时可用的 Wi-Fi 网络列表。仅 Android 端可用。

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const { networks } = await CapacitorWifi.getAvailableNetworks();
networks.forEach(network => {
  console.log(`SSID: ${network.ssid}, Signal: ${network.rssi} dBm`);
});

`getIpAddress`

获取设备当前的 IP 地址。 Android 和 iOS 均可用。

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const { ipAddress } = await CapacitorWifi.getIpAddress();
console.log('IP Address:', ipAddress);

`getRssi`

获取当前网络的接收信号强度指示（RSSI），单位为 dBm。仅 Android 可用。

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const { rssi } = await CapacitorWifi.getRssi();
console.log('Signal strength:', rssi, 'dBm');

`getSsid`

获取当前网络的服务集标识符（SSID）。 Android 和 iOS 均可用。

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const { ssid } = await CapacitorWifi.getSsid();
console.log('Connected to:', ssid);

`getWifiInfo`

获取当前连接的 WiFi 网络的综合信息。该方法通过单次调用即可提供包括 SSID、BSSID、IP 地址、频率、链路速度和信号强度在内的详细网络信息。在 iOS 上，部分字段可能不可用，值将为 undefined。

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const info = await CapacitorWifi.getWifiInfo();
console.log('Network:', info.ssid);
console.log('BSSID:', info.bssid);
console.log('IP:', info.ip);
console.log('Frequency:', info.frequency, 'MHz');
console.log('Speed:', info.linkSpeed, 'Mbps');
console.log('Signal:', info.signalStrength);

`isEnabled`

检查设备的 Wi-Fi 是否已启用。仅支持 Android。

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const { enabled } = await CapacitorWifi.isEnabled();
console.log('WiFi is', enabled ? 'enabled' : 'disabled');

`startScan`

开始扫描 Wi-Fi 网络。仅支持 Android。扫描结果通过 ‘networksScanned’ 事件监听器返回。注意：可能会因系统节流或硬件问题导致失败。

import { CapacitorWifi } from '@capgo/capacitor-wifi';

await CapacitorWifi.addListener('networksScanned', () => {
  console.log('Scan completed');
});
await CapacitorWifi.startScan();

`checkPermissions`

检查当前的定位权限状态。在两个平台上，Wi-Fi 操作都需要定位权限。

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const status = await CapacitorWifi.checkPermissions();
console.log('Location permission:', status.location);

`requestPermissions`

请求用户授予定位权限。在两个平台上，Wi-Fi 操作都需要定位权限。

import { CapacitorWifi } from '@capgo/capacitor-wifi';

const status = await CapacitorWifi.requestPermissions();
if (status.location === 'granted') {
  console.log('Permission granted');
}

类型参考

`AddNetworkOptions`

添加网络的配置选项。

export interface AddNetworkOptions {
  /**
   * The SSID of the network to add
   *
   * @since 7.0.0
   */
  ssid: string;

  /**
   * The password for the network (optional for open networks)
   *
   * @since 7.0.0
   */
  password?: string;

  /**
   * Whether the network is hidden (Android only)
   *
   * @since 7.0.0
   * @default false
   */
  isHiddenSsid?: boolean;

  /**
   * The security type of the network (Android only)
   *
   * @since 7.0.0
   * @default NetworkSecurityType.WPA2_PSK
   */
  securityType?: NetworkSecurityType;
}

`ConnectOptions`

连接网络的配置选项。

export interface ConnectOptions {
  /**
   * The SSID of the network to connect to
   *
   * @since 7.0.0
   */
  ssid: string;

  /**
   * The password for the network (optional for open networks)
   *
   * @since 7.0.0
   */
  password?: string;

  /**
   * Whether the network is hidden (Android only)
   *
   * @since 7.0.0
   * @default false
   */
  isHiddenSsid?: boolean;

  /**
   * Whether to automatically route app traffic through the connected Wi-Fi network (Android only)
   * When enabled, it binds the app process to the connected network using ConnectivityManager.bindProcessToNetwork()
   * This is useful for connecting to local/device-hosted APs (e.g., ESP32, IoT devices) that don't have internet access.
   *
   * @since 7.0.0
   * @default false
   */
  autoRouteTraffic?: boolean;
}

`DisconnectOptions`

断开网络连接的配置选项。

export interface DisconnectOptions {
  /**
   * The SSID of the network to disconnect from (optional)
   *
   * @since 7.0.0
   */
  ssid?: string;
}

`GetAvailableNetworksResult`

getAvailableNetworks() 的返回值。

export interface GetAvailableNetworksResult {
  /**
   * List of available networks
   *
   * @since 7.0.0
   */
  networks: Network[];
}

`GetIpAddressResult`

getIpAddress() 的返回值。

export interface GetIpAddressResult {
  /**
   * The device's IP address
   *
   * @since 7.0.0
   */
  ipAddress: string;
}

`GetRssiResult`

getRssi() 的返回值。

export interface GetRssiResult {
  /**
   * The signal strength in dBm
   *
   * @since 7.0.0
   */
  rssi: number;
}

`GetSsidResult`

getSsid() 的返回值。

export interface GetSsidResult {
  /**
   * The SSID of the current network
   *
   * @since 7.0.0
   */
  ssid: string;
}

`WifiInfo`

全面的 WiFi 信息。

export interface WifiInfo {
  /**
   * The SSID (network name) of the current network
   *
   * @since 7.0.0
   */
  ssid: string;

  /**
   * The BSSID (MAC address) of the access point.
   * Not available on iOS.
   *
   * @since 7.0.0
   */
  bssid?: string;

  /**
   * The device's IP address on the network
   *
   * @since 7.0.0
   */
  ip: string;

  /**
   * The network frequency in MHz.
   * Not available on iOS.
   *
   * @since 7.0.0
   */
  frequency?: number;

  /**
   * The connection speed in Mbps.
   * Not available on iOS.
   *
   * @since 7.0.0
   */
  linkSpeed?: number;

  /**
   * The signal strength (0-100).
   * Calculated from RSSI on Android.
   * Not available on iOS.
   *
   * @since 7.0.0
   */
  signalStrength?: number;
}

`IsEnabledResult`

isEnabled() 的返回结果。

export interface IsEnabledResult {
  /**
   * Whether Wi-Fi is enabled
   *
   * @since 7.0.0
   */
  enabled: boolean;
}

`PermissionStatus`

权限状态。

export interface PermissionStatus {
  /**
   * Location permission state
   *
   * @since 7.0.0
   */
  location: PermissionState;
}

`RequestPermissionsOptions`

请求权限时的配置选项。

export interface RequestPermissionsOptions {
  /**
   * Permissions to request
   *
   * @since 7.0.0
   */
  permissions?: 'location'[];
}

`NetworkSecurityType`

网络安全类型。

export enum NetworkSecurityType {
  /**
   * Open network with no security
   *
   * @since 7.0.0
   */
  OPEN = 0,

  /**
   * WEP security
   *
   * @since 7.0.0
   */
  WEP = 1,

  /**
   * WPA/WPA2 Personal (PSK)
   *
   * @since 7.0.0
   */
  WPA2_PSK = 2,

  /**
   * WPA/WPA2/WPA3 Enterprise (EAP)
   *
   * @since 7.0.0
   */
  EAP = 3,

  /**
   * WPA3 Personal (SAE)
   *
   * @since 7.0.0
   */
  SAE = 4,

  /**
   * WPA3 Enterprise
   *
   * @since 7.0.0
   */
  WPA3_ENTERPRISE = 5,

  /**
   * WPA3 Enterprise 192-bit mode
   *
   * @since 7.0.0
   */
  WPA3_ENTERPRISE_192_BIT = 6,

  /**
   * Passpoint network
   *
   * @since 7.0.0
   */
  PASSPOINT = 7,

  /**
   * Enhanced Open (OWE)
   *
   * @since 7.0.0
   */
  OWE = 8,

  /**
   * WAPI PSK
   *
   * @since 7.0.0
   */
  WAPI_PSK = 9,

  /**
   * WAPI Certificate
   *
   * @since 7.0.0
   */
  WAPI_CERT = 10,
}

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。

从入门指南继续

如果你正在使用 快速入门 要规划 dashboard 和 API 操作，请将其连接到使用 @capgo/capacitor-wifi 关于使用 @capgo/capacitor-wifi 中的原生能力， API 概览关于 API Overview 中的实现细节，简介关于 Introduction 中的实现细节， API 密钥有关 API Keys 的实现细节，以及设备有关 Devices 的实现细节。