pangu-vis-cli

盘古可视化平台的图表包脚手架与开发辅助工具

简介

pangu-vis-cli 是一个专为盘古可视化平台设计的图表包脚手架与开发辅助工具，覆盖图表包创建、本地开发调试与打包构建。通过简洁的命令，开发者可以快速创建标准化的图表项目，进行本地开发调试，并一键打包为 tar.gz 发布产物。1.1.0 起本工具聚焦脚手架与开发辅助，tar.gz 发布产物面向盘古可视化平台使用。

核心价值：

• 🚀 快速初始化 - 一键创建标准化图表项目模板
• 🔧 开发友好 - 一键启动图表包本地开发调试
• 📦 智能打包 - 版本同步、自动压缩、一键生成 tar.gz 发布产物
• ⚙️ 灵活配置 - 自动化行为可自定义

特性

• ✅ 支持 9 种图表类型（折线图、柱状图、饼图、表格、地图、文本、指标、交互、其他）
• ✅ 可选 TypeScript 支持
• ✅ 交互式命令行提示
• ✅ 自动版本同步（public/base.json ↔ package.json）
• ✅ 单图表一键打包为 tar.gz
• ✅ 自动更新检测
• ✅ 跨平台支持（macOS / Windows / Linux）

安装

macOS

# 全局安装
sudo npm install -g pangu-vis-cli

# 或使用 pnpm
sudo pnpm install -g pangu-vis-cli

Windows

# 全局安装（管理员权限）
npm install -g pangu-vis-cli

# 或使用 pnpm
pnpm install -g pangu-vis-cli

Linux

# 全局安装
sudo npm install -g pangu-vis-cli

# 或使用 pnpm
sudo pnpm install -g pangu-vis-cli

验证安装

# 查看版本
pv -v
# 或
pvis -v

快速开始

创建第一个图表项目：

# 创建图表包
pv create my-line-chart

# 进入项目目录（根据提示）
cd packages/components/my-line-chart

# 启动开发环境
pnpm dev

完整工作流：

# 1. 创建图表包
pv create my-chart

# 2. 进入图表包目录
cd packages/components/my-chart

# 3. 启动开发环境
pnpm dev

# 4. 打包构建（在图表包目录）
pv build

命令详解

pv create - 创建图表包

创建新的图表项目模板。

别名：pv c

用法：

pv create <project-name>
pv c <project-name>

交互式选项：

1. 图表类型选择：

   • line - 折线图
   • bar - 柱状图
   • pie - 饼图
   • form - 表格
   • map - 地图
   • text - 文本
   • indicator - 指标
   • interaction - 交互
   • other - 其他（默认选中，推荐）

2. TypeScript 支持：

   • yes - 启用 TypeScript
   • no - 使用 JavaScript（默认）

3. 图表命名规则：

   • 必须以小写字母开头
   • 仅允许小写字母、数字、下划线
   • 长度 1-100 字符
   • 推荐添加自定义前缀防止冲突

示例：

# 创建折线图（交互式）
pv create custom_line_chart

# 创建柱状图并启用 TypeScript
pv create custom_bar_chart
# 在交互提示中选择 "bar" 类型，启用 TS

创建目录结构：

图表创建位置取决于当前工作目录：

• 当前目录或其上级目录（最多向上 10 层）具备图表库特征（package.json 包名含 pangu + packages/components + packages/tailored）：

  • 在特征目录下归位：packages/components/<project-name>/
  • 运行路径包含 "tailored" 时：packages/tailored/<project-name>/

• 其他目录：

  • 当前目录下创建：./<project-name>/

自动执行：

• 复制模板文件
• 配置图表类型和名称
• 安装项目依赖（pnpm install）

pv build - 单个图表打包

打包单个图表组件为 tar.gz 压缩包。

别名：pv b

用法：

pv build                  # 打包当前目录图表
pv build <path>           # 打包指定路径图表

参数：

• <path> - 图表包路径（相对或绝对）

示例：

# 在图表包目录下执行
cd packages/components/my-chart
pv build

# 指定路径打包
pv build packages/components/my-chart

打包流程：

1. 版本同步（public/base.json ↔ package.json）
2. 执行 pnpm build
3. 生成产物目录：<chart-name>_v<version>/
4. 可选删除 es/ 目录（根据配置）
5. 过滤无用文件（.git, .vscode, .DS_Store, .idea）
6. 打包为 tar.gz：<chart-name>_v<version>.tar.gz
7. 可选删除打包目录（根据配置 autoRemove）

产物文件：

my-chart_v1.0.0.tar.gz

pv dev - 启动开发环境

启动图表包的本地开发服务器。

别名：pv d

用法：

pv dev              # 启动当前目录开发环境

需先 cd 到图表包目录再执行。

示例：

# 在图表包目录下执行
cd packages/components/my-chart
pv dev

自动检测：

• 查找 package.json 中的 dev 脚本
• 执行 <探测到的包管理器> run dev
• 实时预览图表开发效果

pv config - 配置管理

配置 CLI 工具的自动化行为。

别名：pv set

用法：

pv config

交互式配置项：

| 配置项 | 说明 | 默认值 | | -------------- | -------------------------- | ------------ | | autoRemove | 打包后是否自动删除打包目录 | yes (true) | | autoRemoveEs | 打包后是否移除 es 目录 | yes (true) |

示例：

pv config
# 按提示选择配置项

配置文件位置：

~/.pangu-vis-store/.cli_store

配置文件格式：

{
	"autoRemove": true,
	"autoRemoveEs": true,
	"lastUpdateCheck": 1788480000000,
	"privateRegistry": "http://192.168.12.88:10000"
}

pv update - CLI 更新

检查并更新 CLI 工具至最新版本。

别名：pv up

用法：

pv update

更新流程：

1. 检查 npm 源最新版本
2. 安装前确认提示「是否安装 <版本>？」（默认 yes，可跳过；跳过后提示稍后可再运行 pvis update）
3. 优先用探测到的 pnpm（不可用时回退 npm）执行 install -g pangu-vis-cli@latest

示例：

# 检查更新
pv update

# 已是最新版本提示
当前已是最新版本 1.1.0

# 有新版本时提示
发现新版本 1.2.0，当前版本 1.1.0
是否安装 1.2.0？

自动检查：

• CLI 每次执行命令时自动检查更新（24小时内只检查一次）
• 检测到新版本时提示用户更新

配置

配置文件位置

CLI 配置信息存储在用户主目录：

~/.pangu-vis-store/.cli_store

可通过环境变量 PANGU_CONFIG_DIR 覆盖配置目录位置。

配置项说明

| 配置项 | 类型 | 说明 | 默认值 | | ----------------- | ------- | ------------------------------------------------------------------------------ | ---------- | | autoRemove | boolean | 打包后是否自动删除打包目录 | true | | autoRemoveEs | boolean | 打包后是否自动删除 es 目录 | true | | lastUpdateCheck | number | 更新检查节流时间戳（可选） | 无 | | privateRegistry | string | 私有 npm 源（可选，优先级：PANGU_REGISTRY 环境变量 > 配置文件 > 内网默认源） | 内网默认源 |

修改配置

方法 1：交互式配置

pv config

方法 2：手动编辑 编辑 ~/.pangu-vis-store/.cli_store 文件。

使用示例

示例：创建并打包折线图

完整流程演示：

# 1. 创建折线图项目
pv create custom_line_chart
# 选择：折线图、不使用 TypeScript

# 2. 进入项目目录（根据提示）
cd packages/components/custom_line_chart

# 3. 启动开发环境
pnpm dev
# 在浏览器中开发调试图表

# 4. 开发完成后，打包图表
pv build
# 生成：custom_line_chart_v1.0.0.tar.gz

命令速查表

| 命令 | 别名 | 说明 | | ----------- | -------- | ------------ | | pv create | pv c | 创建图表包 | | pv build | pv b | 单个图表打包 | | pv dev | pv d | 启动开发环境 | | pv config | pv set | 配置管理 | | pv update | pv up | CLI 更新 |

常见问题

1. 安装失败或权限不足

macOS/Linux：

sudo npm install -g pangu-vis-cli

Windows： 以管理员身份运行终端，再执行安装命令。

2. 图表包名称重复

• 使用自定义前缀避免冲突
• 遵循命名规则：小写字母开头，仅允许小写字母、数字、下划线

3. 打包产物找不到

• 检查配置 autoRemove 是否为 yes
• 打包产物默认在图表包目录下

4. 版本号不同步

• CLI 自动同步 public/base.json 和 package.json 版本
• 手动修改版本时需同时更新两个文件
• 或使用 pv build 自动同步

5. 开发环境启动失败

• 确认已安装 pnpm
• 检查 package.json 中是否有 dev 脚本
• 安装依赖：pnpm install

许可证

MIT License

Copyright (c) 2023 Jaxon

作者

Jaxon

如有问题或建议，请联系作者或在项目仓库提交 Issue。