---
title: 使用插件权限
sidebar:
  order: 10
i18nReady: true
---

import { Steps } from '@astrojs/starlight/components';
import ShowSolution from '@components/ShowSolution.astro'
import Cta from '@fragments/cta.mdx';

本实验的目标是更好地了解如何启用或禁用插件权限、在哪里描述它们以及如何使用插件的默认权限。

最后，你将能够查找和使用任意插件的权限，并了解如何自定义现有权限。
你将获得一个 Tauri 示例应用程序，其中使用了一个插件和插件特定的权限。

<Steps>

1. ### 创建 Tauri 应用程序

    创建你的 Tauri 应用程序。
    在我们的示例中，我们将使用 [`create-tauri-app`](https://github.com/tauri-apps/create-tauri-app) ：

    <Cta />

    我们将使用 `pnpm` 进行逐步解释，但你可以选择其他包管理器并在命令中相应地替换它。


    <ShowSolution>
    ```
    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
    ```
    </ShowSolution>

2. ### 将 `file-system` 插件添加到你的应用程序中

    要搜索现有的插件，你可以使用多个资源。

    最直接的方法是检查你的插件是否已在文档的 [插件](/plugin/) 部分中，
    此处是 Tauri 维护的插件集的一部分。
    文件系统插件是 Tauri 插件工作区的一部分，你可以按照 [设置](/plugin/file-system/#permission-table) 将其添加到你的项目中。

    如果该插件是社区努力的一部分，那么你最有可能在 [crates.io](https://crates.io/search?q=tauri-plugin-) 
    上搜索 `tauri-plugin-<your plugin name>` 时找到它。

    <ShowSolution>
    如果它是我们工作区中现有的插件，你可以使用自动化方式：

    ```
    pnpm tauri add fs
    ```

    如果你在 [crates.io](https://crates.io/crates/tauri-plugin-fs) 上找到它
    你需要手动将其添加为依赖项并修改 Tauri 构建器初始化插件：

    ```sh
    cargo add tauri-plugin-fs
    ```

    修改 `lib.rs` 来初始化插件:

    ```rust title="src-tauri/src/lib.rs" ins={4}
    #[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");
    }
    ```
    </ShowSolution>

3. ### 了解 `fs` 插件的默认权限
    
    每个插件都有一组 `default` 权限集，其中包含使用插件所需的所有权限和范围，
    以及使用插件的合理的最小功能集。
    
    对于官方维护的插件，你可以在文档中找到相关描述
    （例如 [fs default](/plugin/file-system/#default-permission) ）。

    In case you are figuring this out for a community plugin you
    need to check out the source code of the plugin.
    This should be defined in `your-plugin/permissions/default.toml`.
    如果你要查看社区插件的默认权限集，则需要查看该插件的源代码。
    这应该在 `your-plugin/permissions/default.toml` 中定义。

    <ShowSolution>
    ```toml
    "$schema" = "schemas/schema.json"

    [default]
    description = """
    # Tauri `fs` 插件的默认权限集

    这个配置文件定义了授予文件系统的默认权限。

    ### 已授予的权限

    这个默认的权限集启用了所有与读取相关的命令，
    并允许访问 `$APP` 文件夹及其在运行时创建的子目录。
    `$APP` 文件夹的具体位置取决于操作系统以及应用程序的运行方式。

    一般来说，`$APP` 文件夹需要由应用程序在运行时手动创建，之后才能访问其中的文件或子目录。

    ### 被拒绝的权限

    该默认权限集默认阻止对 Tauri 应用程序中关键组件的访问。
    在 Windows 上，默认会禁止访问 WebView 数据文件夹 。

    """
    permissions = ["read-all", "scope-app-recursive", "deny-default"]

    ```
    </ShowSolution>

4. ### 找到正确的权限
      
    此步骤是关于找到你需要的权限，以便以最少的系统访问权限将实现你的命令并公开到前端。

    `fs` 插件具有自动生成的权限，可以禁用或启用单个命令并允许或禁用全局范围。

    这些可以在 [文档](/plugin/file-system/#permission-table) 中找到，
    也可以在插件源代码中找到（`fs/permissions/autogenerated`）。

    假设我们想要启用写入位于用户的 `$HOME` 文件夹中的文本文件 `test.txt`。

    为此，我们将在自动生成的权限中搜索允许写入文本文件的权限，
    例如 `allow-write-text-file` ，然后是允许我们访问 `$HOME/test.txt` 范围内的文件。

    我们需要将这些添加到我们的 `capabilities` 部分，在 `src-tauri/tauri.conf.json` 
    文件中或 `src-tauri/capabilities/` 文件夹中的某个文件。
    默认情况下， `src-tauri/capabilities/default.json` 中已包含我们可以修改的权限。

    <ShowSolution>

    ```json title="src-tauri/capabilities/default.json" del={18} ins={19}
    {
      "$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",
      ]
    }
    ```

    </ShowSolution>

    由于 `fs` 插件中只有自动生成的范围可以访问完整的 `$HOME` 文件夹，
    因此我们需要配置自己的范围。此范围应仅对 `write-text-file` 命令启用，
    并且应仅包含我们的 `test.txt` 文件。

    <ShowSolution>
    ```json title="src-tauri/capabilities/default.json" del={18} ins={19-22}
       {
      "$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" }]
        },
      ]
    }
    ```
    </ShowSolution>
    
5. ### 在实践中测试权限

    添加必要的权限后，我们要确认我们的应用程序可以访问该文件并写入其内容。

    <ShowSolution>
    我们可以在我们的应用程序中使用这个代码片段来写入文件：

    ```ts title="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
    ```

    写入输入框并单击“提交”后，我们可以通过终端或手动打开主文件夹中的文件进行检查。

    ```
    cat $HOME/test.txt
    ```

    你应该会看到你的输入，然后就完成了有关在 Tauri 应用程序中使用插件权限的学习。🥳


    如果你遇到此错误：

    ```sh
    [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)
    ```
    那么你很可能没有正确遵循 [先前的指示](#找到正确的权限).

    </ShowSolution>

 </Steps>   
