HarmonyKit | 鸿蒙新特性 API：URL 编解码 encodeURIComponent 模式切换

●VON

16人浏览 · 2026-07-06 21:39:39

●VON · 2026-07-06 21:39:39 发布

在这里插入图片描述

HarmonyKit | 鸿蒙新特性 API：URL 编解码 encodeURIComponent 模式切换

引言：移动端 URL 编解码的三个场景

URL 编解码是 HarmonyKit 中使用频率排名前三的工具。追查 API 日志中 %E4%BD%A0%E5%A5%BD 这样的编码参数、构造带有中文关键词的搜索请求、解码被邮件客户端或聊天软件多次编码的链接——这些场景几乎每天都会遇到。

HarmonyKit 的 URL 编解码工具只有约 120 行代码，但围绕它有两个值得深入讨论的设计决策：encodeURIComponent 与 encodeURI 的行为差异、以及"模式切换按钮"与"双按钮布局"的权衡。

项目仓库：https://atomgit.com/VON-/harmony-kit

URL 编码原理：百分号编码

URL 设计规范（RFC 3986）规定了 URL 中允许出现的字符集。字母、数字、以及 -_.~ 可以直接出现。其余所有字符——空格、中文、&、=、?、#——都必须进行百分号编码。

规则：字符 → UTF-8 字节序列 → 每个字节写为 %XX（XX 是十六进制值）。例：中文字符"你"的 UTF-8 编码是 E4 BD A0，编码后是 %E4%BD%A0。

JavaScript 提供了两个编码函数，区别关键：

let url = 'https://api.example.com/search?q=你好&page=1';

encodeURI(url);
// → 'https://api.example.com/search?q=%E4%BD%A0%E5%A5%BD&page=1'
// URL 结构(: / ? = &)保留，只编码参数值中的中文

encodeURIComponent(url);
// → 'https%3A%2F%2Fapi.example.com%2Fsearch%3Fq%3D%E4%BD%A0%E5%A5%BD%26page%3D1'
// 全部编码，包括 URL 结构字符

如果你用 encodeURIComponent 编码完整 URL 后放到浏览器地址栏，浏览器会把它当成一个参数值。反之，用 encodeURI 编码参数值，& 不会被编码，服务器会把 & 当成参数分隔符导致参数截断。

Utils 层实现

在这里插入图片描述

export class UrlUtils {
  static encode(input: string): string {
    return encodeURIComponent(input);
  }
  static decode(input: string): string {
    return decodeURIComponent(input);
  }
  static encodeFull(input: string): string {
    return encodeURI(input);
  }
  static decodeFull(input: string): string {
    return decodeURI(input);
  }
}

四个静态方法，两两配对。encode/decode 对应参数编码，encodeFull/decodeFull 对应完整 URL 编码。每个方法输入 string，输出 string。

decodeURIComponent 和 decodeURI 对不合法的百分号序列（如残缺的 %E0%A4%A）会抛出 URIError。必须在 UI 层 try/catch 处理。

模式切换按钮

@State mode: number = 0;

Button(this.mode === 0 ? '模式: 参数编码' : '模式: 完整URL')
  .fontSize(11).height(28)
  .backgroundColor('#f0f0f0').fontColor('#333')
  .onClick(() => { this.mode = this.mode === 0 ? 1 : 0; });

一个按钮显示当前模式。点击切换只一次操作。为什么不用两个按钮（如 Base64 的"编码|解码"）？因为两种编码模式是互斥的选择——同方向、不同范围。切换按钮比两个独立按钮更准确表达"互斥"语义。

操作按钮和错误处理

编码按钮（蓝色 #007aff）和解码按钮（橙色 #ff9500）在模式切换按钮右侧。Blank() 将两者推到两端。

doDecode() {
  if (!this.input.trim()) return;
  try {
    this.output = this.mode === 0
      ? UrlUtils.decode(this.input)
      : UrlUtils.decodeFull(this.input);
  } catch (e) {
    this.output = '解码失败，请检查输入';
  }
}