API 文档 - url 模块
术语
Query String
举例来说，http://domain.com/path/file?foo&bar=2 中的 foo&bar=2 部分即为 query string。
Query String 的本质是对一些名值对进行编码和序列化之后的结果。而 query string 的解析就是一个反序列化和解码的过程。
URL 参数
Query String 所保存的这些名值对即称作 “URL 参数”。
JavaScript 接口
.parseQuery(queryString)
把 query string 解析为以对象的方式保存的名值对。
参数
queryString -- 字符串。需要解析的 query string。
返回值
对象。解析结果，以名值对的方式保存。
示例
gearbox.url.parseQuery('foo=1&bar=2') // => {foo: '1', bar: '2'}
gearbox.url.parseQuery('foo=&bar=2') // => {foo: '', bar: '2'}
gearbox.url.parseQuery('foo&bar=2') // => {foo: '', bar: '2'}
gearbox.url.parseQuery('') // => {}注意事项
- 传入不合法的参数，则一律返回空对象（
{}）。
- Query string 中的所有 key 都会被转换为小写。
- Query string 的格式为
foo=1&bar=true，不包含问号。如果此接口接收的参数以问号开头，则会被视为第一个 URL 参数的一部分，因为 ?foo 是一个合法的 URL 参数名。
- Query string 中多个连续的
& 字符会被视为一个。
- 解析结果中的值如果为
true、false、null、undefined 或数字时，总是以字符串的方式保存，不会自动转换数据类型。
- 当 query string 中出现某个 key 但没有对应的值时（比如
foo&bar=2 或 foo=&bar=2 中的 foo），其值将解析为空字符串。
已知问题
- 重复出现的 key 将只解析最后一次出现的值，不会把所有值加入到一个数组中。
- 不处理复杂模式的 key，比如
foo[] 或 foo[bar] 都不会被视为特殊含义，只会视为普通的 key。
.getParam(key)
获取当前页面 URL 的某个 URL 参数的值。
参数
key -- 字符串。需要获取的 URL 参数名，忽略大小写。
返回值
字符串或 undefined。对应 URL 参数的值。
示例
假设当前页面的 URL 为 http://domain.com/path/file?foo&bar=2，此时：
gearbox.url.getParam('foo') // => ''
gearbox.url.getParam('bar') // => '2'
gearbox.url.getParam('absentKey') // => undefined注意事项
- Query string 的解析方式参见
.parseQuery() 方法。
- 当页面 URL 发生变化时（比如调用
history.pushState() 等方法时），返回结果总是当前的。
.appendParam(url, param)
为给定的 URL 附加新的参数。
参数
url -- 字符串。待处理的 URL。param -- 对象。需要附加的 URL 参数（名值对）。
返回值
字符串。已附加 URL 参数的新的 URL。
示例
var url = 'http://domain.com/path/file'
url = gearbox.url.appendParam(url, {foo: 'bar'})
// => 'http://domain.com/path/file?foo=bar'
url = gearbox.url.appendParam(url, {test: 1})
// => 'http://domain.com/path/file?foo=bar&test=1'注意事项
param 参数中的 key 并不会覆盖 url 参数中已有的同名 key，只是追加一个同名参数。
.removeHashFromUrl(url)
把 URL 中的 hash 部分去除。
参数
url -- 字符串。待处理的 URL，可以是完整的 URL，也可以是相对路径。若传入其它类型的数值，将被转换为字符串。
返回值
字符串。去除 hash 之后的 URL。若未传入参数则返回空字符串。
示例
var url = 'http://domain.com/foo#bar'
gearbox.url.removeHashFromUrl(url) // => 'http://domain.com/foo'
.getHashFromUrl(url)
获取 URL 中的 hash 部分。获取结果包含开头的 # 字符。
如果需要得到当前页面 URL 的 hash 部分，直接使用 location.hash 即可。
参数
url -- 字符串。待处理的 URL，可以是完整的 URL，也可以是相对路径。若传入其它类型的数值，将被转换为字符串。
返回值
字符串。若传入的 URL 不包含 hash 部分则返回空字符串；若未传入参数则返回空字符串。
示例
var url = 'http://domain.com/foo#bar'
gearbox.url.getHashFromUrl(url) // => '#bar'
别名
.isHash()
gearbox.str.isHash() 的别名。
.stripHash()
gearbox.str.stripHash() 的别名。
暂未实现的接口 ⚠️
.parse(url)
别名： .parseUrl()
此接口的行为与 Node.js 内置的 url 模块 的 .parse() 接口的功能保持基本一致，但仍然有细微差异，详见 “注意事项” 部分。
解析 URL 的各个要素，解析结果以对象的方式输出。举例来说，当传入以下 URL 时：
'http://user:[email protected]:8080/path/file?query=string#hash'
解析结果中各个 key 的含义和值如下：
href -- 完整 URL 值。协议名和域名会被转换为全小写。
值：（同传入的 URL）protocol -- 协议。
值：'http:'slashes -- 布尔值，此协议是否需要双斜杠。
值：truehost -- 主机（含端口号）。域名会被转换为全小写。
值：'domain.com:8080'auth -- 身份验证信息。
值：'user:pass'hostname -- 主机名（不含端口号）。域名会被转换为全小写。
值：'domain.com'port -- 端口号。它不会被转换为数字。
值：'8080'pathname -- 路径（含文件名）。
值：'/path/file'search -- query string 部分（含开头的 ? 字符）。参数名和值不会被解码。
值：'?query=string'path -- 路径加上 query string 部分。参数名和值不会被解码。
值：'/path/file?query=string'query -- query string 部分（不含开头的 ? 字符）。
值：'query=string'hash -- hash 部分（含开头的 # 字符）。
值：'query=string'
可以看出它们涵盖了 location 对象的各个 key，且含义相同。
参数
返回值
对象。整个 URL 的解析结果，URL 的各个要素部分以名值对的方式保存。
当参数不合法时，返回空对象（{}）。
注意事项
- 此接口的实现依赖 DOM，无法用于 Worker。
- 若传入的 URL 不完整，则视为相对路径，以当前页面为基准进行解析。这也意味着
//foo/bar 将会被视为 “foo 主机下的 /bar 路径”。
- 当 URL 中的某些部分不存在时，解析结果中对应的 key 也将不存在。
.format(parts)
别名： .composeUrl()
此接口的行为与 Node.js 内置的 url 模块的 .format() 接口的功能保持基本一致。
根据提供的 URL 各个要素，构造完整的 URL。URL 各个组成部分的名称及含义同 .parse() 接口的描述。
参数
parts -- 对象。URL 的各个要素的名值对。
返回值
字符串。构造出的完整 URL。
当参数不合法时，返回空字符串。
示例
var urlParts = {
protocol: 'http:',
host: 'domain.com',
pathname: '/foo/bar'
}
gearbox.url.format(urlParts) // => 'http://domain.com/foo/bar'注意事项
- 此接口的实现依赖 DOM，无法用于 Worker。
href 字段将被忽略。path 字段将被忽略。protocol 字段如果没有用冒号结尾，则会自动补上。对于这些协议（http、https、ftp、gopher、file），还会自动补上双斜杠。- 可以额外使用
slashes 字段来强制自动补上双斜杠。
- 如果提供了
auth 字段，则会被使用。
- 当存在
host 时，将忽略 hostname 和 port 字段。
- 当存在
search 时，将忽略 query 字段。
pathname 应以 / 开头；不以 / 开头则会自动补上。search 应以 ? 开头；不以 ? 开头则会自动补上。hash 应以 # 开头；不以 # 开头则会自动补上。host、hostname、pathname 中的 ? 和 # 字符会被编码；search 中的 # 字符会被编码。port 值在经过 parseInt(port, 10) 转换后必须为 0 或正整数，否则均视为 0。- URL 的各个要素并不都是必选的。各字段省略时的行为如下（注意，字段值为空字符串并不表示省略）：
protocol -- 若省略则取当前页面的 location.protocol。auth -- 若省略则不输出。host -- 若省略则取 hostname 和 port。hostname -- 若省略则取当前页面的 location.hostname。port -- 若省略则不输出。pathname -- 若省略则取根目录（/）。search -- 若省略则取 query。query -- 若省略则不输出。hash -- 若省略则不输出。
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent