命令列介面 (CLI)

GitHub npm crates.io

API 參考

Tauri 讓您的應用程式能夠透過 clap 擁有 CLI，clap 是一個強大的命令列參數解析器。透過在您的 tauri.conf.json 檔案中簡單的 CLI 定義，您可以定義您的介面並在 JavaScript 和/或 Rust 上讀取其參數匹配映射。

支援平台

此外掛程式需要至少 1.77.2 版本的 Rust

平台	層級	注意事項
windows
linux
macos
android
ios

• Windows
  • 由於作業系統限制，生產應用程式預設無法將文字寫回呼叫主控台。請查看 tauri#8305 以取得解決方案。

設定

安裝 CLI 外掛程式以開始使用。

自動

使用專案的套件管理器新增依賴

npm

npm run tauri add cli

yarn

yarn run tauri add cli

pnpm

pnpm tauri add cli

deno

deno task tauri add cli

bun

bun tauri add cli

cargo

cargo tauri add cli

手動

1. 在 src-tauri 資料夾中執行以下命令，將外掛程式新增至 Cargo.toml 中專案的依賴項

   cargo add tauri-plugin-cli --target 'cfg(any(target_os = "macos", windows, target_os = "linux"))'

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

   src-tauri/src/lib.rs

   #[cfg_attr(mobile, tauri::mobile_entry_point)]
   pub fn run() {
       tauri::Builder::default()
           .setup(|app| {
               #[cfg(desktop)]
               app.handle().plugin(tauri_plugin_cli::init());
               Ok(())
           })
           .run(tauri::generate_context!())
           .expect("error while running tauri application");
   }

   3. 使用您偏好的 JavaScript 套件管理器安裝 JavaScript Guest 綁定
   npm

   npm install @tauri-apps/plugin-cli

   yarn

   yarn add @tauri-apps/plugin-cli

   pnpm

   pnpm add @tauri-apps/plugin-cli

   deno

   deno add npm:@tauri-apps/plugin-cli

   bun

   bun add @tauri-apps/plugin-cli

基本設定

在 tauri.conf.json 下，您有以下結構來設定介面

src-tauri/tauri.conf.json

{
  "plugins": {
    "cli": {
      "description": "Tauri CLI Plugin Example",
      "args": [
        {
          "short": "v",
          "name": "verbose",
          "description": "Verbosity level"
        }
      ],
      "subcommands": {
        "run": {
          "description": "Run the application",
          "args": [
            {
              "name": "debug",
              "description": "Run application in debug mode"
            },
            {
              "name": "release",
              "description": "Run application in release mode"
            }
          ]
        }
      }
    }
  }
}

注意

此處的所有 JSON 設定僅為範例，為了清晰起見，省略了許多其他欄位。

新增參數

args 陣列代表其命令或子命令接受的參數清單。

位置參數

位置參數由其在參數清單中的位置識別。使用以下設定

src-tauri/tauri.conf.json

{
  "args": [
    {
      "name": "source",
      "index": 1,
      "takesValue": true
    },
    {
      "name": "destination",
      "index": 2,
      "takesValue": true
    }
  ]
}

使用者可以將您的應用程式作為 ./app tauri.txt dest.txt 執行，並且參數匹配映射將 source 定義為 "tauri.txt"，並將 destination 定義為 "dest.txt"。

具名參數

具名參數是 (鍵, 值) 對，其中鍵識別值。使用以下設定

tauri-src/tauri.conf.json

{
  "args": [
    {
      "name": "type",
      "short": "t",
      "takesValue": true,
      "multiple": true,
      "possibleValues": ["foo", "bar"]
    }
  ]
}

使用者可以將您的應用程式作為 ./app --type foo bar、./app -t foo -t bar 或 ./app --type=foo,bar 執行，並且參數匹配映射將 type 定義為 ["foo", "bar"]。

旗標參數

旗標參數是一個獨立的鍵，其存在與否為您的應用程式提供資訊。使用以下設定

tauri-src/tauri.conf.json

{
  "args": [
    {
      "name": "verbose",
      "short": "v"
    }
  ]
}

使用者可以將您的應用程式作為 ./app -v -v -v、./app --verbose --verbose --verbose 或 ./app -vvv 執行，並且參數匹配映射將 verbose 定義為 true，其中 occurrences = 3。

子命令

某些 CLI 應用程式具有作為子命令的其他介面。例如，git CLI 具有 git branch、git commit 和 git push。您可以使用 subcommands 陣列定義其他巢狀介面

tauri-src/tauri.conf.json

{
  "cli": {
    ...
    "subcommands": {
      "branch": {
        "args": []
      },
      "push": {
        "args": []
      }
    }
  }
}

其設定與根應用程式設定相同，具有 description、longDescription、args 等。

使用方式

CLI 外掛程式在 JavaScript 和 Rust 中皆可使用。

JavaScript

import { getMatches } from '@tauri-apps/plugin-cli';
// when using `"withGlobalTauri": true`, you may use
// const { getMatches } = window.__TAURI__.cli;

const matches = await getMatches();
if (matches.subcommand?.name === 'run') {
  // `./your-app run $ARGS` was executed
  const args = matches.subcommand.matches.args;
  if (args.debug?.value === true) {
    // `./your-app run --debug` was executed
  }
  if (args.release?.value === true) {
    // `./your-app run --release` was executed
  }
}

Rust

src-tauri/src/lib.rs

use tauri_plugin_cli::CliExt;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
   tauri::Builder::default()
       .plugin(tauri_plugin_cli::init())
       .setup(|app| {
           match app.cli().matches() {
               // `matches` here is a Struct with { args, subcommand }.
               // `args` is `HashMap<String, ArgData>` where `ArgData` is a struct with { value, occurrences }.
               // `subcommand` is `Option<Box<SubcommandMatches>>` where `SubcommandMatches` is a struct with { name, matches }.
               Ok(matches) => {
                   println!("{:?}", matches)
               }
               Err(_) => {}
           }
           Ok(())
       })
       .run(tauri::generate_context!())
       .expect("error while running tauri application");
}

權限

預設情況下，所有潛在危險的外掛程式命令和作用域都被封鎖且無法存取。您必須修改 capabilities 設定中的權限才能啟用這些。

有關更多資訊，請參閱功能概觀，以及使用外掛程式權限的逐步指南。

src-tauri/capabilities/default.json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": ["cli:default"]
}

預設權限

允許讀取 CLI 匹配項

• allow-cli-matches

權限表

識別符	描述
cli:allow-cli-matches	啟用 cli_matches 命令，無需任何預先設定的作用域。
cli:deny-cli-matches	拒絕 cli_matches 命令，無需任何預先設定的作用域。