#@guanriyue/decurl

@guanriyue/decurl 默认入口提供开箱即用的 React Router hooks。它们会在 hook 内部读取当前 React Router 的 location 和 navigate，不需要手动放置 Provider。

import { useSearchValue, useSearchValues } from '@guanriyue/decurl';

默认 hooks 使用默认的单例 search store。对于一个应用只有一套 React Router runtime 的场景，通常直接使用即可。

这些 hooks 需要运行在 React Router 上下文内，例如 BrowserRouter、RouterProvider 或其他 React Router runtime 内部。

如果需要显式提供 store、配置 store 行为，或者减少组件对 React Router useLocation 的直接依赖，见 @guanriyue/decurl/provided。

#useSearchValues

useSearchValues(searchFields) 读取和更新多个 search values。

useSearchValues(searchFields): [values, setValues]

参数：

返回值：

import { useSearchValues } from '@guanriyue/decurl';

const SearchPanel = () => {
  const [values, setValues] = useSearchValues(searchFields);

  return (
    <button
      type="button"
      onClick={() => {
        setValues({ page: values.page + 1 });
      }}
    >
      Next page
    </button>
  );
};

setValues(patch, options?) 接收 patch。只会更新传入字段，未传入字段保持不变。默认使用 { replace: true } 写回 URL。

传入 null 或 undefined 表示删除对应字段的 URL key。如果写入值等于 field 的 defaultValue，默认也会删除对应 key；是否保留 default value 由 URLSearchParams codec 的 encode 规则决定。

如果把整个 patch 传为 undefined，会删除当前 searchFields 中所有字段对应的 URL key，并保留 searchFields 之外的 search params：

setValues(undefined);

patch 也可以是 updater：

setValues((previousValues) => ({
  page: previousValues.page + 1,
}));

如果 updater 返回 undefined，语义与 setValues(undefined) 相同。

#useSearchValue

useSearchValue(codec) 读取和更新单个 field。传入的 codec 必须已经拥有确定的 name，通常来自 defineFields 的返回值。

useSearchValue(codec): [value, setValue]

参数：

返回值：

import { useSearchValue } from '@guanriyue/decurl';

const PageButton = () => {
  const [page, setPage] = useSearchValue(searchFields.page);

  return (
    <button
      type="button"
      onClick={() => {
        setPage(page + 1);
      }}
    >
      Next page
    </button>
  );
};

setValue(patch, options?) 同样支持直接值或 updater。默认使用 { replace: true } 写回 URL。

传入 null 或 undefined 表示删除该 field 对应的 URL key。如果写入值等于 field 的 defaultValue，默认也会删除对应 key。

setPage((previousPage) => previousPage + 1);

#Render behavior

默认 hooks 会在 hook 内部读取 React Router location。某些路由更新可能让组件跟随 React Router 重新渲染；如果你需要把 React Router 能力获取集中到独立组件，或观察相关渲染边界，可以阅读 @guanriyue/decurl/provided 和 Provided Runtime。

#Navigate options

setter 的第二个参数会透传给 React Router navigate。Decurl 默认使用 replace: true，避免频繁的 search params 更新写入大量 history entries。

setPage(1, { replace: true, preventScrollReset: true });

如果同一次 flush 前发生多次 setter 调用，会使用最后一次调用传入的 navigate options 覆盖默认值。

#SearchProvider

SearchProvider 提供一份独立的 search store，并可以配置 store options。默认 hooks 会优先读取最近的 SearchProvider store；如果没有 Provider，则使用默认 global store。

import { SearchProvider } from '@guanriyue/decurl';

<SearchProvider flushDelay={80} flushMode="debounce">
  <App />
</SearchProvider>

SearchProvider 只负责提供 store，不负责读取 React Router location 或 navigate。默认 hooks 会自己读取 React Router 能力；provided hooks 则需要配合 SearchRuntimeConnector 使用。

#Types

#Related

• @guanriyue/decurl/provided
• @guanriyue/decurl/codec
• React Router 集成概览