npm package: @pellotools/url-parser-utils
Description: A URL parser utility for parsing URL components, compatible with both H5 and APP environments
Author: 1045998323@qq.com
Latest version: 1.0.4

# URL Parser Utils

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

## 安装

```bash
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
- 支持链式调用
- 支持参数的增删改查

## 详细使用方法

### 基础用法

```javascript
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);
```

输出结果：
```json
{
  "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"
  }
}

```

### 获取特定组件

```javascript
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'

```

### 获取参数

```javascript
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' }

```
### 修改参数

```javascript
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'

```

### 链式调用

```javascript

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

```javascript
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' }
```

### 在浏览器环境中使用

```html
<!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](LICENSE) 文件。

## 技术支持

如需技术支持，请在 [GitHub 仓库](https://github.com/pello1020/url-parser-utils/issues) 中开启一个 issue。