umi-plugin-nprogress

安装此插件，自动监听浏览器请求执行情况，以展示 NProgress 进度条。

用法

在 UmiJS 项目中使用

直接安装 umi-plugin-nprogress 到你的 UmiJS 项目即可，默认开启：

yarn add umi-plugin-nprogress --dev
# 或者
npm add umi-plugin-nprogress --save-dev
# 或者
pnpm add umi-plugin-nprogress --save-dev

UmiJS v2 请使用 v1.1.4 及以下版本

动态配置或是获取 NProgress 配置

通常情况下，你可以直接在插件中提供 NProgress 的配置，如果你需要在运行时修改或者获取 NProgress 配置，可以从 'umi' 中导入 NProgress ：

import { NProgress } from 'umi';

NProgress.config({
  // 你想要修改的配置
});

// NProgress 当前的配置
console.log(NProgress.settings);

如果你的项目使用了 React ，还可以通过 React Hook 来修改或是获取 NProgress 配置：

import { useNProgressConfig } from 'umi';

export function MyComponent() {
  // NProgress 当前的配置
  const config = useNProgressConfig();

  useNProgressConfig({
    // 你想要修改的配置
  });

  return null;
}

获取 NProgress 实例

如果需要手动控制 NProgress ，可以从 'umi' 中导入 NProgress ：

import { NProgress } from 'umi';

NProgress.start();
NProgress.done();

在其他项目中使用

umi-plugin-nprogress 的核心运行时能力由 umi-plugin-nprogress-runtime 提供，而 umi-plugin-nprogress-runtime 无需依赖 UmiJS 即可运行，所以可以在非 UmiJS 项目中使用。

首先安装 umi-plugin-nprogress-runtime 到你的项目：

yarn add umi-plugin-nprogress-runtime
# 或者
npm add umi-plugin-nprogress-runtime
# 或者
pnpm add umi-plugin-nprogress-runtime

然后在项目的入口文件添加如下代码：

import { NProgress, setupNProgressPluginRuntime } from 'umi-plugin-nprogress-runtime';
// 引入 NProgress 样式，如果你确定不需要（例如自己定义了 NProgress 的渲染模板），则可以删除此行
import 'nprogress/nprogress.css';

// 如果默认配置即可满足需求，则无需调用此函数
NProgress.configure({
  // 添加你的 NProgress 配置
});

// 如果默认配置即可满足需求，直接 setupNProgressPluginRuntime() 即可
setupNProgressPluginRuntime({
  // 添加你的 runtime 配置
});

前面示例中，从 'umi' 导出的 NProgress 、 useNProgressConfig 等 API ，可以直接从 'umi-plugin-nprogress-runtime' 获取：

- import { NProgress, useNProgressConfig } from 'umi';
+ import { NProgress, useNProgressConfig } from 'umi-plugin-nprogress-runtime';

配置

ie11

是否需要兼容到 IE 11 。

• 类型：boolean | 'cjs' | 'esm' | undefined
• 默认值：false

说明

未启用此项时，默认兼容到 chrome 67, edge 79, firefox 64, safari 12.1 ，启用此配置后将兼容到 chrome 50, edge 12, ie 11, firefox 50, safari 10 。

配置为 'cjs' 或是 'esm' 可指定走 CommonJS 还是 ESModule 产物，配置为 true 相当于 'esm' 。

如需兼容更低版本，请直接配置 umi-plugin-nprogress-runtime 依赖走 babel 编译。

配置示例

// .umirc.ts
import { defineConfig } from 'umi';

export default defineConfig({
  nprogress: {
    ie11: true,
  },
});

runtime

运行时的插件配置。

• 类型：UmiPluginNProgressRuntimeConfig | undefined
• 默认值：undefined

interface UmiPluginNProgressRuntimeConfig {
  /**
   * 启用对 XMLHttpRequest 的监听。
   *
   * @default
   * ```ts
   * true
   * ```
   */
  readonly XMLHttpRequest?: boolean;
  /**
   * 启用对 fetch 的监听。
   *
   * @default
   * ```ts
   * true
   * ```
   */
  readonly fetch?: boolean;
}

配置示例

// .umirc.ts
import { defineConfig } from 'umi';

export default defineConfig({
  nprogress: {
    runtime: {
      // 关闭对 XMLHttpRequest 的监听
      XMLHttpRequest: false,
    },
  },
});

ui

配置 nprogress 进度条的动效曲线、挂载容器、增速、渲染模板等样式。

• 类型：NProgressConfigureOptions | undefined
• 默认值：undefined

interface NProgressConfigureOptions {
  /**
   * 使用的 CSS 动效曲线，默认为 'ease' 。
   *
   * The CSS easing animation to use. Default is 'ease'.
   */
  readonly easing?: string;

  /**
   * 进度条最小的百分比，默认为 0.08 。
   *
   * The minimum progress percentage. Default is 0.08.
   */
  readonly minimum?: number;

  /**
   * 配置进度条 DOM 容器，需要是一个 CSS 选择器，默认为 'body' 。
   *
   * CSS selector to change the parent DOM element of the progress. Default is 'body'.
   */
  readonly parent?: string;

  /**
   * 是否在进度条出现时展示旋转的圆圈图标，默认展示。
   *
   * Whether to show the spinner. Default to true.
   */
  readonly showSpinner?: boolean;

  /**
   * 动画的速度（毫秒计），默认为 200 。
   *
   * The animation speed in milliseconds. Default is 200.
   */
  readonly speed?: number;

  /**
   * 进度条的 HTML 渲染模板，其中至少包含一个 HTML 属性 role 为 'bar' 的元素。
   *
   * The HTML markup inserted for the progress indicator. To keep the progress bar working, keep an element with role='bar' in there.
   */
  readonly template?: string;

  /**
   * 在展示进度条时，是否定时随机前进一点，默认启用。
   *
   * Whether to enable trickling the progress. Default is true.
   */
  readonly trickle?: boolean;

  /**
   * 进度条定时随机前进的间隔，默认为 800 。
   *
   * How often to trickle, in milliseconds. Default is 800.
   */
  readonly trickleSpeed?: number;
}

配置示例

// .umirc.ts
import { defineConfig } from 'umi';

export default defineConfig({
  nprogress: {
    ui: {
      speed: 500,
    },
  },
});

完整配置示例

// .umirc.ts
import { defineConfig } from 'umi';

export default defineConfig({
  nprogress: {
    ie11: false,
    runtime: {
      fetch: false,
    },
    ui: {
      speed: 600,
    },
  },
});