---
URL: "/zh-CN/blog/2025-08/url-query.html"
LLMS_URL: "/zh-CN/blog/2025-08/url-query.md"
lastUpdated: true
commentabled: true
recommended: true
title: "获取URL参数的最佳实践：兼容Hash模式的TypeScript实现"
description: "获取URL参数的最佳实践：兼容Hash模式的TypeScript实现"
date:
pageClass: "blog-page-class"
cover: "/covers/typescript.svg"
---
---
lastUpdated: true
commentabled: true
recommended: true
title: 获取URL参数的最佳实践：兼容Hash模式的TypeScript实现
description: 获取URL参数的最佳实践：兼容Hash模式的TypeScript实现
date: 2025-08-28 14:30:00
pageClass: blog-page-class
cover: /covers/typescript.svg
---
在现代Web开发中，获取URL中的参数是一项常见且重要的需求。这些参数常用于传递状态、配置以及用户数据等。然而，随着 `单页面应用`（SPA）的兴起，URL结构变得更加多样化，特别是引入了Hash路由模式（如使用 `#` 符号的URL）。为了确保在各种模式下都能准确获取参数，本文将介绍一个兼容Hash模式的TypeScript函数 `getUrlQuery`，并详细解析其实现原理及使用方法。
## 函数介绍 ##
下面是我们要讨论的 `getUrlQuery` 函数：
```ts
/**
* 获取URL参数，兼容HASH模式
* @category Url
* @param key 需要获取的参数名
* @returns 参数值或null
* @example
* ```typescript
* const name = getUrlQuery('name')
* ```
*/
export function getUrlQuery(key: string): string | null {
// 获取查询字符串，优先使用search，如果没有则尝试从hash中获取
const searchParams: URLSearchParams = new URLSearchParams(
window.location.search || window.location.hash.split('?')[1] || '',
)
// 使用URLSearchParams API获取参数值
const value = searchParams.get(key)
// 如果找到参数值，进行解码并返回；否则返回null
return value != null ? decodeURIComponent(value) : null
}
```
### 功能概述 ###
- **目标**：根据指定的参数名 `key`，从当前URL中提取对应的参数值。
- **兼容性**：支持标准的 `search` 参数（即 `?key=value` 形式）和Hash模式下的参数（即 `#/?key=value` 或 `#somePath?key=value` 形式）。
- **返回值**：如果找到对应参数，返回其解码后的值；否则返回 `null`。
## 代码详解 ##
让我们逐行解析这个函数的工作原理：
### 函数签名与注释 ###
函数通过TypeScript定义，接受一个字符串类型的参数 `key`，返回类型为 `string | null`。函数顶部的注释使用了JSDoc风格，清晰地描述了函数的用途、参数、返回值以及使用示例，有助于提升代码的可读性和可维护性。
### 获取查询字符串 ###
```ts
const searchParams: URLSearchParams = new URLSearchParams(
window.location.search || window.location.hash.split('?')[1] || '',
)
```
- **`window.location.search`**：获取URL中的查询字符串部分，即 `?key=value`。
- **Hash模式处理**：如果 `search` 部分为空，函数会尝试从 `hash` 部分获取参数。通过 `window.location.hash.split('?')[1]`，它尝试从类似 `#path?key=value` 的格式中提取查询字符串。
- **容错处理**：如果以上两种方式都无法获取到查询字符串，默认传递一个空字符串 `''` 给 `URLSearchParams`，避免出现错误。
### 使用 `URLSearchParams` 获取参数值 ###
```ts
const value = searchParams.get(key)
```
`URLSearchParams` 是现代浏览器提供的API，专门用于解析和操作URL中的查询参数。通过调用 `get` 方法，可以方便地根据键名获取对应的参数值。
### 返回解码后的参数值 ###
```ts
return value != null ? decodeURIComponent(value) : null
```
- **存在检查**：首先检查 `value` 是否为 `null`。
- **解码处理**：如果存在，则使用 `decodeURIComponent` 对参数值进行解码，确保处理例如URL编码的特殊字符。
- **返回结果**：返回解码后的值或 `null`。
## 使用示例 ##
假设当前URL为 `https://example.com/page?name=lance`，或者在Hash模式下为 `https://example.com/#/page?name=lance`，我们可以如下使用 `getUrlQuery` 函数：
```ts
const name = getUrlQuery('name')
console.log(name) // 输出: "lance" 或 null
```
无论是标准的查询字符串还是Hash模式，函数都能正确提取参数 `name` 的值。如果参数不存在，则返回 `null`。
## 优点与兼容性 ##
### 优点 ###
- **兼容性强**：无论是传统的查询字符串还是Hash模式，都能准确获取参数。
- **简洁易用**：利用现代浏览器的 `URLSearchParams API`，代码简洁且高效。
- **安全性**：在返回参数值前进行解码，避免潜在的编码问题。
### 兼容性 ###
- **浏览器支持**：`URLSearchParams` 在现代浏览器中得到广泛支持，包括最新版本的Chrome、Firefox、Edge和Safari。但对于一些旧版本的浏览器（如IE），可能需要引入Polyfill来确保兼容性。
- **TypeScript支持**：本函数使用TypeScript编写，适用于TypeScript项目，也可以很容易地在JavaScript项目中使用。
## 结论 ##
在处理URL参数时，考虑到不同的URL结构和路由模式是非常重要的。通过上述的 `getUrlQuery` 函数，我们可以在多种场景下稳定地获取URL参数，实现更灵活和强大的Web应用。结合现代API和良好的代码结构，这种方法不仅提高了开发效率，还增强了代码的可维护性。
在实际项目中，您可以将这个函数封装成工具库的一部分，并根据需要进行扩展，例如支持批量获取参数、处理数组参数等，以满足更复杂的需求。