一键搞定UniApp WiFi连接！这个Vue 3 Hook让你少走弯路

在移动应用开发中，设备连接功能是常见的需求场景。无论是智能家居配网、设备绑定，还是网络配置，WiFi功能都扮演着重要角色。本文将分享一个在UniApp中实现WiFi连接的全过程。

技术背景与挑战

在开发WiFi相关功能时，我们面临的主要挑战包括：

平台差异：Android和iOS在WiFi权限和API支持上存在显著差异
权限管理：微信小程序规范要求获取位置权限才能使用WiFi功能
用户体验：需要处理各种异常情况，提供清晰的用户引导

核心实现代码解析

1. 模块初始化与版本检测

javascript 复制代码

export function useWifi() {
  const toast = inject("toast")
  
  let info = uni.getDeviceInfo()
  const os = info.osName
  const osVersion = info.osVersion
  
  // 初始化wifi模块
  const startWifi = (getList = 1) => {
    // 版本兼容性检查
    if (os == 'android' && osVersion < 6) {
      toast('手机版本不支持')
      return;
    }
    if (os == 'ios' && osVersion < 11.2) {
      toast('手机版本不支持')
      return;
    }
    
    uni.showLoading({
      title: '初始化WIFI模块',
      mask: true
    })
    
    uni.startWifi({
      success(res) {
        console.log('wifi 初始化成功');
        if(getList == 1) {
          getUserAuthorize();
        }
      },
      fail(err) {
        // 错误处理逻辑
      }
    })
  }
}

关键点说明：

通过os和osVersion进行平台版本检测
使用uni.showLoading提供操作反馈
初始化成功后自动触发权限获取流程

2. 位置权限获取

javascript 复制代码

const getUserAuthorize = async () => {
  uni.showLoading({
    title: '获取定位权限...',
    mask: true
  })
  
  // authorize内使用uni.getSetting和uni.authorize获取授权状态
  authorize('scope.userLocation')
  .then(res => {
    console.log("用户已提供权限")
    getWifiList();
  })
  .catch(err => {
    // 权限被拒绝时的引导流程
    uni.showModal({
      content: '请授权获取位置信息',
      showCancel: false,
      success: function(res) {
        uni.openSetting({
          success: (res) => {
            if (!res.authSetting['scope.userLocation']) {
              // 未授权时的提示
            } else {
              // 授权完成后的处理
              getWifiList();
            }
          }
        });
      }
    })		
  })
}

权限获取策略：

先检查当前权限状态
无权限时先尝试获取授权
用户拒绝后引导跳转设置页面

3. WiFi列表获取与平台差异处理

javascript 复制代码

const wifiList = ref([])
const getWifiList = () => {
  uni.showLoading({
    title: '获取当前WiFi列表...',
    mask: true
  })
  
  uni.getWifiList({
    success: (res) => {
      uni.hideLoading();
      // iOS特殊处理
      if (os == 'ios') {
        setTimeout(() => {
          uni.showModal({
            content: 'IOS手机无法主动获取WiFi列表，请先进入系统的【设置-WiFi】页面...',
            showCancel: false,
          })
        }, 2000)
      }
    },
    fail: (err) => {
      // 失败处理逻辑
    },
  })
  
  // 监听WiFi列表返回
  uni.onGetWifiList((res) => {
    wifiList.value = res?.wifiList?.filter(item => item.SSID)
      ?.sort((a,b) => b.signalStrength - a.signalStrength) || []
  })
}

平台兼容性处理要点：

Android可直接获取WiFi列表
iOS需要用户手动在系统设置中选择WiFi
使用信号强度排序提供更好的用户体验

4. WiFi连接实现

javascript 复制代码

const connectWifi = (wifiName, success, fail) => {
  uni.connectWifi({
    SSID: wifiName,
    password: '', // 开放网络
    forceNewApi: true,
    success(res) {
      console.log('手动连接完毕', res)
      if(isFunction(success)) {
        success()
      }
    },
    fail(err) {
      uni.hideLoading()
      uni.showToast({
        title: 'wifi连接异常，请尝试手动连接',
        icon: 'error'
      })
      if(isFunction(fail)) {
        fail()
      }
    }
  })
}

实际应用中的坑与解决方案

1. iOS平台限制

问题：iOS系统出于隐私考虑，不允许应用直接获取WiFi列表。

解决方案：

javascript 复制代码

// 提供明确的用户引导
uni.showModal({
  content: 'IOS手机无法主动获取WiFi列表，请先进入系统的【设置-WiFi】页面，待加载完毕WiFi列表后，返回小程序完成后续配置',
  showCancel: false,
})

2. 权限获取流程优化

问题：用户可能在权限弹窗中选择拒绝。

解决方案：

javascript 复制代码

// 提供二次引导机会
uni.showModal({
  content: '请授权获取位置信息',
  showCancel: false,
  success: function(res) {
    uni.openSetting({
      success: (res) => {
        if (res.authSetting['scope.userLocation']) {
          getWifiList(); // 用户授权后继续流程
        }
      }
    });
  }
})

完整的使用示例

vue 复制代码

<template>
  <view class="container">
    <button @click="startWifi">搜索WiFi</button>
    <view v-for="wifi in wifiList" :key="wifi.SSID" 
          @click="connectWifi(wifi.SSID)">
      {{ wifi.SSID }} - 信号强度: {{ wifi.signalStrength }}
    </view>
  </view>
</template>

<script setup>
import { useWifi } from '@/composables/useWifi'

const { wifiList, startWifi, connectWifi } = useWifi()
</script>

总结与最佳实践

通过本文我们总结了以下最佳实践：

版本检测前置：在功能调用前进行充分的平台和版本检测
权限引导友好：为用户提供清晰的权限获取引导流程
平台差异处理：针对不同平台的限制提供相应的解决方案
错误处理完善：覆盖所有可能的异常情况，提供有用的错误信息
用户体验优先：通过加载状态和明确提示提升用户体验

WiFi连接功能虽然看似简单，但在实际开发中需要考虑众多细节和平台差异。希望本文的经验分享能够帮助你在UniApp项目中顺利实现WiFi相关功能。