跳转至

第八章 文本编辑

TextEdit 是 egui 的文本编辑控件,源码在 crates/egui/src/widgets/text_edit/。功能比看起来强:单行/多行、复制粘贴、撤销重做、emoji、密码框、可选可编辑文本等。

8.1 最常用形式

// 单行
let mut name = String::new();
ui.text_edit_singleline(&mut name);

// 多行
let mut notes = String::new();
ui.text_edit_multiline(&mut notes);

8.2 完整 builder

TextEdit 是 builder。需要更多控制时用 ui.add:

ui.add(
    egui::TextEdit::singleline(&mut password)
        .password(true)
        .hint_text("输入密码")
        .desired_width(200.0)
        .interactive(true)
        .text_color(egui::Color32::WHITE)
        .clip_text(true)
);

多行:

ui.add(
    egui::TextEdit::multiline(&mut code)
        .code_editor()              // 当代码编辑器(等宽 + 行号风格)
        .desired_width(f32::INFINITY)
        .desired_rows(10)
        .lock_focus(true)
);

8.3 TextBuffer trait

TextEdit::new 接受任何实现 TextBuffer 的类型,不只是 String。String 和 Rc<String> 都实现了。你可以给自己的字符串类型实现 TextBuffer 来用 egui 编辑。

8.4 密码框

let mut pwd = String::new();
ui.add(egui::TextEdit::singleline(&mut pwd).password(true));

显示成圆点,剪贴板操作也会被禁用。

8.5 提示文字(hint_text)

输入框为空时显示的灰字:

ui.add(egui::TextEdit::singleline(&mut search).hint_text("搜索..."));

8.6 撤销/重做

TextEdit 内置撤销/重做,按 Ctrl+Z / Ctrl+Y 即可。状态按 Id 持久化。

8.7 选中文本

用户可以鼠标拖选。要程序化获取选区:

let response = ui.add(egui::TextEdit::singleline(&mut s));
if let Some(state) = egui::TextEdit::State::load(&response.ctx, response.id) {
    let cursor = state.cursor;
    // cursor.char_range 给出选中范围
}

也可以让 label 的文字可选中:

ui.add(egui::Label::new("可以选中复制的文字").selectable(true));
// 或全局开启
ui.style_mut().interaction.selectable_labels = true;

8.8 限制输入

egui 不直接提供“只能输数字”这类限制,自己在每帧检查并修正即可:

ui.text_edit_singleline(&mut input);
// 只保留数字
input.retain(|c| c.is_ascii_digit());

另一类“限制”是限制哪些按键归输入框管。默认情况下方向键被输入框吃掉,Tab 和 Esc 则交给 egui 做键盘导航(Tab/方向键切焦点,Esc 放弃焦点)。event_filter 能把这些键放出去(0.36.2 新增):

use egui::EventFilter;

// 把 tab 也捕获:按 Tab 在框里插制表符,而不是跳走焦点
let filter = EventFilter {
    tab: true,
    horizontal_arrows: true, // 默认就是 true
    vertical_arrows: true,   // 默认就是 true
    escape: false,           // 默认,Esc 仍能退出焦点
};
ui.add(egui::TextEdit::singleline(&mut code).event_filter(filter));

字段为 true 表示这个键被输入框捕获(Tab 会插入 \t),false 表示交给 egui 做焦点导航。列直接写 EventFilter::default()——“全放行”会让方向键也离开输入框,光标就动不了了。只想改一项时用 ..Default::default()。

8.9 输入事件回调

TextEdit 没有传统的“onChange”回调。即时模式下你只需要在每帧之后看 &mut s 的值是否变了。如果要区分“用户按了回车”:

let r = ui.add(egui::TextEdit::singleline(&mut s).lock_focus(true));
if r.lost_focus() && ui.input(|i| i.key_pressed(egui::Key::Enter)) {
    // 用户按回车了
    submit(&s);
}

Response::lost_focus() 表示这个控件这一帧失去了焦点,配合按键检测就能模拟“回车提交”。

8.10 IME(中文输入法)

TextEdit 默认支持 IME。在桌面上由 egui-winit 处理 IME 事件。如果你写自定义控件想接 IME,看 widgets/text_edit/ 里的实现。

8.11 代码编辑器

TextEdit::multiline(...).code_editor() 会切换成等宽字体 + 行号样式。但 egui 不带语法高亮——要高亮自己用 LayoutJob 给文字上色:

use egui::text::LayoutJob;

let mut job = LayoutJob::default();
// 把字符串切片按 token 加进 job,每段指定颜色
job.append("fn ", 0.0, egui::TextFormat { color: egui::Color32::from_rgb(180, 120, 255), ..Default::default() });
job.append("main", 0.0, egui::TextFormat { color: egui::Color32::from_rgb(255, 200, 100), ..Default::default() });
// ...

ui.label(job);

要完整语法高亮,可以用 syntect 之类的 crate,配合 egui_extras::syntect。

8.12 多人协作 / 异步更新

TextEdit 直接绑定 &mut String。如果数据来自另一个线程,先把数据 clone 到 App 字段里再绑给它。改完之后再发回去。

8.13 控件大小

ui.add(
    egui::TextEdit::multiline(&mut s)
        .desired_width(400.0)    // 宽度
        .desired_rows(8)         // 行数
);

8.14 自动补全:CompletionPopup

命令面板、@ 提及、文件路径这类输入框都需要一个“边打边弹建议”的弹窗。0.37 把它做成了现成控件 CompletionPopup。

let commands = ["/help", "/clear", "/open"];

let output = egui::CompletionPopup::new(ui.make_persistent_id("prompt"))
    .show(
        ui,
        egui::TextEdit::singleline(&mut text).hint_text("输入 / 看命令"),
        |query| {
            // 只在行首弹
            if !query.is_at_start() {
                return vec![];
            }
            commands
                .iter()
                .filter(|command| command.starts_with(query.word))
                .map(|command| egui::Suggestion::new(format!("{command} ")))
                .collect()
        },
    );

if let Some(accepted) = output.accepted {
    println!("选中了 {}", accepted.insert);
}

行为要点:

  • 第一个参数是 Id,它同时给内部的 TextEdit 和弹窗状态用。一个界面里有多个补全框就用 ui.make_persistent_id(...) 区分。
  • 那个闭包每帧调一次,拿到 query(当前光标下的词 query.word、query.is_at_start() 等),你返回 Vec<Suggestion>。
  • Enter / Tab 接受,Esc 关闭,上下键选择,鼠标也能点。键盘焦点始终留在输入框里,不会“抢”焦点。
  • 弹窗打开时 Tab 和 Esc 会被它接管(尽管用了 event_filter)。

8.15 小结

TextEdit 是个功能比较全的编辑控件。日常用法:

  • 单行:ui.text_edit_singleline(&mut s)
  • 多行:ui.text_edit_multiline(&mut s)
  • 密码:加 .password(true)
  • 提示:加 .hint_text(...)
  • 代码风格:加 .code_editor()
  • 检测回车:r.lost_focus() && ui.input(|i| i.key_pressed(Key::Enter))