【A11】Tauri v2 + 原生前端（无框架）项目笔记：从零到登录界面

一、环境准备

在开始之前，需要确保系统已安装以下工具：

Node.js（18+）：用于运行前端构建工具和 Tauri CLI
Rust：Tauri 后端使用 Rust 编写，需安装 Rust 工具链
系统依赖：Windows 需安装 WebView2（Win10 1803+ 通常自带）；macOS 需 Xcode Command Line Tools；Linux 需 webkit2gtk 等

验证安装：

bash 复制代码

node -v
cargo --version

如果 Rust 未安装，访问 rustup.rs 按提示安装即可。

二、创建 Tauri 项目

Tauri 官方推荐使用 create-tauri-app 工具来快速初始化项目。在你想存放项目的文件夹中执行：

bash 复制代码

npm create tauri-app@latest

系统会依次提示你进行以下选择：

项目名称 ：输入 a11
标识符（bundle identifier） ：例如 com.a11.app（全局唯一即可）
前端语言 ：选择 TypeScript / JavaScript
包管理器 ：选择 npm
UI 模板 ：选择 Vanilla（即无框架，纯 HTML/CSS/JS）
是否使用 TypeScript ：选择 Yes 或 No 均可

完成后，进入项目目录并安装依赖：

bash 复制代码

cd a11
npm install

然后启动开发模式验证：

bash 复制代码

npm run tauri dev

看到弹出的应用窗口就说明项目创建成功了。

三、理解项目结构

创建完成后，项目大致结构如下：

复制代码

a11/
├── src/                    # 前端源码（HTML/CSS/JS/TS）
│   ├── index.html
│   ├── styles.css
│   └── main.ts
├── src-tauri/              # Rust 后端
│   ├── src/
│   │   ├── lib.rs          # Rust 代码入口（主要修改这里）
│   │   └── main.rs         # 桌面端入口，一般不改
│   ├── capabilities/
│   │   └── default.json    # 权限配置文件
│   ├── icons/              # 应用图标
│   ├── tauri.conf.json     # Tauri 主配置文件
│   ├── Cargo.toml
│   └── build.rs
├── package.json
└── vite.config.ts

关键点：

tauri.conf.json 是 Tauri 的主配置文件，包含应用标识符、窗口设置、开发服务器地址等所有配置
capabilities/default.json 控制前端可以调用哪些 Tauri 命令，默认所有插件命令都被拦截，需要显式声明权限
src/lib.rs 是写 Rust 业务逻辑的地方，main.rs 只是桌面端入口，不需要修改

四、配置无框架（Vanilla）前端

使用 Vanilla 模板时，Tauri 需要一个前端开发服务器来提供 HTML/CSS/JS 文件。模板默认使用 Vite 作为构建工具。

在 vite.config.ts 中，需要添加一项配置，防止 Vite 监听 src-tauri 目录（否则 Rust 编译产生的文件变化会触发前端热更新，造成无限循环）：

ts 复制代码

export default defineConfig({
  // ...
  server: {
    watch: {
      ignored: ["**/src-tauri/**"],
    },
  },
});

这一配置在 Tauri 官方文档中有明确说明。

前端入口是 src/index.html，直接在其中编写 HTML 结构，CSS 放入 src/styles.css，JavaScript 逻辑放入 src/main.ts（或 .js）。由于没有框架，所有 DOM 操作都是原生 JavaScript。

五、实现登录界面

5.1 窗口配置

登录界面通常需要较小的窗口尺寸，并禁止用户调整大小。在 tauri.conf.json 的 app.windows 中配置：

json 复制代码

{
  "app": {
    "windows": [
      {
        "title": "a11",
        "width": 380,
        "height": 520,
        "resizable": false,
        "decorations": false,
        "center": true
      }
    ]
  }
}

decorations: false 会移除系统默认标题栏，让我们可以用 HTML/CSS 实现自定义标题栏
resizable: false 锁定窗口大小
center: true 让窗口居中显示

5.2 自定义标题栏与窗口控制

移除系统标题栏后，需要自己实现拖动窗口和最小化/关闭按钮。

拖动区域 ：在 HTML 中，给标题栏的拖动区域添加 data-tauri-drag-region 属性，用户按住该区域即可拖动窗口：

html 复制代码

<div class="titlebar__drag" data-tauri-drag-region>
  <span>a11</span>
</div>

窗口按钮 ：最小化和关闭按钮需要调用 Tauri 的窗口 API。在 Vanilla 模板中，Tauri v2 的 API 通过 window.__TAURI__ 全局对象暴露（注意 v2 中路径变为了 window.__TAURI__.core 和 window.__TAURI__.window）：

js 复制代码

// 最小化
document.getElementById('btn-min').addEventListener('click', async () => {
  const { getCurrentWindow } = window.__TAURI__.window;
  await getCurrentWindow().minimize();
});

// 关闭
document.getElementById('btn-close').addEventListener('click', async () => {
  const { getCurrentWindow } = window.__TAURI__.window;
  await getCurrentWindow().close();
});

5.3 配置窗口权限（关键步骤）

在 Tauri v2 中，前端调用任何窗口操作命令都需要在 capability 文件中声明权限，否则会被拦截。

打开 src-tauri/capabilities/default.json，在 permissions 数组中添加：

json 复制代码

{
  "permissions": [
    "core:default",
    "core:window:allow-close",
    "core:window:allow-minimize",
    "core:window:allow-start-dragging",
    "core:window:allow-toggle-maximize"
  ]
}

各权限的作用如下：

权限	作用
`core:window:allow-close`	允许关闭窗口
`core:window:allow-minimize`	允许最小化窗口
`core:window:allow-start-dragging`	允许通过拖动区域移动窗口
`core:window:allow-toggle-maximize`	允许最大化/还原窗口

注意：core:window:default 默认不包含 start-dragging，所以必须单独添加。如果没有添加 allow-start-dragging，data-tauri-drag-region 属性将不会生效。

5.4 登录表单逻辑

登录表单使用原生 HTML 表单元素，JavaScript 处理提交：

js 复制代码

document.getElementById('login-form').addEventListener('submit', async (e) => {
  e.preventDefault();
  const account = document.getElementById('account').value.trim();
  const password = document.getElementById('password').value;

  // 简单校验
  if (!account || !password) {
    showError('请输入账号和密码');
    return;
  }

  // 模拟登录请求（后续可替换为真实接口）
  try {
    // 这里可以调用 Tauri 的 invoke 与 Rust 后端通信
    // const { invoke } = window.__TAURI__.core;
    // const result = await invoke('login', { account, password });
    console.log('登录:', account);
  } catch (err) {
    showError('登录失败，请重试');
  }
});

如果需要与 Rust 后端通信（例如验证账号密码），可以在 src-tauri/src/lib.rs 中定义命令：

rust 复制代码

#[tauri::command]
fn login(account: String, password: String) -> Result<String, String> {
    if account == "admin" && password == "123456" {
        Ok("登录成功".into())
    } else {
        Err("账号或密码错误".into())
    }
}

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![login])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

前端通过 invoke 调用：

js 复制代码

const { invoke } = window.__TAURI__.core;
try {
  const msg = await invoke('login', { account, password });
  // 登录成功，可以跳转或关闭登录窗口
} catch (err) {
  showError(err);
}

5.5 记住账号与自动登录

利用 localStorage 保存用户选择：

js 复制代码

// 登录成功后保存
if (document.getElementById('remember').checked) {
  localStorage.setItem('a11_account', account);
}
if (document.getElementById('auto-login').checked) {
  localStorage.setItem('a11_auto_login', 'true');
}

// 页面加载时回填
window.addEventListener('DOMContentLoaded', () => {
  const saved = localStorage.getItem('a11_account');
  if (saved) {
    document.getElementById('account').value = saved;
    document.getElementById('remember').checked = true;
  }
  if (localStorage.getItem('a11_auto_login') === 'true') {
    document.getElementById('auto-login').checked = true;
  }
});

六、完整开发流程总结

复制代码

1. npm create tauri-app@latest
   → 项目名 a11，Vanilla 模板

2. cd a11 && npm install

3. 配置 vite.config.ts（忽略 src-tauri 目录）

4. 修改 tauri.conf.json
   → decorations: false, resizable: false, 窗口尺寸

5. 编辑 src/index.html + src/styles.css + src/main.ts
   → 实现登录界面 UI

6. 配置 capabilities/default.json
   → 添加窗口权限

7. 实现标题栏拖动 + 窗口按钮 + 登录表单逻辑

8. 可选：在 src-tauri/src/lib.rs 添加 Rust 命令

9. npm run tauri dev 测试

10. npm run tauri build 打包

常见问题与注意事项：

data-tauri-drag-region 不生效 ：检查 capabilities/default.json 中是否添加了 core:window:allow-start-dragging 权限。
Tauri API 未定义 ：确认使用的是 Tauri v2，API 路径为 window.__TAURI__.core（invoke）和 window.__TAURI__.window（窗口操作），而非 v1 的 window.__TAURI__.tauri。
Vite 无限热更新 ：务必在 vite.config.ts 中配置 server.watch.ignored: ["**/src-tauri/**"]。
双击标题栏无法最大化 ：Tauri 的 drag region 默认不处理双击最大化行为，需要手动监听 dblclick 事件并调用 toggleMaximize()。
窗口尺寸限制 ：登录窗口建议 resizable: false，登录成功后如需切换到主界面，可以创建新窗口或调整当前窗口尺寸，参考 Tauri 窗口 API 的 setSize 方法。