# @canshift/core 中文文档

规范地址：https://npmcn.com/package/%40canshift/core/

版本：13\.11\.1
npm 元数据更新时间：2026-10-22T08:46:01.119Z
中文译文更新时间：2026-11-09T16:02:53.092Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：486 kB，281 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-08-02T23:25:24.502Z
- 最新版本发布：2026-10-22T08:46:00.224Z
- 近 30 天下载量：2276（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：63（近 12 个月 63 个）

## 中文简介

CANShift 共享配置域类型、 设置和验证

## 安装

```sh
npm install @canshift/core
```

也可以使用：`pnpm add @canshift/core`、`yarn add @canshift/core`、`bun add @canshift/core`

## README

# 移动核心

`canshift-core` ——CANShift生态系统纯TypeScript合同层.

📖 **[文档](https://npmcn.com/package/%40canshift/core/docs/README.md)** - 配置合同和电线 协议版本规则.

* * *

## 目的

`canshift-core` 为:

-   **配置类型** —— 说 `DashboardConfig`, (中文(简体) ), `Widget` 歧视工会, `PageConfig`, (中文(简体) ), `TopBarConfig`, (中文(简体) ), `ButtonAction`, (中文(简体) ), `DeviceConfig`, (中文(简体) ), `SignalConfig`, (中文(简体) ), `InputBindingsConfig`
-   **验证** 对仪表板、信号和设备配置进行运行时间检查
-   **Schema 迁移** ——将更老的配置带往前的版本链 `CURRENT_SCHEMA_VERSION`
-   **设计符号和部件测量标准( W)** —— 说 `DARK_TOKENS` 调色板+ `tokensToCssVars` 由Tuner公司消费`canshift-tuner/`生成 `src/styles/tokens.generated.css`),加 (中文(简体) ) `widget-metrics.ts` (由固件渲染器镜像的共用测量表/标签/相向光几何)和 `theme-presets.ts` (8个内置短线主题)
-   **线格式计划** —— 说 `DeviceConfigWireSchema`, (中文(简体) ), `InputBindingsConfigWireSchema`, (中文(简体) ), `TrackTelemetrySchema`, (中文(简体) ), `ScreenSettingsSchema`, ECU 配置文件, 硬件配置文件

它纯为TypeScript,有Node.js,浏览器,或React Introduct API. 现在 它被消耗 `canshift-tuner` 财务报告和审定财务报表 `canshift-mobile`. 运输形态 居住类型 `canshift-tuner/src/transport/` 所以核心可以留下来 浏览器/节点中和 .

没错 **没有** 包含:

-   固件 C++ 代码( 运行于 `canshift-firmware/`(中文(简体) )
-   UI 组件( 运行于 `canshift-tuner/src/`(中文(简体) )
-   节点或反应原生特定 API

* * *

## 文件夹结构

```
canshift-core/
└── src/
    ├── index.ts              # Package root — re-exports every entry plus the config contract
    ├── entries/              # One file per subpath export, re-exports only
    ├── schemas/              # Zod schemas — dashboard, widgets, signals, device, wire payloads
    ├── migrations/           # Shape-change steps from MIGRATION_FLOOR_VERSION to CURRENT_SCHEMA_VERSION
    ├── validation/           # validateDashboard
    ├── wire/                 # TELE, ALERT and CAN monitor binary frames, device commands, JSON envelope parsing
    ├── track/                # Lap crossing detection, start/finish line
    ├── widget-metrics/       # Dash geometry and colours the firmware renderer mirrors
    ├── design-tokens/        # Tuner CSS tokens
    ├── controls/             # Button control vocabulary
    ├── ecu-profiles/         # Built-in ECU signal catalogues, OBD-II PIDs and DTCs
    ├── can-xml/              # CAN XML import
    ├── board-profile/        # Board profile blob format
    ├── constants/            # FIRMWARE_CAPS, STRING_CAPS, dash signals
    ├── display-tiers.ts      # Read by the firmware parity script — do not move
    ├── layout-grid.ts        # Read by the firmware parity script — do not move
    ├── schema-version.ts     # Read by the firmware build — do not move
    └── __tests__/
```

`constants/firmware-caps.ts`, (中文(简体) ), `display-tiers.ts`, (中文(简体) ), `layout-grid.ts` 财务报告和审定财务报表 `schema-version.ts` 是用一个兄弟的软件来解析的 退出,所以这些路径及其文字布局是合同的一部分.

* * *

## 公共 API

根出出口携带着所有消费进口品. 子路径带一片 一个没有树震的捆绑者只负载模块 切片后面:

| 导入 | 它所持有的 |
| --- | --- |
| `@canshift/core` | 下方的一切,加上仪表板配置合同,验证,迁移 |
| `@canshift/core/wire` | TELE, ALERT 和 CAN 监视帧, 设备命令, 状态 / USB / 计时器有效载荷解析器 |
| `@canshift/core/track` | 拉普过道探测器、起跑/终点线、轨迹遥测计划 |
| `@canshift/core/widget-metrics` | Dash 几何、重度、传感器范围和危险波段、转向灯段 |
| `@canshift/core/tokens` | Tener 设计符及其 CSS 变量 |
| `@canshift/core/ecu-profiles` | ECU目录, MaxxECU 单元, OBD- II 模式 01 PID 和 DTC 解码 |
| `@canshift/core/schema-version` | `CURRENT_SCHEMA_VERSION` |

出口没有取消消费进口,以后没有保留. `Widget` 是一个 工会歧视 `type`: 缩小 `widget.type` 缩进 `widget.config`, (中文(简体) ), 财务报告和审定财务报表 `WidgetOfType<'gauge'>` 一个成员的名字.

* * *

## Schema 版本和迁移

每个配置文件都包含 `"version"` 字段的根 :

```json
{ "version": "1.41.0", ... }
```

`CURRENT_SCHEMA_VERSION` (单位:千美元)`src/schema-version.ts`)是这个代码读取和写入的版本. 其分解如下:

-   **大师** ——突破计划变化,需要迁移
-   **毛里塔尼亚** ——添加剂变化,后相兼容
-   **帕齐** - 只修改文件或评论

在装入配置时,消费者必须:

1.  读取 `version`
2.  若为 `version === CURRENT_SCHEMA_VERSION` \* 正常装载
3.  若为 `version < CURRENT_SCHEMA_VERSION` 运行 `migrateConfig(config, CURRENT_SCHEMA_VERSION)`; 比 `MIGRATION_FLOOR_VERSION` (1.24.0) 丢出一个 `below_floor` `MigrationError`
4.  若为 `version > CURRENT_SCHEMA_VERSION` 请用户更新应用程序

登记处持有 **只更改形状**。只添加可选字段凸起的发布 `CURRENT_SCHEMA_VERSION` 且不需要输入 : `migrateConfig` 运行文件版本与目标之间的每一步顺序,然后设定目标版本. 超过1.24.0的配置不再装入(#151).

### 形状变化(从1.24.0层)

| 步骤 | 变动 |
| --- | --- |
| 1.2.4.0 − 1.2.5.0 | 转换为12列网格跨度的像素布局,取自目标屏幕配置 |
| 1.2.6.0 — 1.27.0 (中文(简体) ) | 顶级部件 `type` 已调整为 `config.type` |
| 1.2.8. − 1.29.0 (中文(简体) ) | 遗留旗上方栏移入音轨栏 |
| 1.29.0 − 1.30.0 (中文(简体) ) | 高盖 `arcFillStyle` 空出- 光谱限制填充 |
| 1.30.0 — 1.31.0 (中文(简体) ) | 扣子图标字段被剥除——破折号上没有图标 |
| 1.36.0 − 1.37.0 (简体中文) | 主题相配 `theme.day` 编号 : `theme.night` |
| 1.39.0 — 1.40.0 (中文(简体) ) | 高盖 `alertThreshold` 扔了,它没有武器 |
| 1.42.0 — 1.43.0 (中文(简体) ) | `criticalAlert` 成为单条目列表 `criticalAlerts` |
| 1.43.0 — 1.44.0 (中文(简体) ) | 字符串切入固件缓冲器(上条文本/格式 15, ids 31), `zOrder` 夹住 |

`migrateConfig` 在任何迁移运行前(# 282) 深切入输入, 所以单个迁移可以自由突变, 而不用化名调用对象 .

* * *

## 验证

验证是 **佐德后卫** (Zod为: `canshift-core`唯一的运行时间 (b) 依赖性。 每个验证符返回 :

```ts
{ valid: boolean; errors: string[]; warnings: string[]; config?: T }
```

`config` 只在成功分支上出现,并且经过验证 `DashboardConfig` (或等值)随时可以消费.

`validateDashboard` 涵盖:

-   布局界限对齐 `CANVAS` 财务报告和审定财务报表 `TOPBAR_HEIGHT`
-   十六进制颜色 `HexColorSchema`
-   信号目录引用( 每个绑定的信号都存在)
-   复制部件标识
-   固件盖从 `FIRMWARE_CAPS` (每页最大部件,最大页等)
-   歧视 `WidgetConfig.type` 详尽无遗

维特套接字套接字行为与捆绑 `dashboard.json` fixture (# 287) 所以当形状变化在没有对齐迁移的情况下被引入时立即回归表面.

* * *

## 固件同步要求

`config_types.h` 内 `canshift-firmware/src/config/` 在 C++ 中镜像这些 TypeScript 类型. 更改时 `DashboardConfig`, (中文(简体) ), `PageConfig`, (中文(简体) ), `WidgetConfig`,或 `SignalDef`数字 :

1.  在此更新类型脚本类型
2.  弹出 `CURRENT_SCHEMA_VERSION` 如果改变并非纯粹是添加剂
3.  在 `migrations/migration-runner.ts` 和相应的测试
4.  更新 `config_types.h` 在坚固的软件中匹配
5.  更新 `config_loader.cpp` 在读取新字段的固件中

在运行时检测到固件和核心之间的 Schema 错配 stale 固件与更新的配置对齐, 记录一个明显的错误而不是 默读字节(# 259) 。 坚固的器皿 **不运行迁移 链式** ——只有图纳人向前迁移配置. 问题1019(A-COMPAT-1) 跟踪将拒绝不匹配的推进的固件侧前飞行 而不是无声地侮辱.

* * *

## 正在安装的项目

从 npm 安装 :

```bash
npm install @canshift/core
```

地方发展与未公布的变化: `npm link` 或暂时的 `file:` 取消——从未承诺.

* * *

## 构建测试( T)

```bash
npm run build         # tsc → dist/
npm run lint          # eslint src
npm run format:check  # prettier --check src/**/*.ts
npm test              # Vitest
```

下方的维特套房 `src/__tests__/` 涵盖迁移,仪表板验证(完整和端到端),信号验证,设备验证,并捆绑固定.

* * *

## 公约和规则

-   **纯类型脚本** ——无节点,浏览器,或反应原生API
-   **严格打字** 没有 `any`缩; 窄 `unknown` 使用前带有类型守护符
-   **仅公布条目** - 消费者从 `@canshift/core` 或其子路径出口; `dist/` 未导出路径
-   **弹出 `CURRENT_SCHEMA_VERSION`** 任何时候 `DashboardConfig` 形状变化,并在同一 PR 中进行对齐迁移
-   **歧视工会** —— 说 `WidgetConfig` 用途 `type` 作为歧视者; 新的部件类型扩展联盟和验证者的详尽切换
-   **镜像 C++** - 这里的每一个变化都必须在固件中反映出来 `config_types.h`

* * *

## 连接到其他项目

-   **移动调试器** 配置符; 导入类型、 验证符、 迁移、 部件度量器、 主题预设、 设计符
-   **移动软件** —— 说 `config_types.h` 在 C++ 中镜像这些类型; 加载器读取相同的 JSON 形状,而渲染器镜像 `widget-metrics.ts` 编号 : `theme-presets.ts` 常数
-   **移动式** ——当需要配置或遥测类型(BLE status schema,屏幕设置边框,设计符号)时,直接消耗同一包

## 常见问题

### @canshift/core 是什么？

CANShift 共享配置域类型、 设置和验证

### 如何安装 @canshift/core？

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

### @canshift/core 支持 TypeScript 吗？

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

### @canshift/core 支持 ESM 还是 CommonJS？

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

### @canshift/core 可以商用吗？

@canshift/core 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @canshift/core 的下载量有多少？

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

### @canshift/core 还在维护吗？

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