From d9b57afb051d43094372f03bac05e8aa158def05 Mon Sep 17 00:00:00 2001 From: jin-sir <942725119@qq.com> Date: Thu, 21 May 2026 21:12:25 +0800 Subject: [PATCH 1/2] feat: add getQueryParameter utility function --- docs/api/functions/getQueryParameter.md | 55 ++++++++++++++++++++ docs/api/globals.md | 1 + docs/api/typedoc-sidebar.json | 4 ++ src/getQueryParameter/__test__/index.test.ts | 36 +++++++++++++ src/getQueryParameter/index.ts | 50 ++++++++++++++++++ src/index.ts | 1 + 6 files changed, 147 insertions(+) create mode 100644 docs/api/functions/getQueryParameter.md create mode 100644 src/getQueryParameter/__test__/index.test.ts create mode 100644 src/getQueryParameter/index.ts diff --git a/docs/api/functions/getQueryParameter.md b/docs/api/functions/getQueryParameter.md new file mode 100644 index 0000000..d69286a --- /dev/null +++ b/docs/api/functions/getQueryParameter.md @@ -0,0 +1,55 @@ +[dt-utils](../globals.md) / getQueryParameter + +# Function: getQueryParameter() + +> **getQueryParameter**(`name`, `url?`): `undefined` \| `null` \| `string` \| `number` \| `boolean` + +Defined in: [getQueryParameter/index.ts:35](https://github.com/DTStack/dt-utils/blob/master/src/getQueryParameter/index.ts#L35) + +从给定的 URL 中获取指定查询参数的值。 + +## Parameters + +### name + +`string` + +要获取的查询参数名 + +### url? + +`string` + +目标 URL，若未提供则使用当前页面的 window.location.href + +## Returns + +`undefined` \| `null` \| `string` \| `number` \| `boolean` + +- 解析后的查询参数值 + +## Description + +解析目标 URL 的查询字符串，提取并转换指定名称的查询参数值。 +支持处理特殊字符串值： +- 'null' 会被转换为 null +- 'undefined' 会被转换为 undefined +- 可以被 JSON 解析的字符串会被自动解析（例如数字、布尔值） +- 其他值保持字符串形式 + +## Example + +```typescript +import getQueryParameter from 'dt-utils'; + +// 基本用法 +getQueryParameter('name', 'https://example.com?name=john&age=25'); // => "john" + +// 处理特殊值 +getQueryParameter('isActive', 'https://example.com?isActive=true&count=null'); // => true +getQueryParameter('count', 'https://example.com?isActive=true&count=null'); // => null + +// 不传入 url 时使用当前页面 URL +// 若当前页面 URL 为 https://current.com?page=home&limit=10 +getQueryParameter('limit'); // => 10 +``` diff --git a/docs/api/globals.md b/docs/api/globals.md index 2ca232e..507d96c 100644 --- a/docs/api/globals.md +++ b/docs/api/globals.md @@ -12,6 +12,7 @@ - [downloadFile](functions/downloadFile.md) - [generateUniqueId](functions/generateUniqueId.md) - [generateUrlWithQuery](functions/generateUrlWithQuery.md) +- [getQueryParameter](functions/getQueryParameter.md) - [getQueryParameters](functions/getQueryParameters.md) - [getTypeOfValue](functions/getTypeOfValue.md) - [~~shouldRender~~](functions/shouldRender.md) diff --git a/docs/api/typedoc-sidebar.json b/docs/api/typedoc-sidebar.json index 60890a9..6f63f98 100644 --- a/docs/api/typedoc-sidebar.json +++ b/docs/api/typedoc-sidebar.json @@ -37,6 +37,10 @@ "text": "generateUrlWithQuery", "link": "/api/functions/generateUrlWithQuery.md" }, + { + "text": "getQueryParameter", + "link": "/api/functions/getQueryParameter.md" + }, { "text": "getQueryParameters", "link": "/api/functions/getQueryParameters.md" diff --git a/src/getQueryParameter/__test__/index.test.ts b/src/getQueryParameter/__test__/index.test.ts new file mode 100644 index 0000000..58dde80 --- /dev/null +++ b/src/getQueryParameter/__test__/index.test.ts @@ -0,0 +1,36 @@ +import getQueryParameter from '..'; + +describe('getQueryParameter', () => { + it('should return the parsed value for a parameter from the provided url', () => { + expect(getQueryParameter('age', 'https://example.com?name=john&age=25')).toBe(25); + expect(getQueryParameter('enabled', 'https://example.com?enabled=true')).toBe(true); + }); + + it('should return undefined when the parameter does not exist', () => { + expect(getQueryParameter('missing', 'https://example.com?name=john')).toBeUndefined(); + }); + + it('should use window.location.href when url is not provided', () => { + const originalLocation = window.location; + + Object.defineProperty(window, 'location', { + configurable: true, + value: { + href: 'https://current.com?page=home&limit=10', + }, + }); + + expect(getQueryParameter('page')).toBe('home'); + expect(getQueryParameter('limit')).toBe(10); + + Object.defineProperty(window, 'location', { + configurable: true, + value: originalLocation, + }); + }); + + it('should preserve special parsed values from the query string', () => { + expect(getQueryParameter('empty', 'https://example.com?empty=null')).toBeNull(); + expect(getQueryParameter('unset', 'https://example.com?unset=undefined')).toBeUndefined(); + }); +}); diff --git a/src/getQueryParameter/index.ts b/src/getQueryParameter/index.ts new file mode 100644 index 0000000..58ece54 --- /dev/null +++ b/src/getQueryParameter/index.ts @@ -0,0 +1,50 @@ +import getQueryParameters from '../getQueryParameters'; + +/** + * 从给定的 URL 中获取指定查询参数的值。 + * + * @category Utils + * @description + * 解析目标 URL 的查询字符串，提取并转换指定名称的查询参数值。 + * 支持处理特殊字符串值： + * - 'null' 会被转换为 null + * - 'undefined' 会被转换为 undefined + * - 可以被 JSON 解析的字符串会被自动解析（例如数字、布尔值） + * - 其他值保持字符串形式 + * + * @param {string} name - 要获取的查询参数名 + * @param {string} [url] - 目标 URL，若未提供则使用当前页面的 window.location.href + * @returns {string | null | undefined | number | boolean} - 解析后的查询参数值 + * + * @example + * ```typescript + * import getQueryParameter from 'dt-utils'; + * + * // 基本用法 + * getQueryParameter('name', 'https://example.com?name=john&age=25'); // => "john" + * + * // 处理特殊值 + * getQueryParameter('isActive', 'https://example.com?isActive=true&count=null'); // => true + * getQueryParameter('count', 'https://example.com?isActive=true&count=null'); // => null + * + * // 不传入 url 时使用当前页面 URL + * // 若当前页面 URL 为 https://current.com?page=home&limit=10 + * getQueryParameter('limit'); // => 10 + * ``` + */ +const getQueryParameter = (name: string, url?: string) => { + try { + const targetUrl = url || window.location.href; + const search = new URL(targetUrl).search; + const params = getQueryParameters(search); + + return params[name]; + } catch (error: unknown) { + console.error( + 'Error parsing query parameter:', + error instanceof Error ? error.message : error + ); + return undefined; + } +}; +export default getQueryParameter; diff --git a/src/index.ts b/src/index.ts index 7c0a099..ce83fc6 100644 --- a/src/index.ts +++ b/src/index.ts @@ -14,6 +14,7 @@ export { default as formatSecond } from './formatSecond'; export { default as fromBase64 } from './fromBase64'; export { default as generateUniqueId } from './generateUniqueId'; export { default as generateUrlWithQuery } from './generateUrlWithQuery'; +export { default as getQueryParameter } from './getQueryParameter'; export { default as getQueryParameters } from './getQueryParameters'; export { default as getTypeOfValue } from './getTypeOfValue'; export { default as IndexedDB } from './indexedDB'; From 7a8816a2819af7b9fd3957e7a5b000d0e349484f Mon Sep 17 00:00:00 2001 From: jin-sir <942725119@qq.com> Date: Wed, 27 May 2026 19:44:11 +0800 Subject: [PATCH 2/2] fix: use try-catch --- docs/api/functions/getQueryParameters.md | 2 +- src/getQueryParameters/index.ts | 40 ++++++++++++++---------- 2 files changed, 25 insertions(+), 17 deletions(-) diff --git a/docs/api/functions/getQueryParameters.md b/docs/api/functions/getQueryParameters.md index 247bf40..4fc4a88 100644 --- a/docs/api/functions/getQueryParameters.md +++ b/docs/api/functions/getQueryParameters.md @@ -12,7 +12,7 @@ Defined in: [getQueryParameters/index.ts:37](https://github.com/DTStack/dt-utils ### T -`T` *extends* `Record`\<`string`, `undefined` \| `null` \| `string`\> +`T` *extends* `Record`\<`string`, `undefined` \| `null` \| `string` \| `number` \| `boolean`\> ## Parameters diff --git a/src/getQueryParameters/index.ts b/src/getQueryParameters/index.ts index 5f81571..1c83136 100644 --- a/src/getQueryParameters/index.ts +++ b/src/getQueryParameters/index.ts @@ -34,29 +34,37 @@ * // params.page 是字符串类型, params.limit 是数字类型 * ``` */ -const getQueryParameters = >( +const getQueryParameters = >( search: string ): T => { if (!search) return {} as T; - const searchParams = new URLSearchParams(search); - const paramValue = {}; + try { + const searchParams = new URLSearchParams(search); + const paramValue = {}; - searchParams.forEach((value, key) => { - if (value === 'null') { - paramValue[key] = null; - } else if (value === 'undefined') { - paramValue[key] = undefined; - } else { - try { - paramValue[key] = JSON.parse(value); - } catch (error) { - paramValue[key] = value; + searchParams.forEach((value, key) => { + if (value === 'null') { + paramValue[key] = null; + } else if (value === 'undefined') { + paramValue[key] = undefined; + } else { + try { + paramValue[key] = JSON.parse(value); + } catch (error) { + paramValue[key] = value; + } } - } - }); + }); - return paramValue as T; + return paramValue as T; + } catch (error: unknown) { + console.error( + 'Error parsing query parameters:', + error instanceof Error ? error.message : error + ); + return {} as T; + } }; export default getQueryParameters;