@geckosoft/ngx-query-params

中文文档
0.0.6发布于 2025/03/25MITTypeScriptES Module近 30 天下载 1976

Reactive and type-safe query parameter management using Angular Signals.

原始使用文档
文档目录17 节
  1. 🚀 Features
  2. 📦 Installation
  3. 🧩 Setup
  4. 🧪 Usage
  5. Bind a number param:
  6. Bind a boolean param:
  7. Bind a string param:
  8. Optional single param:
  9. Enum-like casting:
  10. Multi-value param:
  11. 🧠 How It Works
  12. 📦 API Reference
  13. Signals
  14. 🔧 Advanced
  15. 🧼 Cleanup
  16. 📜 License
  17. 💬 Feedback / Contributions

ngx-query-params

Reactive and type-safe query parameter management using Angular Signals.

🔁 Two-way binding between URL query parameters and application state, powered by Angular’s modern reactivity model.


🚀 Features

  • ✅ Auto-synced signals from query parameters
  • ✅ Two-way binding: update signals → update URL
  • ✅ Works with primitive types, arrays, booleans, numbers, enums, and more
  • ✅ Fully tree-shakable, Angular-native
  • ✅ Zero extra dependencies

📦 Installation

Using NPM:

npm install @geckosoft/ngx-query-params

Using YARN:

yarn add @geckosoft/ngx-query-params

🧩 Setup

Ensure your app uses Angular's Signals (Angular v17+).

No special setup needed—just import and use in any Angular component or service.


🧪 Usage

Bind a number param:

import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { qpNum } from '@geckosoft/ngx-query-params';

@Component({
  selector: ...,
  imports: [FormsModule],
  template: `
    <input type="number" [(ngModel)]="page">
    <button (click)="nextPage()">Next Page</button>
  `,
})
export class MyComponent {
  page = qpNum('page', 1); // ?page=1

  nextPage() {
    this.page.set(this.page() + 1);
  }
}

Bind a boolean param:

toggle = qpBool('debug', false); // ?debug=true

Bind a string param:

filter = qp('filter', 'all'); // ?filter=all

Optional single param:

sort = qp('sort'); // string | undefined

Enum-like casting:

type Tab = 'home' | 'profile' | 'settings';
tab = qpCast1<Tab>('tab', 'home'); // ?tab=home

Multi-value param:

tags = qpMapN('tag', (x) => x.toLowerCase()); // ?tag=a&tag=b

🧠 How It Works

  • Hooks into Angular Router's ActivatedRoute and queryParamMap
  • Syncs with WritableSignal<T>
  • A global QueryParamsService batches and updates the URL when any param changes

📦 API Reference

Signals

FunctionTypeDescription
qp()WritableSignal<string | undefined>String param
qpNum()WritableSignal<number | undefined>Number param
qpBool()WritableSignal<boolean | undefined>Boolean param
qpCast1<T>()WritableSignal<T | undefined>Cast to enum/union type
qpMapN()WritableSignal<T[]>Multi-value param with mapping
qpMap1()WritableSignal<T | undefined>Generic one-value mapper

🔧 Advanced

You can inject QueryParamsService to manually batch or set multiple parameters:

constructor(private readonly qps: QueryParamsService) {}

applyFilters() {
  this.qps.set('filter', 'recent');
  this.qps.set('limit', 20);
}

🧼 Cleanup

No need to manually unsubscribe—internally handles onDestroy() and signal disposal.


📜 License

MIT


💬 Feedback / Contributions

Issues and PRs welcome!

版本与发布记录

@geckosoft/ngx-query-params 共发布 3 个版本,首次发布于 2025/03/25;过去 12 个月发布了 0 个版本。

版本发布日期距今
0.0.6latest2025/03/251.6 年前
0.0.52025/03/251.6 年前
0.0.42025/03/251.6 年前

关于 @geckosoft/ngx-query-params 的常见问题

@geckosoft/ngx-query-params 是什么?

Reactive and type-safe query parameter management using Angular Signals.

如何安装 @geckosoft/ngx-query-params?

在项目目录运行 npm install @geckosoft/ngx-query-params,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@angular/core(>= 17 < 21)、@angular/router(>= 17 < 21)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@geckosoft/ngx-query-params 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geckosoft/ngx-query-params 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@geckosoft/ngx-query-params 可以商用吗?

@geckosoft/ngx-query-params 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@geckosoft/ngx-query-params 的下载量有多少?

根据 npm 官方下载统计,@geckosoft/ngx-query-params 在 2026/10/16 – 2026/11/14 这 30 天内被下载 1,976 次,日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geckosoft/ngx-query-params 还在维护吗?

最新版本 0.0.6 发布于 2025/03/25(1.6 年前);至今共发布 3 个版本,其中过去 12 个月发布了 0 个;首次发布于 2025/03/25。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。