常用函数与方法

// app/page.js
export default async function Page() {
  // 请求会被缓存
  // 类似于 Pages Router 下的 `getStaticProps`.
  // `force-cache` 是默认选项，不写也行
  const staticData = await fetch(`https://...`, { cache: 'force-cache' })
 
  // 每次请求的时候都会重新获取
  // 类似于 Pages Router 下的 `getServerSideProps`.
  const dynamicData = await fetch(`https://...`, { cache: 'no-store' })
 
  // 请求会被缓存，最多缓存 10s
  // 类似于 Pages Router 下的 `getStaticProps` 使用 `revalidate` 选项.
  const revalidatedData = await fetch(`https://...`, {
    next: { revalidate: 10 },
  })
 
  return <div>...</div>
}

async function postData(url = "", data = {}) {
  const response = await fetch(url, {
    method: "POST",
    cache: "no-cache", // *default, no-cache, reload, force-cache, only-if-cached
    body: JSON.stringify(data), 
  });
  return response.json();
}

fetch(`https://...`, { cache: 'force-cache' | 'no-store' })

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

fetch(`https://...`, { next: { tags: ['collection'] } })

// app/page.js
import { cookies } from 'next/headers'
 
export default function Page() {
  const cookieStore = await cookies()
  // 如果匹配到，theme 的值为 { name: 'theme', value: 'xxxx' }
  // 如果没有匹配到，theme 的值为 undefined
  const theme = cookieStore.get('theme')
  return '...'
}

// app/page.js
import { cookies } from 'next/headers'
 
export default function Page() {
  const cookieStore = await cookies()
  // 如果匹配到，theme 的值为 [{ name: 'theme', value: 'xxxx' }]
  // 如果没有匹配到，theme 的值为 []
  const theme = cookieStore.get('theme')
  return '...'
}

// app/page.js
import { cookies } from 'next/headers'
 
export default function Page() {
  const cookieStore = await cookies()
  return cookieStore.getAll().map((cookie) => (
    <div key={cookie.name}>
      <p>Name: {cookie.name}</p>
      <p>Value: {cookie.value}</p>
    </div>
  ))
}

// app/page.js
import { cookies } from 'next/headers'
 
export default function Page() {
  const cookiesList = cookies()
  // true | false
  const hasCookie = cookiesList.has('theme')
  return '...'
}

'use server'
// app/actions.js
import { cookies } from 'next/headers'
 
async function create(data) {
  (await cookies()).set('name', 'lee')
  // or
  (await cookies()).set('name', 'lee', { secure: true })
  // or
  (await cookies()).set({
    name: 'name',
    value: 'lee',
    httpOnly: true,
    path: '/',
  })
}

'use server'
// app/actions.js
import { cookies } from 'next/headers'
 
export async function create(data) {
  (await cookies()).delete('name')
}

'use server'
// app/actions.js
import { cookies } from 'next/headers'
 
export async function create(data) {
  (await cookies()).set('name', '')
}

'use server'
// app/actions.js
import { cookies } from 'next/headers'
 
export async function create(data) {
  (await cookies()).set('name', 'value', { maxAge: 0 })
}

'use server'
// app/actions.js
import { cookies } from 'next/headers'
 
export async function create(data) {
  const oneDay = 24 * 60 * 60 * 1000
  (await cookies()).set('name', 'value', { expires: Date.now() - oneDay })
}

'use client'
// app/page.js
import { create } from './action'

export default async function Page({ params }) {
  const resolvedParams = await params
 
  return (
    <form action={create}>
      <input type="text" name="name" />
      <button type="submit">Submit</button>
    </form>
  );
}

// app/page.js
import { headers } from 'next/headers'
 
export default function Page() {
  const headersList = await headers()
  const referer = headersList.get('referer')
 
  return <div>Referer: {referer}</div>
}

const headersList = await headers()

// app/page.js
import { headers } from 'next/headers'
 
async function getUser() {
  const headersInstance = headers()
  const authorization = headersInstance.get('authorization')
  // 转发 authorization header
  const res = await fetch('...', {
    headers: { authorization },
  })
  return res.json()
}
 
export default async function UserPage() {
  const user = await getUser()
  return <h1>{user.name}</h1>
}

// 请求会有一个 `Set-Cookie:show-banner=false;path=/home` 标头
request.cookies.set('show-banner', 'false')

// { name: 'show-banner', value: 'false', Path: '/home' }
request.cookies.get('show-banner')

// [
//   { name: 'experiments', value: 'new-pricing-page', Path: '/home' },
//   { name: 'experiments', value: 'winter-launch', Path: '/home' },
// ]
request.cookies.getAll('experiments')
// 返回所有 cookie 值
request.cookies.getAll()

// 返回 true 表示删除成功, false 表示没有删掉任何东西
request.cookies.delete('experiments')

request.cookies.has('experiments')

request.cookies.clear()

// 假设请求是 /home, pathname 是 /home
request.nextUrl.pathname
// 请求是 /home?name=lee, searchParams 是 { 'name': 'lee' }
request.nextUrl.searchParams

// 请求未 /home
let response = NextResponse.next()
// 设置 cookie
response.cookies.set('show-banner', 'false')
// Response 的 Set-Cookie 标头为 `Set-Cookie:show-banner=false;path=/home`
return response

// 假设请求为 /home
let response = NextResponse.next()
// { name: 'show-banner', value: 'false', Path: '/home' }
response.cookies.get('show-banner')

// 假设请求为 /home
let response = NextResponse.next()
// [
//   { name: 'experiments', value: 'new-pricing-page', Path: '/home' },
//   { name: 'experiments', value: 'winter-launch', Path: '/home' },
// ]
response.cookies.getAll('experiments')
// 返回所有 cookie 值
response.cookies.getAll()

// 假设请求为 /home
let response = NextResponse.next()
// 返回 true 表示删除成功, false 表示没有删掉任何东西
response.cookies.delete('experiments')

// app/api/route.js
import { NextResponse } from 'next/server'
 
export async function GET(request) {
  return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 })
}

import { NextResponse } from 'next/server'
 
return NextResponse.redirect(new URL('/new', request.url))

import { NextResponse } from 'next/server'
 
const loginUrl = new URL('/login', request.url)
// 添加 ?from=/incoming-url 参数到 /login URL
loginUrl.searchParams.set('from', request.nextUrl.pathname)
// 重定向到新 URL
return NextResponse.redirect(loginUrl)

import { NextResponse } from 'next/server'
 
// 传入请求: /about, 浏览器显示 /about
// 重写请求: /proxy, 浏览器显示 /about
return NextResponse.rewrite(new URL('/proxy', request.url))

import { NextResponse } from 'next/server'
 
return NextResponse.next()

import { NextResponse } from 'next/server'
 
const newHeaders = new Headers(request.headers)
// 添加新 header
newHeaders.set('x-version', '123')
// 返回新的 headers
return NextResponse.next({
  request: {
    headers: newHeaders,
  },
})

redirect(path, type)

// app/team/[id]/page.js
import { redirect } from 'next/navigation'
 
async function fetchTeam(id) {
  const res = await fetch('https://...')
  if (!res.ok) return undefined
  return res.json()
}
 
export default async function Profile({ params }) {
  const { id } = await params
  const team = await fetchTeam(id)
  if (!team) {
    redirect('/login')
  }
 
  // ...
}

permanentRedirect(path, type)

// app/team/[id]/page.js
import { permanentRedirect } from 'next/navigation'
 
async function fetchTeam(id) {
  const res = await fetch('https://...')
  if (!res.ok) return undefined
  return res.json()
}
 
export default async function Profile({ params }) {
  const { id } = await params
  const team = await fetchTeam(id)
  if (!team) {
    permanentRedirect('/login')
  }
 
  // ...
}

// app/user/[id]/page.js 
import { notFound } from 'next/navigation'
 
async function fetchUser(id) {
  const res = await fetch('https://...')
  if (!res.ok) return undefined
  return res.json()
}
 
export default async function Profile({ params }) {
  const { id } = await params
  const user = await fetchUser(id)
 
  if (!user) {
    notFound()
  }
 
  // ...
}

'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 <></>
}

const params = useParams()

'use client'
// app/example-client-component.js
import { usePathname } from 'next/navigation'
 
export default function ExampleClientComponent() {
  const pathname = usePathname()
  return <p>Current pathname: {pathname}</p>
}

const pathname = usePathname()

'use client'
// app/example-client-component.js
import { usePathname, useSearchParams } from 'next/navigation'
 
function ExampleClientComponent() {
  const pathname = usePathname()
  const searchParams = useSearchParams()
  useEffect(() => {
    // 监听路由变化
  }, [pathname, searchParams])
}

'use client'
// app/example-client-component.js
import { useRouter } from 'next/navigation'
 
export default function Page() {
  const router = useRouter()
 
  return (
    <button type="button" onClick={() => router.push('/dashboard')}>
      Dashboard
    </button>
  )
}

'use client'
// app/components/navigation-events.js
import { useEffect } from 'react'
import { usePathname, useSearchParams } from 'next/navigation'
 
export function NavigationEvents() {
  const pathname = usePathname()
  const searchParams = useSearchParams()
 
  useEffect(() => {
    const url = `${pathname}?${searchParams}`
    console.log(url)
    // ...
  }, [pathname, searchParams])
 
  return null
}

// app/layout.js
import { Suspense } from 'react'
import { NavigationEvents } from './components/navigation-events'
 
export default function Layout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
 
        <Suspense fallback={null}>
          <NavigationEvents />
        </Suspense>
      </body>
    </html>
  )
}

'use client'
// app/example-client-component.jsx
import { useRouter } from 'next/navigation'
 
export default function Page() {
  const router = useRouter()
 
  return (
    <button
      type="button"
      onClick={() => router.push('/dashboard', { scroll: false })}
    >
      Dashboard
    </button>
  )
}

'use client'
// app/dashboard/search-bar.js
import { useSearchParams } from 'next/navigation'
 
export default function SearchBar() {
  const searchParams = useSearchParams()
 
  const search = searchParams.get('search')
 
  // URL -> `/dashboard?search=my-project`
  // `search` -> 'my-project'
  return <>Search: {search}</>
}

const searchParams = useSearchParams()

'use client'
// app/dashboard/search-bar.js
import { useSearchParams } from 'next/navigation'
 
export default function SearchBar() {
  const searchParams = useSearchParams()
 
  const search = searchParams.get('search')

  // 当使用静态渲染的时候，不会在服务端打印
  console.log(search)
 
  return <>Search: {search}</>
}

// app/dashboard/page.js
import { Suspense } from 'react'
import SearchBar from './search-bar'
 
function SearchBarFallback() {
  return <>placeholder</>
}
 
export default function Page() {
  return (
    <>
      <nav>
        <Suspense fallback={<SearchBarFallback />}>
          <SearchBar />
        </Suspense>
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

'use client'
// app/dashboard/search-bar.js
import { useSearchParams } from 'next/navigation'
 
export default function SearchBar() {
  const searchParams = useSearchParams()
 
  const search = searchParams.get('search')

  // 初始渲染的时候会在服务端打印，后续导航中客户端也会打印
  console.log(search)
 
  return <>Search: {search}</>
}

// app/dashboard/page.js
import SearchBar from './search-bar'
 
export const dynamic = 'force-dynamic'
 
export default function Page() {
  return (
    <>
      <nav>
        <SearchBar />
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

// app/example-client-component.js
export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()
 
  const createQueryString = useCallback(
    (name, value) => {
      const params = new URLSearchParams(searchParams)
      params.set(name, value)
 
      return params.toString()
    },
    [searchParams]
  )
 
  return (
    <>
      <p>Sort By</p>
 
      {/* 使用 useRouter */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        ASC
      </button>
 
      {/* 使用 <Link> */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        DESC
      </Link>
    </>
  )
}

// app/product/[id]/page.js
export function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }, { id: '3' }]
}
 
// 对应会生成 3 个静态路由：
// - /product/1
// - /product/2
// - /product/3
export default async function Page({ params }) {
  const { id } = await params
  // ...
}

// app/blog/[slug]/page.js
export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())
 
  return posts.map((post) => ({
    slug: post.slug,
  }))
}
 
export default async function Page({ params }) {
  const { slug } = await params
  // ...
}

// app/products/[category]/[product]/page.js
export function generateStaticParams() {
  return [
    { category: 'a', product: '1' },
    { category: 'b', product: '2' },
    { category: 'c', product: '3' },
  ]
}
 
// 对应会生成 3 个静态路由：
// - /products/a/1
// - /products/b/2
// - /products/c/3
export default async function Page({ params }) {
  const { category, product } = await params
  // ...
}

// app/product/[...slug]/page.js
export function generateStaticParams() {
  return [{ slug: ['a', '1'] }, { slug: ['b', '2'] }, { slug: ['c', '3'] }]
}
 
// 对应会生成 3 个静态路由：
// - /product/a/1
// - /product/b/2
// - /product/c/3
export default async function Page({ params }) {
  const { slug } = await params
  // ...
}

// app/products/[category]/layout.js
export async function generateStaticParams() {
  const products = await fetch('https://.../products').then((res) => res.json())
 
  return products.map((product) => ({
    category: product.category.slug,
  }))
}
 
export default async function Layout({ params }) {
  const resolvedParams = await params
  // ...
}

// app/products/[category]/[product]/page.js
export async function generateStaticParams({ params: { category } }) {
  const products = await fetch(
    `https://.../products?category=${category}`
  ).then((res) => res.json())
 
  return products.map((product) => ({
    product: product.id,
  }))
}
 
export default async function Page({ params }) {
  const resolvedParams = await params
  // ...
}

// app/products/[category]/[product]/page.js
export async function generateStaticParams() {
  const products = await fetch('https://.../products').then((res) => res.json())
 
  return products.map((product) => ({
    category: product.category.slug,
    product: product.id,
  }))
}
 
export default async function Page({ params }) {
  const resolvedParams = await params
  // ...
}

// layout.js | page.js 
export const viewport = {
  themeColor: 'black',
}
 
export default function Page() {}

export async function generateViewport({ params }) {
  const resolvedParams = await params
  return {
    themeColor: '...',
  }
}

// layout.js | page.js
export const viewport = {
  themeColor: 'black',
}

<meta name="theme-color" content="black" />

export const viewport = {
  themeColor: [
    { media: '(prefers-color-scheme: light)', color: 'cyan' },
    { media: '(prefers-color-scheme: dark)', color: 'black' },
  ],
}

<meta name="theme-color" media="(prefers-color-scheme: light)" content="cyan" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black" />

// layout.js | page.js
export const viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  // 也支持
  // interactiveWidget: 'resizes-visual',
}

<meta
  name="viewport"
  content="width=device-width, initial-scale=1, maximum-scale=1"
/>

// layout.js | page.js
export const viewport = {
  colorScheme: 'dark',
}

<meta name="color-scheme" content="dark" />

revalidatePath(path: string, type?: 'page' | 'layout'): void;

import { revalidatePath } from 'next/cache'
revalidatePath('/blog/post-1')

import { revalidatePath } from 'next/cache'
revalidatePath('/blog/[slug]', 'page')
// 带路由组也可以
revalidatePath('/(main)/post/[slug]', 'page')

import { revalidatePath } from 'next/cache'
revalidatePath('/blog/[slug]', 'layout')
// 带路由组也可以
revalidatePath('/(main)/post/[slug]', 'layout')

import { revalidatePath } from 'next/cache'
 
revalidatePath('/', 'layout')

'use server'
// app/actions.js
import { revalidatePath } from 'next/cache'
 
export default async function submit() {
  await submitForm()
  revalidatePath('/')
}

// app/api/revalidate/route.js
import { revalidatePath } from 'next/cache'
 
export async function GET(request) {
  const path = request.nextUrl.searchParams.get('path')
 
  if (path) {
    revalidatePath(path)
    return Response.json({ revalidated: true, now: Date.now() })
  }
 
  return Response.json({
    revalidated: false,
    now: Date.now(),
    message: 'Missing path to revalidate',
  })
}

revalidateTag(tag: string): void;

fetch(url, { next: { tags: [...] } });

// app/actions.js
import { revalidateTag } from 'next/cache'
 
export async function GET(request) {
  const tag = request.nextUrl.searchParams.get('tag')
  revalidateTag(tag)
  return Response.json({ revalidated: true, now: Date.now() })
}

// app/api/revalidate/route.js
import { revalidateTag } from 'next/cache'
 
export async function GET(request) {
  const tag = request.nextUrl.searchParams.get('tag')
  revalidateTag(tag)
  return Response.json({ revalidated: true, now: Date.now() })
}

import { getUser } from './data';
import { unstable_cache } from 'next/cache';
 
const getCachedUser = unstable_cache(
  async (id) => getUser(id),
  ['my-app-user']
);
 
export default async function Component({ userID }) {
  const user = await getCachedUser(userID);
  ...
}

const data = unstable_cache(fetchData, keyParts, options)()

import { unstable_noStore as noStore } from 'next/cache';
 
export default async function Component() {
  noStore();
  const result = await db.query(...);
  ...
}

import { unstable_noStore as noStore } from 'next/cache';
 
export default async function Component() {
  noStore();
  const result = await db.query(...);
  ...
}

'use client'
// app/example-client-component.js
import { useSelectedLayoutSegment } from 'next/navigation'
 
export default function ExampleClientComponent() {
  const segment = useSelectedLayoutSegment()
 
  return <p>Active segment: {segment}</p>
}

// app/blog/layout.js
import BlogNavLink from './blog-nav-link'
import getFeaturedPosts from './get-featured-posts'
 
export default async function Layout({ children }) {
  const featuredPosts = await getFeaturedPosts()
  return (
    <div>
      {featuredPosts.map((post) => (
        <div key={post.id}>
          <BlogNavLink slug={post.slug}>{post.title}</BlogNavLink>
        </div>
      ))}
      <div>{children}</div>
    </div>
  )
}

'use client'
// app/blog/blog-nav-link.js
import Link from 'next/link'
import { useSelectedLayoutSegment } from 'next/navigation'
 
export default function BlogNavLink({ slug, children }) {
  const segment = useSelectedLayoutSegment()
  const isActive = slug === segment
 
  return (
    <Link
      href={`/blog/${slug}`}
      style={{ fontWeight: isActive ? 'bold' : 'normal' }}
    >
      {children}
    </Link>
  )
}

// app/blog/get-featured-posts.js
export default async function getFeaturedPosts() {
  await new Promise((resolve) => setTimeout(resolve, 3000))
  return [
    { id: '1', slug: 'article1', title: '文章 1'},
    { id: '2', slug: 'article2', title: '文章 2'},
    { id: '3', slug: 'article3', title: '文章 3'}
  ]
}

// app/blog/[slug]/page.js
export default async function Page({ params }) {
  const { slug } = await params
  return <div>当前 slug: {slug}</div>
}

const segment = useSelectedLayoutSegment(parallelRoutesKey?: string)

'use client'
// app/example-client-component.js
import { useSelectedLayoutSegments } from 'next/navigation'
 
export default function ExampleClientComponent() {
  const segments = useSelectedLayoutSegments()
 
  return (
    <ul>
      {segments.map((segment, index) => (
        <li key={index}>{segment}</li>
      ))}
    </ul>
  )
}

const segments = useSelectedLayoutSegments(parallelRoutesKey?: string)