encodeURIComponent()

**encodeURIComponent()** 函数通过将某些字符的每个实例替换为一个、两个、三个或四个表示该字符的 UTF-8 编码的转义序列来对 URI 进行编码（对于由两个代理字符组成的字符，将只会有四个转义序列）。与 encodeURI() 相比，此函数对更多字符进行编码，包括 URI 语法的一部分的字符。

试一试

语法

js
encodeURIComponent(uriComponent)

参数

uriComponent

要作为 URI 组件（路径、查询字符串、片段等）编码的字符串。其他值将转换为字符串。

返回值

一个新字符串，表示作为 URI 组件编码的提供的 uriComponent。

异常

URIError

如果 uriComponent 包含孤立的代理，则抛出。

描述

encodeURIComponent() 是全局对象的函数属性。

encodeURIComponent() 使用与 encodeURI() 中描述的相同的编码算法。它转义了除了以下字符之外的所有字符

A–Z a–z 0–9 - _ . ! ~ * ' ( )

与 encodeURI() 相比，encodeURIComponent() 转义了更多字符。对从表单 POST 到服务器的用户输入字段使用 encodeURIComponent() - 这将编码在数据输入过程中可能无意中生成的 & 符号，用于字符引用或其他需要编码/解码的字符。例如，如果用户写了 Jack & Jill，如果没有 encodeURIComponent()，服务器可能会将 & 解释为新字段的开始，从而危及数据的完整性。

对于 application/x-www-form-urlencoded，空格将替换为 +，因此可能希望在 encodeURIComponent() 替换之后再额外将 %20 替换为 +。

示例

Content-Disposition 和 Link 标头的编码

以下示例提供了 UTF-8 Content-Disposition 和 Link 服务器响应标头参数（例如，UTF-8 文件名）所需的特殊编码

js
const fileName = "my file(2).txt";
const header = `Content-Disposition: attachment; filename*=UTF-8''${encodeRFC5987ValueChars(
  fileName,
)}`;

console.log(header);
// "Content-Disposition: attachment; filename*=UTF-8''my%20file%282%29.txt"

function encodeRFC5987ValueChars(str) {
  return (
    encodeURIComponent(str)
      // The following creates the sequences %27 %28 %29 %2A (Note that
      // the valid encoding of "*" is %2A, which necessitates calling
      // toUpperCase() to properly encode). Although RFC3986 reserves "!",
      // RFC5987 does not, so we do not need to escape it.
      .replace(
        /['()*]/g,
        (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
      )
      // The following are not required for percent-encoding per RFC5987,
      // so we can allow for a little better readability over the wire: |`^
      .replace(/%(7C|60|5E)/g, (str, hex) =>
        String.fromCharCode(parseInt(hex, 16)),
      )
  );
}

RFC3986 的编码

最近的 RFC3986 保留了 !、'、(、) 和 *，即使这些字符没有正式的 URI 分隔符用途。以下函数对字符串进行编码，以符合 RFC3986 的 URL 组件格式。它还对 [ 和 ] 进行编码，它们是 IPv6 URI 语法的一部分。符合 RFC3986 的 encodeURI 实现不应转义它们，这在 encodeURI() 示例中进行了演示。

js
function encodeRFC3986URIComponent(str) {
  return encodeURIComponent(str).replace(
    /[!'()*]/g,
    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
  );
}

编码孤立的代理会抛出异常

如果尝试编码不属于高低对的代理，则会抛出 URIError。例如

js
// High-low pair OK
encodeURIComponent("\uD800\uDFFF"); // "%F0%90%8F%BF"

// Lone high-surrogate code unit throws "URIError: malformed URI sequence"
encodeURIComponent("\uD800");

// Lone high-surrogate code unit throws "URIError: malformed URI sequence"
encodeURIComponent("\uDFFF");

您可以使用 String.prototype.toWellFormed()，它将孤立的代理替换为 Unicode 替换字符 (U+FFFD)，以避免此错误。您还可以使用 String.prototype.isWellFormed() 在将字符串传递给 encodeURIComponent() 之前检查字符串是否包含孤立的代理。

规范

规范
ECMAScript 语言规范
# sec-encodeuricomponent-uricomponent

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅