跳到主要内容

输入框 TextInput

输入框是我们和程序“对话”最常用的方式之一。在 HiEasyX 里，TextInput 提供了一个功能完整的多行文本编辑器，支持光标、选区、滚动条，还有原生的 IME 中文输入。

第一印象

如果你只需要一行简单的输入框，TextInput 同样能胜任——默认高度足以容纳单行，竖直滚动条会在内容溢出时自动出现。

函数原型​

void TextInput(TextInputProfile &Profile);

参数说明​

TextInput 只有一个参数，但这是一个“资料结构体”，里面打包了所有你需要控制的行为和外观。记得把它声明为 static 或全局变量，否则每帧都会丢失你刚刚输入的文字！

TextInputProfile​

字段类型默认值说明
TextHXString""当前输入的文本内容。会被控件实时修改。
SizeHXPoint{400, 300}输入框的宽高。宽度和高度都可以是 -1 表示自动填充剩余空间。
WhereHXPoint{0, 0}相对于当前窗口的偏移。通常由布局系统自动计算，无需手动设置。
SelectingPointint0选区的结束位置（字符索引）。内部状态，不需要手动初始化。
DisplayCursorbooltrue是否显示光标。如果你需要纯静态文本展示，可以设为 false。
Cursorsint0当前光标所在字符索引。内部状态。
MouseStyleHXMouseStyleNormal鼠标悬停时的样式。内部会根据状态自动切换为 IBeam。
OnFocusboolfalse当前输入框是否拥有焦点。内部状态。
InDragboolfalse是否正在用鼠标拖拽选区。内部状态。
VerticalVPerfloat0.0f竖直滚动百分比（0.0 ~ 1.0）。内部状态。
HorizontalVPerfloat0.0f水平滚动百分比。内部状态。
VerticalButtonboolfalse竖直滚动条按钮是否被按下。内部状态。
HorizontalButtonboolfalse水平滚动条按钮是否被按下。内部状态。
InIMECompositionboolfalse是否处于 IME 拼音/五笔等组合输入状态。内部状态。
IMELastRectHXRect—上次 IME 候选窗的位置。内部状态。
ReadOnlyboolfalse是否只读。设为 true 后，用户无法编辑，但仍然可以选中和复制。
LastClickTimeDWORD0上次点击时间戳，用于双击选词。内部状态。
FontSizeint16字体大小。
LineGapint3行间距，单位是像素。
PaddingXint10左右内边距。
CursorBlinkMsint500光标闪烁周期，单位毫秒。
关于滚动条

当文本内容超出 Size 时，竖直滚动条会自动出现；如果某一行特别长，水平滚动条也会出现。滚动状态完全由控件内部维护，你不需要操心。

生命周期警告

TextInputProfile 必须是 static 或全局变量。如果你把它声明在函数内部且不加 static，每帧都会重新构造，Text 永远为空，看起来就像“键盘失灵”一样。这是 IMGUI 的典型陷阱，新手很容易踩！

返回值​

void。但注意，Profile.Text 会被控件实时修改，你下次读取它就能得到用户输入的内容。

完整示例​

#include <include/hex.h>
#include <include/impl/EasyX/hex_impl_easyx.h>

// 全局资料结构体，确保生命周期跨帧
static HX::TextInputProfile g_inputProfile;

int main() {
    static HX::WindowProfile wp;
    // 初始化输入框内容
    g_inputProfile.Text = HXStr("在这里输入文字...\n支持多行！");
    g_inputProfile.Size = {400, 200};
    g_inputProfile.FontSize = 18;

    while (true) {
        HX::HXBegin();
        ExMessage msg;
        while (peekmessage(&msg)) {
            HX::PushMessage(HX::GetHXMessage(&msg));
        }

        HX::Window(HXStr("TextInput 示例"), wp);

        HX::Text(HXStr("请输入你的备注："));
        HX::TextInput(g_inputProfile);

        HX::End();
        HX::Render();
    }

    return 0;
}

只读模式​

有时候我们只想展示一段代码或日志，不希望用户误触修改。这时开启 ReadOnly 即可：

static HX::TextInputProfile g_logProfile;
g_logProfile.ReadOnly = true;
g_logProfile.Text = HXStr("[系统日志]\n程序已启动...\n加载完成。");

只读模式下：

  • 键盘输入无效
  • 鼠标可以选中文本（方便复制到剪贴板）
  • 滚动条依然可用

IME 中文输入​

HiEasyX 对 Windows IME 有原生支持。当你在输入框里按下拼音键时，底部会出现候选条，按空格或数字即可上屏。这一切都不需要你做额外配置，只要系统输入法正常工作即可。

光标跟随

IME 候选窗会自动跟随光标位置，所以即使你滚动了文本，候选窗依然出现在正确的字符旁边。

常见疑问​

Q：我想限制输入长度怎么办？ 目前 TextInput 没有内置 MaxLength，你可以在读取 Profile.Text 后用 substr 截断，或者在业务层做校验。

Q：如何高亮代码？ TextInput 是纯文本输入控件，不带语法高亮。如果你需要代码编辑功能，可以查看 TextEditor 控件。

运行效果​

截图占位符：请补充 $name 控件的运行效果截图。

截图占位符：请补充 TextInput 运行效果 的运行效果截图，保存为 ./assets/TextInput_view.png。`n