URL Parser Utils

一个功能强大的 URL 解析工具，用于解析 URL 的各个组成部分，兼容 H5 和 APP 环境。不依赖 window

安装

npm install @pellotools/url-parser-utils

Node.js 版本兼容性

本库需要支持 ECMAScript 2015 (ES6) 特性的 Node.js 版本。推荐使用的 Node.js 版本包括：

• Node.js 12.x (维护中的 LTS)
• Node.js 14.x (活跃的 LTS)
• Node.js 16.x (活跃的 LTS)
• Node.js 18.x (当前版本)

最低要求版本为 Node.js 12.0.0。对于更早的 Node.js 版本，某些功能可能无法正常工作。

环境兼容性

浏览器支持

• Chrome 45+
• Firefox 42+
• Safari 10+
• Edge 13+
• Internet Explorer 11+ (需要 polyfills)

移动端环境

• iOS WebView 10+
• Android WebView 4.4.4+
• React Native 0.60+
• Cordova/PhoneGap 应用

服务器环境

• Node.js 12.0.0+
• Express.js
• Koa.js
• 其他 Node.js 框架

前端框架支持

• Vue.js 2.x / 3.x
• React 16.x / 17.x / 18.x
• Angular 8+
• UniApp
• Taro
• Ionic
• 其他支持 ES6 模块的框架

混合应用框架

• Ionic 4+
• Capacitor
• NativeScript

功能特性

• 解析 URL 组件（协议、主机名、端口、路径、查询参数、哈希值）
• 兼容 H5 和 APP 环境
• 轻量级且解析速度快
• 无外部依赖
• 支持复杂查询字符串解析
• 支持相对和绝对 URL
• 支持链式调用
• 支持参数的增删改查

详细使用方法

基础用法

import UrlParser from '@pellotools/url-parser-utils';

// 解析 URL
const urlParser = new UrlParser('https://example.com:8080/path?param1=value1&param2=value2#section/path?hashParam=hashValue');

// 获取解析后的数据
const parsedData = urlParser.getData();

console.log(parsedData);

输出结果：

{
  "isValid": true,
  "origin": "https://example.com:8080",
  "protocol": "https://",
  "hostname": "example.com",
  "port": "8080",
  "pathname": "/path",
  "search": "?param1=value1&param2=value2",
  "searchParams": {
    "param1": "value1",
    "param2": "value2"
  },
  "hash": "#section/path?hashParam=hashValue",
  "hashPath": "section/path",
  "hashQuery": "?hashParam=hashValue",
  "hashParams": {
    "hashParam": "hashValue"
  },
  "params": {
    "param1": "value1",
    "param2": "value2",
    "hashParam": "hashValue"
  }
}

获取特定组件

import UrlParser from '@pellotools/url-parser-utils';

const urlParser = new UrlParser('https://example.com:8080/search?q=url+parser&page=1#results/page1?tab=main');

// 获取各种 URL 组件
console.log(urlParser.getHostname());    // 'example.com'
console.log(urlParser.getPort());        // '8080'
console.log(urlParser.getProtocol());    // 'https://'
console.log(urlParser.getPathname());    // '/search'
console.log(urlParser.getSearch());      // '?q=url+parser&page=1'
console.log(urlParser.getHash());        // '#results/page1?tab=main'
console.log(urlParser.getHashPath());    // 'results/page1'
console.log(urlParser.getHashQuery());   // '?tab=main'

获取参数

import UrlParser from '@pellotools/url-parser-utils';

const urlParser = new UrlParser('https://example.com/search?q=url+parser&page=1&category=tech&tags=js&tags=node#results?tab=main&sort=date');

// 获取查询参数
console.log(urlParser.getSearchParams());
// 输出: { q: 'url parser', page: '1', category: 'tech', tags: 'node' }
// 注意：同名参数后面的会覆盖前面的

console.log(urlParser.getSearchParams('q'));
// 输出: 'url parser'

// 获取 hash 参数
console.log(urlParser.getHashParams());
// 输出: { tab: 'main', sort: 'date' }

console.log(urlParser.getHashParams('tab'));
// 输出: 'main'

// 获取合并后的所有参数（hash 参数优先级更高）
console.log(urlParser.getParams());
// 输出: { q: 'url parser', page: '1', category: 'tech', tags: 'node', tab: 'main', sort: 'date' }

修改参数

import UrlParser from '@pellotools/url-parser-utils';

const urlParser = new UrlParser('https://example.com/search?q=url+parser&page=1');

// 设置单个参数
urlParser.setSearchParam('page', '2');

// 批量设置参数
urlParser.setSearchParam({
    category: 'tech',
    sort: 'date'
});

// 删除参数
urlParser.removeSearchParam('q');

// 转换为 URL 字符串
console.log(urlParser.toString());
// 输出: 'https://example.com/search?page=2&category=tech&sort=date'

链式调用

import UrlParser from '@pellotools/url-parser-utils';

const url = new UrlParser('https://example.com/search?q=test')
  .setSearchParam('page', '1')
  .setSearchParam('sort', 'date')
  .removeSearchParam('q')
  .toString();

console.log(url); 
// 输出: 'https://example.com/search?page=1&sort=date'

处理相对路径 URL

import UrlParser from '@pellotools/url-parser-utils';

// 解析相对路径 URL
const urlParser = new UrlParser('/api/users?id=123&name=john#profile?section=info');

console.log(urlParser.getPathname());      // '/api/users'
console.log(urlParser.getSearchParams());  // { id: '123', name: 'john' }
console.log(urlParser.getHashPath());      // 'profile'
console.log(urlParser.getHashParams());    // { section: 'info' }

在浏览器环境中使用

<!DOCTYPE html>
<html>
  <head> 
      <title>URL Parser Utils Example</title>
  </head> 
  <body> 
      <script type="module">
        import UrlParser from './node_modules/@pellotools/url-parser-utils/src/UrlParser.js';
        // 解析当前页面 URL
        const currentUrl = window.location.href;
        const urlParser = new UrlParser(currentUrl);
        
        console.log('当前页面 URL 信息:', urlParser.getData());
      </script>
  </body> 
</html>

API 参考

构造函数

new UrlParser(url)

创建一个新的 UrlParser 实例

参数:

• url (string): 要解析的 URL 字符串

实例方法

getData()

获取完整的解析结果对象

返回值:

• 包含所有 URL 组件和参数的对象

get(field)

获取指定字段的值

参数:

• field (string): 字段名

返回值:

• 指定字段的值

isValid()

检查 URL 是否有效（是否包含协议）

返回值:

• (boolean) URL 是否有效

getSearchParams(key)

获取查询参数

参数:

• key (string, optional): 参数名，如果不提供则返回所有查询参数

返回值:

• 指定参数的值或所有查询参数对象

getHashParams(key)

获取 hash 参数

参数:

• key (string, optional): 参数名，如果不提供则返回所有 hash 参数

返回值:

• 指定参数的值或所有 hash 参数对象

getParams(key)

获取合并后的参数（查询参数和 hash 参数）

参数:

• key (string, optional): 参数名，如果不提供则返回所有合并参数

返回值:

• 指定参数的值或所有合并参数对象

getHashPath()

获取 hash 路径部分

返回值:

• (string) hash 路径

getHash()

获取完整 hash

返回值:

• (string) 完整 hash

getHostname()

获取主机名

返回值:

• (string) 主机名

getProtocol()

获取协议

返回值:

• (string) 协议

getPort()

获取端口

返回值:

• (string) 端口

getOrigin()

获取源地址（协议+主机名+端口）

返回值:

• (string) 源地址

getPathname()

获取路径名

返回值:

• (string) 路径名

getSearch()

获取查询字符串

返回值:

• (string) 查询字符串

getHashQuery()

获取 hash 中的查询字符串

返回值:

• (string) hash 中的查询字符串

setSearchParam(key, value)

设置或更新查询参数

参数:

• key (string|Object): 参数名或包含多个参数的对象
• value (string, optional): 参数值（当 key 为字符串时使用）

返回值:

• (UrlParser) 返回当前实例，支持链式调用

removeSearchParam(key)

删除查询参数

参数:

• key (string): 要删除的参数名

返回值:

• (UrlParser) 返回当前实例，支持链式调用

toString()

构建完整的 URL 字符串

返回值:

• (string) 完整的 URL 字符串

贡献指南

1. Fork 此仓库
2. 创建您的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交您的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启一个 Pull Request

许可证

该项目基于 MIT 许可证 - 详情请见 LICENSE 文件。

技术支持

如需技术支持，请在 GitHub 仓库 中开启一个 issue。