剪贴板与全局快捷键

这一章把两个小插件放一起讲——它们都很轻量，API 也不多，但组合起来能做不少实用功能。剪贴板插件让你读写系统剪贴板，全局快捷键插件让你注册像 Ctrl+Shift+C 这样的组合键，即使用户正用在别的软件里也能触发。

剪贴板插件：安装与注册

插件名是 tauri-plugin-clipboard-manager，注意不是 tauri-plugin-clipboard（短了）：

# 1. Rust 端
cd src-tauri
cargo add tauri-plugin-clipboard-manager

// 2. 注册插件
// src-tauri/src/lib.rs
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_clipboard_manager::init())
        .run(tauri::generate_context!())
        .expect("运行 Tauri 应用时出错");
}

# 3. 前端
npm install @tauri-apps/plugin-clipboard-manager

剪贴板插件的权限比较简单，加 clipboard-manager:default 就行：

{
  "permissions": [
    "core:default",
    "clipboard-manager:allow-write-text",
    "clipboard-manager:allow-read-text"
  ]
}

这里用了两个细粒度权限：allow-write-text 允许写剪贴板，allow-read-text 允许读剪贴板。如果你只写不读，就只加前者，遵循最小权限原则。

前端读写剪贴板

API 非常简洁，就两个函数：writeText 和 readText：

import { writeText, readText } from "@tauri-apps/plugin-clipboard-manager";

// 写入剪贴板
await writeText("Tauri is awesome!");

// 读取剪贴板
const content = await readText();
console.log(content); // Tauri is awesome!

就这么简单——写一段文本进去，读出来。这两个操作都是异步的，返回 Promise。readText 返回的是当前剪贴板里的文本内容；如果剪贴板里是图片或其他非文本格式，会返回空字符串或抛错。

Rust 端读写剪贴板

Rust 端通过 ClipboardExt trait 操作剪贴板：

use tauri_plugin_clipboard_manager::ClipboardExt;

// 写入剪贴板
app.clipboard()
    .write_text("Tauri is awesome!".to_string())
    .unwrap();

// 读取剪贴板
let content = app.clipboard().read_text();
println!("{}", content.unwrap()); // Tauri is awesome!

app.clipboard() 返回一个剪贴板句柄，write_text 接受 String，read_text 返回 Result<String, _>。Rust 端的调用是同步的，不需要 async。

全局快捷键插件：安装与注册

全局快捷键（global shortcut）是指即使你的应用窗口不在前台，用户按下特定组合键也能触发的快捷键。比如截图工具按 Ctrl+Shift+A 开始截屏，音乐播放器按 Ctrl+Alt+P 播放暂停。

插件名是 tauri-plugin-global-shortcut。这个插件只在桌面端可用（Windows、macOS、Linux），移动端没有全局快捷键概念：

# 1. Rust 端
cd src-tauri
cargo add tauri-plugin-global-shortcut --target 'cfg(any(target_os = "macos", windows, target_os = "linux"))'

// 2. 注册插件
// src-tauri/src/lib.rs
pub fn run() {
    tauri::Builder::default()
        .setup(|app| {
            #[cfg(desktop)]
            app.handle().plugin(
                tauri_plugin_global_shortcut::Builder::new().build()
            );
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("运行 Tauri 应用时出错");
}

# 3. 前端
npm install @tauri-apps/plugin-global-shortcut

注意注册方式和大多数插件不同——不是 .plugin(xxx::init()) 而是用 Builder::new().build()，并且放在 setup 回调里，用 #[cfg(desktop)] 确保只在桌面端编译。这是因为全局快捷键依赖平台 API，移动端编译会报错。

前端注册全局快捷键

前端 API 也很直接：

import { register } from "@tauri-apps/plugin-global-shortcut";

// 注册一个全局快捷键
await register("CommandOrControl+Shift+C", () => {
  console.log("快捷键触发了！");
});

register 接受两个参数：快捷键组合字符串和回调函数。CommandOrControl 是个跨平台写法——在 macOS 上是 Command 键，在 Windows/Linux 上是 Ctrl 键。你还可以用 Ctrl、Alt、Shift、Super（Windows 键/⌘）等修饰键，加上具体键名如 KeyA、KeyF1、Digit1 等。

注销单个快捷键用 unregister，全部注销用 unregisterAll：

import { register, unregister, unregisterAll } from "@tauri-apps/plugin-global-shortcut";

// 注销一个
await unregister("CommandOrControl+Shift+C");

// 注销所有
await unregisterAll();

检查某个快捷键是否已注册用 isRegistered：

import { isRegistered } from "@tauri-apps/plugin-global-shortcut";

const registered = await isRegistered("CommandOrControl+Shift+C");
console.log("已注册？", registered);

前端调用需要在 capability 里授权：

{
  "permissions": [
    "global-shortcut:allow-register",
    "global-shortcut:allow-unregister",
    "global-shortcut:allow-is-registered"
  ]
}

Rust 端注册全局快捷键

Rust 端注册全局快捷键更强大，可以区分按下和释放两个事件。在 setup 里注册：

pub fn run() {
    tauri::Builder::default()
        .setup(|app| {
            #[cfg(desktop)]
            {
                use tauri_plugin_global_shortcut::{
                    Code, GlobalShortcutExt, Modifiers, Shortcut, ShortcutState,
                };

                // 定义快捷键：Ctrl + N
                let ctrl_n = Shortcut::new(Some(Modifiers::CONTROL), Code::KeyN);

                app.handle().plugin(
                    tauri_plugin_global_shortcut::Builder::new()
                        .with_handler(move |_app, shortcut, event| {
                            if shortcut == &ctrl_n {
                                match event.state() {
                                    ShortcutState::Pressed => {
                                        println!("Ctrl+N 按下了！");
                                    }
                                    ShortcutState::Released => {
                                        println!("Ctrl+N 释放了！");
                                    }
                                }
                            }
                        })
                        .build(),
                )?;

                // 注册快捷键
                app.global_shortcut().register(ctrl_n)?;
            }
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("运行 Tauri 应用时出错");
}

这里有几个关键点：

• Shortcut::new(modifiers, code): 创建快捷键定义。Modifiers::CONTROL 是 Ctrl 键，Code::KeyN 是 N 键。多个修饰键用 | 组合：Modifiers::CONTROL | Modifiers::SHIFT。
• with_handler: 注册一个回调函数，参数是 _app（AppHandle）、shortcut（触发的快捷键）和 event（事件对象）。
• event.state(): 返回 ShortcutState::Pressed 或 ShortcutState::Released，让你区分按下和松开。
• app.global_shortcut().register(shortcut): 真正注册快捷键，让操作系统开始监听。

快捷键字符串语法速查

前端 register 用字符串表示快捷键，格式是 修饰键+键名，用 + 连接。常用写法：

快捷键字符串	含义
CommandOrControl+Shift+C	Ctrl+Shift+C（Win）或 ⌘+Shift+C（Mac）
Ctrl+Alt+P	Ctrl+Alt+P
Super+Space	Win键+空格 / ⌘+空格
CommandOrControl+KeyF1	Ctrl+F1 / ⌘+F1
Alt+Digit1	Alt+1

CommandOrControl 是最常用的跨平台修饰键写法，强烈推荐用它代替单独的 Control 或 Super。

小结

剪贴板插件（tauri-plugin-clipboard-manager）提供 writeText / readText 两个简单 API，前端和 Rust 端都能用，适合存取用户复制的文本内容。全局快捷键插件（tauri-plugin-global-shortcut）让你注册系统级键盘组合，应用不在前台也能响应：前端用 register("CommandOrControl+Shift+C", callback) 一行搞定，Rust 端用 Shortcut::new + with_handler 能区分按下和释放事件。快捷键字符串用 修饰键+键名 格式，CommandOrControl 跨平台映射到 Ctrl 或 ⌘。两个插件都只在桌面端有效（剪贴板插件移动端也支持，但全局快捷键仅桌面），注册时注意用 #[cfg(desktop)] 条件编译。