使用外掛程式權限

本練習的目標是更好地理解如何啟用或停用外掛程式權限、權限的描述位置，以及如何使用外掛程式的預設權限。

最後，您將能夠找到並使用任意外掛程式的權限，並了解如何自訂現有權限。您將會有一個 Tauri 應用程式範例，其中使用了外掛程式和外掛程式特定的權限。

1. 建立 Tauri 應用程式

   建立您的 Tauri 應用程式。在我們的範例中，我們將使用 create-tauri-app

   Bash

   sh <(curl https://create.tauri.app/sh)

   PowerShell

   irm https://create.tauri.app/ps | iex

   Fish

   sh (curl -sSL https://create.tauri.app/sh | psub)

   npm

   npm create tauri-app@latest

   Yarn

   yarn create tauri-app

   pnpm

   pnpm create tauri-app

   deno

   deno run -A npm:create-tauri-app

   bun

   bun create tauri-app

   Cargo

   cargo install create-tauri-app --locked
   cargo create-tauri-app

   在此逐步說明中，我們將使用 pnpm，但您可以選擇其他套件管理器，並在命令中相應地替換它。

   顯示解決方案

   pnpm create tauri-app

   ✔ Project name · plugin-permission-demo
   ✔ Choose which language to use for your frontend · TypeScript / JavaScript - (pnpm, yarn, npm, bun)
   ✔ Choose your package manager · pnpm
   ✔ Choose your UI template · Vanilla
   ✔ Choose your UI flavor · TypeScript
   
   Template created! To get started run:
   cd plugin-permission-demo
   pnpm install
   pnpm tauri dev

2. 將 file-system 外掛程式新增至您的應用程式

   您可以使用多種資源來搜尋現有的外掛程式。

   最直接的方式是查看您的外掛程式是否已在文件中的外掛程式章節中，並且是 Tauri 維護的外掛程式集的一部分。Filesystem 外掛程式是 Tauri 外掛程式工作區的一部分，您可以按照指示將其新增至您的專案。

   如果外掛程式是社群貢獻的一部分，您很可能可以在 crates.io 上找到它，方法是搜尋 tauri-plugin-<您的外掛程式名稱>。

   顯示解決方案

   如果是我們工作區中現有的外掛程式，您可以使用自動化方式

   pnpm tauri add fs

   如果您在 crates.io 上找到它，您需要手動將其新增為依賴項，並修改 Tauri builder 以初始化外掛程式

   cargo add tauri-plugin-fs

   修改 lib.rs 以初始化外掛程式

   src-tauri/src/lib.rs

   #[cfg_attr(mobile, tauri::mobile_entry_point)]
   fn run() {
     tauri::Builder::default()
       .plugin(tauri_plugin_fs::init())
       .run(tauri::generate_context!())
       .expect("error while running tauri application");
   }

3. 了解 fs 外掛程式的預設權限

   每個外掛程式都有一個 預設 權限集，其中包含所有權限和範圍，以便開箱即用地使用外掛程式，並具有合理的最小功能集。

   對於官方維護的外掛程式，您可以在文件中找到渲染的描述（例如 fs 預設）。

   如果您要找出社群外掛程式的權限，您需要查看外掛程式的原始程式碼。這應該在 your-plugin/permissions/default.toml 中定義。

   顯示解決方案

   "$schema" = "schemas/schema.json"
   
   [default]
   description = """
   # Tauri `fs` default permissions
   
   This configuration file defines the default permissions granted
   to the filesystem.
   
   ### Granted Permissions
   
   This default permission set enables all read-related commands and
   allows access to the `$APP` folder and sub directories created in it.
   The location of the `$APP` folder depends on the operating system,
   where the application is run.
   
   In general the `$APP` folder needs to be manually created
   by the application at runtime, before accessing files or folders
   in it is possible.
   
   ### Denied Permissions
   
   This default permission set prevents access to critical components
   of the Tauri application by default.
   On Windows the webview data folder access is denied.
   
   """
   permissions = ["read-all", "scope-app-recursive", "deny-default"]

4. 找到正確的權限

   此步驟的重點是找到您需要的權限，以便將您的指令公開給前端，並以最小的系統存取權限。

   fs 外掛程式具有自動產生的權限，這些權限將停用或啟用個別指令，並允許或停用全域範圍。

   這些可以在文件或外掛程式的原始程式碼 (fs/permissions/autogenerated) 中找到。

   假設我們要啟用寫入位於使用者 $HOME 資料夾中的文字檔 test.txt。

   為此，我們會在自動產生的權限中搜尋啟用寫入文字檔的權限，例如 allow-write-text-file，然後搜尋允許我們存取 $HOME/test.txt 檔案的範圍。

   我們需要將這些新增到 src-tauri/tauri.conf.json 中的 capabilities 區段，或 src-tauri/capabilities/ 資料夾中的檔案中。預設情況下，src-tauri/capabilities/default.json 中已經有一個功能，我們可以修改。

   顯示解決方案

   src-tauri/capabilities/default.json

   {
     "$schema": "../gen/schemas/desktop-schema.json",
     "identifier": "default",
     "description": "Capability for the main window",
     "windows": [
       "main"
     ],
     "permissions": [
       "path:default",
       "event:default",
       "window:default",
       "app:default",
       "image:default",
       "resources:default",
       "menu:default",
       "tray:default",
       "shell:allow-open",
       "fs:default",
       "fs:allow-write-text-file",
     ]
   }

   由於 fs 外掛程式中只有自動產生的範圍可以存取完整的 $HOME 資料夾，因此我們需要設定自己的範圍。此範圍應僅針對 write-text-file 指令啟用，並且僅公開我們的 test.txt 檔案。

   顯示解決方案

   src-tauri/capabilities/default.json

      {
     "$schema": "../gen/schemas/desktop-schema.json",
     "identifier": "default",
     "description": "Capability for the main window",
     "windows": [
       "main"
     ],
     "permissions": [
       "path:default",
       "event:default",
       "window:default",
       "app:default",
       "image:default",
       "resources:default",
       "menu:default",
       "tray:default",
       "shell:allow-open",
       "fs:allow-write-text-file",
       {
         "identifier": "fs:allow-write-text-file",
         "allow": [{ "path": "$HOME/test.txt" }]
       },
     ]
   }

5. 在實務中測試權限

   新增必要的權限後，我們要確認我們的應用程式可以存取檔案並寫入其內容。

   顯示解決方案

   我們可以在應用程式中使用此程式碼片段來寫入檔案

   src/main.ts

   import { writeTextFile, BaseDirectory } from '@tauri-apps/plugin-fs';
   
   let greetInputEl: HTMLInputElement | null;
   
   async function write(message: string) {
       await writeTextFile('test.txt', message, { baseDir: BaseDirectory.Home });
   }
   
   window.addEventListener("DOMContentLoaded", () => {
     greetInputEl = document.querySelector("#greet-input");
     document.querySelector("#greet-form")?.addEventListener("submit", (e) => {
       e.preventDefault();
       if (!greetInputEl )
         return;
   
       write(greetInputEl.value == "" ? "No input provided": greetInputEl.value);
   
     });
   });

   將 src/main.ts 替換為此程式碼片段表示我們在使用純 Vanilla+Typescript 應用程式時，不需要修改預設的 index.html。在執行中的應用程式的輸入欄位中輸入任何內容，將在提交時寫入檔案。

   現在讓我們在實務中測試

   pnpm run tauri dev

   在輸入內容並點擊「提交」後，我們可以透過終端機模擬器檢查，或手動開啟您 home 資料夾中的檔案。

   cat $HOME/test.txt

   您應該會看到您的輸入，並完成學習如何在 Tauri 應用程式中使用外掛程式的權限。🥳

   如果您遇到此錯誤

   [Error] Unhandled Promise Rejection: fs.write_text_file not allowed. Permissions associated with this command: fs:allow-app-write, fs:allow-app-write-recursive, fs:allow-appcache-write, fs:allow-appcache-write-recursive, fs:allow-appconf...
   (anonymous function) (main.ts:5)

   那麼您很可能沒有正確遵循先前的指示。