QStringConverter Class
QStringConverter 类提供了编码和解码文本的基类。更多
| Header： | #include <QStringConverter> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
| 继承于 |
- 所有成员的列表，包括继承成员
- QStringConverter 属于字符串数据类。
注意：该类中的所有函数都是可重入的。
公共类型
| enum | Encoding { Utf8, Utf16, Utf16BE, Utf16LE, Utf32, …, System } |
| enum class | Flag { Default, ConvertInvalidToNull, WriteBom, ConvertInitialBom, Stateless } |
| flags | Flags |
公共函数
| bool | hasError() const |
| bool | isValid() const |
| const char * | name() const |
| void | resetState() |
静态公共成员
| QStringList | availableCodecs() |
| std::optional<QStringConverter::Encoding> | encodingForData(QByteArrayView data, char16_t expectedFirstCharacter = 0) |
| std::optional<QStringConverter::Encoding> | encodingForHtml(QByteArrayView data) |
| std::optional<QStringConverter::Encoding> | encodingForName(QAnyStringView name) |
| const char * | nameForEncoding(QStringConverter::Encoding e) |
详细说明
Qt 使用 UTF-16 来存储、绘制和操作字符串。在许多情况下，您可能希望处理使用不同编码的数据。大多数通过文件和网络连接传输的文本数据都是以 UTF-8 编码的。
QStringConverter 类是QStringEncoder 和QStringDecoder 类的基类，可帮助在不同文本编码之间进行转换。QStringDecoder 可将字符串从编码表示解码为 Qt 内部使用的格式 UTF-16。QStringEncoder 进行相反的操作，将 UTF-16 编码数据（通常以QString 的形式）编码为请求的编码。
始终支持以下编码：
- UTF-8
- UTF-16
- UTF-16BE
- UTF-16LE
- UTF-32
- UTF-32BE
- UTF-32LE
- ISO-8859-1 (Latin-1)
- 系统编码
QStringConverter 可能支持更多编码，这取决于 Qt 的编译方式。如果支持更多编码，可以使用availableCodecs() 列出。
QStringConverter可以使用 QStringConverter s 将某些编码字符串转换为 UTF-16 或从 UTF-16 转换为 UTF-16。
假设您有一些以 UTF-8 编码的字符串，并希望将其转换为QString 。简单的方法是像这样使用QStringDecoder ：
QByteArray encodedString = "..."; auto toUtf16 = QStringDecoder(QStringDecoder::Utf8); QString string = toUtf16(encodedString);
之后，string 保存解码后的文本。使用QStringEncoder 类将字符串从 Unicode 转换为本地编码也同样简单：
QString string = "..."; auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8); QByteArray encodedString = fromUtf16(string);
要读取或写入各种编码的文本文件，请使用QTextStream 及其setEncoding() 函数。
在尝试分块转换数据时，例如通过网络接收数据时，必须小心谨慎。在这种情况下，一个多字节字符有可能被分成两块。轻则丢失一个字符，重则导致整个转换失败。
QStringEncoder 和QStringDecoder 通过在内部状态中跟踪这种情况，可以轻松解决这个问题。因此，只需用下一个数据块再次调用编码器或解码器，就会自动继续对数据进行正确的编码或解码：
auto toUtf16 = QStringDecoder(QStringDecoder::Utf8); QString string; while (new_data_available()) { QByteArray chunk = get_new_data(); string += toUtf16(chunk); }
QStringDecoder 对象在数据块之间保持状态，因此即使多字节字符在数据块之间被分割，也能正常工作。
QStringConverter 对象因其内部状态而无法复制，但可以移动。
另请参见 QTextStream,QStringDecoder, 和QStringEncoder 。
成员类型文档
enum QStringConverter::Encoding
| 常数 | 值 | 说明 |
|---|---|---|
QStringConverter::Utf8 | 0 | 创建 UTF-8 或 UTF-8 转换器 |
QStringConverter::Utf16 | 1 | 创建 UTF-16 转换器。解码时，字节顺序将通过前导字节顺序标记自动检测。如果不存在，或在编码时，将假定使用系统字节序。 |
QStringConverter::Utf16BE | 3 | 创建大位UTF-16 转换器或小位UTF-16 转换器。 |
QStringConverter::Utf16LE | 2 | 创建小二进制 UTF-16 转换器或小二进制 UTF-16 转换器。 |
QStringConverter::Utf32 | 4 | 创建 UTF-32 转换器。解码时，字节顺序将通过前导字节顺序标记自动检测。如果不存在，或在编码时，将假定使用系统字节序。 |
QStringConverter::Utf32BE | 6 | 创建 big-endian UTF-32 转换器。 |
QStringConverter::Utf32LE | 5 | 创建小字节 UTF-32 转换器或小字节 UTF-32 转换器。 |
QStringConverter::Latin1 | 7 | 创建 ISO-8859-1 (Latin1) 转换器。 |
QStringConverter::System | 8 | 创建操作系统本地编码的转换器。对于基于 Unix 的系统，该编码总是假定为 UTF-8。在 Windows 系统中，该转换器可转换成或转换自本地编码页。 |
枚举类 QStringConverter::Flag
flags QStringConverter::Flags
| 常量 | 值 | 说明 |
|---|---|---|
QStringConverter::Flag::Default | 0 | 默认转换规则。 |
QStringConverter::Flag::ConvertInvalidToNull | 0x2 | 如果设置了该标志，则每个无效输入字符将作为空字符输出。如果未设置该标志，则在输出编码可以表示无效输入字符时，将其表示为QChar::ReplacementCharacter ，否则表示为问号。 |
QStringConverter::Flag::WriteBom | 0x4 | 从QString 转换为输出编码时，如果输出编码支持，则第一个字符写为QChar::ByteOrderMark 。UTF-8、UTF-16 和 UTF-32 编码就是这种情况。 |
QStringConverter::Flag::ConvertInitialBom | 0x8 | 从输入编码转换到QString 时，QStringDecoder 通常会跳过前导的QChar::ByteOrderMark 。当设置此标志时，字节序号不会被跳过，而是转换为 utf-16 并插入所创建的QString 的开头。 |
QStringConverter::Flag::Stateless | 0x1 | 忽略编码或解码字符串的不同函数调用之间可能存在的转换器状态。如果遇到不完整的数据序列，这也会导致QStringConverter 引发错误。 |
Flags 类型是QFlags<Flag> 的类型定义。它存储 Flag 值的 OR 组合。
成员函数文档
[static] QStringList QStringConverter::availableCodecs()
返回受支持编解码器的名称列表。此函数返回的名称可传递给QStringEncoder 和QStringDecoder 的构造函数，以创建给定编解码器的 en- 或 decoder。
除标准编解码器外，该函数还可用于获取其他编解码器的列表。支持其他编解码器要求 Qt 在编译时支持 ICU 库。
注意： 编解码器的顺序是内部实现细节，不保证稳定。
[static noexcept] std::optional<QStringConverter::Encoding> QStringConverter::encodingForData(QByteArrayView data, char16_t expectedFirstCharacter = 0)
如果可以确定data 内容的编码，则返回该编码。expectedFirstCharacter 可以作为额外提示传入，以帮助确定编码。
如果编码不明确，则返回的可选项为空。
[static] std::optional<QStringConverter::Encoding> QStringConverter::encodingForHtml(QByteArrayView data)
通过查看前导字节序标记或 HTML 元标记中的字符集指定符，尝试确定data 中 HTML 的编码。如果可选项为空，则表示QStringConverter 不支持指定的编码。如果未检测到编码，该方法将返回 Utf8。
另请参阅 QStringDecoder::decoderForHtml() 。
[static noexcept] std::optional<QStringConverter::Encoding> QStringConverter::encodingForName(QAnyStringView name)
将name 转换为相应的Encoding 成员（如果有的话）。
如果name 不是编码枚举中列出的编解码器名称，则会返回std::nullopt 。尽管如此，如果 ICU 提供了具有给定名称的转换器，那么在使用 ICU 构建 Qt 时，QStringConverter 构造函数可能会接受这样的名称。
注意： 在 6.8 之前的 Qt 版本中，该函数只接受const char * ，该名称预计为 UTF-8 编码。
[noexcept] bool QStringConverter::hasError() const
如果转换无法正确转换字符，则返回 true。例如，无效的 UTF-8 序列或由于目标编码的限制而无法转换字符时，就会触发这种情况。
[noexcept] bool QStringConverter::isValid() const
如果这是一个有效的字符串转换器，可用于编码或解码文本，则返回 true。
默认构造的字符串转换器或使用不支持的名称构造的转换器无效。
[noexcept] const char *QStringConverter::name() const
返回QStringConverter 可以编码或解码的编码的规范名称。如果转换器无效，则返回 nullptr。返回的名称是 UTF-8 编码。
另请参见 isValid()。
[static] const char *QStringConverter::nameForEncoding(QStringConverter::Encoding e)
返回编码的规范名称e 。
[noexcept] void QStringConverter::resetState()
重置转换器的内部状态，清除潜在错误或部分转换。
© 2025 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.
