@wordpress/url

一组用于操作 URL 的实用工具集合。

安装

安装该模块

npm install @wordpress/url --save

此包假定你的代码将在 ES2015+ 环境中运行。如果你使用的环境对此类语言特性和 API 的支持有限或完全不支持，则应在你的代码中包含 @wordpress/babel-preset-default 中附带的 polyfill。

用法

addQueryArgs

将参数作为查询字符串追加到提供的 URL。如果 URL 已包含查询参数，则将这些参数与现有参数集合并（并优先于现有参数）。

用法

const newURL = addQueryArgs( 'https://google.com', { q: 'test' } ); // https://google.com/?q=test

参数

• url string：应追加参数的 URL。如果省略，则仅返回生成的查询字符串。
• args Record< string, unknown >：要应用到 URL 的查询参数。

返回值

• string：已应用参数的 URL。

buildQueryString

使用输入的查询数据生成 URL 编码的查询字符串。

它的行为等同于 PHP 的 http_build_query，并配置编码类型为 PHP_QUERY_RFC3986（空格为 %20）。

用法

const queryString = buildQueryString( {
    simple: 'is ok',
    arrays: [ 'are', 'fine', 'too' ],
    objects: {
        evenNested: {
            ok: 'yes',
        },
    },
} );
// "simple=is%20ok&arrays%5B0%5D=are&arrays%5B1%5D=fine&arrays%5B2%5D=too&objects%5BevenNested%5D%5Bok%5D=yes"

参数

• data Record< string, unknown >：要编码的数据。

返回值

• string：查询字符串。

cleanForSlug

对字符串执行一些基本清理，以便用作文章别名。

它复现了 WordPress 核心中 sanitize_title_with_dashes() 的部分行为，但仅用于近似生成最终的别名。

将 Latin-1 Supplement 和 Latin Extended-A 字母转换为基础 Latin 字母。移除组合变音符号。将空白字符、句点和正斜杠转换为连字符。移除除连字符外的其余非单词字符。将剩余字符串转换为小写。它不处理八位字节、HTML 实体或其他已编码字符。

参数

• string string：要处理的标题或别名。

返回值

• string：处理后的字符串。

filterURLForDisplay

返回用于显示的 URL。

用法

const displayUrl = filterURLForDisplay(
    'https://www.wordpress.org/gutenberg/'
); // wordpress.org/gutenberg
const imageUrl = filterURLForDisplay(
    'https://www.wordpress.org/wp-content/uploads/img.png',
    20
); // …ent/uploads/img.png

参数

• url string：原始 URL。
• maxLength number | null：最大 URL 长度。

返回值

• string：显示出的 URL。

getAuthority

返回 URL 的权限部分。

用法

const authority1 = getAuthority( 'https://wordpress.org/help/' ); // 'wordpress.org'
const authority2 = getAuthority( 'https://localhost:8080/test/' ); // 'localhost:8080'

参数

• url string：完整 URL。

返回值

• string | void：URL 的权限部分。

getFilename

返回 URL 的文件名部分。

用法

const filename1 = getFilename( 'http://localhost:8080/this/is/a/test.jpg' ); // 'test.jpg'
const filename2 = getFilename( '/this/is/a/test.png' ); // 'test.png'

参数

• url string：完整 URL。

返回值

• string | void：URL 的文件名部分。

getFragment

返回 URL 的片段部分。

用法

const fragment1 = getFragment(
    'http://localhost:8080/this/is/a/test?query=true#fragment'
); // '#fragment'
const fragment2 = getFragment(
    'https://wordpress.org#another-fragment?query=true'
); // '#another-fragment'

参数

• url string：完整 URL。

返回值

• string | void：URL 的片段部分。

getPath

返回 URL 的路径部分。

用法

const path1 = getPath( 'http://localhost:8080/this/is/a/test?query=true' ); // 'this/is/a/test'
const path2 = getPath( 'https://wordpress.org/help/faq/' ); // 'help/faq'

参数

• url string：完整 URL。

返回值

• string | void：URL 的路径部分。

getPathAndQueryString

返回 URL 的路径部分和查询字符串部分。

用法

const pathAndQueryString1 = getPathAndQueryString(
    'http://localhost:8080/this/is/a/test?query=true'
); // '/this/is/a/test?query=true'
const pathAndQueryString2 = getPathAndQueryString(
    'https://wordpress.org/help/faq/'
); // '/help/faq'

参数

• url string：完整 URL。

返回值

• string：URL 的路径部分和查询字符串部分。

getProtocol

返回 URL 的协议部分。

用法

const protocol1 = getProtocol( 'tel:012345678' ); // 'tel:'
const protocol2 = getProtocol( 'https://wordpress.org' ); // 'https:'

参数

• url string：完整 URL。

返回值

• string | void：URL 的协议部分。

getQueryArg

返回 URL 的单个查询参数。

用法

const foo = getQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'foo' ); // bar

参数

• url string：URL。
• arg string：查询参数名称。

返回值

• QueryArgParsed | undefined：查询参数值。

getQueryArgs

返回给定 URL 的查询参数对象。如果给定 URL 无效或没有查询字符串，则返回空对象。

用法

const foo = getQueryArgs( 'https://wordpress.org?foo=bar&bar=baz' );
// { "foo": "bar", "bar": "baz" }

参数

• url string：URL。

返回值

• QueryArgs：查询参数对象。

getQueryString

返回 URL 的查询字符串部分。

用法

const queryString = getQueryString(
    'http://localhost:8080/this/is/a/test?query=true#fragment'
); // 'query=true'

参数

• url string：完整 URL。

返回值

• string | void：URL 的查询字符串部分。

hasQueryArg

判断 URL 是否包含给定的查询参数。

用法

const hasBar = hasQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'bar' ); // true

参数

• url string：URL。
• arg string：查询参数名称。

返回值

• boolean：URL 是否包含该查询参数。

isEmail

判断给定字符串是否看起来像电子邮件地址。

用法

const isEmail = isEmail( 'hello@wordpress.org' ); // true

参数

• email string：要检查的字符串。

返回值

• boolean：它是否看起来像电子邮件地址。

isPhoneNumber

判断给定字符串是否看起来像电话号码。

用法

const isPhoneNumber = isPhoneNumber( '+1 (555) 123-4567' ); // true

参数

• phoneNumber string：要检查的字符串。

返回值

• boolean：它是否看起来像电话号码。

isURL

判断给定字符串是否看起来像 URL。

相关

• https://url.spec.whatwg.org/
• https://url.spec.whatwg.org/#valid-url-string

用法

const isURL = isURL( 'https://wordpress.org' ); // true

参数

• url string：要检查的字符串。

返回值

• boolean：它是否看起来像 URL。

isValidAuthority

检查提供的授权信息中是否存在无效字符。

用法

const isValid = isValidAuthority( 'wordpress.org' ); // true
const isNotValid = isValidAuthority( 'wordpress#org' ); // false

参数

• authority string：包含 URL 授权信息的字符串。

返回值

• boolean：如果参数包含有效的授权信息，则返回 true。

isValidFragment

检查提供的片段中是否存在无效字符。

用法

const isValid = isValidFragment( '#valid-fragment' ); // true
const isNotValid = isValidFragment( '#invalid-#fragment' ); // false

参数

• fragment string：URL 片段。

返回值

• boolean：如果参数包含有效的片段，则返回 true。

isValidPath

检查提供的路径中是否存在无效字符。

用法

const isValid = isValidPath( 'test/path/' ); // true
const isNotValid = isValidPath( '/invalid?test/path/' ); // false

参数

• path string：URL 路径。

返回值

• boolean：如果参数包含有效的路径，则返回 true。

isValidProtocol

测试 URL 协议是否有效。

用法

const isValid = isValidProtocol( 'https:' ); // true
const isNotValid = isValidProtocol( 'https :' ); // false

参数

• protocol string：URL 协议。

返回值

• boolean：如果参数是有效的协议（例如 http:、tel:），则返回 true。

isValidQueryString

检查提供的查询字符串中是否存在无效字符。

用法

const isValid = isValidQueryString( 'query=true&another=false' ); // true
const isNotValid = isValidQueryString( 'query=true?another=false' ); // false

参数

• queryString string：查询字符串。

返回值

• boolean：如果参数包含有效的查询字符串，则返回 true。

normalizePath

给定一个路径，返回规范化后的路径；无论查询参数值在原始文本中出现的顺序如何，相同的查询参数值都将被视为相同。

参数

• path string：原始路径。

返回值

• string：规范化后的路径。

prependHTTP

如果 URL 看起来像是打算作为顶级域（TLD），则为其添加“http://”前缀。

用法

const actualURL = prependHTTP( 'wordpress.org' ); // http://wordpress.org

参数

• url string：要测试的 URL。

返回值

• string：更新后的 URL。

prependHTTPS

如果 URL 看起来像是打算作为顶级域（TLD），则为其添加“https://”前缀。

注意：这不会将“http://”替换为“<https://>”。

用法

const actualURL = prependHTTPS( 'wordpress.org' ); // https://wordpress.org

参数

• url string：要测试的 URL。

返回值

• string：更新后的 URL。

removeQueryArgs

从 URL 的查询字符串中移除参数。

用法

const newUrl = removeQueryArgs(
    'https://wordpress.org?foo=bar&bar=baz&baz=foobar',
    'foo',
    'bar'
); // https://wordpress.org?baz=foobar

参数

• url string：URL。
• args string[]：查询参数。

返回值

• string：更新后的 URL。

safeDecodeURI

使用 decodeURI 安全地解码 URI。如果 decodeURI 抛出错误，则原样返回该 URI。

用法

const badUri = safeDecodeURI( '%z' ); // 不会抛出错误，仅返回 '%z'

参数

• uri string：要解码的 URI。

返回值

• string：如果可能，返回解码后的 URI。

safeDecodeURIComponent

使用 decodeURIComponent 安全地解码 URI 组件。如果 decodeURIComponent 抛出错误，则原样返回该 URI 组件。

参数

• uriComponent string：要解码的 URI 组件。

返回值

• string：如果可能，返回解码后的 URI 组件。

为这个包做贡献

这是一个独立的包，属于 Gutenberg 项目。该项目以单一仓库的形式组织。它由多个自包含的软件包组成，每个包都有特定用途。此单一仓库中的包会发布到 npm，并被 WordPress 以及其他软件项目使用。

要了解有关为这个包或整个 Gutenberg 项目做贡献的更多信息，请阅读项目的主要 贡献者指南。