前言

近期发现一款很有意思的HarmonyOS 三方库, 地址 @pura/harmony-utils(V1.4.0) , 作者是"桃花镇童长老", 我这里也是直接通过该作者公布的源码进行案例编写进行,写了到目前写了一部分demo ,感觉确实很有帮助,这里呢也是开始写一个系列的演示demo 供大家参考。如有帮助可以在OpenHarmony中进行下载安装进行使用哦

案例demo导航展示

↓↓↓↓↓↓接下来言归正传 ↓↓↓↓

做 HarmonyOS 应用时，处理 URL 参数是个高频需求：H5 页面跳转带参数、后台接口 URL 里取某个字段的值、动态拼接查询参数……每次都自己用字符串 split 或写正则，太麻烦了，FormatUtil 提供了两个专门处理这些的工具。

背景：URL 结构复习

在看代码前，先简单回顾一下 URL 的结构：

https://example.com/api?name=若城&age=18&city=深圳 ↑ 问号后面是查询参数（query string）

查询参数是key=value对，多个参数用&分隔。还有一个细节：中文会被 URL 编码成%E8%8B%A5...的形式。

演示代码里预设了一个 URL：

@StateinputUrl:string='https://example.com/api?name=若城&age=18&city=深圳';@StateinputUrlKey:string='name';

getQueryValue：从 URL 中取出指定参数的值

// 从 URL 中取 'name' 参数的值constv=FormatUtil.getQueryValue(this.inputUrl,this.inputUrlKey);this.addLog(`getQueryValue("${this.inputUrlKey}"):${v}`);// getQueryValue("name"): 若城

两个参数：

1. 完整的 URL 字符串
2. 要取的参数名（key）

返回对应的值，如果参数不存在则返回undefined或空字符串。

URL 中的中文值会自动解码：name=若城取出来就是'若城'，不是编码后的%E8%8B%A5%E5%9F%8E。

演示代码里直接嵌了按钮点击逻辑，注意 try-catch：

Button('getQueryValue').height(38).fontSize(13).backgroundColor('#00796B').onClick(()=>{try{constv=FormatUtil.getQueryValue(this.inputUrl,this.inputUrlKey);this.addLog(`getQueryValue("${this.inputUrlKey}"):${v}`);}catch(e){this.addLog(`getQueryValue 失败:${e}`);}})

URL 格式异常时可能抛出异常，所以套了 try-catch。

getParamsUrl：动态拼接 URL 参数

这个方向反过来：我有一个 URL 和一组参数，要把参数拼接到 URL 上。

用 Map 传参，覆盖模式（false= 用新参数替换原有同名参数）：

constparams=newMap<string,string>([['token','abc123'],['v','2']]);consturl=FormatUtil.getParamsUrl(this.inputUrl,params,false);this.addLog(`getParamsUrl(Map):${url}`);// https://example.com/api?token=abc123&v=2// 注意：false 模式会用新参数替换原有查询参数

用 Record 传参，追加模式（true= 在原有参数基础上追加）：

constparams:Record<string,string>={};params['debug']='true';params['t']=Date.now().toString();consturl=FormatUtil.getParamsUrl(this.inputUrl,params,true);this.addLog(`getParamsUrl(Record,append):${url}`);// https://example.com/api?name=若城&age=18&city=深圳&debug=true&t=1716624000000

三个参数：

1. 原始 URL
2. 参数：Map<string, string>或Record<string, string>
3. 是否追加（true= 追加到原有参数，false= 替换原有参数）

Map 和 Record 两种格式，怎么选

getParamsUrl支持两种格式传参，各有适合的场景：

Map：参数顺序固定，适合有顺序要求的场景

// Map：保持插入顺序constparams=newMap<string,string>([['token','abc123'],['v','2']]);

Record：字面量风格，写起来更简洁

// Record：适合动态构建constparams:Record<string,string>={};params['debug']='true';params['t']=Date.now().toString();

两种格式功能上完全等价，选哪个看你的使用习惯。

追加 vs 替换：第三个参数的区别

这是最容易搞混的地方，举个例子来说明：

原始 URL：https://example.com/api?name=若城&age=18

追加{ v: '2' }：

• append = true：https://example.com/api?name=若城&age=18&v=2（原参数保留）
• append = false：https://example.com/api?v=2（原参数被清除）

使用场景：

• append = true：给已有 URL 添加额外参数（如 token、时间戳）
• append = false：完全重新设置查询参数

实际项目中的使用场景

场景 1：WebView 跳转时追加 token

constbaseUrl='https://m.example.com/home';constparams:Record<string,string>={};params['token']=GlobalContext.getContext().get<string>('token')??'';params['platform']='harmonyos';constfinalUrl=FormatUtil.getParamsUrl(baseUrl,params,true);// 在 WebView 里加载 finalUrl

场景 2：分享链接加上用户 ID

constshareUrl='https://example.com/article/123';constparams=newMap<string,string>([['invite',userId]]);constshareLink=FormatUtil.getParamsUrl(shareUrl,params,true);

写在最后

两个 URL 工具方法，职责分明：

• getQueryValue：从 URL 里取某个参数的值，自动解码
• getParamsUrl：给 URL 动态追加或替换参数

比自己手写 URLSearchParams 或者正则解析要简洁很多，也不容易出 URL 编码相关的 bug。