API 文档 - `url` 模块

[cssmagic]

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() 的别名。

---

---

暂未实现的接口 :warning:

.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 -- 布尔值，此协议是否需要双斜杠。 值：true
• host -- 主机（含端口号）。域名会被转换为全小写。 值：'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。

返回值

对象。整个 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 -- 若省略则不输出。

[cssmagic]

与 Underscore.ext 的差异：

• ~~.parseUrl() 的行为有差异~~
• ~~.composeUrl() 的行为有差异~~
• ~~.parseUrl() 新增别名：.parse()~~
• ~~.composeUrl() 新增别名：.format()~~
• 已移除 .isFullUrl()
• 已移除 .isAbsolutePath()