next-nprogress-bar

<div align="center"> <h1>Next NProgress 进度条</h1> <p>在 Next.js 上集成 NProgress，兼容 /app 和 /pages 文件夹</p> </div>

开始使用
- 安装
- 导入
- 使用
/pages/_app 示例
- JavaScript
- TypeScript
/app/layout 示例
- JavaScript
  - 第一种方法：在 use client 布局中使用
  - 第二种方法：包装在 use client Providers 组件中
- TypeScript
  - 第一种方法：在 use client 布局中使用
  - 第二种方法：包装在 use client Providers 组件中
数据属性
- 在特定链接上禁用进度条
属性
App 目录路由器
- 导入
- 类型
- 使用
从 v1 迁移到 v2
问题
许可证

开始使用

安装

npm install next-nprogress-bar

或

yarn add next-nprogress-bar

导入

在 /pages/_app(.js/.jsx/.ts/.tsx) 或 /app/layout(.js/.jsx/.ts/.tsx) 文件中导入

// 在 app 目录中
import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';

// 在 pages 目录中
import { PagesProgressBar as ProgressBar } from 'next-nprogress-bar';

使用

<ProgressBar />

/pages/_app 示例

JavaScript

import { PagesProgressBar as ProgressBar } from 'next-nprogress-bar';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <ProgressBar
        height="4px"
        color="#fffd00"
        options={{ showSpinner: false }}
        shallowRouting
      />
    </>
  );
}

TypeScript

import type { AppProps } from 'next/app';
import { PagesProgressBar as ProgressBar } from 'next-nprogress-bar';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <ProgressBar
        height="4px"
        color="#fffd00"
        options={{ showSpinner: false }}
        shallowRouting
      />
    </>
  );
}

/app/layout 示例

JavaScript

第一种方法：在 use client 布局中使用

// 在 /app/layout.jsx 中
'use client';

import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <ProgressBar
          height="4px"
          color="#fffd00"
          options={{ showSpinner: false }}
          shallowRouting
        />
      </body>
    </html>
  );
}

第二种方法：包装在 use client Providers 组件中

参见 Next.js 文档

/components/ProgressBarProvider.jsx

// 创建一个 Providers 组件来包装您的应用程序，包含所有需要 'use client' 的组件，如 next-nprogress-bar 或您的不同上下文...
'use client';

import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';

const Providers = ({ children }) => {
  return (
    <>
      {children}
      <ProgressBar
        height="4px"
        color="#fffd00"
        options={{ showSpinner: false }}
        shallowRouting
      />
    </>
  );
};

export default Providers;

/app/layout.jsx

// 在 /app/layout.jsx 中导入并使用
import Providers from './providers';

export const metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
};

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

TypeScript

第一种方法：在 use client 布局中使用

// 在 /app/layout.tsx 中
'use client';

import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <ProgressBar
          height="4px"
          color="#fffd00"
          options={{ showSpinner: false }}
          shallowRouting
        />
      </body>
    </html>
  );
}

第二种方法：包装在 use client Providers 组件中

参见 Next.js 文档

/components/ProgressBarProvider.tsx

// 创建一个 Providers 组件来包装您的应用程序，包含所有需要 'use client' 的组件，如 next-nprogress-bar 或您的不同上下文...
'use client';

import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';

const Providers = ({ children }: { children: React.ReactNode }) => {
  return (
    <>
      {children}
      <ProgressBar
        height="4px"
        color="#fffd00"
        options={{ showSpinner: false }}
        shallowRouting
      />
    </>
  );
};

export default Providers;

/app/layout.tsx

// 在 /app/layout.tsx 中导入并使用
import Providers from './providers';

export const metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

数据属性

在特定链接上禁用进度条

您可以通过添加 data-disable-nprogress={true} 属性来在特定链接上禁用进度条。

/!\ 这在 svg 元素中的 Link 上不起作用。

<Link href="#features" data-disable-nprogress={true}>
  功能
</Link>

防止进度

您可以通过添加 data-prevent-nprogress={true} 属性来防止进度条启动。

<Link href="/dashboard">
  <span>仪表板</span>
  <span onClick={(e) => e.preventDefault()} data-prevent-nprogress={true}>
    阻止默认行为
  </span>
</Link>

属性

height 可选 - 字符串

进度条的高度 - 默认为 2px

color 可选 - 字符串

进度条的颜色 - 默认为 #0A2FFF

options 可选 - NProgressOptions

默认为 undefined

参见 NProgress 文档

shallowRouting 可选 - 布尔值

如果在只改变 URL 参数而不改变路由时不显示进度条 - 默认为 false

参见 Next.js 文档

startPosition 可选 - 数字

进度条开始的位置，从 0 到 1 - 默认为 0

delay 可选 - 数字

当页面加载速度快于进度条时，它不显示 - 默认为 0

disableSameURL 可选 - 布尔值

当目标 URL 与当前 URL 相同时禁用进度条 - 默认为 true

stopDelay 可选 - 数字

进度条停止前的延迟时间（毫秒） - 默认为 0

nonce 可选 - 字符串

用于在内容安全策略中声明内联脚本的加密随机数（仅使用一次的数字） - 默认为 undefined

memo 可选 - 布尔值

用于在内容安全策略中声明内联脚本的加密随机数（仅使用一次的数字） - 默认为 true

style 可选 - 字符串

您的自定义 CSS - 默认为 NProgress CSS

shouldCompareComplexProps 可选 - 布尔值

激活组件属性的详细比较，以确定是否需要重新渲染。当设置为 true 时，组件只会在关键属性如 color、height、shallowRouting、delay、options 和 style 发生变化时重新渲染。这对于优化性能在这些属性不经常变化的情况下很有用。如果未提供或设置为 false，组件将假定属性没有变化，不会重新渲染，这可以在属性保持静态的情况下提高性能。 - 默认为 undefined

targetPreprocessor 可选 - (url: URL) => URL - (仅适用于 app 目录进度条)

提供一个自定义函数来预处理目标 URL，然后再与当前 URL 进行比较。这在 URL 在导航后经过转换（如本地化或路径修改）的场景中特别有用。该函数接收一个 URL 对象作为输入，应返回一个修改后的 URL 对象。如果提供了此属性，预处理后的 URL 将用于比较，确保准确判断导航目标是否与当前 URL 等效。这可以防止在目标 URL 经过预处理后实际上与当前 URL 相同时不必要地显示进度条。 - 默认为 undefined

App 目录路由器

导入

import { useRouter } from 'next-nprogress-bar';

类型

router.push(url: string, options?: NavigateOptions, NProgressOptions?: RouterNProgressOptions)
router.replace(url: string, options?: NavigateOptions, NProgressOptions?: RouterNProgressOptions)
router.back(NProgressOptions?: RouterNProgressOptions)

NavigateOptions 是 next 路由器的选项。

interface RouterNProgressOptions {
  showProgressBar?: boolean;
  startPosition?: number;
  disableSameURL?: boolean;
}

使用

用这个替换您的 'next/navigation' 路由器。它是相同的路由器，但这个支持 NProgress。

const router = useRouter();

// 带进度条
router.push('/about');
router.replace('/?counter=10');
router.back();

从 v1 迁移到 v2

Pages 目录

// 之前 (v1)
import ProgressBar from 'next-nprogress-bar';

<ProgressBar
  height="4px"
  color="#fffd00"
  options={{ showSpinner: false }}
  shallowRouting
/>;

// 之后 (v2)
import { PagesProgressBar as ProgressBar } from 'next-nprogress-bar';

<ProgressBar
  height="4px"
  color="#fffd00"
  options={{ showSpinner: false }}
  shallowRouting
/>;

App 目录

// 之前 (v1)
import ProgressBar from 'next-nprogress-bar';

<ProgressBar
  height="4px"
  color="#fffd00"
  options={{ showSpinner: false }}
  appDirectory
  shallowRouting
/>;

// 之后 (v2)
import { AppProgressBar as ProgressBar } from 'next-nprogress-bar';

<ProgressBar
  height="4px"
  color="#fffd00"
  options={{ showSpinner: false }}
  shallowRouting
/>;