如何基于QTextDocument构建自定义Widget组件？

你之前踩的坑其实很典型——QTextDocument是Qt里负责存储富文本内容的数据模型，根本不是UI视图控件，自然没法直接用addWidget()加到布局里。得搭配专门的视图载体才能把内容显示出来，我给你两种实用的解决方案：

方案一：用QTextEdit作为显示容器（最推荐） #

QTextEdit本身就是为承载QTextDocument设计的，自带滚动、排版、可选编辑功能，用它当容器最省心。修改你的代码如下：

MyWidget.h #

class MyWidget: public QFrame {
public:
    explicit MyWidget( QWidget *p_parent );
private:
    QTextEdit* m_textEdit;       // 负责显示的视图控件
    QTextDocument* m_textDocument; // 我们的文档数据模型
};

MyWidget.cpp #

MyWidget::MyWidget( QWidget *p_parent ) : QFrame( p_parent ) {
    QVBoxLayout *layout = new QVBoxLayout( this );
    layout->setMargin( 0 );
    layout->setSpacing( 0 );

    // 1. 创建QTextEdit作为显示载体
    m_textEdit = new QTextEdit(this);
    // 2. 初始化我们的文档对象
    m_textDocument = new QTextDocument(this);
    // 3. 把QTextEdit的默认文档替换成我们自己的
    m_textEdit->setDocument(m_textDocument);

    // 如果不需要用户编辑，设置为只读模式
    m_textEdit->setReadOnly(true);
    // 按需去掉边框和滚动条，让它看起来像个纯自定义Widget
    m_textEdit->setFrameShape(QFrame::NoFrame);
    m_textEdit->setVerticalScrollBarPolicy(Qt::ScrollBarAlwaysOff);
    m_textEdit->setHorizontalScrollBarPolicy(Qt::ScrollBarAlwaysOff);

    // 现在就能正常加到布局里了
    layout->addWidget(m_textEdit);
}

之后你就可以通过m_textDocument来设置富文本内容（比如m_textDocument->setHtml("<h1>测试标题</h1>")），QTextEdit会自动帮你渲染排版好。

方案二：自定义Widget直接绘制QTextDocument（适合特殊定制需求） #

如果你想完全掌控渲染逻辑，不想用QTextEdit的默认样式，可以继承QWidget，重写paintEvent直接用QPainter绘制文档。不过这种方式需要自己处理滚动、鼠标事件等，适合复杂定制场景：

MyWidget.h #

class MyWidget: public QWidget {
public:
    explicit MyWidget( QWidget *p_parent );
protected:
    void paintEvent(QPaintEvent *event) override;
private:
    QTextDocument m_textDocument;
};

MyWidget.cpp #

MyWidget::MyWidget( QWidget *p_parent ) : QWidget( p_parent ) {
    // 初始化文档内容
    m_textDocument.setHtml("<h2>自定义绘制测试</h2><p>这是直接用QPainter绘制的内容</p>");
}

void MyWidget::paintEvent(QPaintEvent *event) {
    QPainter painter(this);
    // 把文档绘制到Widget的区域内，这里可以自定义绘制的位置和范围
    m_textDocument.drawContents(&painter, QRectF(0, 0, width(), height()));
}

⚠️ 注意：这种方式如果需要滚动功能，你得自己添加滚动条、处理滚动偏移，比方案一麻烦不少，非必要不推荐。

补充小提示 #

如果只是显示简单的富文本，也可以用QLabel，它的setDocument()方法也能关联QTextDocument，但QLabel对复杂排版（比如多段落、图片、列表）的支持不如QTextEdit，所以优先选QTextEdit。

内容的提问来源于stack exchange，提问作者songvan