Tauri SDK 概述
Tauri SDK 讓你在用 Tauri 2 開發的桌面應用（Windows、macOS、Linux）中接入 IM 服務。它由一個 npm 包和一個 Rust 外掛組成：JavaScript 部分就是 Web SDK 的核心，各模組的 API、可訂閱的列表和事件與 Web SDK 完全相同；Rust 外掛負責本地資料庫、系統鑰匙串、關閉視窗後仍然保持的長連線、系統通知、角標與工作列，以及按本地路徑收發檔案。
// 引擎页（不显示的页面）：长连接、同步和提醒都在这里，整个应用一个
import { createDRTauriEngine } from '@deeprespond/im-tauri/engine';
createDRTauriEngine({ appKey: '1575529652#demo', apiUrl: 'https://im.example.com' });// 界面窗口：只需要 AppKey，之后的用法与 Web SDK 相同
import { createDRTauriClient } from '@deeprespond/im-tauri';
const im = createDRTauriClient({ appKey: '1575529652#demo' });
if (!im.auth.currentUser) await im.auth.loginWithTicket({ ticket }); // 已登录过的，启动后自动恢复
const list = im.conversations.list(); // 会话列表：先显示本地数据，后台同步
list.subscribe(() => render(list.getSnapshot().items));
| 專案 | 說明 |
|---|---|
| 當前版本 | 1.1.1（版本與支援狀態） |
| 安裝 | npm：@deeprespond/im-tauri；Rust：tauri-plugin-deeprespond-im，兩邊版本必須相同 |
| 系統 | Windows 10（1809）、macOS 12、Linux（WebKitGTK 4.1）以上的桌面系統 |
| 環境 | Tauri 2.12、Rust 1.90 以上 |
| 不支援 | Tauri 的移動端；Linux 上的音視訊通話 |
能做什麼
介面視窗中的客戶端物件 im 與 Web SDK 的客戶端相同，另外多了桌面相關的 im.desktop。各模組的用法請直接看 Web SDK 的文件：
| 屬性 | 功能 | 文件 |
|---|---|---|
im.auth、im.connection、im.config | 登入、退出、修改密碼；連線狀態與診斷；應用的執行配置 | 初始化、登入與連線 |
im.conversations | 會話列表、未讀數、置頂、草稿、正在輸入 | 會話 |
im.messages | 訊息列表、傳送、撤回、表情回應、置頂、已讀回執、本地搜尋 | 訊息 |
im.users、im.friends、im.presence、im.devices | 本人與其他使用者的資料、好友與黑名單、線上狀態、本人的登入裝置 | 使用者、好友與線上狀態 |
im.groups | 群、群成員、入群申請與邀請、入群連結 | 群組 |
im.files | 上傳、下載、群檔案、錄音 | 檔案 |
im.chatrooms | 聊天室 | 聊天室 |
im.calls | 一對一和群組的語音、視訊通話 | 音視訊通話 |
im.channels | 獨立 RTC 頻道：加入、恢復、媒體、狀態與退出 | 頻道接入 |
im.push、im.reports | 推送設定、會話免打擾；舉報 | 提醒、推送設定與舉報 |
im.on()、DRError | 事件、錯誤與提示文案 | 事件與錯誤處理 |
im.desktop | 系統通知、角標與工作列、選擇和拖放檔案、本地預覽、下載與開啟檔案、診斷 | 桌面能力 |
Tauri SDK 自己的內容在本節的另外三頁：第一次接入請看快速整合；引擎頁、多個視窗、退出與托盤應用見引擎與視窗；通知、角標、檔案路徑等見桌面能力。
包的組成
| 包 | 內容 |
|---|---|
npm @deeprespond/im-tauri | 介面視窗的 createDRTauriClient、拖放檔案的 onFilesDropped、桌面模組的型別和事件型別 DesktopEvents。同時重新匯出 @deeprespond/im-web 的全部內容（DRError、各模組的型別等），不必再從 Web SDK 匯入 |
npm @deeprespond/im-tauri/engine | 引擎頁的 createDRTauriEngine |
crate tauri-plugin-deeprespond-im | Rust 外掛：在 src-tauri 中註冊，見快速整合 |
- 依賴：npm 包以
@deeprespond/im-web（同一版本）和@tauri-apps/api（2.12 以上）為對等依賴，需要一起安裝。 - React、Vue：直接使用 Web SDK 的繫結包
@deeprespond/im-web-react、@deeprespond/im-web-vue，把createDRTauriClient()的結果交給DRProvider（或 Vue 外掛）即可，見在 React 和 Vue 中使用。 - 顯示輔助和提示文案：從
@deeprespond/im-web/render、@deeprespond/im-web/locale/zh-CN匯入，與 Web SDK 相同。
外掛的特性
| 特性 | 預設 | 說明 |
|---|---|---|
tray | 開啟 | 托盤圖示閃爍的輔助 desktop.trayBlink()，會開啟 Tauri 的 tray-icon 特性。不用托盤的應用可以關閉預設特性 |
sqlcipher | 關閉 | 加密本地資料庫，見加密本地資料庫。會連結 SQLCipher，安裝包隨之增大 |
heic | 關閉 | Linux 上用系統的 libheif（1.17 以上）把 HEIC 照片轉為圖片傳送，見傳送本地檔案 |
版本
npm 包與 Rust 外掛同時釋出，版本號相同，兩邊必須使用同一個版本：引擎啟動時比較兩者，不同時以 unsupported（details.reason 為 version_mismatch）拒絕建立客戶端。請在 package.json 和 Cargo.toml 中都寫確切的版本號，升級時一起修改。
執行環境
| 系統 | 最低版本 | WebView | 系統通知 | 角標 | 音視訊通話 |
|---|---|---|---|---|---|
| Windows | 10（1809）、11，x64、Arm64 | WebView2（Chromium 100 以上） | Windows 通知 | 工作列按鈕上的數字圖示、工作列閃爍 | 支援 |
| macOS | 12，Intel 與 Apple 晶片 | 系統的 WKWebView，要求 Safari 已更新到 16.4 以上 | 通知中心 | 程式塢圖示上的數字、圖示跳動 | 支援 |
| Linux | x64、Arm64，WebKitGTK 4.1（2.40 以上）、GTK 3 | WebKitGTK | 桌面通知（freedesktop） | 支援 Unity 啟動器介面的桌面環境顯示數字 | 暫不支援 |
- Tauri 和 Rust：Tauri 2.12 以上，Rust 1.90 以上。
- WebView2 執行時：Windows 11 自帶；Windows 10 由 Tauri 的安裝包下載。不能訪問網際網路的內網環境，請讓安裝包內建 WebView2 執行時（Tauri 配置中的
bundle.windows.webviewInstallMode）。 - WebView 不滿足要求時（缺少
OffscreenCanvas、crypto.randomUUID等），建立客戶端時得到unsupported。本地儲存、視窗之間的協調由外掛提供，不依賴 WebView 的 IndexedDB、Web Locks 和 BroadcastChannel。 - 不支援 Tauri 的移動端（iOS、Android）：外掛在移動端編譯時直接報錯。手機 App 請使用 Flutter SDK。
- 平臺：SDK 按所在的系統自動以
windows、macos或linux登入，按平臺限制裝置數時算作電腦，與 Flutter 桌面端、Electron 中的 Web SDK 是同一類。應用設定為“電腦只能登入一臺”時，在 Tauri 應用中登入會把同一賬號在其他電腦上的登入擠下線，反過來也一樣。 - 與瀏覽器的關係：同一臺電腦上，瀏覽器中的網頁和 Tauri 應用是兩臺裝置，各自登入，本地資料互不共享。
各系統的限制
- Linux：
- 暫不支援音視訊通話：
im.calls.supported為false，發起和接聽以unsupported（calls_unavailable）拒絕；來電事件照常發出，可以提示使用者在手機上接聽。 - 錄音依賴發行版提供的 GStreamer 編碼器，不可用時
im.files.recordVoice()以unsupported拒絕，請隱藏錄音按鈕。 - 啟動器上的數字需要系統中裝有應用的
.desktop檔案，見角標。 - 暫不支援 Flatpak、Snap 打包（通知、檔案選擇、鑰匙串要經 XDG 門戶），請釋出
.deb或 AppImage。
- 暫不支援音視訊通話：
- Windows：系統通知要求應用經安裝包安裝，開發時直接執行的版本通知顯示為 PowerShell 發出，點選回不到應用，見打包與簽名。
- macOS：只發語音訊息的應用也要在
Info.plist中寫麥克風的用途說明，否則錄音時應用會被系統終止，見打包與簽名。
基本概念
引擎視窗與介面視窗
桌面 IM 通常在使用者關閉主視窗後縮到托盤繼續執行，並在收到訊息時提醒。所以 Tauri SDK 把長連線放在一個不顯示的引擎視窗中，它隨程序存在，不受你的視窗管理影響：
- 引擎視窗載入你提供的引擎頁，由外掛在應用啟動時建立，不顯示、不出現在工作列中。引擎持有長連線和登入令牌，負責同步、寫入本地資料、傳送訊息，以及沒有可見視窗時的提醒和來電。
- 介面視窗是你自己的視窗，可以有零個或多個。每個視窗用
createDRTauriClient()建立客戶端，直接讀取本地資料，需要請求服務端的操作由 SDK 轉給引擎執行。
這與 Web SDK 中多個標籤頁共用一個連線的方式相同，只是負責連線的固定是引擎視窗。詳見引擎與視窗。
與 Web SDK 相同的部分
可訂閱的列表（LiveList、MessageList）、本地優先和後臺同步、傳送佇列、事件和錯誤物件都與 Web SDK 相同，見 Web SDK 的基本概念。返回的訊息、會話、群等資料物件與服務端 REST API 中的物件欄位相同。
本地資料與令牌
本地資料儲存在應用資料目錄中的 SQLite 資料庫裡，登入令牌加密儲存，金鑰放在系統的鑰匙串中。令牌只在引擎中，介面視窗拿不到。詳見令牌與本地資料。
與服務端的關係
與 Web SDK 相同：你的業務服務端用 App Token 為使用者建立 IM 賬號，並在使用者登入你的業務系統後為他簽發登入憑證；應用從業務服務端取得憑證，交給 SDK 登入 IM，之後收發訊息、同步會話都由 SDK 直接與 IM 服務通訊。App Token 和 Client Secret 是服務端憑據，不能放進桌面應用中。
IM 服務的客戶端介面允許跨域呼叫，桌面應用不需要額外配置。檔案的上傳和下載由 Rust 外掛直接與檔案儲存通訊，也不需要為桌面應用配置檔案儲存的跨域規則。
與 Web SDK 的區別
| Web SDK | Tauri SDK |
|---|---|
createDRClient(options) | 引擎頁：createDRTauriEngine(options)；介面視窗：createDRTauriClient({ appKey }) |
選項 platform、deviceName | platform 自動按系統給出；deviceName 在引擎的選項中，預設為計算機名 |
選項 storage、tokenStorage、persistStorage、sessionScope | 沒有：資料儲存在 SQLite 中，令牌加密後儲存，金鑰在系統鑰匙串中 |
| 多個標籤頁選出一個主標籤頁 | 引擎視窗固定負責連線；im.connection.isLeader 在介面視窗中總是 false |
tabs.roleChanged | window.roleChanged：載荷相同，只有 isAlertTab 會變 |
| 瀏覽器通知由你用 Notification API 顯示 | 系統通知，預設由 SDK 自動顯示，見系統通知 |
| “正在看”要求頁面可見 | 還要求視窗獲得焦點：視窗被其他程式擋住時使用者沒有在看 |
接受檔案的引數為 Blob | Blob 或本地路徑 { path }，見傳送本地檔案 |
im.files.fetchBlob() 下載檔案內容 | 仍可用，適合小檔案；大檔案用 im.desktop.download() 儲存到磁碟 |
| 傳送佇列儲存不超過 50 MB 的附件 | 不超過 200 MB 的附件複製儲存，更大的記下路徑，應用重啟後繼續傳送 |
| — | im.desktop、engine.stateChanged 等桌面事件 |
暫不提供的功能
| 功能 | 說明 |
|---|---|
| Tauri 的移動端（iOS、Android） | 請使用 Flutter SDK |
| Linux 上的音視訊通話 | 見各系統的限制 |
| 離線推送（macOS 的 APNs、Windows 的 WNS） | 桌面應用依靠常駐的長連線收訊息，應用退出後收不到提醒 |
| 系統來電介面 | 桌面系統沒有類似手機的來電介面，來電由通知和你的視窗顯示 |
| 托盤圖示與選單、開機自啟、全域性快捷鍵、截圖 | 用 Tauri 的托盤介面和自啟動、全域性快捷鍵等外掛實現；SDK 提供未讀數和托盤閃爍的輔助，見托盤 |
| 介面元件 | 與 Web SDK 一樣不含介面元件 |
| 與瀏覽器中的網頁共用登入、遷移瀏覽器中的本地資料 | 兩者是不同的裝置，各自登入，登入後從服務端同步 |
| 同時登入多個賬號 | 一個 AppKey 同一時刻只有一個登入使用者，切換賬號要先退出 |
應用的連結（如 myapp://chat/…） | 用 Tauri 的深度連結外掛接收，再開啟對應的會話 |
| 通知中顯示傳送者的頭像、圖片縮圖 | 自動顯示的通知只有應用的圖示 |
| Linux 的 Flatpak、Snap 打包 | 見各系統的限制 |
獨立 RTC 頻道
im.channels 用於會議、語音房等不建群的音影片頻道，呼叫方式、媒體許可權和前後臺處理見頻道接入。Linux 的 WebKitGTK 是否帶 WebRTC 因發行版而異，各平臺的支援情況見版本與支援狀態。