logo
Zess
指南
API
演练场
English
简体中文
指南
API
演练场
English
简体中文
logo
Zess

开始

介绍
快速开始

核心功能

响应性基础
生命周期
内置组件
响应性工具类
Store 工具类
次要 API
渲染
特殊 JSX 属性

路由系统

内置组件
基础 API
📝 在 GitHub 上编辑此页
上一页内置组件

#基础 API

#useNavigate

返回一个用于在路由间进行编程式导航的函数的钩子。

类型:

useNavigate(): (href: string, options?: NavigateOptions) => void

参数:

  • href: 目标路径,可包含查询字符串
  • options: 可选配置
    • relative: 如果为 false,导航到绝对路径,忽略相对基准。默认为 true
    • replace: 如果为 true,替换当前历史记录
    • noScroll: 如果为 true,阻止导航时滚动到顶部
    • state: 可选的状态对象,会被传递给 history.state。默认为 null

示例:

function NavigationComponent() {
  const navigate = useNavigate()

  return (
    <>
      <button onClick={() => navigate('/')}>首页</button>
      <button onClick={() => navigate('/products', { relative: false })}>
        产品
      </button>
      <button onClick={() => navigate('/login', { replace: true })}>
        登录
      </button>
      <button onClick={() => navigate('/details', { noScroll: true })}>
        查看详情(不滚动)
      </button>
      <button onClick={() => navigate('/search?q=zess&page=1')}>
        搜索 Zess(第1页)
      </button>
      <button onClick={() => navigate('/checkout', { state: { userId: 1 } })}>
        前往结账
      </button>
    </>
  )
}

#useSearchParams

提供对搜索参数访问权限以及更新这些参数的函数的钩子。

类型:

useSearchParams(): [SearchParams, (params: Record<string, any>, options?: SearchParamsOptions) => void]

返回值: 包含以下内容的数组

  • searchParams: 响应式对象,包含当前搜索参数,当 location.search 更改或通过 setSearchParams 修改时会自动更新
  • setSearchParams: 更新搜索参数的函数
    • params: 要与现有参数合并的搜索参数。将属性值设置为 undefined、null 或空字符串会移除该属性
    • options: 可选的配置对象
      • replace: 可选标志,用于替换当前历史记录条目而不是添加新条目
      • state: 可选的状态对象,会被传递给 history.state。默认为 null

示例:

function ProductFilter() {
  const [searchParams, setSearchParams] = useSearchParams()
  const setCategory = (category) => setSearchParams({ category })
  const search = (keyword, searchType) => {
    setSearchParams(
      { keyword },
      {
        replace: true,
        state: { searchType },
      },
    )
  }
  const clearFilters = () => {
    setSearchParams({ category: undefined, keyword: undefined })
  }

  return (
    <div>
      <p>当前分类: {searchParams.category || '全部'}</p>
      <p>搜索关键词: {searchParams.keyword || '无'}</p>
      <button onClick={() => setCategory('shoes')}>设置分类</button>
      <button onClick={() => search('sale', 'quick')}>按类型搜索</button>
      <button onClick={clearFilters}>清除筛选</button>
    </div>
  )
}

#useBeforeLeave

注册一个在离开当前路由前调用的监听器的钩子。这允许您拦截导航尝试并可能阻止它们,例如,警告用户有关未保存的更改。

类型:

useBeforeLeave(listener: RouteGuardListener): void

参数:

  • listener: 当尝试从当前路由导航离开时调用的函数,接收 RouteGuardEvent 对象
    • event: 路由守卫事件对象,包含:
      • to: 要导航到的目标路径
      • from: 正在导航离开的当前路径
      • options: 导航选项,包括 relative、replace 和 noScroll
      • defaultPrevented: 布尔值,指示导航是否已被阻止
      • preventDefault: 阻止导航的函数
      • retry: 稍后重试导航的函数,带有可选的 force 参数以绕过守卫

示例:

function FormEditor() {
  const [hasUnsavedChanges, setHasUnsavedChanges] = useSignal(false)
  useBeforeLeave((event) => {
    if (hasUnsavedChanges()) {
      const confirmed = window.confirm('您有未保存的更改。确定要离开吗?')
      if (!confirmed) {
        event.preventDefault()
      }
    }
  })

  return (
    <div>
      <input type="text" onChange={() => setHasUnsavedChanges(true)} />
      <button onClick={() => setHasUnsavedChanges(false)}>保存</button>
    </div>
  )
}

#useLocation

返回一个响应式 Location 对象的钩子,该对象包含当前 URL 的相关信息。当 URL 变化时,此对象会自动更新。

类型:

useLocation(): Location

返回值: 一个带有 pathname 和其他属性的响应式 Location 对象

  • pathname: URL 的路径部分,不包含查询字符串
  • search: URL 的查询字符串部分
  • hash: URL 的哈希部分,包含 # 符号
  • state: 与当前历史记录条目关联的状态对象,通过 useNavigate 或 <Link> 组件传递
  • query: 包含 URL 所有查询参数的响应式对象

示例:

function LocationDisplay() {
  const location = useLocation()

  return (
    <div>
      <h2>当前位置信息</h2>
      <p>路径: {location.pathname}</p>
      <p>查询字符串: {location.search}</p>
      <p>哈希值: {location.hash}</p>
      <p>状态: {JSON.stringify(location.state)}</p>
      <p>查询参数: {JSON.stringify(location.query)}</p>
    </div>
  )
}