let file = fs::File::open(path)?;
let mut textarea: TextArea = io::BufReader::new(file).lines().collect::<io::Result<_>>()?;

从TextArea获取文本内容

TextArea::lines()返回文本行作为&[String]。它临时借用文本内容。

let text: String = textarea.lines().join("\n");

TextArea::into_lines()将TextArea实例移动到文本行作为Vec<String>。这样可以检索文本内容而不进行任何复制。

let lines: Vec<String> = textarea.into_lines();

请注意，TextArea始终包含至少一行。例如，空文本表示一行空行。这是因为任何文本文件都必须以换行符结束。

let textarea = TextArea::default();
assert_eq!(textarea.into_lines(), [""]);

显示行号

默认情况下，TextArea不显示行号。要启用，请通过TextArea::set_line_number_style()设置渲染行号的样式。例如，以下在深灰色背景色中渲染行号。

use ratatui::style::{Style, Color};

let style = Style::default().bg(Color::DarkGray);
textarea.set_line_number_style(style);

配置光标行样式

默认情况下，TextArea使用下划线渲染光标所在的行，以便用户可以轻松地注意到当前行。要更改光标行的样式，请使用TextArea::set_cursor_line_style()。例如，以下使用加粗文本样式化光标行。

use ratatui::style::{Style, Modifier};

let style = Style::default().add_modifier(Modifier::BOLD);
textarea.set_line_number_style(style);

要禁用光标行样式，请按照以下方式设置默认样式

use ratatui::style::{Style, Modifier};

textarea.set_line_number_style(Style::default());

配置制表符宽度

默认制表符宽度为4。要更改它，请使用TextArea::set_tab_length()方法。以下设置制表符宽度为2。按制表符键插入2个空格。

textarea.set_tab_length(2);

配置最大历史记录大小

默认情况下，过去50次修改被存储为编辑历史记录。历史记录用于撤销/重做。要更改记住多少过去编辑，请使用TextArea::set_max_histories()方法。以下记住过去1000次更改。

textarea.set_max_histories(1000);

设置0将禁用撤销/重做。

textarea.set_max_histories(0);

使用正则表达式进行文本搜索

在文本区域中搜索文本，使用TextArea::set_search_pattern()设置正则表达式模式，并通过TextArea::search_forward()进行正向搜索或使用TextArea::search_back()进行反向搜索。正则表达式由regex crate处理。

文本搜索会环绕文本区域。在正向搜索中，如果没有找到匹配项直到文本区域末尾，它将从文件开头搜索该模式。

匹配项在文本区域中被突出显示。可以使用TextArea::set_search_style()更改用于突出显示匹配项的文本样式。将空字符串设置到TextArea::set_search_pattern()将停止文本搜索。

// Start text search matching to "hello" or "hi". This highlights matches in textarea but does not move cursor.
// `regex::Error` is returned on invalid pattern.
textarea.set_search_pattern("(hello|hi)").unwrap();

textarea.search_forward(false); // Move cursor to the next match
textarea.search_back(false);    // Move cursor to the previous match

// Setting empty string stops the search
textarea.set_search_pattern("").unwrap();

没有提供文本搜索的UI。您需要提供自己的UI来输入搜索查询。建议使用另一个TextArea作为搜索表单。要构建单行输入表单，请参阅下文“高级用法”部分的“HTML中的单行输入如<input>”。

editor 示例实现了基于TextArea构建的搜索表单的文本搜索。请参阅实现以获取工作示例。

要使用文本搜索，需要在您的Cargo.toml中启用search功能。默认情况下它是禁用的，以避免在不需要时依赖regex crate。

ratatui-textarea = { version = "*", features = ["search"] }

高级用法

HTML中的单行输入如<input>

要在HTML中使用TextArea作为单行输入小部件（如<input>），请忽略所有插入换行符的关键映射。

use crossterm::event::{Event, read};
use ratatui_textarea::{Input, Key};

let default_text: &str = ...;
let default_text = default_text.replace(&['\n', '\r'], " "); // Ensure no new line is contained
let mut textarea = TextArea::new(vec![default_text]);

// Event loop
loop {
    // ...

    // Using `Input` is not mandatory, but it's useful for pattern match
    // Ignore Ctrl+m and Enter. Otherwise handle keys as usual
    match read()?.into() {
        Input { key: Key::Char('m'), ctrl: true, alt: false }
        | Input { key: Key::Enter, .. } => continue,
        input => {
            textarea.input(key);
        }
    }
}

let text = textarea.into_lines().remove(0); // Get input text

请参阅single_line 示例以获取工作示例。

定义您自己的键映射

所有编辑器操作都定义为TextArea的公共方法。要移动光标，使用ratatui_textarea::CursorMove来通知如何移动光标。

要定义自己的键映射，只需在代码中调用上述方法，而不是使用 TextArea::input() 方法。以下示例定义了类似于 Vim 的模式键映射。

use crossterm::event::{Event, read};
use ratatui_textarea::{Input, Key, CursorMove, Scrolling};

let mut textarea = ...;

enum Mode {
    Normal,
    Insert,
}

let mut mode = Mode::Normal;

// Event loop
loop {
    // ...

    match mode {
        Mode::Normal => match read()?.into() {
            Input { key: Key::Char('h'), .. } => textarea.move_cursor(CursorMove::Back),
            Input { key: Key::Char('j'), .. } => textarea.move_cursor(CursorMove::Down),
            Input { key: Key::Char('k'), .. } => textarea.move_cursor(CursorMove::Up),
            Input { key: Key::Char('l'), .. } => textarea.move_cursor(CursorMove::Forward),
            Input { key: Key::Char('i'), .. } => mode = Mode::Insert, // Enter insert mode
            // ...Add more mappings
            _ => {},
        },
        Mode::Insert => match read()?.into() {
            Input { key: Key::Esc, .. } => {
                mode = Mode::Normal; // Back to normal mode with Esc or Ctrl+C
            }
            input => {
                textarea.input(input); // Use default key mappings in insert mode
            }
        },
    }
}

参见 modal 示例 了解工作示例。它实现了更多类似 Vim 的键映射。

如果您不想使用默认的键映射，可以使用 TextArea::input_without_shortcuts() 方法代替 TextArea::input()。该方法仅处理非常基本的操作，如插入/删除单个字符、制表符、换行符。

match read()?.into() {
    // Handle your own key mappings here
    // ...
    input => textarea.input_without_shortcuts(input),
}

使用自己的后端

ratatui 允许您通过实现 ratatui::backend::Backend trait 来创建自己的后端。ratatui-textarea 也支持它。在这种情况下，请为 ratatui 使用 your-backend 功能。它们避免添加后端 crate（crossterm 和 termion），因为您正在使用自己的后端。

[dependencies]
ratatui = { version = "*", default-features = false }
ratatui-textarea = { version = "*", default-features = false, features = ["your-backend"] }

ratatui_textarea::Input 是一个不依赖于后端的关键输入类型。您需要做的是将您自己的后端中的键事件转换为 ratatui_textarea::Input 实例。然后 TextArea::input() 方法可以像其他后端一样处理输入。

以下示例中，假设 your_backend::KeyDown 是您后端的一个键事件类型，而 your_backend::read_next_key() 返回下一个键事件。

// In your backend implementation

pub enum KeyDown {
    Char(char),
    BS,
    Del,
    Esc,
    // ...
}

// Return tuple of (key, ctrlkey, altkey)
pub fn read_next_key() -> (KeyDown, bool, bool) {
    // ...
}

然后您可以实现将 your_backend::KeyDown 值转换为 ratatui_textarea::Input 值的逻辑。

use ratatui_textarea::{Input, Key};
use your_backend::KeyDown;

fn keydown_to_input(key: KeyDown, ctrl: bool, alt: bool) -> Input {
    match key {
        KeyDown::Char(c) => Input { key: Key::Char(c), ctrl, alt },
        KeyDown::BS => Input { key: Key::Backspace, ctrl, alt },
        KeyDown::Del => Input { key: Key::Delete, ctrl, alt },
        KeyDown::Esc => Input { key: Key::Esc, ctrl, alt },
        // ...
        _ => Input::default(),
    }
}

对于 ratatui-textarea 无法处理的键，可以使用 ratatui_textarea::Input::default()。它返回 'null' 键。编辑器将对此键不采取任何操作。

最后，将您自己的后端的键输入类型转换为 ratatui_textarea::Input 并将其传递给 TextArea::input()。

let mut textarea = ...;

// Event loop
loop {
    // ...

    let (key, ctrl, alt) = your_backend::read_next_key();
    if key == your_backend::KeyDown::Esc {
        break; // For example, quit your app on pressing Esc
    }
    textarea.input(keydown_to_input(key, ctrl, alt));
}

在屏幕上放置多个 TextArea 实例

您不需要做任何特别的事情。创建多个 TextArea 实例，并渲染从每个实例构建的小部件。

以下是一个示例，将两个 textarea 小部件放入应用程序并管理焦点。

use ratatui_textarea::{TextArea, Input, Key};
use crossterm::event::{Event, read};

let editors = &mut [
    TextArea::default(),
    TextArea::default(),
];

let mut focused = 0;

loop {
    term.draw(|f| {
        let rects = ...;

        for (editor, rect) in editors.iter_mut().zip(rects.into_iter()) {
            let widget = editor.widget();
            f.render_widget(widget, rect);
        }
    })?;

    match read()?.into() {
        // Switch focused textarea by Ctrl+S
        Input { key: Key::Char('s'), ctrl: true, .. } => focused = (focused + 1) % 2;
        // Handle input by the focused editor
        input => editors[focused].input(input),
    }
}

请参阅split示例和editor示例以获取工作示例。

最低支持的 Rust 版本

本 crate 的最低支持 Rust 版本依赖于ratatui crate。当前最低支持版本为 1.56.1。

版本控制

本 crate 尚未达到 v1.0.0。目前没有计划提升主版本。当前的版本控制策略如下

• 主版本：固定为 0
• 次版本：在发生重大更改时提升
• 补丁版本：在添加新功能或修复错误时提升

为 ratatui-textarea 贡献

此项目在GitHub上开发。

对于功能请求或错误报告，请创建一个问题。提交补丁时，请创建一个拉取请求。

在提交拉取请求之前，请参阅CONTRIBUTING.md。

许可证

ratatui-textarea 在MIT 许可证下分发。