# ludic-canvas 中文文档
规范地址：https://npmcn.com/package/ludic-canvas/
版本：0\.10\.0
npm 元数据更新时间：2026-11-04T00:24:26.881Z
中文译文更新时间：2026-11-04T02:45:00.158Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/ludic-canvas
原文对照：https://npmcn.com/package/ludic-canvas/?lang=original
项目主页：https://libraries.ludic-canvas.victorqueiroz.dev/
源码仓库：https://github.com/VictorQueiroz/ludic-canvas
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：2 MB，139 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：1 个
- peer 依赖：react 19\.3\.1
- 首次发布：2026-10-26T18:43:08.744Z
- 最新版本发布：2026-11-04T00:24:26.559Z
- 已发布版本数：13（近 12 个月 13 个）
## 中文简介
浏览器游戏的React界面，由Yoga WebAssembly和WebGL提供支持。
## 安装
```sh
npm install ludic-canvas
```
也可以使用：`pnpm add ludic-canvas`、`yarn add ludic-canvas`、`bun add ludic-canvas`
## README
# 顽皮的画布
用于浏览器游戏的React界面，由Yoga WebAssembly布局和WebGL渲染提供支持。
[文档](https://libraries.ludic-canvas.victorqueiroz.dev/) · [指南](https://libraries.ludic-canvas.victorqueiroz.dev/guide/) · [API参考](https://libraries.ludic-canvas.victorqueiroz.dev/api/)
用四种类型的原语组合hud、菜单和目录： **视图**， **文本**， **图像** 和 **行**． 当渲染器在WebAssembly中计算flexx布局并使用清晰的MSDF文本绘制批处理GPU原语时，使用React状态、效果和上下文。
控制 **按钮**， **开关**， **滑块**， **选项卡**， **选项卡**， **对话框** 和 **ScrollArea** 组件在离开它们的布局时共享交互行为， 游戏的颜色和内容。探索 [组件目录](https://libraries.ludic-canvas.victorqueiroz.dev/components/)。
0.7.0版本增加了controlled **TextInput** 和 **文本区域** 本地的 最顶层的表单面板和对话框的编辑器。看到 [本地编辑合同](https://npmcn.com/package/ludic-canvas/docs/NATIVE_EDITING.md) 对于字体，分层，构图和资格限制。这些字段需要 Ludic-canvas 0.7.0或更高版本。
0.9.0版本包含一个 **实验便携式核心和macOS证明**： 同样的React组件运行在Hermes、native Yoga和Skia/Metal上。这项工作 仍然是实验性的。看到 [架构和构建指令](https://npmcn.com/package/ludic-canvas/docs/PORTABILITY.md) 和 [资格的结果](https://npmcn.com/package/ludic-canvas/docs/PORTABILITY_RESULTS.md)． Android, iOS, Windows 和Linux主机仍然是未来的工作。
## 安装
npm包包括JavaScript、TypeScript声明、预编译的Yoga反应器、默认的OFL字体图集、可移植字体图集编译器和许可声明。
```sh
npm install ludic-canvas react@19.3.1
```
版本使用中描述的变更集版本- pr工作流 [文档/ RELEASING.md](https://npmcn.com/package/ludic-canvas/docs/RELEASING.md)。
## 启动一个项目（0.4.0+）
```sh
npx ludic-canvas@latest init my-game --template canvas2d
cd my-game
npm install
npm run dev
```
选择 `--template three` Three.js的世界。两个启动器都包含一个透明的 UI覆盖，控制HUD，应用程序拥有的仿真/帧循环，响应 画布大小，许可字体，开发/构建前的字体生成，以及 资源拆卸。初始化器接受新目录或空目录 自动安装依赖项。使用 `npm run build` 生成 `dist/`。
取代 `fonts/Interface.ttf` 和编辑 `ludic-canvas.fonts.json` 带上你自己的 授权的TTF、OTF、WOFF或WOFF2字体。导入的atlas url支持部署 在URL前缀下。看到 [初始化器指南](https://libraries.ludic-canvas.victorqueiroz.dev/guide/#project-init)。
## 共同控制
```tsx
import { useState } from 'react';
import { Switch, Text } from 'ludic-canvas';
function Hints() {
const [enabled, setEnabled] = useState(true);
return (
{enabled ? 'Hints on' : 'Hints off'}
);
}
```
值仍然由应用程序控制。滑动条渲染函数接收 归一化比例自定义轨道/拇指。选项卡管理一个键盘选项卡停止和 跳过禁用的条目。对话框通过嵌套隔离输入并恢复焦点 范围。ScrollArea提供垂直滚轮/触摸滚动和焦点显示。 `useUIRoot()` 访问内部的所属根 `ui.render()`;分开的根保持 他们自己的焦点，React状态和资源。没有使用全局活动根。
## 字体图集CLI （0.2.0+）
该包包含一个可移植的CLI：
```sh
npx ludic-canvas fonts --init
# Set the font source paths in ludic-canvas.fonts.json
npx ludic-canvas fonts --config ludic-canvas.fonts.json
```
```json
{
"$schema": "https://libraries.ludic-canvas.victorqueiroz.dev/font-atlas.schema.json",
"output": "public/fonts",
"fonts": [
{
"name": "interface",
"source": "fonts/Interface.woff2",
"size": 48,
"distanceRange": 6
}
]
}
```
输入为单面轮廓 **TTF， OTF， WOFF和WOFF2** 字体，包括变量 配置了轴标记的字体，如 `"variations": { "wght": 600 }`。 路径是相对于配置文件的。命令行生成MTSDF PNG文件， JSON指标和缓存清单。通过注册PNG/JSON `createUI({ fonts })`。 安装后不需要本机编译器、外部可执行文件或网络连接。
将CLI命令添加到您的项目中 `predev` 和 `prebuild` 生成的脚本 只有当输入改变时。使用 `--force` 重建。看到 [字体命令行指南](https://libraries.ludic-canvas.victorqueiroz.dev/guide/#font-cli) 用于字符覆盖，可变字体和诊断。
## 第一个界面
[在StackBlitz中打开最小计数器](https://stackblitz.com/fork/github/VictorQueiroz/ludic-canvas/tree/main/examples/first-interface?file=src/main.tsx) 或者运行 [独立的例子](https://npmcn.com/package/ludic-canvas/examples/first-interface)． 它安装已发布的 并使用其捆绑的字体和布局WASM，而不使用本地构建工具。 看到 [已测试的消费者配置](https://npmcn.com/package/ludic-canvas/docs/INTEGRATION.md) 发展 启动和浏览器验证。
给画布一个非零的CSS宽度和高度。然后使用自动JSX编译：
```tsx
import { createUI, View, Text } from 'ludic-canvas';
const ui = await createUI({ canvas });
ui.render(
Ready to play
startGame()}
style={{ padding: 16, background: '#526dff', borderRadius: 8 }}
>
Start game
,
);
// On scene teardown:
ui.destroy();
```
## 可玩性整合示例
这个 [玩画廊](https://libraries.ludic-canvas.victorqueiroz.dev/play/) 提供可选择的缩略图，一个活动的游戏视窗和集成说明，为每个例子。
[轨道继电器](https://libraries.ludic-canvas.victorqueiroz.dev/play/?example=orbital-relay) 是一款带有Canvas 2D世界和透明Ludic Canvas HUD的小型快递游戏。它包括货物收集和交付，碰撞，增强，暂停和重放，响应清单和键盘/触摸控制。
这个 [示例源](https://npmcn.com/package/ludic-canvas/examples/orbital-relay) 仅使用公共库导出。它的接口和任务模块分别定义了一个字体族和一个CLI配置。应用程序根由两者组成 `FontSource` 值，在React外部保持模拟状态，并驱动 `ui.frame(now)` 从游戏循环来看。
```sh
npm run fonts:game # regenerate Oxanium and Space Mono atlases
npm run dev # open /play/ or play inside the homepage
```
## 体系结构
```text
React components and hooks
↓
Retained host tree + input
↓
Yoga 3.2.1 layout in WebAssembly
↓
Painter, animation and hit testing
↓
WebGL 1 batches + MSDF font atlases
```
该库拥有布局、渲染、动画和输入。你的应用程序拥有游戏状态、模拟、持久性、音频和资产。提供图像url或解析器、注册字体图集和自定义主题令牌。没有绑定游戏模式、资产目录或ECS。
默认启动自动绘图。对于游戏拥有的循环，通过 `autoStart: false` 并调用 `ui.frame(now)` 游戏渲染后。透明的覆盖画布独立于游戏的渲染器工作。高级WebGL 1集成可以提供共享上下文；UI更改GL状态，引擎必须在下一次通过之前重置其状态缓存。
## 发展
Node 24或更新版本：
```sh
npm ci
npm run dev # documentation and interactive examples
npm run check # types, real WASM/React tests, docs, distribution audit
npm run format:check
npx playwright install --with-deps
npm run test:browser # Chromium, Firefox, WebKit and mobile emulation
npm pack # installable release tarball
```
该文档使用Vite和静态HTML作为可抓取的指南和从发出的TypeScript声明生成的API引用。它的实例使用了构建包的公共输出。
看到 [CONTRIBUTING.md](https://npmcn.com/package/ludic-canvas/CONTRIBUTING.md) 对于源映射，生成的文档， 集中浏览器检查，CI故障排除和证据程序。的日期为 [会话切换](https://npmcn.com/package/ludic-canvas/docs/SESSION_HANDOFF.md) 记录验证状态和剩余工作。
重新构建可选的本地工具：
```sh
npm run toolchain -- --llvm /path/to/llvm
npm run wasm
npm run fontgen:wasm
npm run fonts:example
```
Yoga使用c++ 23， CMake 3.28+，原始Clang/LLVM和wasm-ld，并使用sha -256固定的Yoga和WASI工具链下载。不使用Emscripten。可移植字体编译器将固定的msdf-atlas-gen、FreeType和Brotli源代码构建到WASI命令中。消费者使用Node运行包含的编译器，不需要本地工具。
## 出版
运行 `npm run changeset` 对于可发布的行为变化。合并到 `main` 打开或 更新一个版本PR。将PR通过npm OIDC发布的版本与 来源，在Linux/macOS/Windows检查通过后。工作流创建标记和 GitHub发布和跳过npm上已经存在的版本。
看到 [文档/ RELEASING.md](https://npmcn.com/package/ludic-canvas/docs/RELEASING.md) 对于常规放行程序， `npm run verify:release`、部署验证和历史所有者设置。 没有npm令牌存储在GitHub机密中。
## 兼容性和范围
Ludic Canvas瞄准桌面和手机浏览器游戏。React 19.3.1是测试的对等版本；react-reconciler 0.34.0被固定，因为它的主机API不稳定。浏览器需要WebGL 1， WebAssembly SIMD/bulk-memory， createImageBitmap和Pointer Events。
运行时支持捕获的指针/键事件、垂直滚轮/触摸滚动、范围热键、模态焦点范围、空间焦点导航、DOM控制/组语义、礼貌的实时通知、文本缩放和减少运动。镜像是一个有限的辅助工具，而不是一个完整的语义文档。
文本使用预烤的字形，地图集对字距和贪婪包装。一串或 有序数组 `fontFamily` 选择注册面；每个字形都使用第一个 脸上含着它。所有选择的面都共享一个基线，而回退指标可以 增加行高。集 `fontKerning: 'none'` 禁用配对调整。 Complex-script/GPOS塑形，bidi，石墨烯感知包装，可编辑的画布文本， 共享的WebGL 2上下文和本地引擎绑定仍然没有实现。到 每个根支持四个字体地图集。看到 [生产审核](https://npmcn.com/package/ludic-canvas/PRODUCTION.md) 和 [支持矩阵](https://libraries.ludic-canvas.victorqueiroz.dev/guide/#production)。
```tsx
const ui = await createUI({
canvas,
fonts: [interfaceFont, symbolsFont],
onFontDiagnostic: (diagnostic) => console.warn(diagnostic.message),
});
ui.render(Café · Ready);
```
使用你的名字 `FontSource` 值。缺失的字形变成 `?` 在 主要面对和可以产生一个可选择的诊断，每个代码点/订购一次 链，上限为每个根1024个报告。当改变字符集时再生一个地图集 报道。CLI提取遗留文件 `kern` 表;只有gpos的字体可以输出零 对。没有字距数组的现有atlas JSON仍然可用。
这个 [性能实验室](https://libraries.ludic-canvas.victorqueiroz.dev/performance/) 运行固定的UI工作负载并下载带有源/环境元数据的原始示例。 看到 [测量限制和获取说明](https://npmcn.com/package/ludic-canvas/docs/PERFORMANCE.md)。
这个 [路线图](https://npmcn.com/package/ludic-canvas/ROADMAP.md) 定义专用排版里程碑和 [物理设备鉴定协议](https://npmcn.com/package/ludic-canvas/docs/DEVICE_QUALIFICATION.md) 分离 来自硬件和辅助技术证据的自动正确性检查。
## 许可证
MIT©Victor Queiroz。绑定的字体使用SIL开放字体许可证。看到 [THIRD\_PARTY\_NOTICES.md](https://npmcn.com/package/ludic-canvas/THIRD_PARTY_NOTICES.md) 和 [许可/](https://npmcn.com/package/ludic-canvas/licenses/)。
## 3D样例工程
[玩《红隼调查》](https://libraries.ludic-canvas.victorqueiroz.dev/play/?example=kestrel-survey) 或者运行 [独立实例工程](https://npmcn.com/package/ludic-canvas/examples/kestrel-survey)． 它结合了一个程序化的3 .js世界和一个完全自定义的Ludic Canvas界面：投影站点标签、任务卡、遥测、小地图、相机控制、模态菜单和移动站点选择器。
```sh
cd examples/kestrel-survey
npm install
npm run dev
```
## 大集合
`VirtualList` 提供具有稳定键的固定高度单选择集合； 扫描，控制选择和逻辑键盘/手柄焦点。普通的 `ScrollArea` 区域可以公开独立类型的滚动句柄。看到 [收集指南](https://libraries.ludic-canvas.victorqueiroz.dev/guide/#virtualization)， [完整的合同](https://npmcn.com/package/ludic-canvas/docs/VIRTUALIZATION.md)，以及里面4000条记录的档案 [红隼调查](https://libraries.ludic-canvas.victorqueiroz.dev/play/?example=kestrel-survey)。 这个 [性能实验室](https://libraries.ludic-canvas.victorqueiroz.dev/performance/) 比较匹配的保留/窗口工作负载并保留原始测量值。
浏览器根自动使用包含渲染画布块的本地溢出 对于支持的滚动面板。浏览器提供动力，而React， Yoga 应用程序的框架循环保留它们现有的所有权。使用 `scrollMode="canvas"` 按地区或 `scrollMode: 'canvas'` 在 `createUI` 选择 帆布表示。共享上下文，自定义手势和不支持的布局 自动后退。看到 [滚动的合同](https://npmcn.com/package/ludic-canvas/docs/SCROLLING.md) 为 支持边界、贴图预算和快照定时。
## 常见问题
### ludic-canvas 是什么？
浏览器游戏的React界面，由Yoga WebAssembly和WebGL提供支持。
### 如何安装 ludic-canvas？
在项目目录运行 npm install ludic-canvas，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（19\.3\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 ludic-canvas，可以用 npx ludic-canvas 直接运行。
### ludic-canvas 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### ludic-canvas 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### ludic-canvas 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### ludic-canvas 可以商用吗？
ludic-canvas 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### ludic-canvas 还在维护吗？
最新版本 0\.10\.0 发布于 2026/11/04（1 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/10/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。