在搜索列表和后台筛选页面中,用户可能选择分类、输入关键词、切换排序方式,再把当前页面分享给同事。如果筛选条件只存在 JavaScript 内存里,刷新页面后状态就会丢失,浏览器前进和后退按钮也难以得到正确结果。
通过 URL、URLSearchParams 与 History API,可以让页面状态与地址栏保持一致。本文实现一个可分享、可刷新恢复的商品检索界面,并讨论参数校验、历史记录和重复更新问题。
一、哪些状态应该进入 URL?
适合放入 URL 的通常是影响结果集合的公开筛选条件,例如关键词、分类、排序和页码;临时弹窗是否展开、用户输入中的密码等则不适合。
URL 是可以复制和记录的公开状态,不应把认证 Token、个人敏感信息或大量临时数据放进查询参数。
先设计搜索区域:
<section class="search-controls" data-search-page>
<input type="search" data-keyword placeholder="搜索商品">
<select data-category>
<option value="all">全部分类</option>
<option value="book">图书</option>
<option value="device">设备</option>
</select>
</section>
<a href="https://www.yxtiktok.com/blog/guides/">
二、定义参数的规范化规则
URL 参数始终是字符串,不能假设从地址栏得到的页码一定为正整数,也不能把未知排序字段直接传给数据库查询。
const allowedCategories = new Set(['all', 'book', 'device']);
const allowedSorts = new Set(['newest', 'price_asc', 'price_desc']);
function readSearchState(search = location.search) {
const params = new URLSearchParams(search);
const rawPage = Number(params.get('page'));
const category = params.get('category') ?? 'all';
const sort = params.get('sort') ?? 'newest';
return {
keyword: (params.get('q') ?? '').trim().slice(0, 100),
category: allowedCategories.has(category) ? category : 'all',
sort: allowedSorts.has(sort) ? sort : 'newest',
page: Number.isSafeInteger(rawPage) && rawPage > 0 ? rawPage : 1
};
}
这里规定了默认值、允许值和关键词长度。规范化之后,整个页面只依赖一个可靠的状态对象,而不是在各个组件内分别读取查询字符串。
三、只序列化具有业务意义的字段
为了保持地址简洁,可以不输出与默认值一致的参数。这样不同操作产生的 URL 更容易比较,也方便测试。
function buildSearchURL(state) {
const url = new URL(location.href);
for (const key of ['q', 'category', 'sort', 'page']) {
url.searchParams.delete(key);
}
if (state.keyword) url.searchParams.set('q', state.keyword);
if (state.category !== 'all') url.searchParams.set('category', state.category);
if (state.sort !== 'newest') url.searchParams.set('sort', state.sort);
if (state.page !== 1) url.searchParams.set('page', String(state.page));
return url;
}
注意先移除当前页面受管理的参数,再写入新值,而不是清空全部参数;这样可避免误删其他模块持有的查询参数。
四、选择 pushState 还是 replaceState
History API 的两个常用入口是 pushState() 和 replaceState()。前者新增历史记录,后者修改当前记录。
当用户明确点击分页或切换分类时,新增历史记录通常符合预期;连续输入关键词时,如果每敲一个字符都新增历史记录,浏览器后退按钮就会变得难用。
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/3b1fdfe1df81b4fcab1fdd5c2f4f721906b49b7c" class="sort-toolbar" data-sort-toolbar>
<label>排序
<select data-sort>
<option value="newest">最新</option>
<option value="price_asc">价格从低到高</option>
<option value="price_desc">价格从高到低</option>
</select>
</label>
</div>
状态写入函数如下:
function writeSearchState(state, mode = 'push') {
const url = buildSearchURL(state);
const method = mode === 'replace' ? 'replaceState' : 'pushState';
history[method]({
searchState: state }, '', url);
}
pushState() 本身不会触发 popstate,所以调用后仍然需要主动更新当前组件的内容。
五、浏览器后退时恢复界面
当用户使用浏览器前进或后退时,当前 URL 会变化。页面可以监听 popstate,重新读取并规范化查询参数。
<section class="search-summary" data-search-summary>
<h2>当前搜索</h2>
<output data-current-filters>尚未选择筛选条件</output>
</section>
<a href="https://www.yxtiktok.com/blog/guides/">
window.addEventListener('popstate', () => {
const state = readSearchState();
syncControls(state);
void loadProducts(state);
});
syncControls 只负责更新输入框和下拉框;loadProducts 负责请求和渲染。拆分职责可以避免监听器中出现重复的状态写入逻辑。
六、关键词输入应重置分页
当用户从第八页切换到新的搜索关键词时,继续请求第八页通常不是理想行为。应在改变筛选条件时重置页码。
function updateFilters(current, patch) {
return {
...current,
...patch,
page: 1
};
}
构建分页组件时,页码按钮应携带明确的目标状态,而不是自行从 DOM 中猜测当前页。
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/d7c26d000f80788b7e4dc78215b6d24c656818e0" class="pagination" role="navigation" aria-label="搜索结果分页">
<button type="button" data-prev-page>上一页</button>
<output data-current-page>1</output>
<button type="button" data-next-page>下一页</button>
</div>
下面的控制区显示当前页面状态,便于排查刷新恢复问题:
<div class="search-debug" data-search-debug>
<output data-url-state aria-live="polite"></output>
</div>
<a href="https://www.yxtiktok.com/blog/guides/">
七、避免状态同步产生循环
一个常见错误是:URL 变化触发表单更新,表单更新又触发 URL 写入,最终产生重复渲染或不断增加历史记录。
更稳定的设计是明确两个方向:用户交互先更新状态,再写 URL;浏览器历史导航则从 URL 恢复状态,但不再写入新历史记录。
function handleUserFilterChange(patch) {
const next = updateFilters(readSearchState(), patch);
writeSearchState(next, 'push');
syncControls(next);
void loadProducts(next);
}
对于输入框的逐字输入,可以使用防抖,并采用 replaceState,避免每个字符都成为一条历史记录。
八、对异步查询添加版本保护
用户快速切换筛选条件时,旧请求可能后完成。应确保页面只渲染最新筛选对应的数据。
let queryVersion = 0;
async function loadProducts(state) {
const current = ++queryVersion;
const url = new URL('/api/products', location.origin);
url.search = buildSearchURL(state).search;
const response = await fetch(url);
if (!response.ok) throw new Error(`HTTP ${
response.status}`);
const products = await response.json();
if (current !== queryVersion) return;
renderProducts(products);
}
buildSearchURL 从当前地址继承查询参数,因此实际生产项目若存在与接口无关的参数,应使用专门的接口参数序列化器,不要把页面全部参数直接转发到服务端。
列表区域使用稳定的数据标记:
<section class="products-panel" data-products-panel>
<h2>搜索结果</h2>
<ul data-product-list></ul>
<p data-empty-result hidden>没有符合条件的数据</p>
</section>
<a href="https://www.yxtiktok.com/blog/guides/">
九、处理不存在和无效的筛选值
如果用户直接修改 URL,把 page 改为负数或 sort 改为未知值,页面应回退到允许范围。是否同步修正地址栏,可根据产品设计采用 replaceState,避免形成多余的历史记录。
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/f0fd989f0718977bf2a88e8d28816dbf9cb30d48" class="state-notice" data-state-notice>
<p data-invalid-filter-message role="status" hidden></p>
</div>
还可以提供清除筛选入口,将状态恢复到默认值:
<div class="search-reset-actions">
<button type="button" data-reset-filters>清除筛选</button>
</div>
<a href="https://www.yxtiktok.com/blog/guides/">
十、总结
使用 URLSearchParams 管理页面状态,能够使列表筛选、搜索、排序和分页拥有稳定的刷新恢复能力。History API 则让这些状态与浏览器前进、后退行为一致。
工程中最重要的是确定哪些状态进入 URL、参数如何校验,以及哪些用户行为应该形成历史记录。只要统一状态来源、写入规则与恢复流程,就能避免页面内状态和地址栏彼此矛盾。