QTextCodec是Qt框架中负责文本编码之间转换的类，属于Qt Core模块。Qt内部统一以Unicode存储、绘制和处理字符串，而外部数据常使用Shift-JIS、KOI8-R等非Unicode编码，QTextCodec提供了在这些编码与Unicode之间双向转换的标准接口。开发者既可调用框架内置的编解码器，也可通过继承该类自行扩展新的编码支持。
定义
QTextCodec是Qt框架提供的一个抽象基类，用于在不同文本编码之间进行转换[1]。Qt使用Unicode来存储、绘制和处理字符串，当程序需要处理以其他编码保存的数据时，就由该类完成到Unicode的双向映射[2]。
该类属于Qt Core模块。在Qt 6中使用它需要链接Core5Compat组件，在qmake项目中则需添加库依赖core5compat[1]。其所有的函数都是可重入的，其中一部分函数同时具备线程安全性[1]。
原理
QTextCodec把编码信息封装在对象中，每个对象对应一种字符集，并通过纯虚函数向系统描述自身的编码规则[3]。核心的两个纯虚函数分别是convertToUnicode()与convertFromUnicode()，前者把8位字符序列解释为Unicode字符，后者把Unicode字符序列输出为8位字节流[4]。
每种编码还通过name()返回官方名称，通过aliases()返回别名列表，通过mibEnum()返回其在IANA字符集注册表中的MIB枚举值。当编码已在该注册文件中登记时，名称应采用首选的MIME名称，例如ISO-8859-1拥有latin1、CP819、IBM819等别名[3]。
由于部分多字节编码的字符可能跨越数据块的边界，该类提供了有状态的QTextDecoder与QTextEncoder。解码器在多次调用之间保留状态，即使一个多字节字符被切分在两个数据块里，也能正确地继续解码[3]。转换过程还可以通过转换标志控制行为，例如忽略Unicode字节序标记，或把非法输入输出为空字符串[5]。
发展历程
QTextCodec自Qt 4时代便已存在，其设计目标是在不同平台和不同语言环境下统一处理字符编码[5]。在Unix系统上，从Qt 4.2起本地编码由iconv库提供支持；无论是在Windows还是Unix，这类本地编解码器的名称都可能显示为System[6]。
专用于HTML内容的编码探测函数codecForHtml()于Qt 4.4引入，它通过检查字节序标记与HTML中的content-type元信息来推断编码[5]。类似的codecForUtfText()于Qt 4.6引入，可识别UTF-32大小端、UTF-16大小端以及UTF-8等格式的BOM[6]。
在Qt 6中，QTextCodec不再位于默认的核心库内，而是被移入Core5Compat兼容组件，使用时需要显式声明该依赖[1]。
应用
最直接的使用方式是通过静态函数codecForName()按名称取得编解码器，再调用toUnicode()把读入的字节串转换为QString，或调用fromUnicode()把字符串写回指定编码的字节数组[2]。框架内置支持的编码包括Big5、Big5-HKSCS、CP949、EUC-JP、EUC-KR、GB18030、Shift-JIS、KOI8-R、KOI8-U、TIS-620、UTF-8、UTF-16、UTF-32以及Windows-1250至1258等[1]。
在读取文件或解析网络数据时，可借助codecForLocale()获取与当前区域设置匹配的编解码器，还可通过setCodecForLocale()进行替换[2]。对于缺乏编码声明的文本，可先用canEncode()判断某个字符或字符串能否被目标编码完整表示，避免转换失败[4]。
当内置编码不足以覆盖需求时，开发者可以继承QTextCodec并实现相关虚函数，从而把新的编码方案接入Qt；文档建议将自定义编解码器以插件形式发布，便于复用与分发[3]。如果Qt在编译时启用了ICU支持，应用程序还可以使用ICU所支持的大部分编解码器[1]。
局限
编码转换本身存在信息损失的风险。当源字符在目标编码中没有对应表示时，结果轻则丢失一个字符，重则导致整次转换失败[3]。因此，在不确认目标编码覆盖范围的情况下直接转换并不安全。
按数据块分次转换容易出错。如果简单地对每一块数据单独调用转换函数，落在块边界上的多字节字符可能被截断，此时必须改用QTextDecoder来维持跨块状态[3]。
自动探测编码的能力也是有限的。codecForUtfText()只能依据字节序标记识别少数UTF系编码，codecForHtml()则依赖HTML中的元信息；一旦这些线索缺失，就只能退回默认编码，而默认值往往是Latin-1，并非真正正确的选择[4]。此外，编解码器对象由Qt持有并统一释放，使用者不应自行删除，否则可能造成悬空引用[3]。
参见
参考资料
- QTextCodec Class [引用日期2026-10-14]
- QTextCodec 类 [引用日期2026-10-14]
- QTextCodec Class [引用日期2026-10-14]
- QTextCodec Class - Sur cette page [引用日期2026-10-14]
- QTextCodec Class Reference[QtCore module] [引用日期2026-10-14]
- QTextCodec Class Reference [引用日期2026-10-14]