Unverified Commit ab6aeab5 authored by Lee Robinson's avatar Lee Robinson Committed by GitHub

docs: improve JSDocs for `metadata` and `<Link>` (#75576)

Co-authored-by: 's avatarJiachi Liu <inbox@huozhi.im>
parent 263dc23a
...@@ -664,6 +664,10 @@ export const metadata = { ...@@ -664,6 +664,10 @@ export const metadata = {
> **Deprecated**: The `themeColor` option in `metadata` is deprecated as of Next.js 14. Please use the [`viewport` configuration](/docs/app/api-reference/functions/generate-viewport) instead. > **Deprecated**: The `themeColor` option in `metadata` is deprecated as of Next.js 14. Please use the [`viewport` configuration](/docs/app/api-reference/functions/generate-viewport) instead.
### `colorScheme`
> **Deprecated**: The `colorScheme` option in `metadata` is deprecated as of Next.js 14. Please use the [`viewport` configuration](/docs/app/api-reference/functions/generate-viewport) instead.
### `manifest` ### `manifest`
A web application manifest, as defined in the [Web Application Manifest specification](https://developer.mozilla.org/docs/Web/Manifest). A web application manifest, as defined in the [Web Application Manifest specification](https://developer.mozilla.org/docs/Web/Manifest).
......
...@@ -33,79 +33,168 @@ type OptionalKeys<T> = { ...@@ -33,79 +33,168 @@ type OptionalKeys<T> = {
type InternalLinkProps = { type InternalLinkProps = {
/** /**
* The path or URL to navigate to. It can also be an object. * **Required**. The path or URL to navigate to. It can also be an object (similar to `URL`).
* *
* @example https://nextjs.org/docs/api-reference/next/link#with-url-object * @example
* ```tsx
* // Navigate to /dashboard:
* <Link href="/dashboard">Dashboard</Link>
*
* // Navigate to /about?name=test:
* <Link href={{ pathname: '/about', query: { name: 'test' } }}>
* About
* </Link>
* ```
*
* @remarks
* - For external URLs, use a fully qualified URL such as `https://...`.
* - In the App Router, dynamic routes must not include bracketed segments in `href`.
*/ */
href: Url href: Url
/** /**
* Optional decorator for the path that will be shown in the browser URL bar. Before Next.js 9.5.3 this was used for dynamic routes, check our [previous docs](https://github.com/vercel/next.js/blob/v9.5.2/docs/api-reference/next/link.md#dynamic-routes) to see how it worked. Note: when this path differs from the one provided in `href` the previous `href`/`as` behavior is used as shown in the [previous docs](https://github.com/vercel/next.js/blob/v9.5.2/docs/api-reference/next/link.md#dynamic-routes). * @deprecated v10.0.0: `href` props pointing to a dynamic route are
* automatically resolved and no longer require the `as` prop.
*/ */
as?: Url as?: Url
/** /**
* Replace the current `history` state instead of adding a new url into the stack. * Replace the current `history` state instead of adding a new URL into the stack.
* *
* @defaultValue `false` * @defaultValue `false`
*
* @example
* ```tsx
* <Link href="/about" replace>
* About (replaces the history state)
* </Link>
* ```
*/ */
replace?: boolean replace?: boolean
/** /**
* Whether to override the default scroll behavior * Whether to override the default scroll behavior. If `true`, Next.js attempts to maintain
* the scroll position if the newly navigated page is still visible. If not, it scrolls to the top.
* *
* @example https://nextjs.org/docs/api-reference/next/link#disable-scrolling-to-the-top-of-the-page * If `false`, Next.js will not modify the scroll behavior at all.
* *
* @defaultValue `true` * @defaultValue `true`
*
* @example
* ```tsx
* <Link href="/dashboard" scroll={false}>
* No auto scroll
* </Link>
* ```
*/ */
scroll?: boolean scroll?: boolean
/** /**
* Update the path of the current page without rerunning [`getStaticProps`](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-static-props), [`getServerSideProps`](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-server-side-props) or [`getInitialProps`](/docs/pages/api-reference/functions/get-initial-props). * Update the path of the current page without rerunning data fetching methods
* like `getStaticProps`, `getServerSideProps`, or `getInitialProps`.
*
* @remarks
* `shallow` only applies to the Pages Router. For the App Router, see the
* [following documentation](https://nextjs.org/docs/app/building-your-application/routing/linking-and-navigating#using-the-native-history-api).
* *
* @defaultValue `false` * @defaultValue `false`
*
* @example
* ```tsx
* <Link href="/blog" shallow>
* Shallow navigation
* </Link>
* ```
*/ */
shallow?: boolean shallow?: boolean
/** /**
* Forces `Link` to send the `href` property to its child. * Forces `Link` to pass its `href` to the child component. Useful if the child is a custom
* component that wraps an `<a>` tag, or if you're using certain styling libraries.
* *
* @defaultValue `false` * @defaultValue `false`
*
* @example
* ```tsx
* <Link href="/dashboard" passHref>
* <MyStyledAnchor>Dashboard</MyStyledAnchor>
* </Link>
* ```
*/ */
passHref?: boolean passHref?: boolean
/** /**
* Prefetch the page in the background. * Prefetch the page in the background.
* Any `<Link />` that is in the viewport (initially or through scroll) will be prefetched. * Any `<Link />` that is in the viewport (initially or through scroll) will be prefetched.
* Prefetch can be disabled by passing `prefetch={false}`. Prefetching is only enabled in production. * Prefetch can be disabled by passing `prefetch={false}`.
*
* @remarks
* Prefetching is only enabled in production.
*
* - In the **App Router**:
* - `null` (default): Prefetch behavior depends on static vs dynamic routes:
* - Static routes: fully prefetched
* - Dynamic routes: partial prefetch to the nearest segment with a `loading.js`
* - `true`: Always prefetch the full route and data.
* - `false`: Disable prefetching on both viewport and hover.
* - In the **Pages Router**:
* - `true` (default): Prefetches the route and data in the background on viewport or hover.
* - `false`: Prefetch only on hover, not on viewport.
* *
* In App Router: * @defaultValue `true` (Pages Router) or `null` (App Router)
* - `null` (default): For statically generated pages, this will prefetch the full React Server Component data. For dynamic pages, this will prefetch up to the nearest route segment with a [`loading.js`](https://nextjs.org/docs/app/api-reference/file-conventions/loading) file. If there is no loading file, it will not fetch the full tree to avoid fetching too much data.
* - `true`: This will prefetch the full React Server Component data for all route segments, regardless of whether they contain a segment with `loading.js`.
* - `false`: This will not prefetch any data, even on hover.
* *
* In Pages Router: * @example
* - `true` (default): The full route & its data will be prefetched. * ```tsx
* - `false`: Prefetching will not happen when entering the viewport, but will still happen on hover. * <Link href="/dashboard" prefetch={false}>
* @defaultValue `true` (pages router) or `null` (app router) * Dashboard
* </Link>
* ```
*/ */
prefetch?: boolean | null prefetch?: boolean | null
/** /**
* The active locale is automatically prepended. `locale` allows for providing a different locale. * The active locale is automatically prepended in the Pages Router. `locale` allows for providing
* When `false` `href` has to include the locale as the default behavior is disabled. * a different locale, or can be set to `false` to opt out of automatic locale behavior.
* Note: This is only available in the Pages Router. *
* @remarks
* Note: locale only applies in the Pages Router and is ignored in the App Router.
*
* @example
* ```tsx
* // Use the 'fr' locale:
* <Link href="/about" locale="fr">
* About (French)
* </Link>
*
* // Disable locale prefix:
* <Link href="/about" locale={false}>
* About (no locale prefix)
* </Link>
* ```
*/ */
locale?: string | false locale?: string | false
/** /**
* Enable legacy link behavior. * Enable legacy link behavior, requiring an `<a>` tag to wrap the child content
* if the child is a string or number.
*
* @defaultValue `false` * @defaultValue `false`
* @see https://github.com/vercel/next.js/commit/489e65ed98544e69b0afd7e0cfc3f9f6c2b803b7 * @see https://github.com/vercel/next.js/commit/489e65ed98544e69b0afd7e0cfc3f9f6c2b803b7
*/ */
legacyBehavior?: boolean legacyBehavior?: boolean
/** /**
* Optional event handler for when the mouse pointer is moved onto Link * Optional event handler for when the mouse pointer is moved onto the `<Link>`.
*/ */
onMouseEnter?: React.MouseEventHandler<HTMLAnchorElement> onMouseEnter?: React.MouseEventHandler<HTMLAnchorElement>
/** /**
* Optional event handler for when Link is touched. * Optional event handler for when the `<Link>` is touched.
*/ */
onTouchStart?: React.TouchEventHandler<HTMLAnchorElement> onTouchStart?: React.TouchEventHandler<HTMLAnchorElement>
/** /**
* Optional event handler for when Link is clicked. * Optional event handler for when the `<Link>` is clicked.
*/ */
onClick?: React.MouseEventHandler<HTMLAnchorElement> onClick?: React.MouseEventHandler<HTMLAnchorElement>
} }
...@@ -400,12 +489,14 @@ function formatStringOrUrl(urlObjOrString: UrlObject | string): string { ...@@ -400,12 +489,14 @@ function formatStringOrUrl(urlObjOrString: UrlObject | string): string {
} }
/** /**
* A React component that extends the HTML `<a>` element to provide [prefetching](https://nextjs.org/docs/app/building-your-application/routing/linking-and-navigating#2-prefetching) * A React component that extends the HTML `<a>` element to provide
* and client-side navigation between routes. * [prefetching](https://nextjs.org/docs/app/building-your-application/routing/linking-and-navigating#2-prefetching)
* and client-side navigation. This is the primary way to navigate between routes in Next.js.
* *
* It is the primary way to navigate between routes in Next.js. * @remarks
* - Prefetching is only enabled in production.
* *
* Read more: [Next.js docs: `<Link>`](https://nextjs.org/docs/app/api-reference/components/link) * @see https://nextjs.org/docs/app/api-reference/components/link
*/ */
const Link = React.forwardRef<HTMLAnchorElement, LinkPropsReal>( const Link = React.forwardRef<HTMLAnchorElement, LinkPropsReal>(
function LinkComponent(props, forwardedRef) { function LinkComponent(props, forwardedRef) {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment