# @davidwells/box-logger 中文文档

规范地址：https://npmcn.com/package/%40davidwells/box-logger/

版本：2\.0\.8
npm 元数据更新时间：2025-12-31T18:49:24.841Z
中文译文更新时间：2026-11-13T05:54:36.561Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40davidwells/box-logger
原文对照：https://npmcn.com/package/%40davidwells/box-logger/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：412 kB，88 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2025-04-04T22:15:07.641Z
- 最新版本发布：2025-12-31T18:49:24.664Z
- 近 30 天下载量：2167（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 10 个）

## 中文简介

用于在控制台中文本周围创建框的简单工具

## 安装

```sh
npm install @davidwells/box-logger
```

也可以使用：`pnpm add @davidwells/box-logger`、`yarn add @davidwells/box-logger`、`bun add @davidwells/box-logger`

## README

# 选项

用于在终端中创建格式化文本框、标题和行的简单工具.

## 安装

```bash
npm install @davidwells/box-logger
```

## 使用量

### 方框

以自定义的边框、 粘贴和样式创建文本周围的框 .

```javascript
const { makeBox, logBox } = require('@davidwells/box-logger')

// Simple usage with a string
console.log(makeBox('Hello World'))

// With options
console.log(makeBox({
  content: 'Hello World',
  textAlign: 'center',
  paddingLeft: 4,
  paddingRight: 4,
  borderColor: 'green',
  borderStyle: 'bold'
}))

// With title and content
console.log(makeBox({
  title: 'My Title',
  content: 'Box content here',
  borderStyle: 'rounded'
}))

// Hex colors are supported
console.log(makeBox({
  content: 'Custom colors',
  borderColor: '#4287f5',
  backgroundColor: '#1a1a2e'
}))

// Dynamic content - function receives { innerWidth } for sizing
console.log(makeBox({
  title: 'Dynamic Width',
  content: ({ innerWidth }) => generateContent({ width: innerWidth }),
  paddingLeft: 1,
  paddingRight: 0
}))

// Async content - use makeBoxAsync for async functions
const box = await makeBoxAsync({
  title: 'Async Content',
  content: async ({ innerWidth }) => await fetchData({ width: innerWidth })
})
console.log(box)

// Call logger directly
logBox('Log the box directly')
```

#### 框选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `content` | 字符串 QQ 区域函数 | \- 说吧 | 内容(或接收的函数) `{ innerWidth }`(中文(简体) ) |
| `title` | 字符串 QQ 区域 | \- 说吧 | 框上方的标题区域 |
| `fontStyle` | '正常' '粗体' | "正常的" | 字体样式 |
| `textAlign` | '左''''"中'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | 左边 | 文本对齐 |
| `color` | 字符串 | \- 说吧 | 文本颜色( 字符颜色或十六进制像“ #ff00” ) |
| `backgroundColor` | 字符串 | \- 说吧 | 背景颜色( 颜色或十六进制) |
| `paddingTop` | 编号 | 0 个 | 内容前的新行 |
| `paddingBottom` | 编号 | 0 个 | 内容后的新行 |
| `paddingLeft` | 编号 | 2个 | 左侧垫入空格 |
| `paddingRight` | 编号 | 2个 | 右补丁空格 |
| `borderColor` | 字符串 | \- 说吧 | 边框颜色( 字符颜色或十六进制) |
| `borderStyle` | 字符串 | "正常的" | 边框样式(见下文) |
| `borderTop` | 布尔 | 真实 | 显示上边框 |
| `borderBottom` | 布尔 | 真实 | 显示下边框 |
| `borderLeft` | 布尔 | 真实 | 显示左边框 |
| `borderRight` | 布尔 | 真实 | 显示右边框 |
| `borderText` | 字符串 | \- 说吧 | 文本嵌入上边框 |
| `borderTextColor` | 字符串 | \- 说吧 | 边框文本的颜色 |
| `borderTextAlign` | '左''''"中'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | 左边 | 边框文本对齐 |
| `width` | 数字 qq 字符串 | \- 说吧 | 固定宽度 |
| `minWidth` | 数字 qq 字符串 | \- 说吧 | 最小宽度( 全宽为“ 100% ” ) |
| `maxWidth` | 数字 qq 字符串 | 终端宽度 | 最大宽度 |
| `marginTop` | 编号 | 0 个 | 框前的新行 |
| `marginBottom` | 编号 | 0 个 | 框后新建行 |
| `marginLeft` | 编号 | 0 个 | 每行前的空格 |
| `wrapText` | 布尔 | 真实 | 将文字包入框中 |
| `type` | 字符串 | \- 说吧 | 框类型 : “ 成功 ” 、 “ 错误 ” 、 “ 警告 ” 、 “ info ” |
| `icon` | 字符串 | \- 说吧 | 自定义图标 |
| `header` | 布尔 | 虚假 | 页眉模式( 无左边框) |
| `edges` | 对象 | \- 说吧 | 自定义边框符号 |

#### 边框样式

-   `normal` - 标准框绘图字符(QQ)
-   `rounded` - 圆角(XQ)
-   `bold` - 重度边界(XQ)
-   `double` - 双线边界(XQ)
-   `dashed` - 扭曲的横向行线( )
-   `dotted` - 点点水平线( )
-   `thick` - 块字符 (Q)
-   `half-thick` - 半块边界( )
-   `ultra-thick` - 全部区块边界(
-   `ascii` - ASCII倒计时(-)
-   `dots` - 点数(-)
-   `circles` - 圆圈(0个)
-   `stars` - 闪光星星(QQ)
-   `triple` - 三行线( )
-   `transparent` - 隐形边界(空间)
-   `none` - 根本没有边界
-   `filled` - 与背景相通

#### 区域对象

标题和内容可以是字符串或节对象,以进行更多的控制:

```javascript
makeBox({
  title: {
    left: 'Title',
    right: 'v1.0.0',
    fontStyle: 'bold',
    color: 'cyan'
  },
  content: {
    left: 'Description',
    right: 'Status: OK',
    color: 'green'
  }
})
```

区域属性 : `left`, (中文(简体) ), `right`, (中文(简体) ), `center`, (中文(简体) ), `color`, (中文(简体) ), `fontStyle`, (中文(简体) ), `paddingLeft`, (中文(简体) ), `paddingRight`, (中文(简体) ), `paddingTop`, (中文(简体) ), `paddingBottom`, (中文(简体) ), `truncate`

### 堆叠的框

在共享边框上垂直堆放多个框 :

```javascript
const { makeStackedBoxes } = require('@davidwells/box-logger')

console.log(makeStackedBoxes([
  { title: 'Box 1', content: 'First box content' },
  { title: 'Box 2', content: 'Second box content' },
  { title: 'Box 3', content: 'Third box content' }
], {
  borderStyle: 'rounded',
  borderColor: 'cyan'
}))
```

### 水平框

并排渲染盒 :

```javascript
const { makeHorizontalBoxes } = require('@davidwells/box-logger')

console.log(makeHorizontalBoxes([
  { content: 'Left box' },
  { content: 'Middle box' },
  { content: 'Right box' }
], {
  gap: 2,
  mergeBoxes: true  // Merge adjacent borders
}))
```

选项 : `gap`, (中文(简体) ), `marginLeft`, (中文(简体) ), `connectRows`, (中文(简体) ), `justifyContent` ("弹性启动","弹性端","间距"), `wrap`, (中文(简体) ), `mergeBoxes`

### 页眉

创建标题( 无左边框的框) :

```javascript
const { makeHeader, logHeader } = require('@davidwells/box-logger')

// Simple usage
console.log(makeHeader('Hello World'))

// With options
console.log(makeHeader({
  content: 'Hello World',
  borderColor: 'blue'
}))

// Typed variants
logHeader.success('Operation completed')
logHeader.error('An error occurred')
logHeader.warning('Please be careful')
logHeader.info('Information')
```

标题使用与 Box 相同的选项( 这只是 `header: true` 盖下.

### 线条

以可选文本创建水平行 :

```javascript
const { makeLine, logLine } = require('@davidwells/box-logger')

// Simple line
console.log(makeLine())

// Line with centered text
console.log(makeLine('Section Title'))

// Line with options
console.log(makeLine({
  text: 'Styled text',
  fontStyle: 'bold',
  borderColor: 'green'
}))

// Left and right text
console.log(makeLine({
  left: 'Section',
  right: 'v1.2.3',
  borderColor: 'cyan'
}))

// All three positions
console.log(makeLine({
  left: 'Left',
  center: 'Center',
  right: 'Right'
}))
```

#### 行选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `text` | 字符串 | \- 说吧 | 要显示的文本( 用文本对齐使用) |
| `left` | 字符串 | \- 说吧 | 左对齐文本 |
| `right` | 字符串 | \- 说吧 | 右对齐文本 |
| `center` | 字符串 | \- 说吧 | 中央对齐文本 |
| `color` | 字符串 | \- 说吧 | 文本颜色 |
| `backgroundColor` | 字符串 | \- 说吧 | 文本的背景颜色 |
| `lineBackgroundColor` | 字符串 | \- 说吧 | 整个行的背景 |
| `fontStyle` | '正常' '粗体' | "正常的" | 字体样式 |
| `borderColor` | 字符串 | \- 说吧 | 线条颜色 |
| `borderStyle` | 字符串 | "正常的" | 线条样式 |
| `textAlign` | '左''''"中'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | 中间 | 文本对齐 |
| `paddingLeft` | 编号 | 页:1 | 左侧挂起 |
| `paddingRight` | 编号 | 页:1 | 右侧粘贴 |
| `minWidth` | 数字 qq 字符串 | \- 说吧 | 最小宽度 |
| `maxWidth` | 数字 qq 字符串 | 终端宽度 | 最大宽度 |
| `lines` | 编号 | \- 说吧 | 生成多行空行 |

### 已打入的备选案文

所有日志功能都有有自动图标和颜色的输入变体:

```javascript
const { logBox, logHeader, logLine } = require('@davidwells/box-logger')

// Box variants
logBox.success('Operation completed successfully')
logBox.error('An error occurred')
logBox.warning('Please be careful')
logBox.info('Here is some information')

// Header variants
logHeader.success('Success!')
logHeader.error('Error!')

// Line variants
logLine.success('Success line')
logLine.error('Error line')
```

### 处理错误

向logBox传递一个错误对象用于格式化错误显示 :

```javascript
try {
  throw new Error('Something went wrong')
} catch (err) {
  logBox.error(err)  // Shows error name, message, and cleaned stack trace
}
```

## 实例

### 基本方框

```
┌─────────────┐
│  Hello World  │
└─────────────┘
```

### 有标题的圆形框

```
╭──────────────────────╮
│  My Title            │
├──────────────────────┤
│  Content goes here   │
╰──────────────────────╯
```

### 粗体框

```
┏━━━━━━━━━━━━━━━━━━━━━━┓
┃  Hello World         ┃
┗━━━━━━━━━━━━━━━━━━━━━━┛
```

### 标题( 无左边框)

```
──────────────────────────────┐
  Hello World                 │
──────────────────────────────┘
```

### 带文字的行

```
────────── Section Title ──────────
```

### 以左右为行

```
──── Section ──────────── v1.2.3 ────
```

## 公用事业

### 终端大小

获取当前终端尺寸 :

```javascript
const { terminalSize } = require('@davidwells/box-logger')

const { columns, rows } = terminalSize()
console.log(`Terminal is ${columns}x${rows}`)
```

### 获取内网

计算框配置的内在内容宽度 :

```javascript
const { getInnerWidth } = require('@davidwells/box-logger')

const innerWidth = getInnerWidth({
  paddingLeft: 1,
  paddingRight: 0,
  marginLeft: 5
})
// Use innerWidth to pre-size content before calling makeBox
```

## 许可证

麻省理工学院

## 其他表达式

-   [https://github.com/tecfu/tty-table 页面存档备份,存于互联网档案馆](https://github.com/tecfu/tty-table)
-   [https://www.npmjs.com/package/boxen (英语)](https://www.npmjs.com/package/boxen)

## 常见问题

### @davidwells/box-logger 是什么？

用于在控制台中文本周围创建框的简单工具

### 如何安装 @davidwells/box-logger？

在项目目录运行 npm install @davidwells/box-logger，或使用 pnpm add / yarn add / bun add。

### @davidwells/box-logger 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @davidwells/box-logger 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @davidwells/box-logger 可以商用吗？

@davidwells/box-logger 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @davidwells/box-logger 的下载量有多少？

根据 npm 官方下载统计，@davidwells/box-logger 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,167 次，日均约 72 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @davidwells/box-logger 还在维护吗？

最新版本 2\.0\.8 发布于 2026/01/01（10 个月前）；至今共发布 31 个版本，其中过去 12 个月发布了 10 个；首次发布于 2025/04/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。