Back to Qt.io
Contact Us Blog Download Qt
在本页

QStringDecoder Class

QStringDecoder 类提供了一个基于状态的文本解码器。更多

Header： #include <QStringDecoder>
CMake： find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake： QT += core
继承： QStringConverter

注意：该类中的所有函数都是可重入的。

公共类型

FinalizeResult
FinalizeResultQChar

公共函数

QStringDecoder()
QStringDecoder(QAnyStringView name, QStringConverter::Flags flags = Flag::Default)
QStringDecoder(QStringConverter::Encoding encoding, QStringConverter::Flags flags = Flag::Default)
QChar *appendToBuffer(QChar *out, QByteArrayView in)
(since 6.6) char16_t *appendToBuffer(char16_t *out, QByteArrayView in)
QStringDecoder::EncodedData<QByteArrayView> decode(QByteArrayView ba)
QStringDecoder::EncodedData<const QByteArray &> decode(const QByteArray &ba)
(since 6.11) QStringDecoder::FinalizeResult finalize()
(since 6.11) QStringDecoder::FinalizeResultQChar finalize(QChar *out, qsizetype maxlen)
(since 6.11) QStringDecoder::FinalizeResult finalize(char16_t *out, qsizetype maxlen)
qsizetype requiredSpace(qsizetype inputLength) const
QStringDecoder::EncodedData<QByteArrayView> operator()(QByteArrayView ba)
QStringDecoder::EncodedData<const QByteArray &> operator()(const QByteArray &ba)

静态公共成员

QStringDecoder decoderForHtml(QByteArrayView data)

详细说明

文本解码器可将使用特定编码的编码文本格式转换为 Qt 的内部表示形式。

可使用以下代码将编码数据转换为QString ：

QByteArray encodedString = "...";
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
QString string = toUtf16(encodedString);

解码器会记住调用之间所需的任何状态，因此转换分块接收的数据（例如，通过网络接收数据时）非常简单，只需在有新数据时调用解码器即可：

auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);

QString string;
while (new_data_available() && !toUtf16.hasError()) {
    QByteArray chunk = get_new_data();
    string += toUtf16(chunk);
}
auto result = toUtf16.finalize();
if (result.error != QStringDecoder::FinalizeResult::Error::NoError) {
    // Handle error
}

QStringDecoder 对象会在各块之间保持状态，因此即使在多字节字符序列中间拆分块也能正常工作。

QStringDecoder 对象因其内部状态而无法复制，但可以移动。

另请参阅 QStringConverter 和QStringEncoder 。

成员类型文档

[alias] QStringDecoder::FinalizeResult

这是QStringConverter::FinalizeResultChar<char16_t> 的别名。

[alias] QStringDecoder::FinalizeResultQChar

是QStringConverter::FinalizeResultChar<QChar> 的别名。

成员函数文档

[constexpr noexcept] QStringDecoder::QStringDecoder()

默认构造一个解码器。默认解码器无效，不能用于转换文本。

[explicit] QStringDecoder::QStringDecoder(QAnyStringView name, QStringConverter::Flags flags = Flag::Default)

使用name 和flags 创建解码器对象。如果name 不是已知编码的名称，则将创建一个无效的转换器。

注意： 在 6.8 之前的 Qt XML 版本中，此函数只接受const char * ，而 应为 UTF-8 编码。

另请参阅 isValid() 。

[explicit constexpr] QStringDecoder::QStringDecoder(QStringConverter::Encoding encoding, QStringConverter::Flags flags = Flag::Default)

使用encoding 和flags 创建解码器对象。

QChar *QStringDecoder::appendToBuffer(QChar *out, QByteArrayView in)

解码in 查看的字节序列，并将解码结果从out 开始写入缓冲区。返回写入数据末尾的指针。

out 缓冲区需要足够大，才能容纳所有解码数据。使用requiredSpace 确定解码in.size() 字节的编码数据缓冲区所需的最大大小。该函数可以写入out 和out + requiredSpace() 之间的任何字节，包括超出返回的结束指针的字节。

另请参阅 requiredSpace 。

[since 6.6] char16_t *QStringDecoder::appendToBuffer(char16_t *out, QByteArrayView in)

这是一个重载函数。

该函数在 Qt 6.6 中引入。

[static] QStringDecoder QStringDecoder::decoderForHtml(QByteArrayView data)

通过查看前导字节序标记或 HTML 元标记中的字符集指定符，尝试确定data 中 HTML 的编码，并返回与编码相匹配的QStringDecoder 。如果返回的解码器无效，则说明QStringConverter 不支持指定的编码。如果未检测到编码，该方法将返回 Utf8 的解码器。

另请参阅 isValid().

[since 6.11] QStringDecoder::FinalizeResultQChar QStringDecoder::finalize(QChar *out, qsizetype maxlen)

[since 6.11] QStringDecoder::FinalizeResult QStringDecoder::finalize(char16_t *out, qsizetype maxlen)

[since 6.11] QStringDecoder::FinalizeResult QStringDecoder::finalize()

向解码器发出不再有数据到达的信号。

也可提供待解码的残余内容数据。当没有剩余数据时，返回的error 字段将设为NoError 。

如果提供了非空的out ，则必须留有空间，最多可写入maxlen 个字符。残余输出将写入该空间，最多写入这么多字符，并由返回值的next 字段表示结束。通常情况下，这些残余数据应由每个剩余的未转换输入字符的一个替换字符组成。

如果所有剩余内容都已通过out 发送，如果out 是nullptr ，或者如果没有剩余数据，解码器将在从finalize() 返回时重置。否则，可以通过进一步调用finalize() 来检索或丢弃剩余数据。

这些函数在 Qt 6.11 中引入。

另请参阅 hasError() 和appendToBuffer()。

qsizetype QStringDecoder::requiredSpace(qsizetype inputLength) const

返回处理inputLength 编码数据所需的 UTF-16 代码单元的最大数量。

另请参阅 appendToBuffer 。

QStringDecoder::EncodedData<const QByteArray &> QStringDecoder::operator()(const QByteArray &ba)

QStringDecoder::EncodedData<const QByteArray &> QStringDecoder::decode(const QByteArray &ba)

QStringDecoder::EncodedData<QByteArrayView> QStringDecoder::operator()(QByteArrayView ba)

QStringDecoder::EncodedData<QByteArrayView> QStringDecoder::decode(QByteArrayView ba)

转换ba 并返回一个可隐式转换为QString 的结构体。

QByteArray encodedString = "...";
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
auto data = toUtf16(encodedString); // data's type is QStringDecoder::EncodedData<const QByteArray &>
QString string = toUtf16(encodedString); // Implicit conversion to QString

// Here you have to cast "data" to QString
auto func = [&]() { return !toUtf16.hasError() ? QString(data) : u"foo"_s; };

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.