Qt::QUrl

QUrl

• 最常见的使用QUrl 的方式是通过构造函数来初始化，传递一个 QString 参数。如果 URL 是有效的，isValid() 方法将返回 true。

QUrl url("https://github.com/");

• 然而，也可以使用 setUrl()。

QUrl url;
url.setUrl("https://github.com/");

解析

QUrl 提供了多个方法来访问 URL 的各个组成部分，例如：

• scheme()：返回 URL 的方案（例如 “http”、“https” 或 “ftp”）。
• host()：返回 URL 的主机名。
• port()：返回 URL 的端口号。
• path()：返回 URL 的路径。
• query()：返回 URL 的查询字符串。
• fragment()：返回 URL 的片段标识符。

URL格式

scheme

• scheme 指定使用的传输协议，它由 URL 起始部分的一个或多个 ASCII 字符表示。scheme 只能包含 ASCII 字符，对输入不做转换或解码，必须以 ASCII 字母开始。

协议	描述
file	资源是本地计算机上的文件。格式：file:///，注意后边应是三个斜杠。
ftp	通过 FTP 访问资源。格式：FTP://
gopher	通过 Gopher 协议访问该资源。
http	通过 HTTP 访问该资源。格式：HTTP://
https	通过安全的 HTTPS 访问该资源。格式：HTTPS://
mailto	资源为电子邮件地址，通过 SMTP 访问。格式：mailto:
MMS	通过支持MMS（流媒体）协议的播放该资源（代表软件：Windows Media Player）。格式：MMS://
ed2k	通过 支持ed2k（专用下载链接）协议的P2P软件访问该资源（代表软件：电驴）。格式：ed2k://
Flashget	通过 支持Flashget:（专用下载链接）协议的P2P软件访问该资源（代表软件：快车）。格式： Flashget://
thunder	通过 支持thunder（专用下载链接）协议的 P2P 软件访问该资源（代表软件：迅雷）。格式： thunder://
news	通过 NNTP 访问该资源。

下图显示了一个 URL，其 scheme 是 ftp：
![[scheme.png]]

Authority

• URL 的 authority 由用户信息、主机名和端口组成。所有这些元素都是可选的，即使 authority 为空，也是有效的。
• 格式：username:password@hostname:port
• 用户信息和主机由'@' 分割，主机和端口由 ':'分割 。如果用户信息为空，'@' 必须被省略。尽管端口为空时，允许使用 ':'。
  ![[authority.png]]
• host：指存放资源的服务器的域名系统（DNS）主机名或 IP 地址。
• port：整数，可选，省略时使用方案的默认端口，各种传输协议都有默认的端口号，如 HTTP 的默认端口为80。如果输入时省略，则使用默认端口号。有时候出于安全或其他考虑，可以在服务器上对端口进行重定义，即采用非标准端口号，此时，URL 中就不能省略端口号这一项。

user info

user info 指用户信息，是 URL 中 authority 可选的一部分。

用户信息包括：用户名和一个可选的密码，由 ':' 分割。 如果密码为空，':'必须被省略。

path

由零或多个 / 隔开的字符串，一般用来表示主机上的一个目录或文件地址。在 authority 之后，query 之前。

对于没有层级的 schemes，路径将是 scheme 后的所有部分，像下面这样：

query

query 指查询字符串，可选，用于给动态网页（例如：使用 CGI、ISAPI、PHP/JSP/ASP/ASP、.NET 等技术制作的网页）传递参数，可有多个参数，用 & 隔开，每个参数的名和值用 = 隔开。

fragment

fragment 指定网络资源中的片断。是 URL 的最后一部分，由'#' 后面跟的字符串表示。通常指的是用于 HTTP 页面上的某个链接或点。

例如：一个网页中有多个名词解释，可使用 fragment 直接定位到某一名词解释。

fragment 有时也被称为 URL“引用”。

传递一个 QString()（null 字符串）将取消 fragment 的设置。传递一个参数 QString(“”)（空而非 null 字符串）将 fragment 设置为一个空字符串（和原始 URL 一样，只有一个 "#")。

修改

修改 URL：您可以使用 QUrl 类的方法来修改 URL 的组成部分，例如：

• setScheme()：设置 URL 的方案。
• setHost()：设置 URL 的主机名。
• setPort()：设置 URL 的端口号。
• setPath()：设置 URL 的路径。
• setQuery()：设置 URL 的查询字符串。
• setFragment()：设置 URL 的片段标识符。

深入使用

相对路径

调用 isRelative() 可以判断 URL 是否是相对的。一个相对的 URL 可以被转变通过将它作为参数传递给 resolved()，会返回一个绝对 URL。isParentOf() 用来确定一个 URL 是否是另一个的 parent。

QUrl resolved(const QUrl &relative) const
如果 relative 不是一个相对 URL，该函数会直接返回 relative。否则，这两个 URL 的路径会进行合并，返回的新 URL 会有 base URL 的 scheme 和 authority。

合并后的路径，就像下面这样：

QUrl baseUrl("http://qt.digia.com/Support/");
QUrl relativeUrl("../Product/Library/");
qDebug(baseUrl.resolved(relativeUrl).toString());
// 打印 "http://qt.digia.com/Product/Library/"

调用 resolved() 使用 ".."，返回原始目录的上级目录。同样，使用 "../.." 将返回上上一层目录。如果 relative 是 "/"，路径会变成 "/"。

用户输入

[static] QUrl fromUserInput(const QString &userInput)

可以被扣除，返回一个 userInput 指定的有效 URL；如果不能，则会返回一个空 QURL。

大多数应用程序，可以浏览网页，允许用户输入一个 URL 形式的简单字符串。此字符串可以手动输入到地址栏，从剪贴板中获得，或者通过命令行参数传递。

当没有一个有效的 URL 字符串时，执行最好的猜测，使各种web相关的假设。

当字符串对应系统上的一个有效文件路径时，会构造一个 file:// URL，使用 QUrl::fromLocalFile()。

如果不是这种情况，试图把字符串变成一个 http:// 或 ftp:// URL。这时，后者字符串从以 'ftp' 开始。结果然后通过 QUrl 的 tolerant 解析器传递，如果成功，则会返回一个有效的 QUrl；否则，返回 QUrl()。

例如：

• qt-project.org -> http://qt-project.org
• ftp.qt-project.org -> ftp://ftp.qt-project.org
• hostname -> http://hostname
• /home/user/test.html -> file:///home/user/test.html

文件名

QString fileName(ComponentFormattingOptions options = FullyDecoded) const

返回文件的名称，包括目录路径。

**注意：**如果这个 QUrl 对象路径以斜杠结束，文件的名称是空的。

如果路径不包含任何斜线，完全返回作为文件名。

示例：

QUrl url("http://qt-project.org/support/file.html");
// url.adjusted(RemoveFilename) == "http://qt-project.org/support/"
// url.fileName() == "file.html"

参数 options 控制如何格式化文件名称组成。所有值产生一个明确的结果。使用 QUrl::FullyDecoded，所有百分比编码序列被解码；否则，返回值可能包含在QString的编码形式不能表示的一些百分比编码序列。

主机、端口

例如，通过 socket 连接到一个指定 QUrl 包含的主机、端口：

QTcpSocket sock;
sock.connectToHost(url.host(), url.port(80));

本地文件

可以使用 fromLocalFile() 构造一个 QUrl，通过传递一个本地文件路径。toLocalFile() 将一个 URL 转换为本地文件路径。

QUrl url = QUrl::fromLocalFile("E:\\Qt.txt");
// QUrl("file:///E:/Qt.txt")

百分比编码

URL 编码和解码

URL 编码和解码：QUrl 类提供了编码和解码 URL 组件的方法，如 toEncoded() 和 fromEncoded()。这些方法可以确保 URL 符合 RFC 3986 标准。

百分比编码

为方便生成编码 URL 字符串或查询字符串，有两个静态函数：fromPercentEncoding() 和 toPercentEncoding()，处理编码和解码的百分比 QString 对象。

[static] QByteArray toPercentEncoding(const QString &input, const QByteArray &exclude = QByteArray(), const QByteArray &include = QByteArray())

返回一个编码的输入副本 。输入首先转换为 UTF-8，没有在无限制组中的所有 ASCII 字符是百分比编码的。 为了防止字符变为百分比编码，可以将他们传递给 exclude，为了迫使字符变为百分比编码，将他们传递给 include。

无限制的定义是：ALPHA / DIGIT / “-” / “.” / “_” / “~”

QByteArray ba = QUrl::toPercentEncoding("{a fishy string?}", "{}", "s");
qDebug(ba.constData());
// 打印 "{a fi%73hy %73tring%3F}"

有效性

构建一个 URL 后，可以在任何时候调用 isValid()，来检查 URL 的有效性。如果返回 false，应该在继续之前 clear() URL，或通过为 setUrl() 传递一个新的 URL 重新开始。

bool isValid() const

URL 运行通过一致性测试。URL 的每一部分都必须符合 URI 标准的标准编码规则，URL 才是有效的。

bool checkUrl(const QUrl &url) {
    if (!url.isValid()) {
        qDebug(QString("Invalid URL: %1").arg(url.toString()));
        return false;
    }

    return true;
}