consola · Packages · UnJS 中文

优雅的控制台封装

Consola 有何优势？

👌 易于使用
💅 华丽的输出，并在极简环境下提供回退
🔌 可插拔的报告器
💻 一致的命令行界面 (CLI) 体验
🏷 标签支持
🚏 将 console 和 stdout/stderr 重定向到 consola，并轻松恢复重定向。
🌐 浏览器支持
⏯ 暂停/恢复支持
👻 模拟支持
👮‍♂️ 通过限制日志防止垃圾信息
❯ 由 clack 提供支持的交互式提示

安装

使用 npm

npm i consola

使用 yarn

yarn add consola

使用 pnpm

pnpm i consola

快速入门

// ESM
import { consola, createConsola } from "consola";

// CommonJS
const { consola, createConsola } = require("consola");

consola.info("Using consola 3.0.0");
consola.start("Building project...");
consola.warn("A new version of consola is available: 3.0.1");
consola.success("Project built!");
consola.error(new Error("This is an example error. Everything is fine!"));
consola.box("I am a simple box");
await consola.prompt("Deploy to the production?", {
  type: "confirm",
});

将在终端中显示

consola-screenshot

您可以使用更小的核心构建，无需花哨的报告器，以节省 80% 的包大小

import { consola, createConsola } from "consola/basic";
import { consola, createConsola } from "consola/browser";
import { createConsola } from "consola/core";

Consola 方法

`<type>(logObject)` `<type>(args...)`

记录到所有报告器。

示例：consola.info('Message')

`await prompt(message, { type })`

显示输入提示。类型可以是 text、confirm、select 或 multiselect。

请参阅 examples/prompt.ts 获取使用示例。

`addReporter(reporter)`

别名：add

注册自定义报告器实例。

`removeReporter(reporter?)`

别名：remove, clear

移除已注册的报告器。

如果没有传递任何参数，则所有报告器都将被移除。

`setReporters(reporter|reporter[])`

替换所有报告器。

`create(options)`

创建一个新的 Consola 实例，并继承所有父选项作为默认值。

`withDefaults(defaults)`

使用提供的默认值创建一个新的 Consola 实例

`withTag(tag)`

别名：withScope

创建一个带该标签的新的 Consola 实例。

`wrapConsole()` `restoreConsole()`

全局重定向所有 console.log 等调用到 consola 处理器。

`wrapStd()` `restoreStd()`

全局重定向所有 stdout/stderr 输出到 consola。

`wrapAll()` `restoreAll()`

同时封装标准输出和控制台。

控制台在底层使用标准输出，因此调用 wrapStd 也会重定向控制台。此函数的好处是，像 console.info 这样的内容将被正确重定向到相应的类型。

`pauseLogs()` `resumeLogs()`

别名：pause/resume

全局暂停和恢复日志。

Consola 在暂停时会将所有日志排队，并在恢复时将其发送给报告器。

`mockTypes`

别名：mock

模拟所有类型。对于测试很有用。

传递给 mockTypes 的第一个参数应该是一个回调函数，接受 (typeName, type) 并返回模拟值

consola.mockTypes((typeName, type) => jest.fn());

请注意，以上示例中，所有内容都是独立地为每种类型进行模拟的。如果您需要一个模拟函数，请在外部创建它

const fn = jest.fn();
consola.mockTypes(() => fn);

如果回调函数返回一个虚假值，则该类型将不被模拟。

例如，如果您只需要模拟 consola.fatal

consola.mockTypes((typeName) => typeName === "fatal" && jest.fn());

注意：任何继承了模拟实例的 consola 实例，将再次应用提供的回调。这样，对于 withTag 作用域的日志记录器，模拟无需额外努力即可工作。

自定义报告器

Consola 默认提供了 3 种内置报告器。默认情况下是一个华丽的彩色报告器，如果检测到在测试或 CI 环境中运行（使用 unjs/std-env 检测），则回退到一个基本报告器，以及一个基本的浏览器报告器。

您可以创建一个新的报告器对象，它实现 { log(logObject): () => { } } 接口。

示例：简单的 JSON 报告器

import { createConsola } from "consola";

const consola = createConsola({
  reporters: [
    {
      log: (logObj) => {
        console.log(JSON.stringify(logObj));
      },
    },
  ],
});

// Prints {"date":"2023-04-18T12:43:38.693Z","args":["foo bar"],"type":"log","level":2,"tag":""}
consola.log("foo bar");

日志级别

Consola 只显示配置的日志级别或低于该级别的日志。（默认为 3）

可用日志级别

0: 致命和错误
1: 警告
2: 普通日志
3: 信息日志，成功，失败，就绪，开始，...
4: 调试日志
5: 跟踪日志
-999: 静默
+999: 详细日志

您可以通过以下方式设置日志级别：

向 createConsola 传递 level 选项
在实例上设置 consola.level
使用 CONSOLA_LEVEL 环境变量（浏览器和核心构建不支持）。

日志类型

日志类型通过 consola.[type](https://raw.githubusercontent.com/unjs/consola/main/...) 暴露，每种类型都是样式和日志级别的预设。

所有可用内置类型的列表在此处可用。

创建新实例

Consola 有一个全局实例，建议在任何地方使用。如果需要更多控制，请创建一个新实例。

import { createConsola } from "consola";

const logger = createConsola({
  // level: 4,
  // fancy: true | false
  // formatOptions: {
  //     columns: 80,
  //     colors: false,
  //     compact: false,
  //     date: false,
  // },
});

集成

与 jest 或 vitest

describe("your-consola-mock-test", () => {
  beforeAll(() => {
    // Redirect std and console to consola too
    // Calling this once is sufficient
    consola.wrapAll();
  });

  beforeEach(() => {
    // Re-mock consola before each test call to remove
    // calls from before
    consola.mockTypes(() => jest.fn());
  });

  test("your test", async () => {
    // Some code here

    // Let's retrieve all messages of `consola.log`
    // Get the mock and map all calls to their first argument
    const consolaMessages = consola.log.mock.calls.map((c) => c[0]);
    expect(consolaMessages).toContain("your message");
  });
});

与 jsdom

{
  virtualConsole: new jsdom.VirtualConsole().sendTo(consola);
}

控制台实用工具

// ESM
import {
  stripAnsi,
  centerAlign,
  rightAlign,
  leftAlign,
  align,
  box,
  colors,
  getColor,
  colorize,
} from "consola/utils";

// CommonJS
const { stripAnsi } = require("consola/utils");

许可

MIT