Positioner（ウィンドウ配置）

《訳注》

Plugin 説明内容の英語表記部分について　Plugin の各章は、原文データからページ内容の一部が自動生成されているため、英語表記のままの部分があります。

GitHub npm crates.io

API Reference

ウィンドウをよく知られた場所に配置します。

このプラグインは、electron-positioner を Tauri に移植したものです。

対応プラットフォーム

This plugin requires a Rust version of at least 1.77.2

Platform	Level	Notes
windows
linux
macos
android
ios

セットアップ

はじめに、「positioner」プラグインをインストールしてください。

ノート

Rust コードからウィンドウの移動を行なうだけの場合は、src-tauri/Cargo.toml 内の依存関係のみが必要です。したがって、以下の「自動」セットアップを選択した場合は lib.rs から「プラグインの登録」を削除できます。

自動で設定

自分のプロジェクトのパッケージ・マネージャーを使用して依存関係を追加します：

npm

npm run tauri add positioner

yarn

yarn run tauri add positioner

pnpm

pnpm tauri add positioner

deno

deno task tauri add positioner

bun

bun tauri add positioner

cargo

cargo tauri add positioner

手動で設定

1. src-tauri フォルダで次のコマンドを実行して、このプラグインを Cargo.toml 内のプロジェクトの依存関係に追加します：

   cargo add tauri-plugin-positioner --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_positioner::init());
               Ok(())
           })
           .run(tauri::generate_context!())
           .expect("error while running tauri application");
   }

3. お好みの JavaScript パッケージ・マネージャーを使用して、「JavaScript Guest」バインディングをインストールします：

   npm

   npm install @tauri-apps/plugin-positioner

   yarn

   yarn add @tauri-apps/plugin-positioner

   pnpm

   pnpm add @tauri-apps/plugin-positioner

   deno

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

   bun

   bun add @tauri-apps/plugin-positioner

「トレイの相対配置」を機能させるには追加の設定が必要です。

1. Cargo.toml ファイルに tray-icon 機能を追加します：

   src-tauri/Cargo.toml

   [dependencies]
   tauri-plugin-positioner = { version = "2.0.0", features = ["tray-icon"] }

2. 「positioner」プラグインに on_tray_event を設定します：

   src-tauri/src/lib.rs

   pub fn run() {
       tauri::Builder::default()
           // これは「トレイ相対配置」を機能させるために必要です
           .setup(|app| {
               #[cfg(desktop)]
               {
                   app.handle().plugin(tauri_plugin_positioner::init());
                       tauri::tray::TrayIconBuilder::new()
                           .on_tray_icon_event(|tray_handle, event| {
                               tauri_plugin_positioner::on_tray_event(tray_handle.app_handle(), &event);
                           })
                           .build(app)?;
               }
           Ok(())
       })
       .run(tauri::generate_context!())
       .expect("error while running tauri application");
   }

使用法

このプラグインの API は、「JavaScript Guest」バインディングを通じて利用できます：

import { moveWindow, Position } from '@tauri-apps/plugin-positioner';
// `"withGlobalTauri": true` を使用する場合は、
// const { moveWindow, Position } = window.__TAURI__.positioner; を使用できます

moveWindow(Position.TopRight);

Rust を通して Window 特性拡張（trait extention）を直接インポートして使用することができます：

use tauri_plugin_positioner::{WindowExt, Position};

let mut win = app.get_webview_window("main").unwrap();
let _ = win.as_ref().window().move_window(Position::TopRight);

アクセス権限 Permissions

デフォルトでは、潜在的に危険なプラグイン・コマンドとそのスコープ（有効範囲）はすべてブロックされており、アクセスできません。これらを有効にするには、capabilities 設定でアクセス権限を変更する必要があります。

詳細については「セキュリティ・レベル Capabilities」の章を参照してください。また、プラグインのアクセス権限を設定するには「プライグン・アクセス権の使用」の章のステップ・バイ・ステップ・ガイドを参照してください。

src-tauri/capabilities/default.json

{
  "permissions": [
    ...,
    "positioner:default",
  ]
}

Default Permission

Allows the moveWindow and handleIconState APIs

This default permission set includes the following:

• allow-move-window
• allow-move-window-constrained
• allow-set-tray-icon-state

Permission Table

Identifier	Description
positioner:allow-move-window	Enables the move_window command without any pre-configured scope.
positioner:deny-move-window	Denies the move_window command without any pre-configured scope.
positioner:allow-move-window-constrained	Enables the move_window_constrained command without any pre-configured scope.
positioner:deny-move-window-constrained	Denies the move_window_constrained command without any pre-configured scope.
positioner:allow-set-tray-icon-state	Enables the set_tray_icon_state command without any pre-configured scope.
positioner:deny-set-tray-icon-state	Denies the set_tray_icon_state command without any pre-configured scope.

【※ この日本語版は、「Feb 22, 2025 英語版」に基づいています】