NodeGui LineWrapMode 枚举详解:QPlainTextEdit 换行模式配置指南
NodeGui LineWrapMode 枚举详解:QPlainTextEdit 换行模式配置指南
LineWrapMode 是 NodeGui 中用于控制 QPlainTextEdit(纯文本编辑控件)换行行为的枚举类型,只有 NoWrap 与 WidgetWidth 两个成员,分别对应"禁止自动换行"与"按控件宽度自动换行"两种策略。本文围绕该枚举的语义、在 TypeScript API 中的定义、与底层 C++ 桥接层的映射关系,以及在实际桌面应用中的使用方式展开,帮助你精确控制文本编辑区域的换行呈现效果。
枚举概览:两个成员、两种策略
依据 LineWrapMode 枚举文档,该枚举仅包含两个成员:
| 成员 | 语义 |
|---|---|
NoWrap |
关闭自动换行,超出控件宽度的内容将以横向滚动条方式呈现 |
WidgetWidth |
按控件宽度自动换行,文本会在达到控件右边缘时折行显示 |
LineWrapMode 与 QTextEdit 所使用的 QTextEditLineWrapMode(包含 NoWrap、WidgetWidth、FixedPixelWidth、FixedColumnWidth 四个成员)不同:前者专门服务于纯文本场景的 QPlainTextEdit,后者服务于富文本场景的 QTextEdit。
TypeScript 侧定义:从枚举到控件 API
在 src/lib/QtWidgets/QPlainTextEdit.ts 中,枚举定义如下:
export enum LineWrapMode {
NoWrap,
WidgetWidth,
}
作为 TypeScript 数字枚举,NoWrap 的值为 0,WidgetWidth 的值为 1。该枚举在文件底部与 QPlainTextEdit 类一起导出(见 src/lib/QtWidgets/QPlainTextEdit.ts 的 setLineWrapMode / lineWrapMode 方法),并由 src/index.ts 统一从包入口对外暴露:
export { QPlainTextEdit, QPlainTextEditSignals, LineWrapMode } from './lib/QtWidgets/QPlainTextEdit';
QPlainTextEdit 类上对应的两个方法:
setLineWrapMode(mode: LineWrapMode): void {
this.native.setLineWrapMode(mode);
}
lineWrapMode(): LineWrapMode {
return this.native.lineWrapMode();
}
setLineWrapMode(mode):设置控件的换行模式;lineWrapMode():查询当前控件的换行模式。
底层桥接:C++ 层的映射实现
NodeGui 通过 N-API(Napi)将 TypeScript 调用桥接到 Qt C++ 实现。在 src/cpp/lib/QtWidgets/QPlainTextEdit/qplaintextedit_wrap.cpp 中:
Napi::Value QPlainTextEditWrap::setLineWrapMode(
const Napi::CallbackInfo &info) {
Napi::Env env = info.Env();
Napi::Number mode = info[0].As<Napi::Number>();
this->instance->setLineWrapMode(
static_cast<QPlainTextEdit::LineWrapMode>(mode.Int32Value()));
return env.Null();
}
Napi::Value QPlainTextEditWrap::lineWrapMode(const Napi::CallbackInfo &info) {
Napi::Env env = info.Env();
int value = static_cast<int>(this->instance->lineWrapMode());
return Napi::Number::From(env, value);
}
setLineWrapMode 将 JS 侧传入的数字强制转换为 QPlainTextEdit::LineWrapMode 后调用 Qt 原生方法,lineWrapMode 则将 Qt 返回值转回数字交给 JS 层。这两个方法通过 InstanceMethod 注册进 Napi 类定义(见 qplaintextedit_wrap.cpp)。从源码结构可以看出,NodeGui 对枚举的桥接采用"数字直传 + 静态转换"的方式,TS 枚举成员的值必须与 Qt 侧 QPlainTextEdit::LineWrapMode 的取值一一对应,因此 NoWrap = 0、WidgetWidth = 1 与 Qt 官方枚举顺序保持一致。
实战使用:在 NodeGui 应用中配置换行
默认行为与切换
QPlainTextEdit 在 Qt 中的默认换行模式即 WidgetWidth,因此创建控件后文本默认会随控件宽度自动换行。若需关闭换行(例如实现日志查看器、代码展示框),可显式调用:
import { QPlainTextEdit, LineWrapMode } from '@nodegui/nodegui';
const editor = new QPlainTextEdit();
editor.setPlainText('一段较长的文本内容……');
editor.setLineWrapMode(LineWrapMode.NoWrap);
读取当前模式:
const mode = editor.lineWrapMode(); // 返回 LineWrapMode 枚举值
注意事项
NoWrap模式下,超出控件可视宽度的内容需要通过横向滚动查看,请结合 QAbstractScrollArea 的滚动行为评估布局;- 需要按固定列宽或像素宽折行时,
LineWrapMode并不提供相关成员,此时应使用富文本控件QTextEdit的 setLineWrapMode(配合 QTextEditLineWrapMode 的FixedColumnWidth/FixedPixelWidth),或配合QTextEdit.setLineWrapColumnOrWidth使用(见 QTextEdit.ts)。
关联 API 与进一步阅读
- QPlainTextEdit 类文档:其中
lineWrapMode(返回LineWrapMode)与setLineWrapMode(mode)两个方法的签名与返回值类型即引用本枚举(见 qplaintextedit.md 与 qplaintextedit.md); - QTextEditLineWrapMode 枚举文档:富文本编辑控件的四成员换行枚举;
- QTextEdit.ts:
QTextEditLineWrapMode的 TS 定义; - src/index.ts:
LineWrapMode的包级导出入口。
如需查看 NodeGui 的换行模式在完整控件体系中的位置,可进一步阅读 全局 API 索引。