ufo · 包 · UnJS 中文

为人类设计的 URL 工具。

安装

使用 npm 或您喜欢的包管理器安装

安装包

# npm
npm install ufo

# yarn
yarn add ufo

# pnpm
pnpm install ufo

# bun
bun install ufo

导入工具函数

// ESM
import { normalizeURL, joinURL } from "ufo";

// CommonJS
const { normalizeURL, joinURL } = require("ufo");

// Deno
import { parseURL } from "https://unpkg.com/ufo/dist/index.mjs";

编码工具

`decode(text)`

使用 decodeURIComponent 解码文本。如果失败，则返回原始文本。

`decodePath(text)`

解码 URL 的路径部分（与 encodePath 对斜杠编码的处理保持一致）。

`decodeQueryKey(text)`

解码查询键（与 encodeQueryKey 对加号编码的处理保持一致）。

`decodeQueryValue(text)`

解码查询值（与 encodeQueryValue 对加号编码的处理保持一致）。

`encode(text)`

编码 URL 的路径、搜索和哈希部分中需要编码的字符。

`encodeHash(text)`

编码 URL 的哈希部分中需要编码的字符。

`encodeHost(name)`

使用 Punycode 编码主机名。

`encodeParam(text)`

编码 URL 路径部分中需要作为参数编码的字符。此函数编码 encodePath 所做的一切，加上斜杠 (/) 字符。

`encodePath(text)`

编码 URL 路径部分中需要编码的字符。

`encodeQueryKey(text)`

编码 URL 查询部分中需要作为查询值编码的字符，同时编码 = 字符。

`encodeQueryValue(input)`

编码 URL 查询部分中需要作为查询值编码的字符。

解析工具

`parseAuth(input)`

接受 username:password 形式的字符串，并返回一个包含解码后的用户名和密码的对象。

`parseFilename(input)`

解析 URL 并返回路径中的最后一个片段作为文件名。

如果将 { strict: true } 作为第二个参数传递，它将仅在以扩展名结尾时返回最后一个片段。

示例

// Result: filename.ext
parseFilename("http://example.com/path/to/filename.ext");

// Result: undefined
parseFilename("/path/to/.hidden-file", { strict: true });

`parseHost(input)`

接受一个字符串，并返回一个包含两个属性的对象：hostname 和 port。

`parsePath(input)`

将输入字符串拆分为三部分，并返回一个包含这三部分的对象。

`parseURL(input, defaultProto?)`

接受 URL 字符串，并返回一个包含 URL 的 protocol、auth、host、pathname、search 和 hash 的对象。

示例

parseURL("http://foo.com/foo?test=123#token");
// { protocol: 'http:', auth: '', host: 'foo.com', pathname: '/foo', search: '?test=123', hash: '#token' }

parseURL("foo.com/foo?test=123#token");
// { pathname: 'foo.com/foo', search: '?test=123', hash: '#token' }

parseURL("foo.com/foo?test=123#token", "https://");
// { protocol: 'https:', auth: '', host: 'foo.com', pathname: '/foo', search: '?test=123', hash: '#token' }

`stringifyParsedURL(parsed)`

接受 ParsedURL 对象并返回字符串化的 URL。

示例

const obj = parseURL("http://foo.com/foo?test=123#token");
obj.host = "bar.com";

stringifyParsedURL(obj); // "http://bar.com/foo?test=123#token"

查询工具

`encodeQueryItem(key, value)`

将键值对编码为 URL 查询字符串值。

如果值是数组，它将被编码为多个具有相同键的键值对。

`parseQuery(parametersString)`

解析并解码查询字符串为对象。

输入可以是带或不带前导 ? 的查询字符串

`stringifyQuery(query)`

将查询对象字符串化并编码为查询字符串。

工具

`cleanDoubleSlashes(input)`

移除 URL 中的双斜杠。

示例

cleanDoubleSlashes("//foo//bar//"); // "/foo/bar/"

cleanDoubleSlashes("http://example.com/analyze//https://:3000//");
// Returns "http://example.com/analyze/https://:3000/"

`getQuery(input)`

解析并解码输入 URL 的查询对象为对象。

示例

getQuery("http://foo.com/foo?test=123&unicode=%E5%A5%BD");
// { test: "123", unicode: "好" }

`hasLeadingSlash(input)`

检查输入是否带有前导斜杠。（例如 /foo）

`hasProtocol(inputString, opts)`

`hasTrailingSlash(input, respectQueryAndFragment?)`

检查输入是否带有尾随斜杠。

`isEmptyURL(url)`

检查输入的 URL 是否为空或 /。

`isEqual(a, b, options)`

检查两个路径是否相等，不考虑编码、尾随斜杠和前导斜杠的差异。

您可以将 { trailingSlash: true, leadingSlash: true } 设置为选项，使斜杠检查严格。您可以将 { encoding: true } 设置为选项，使编码检查严格。

示例

isEqual("/foo", "foo"); // true
isEqual("foo/", "foo"); // true
isEqual("/foo bar", "/foo%20bar"); // true

// Strict compare
isEqual("/foo", "foo", { leadingSlash: true }); // false
isEqual("foo/", "foo", { trailingSlash: true }); // false
isEqual("/foo bar", "/foo%20bar", { encoding: true }); // false

`isNonEmptyURL(url)`

检查输入的 URL 是否不为空且不是 /。

`isRelative(inputString)`

检查路径是否以 ./ 或 ../ 开头。

示例

isRelative("./foo"); // true

`isSamePath(p1, p2)`

检查两个路径是否相等。在比较之前，尾随斜杠和编码会被规范化。

示例

isSamePath("/foo", "/foo/"); // true

`isScriptProtocol(protocol?)`

检查输入协议是否为危险的 blob:、data:、javascript: 或 vbscript: 协议之一。

`joinURL(base)`

将多个 URL 片段连接成一个 URL。

示例

joinURL("a", "/b", "/c"); // "a/b/c"

`normalizeURL(input)`

规范化输入的 URL

确保 URL 正确编码 - 确保路径名以斜杠开头 - 如果提供，保留协议/主机

示例

normalizeURL("test?query=123 123#hash, test");
// Returns "test?query=123%20123#hash,%20test"

normalizeURL("https://:3000");
// Returns "https://:3000"

`resolveURL(base)`

将多个 URL 片段解析为单个 URL。

示例

resolveURL("http://foo.com/foo?test=123#token", "bar", "baz");
// Returns "http://foo.com/foo/bar/baz?test=123#token"

`withBase(input, base)`

确保 URL 或路径名带有尾随斜杠。

如果输入已经以基础路径开头，则不会再次添加。

`withFragment(input, hash)`

添加/替换 URL 的片段部分。

示例

withFragment("/foo", "bar"); // "/foo#bar"
withFragment("/foo#bar", "baz"); // "/foo#baz"
withFragment("/foo#bar", ""); // "/foo"

`withHttp(input)`

添加或替换 URL 协议为 http://。

示例

withHttp("https://example.com"); // http://example.com

`withHttps(input)`

添加或替换 URL 协议为 https://。

示例

withHttps("http://example.com"); // https://example.com

`withLeadingSlash(input)`

确保 URL 或路径名带有前导斜杠。

`withoutBase(input, base)`

从 URL 或路径名中移除基础路径。

如果输入不是以基础路径开头，则不会移除。

`withoutFragment(input)`

从 URL 中移除片段部分。

示例

withoutFragment("http://example.com/foo?q=123#bar")
// Returns "http://example.com/foo?q=123"

`withoutHost(input)`

从 URL 中移除主机，保留其他所有部分。

示例

withoutHost("http://example.com/foo?q=123#bar")
// Returns "/foo?q=123#bar"

`withoutLeadingSlash(input)`

从 URL 或路径名中移除前导斜杠。

`withoutProtocol(input)`

从输入中移除协议。

示例

withoutProtocol("http://example.com"); // "example.com"

`withoutTrailingSlash(input, respectQueryAndFragment?)`

从 URL 或路径名中移除尾随斜杠。

如果第二个参数为 true，它将仅在尾随斜杠不是查询或片段的一部分时移除，但这会带来更昂贵的性能开销。

示例

withoutTrailingSlash("/foo/"); // "/foo"

withoutTrailingSlash("/path/?query=true", true); // "/path?query=true"

`withProtocol(input, protocol)`

添加或替换输入 URL 的协议。

示例

withProtocol("http://example.com", "ftp://"); // "ftp://example.com"

`withQuery(input, query)`

添加/替换 URL 的查询部分。

示例

withQuery("/foo?page=a", { token: "secret" }); // "/foo?page=a&token=secret"

`withTrailingSlash(input, respectQueryAndFragment?)`

确保 URL 以尾随斜杠结尾。

如果第二个参数为 true，它将仅在尾随斜杠不是查询或片段的一部分时添加，但这会带来更昂贵的性能开销。

示例

withTrailingSlash("/foo"); // "/foo/"

withTrailingSlash("/path?query=true", true); // "/path/?query=true"

许可

MIT

特别感谢 Eduardo San Martin Morote (posva) 提供的编码工具