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));

能做什么

界面窗口中的客户端对象 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 频道

已提供独立频道接入源码，调用 API、媒体权限与前后台边界见频道接入。频道版本制品尚未发布，实际支持和验收范围见平台表。