Next.js 中常用的函数 API

前言

在 Next.js 中内置了许多 API 供我们使用，其中有关函数的 API 在实际项目中使用的是最多的，对于一些常用的函数方法我们可以直接导入并使用。

常用函数 API

cookies

在 Next.js 官方文档中表明，cookies 函数允许我们从服务端组件 读取 HTTP 传入请求的 cookie，同时还允许我们在路由处理程序 和 Server Action 中写入传出请求的 cookie。

值得注意的是 ，cookies() 函数是一个动态函数，我们无法提前确定其返回值，因此在页面或者布局中使用此函数会导致在请求时选择进入动态渲染的路由。

cookies().get(name)

调用此方法会返回一个带有 name 和 value 属性的对象。

如果未找到带有 name 的 cookie，则返回 undefined，如果有多个 cookie 匹配，则仅返回第一个匹配到的。

import { cookies } from 'next/headers'

export default function Page() {
  const cookieStore = cookies()
  const theme = cookieStore.get('theme')
  return '...'
}

cookies().set(name, value, options)

调用此方法可用于设置 cookie，值得注意的是，该方法只能在开始发送响应体之前使用，也就是说只能在路由处理程序和 Server Action 中使用。

Cookies 是通过 HTTP 的 Set-Cookie 头部来设置的，在响应体已经开始发送后尝试设置 cookies 会导致失败，因为此时 HTTP 头部已经发送完毕，不能再添加或修改 Set-Cookie 头部。

'use server'

import { cookies } from 'next/headers'

async function create(data) {
  cookies().set('name', 'lee')
  // or
  cookies().set('name', 'lee', { secure: true })
  // or
  cookies().set({
    name: 'name',
    value: 'lee',
    httpOnly: true,
    path: '/',
  })
}

cookies().delete(name)

调用此方法可以删除指定名称的 cookie，我们只能删除路由处理程序和 Server Action 中的 cookie。

'use server'

import { cookies } from 'next/headers'

async function delete(data) {
  cookies().delete('name')
}

更多有关 cookies 函数使用的方法可查阅官网 API 参考中的 cookies 这一部分。

fetch

Next.js 扩展了原生的 fetch API，在此基础上，我们可以为每个服务端组件中发送的请求设置自己的缓存模式。

在组件中直接调用 fetch(url, options) 方法发送网络请求。

export default async function Page() {
  // 此请求应该被缓存，直到手动使其无效
  // 类似于 `getStaticProps`
  // 'force-cache' 是默认值，可以省略
  const staticData = await fetch(`https://...`, { cache: 'force-cache' })
 
  // 每次请求的时候都会重新获取
  // 类似于 `getServerSideProps`
  const dynamicData = await fetch(`https://...`, { cache: 'no-store' })
 
  // 请求会被缓存，最多缓存 10s
  // 类似于 `getStaticProps` 使用 `revalidate` 选项
  const revalidatedData = await fetch(`https://...`, {
    next: { revalidate: 10 }
  })
 
  return <div>...</div>
}

options.next.revalidate

fetch(`https://...`, { next: { revalidate: false | 0 | number } })

此选项用于设置资源的缓存生命周期，revalidate 可以被设置为 false、0 和 number。

revalidate 设置为 false，意味着无限期缓存资源 ，语义上等同于 revalidate: Infinity，但是随着时间的推移，HTTP 缓存可能会驱逐较旧的资源。

revalidate 设置为 0，意味着防止资源被缓存。

revalidate 设置为 number，意味指定资源的缓存生存期最多应为 n 秒。

值得注意的是，如果 revalidate 设置为数字，则无需设置 cache 选项，因为 0 意味着 cache: 'no-store'，正值意味着 cache: 'force-cache'。

如果同一路由中具有相同 URL 的两个 fetch 请求具有不同的 revalidate 值，则将使用较低的值。

useParams

useParams 其实是一个客户端组件钩子，可让我们读取由当前 URL 填充的路由的动态参数。

'use client'
// app/example-client-component.js
import { useParams } from 'next/navigation'
 
export default function ExampleClientComponent() {
  const params = useParams()
 
  // 路由 -> /shop/[tag]/[item]
  // URL -> /shop/shoes/nike-air-max-97
  // `params` -> { tag: 'shoes', item: 'nike-air-max-97' }
  console.log(params)
 
  return <></>
}

使用 useParams 的时候不带任何参数，直接调用即可。

const params = useParams()

调用 useParams 返回的结果是一个对象，其中包含动态参数中填充的当前路由，如下方表格中的示例所示。

路由	URL	useParams()
app/shop/page.js	/shop	{}
app/shop/[slug]/page.js	/shop/1	{ slug: '1' }
app/shop/[tag]/[item]/page.js	/shop/1/2	{ tag: '1', item: '2' }
app/shop/[...slug]/page.js	/shop/1/2	{ slug: ['1', '2'] }

usePathname

usePathname 同样是一个客户端组件钩子，可让我们读取当前 URL 的路径名，值得注意的是，不支持从服务端组件中读取当前的 URL 值，意味着我们要在客户端组件中使用此方法。

'use client'

import { usePathname } from 'next/navigation'

export default function ExampleClientComponent() {
  const pathname = usePathname()
  return <p>Current pathname: {pathname}</p>
}

使用 usePathname 的时候不带任何参数，直接调用即可。

const pathname = usePathname()

调用 usePathname 返回的是当前 URL 路径名的字符串，如下方表格中的示例所示。

URL	返回值
/	'/'
/dashboard	'/dashboard'
/dashboard?v=2	'/dashboard'
/blog/hello-world	'/blog/hello-world'

总结

Next.js 中有关函数的 API 不止上述这几种，还有很多不常用的函数方法，如果在实际的项目中需要用到，在官方文档中随查随用，不用刻意去记住这些方法，但是常用的几个函数 API 还是要牢记于心。