Capacitor 常用函式庫

本文檔介紹 Capacitor 開發中常用的第三方函式庫及其使用方式。

目錄

• @capacitor-community/bluetooth-le
• @capacitor-firebase/authentication
• @capacitor/keyboard

---

@capacitor-community/bluetooth-le

概述

@capacitor-community/bluetooth-le 是一個用於實現跨平台藍牙低功耗 (BLE) 連接功能的函式庫，主要用於與 IoT 設備進行通訊。

主要功能：

• 設備掃描和連接
• 藍牙數據讀寫
• 跨平台支援 (iOS, Android, Web)

版本資訊

• 函式庫版本: ^7.2.0
• 支援平台: iOS, Android, Web
• 主要用途: 與 WFCO 設備進行藍牙連接和數據通訊

安裝與配置

1. 安裝

npm install @capacitor-community/bluetooth-le

2. Capacitor 配置

在 capacitor.config.ts 中配置：

plugins: {
  BluetoothLe: {
    displayStrings: {
      scanning: "scanning...",
      cancel: "cancel",
      availableDevices: "available devices",
      noDeviceFound: "no device found",
    },
  },
}

3. 權限配置

Android 權限 (android/app/src/main/AndroidManifest.xml)：

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

iOS 配置 (ios/App/Info.plist)：

<key>NSBluetoothAlwaysUsageDescription</key>
<string>此應用需要藍牙權限來連接 IoT 設備</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>此應用需要藍牙權限來連接 IoT 設備</string>

專案架構

平台適配器模式

src/utils/
├── client.ts              # 主要適配器，根據平台自動選擇
├── client-capacitor.ts    # Capacitor 平台實現
└── client-website.ts      # Web 平台實現

核心組件

ClientAdapter (src/utils/client.ts)

• 根據運行平台自動選擇適當的藍牙客戶端
• 提供統一的 API 介面
• 處理平台差異性

Capacitor 客戶端 (src/utils/client-capacitor.ts)

import { WfcoWebBluetoothClient } from "@thortron/wfco-client-ts-capacitorjs";

const client = new WfcoWebBluetoothClient();

主要功能

1. 設備掃描

// 開始掃描
await client.startScan();

// 停止掃描
await client.stopScan();

// 監聽設備發現事件
client.on("deviceDiscovered", handleDeviceDiscovered);

2. 設備連接

// 連接到指定設備
const result = await client.connectToDevice(deviceId);

// 確認應用連接
const confirm = await client.confirmAppConnection({
  onPairCodeMatch: async (checkMd5: string) => {
    console.log("配對成功，代碼:", checkMd5);
  },
  onPairCodeMismatch: (checkMd5: string, responseMd5: string) => {
    console.log("配對失敗，代碼:", checkMd5, responseMd5);
  },
  onTimeout: (checkMd5: string) => {
    console.log("配對超時，代碼:", checkMd5);
  },
});

3. 數據通訊

// 發送心跳
client.sendHeartBeat(count);

// 讀取設備配置
const config = await client.detectModelAndReturnConfig();

// 讀取設備 ID
await client.readDeviceId();

4. 事件監聽

// 監聽新讀數
client.onNewReadingsComing = (readings) => {
  setHeartbeat(readings);
};

// 監聽感應器讀數
client.onNewSensorReadingsComing = (readings) => {
  useSensorDeviceStore().updateHeartbeat(readings);
};

// 監聽重置 PIN 命令
client.onResetPinCommandComing = () => {
  const event = new CustomEvent("resetPinCommandComing");
  window.dispatchEvent(event);
};

使用流程

設備掃描流程

設備連接流程

錯誤處理

常見錯誤類型

1. 連接超時: 10 秒內未收到心跳
2. 配對失敗: 配對代碼不匹配
3. 設備未找到: 掃描不到目標設備
4. 權限拒絕: 藍牙權限未授予

錯誤處理策略

// 重試機制
let retryCount = 0;
const maxRetries = 3;

while (retryCount < maxRetries && !confirm) {
  try {
    confirm = await client.confirmAppConnection(options);
  } catch (error) {
    retryCount++;
    if (retryCount < maxRetries) {
      console.log(`連接嘗試 ${retryCount} 失敗，重試中...`);
    } else {
      throw error;
    }
  }
}

平台差異

平台	實現方式	特點
Capacitor (iOS/Android)	@capacitor-community/bluetooth-le	需要設備 ID、支援背景掃描、需要權限管理
Web	Web Bluetooth API	不需要設備 ID、僅支援前台掃描、瀏覽器權限管理

最佳實踐

1. 權限檢查: 在掃描前檢查藍牙權限
2. 錯誤處理: 實現完整的錯誤處理和重試機制
3. 狀態管理: 使用 Pinia 管理連接狀態
4. 用戶體驗: 提供清晰的連接進度指示
5. 資源管理: 及時清理事件監聽器和定時器

相關依賴

• @thortron/wfco-client-ts-capacitorjs: WFCO 客戶端 Capacitor 實現
• @thortron/wfco-client-ts: WFCO 客戶端 Web 實現
• @capacitor/core: Capacitor 核心功能
• pinia: 狀態管理

注意事項

1. iOS 限制: iOS 需要用戶手動配對確認
2. Android 權限: 需要位置權限才能掃描 BLE 設備
3. Web 限制: 僅支援 HTTPS 環境下的 Web Bluetooth
4. 設備兼容性: 確保目標設備支援 BLE 協議

故障排除

常見問題

1. 掃描不到設備: 檢查藍牙權限和位置權限
2. 連接失敗: 確認設備在範圍內且未被其他應用佔用
3. 配對超時: 檢查設備配對模式是否正確
4. 數據傳輸中斷: 檢查設備電量和信號強度

調試技巧

// 啟用詳細日誌
console.log("連接結果 =>", result);
console.log("設備配置 =>", config);
console.log("心跳計數 =>", heartbeatCount);

---

@capacitor-firebase/authentication

概述

@capacitor-firebase/authentication 提供 Firebase Authentication 的 Capacitor 整合，讓您可以在移動應用中實現用戶登入功能。

主要功能

• 用戶註冊和登入
• 社交媒體登入 (Google, Facebook, Twitter 等)
• 匿名登入
• 電話號碼驗證
• 電子郵件驗證

安裝

npm install @capacitor-firebase/authentication

基本使用

import { FirebaseAuthentication } from "@capacitor-firebase/authentication";

// 電子郵件登入
const signInWithEmailAndPassword = async (email: string, password: string) => {
  const result = await FirebaseAuthentication.signInWithEmailAndPassword({
    email,
    password,
  });
  return result;
};

// 註冊新用戶
const createUserWithEmailAndPassword = async (email: string, password: string) => {
  const result = await FirebaseAuthentication.createUserWithEmailAndPassword({
    email,
    password,
  });
  return result;
};

// 登出
const signOut = async () => {
  await FirebaseAuthentication.signOut();
};

配置

Firebase 配置

1. 在 Firebase Console 中創建專案
2. 下載 google-services.json (Android) 和 GoogleService-Info.plist (iOS)
3. 將配置文件放置到對應的目錄中

Capacitor 配置

// capacitor.config.ts
plugins: {
  FirebaseAuthentication: {
    skipNativeAuth: false,
    providers: ["google.com", "facebook.com", "twitter.com"]
  }
}

---

@capacitor/keyboard

概述

@capacitor/keyboard 提供鍵盤控制功能，主要用於管理輸入時鍵盤的行為和位置。

主要功能

• 控制鍵盤顯示/隱藏
• 調整鍵盤高度
• 控制應用內容是否跟隨鍵盤移動
• 鍵盤事件監聽

安裝

npm install @capacitor/keyboard

基本使用

import { Keyboard } from "@capacitor/keyboard";

// 顯示鍵盤
const showKeyboard = async () => {
  await Keyboard.show();
};

// 隱藏鍵盤
const hideKeyboard = async () => {
  await Keyboard.hide();
};

// 設置鍵盤樣式
const setKeyboardStyle = async () => {
  await Keyboard.setStyle({
    style: "dark", // 'light' | 'dark'
  });
};

// 設置鍵盤是否自動調整大小
const setResizeMode = async () => {
  await Keyboard.setResizeMode({
    mode: "body", // 'body' | 'ionic' | 'native'
  });
};

事件監聽

import { Keyboard } from "@capacitor/keyboard";

// 監聽鍵盤顯示事件
Keyboard.addListener("keyboardWillShow", (info) => {
  console.log("鍵盤將要顯示，高度:", info.keyboardHeight);
});

// 監聽鍵盤隱藏事件
Keyboard.addListener("keyboardWillHide", () => {
  console.log("鍵盤將要隱藏");
});

// 監聽鍵盤顯示完成事件
Keyboard.addListener("keyboardDidShow", (info) => {
  console.log("鍵盤已顯示，高度:", info.keyboardHeight);
});

// 監聽鍵盤隱藏完成事件
Keyboard.addListener("keyboardDidHide", () => {
  console.log("鍵盤已隱藏");
});

配置選項

鍵盤調整模式

• body: 調整 body 元素大小
• ionic: 使用 Ionic 的鍵盤處理方式
• native: 使用原生鍵盤處理方式

鍵盤樣式

• light: 淺色鍵盤
• dark: 深色鍵盤

使用場景

1. 固定背景: 當您希望應用背景保持固定，不跟隨鍵盤移動時
2. 自適應佈局: 當您希望應用內容跟隨鍵盤向上移動時
3. 鍵盤高度調整: 根據鍵盤高度調整 UI 佈局
4. 鍵盤樣式控制: 根據應用主題設置鍵盤樣式

注意事項

1. iOS: 某些功能在 iOS 上可能有限制
2. Android: 需要適當的權限配置
3. Web: 在 Web 環境中功能可能有限
4. 性能: 頻繁的鍵盤事件可能影響性能，建議適當節流

---

總結

這些函式庫為 Capacitor 應用提供了重要的功能支援：

• @capacitor-community/bluetooth-le: 實現跨平台藍牙連接
• @capacitor-firebase/authentication: 提供完整的用戶認證解決方案
• @capacitor/keyboard: 精確控制鍵盤行為和用戶體驗

選擇合適的函式庫可以大大簡化開發流程，提升應用功能和用戶體驗。