js-log-lib
介绍
浏览器和 node 共用的 log 样式,行为控制工具,可以自定义输出样式,其核心原理是采用了 ANSI 指令以及 css 属性,更多用法可以参照 ANSI 的详细介绍
调试说明
- pnpm build(构建)
- pnpm dev(node 中调试源码)
- pnpm dev:umd(浏览器中调试)
- 在 esm,cjs,window 环境下导入该工具库
- 详情见 dev 文件夹
参与贡献
- Fork 本仓库
- Star 仓库
- 提交代码
- 新建 Pull Request
使用说明
安装
npm install js-log-lib
或
yarn add js-log-lib
或
pnpm install js-log-lib
引入
ESM
import { JSLog } from "js-log-lib";
CJS
const { JSLog } = require("js-log-lib");
浏览器中
<script src="./node_modules/js-log-lib/dist/umd/index.js"></script>
<script>
console.log(JSLog);
</script>
开始使用
在浏览器环境下和 Node 环境下稍有区别
建议在使用前仔细阅读 types.ts 和 static.ts 文件,这样有助于理解和使用
static.ts https://gitee.com/DieHunter/js-log-lib/blob/master/src/static.ts 文件下存放静态变量,大部分指令都在这
types.ts https://gitee.com/DieHunter/js-log-lib/blob/master/src/types.ts 是 JSLog 的核心类型,一些函数的配置项可以在这找到
创建 JSLog 实例
const logger = new JSLog();
全局配置项
参照 types.ts 中的 IGlobalOpts 类型
全局配置项可以传入以下属性
type IGlobalOpts = Partial<{
text: string;
reset: boolean;
type: string;
split: boolean;
color: IColor[] | IColor;
textStyle: ITextStyle[] | ITextStyle;
cursor: ICursor;
move: IMoveParams;
scroll: number;
style: Partial<CSSStyleDeclaration>;
}>;
默认配置
在 index 中,defaultOpts 是默认配置,当开发者没有设置 option 时,会使用这里的样式和设置
const defaultOpts: IGlobalOpts = {
reset: true,
type: "log",
split: true,
};
基本使用
1. 打印字符
const logger = new JSLog();
logger.log({ text: "阿宇的编程之旅" });
2. 为当前实例添加全局配置项
const logger = new JSLog({ type: "error", color: "red" });
logger.log({ text: "我是个错误提示" });
logger.mixins({ type: "info", color: "green" });
logger.log({ text: "我是个成功提示" });
3. 清空所有样式及操作行为
const logger = new JSLog({ type: "error", color: "red" });
logger.log({ text: "阿宇" });
logger.clear();
logger.log({ text: "阿宇" });
4. 校验传入的参数是否允许
const logger = new JSLog();
logger.checkOptions({ style: {} });
5. 样式调整
Node 环境中
const logger = new JSLog();
logger.log({
text: "hello world",
color: "cyan",
textStyle: "bold",
});
浏览器环境中
logger.log({
text: "hello world",
style: { color: "lightblue", background: "#333", margin: "10px" },
});
6. 光标控制指令
const logger = new JSLog();
logger.log({ text: "i m here" });
logger.log({ text: "i m here" });
logger.log({ text: "i m here", cursor: "eraseDisplay" });
7. 光标位置偏移
const logger = new JSLog();
logger.log(
{
move: {
direct: "right",
position: 5,
},
text: "编程之旅",
},
{
move: {
direct: "left",
position: 14,
},
text: "阿宇的",
}
);
8. 滚动条控制
import { TimerManager } from "utils-lib-js";
const logger = new JSLog();
const timerManager = new TimerManager();
let scroll = 0;
const timer = timerManager.add(() => {
if (scroll <= -5) return timerManager.delete(timer);
scroll--;
logger.log({ text: scroll.toString(), scroll });
}, 500);
其他用法
1. log 的链式调用
const logger = new JSLog();
logger.log({ text: "hello" }).log({ text: "world" });
2. 在同一行打印多种类型 log
const logger = new JSLog({ split: false });
logger.log(
{ text: "阿宇", color: "red" },
{ text: "的编程", color: "brightCyan" },
{ text: "之旅", color: "bgBrightMagenta" }
);
3. 属性的指令集
logger.log({
text: "hello world",
color: ["red", "bgBrightGreen"],
textStyle: ["bold", "italic", "strikethrough"],
});
4.JSLog 中针对 ANSI 的一些快捷操作
如果你了解 ANSI 编码的指令,那么下面的函数可以让你锦上添花
不了解也没关系,在 static 文件下我已经将常用的 ANSI 列出,以供参考使用
- ANSI 编码指令拼接
const logger = new JSLog();
const { getANSI } = logger;
console.log(getANSI(`35`), "hello world");
logger.log({
text: getANSI(`34`) + "hello world",
});
- 颜色设置
const logger = new JSLog();
const { getANSI, getColor } = logger;
logger.log({
text: getANSI(getColor("bgBlue")) + "hello world",
});
- 字体样式
const logger = new JSLog();
const { getANSI, getTextStyle } = logger;
logger.log({
text: getANSI(getTextStyle("bold")) + "hello world",
});
- 光标操作
const logger = new JSLog();
const { getANSI, getCursor } = logger;
logger.log(
{ text: "----------------------------" },
{
text: getANSI(getCursor("toLineStart"), false) + "hello world",
}
);
- 光标移动
const logger = new JSLog();
const { getANSI, moveTo } = logger;
logger.log(
{ text: "hello" },
{
text: getANSI(moveTo({ direct: "right", position: 5 }), false) + "world",
}
);
- 滚动条移动
const logger = new JSLog();
const { getANSI, scrollTo } = logger;
logger.log({
text: getANSI(scrollTo(-2), false) + "hello world",
});
- 重置样式
const logger = new JSLog();
const { getANSI, getColor, reset } = logger;
console.log(
getANSI(getColor("bgBrightGreen")),
"i m bgBrightGreen",
reset(),
"i m reset"
);
5. ANSI 颜色指令的进阶用法
上面说到了前后景色的设置,使用 color 属性可以对 log 的字符设置对应的颜色属性,然而由于颜色的指令数有限,有许多其他颜色无法表示,所以 ANSI 提供了两种设置颜色参数的方式
- 第一种是 256 种色调色板的形式,又叫做兼容模式,设置该模式需要将 ANSI 的第二个参数 mode 设置为 5 :
const ANSI = `\x1B[38;5;<color>m`;
它支持设置数字 0-255:
0-15 是标准颜色,也就是之前用到的颜色变量
16-231 有 216 种颜色,这些颜色按照六阶的 RGB 立方体规则排列,提供了各种颜色的组合
232-255 是灰度颜色,这些颜色表示不同灰度级别,从黑到白。232 表示最暗的灰色,255 表示最亮的灰色。
通过下面的代码我们可以打印出全部 256 种色阶:
const logger = new JSLog();
const { getANSI, getRGB, reset } = logger;
let color = ``;
for (let i = 0; i < 255; i++) {
color += `${getANSI(
getRGB({ color: i, mode: "compatibility", type: "background" })
)} `;
}
console.log(color, reset());
- 另一种设置颜色的方式是使用 True Color(真彩色)模式。在 True Color 模式下,可以通过指定 RGB(红绿蓝)值来准确设置颜色,而不仅仅依赖于预定义的颜色索引,就像是 css 中的 rgb 方法。该模式需要将 ANSI 的第二个参数 mode 设置为 2:
const ANSI = `\x1B[38;2;<r>;<g>;<b>m`;
它支持设置数字 256^3 种(16777216 种颜色),在真彩模式下可以通过指定每个颜色通道的具体强度值来准确定义颜色
const logger = new JSLog();
logger.log(
{ text: "hello", color: { red: 255 } },
{
text: "阿宇的",
color: { green: 255 },
},
{ text: "编程之旅", color: { blue: 255, type: "background" } }
);
6. 光标坐标轴移动
通过配置 move 参数可以实现坐标位移的功能
import { TimerManager } from "utils-lib-js";
const logger = new JSLog();
const timer = new TimerManager();
const str = "hello world";
const position = {
row: 0,
col: 0,
};
logger.log({ cursor: "eraseDisplay" });
timer.add(() => {
const _str = str[position.col];
if (!_str) timer.clear();
position.col++;
position.row++;
move(_str);
}, 100);
const move = (str) =>
logger.log({
text: str,
move: {
direct: "custom",
position,
},
});