feat: add getQueryParameter utility function

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
+```

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
 

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)

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"

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();
+    });
+});

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;

src/getQueryParameters/index.ts

@@ -34,29 +34,37 @@
  * // params.page 是字符串类型, params.limit 是数字类型
  * ```
  */
-const getQueryParameters = <T extends Record<string, string | null | undefined>>(
+const getQueryParameters = <T extends Record<string, string | null | undefined | number | boolean>>(
     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;

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';