访问官网
Github
文档
论文Next NProgress 进度条
在 Next.js 上集成 NProgress，兼容 /app 和 /pages 文件夹
目录
开始使用
安装
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
/>;
问题
请为错误、缺失的文档或意外行为提交问题。 不要犹豫，为任何问题提交 PR。
许可证
MIT
