URI.js

简介

URI.js是一个用于处理URL的JavaScript库。可以对URI进行解析， 它提供了一个 jQuery风格 API（Fluent Interface，Method Chaining）来读写所有常规组件和一些方便的方法，如.directory（）和.authority（）。

URI.js提供了简单但强大的查询字符串处理方式，具有许多URI规范化函数并转换相对/绝对路径。

而URI.js提供了一个jQuery插件。 URI.js本身不依赖于 jQuery 。 您不需要jQuery来使用URI.js

API示例

URI("http://example.org/foo.html?hello=world")
    .username("rodneyrehm")
// -> http://rodneyrehm@example.org/foo.html?hello=world
    .username("")
// -> http://example.org/foo.html?hello=world
    .directory("bar")
// -> http://example.org/bar/foo.html?hello=world   添加路径
    .suffix("xml")
// -> http://example.org/bar/foo.xml?hello=world    添加后缀
    .query("")
// -> http://example.org/bar/foo.xml                添加查询条件
    .tld("com")
// -> http://example.com/bar/foo.xml                修改域名后缀
    .query({ foo: "bar", hello: ["world", "mars"] });
// -> http://example.com/bar/foo.xml?foo=bar&hello=world&hello=mars

// 简化
URI("?&foo=bar&&foo=bar&foo=baz&")
    .normalizeQuery();
// -> ?foo=bar&foo=baz

// 获取相对路径
URI("/foo/bar/baz.html")
    .relativeTo("/foo/bar/world.html");
// -> ./baz.html

// 获取绝对路径
URI("/foo/bar/baz.html")
    .relativeTo("/foo/bar/sub/world.html")
// -> ../baz.html
    .absoluteTo("/foo/bar/sub/world.html");
// -> /foo/bar/baz.html

// uri模板
URI.expand("/foo/{dir}/{file}", {
    dir: "bar",
    file: "world.html"
});
// -> /foo/bar/world.html

常用API

新建

var uri = new URI(); //相当于 new URI(location.href)
var uri = new URI("http://example.org"); //新建一个uri
var uri = new URI(new URI("http://example.org")); //clone一个uri
var uri = new URI("http://example.org").clone(); //clone一个uri
var uri = new URI({
    protocol: "http", // no trailing :
    username: "user",
    password: "pass",
    hostname: "example.org",
    port: "80", // 这里是string，不是数字
    path: "/foo/bar.html",  
    query: "foo=bar&bar=baz", // 注意，是"query"，不是"search"，而且，不要在前面加"?"
    fragment: "frag" // 注意，是"fragment"，不是"hash"，而且，不要在前面加"#"
}); //用对象方式新建uri

var parts = {
    protocol: "http",
    username: null,
    password: null,
    hostname: "example.org",
    port: null,
    path: "/foo.html",
    query: null,
    fragment: null
};
URI.build(parts) === "http://example.org/foo.html";

var parts = {
    username: "user",
    password: "pass",
    hostname: "example.org",
    port: "8080"
};
URI.buildAuthority(parts) === "user:pass@example.org:8080";

var parts = {
    username: "user",
    password: "pass"
};
URI.buildUserinfo(parts) === "user:pass@";

var parts = {
    hostname: "example.org",
    port: "8080"
};
URI.buildHost(parts) === "example.org:8080";

var data = {
    foo: "bar",
    hello: ["world", "mars", "mars"],
    bam: "",
    yup: null,
    removed: undefined
};
// 注意，默认情况下，同一个键相同的值会被合并
URI.buildQuery(data) === "foo=bar&hello=world&hello=mars&bam=&yup";
// 调用时传入true则会保留相同的值
URI.buildQuery(data, true) === "foo=bar&hello=world&hello=mars&hello=mars&bam=&yup";

解析

var uri = new URI("http://user:pass@example.org:80/foo/hello.html");
uri.href() === "http://user:pass@example.org:80/foo/hello.html";
uri.toString() === "http://user:pass@example.org:80/foo/hello.html";
uri.protocol(); // "http"，protocol()别名为scheme()
uri.username(); // "user"
uri.password(); // "pass"
uri.hostname(); // "example.org"，注意，hostname()返回的hostname不包含port
uri.port(); // "80"
uri.host(); // "example.org:80"
uri.userinfo(); // "user:pass"，即username+password
uri.authority(); // "user:pass@example.org:80"，即username+password+hostname+port
uri.origin(); // "http://user:pass@example.org:80"，即protocol+authority
uri.domain(); // "example.org"。如果url是“www.example.org”，那么hostname为“www.example.org”，而domain为“example.org”
uri.subdomain(); // ""，如果url是“www.example.org”，那么返回"www"
uri.tld(); // "org"
uri.pathname(); // "/foo/hello.html"，pathname()别名为path()
uri.directory(); // "/foo" 结尾没斜杠
//关于特殊字符有以下情况
//uri.directory("/hello world/");
//uri.directory() === "/hello%20world";
//uri.directory(true) === "/hello world";
uri.filename(); // "hello.html" 开头没斜杠
//关于特殊字符有以下情况
//uri.filename("hello world.html");
//uri.filename() === "hello%20world.html";
//uri.filename(true) === "hello world.html";
uri.suffix(); // "html" 开头没“.”
//关于特殊字符有以下情况
//uri.suffix("würgh");
//uri.suffix() === "w%C3%BCrgh";
//uri.suffix(true) === "würgh";
uri.segment(); // 返回["foo", "hello.html"]，表示路径的directory
//uri.segment(["foo", "bar", "foobar.html"]); // 将路径设置为http://user:pass@example.org:80/foo/bar/foobar.html
uri.segment(0); // 返回"foo"
uri.segmentCoded(); // 返回["foo", "hello.html"]，功能与segment相同，只是会在返回结果时自动解码

var result = URI.parse("http://example.org/foo.html");
result === {
    protocol: "http",
    username: null,
    password: null,
    hostname: "example.org",
    port: null,
    path: "/foo.html",
    query: null,
    fragment: null
};

var parts = {};
var result = URI.parseAuthority("user:pass@example.org:8080/foo.html", parts);
result === "/foo.html";
parts === {
    username: "user",
    password: "pass",
    hostname: "example.org",
    port: "8080"
};

var parts = {};
var result = URI.parseUserinfo("user:pass@example.org:8080/foo.html", parts);
result === "example.org:8080/foo.html";
parts === {
    username: "user",
    password: "pass"
};

var parts = {};
var result = URI.parseHost("example.org:8080/foo.html", parts);
result === "/foo.html";
parts === {
    hostname: "example.org",
    port: "8080"
};

var result = URI.parseQuery("?foo=bar&hello=world&hello=mars&bam=&yup");
result === {
    foo: "bar",
    hello: ["world", "mars"],
    bam: "",
    yup: null
};

参数解析

? 附带参数解析

var uri = new URI("http://example.org/foo/hello.html?foo=bar&bar=baz");
uri.search(); // 返回"?foo=bar&bar=baz"，以"?"开头
uri.query(); // 返回"foo=bar&bar=baz"
uri.search(true); // 返回{ foo: "bar", bar : "baz" }

#附带参数

var uri = new URI("http://example.org/foo/hello.html#world");
uri.hash(); // 返回"#world"，以"#"开头
uri.fragment(); // 返回"world"

?附带参数地修改

setSearch 是 setQuery 的别称

var uri = new URI("?hello=world");
uri.setSearch("hello", "mars"); // 返回一个uri，uri内容为"?hello=mars"
uri.setSearch({ foo: "bar", goodbye : ["world", "mars"] });
// 返回一个uri，uri内容为"?hello=mars&foo=bar&goodbye=world&goodbye=mars"
uri.setSearch("goodbye", "sun");// 返回一个uri，uri内容为"?hello=mars&foo=bar&goodbye=sun"

uri = new URI("?hello=world");
uri.addSearch("hello", "mars"); // 返回一个uri，uri内容为"?hello=world&hello=mars"
uri.addSearch({ foo: "bar", goodbye : ["world", "mars"] });
// 返回一个uri，uri内容为"?hello=world&hello=mars&foo=bar&goodbye=world&goodbye=mars"
uri.addSearch("no-value");
//返回一个uri，uri内容为"?hello=world&hello=mars&foo=bar&goodbye=world&goodbye=mars&no-value"

uri = new URI("?hello=world&hello=mars&foo=bar");
uri.removeSearch("hello"); // 返回一个uri，uri内容为"?foo=bar"
uri.search("?hello=world&hello=mars&foo=bar");
uri.removeSearch("hello", "world"); // 返回一个uri，uri内容为"?hello=mars&foo=bar"

uri.search("?hello=world&hello=mars&foo=bar&mine=true");
uri.removeSearch(["hello", "foo"]); // 返回一个uri，uri内容为"?mine=true"

uri.search("?hello=world&hello=mars&foo=bar&mine=true&a=1&a=2&a=3");
uri.removeSearch({hello: "world", foo: undefined, a: ["1", "3"]});
// 返回一个uri，uri内容为"?hello=mars&mine=true&a=2"

uri.search("?foo=bar&foo=baz&foo=bam&obj=bam&bar=bar&bar=baz&bar=bam");
uri.removeSearch('foo', /[rz]$/);
// 返回一个uri，uri内容为"?foo=bam&obj=bam&bar=bar&bar=baz&bar=bam"

?附带参数地判断

var uri = URI("?string=bar&list=one&list=two&number=123&null&empty=");

// 检查参数是否存在（不管此参数是否有值）
uri.hasQuery("string") === true;
uri.hasQuery("nono") === false;

// 检查参数的值bool化后为true还是false
uri.hasQuery("string", true) === true;
uri.hasQuery("string", false) === false;
uri.hasQuery("empty", true) === false;
uri.hasQuery("empty", false) === true;

// 检查参数的值是否为指定值
uri.hasQuery("string", "bar") === true;
uri.hasQuery("number", 123) === true;

// 检查参数的值是否在给定的列表中
uri.hasQuery("list", "two", true) === true;
uri.hasQuery("list", ["two"], true) === true;
uri.hasQuery("list", "three", true) === false;
uri.hasQuery("list", ["two", "three"], true) === false;
uri.hasQuery("list", /ne$/, true) === true;

// 检查参数的值是否符合正则表达式
uri.hasQuery("string", /ar$/) === true;

// 检查是否有参数的名称符合正则表达式
uri.hasQuery(/^str/) === true;
// 检查符合正则表达式的参数的值是否为指定值
uri.hasQuery(/^li/, "two") === false;

// 通过传入方法判断
uri.hasQuery("string", function(value, name, data) {
    // value === "bar";
    // name === "string";
    // data === uri.query(true);
    return true;
}) === true;

路径转换

relativeTo()和absoluteTo()可以将路径转换为相对路径/绝对路径。

var uri = new URI("/relative/path");
// make path relative
var relUri = uri.relativeTo("/relative/sub/foo/sub/file"); // 返回一个uri，uri内容为"../../../path"

var anotherUri = relUri.absoluteTo("/relative/sub/foo/sub/file"); // 返回一个uri，uri内容为"/relative/path"

其他

URI.commonPath("/foo/bar/baz.html", "/foo/bar/world.html");// 返回"/foo/bar/"
URI.joinPaths('/a/b', '/c', 'd', '/e');// 返回URI("/a/b/c/d/e")

var data = {};

URI.addQuery(data, "hello", "mars");
data === {hello: "mars"};

URI.addQuery(data, "hello", "world");
data === {hello: ["mars", "world"]};

URI.addQuery(data, {foo: "bar", goodbye : ["world", "mars"]});
data === {hello: ["mars", "world"], foo: "bar", goodbye : ["world", "mars"]};

URI.removeQuery(data, "hello");
data === {foo: "bar", goodbye : ["world", "mars"]};

// 移除指定值
data = {hello: ["world", "mars"], foo: "bar"};
URI.removeQuery(data, "hello", "world");
data === {hello: ["mars"], foo: "bar"} // yes, still an array

// 移除多个键
data = {hello: ["world", "mars"], foo: "bar", mine: "true"}
URI.removeQuery(data, ["hello", "foo"]);
data === {mine: "true"};

// 移除多个键的指定值
data = {hello: ["world", "mars"], foo: "bar", mine: "true", a: ["1", "2", "3"]}
URI.removeQuery(data, {hello: "world", foo: undefined, a: ["1", "3"]});
data === {hello: ["mars"], mine: "true", a: ["2"]}

最后更新： 2019年09月19日 11:31

原始链接： https://HowlCN1997.github.io/2019/09/19/urljs/

HowlCN

赏

× 请我吃糖~