QFormDataBuilder Class
QFormDataBuilder 类是一个辅助类，用于简化QHttpMultiPart 对象的创建。更多内容...
| 头文件： | #include <QFormDataBuilder> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Network) target_link_libraries(mytarget PRIVATE Qt6::Network) |
| qmake： | QT += network |
| 自： | Qt 6.8 |
- 所有成员列表，包括继承的成员
- QFormDataBuilder 属于“网络编程 API”和“隐式共享类”。
公共类型
| enum class | Option { Default, OmitRfc8187EncodedFilename, UseRfc7578PercentEncodedFilename, PreferLatin1EncodedFilename, StrictRfc7578 } |
| flags | Options |
公共函数
| QFormDataBuilder() | |
| QFormDataBuilder(QFormDataBuilder &&other) | |
| ~QFormDataBuilder() | |
| std::unique_ptr<QHttpMultiPart> | buildMultiPart(QFormDataBuilder::Options options = {}) |
| QFormDataPartBuilder | part(QAnyStringView name) |
| QFormDataBuilder & | operator=(QFormDataBuilder &&other) |
详细描述
QFormDataBuilder 类可用于构建一个QHttpMultiPart 对象，其内容类型默认设置为 FormDataType。
下面的代码片段演示了如何使用 QFormDataBuilder 构建多部分消息：
QFormDataBuilder builder;
QFile image(u"../../pic.png"_s); image.open(QFile::ReadOnly);
QFile mask(u"../../mask.png"_s); mask.open(QFile::ReadOnly);
builder.part("image"_L1).setBodyDevice(&image, "the actual image");
builder.part("mask"_L1).setBodyDevice(&mask, "the mask image");
builder.part("prompt"_L1).setBody("Lobster wearing a beret");
builder.part("n"_L1).setBody("2");
builder.part("size"_L1).setBody("512x512");
std::unique_ptr<QHttpMultiPart> mp = builder.buildMultiPart();另请参阅 QHttpPart 、QHttpMultiPart 和QFormDataPartBuilder 。
成员类型文档
enum class QFormDataBuilder::Option
flags QFormDataBuilder::Options
控制buildMultiPart() 的选项。
目前有几份 RFC 在multipart/form-data 的具体格式化方式上存在分歧。这些选项让你能够自主选择遵循哪份 RFC，而不是硬编码任何一份 RFC。
| 常量 | 值 | 描述 |
|---|---|---|
QFormDataBuilder::Option::Default | 0x00 | 默认值，旨在最大限度地提高整体互操作性。以下列出的所有选项均处于关闭状态。 |
QFormDataBuilder::Option::OmitRfc8187EncodedFilename | 0x01 | 当邮件正文部分的文件名包含非 US-ASCII 字符时，RFC 6266 第 4.3 节建议使用RFC 8187 风格的编码（filename*=utf-8''... ）。然而，较新的RFC 7578 第 4.2 节则禁止使用该机制。 截至本文撰写之时，这两份 RFC 均有效，因此此选项允许您选择遵循哪一份。默认情况下，将按照 RFC 6266 的建议，在未编码的filename 旁边包含 RFC 8187 编码的filename* 。 |
QFormDataBuilder::Option::UseRfc7578PercentEncodedFilename | 0x02 | 当正文部分的文件名包含非 US-ASCII 字符时，RFC 7578 第 4.2 节建议对 UTF-8 编码的文件名的字节进行百分比编码。 不过，该规范接着指出，许多实现并未对UTF-8 编码的文件名进行百分比编码，而是直接输出“原始”UTF-8（其中" 和\ 通过\ 进行转义）。这也是QFormDataBuilder 的默认行为。 |
QFormDataBuilder::Option::PreferLatin1EncodedFilename | 0x04 | RFC 5987 第 3.2 节要求收件人支持 ISO-8859-1（“Latin-1”）编码。 当邮件正文部分的文件名包含非 US-ASCII 字符（但这些字符符合 Latin-1 标准）时，此选项会优先使用 ISO-8859-1 编码，而非 UTF-8。 较新的 {https://datatracker.ietf.org/doc/html/rfc8187#附录 A}{RFC 8187} 不再要求支持 ISO-8859-1，因此默认情况下，所有非美国 ASCII 文件名都将以 UTF-8 编码发送。 |
QFormDataBuilder::Option::StrictRfc7578 | OmitRfc8187EncodedFilename | UseRfc7578PercentEncodedFilename | 此选项结合其他选项，以实现对RFC 7578的严格合规。 |
Options 类型是QFlags<Option> 的 typedef。它存储 Option 值的 OR 组合。
成员函数文档
QFormDataBuilder::QFormDataBuilder()
创建一个空的 QFormDataBuilder 对象。
[noexcept] QFormDataBuilder::QFormDataBuilder(QFormDataBuilder &&other)
通过“move”操作构造一个 QFormDataBuilder 实例，使其指向与other 所指向的同一对象。
[noexcept] QFormDataBuilder::~QFormDataBuilder()
销毁QFormDataBuilder 对象。
std::unique_ptr<QHttpMultiPart> QFormDataBuilder::buildMultiPart(QFormDataBuilder::Options options = {})
根据options 构建并返回一个指向 QHttpMultipart 对象的指针。
另请参阅 QHttpMultiPart 。
QFormDataPartBuilder QFormDataBuilder::part(QAnyStringView name)
返回一个新创建的QFormDataPartBuilder 对象，并将name 作为表单数据的name 参数。只要关联的QFormDataBuilder 尚未被销毁，该对象即保持有效。
出于互操作性的考虑，强烈建议将name 中的字符限制为US-ASCII字符集。
另请参阅 QFormDataPartBuilder 和QHttpPart 。
[noexcept] QFormDataBuilder &QFormDataBuilder::operator=(QFormDataBuilder &&other)
将other 通过Move操作赋值给此QFormDataBuilder 实例。
© 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.
