Skip to content
Ratatui

Hello world

このチュートリアルでは、画面の中央にテキストを表示し、ユーザーが Q を押して終了するのを待つシンプルな「Hello World」TUIアプリを作成することができます。ここでは、 Ratatui で開発されるアプリケーションに必要な作業を説明します。ターミナルの基本的な理解があり、テキストエディターまたはRust IDEを持っていることを前提としています。特に好みがない場合、vscode がお勧めです。

次のようなものを構築します。

hello

このチュートリアルの完全なコードは、https://github.com/ratatui/ratatui-website/tree/main/code/tutorials/hello-world で見ることができます。

Rust をインストールする

最初のステップは、Rust をインストールすることです。 詳細については、公式 Rust Book の[インストール]セクションを参照してください。 ほとんどの人は、 Rust バージョンと関連するツールを管理するためのコマンドラインツールである rustup を使用します。

Rustをインストールしたら、実行してインストールされていることを確認してください。

check rust version
rustc --version

次のような出力が表示されるはずです (正確なバージョン、日付、およびコミットハッシュは異なります) 。

rustc 1.80.1 (3f5fd8dd4 2024-08-06)

新しいプロジェクトを作成する

新しいRustプロジェクトを作成しましょう。ターミナルで、プロジェクトを保存して実行するフォルダーに移動します。

create new rust project
cargo new hello-ratatui
cd hello-ratatui

cargo new コマンドは、基本的なバイナリアプリケーションを備えた hello-ratatui という新しいフォルダーを作成します。次のように表示されます。

Created binary (application) `hello-ratatui` package

作成したフォルダーとファイルを調べた場合、これは次のようになります。

hello-ratatui/
├── src/
│  └── main.rs
└── Cargo.toml

cargo new コマンドで “Hello, world!” と表示する小さなコンソール プログラムを含むデフォルトの main.rs を作成します。

main.rs
fn main() {
    println!("Hello, world!");
}

プロジェクトをビルドして実行しましょう。

run the app
cargo run

次のように表示されます。

   Compiling hello-ratatui v0.1.0 (/Users/joshka/local/hello-ratatui)
    Finished dev [unoptimized + debuginfo] target(s) in 0.18s
     Running `target/debug/hello-ratatui`
Hello, world!

デフォルトの main.rs プログラムは、最後の行の表示を担当します。もう少しエキサイティングなものに置き換えます。

Ratatui をインストールする

まず、Ratatui Crateをプロジェクトにインストールする必要があります。[バックエンド]をインストールする必要もあります。このチュートリアルでは、ほとんどのオペレーティングシステムと互換性があるため、Crosstermをバックエンドとして使用します。 ratatui および crossterm クレートの最新バージョンをプロジェクト実行にインストールするには:

install ratatui and crossterm
cargo add ratatui crossterm

cargoは次の出力を出力します (正確なバージョンは、このチュートリアルのバージョンよりも遅くなる可能性があることに注意してください) 。

    Updating crates.io index
      Adding ratatui v0.28.1 to dependencies
             Features:
             + crossterm
             + underline-color
             - all-widgets
             - document-features
             - macros
             - palette
             - serde
             - termion
             - termwiz
             - unstable
             - unstable-rendered-line-info
             - unstable-widget-ref
             - widget-calendar
    Updating crates.io index
     Locking 66 packages to latest compatible versions
      Adding hermit-abi v0.3.9 (latest: v0.4.0)
      Adding linux-raw-sys v0.4.14 (latest: v0.6.5)
      Adding wasi v0.11.0+wasi-snapshot-preview1 (latest: v0.13.2+wasi-0.2.1)
      Adding windows-sys v0.52.0 (latest: v0.59.0)

Cargo.toml ファイルを調べると、新しいクレートが依存関係セクションに追加されていることがわかります。

Cargo.toml
[dependencies]
ratatui = "0.28.1"

TUI アプリケーションを作成する

画面の中央に色付きのメッセージを表示し、ユーザーがキーを押して終了するのを待っているratatuiアプリケーションで作成された cargo new であるデフォルトのコンソールアプリケーションコードを置き換えましょう。

注: コードの完全なコピーは、 Run the application _セクションの以下に入手できます。

Import を追加する

まず、アプリケーションの実行に必要なモジュールインポートを追加しましょう。

  • std から io モジュールをインポートします。
  • ratatui から次のものをインポートします:
    • crossterm::event モジュール (および KeyEvent と KeyEventKind 型)。これらの型の詳細については、[Crosstermドキュメント] を参照してください。これは Crossterm クレートから再エクスポートされます。
    • Stylize は、他の型に [スタイル ショートハンド] を追加する拡張trait です。
    • Paragraph ウィジェットは、テキストの表示に使用されます。
    • DefaultTerminal は、ターミナルに出力するための手段を提供します。エディターで、 src/main.rs を開き、ファイルの上部に次のように追加します。
main.rs
use std::io;


use ratatui::{
    crossterm::event::{self, KeyCode, KeyEventKind},
    style::Stylize,
    widgets::Paragraph,
    DefaultTerminal,
};

ターミナルを初期化する

次に、メイン関数にコードを追加して、ターミナル状態をセットアップおよび復元します。

使用するためにターミナルをセットアップするために、私たちのアプリケーションはいくつかのことをする必要があります。

  • まず、アプリケーションは [代替画面] に入ります。これは、シェル内のターミナル アプリの通常の出力を妨げずに、アプリケーションが必要なものをすべてレンダリングできるセカンダリ画面です。
  • 次に、アプリケーションは [raw モード] を有効にします。これにより、ターミナルによる入出力処理がオフになります。これにより、アプリケーションは画面に文字を出力するタイミングを制御できます。
  • 次に、アプリケーションは [バックエンド] と [Terminal] を作成し、画面をクリアします。

アプリケーションが終了したら、代替画面を離れて生モードを無効にすることにより、ターミナル状態を復元する必要があります。

既存の main 関数をコードに置き換えて、ターミナルをセットアップおよび復元します。

main.rs
fn main() -> io::Result<()> {
    let mut terminal = ratatui::init();
    terminal.clear()?;
1 collapsed line
    let app_result = run(terminal);
    ratatui::restore();
1 collapsed line
    app_result
}

メインループを実行する

アプリケーションの主要部分はメインループです。アプリケーションはUIを繰り返し描画し、発生したイベントを処理します。

run() という名前のメソッドを作成し、メイン関数から呼び出します。

main.rs
fn main() -> io::Result<()> {
    let mut terminal = ratatui::init();
    terminal.clear()?;
    let app_result = run(terminal);
    ratatui::restore();
    app_result
}
main.rs
fn run(mut terminal: DefaultTerminal) -> io::Result<()> {
    loop {
12 collapsed lines
        terminal.draw(|frame| {
            let greeting = Paragraph::new("Hello Ratatui! (press 'q' to quit)")
                .white()
                .on_blue();
            frame.render_widget(greeting, frame.area());
        })?;


        if let event::Event::Key(key) = event::read()? {
            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
                return Ok(());
            }
        }
    }
}

ターミナルに描く

Terminal::drawメソッドは、アプリがRATATUIに持っている主な相互作用ポイントです。 draw メソッドは、単一のFrameパラメーターを備えた閉鎖 (匿名メソッド) を受け入れ、画面全体をレンダリングします。アプリケーションは、ターミナルウィンドウのフルサイズの領域を作成し、白い前景テキストと青色の背景を備えた新しい段落をレンダリングします。

次のコードを run メソッドに追加します。

main.rs
fn run(mut terminal: DefaultTerminal) -> io::Result<()> {
    loop {
        terminal.draw(|frame| {
            let greeting = Paragraph::new("Hello Ratatui! (press 'q' to quit)")
                .white()
                .on_blue();
            frame.render_widget(greeting, frame.area());
        })?;
6 collapsed lines


        if let event::Event::Key(key) = event::read()? {
            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
                return Ok(());
            }
        }
    }
}

ratatui docで white() および on_blue() メソッドを見つける場所を疑問に思っている場合、これらはStylize拡張trait で[スタイルショートハンド]として定義されています。

キーボードイベントを処理する

Ratatuiがフレームを描いた後、アプリケーションがイベントが発生したかどうかを確認する必要があります。これらは、キーボードプレス、マウスイベント、サイズ化などのようなものです。ユーザーが q キーを押した場合、アプリはループから抜け出す必要があります。

イベントの種類が Press であることを確認することが重要です。そうしないと、Windowsターミナルが各キーが2回表示されることを確認します。

次のコードを run メソッドに追加します。

main.rs
fn run(mut terminal: DefaultTerminal) -> io::Result<()> {
    loop {
7 collapsed lines
        terminal.draw(|frame| {
            let greeting = Paragraph::new("Hello Ratatui! (press 'q' to quit)")
                .white()
                .on_blue();
            frame.render_widget(greeting, frame.area());
        })?;


        if let event::Event::Key(key) = event::read()? {
            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
                return Ok(());
            }
        }
    }
}

アプリケーションを実行する

次のようなアプリケーションになるはずです。

main.rs (click to expand)
use std::io;


use ratatui::{
    crossterm::event::{self, KeyCode, KeyEventKind},
    style::Stylize,
    widgets::Paragraph,
    DefaultTerminal,
};


fn main() -> io::Result<()> {
    let mut terminal = ratatui::init();
    terminal.clear()?;
    let app_result = run(terminal);
    ratatui::restore();
    app_result
}


fn run(mut terminal: DefaultTerminal) -> io::Result<()> {
    loop {
        terminal.draw(|frame| {
            let greeting = Paragraph::new("Hello Ratatui! (press 'q' to quit)")
                .white()
                .on_blue();
            frame.render_widget(greeting, frame.area());
        })?;


        if let event::Event::Key(key) = event::read()? {
            if key.kind == KeyEventKind::Press && key.code == KeyCode::Char('q') {
                return Ok(());
            }
        }
    }
}

ファイルを保存してください！これでアプリを実行できます。

run the app
cargo run

ターミナルに Hello Ratatui! (press 'q' to quit) という TUI アプリが TUI アプリとして表示されます。

hello

q を押して終了して、以前と同じようにターミナルに戻ることができます。

おめでとう！ :data:

Ratatuiとの「Hello World」ターミナルユーザーインターフェイスを作成しました。次のセクションでは、Ratatuiの仕組みについて詳しく説明します。

次のステップ

次のチュートリアル Counter App では、さらにインタラクティブな機能と、アプリケーション コードを配置するためのより堅牢なアプローチを紹介します。