Cube Icons
Cube Icons 在 <canvas> 上将微小的像素图画渲染为 3D 立方体。每个彩色像素变成一短摞立方体。引擎是 assets/cubes.js（约 9 KB gzip，无依赖），图标库是 assets/icons.js。一切都在浏览器中运行。
工作流程
- 放置它。 决定图标做什么：悬停时构建（菜单、按钮、卡片）、滚动时构建（章节、英雄区）、单次显示（空状态、加载器），或跟随指针（磁吸）。将真实文本保留在 canvas 旁边的 HTML 中。
- 安装。 将
assets/cubes.js和assets/icons.js复制到项目的静态文件夹中，并使用两个<script>标签加载它们，icons.js在前。或者从 CDN 加载：https://cdn.jsdelivr.net/gh/atwalabs/[email protected]/icons.js和.../cubes.js。在框架中，仅在浏览器端加载它们（参见references/recipes.md中的“Frameworks”）。 - 选择或绘制图标。 在匹配时使用内置名称（列表如下）。否则，按照下方的“绘制图标”方法，将图标绘制为一系列调色板键组成的行。
- 编写代码。 在设置了尺寸的 canvas 上创建一个舞台，然后调用
show、scroll、build、sequence或explode。从references/recipes.md中的匹配示例开始。 - 完成。 为 canvas 设置 CSS 宽度和高度，添加
role="img"和aria-label（如果是装饰性的则使用aria-hidden="true"），在键盘焦点上也运行悬停效果，并在组件卸载时调用stage.destroy()。
最小示例
<canvas id="hero-icon" style="width:360px;height:280px" role="img" aria-label="火箭"></canvas>
<script src="icons.js"></script>
<script src="cubes.js"></script>
<script>
const stage = CubeIcons.stage(document.getElementById("hero-icon"), { look: "soft" });
stage.show("rocket");
</script>
内置图标
close, bolt, sword, briefcase, person, phone, browser, envelope, chart, terminal, heart, star, rocket, bulb, camera, gamepad, music, globe, lock, folder, coffee, chat, clock, check, search, download, cursor, home, bell, gear, calendar, pin, wifi, battery, play, arrow, trash, pencil, code, key, bag, cart, gift, trophy, diamond, crown, book, headphones, umbrella, flag, sun, moon, cloud, tree, leaf, fire, planet, sparkle, smile, ghost, robot。
绘制图标
图标是一个等长字符串的数组，像图片一样从上往下读取。每个字符是一个调色板键；. 表示空白。
| 键 | 颜色 | 键 | 颜色 |
|---|---|---|---|
B | 钴蓝色 | G | 绿色 |
W | 纸白色 | P | 淡紫色 |
K | 灰色 | C | 青色 |
L | 浅灰色 | M | 粉色 |
D | 近黑色 | N | 棕色 |
R | 红色 | O | 橙色 |
Y | 黄色 |
让图标看起来舒服的规则：
- 8–16 列宽，6–14 行高。 每行长度相同。更大则失去块状感；舞台默认容纳 900 个立方体（单元格 × 深度）。
- 先画轮廓。 在用单一颜色添加细节之前，先使轮廓可辨认；通过快速浏览各行来检查。
- 轮廓与填充： 在填充色周围使用较深或对比鲜明的轮廓（
K、D），然后加一个重点细节（金色搭扣、红色旗帜、蓝色窗户）。 - 对称 对于对称的物体（奖杯、铃铛、面孔）：镜像每一行。
- 避免孤立的单个单元格，除非是眼睛或火花等特意设计的细节。
- 要按名称放置，将其添加到库中：
Object.assign(window.CUBE_ICONS, { badge: [...] })。或者直接将行数组传递给stage.show(rows)。 - 自定义颜色： 图标可以携带额外的调色板键，格式为
{ colors: { a: "#eb234f", b: "#79a93e" }, rows: ["..aa..", "bbbbbb"] }。为此使用小写字母。除非需求指定了精确颜色，否则优先使用内置调色板。
示例（一个咖啡杯）：
coffee: [
"..W..W.....",
"...W..W....",
"...........",
"KKKKKKKKK..",
"KWWWWWWWKKK",
"KWWWWWWWK.K",
"KWWWWWWWKKK",
"KWWWWWWWK..",
".KKKKKKK...",
],
对于文字，使用 CubeIcons.text("你好", { color: "B" })：这是一个 5 行的像素字体，支持 A–Z、0–9 以及 . , : ! ? - + ' & /。
最重要的选项
CubeIcons.stage(canvas, {
look: "soft", // flat (默认) · soft · clay · candy · paper · outline · pixel · glass · neon · wire · holo
view: "front", // front (默认) · iso
depth: 2, // 立方体深度，1–5
gap: 0.06, // 立方体之间的间隙，0–0.4
tint: null, // 一种品牌墨水色，例如 "#2f3cff"：每种颜色都会以其深浅重新绘制
ease: "expo", // expo (默认，柔和着陆) · cubic · back · elastic · linear
duration: 700, // 每个立方体飞行的毫秒数
stagger: 260, // 每个立方体的随机延迟毫秒数
spin: 0.25, // 飞行时旋转的圈数
from: "auto", // auto · below · above · left · right · center
magnet: 0, // 指针附近的立方体向前弹出（尝试 1.5）
glow: 0, // 立方体周围的光晕，0–1（在深色页面上搭配 tint 效果很好）
float: 0, // 空闲时的运动，0–1：图标摇摆和浮动，松散的立方体漂移
tilt: true, // 深度随鼠标倾斜
});
将外观与页面匹配：soft、clay、candy、paper 和 outline 适合浅色页面；glass、neon 和 holo 适合深色页面；带浅色 tint 的 wire 适合深色或彩色区域；pixel 是任何地方都适用的扁平复古像素艺术。完整的选项和 API 表格见 references/api.md。
方法
stage.show(icon)：构建一个图标（名称或行数组）。显示不同的图标会变形为它。stage.clear()：飞散并淡出。stage.build(icon, progress)：部分构建，0–1，从最底行开始。通过滚动、上传进度、定时器来驱动它。stage.explode(clientX?, clientY?)：撞散立方体；它们会重新归位。stage.burst()：立方体冲向观看者并淡出（用于菜单或页面过渡）。stage.scatter(count, { icon })：在 canvas 上散布松散的立方体；之后的show()会将它们聚集成图标。stage.set(options)、stage.destroy()。CubeIcons.scroll(stage, icon, { mode: "scrub" | "trigger" })、CubeIcons.sequence(stage, icons, { every })、CubeIcons.still(canvas, icon, options)用于静态缩略图。
常见错误
- 没有 canvas 尺寸。 canvas 需要 CSS 宽度和高度，否则渲染为 0 像素高。
- 脚本顺序。 在调用
show()并传入名称之前加载icons.js，在调用CubeIcons之前加载cubes.js。 - 服务端渲染。 永远不要在 Next.js、Nuxt 或 SvelteKit 中于模块顶层接触
CubeIcons；在 effect 或挂载钩子中创建舞台。 - 立方体太多。 20×20 的图标在深度 3 下是 1200 个立方体；降低深度、绘制更小的图标，或提高
max值。 - 仅悬停。 还需要在
focus上触发，这样键盘用户也能看到效果。
参考
references/recipes.md：即用型代码，涵盖菜单、按钮、空状态、变形序列、爆炸、磁吸、文本、功能卡片、滚动区域以及每种框架。references/api.md：所有选项、方法和辅助函数，含默认值。assets/cubes.js、assets/icons.js：引擎和图标库，供复制到项目中。