当前位置：首页 > news >正文

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

news 2026/7/7 16:41:27

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 提供了两个编码函数，区别关键：

leturl='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 层实现

exportclassUrlUtils{staticencode(input:string):string{returnencodeURIComponent(input);}staticdecode(input:string):string{returndecodeURIComponent(input);}staticencodeFull(input:string):string{returnencodeURI(input);}staticdecodeFull(input:string):string{returndecodeURI(input);}}

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

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

模式切换按钮

@Statemode: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='解码失败，请检查输入';}}