本页是速查：环境要求、三步安装、命令参考、产物格式与复现要点。完整教程与架构说明随发行版提供。This page is a quick reference: requirements, a three-step install, command reference, output formats and reproducibility. Full tutorials ship with the release.
只需三样：Node.js、一款中文字体，以及（可选）ffmpeg 用于 MP4 导出。Only three things: Node.js, a CJK font, and (optionally) ffmpeg for MP4 export.
| 依赖Dependency | 要求Requirement |
|---|---|
| Node.js | ≥ 20（低于 20 直接退出并提示）≥ 20 (exits with guidance below 20) |
| 中文字体CJK font | Windows 自带微软雅黑；macOS 自带苹方；Linux 建议 Noto Sans CJKMicrosoft YaHei on Windows; PingFang on macOS; Noto Sans CJK on Linux |
| ffmpeg | 仅 MP4 需要；motionchart setup 可自动补装。不影响 SVG/PNG/GIF/PDF/PPTX/DOCXMP4 only; motionchart setup installs it. Not needed for SVG/PNG/GIF/PDF/PPTX/DOCX |
sudo npm install -g。若已用 sudo 安装，普通用户首次运行 motionchart setup 会在自己的用户目录补装 ffmpeg。Avoid sudo npm install -g on macOS / Linux. If you did, a normal user running motionchart setup installs ffmpeg into the user directory.全局安装渲染引擎，然后跑一次 onboard 完成体检、选目录与验证。约一分钟，只装一次。Install the engine globally, then run onboard once to check the environment, pick a folder and verify. About a minute, once.
npm install -g motionchart-cli --registry https://registry.npmmirror.com
motionchart onboard # 六项体检 → 补装依赖 → 选目录 → 验证图motionchart onboard --check # 只体检，必需项未满足退出码 1
motionchart doctor # 环境复查（版本 / 指纹 / 字体 / ffmpeg）
npx -y motionchart-cli doctor # 不全局安装，直接试先体检数据，再点选保存位置，然后生成 spec、静态预览、正式渲染。所有输出均写入 <OUT_DIR>。Triage the data, pick a save folder, generate a spec, preview, then render. All output goes to <OUT_DIR>.
# 1 · 数据体检
motionchart inspect data.csv --json
# 2 · 点选保存位置
motionchart choose-dir --json
# 3 · 生成 spec
motionchart init bar-race --data data.csv --out "<OUT_DIR>/chart.spec.json"
# 4 · 静态草稿确认 → 5 · 正式渲染
motionchart preview "<OUT_DIR>/chart.spec.json" --preset draft --out-dir "<OUT_DIR>"
motionchart render "<OUT_DIR>/chart.spec.json" --preset defense --out-dir "<OUT_DIR>"render / preview / demo / bundle / gallery / init 未提供输出目录时会直接报错，不会静默写到 C 盘或当前目录。Output folder is required: render / preview / demo / bundle / gallery / init error out without one — never silently writing to C: or the current folder.常用命令速查。加 --json 可获得机器可读输出；加 --help 查看完整参数。The most-used commands. Add --json for machine-readable output, --help for full options.
| 命令Command | 作用What it does |
|---|---|
doctor | 环境复查：版本、构建指纹、Node、光栅化、ffmpeg、字体Environment check: version, build fingerprint, Node, rasterizer, ffmpeg, fonts |
onboard | 首次引导：体检 → 补装 → 选目录 → 验证图First-run guide: checks → install deps → pick folder → verify |
dirs | 建议保存目录、剩余空间与选择器状态Suggested folders, free space and picker status |
choose-dir | 系统窗口点选目录，返回路径（取消则回退默认）Pick a folder via native dialog; returns the path |
check-dir <dir> | 检查目录读写权限与剩余空间Verify write access and free space |
setup | 检查并补装 ffmpeg（国内镜像优先）Check / install ffmpeg (China mirrors first) |
capabilities | 能力边界（能做 / 不做）Capability boundary (can / cannot) |
list | 列出图表类型List chart types |
components / describe | 组件清单与单个组件详情（参数、预设、元素）Component inventory and per-component details |
design / elements | 设计预设（配色/字体/圆角/阴影）与可复用元素Design presets and reusable elements |
inspect <file|url> | 数据体检：列类型、时间字段、统计列Data triage: column types, time fields, stat columns |
clean / convert | 整理数据 / 格式互转Clean data / convert formats |
try <data> | 选图助手：推荐 Top 3、并排对比图与三份 specChart picker: top 3 recommendations, comparison and specs |
wizard | 问答式生成 spec，每步回车即走默认Guided spec builder; Enter accepts defaults |
init <chart> | 据数据生成指定图表的 specGenerate a spec for a given chart type |
validate <spec> | 校验 spec 合法性Validate a spec |
preview <spec> | 静态预览 / 接触表Static preview / contact sheet |
render <spec> | 正式渲染（可 --plan 批量）Render (batch with --plan) |
bundle <spec> | 打包复现包：spec、数据副本、产物与 READMERepro bundle: spec, data copy, outputs and README |
gallery | 生成图表 / 配色单页选择器Generate a single-page chart/palette picker |
fetch <url> | 抓取直链数据并缓存（记录来源与哈希）Fetch and cache URL data (source + hash logged) |
parity <ref> <actual> | 像素级对比，可排除指定区域Pixel comparison with optional exclusions |
一次渲染可任意组合多种产物；六种成品形态覆盖从单帧到归档。One render can combine multiple outputs; six deliverable shapes cover single frames through archival.
| 类别Category | 可选值Options |
|---|---|
| 输出格式Formats | svg · png · gif · mp4 · pdf · pptx · docx · bundle |
| 成品形态Shapes | static · storyboard · gif · mp4 · publication · archive |
| 清晰度Resolution | 720p · 1080p · 2K · 4K（只改像素密度，不改排版） (pixel density only) |
| 场景预设Presets | paper · defense · report · web · draft |
五个领域各带术语、单位、精度、阈值、推荐图组与典型 spec，可直接套用。Five domains each bundle terminology, units, precision, thresholds, chart sets and typical specs — applied directly.
motionchart domains eco # 查看领域口径 · view a domain pack
motionchart init --domain eco --chart heatmap --data x.csveco 生态环境 · pubhealth 公共卫生 · econ 经济金融 · energy 能源双碳 · edu 教育科研eco ecology · pubhealth public health · econ economy · energy energy · edu education
每次渲染在输出目录写入 *.manifest.json，记录渲染器版本、运行环境、spec 与数据 SHA-256、URL 来源与抓取时间、动画帧数与尺寸，以及每个产物的字节数与哈希。Every render writes *.manifest.json: renderer version, environment, spec and data SHA-256, URL source and fetch time, frame count and size, and each output's bytes and hash.
bundle 额外打包 spec、数据副本、产物与 README，可直接归档或交给合作者bundle archives spec, data copy, outputs and README for hand-offnode -v 确认，升级到 20 或以上。Exits immediately: Node below 20. Check node -v and upgrade.fonts-noto-cjk。CJK shows as boxes: missing font. Usually bundled on Windows/macOS; install fonts-noto-cjk on Linux.motionchart setup，或设置 MOTIONCHART_FFMPEG。MP4 fails: missing ffmpeg. Run motionchart setup or set MOTIONCHART_FFMPEG.motionchart onboard --set-dir 或传入 --out-dir。"No output folder": run motionchart onboard --set-dir or pass --out-dir.MotionChart 为专有软件（UNLICENSED），版权归 TheAIer 所有。使用、分发与二次开发需取得书面授权；发布产物经压缩并写入构建指纹，不含源码与 sourcemap，禁止逆向工程与再分发。MotionChart is proprietary (UNLICENSED), copyright TheAIer. Use, distribution and derivative work require written permission. Released builds are minified and fingerprinted, with no source or sourcemaps; reverse engineering and redistribution are prohibited.
本页为产品介绍与速查，不构成授权或服务承诺。完整条款见随包 LICENSE。This page is an introduction and quick reference; it grants no license and is not a service commitment. Full terms ship in the bundled LICENSE.