# @charmland/lipgloss 中文文档

规范地址：https://npmcn.com/package/%40charmland/lipgloss/

版本：2\.0\.0-beta\.3-0e280f3
npm 元数据更新时间：2026-06-14T12:57:53.840Z
中文译文更新时间：2026-11-09T10:59:29.093Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40charmland/lipgloss
原文对照：https://npmcn.com/package/%40charmland/lipgloss/?lang=original
项目主页：https://github.com/charmbracelet/lipgloss#readme
源码仓库：https://github.com/charmbracelet/lipgloss

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

- 包体积（解压后）：1.1 MB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2025-10-06T07:24:27.327Z
- 最新版本发布：2025-10-06T07:24:27.665Z
- 近 30 天下载量：15450（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

良好终端布局的样式定义 QQ

## 安装

```sh
npm install @charmland/lipgloss
```

也可以使用：`pnpm add @charmland/lipgloss`、`yarn add @charmland/lipgloss`、`bun add @charmland/lipgloss`

## README

# LipGloss.js (英语)

你所知道和所爱的唇膏 现在在JavaScript.

> \[尖叫声\] LipGloss.js是斯图尔实验.

## 安装

```bash
npm i @charmland/lipgloss
```

## 示例

```javascript
const { Table, TableData, Style, Color, List, Tree, Leaf, Bullet, RoundedEnumerator } = require("@charmland/lipgloss");

var s = new Style().foreground(Color("240")).render;
console.log(
  new Table()
    .wrap(false)
    .headers("Drink", "Description")
    .row("Bubble Tea", s("Milky"))
    .row("Milk Tea", s("Also milky"))
    .row("Actual milk", s("Milky as well"))
    .render(),
);

// TableData example - for more complex data management
const employeeData = new TableData(
  ["Employee ID", "Name", "Department"],
  ["001", "John Doe", "Engineering"],
  ["002", "Jane Smith", "Marketing"],
  ["003", "Mike Johnson", "Sales"]
);

console.log(
  new Table()
    .data(employeeData)
    .styleFunc((row, col) => {
      if (row === -1) {
        return new Style().foreground(Color("99")).bold(true);
      }
      return new Style().padding(0, 1);
    })
    .render()
);

// List example
const groceries = new List("Bananas", "Barley", "Cashews", "Milk")
  .enumerator(Bullet)
  .itemStyle(new Style().foreground(Color("255")));

console.log(groceries.render());

// Tree example with Leaf nodes
const makeupTree = new Tree()
  .root("⁜ Makeup")
  .child(
    "Glossier",
    "Fenty Beauty",
    new Tree().child(
      new Leaf("Gloss Bomb Universal Lip Luminizer"),
      new Leaf("Hot Cheeks Velour Blushlighter")
    ),
    new Leaf("Nyx"),
    new Leaf("Mac"),
    "Milk"
  )
  .enumerator(RoundedEnumerator)
  .enumeratorStyle(new Style().foreground(Color("63")).marginRight(1))
  .rootStyle(new Style().foreground(Color("35")))
  .itemStyle(new Style().foreground(Color("212")));

console.log(makeupTree.render());
```

## 表格数据

这个 `TableData` 类提供了比起使用单个行来管理表格数据的更结构化的方法. 需要时特别有用:

-   动态构建表格
-   在方案上访问各个单元
-   管理大数据集
-   将数据逻辑与演示文稿分开

### 基本用途

```javascript
const { Table, TableData, Style, Color } = require("@charmland/lipgloss");

// Create TableData with initial rows
const data = new TableData(
  ["Name", "Age", "City"],
  ["Alice", "25", "New York"],
  ["Bob", "30", "San Francisco"]
);

// Or build it incrementally
const data2 = new TableData()
  .append(["Product", "Price"])
  .append(["Laptop", "$999"])
  .append(["Mouse", "$25"]);

// Use with Table
const table = new Table()
  .data(data)
  .styleFunc((row, col) => {
    if (row === -1) return new Style().bold(true); // Header
    return new Style().padding(0, 1);
  })
  .render();
```

### 表格数据方法

-   `new TableData(...rows)` - 以可选初始行创建
-   `.append(row)` - 添加一行(字符串阵列)
-   `.rows(...rows)` - 一次添加多行
-   `.at(row, col)` - 在特定位置获得价值
-   `.rowCount()` - 获取行数
-   `.columnCount()` - 获取列数

见 `examples/table-data.js` 比较全面的例子.

## 环境变量

您可以使用环境变量控制调试输出 :

-   `LIPGLOSS_DEBUG=true` - 启用所有 lipgloss 调试输出
-   `DEBUG=lipgloss` - 启用 lipgloss 调试输出(标准调试模式)
-   `DEBUG=*` - 启用所有调试输出

示例

```bash
node your-script.js
```

## 兼容性

在JavaScript中Lipgloss是实验性的,很多已存在的功能还没有被移植到JavaScript上.

### 规模(100%)

| 函数 | 状态 |
| --- | --- |
| `Width` | ✅ |
| `Height` | ✅ |
| `Size` | ✅ |

### 颜色 (100%)

| 函数 | 状态 |
| --- | --- |
| `Color` | ✅ |
| `NoColor` | ✅ |
| `Complete` | ✅ |
| `LightDark` | ✅ |
| `RGBA` | ✅ |

### 边界(100%)

| 函数 | 状态 |
| --- | --- |
| `NormalBorder` | ✅ |
| `RoundedBorder` | ✅ |
| `BlockBorder` | ✅ |
| `OuterHalfBlockBorder` | ✅ |
| `InnerHalfBlockBorder` | ✅ |
| `ThickBorder` | ✅ |
| `DoubleBorder` | ✅ |
| `HiddenBorder` | ✅ |
| `MarkdownBorder` | ✅ |
| `ASCIIBorder` | ✅ |

### 样式(97.62%)

| 函数 | 状态 |
| --- | --- |
| `Foreground` | ✅ |
| `Background` | ✅ |
| `Width` | ✅ |
| `Height` | ✅ |
| `Align` | ✅ |
| `AlignHorizontal` | ✅ |
| `AlignVertical` | ✅ |
| `Padding` | ✅ |
| `PaddingLeft` | ✅ |
| `PaddingRight` | ✅ |
| `PaddingTop` | ✅ |
| `PaddingBottom` | ✅ |
| `ColorWhitespace` | ✅ |
| `Margin` | ✅ |
| `MarginLeft` | ✅ |
| `MarginRight` | ✅ |
| `MarginTop` | ✅ |
| `MarginBottom` | ✅ |
| `MarginBackground` | ✅ |
| `Border` | ✅ |
| `BorderStyle` | ✅ |
| `SetBorderRight` | ✅ |
| `SetBorderLeft` | ✅ |
| `SetBorderTop` | ✅ |
| `SetBorderBottom` | ✅ |
| `BorderForeground` | ✅ |
| `BorderTopForeground` | ✅ |
| `BorderRightForeground` | ✅ |
| `BorderBottomForeground` | ✅ |
| `BorderLeftForeground` | ✅ |
| `BorderBackground` | ✅ |
| `BorderTopBackground` | ✅ |
| `BorderRightBackground` | ✅ |
| `BorderBottomBackground` | ✅ |
| `BorderLeftBackground` | ✅ |
| `Inline` | ✅ |
| `MaxWidth` | ✅ |
| `MaxHeight` | ✅ |
| `TabWidth` | ✅ |
| `UnderlineSpaces` | ✅ |
| `Underline` | ✅ |
| `Reverse` | ✅ |
| `SetString` | ✅ |
| `Inherit` | ✅ |
| `Faint` | ✅ |
| `Italic` | ✅ |
| `Strikethrough` | ✅ |
| `StrikethroughSpaces` | ✅ |
| `Transform` | ⏳ |

### 表格(100%)

| 函数 | 状态 |
| --- | --- |
| `table.New` | ✅ |
| `table.Rows` | ✅ |
| `table.Headers` | ✅ |
| `table.Render` | ✅ |
| `table.ClearRows` | ✅ |
| `table.BorderTop` | ✅ |
| `table.BorderBottom` | ✅ |
| `table.BorderLeft` | ✅ |
| `table.BorderRight` | ✅ |
| `table.BorderHeader` | ✅ |
| `table.BorderColumn` | ✅ |
| `table.BorderRow` | ✅ |
| `table.Width` | ✅ |
| `table.Height` | ✅ |
| `table.Offset` | ✅ |
| `table.String` | ✅ |
| `table.StyleFunc` | ✅ |
| `table.Data` | ✅ |
| `table.Border` | ✅ |
| `table.BorderStyle` | ✅ |

### 名单(100%)

| 函数 | 状态 |
| --- | --- |
| `Hidden` | ✅ |
| `Hide` | ✅ |
| `Offset` | ✅ |
| `Value` | ✅ |
| `String` | ✅ |
| `Indenter` | ✅ |
| `ItemStyle` | ✅ |
| `ItemStyleFunc` | ✅ |
| `EnumeratorStyle` | ✅ |
| `EnumeratorStyleFunc` | ✅ |
| `Item` | ✅ |
| `Items` | ✅ |
| `Enumerator` | ✅ |

### 树 (95%)

| 函数 | 状态 |
| --- | --- |
| `tree.New` | ✅ |
| `tree.Root` | ✅ |
| `tree.Child` | ✅ |
| `tree.Hidden` | ✅ |
| `tree.Hide` | ✅ |
| `tree.SetHidden` | ✅ |
| `tree.Offset` | ✅ |
| `tree.Value` | ✅ |
| `tree.SetValue` | ✅ |
| `tree.String` | ✅ |
| `tree.Render` | ✅ |
| `tree.EnumeratorStyle` | ✅ |
| `tree.EnumeratorStyleFunc` | ✅ |
| `tree.ItemStyle` | ✅ |
| `tree.ItemStyleFunc` | ✅ |
| `tree.RootStyle` | ✅ |
| `tree.Enumerator` | ✅ |
| `tree.Indenter` | ✅ |
| `tree.DefaultEnumerator` | ✅ |
| `tree.RoundedEnumerator` | ✅ |
| `tree.DefaultIndenter` | ✅ |
| `NewLeaf` | ✅ |
| `Leaf.Value` | ✅ |
| `Leaf.SetValue` | ✅ |
| `Leaf.Hidden` | ✅ |
| `Leaf.SetHidden` | ✅ |
| `Leaf.String` | ✅ |
| 自定义数字 | ⏳ |
| 自定义缩进 | ⏳ |

### 加入(100%)

| 函数 | 状态 |
| --- | --- |
| `JoinHorizontal` | ✅ |
| `JoinVertical` | ✅ |

### 职位(100%)

| 函数 | 状态 |
| --- | --- |
| `Center` | ✅ |
| `Right` | ✅ |
| `Bottom` | ✅ |
| `Top` | ✅ |
| `Left` | ✅ |
| `Place` | ✅ |

### 查询( 50%)

| 函数 | 状态 |
| --- | --- |
| `BackgroundColor` | ⏳ |
| `HasDarkBackground` | ✅ |

### 对齐(0%)

| 函数 | 状态 |
| --- | --- |
| `EnableLegacyWindowsANSI` | ⏳ |

## 捐款

我们很乐意你出力 请看 [提供指南](https://github.com/charmbracelet/lipgloss/contribute) 更多信息.

### 测试

JavaScript装订包括一个全面的测试套件:

```bash
# From bindings directory
npm test                      # Run all tests
npm run test:simple           # Basic table functionality
npm run test:comprehensive    # Complete TableData tests
npm run examples              # Showcase functionality

# Or from examples directory
cd examples && npm test
```

测试位于 `examples/tests/` 并覆盖:

-   基本表格功能
-   表格数据操作
-   样式函数
-   Unicode 处理( 有已知限制)

见 [捐款](https://github.com/charmbracelet/lipgloss/contribute)。 。 。 .

## 反馈

我们很想听听你对这个项目的看法。 给我们留个字条吧!

-   [微博](https://twitter.com/charmcli)
-   [费迪弗斯](https://mastodon.social/@charmcli)
-   [解析器](https://charm.sh/chat)

## 许可证

[麻省理工学院](https://github.com/charmbracelet/lipgloss/raw/master/LICENSE)

* * *

部分 [魅力](https://charm.land/)。 。 。 .

[![The Charm logo](https://stuff.charm.sh/charm-banner-next.jpg)](https://charm.land/)

• 魅力爱开源

## 常见问题

### @charmland/lipgloss 是什么？

良好终端布局的样式定义 QQ

### 如何安装 @charmland/lipgloss？

在项目目录运行 npm install @charmland/lipgloss，或使用 pnpm add / yarn add / bun add。

### @charmland/lipgloss 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/charmland\_\_lipgloss 是否存在。

### @charmland/lipgloss 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @charmland/lipgloss 可以商用吗？

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

### @charmland/lipgloss 的下载量有多少？

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

### @charmland/lipgloss 还在维护吗？

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