墨池 Inkpond

简体中文 · English

以字为墨，以页为池：一层铺在网页背后的水墨汉字底。

在线演示 · 发起会话 Demo

汉字按笔画疏密排成画面：远山云雾、鲤鱼游动的荷塘、缓缓展开的清明上河长卷、随日期轮换的二十四节气、鲸影游过的深海，或守着一碗白米饭的大肥鲸。鼠标划过泛起水波，点击空白处落墨，墨迹晕开后慢慢淡去；页面上的内容周围自动留白。

• 六个场景：山水、荷塘、清明上河、按日期自动切换的二十四节气、鲸游深海的北冥，以及搞笑的大肥鲸，可选淡彩
• 会回应：鼠标起波、点击落墨，鲤鱼躲人、抢食，行人被墨惊散，鲸被触到会下潜，大肥鲸被戳会笑
• 不碍事：内容周围自动留白，鱼、船、行人也会绕开
• 够轻：Canvas 2D，零运行时依赖，每帧脚本开销不到 2 ms，弱设备自动降级
• React 可选：提供 <InkPond /> 组件，不用 React 也能直接用

场景

scene	画面	会动的东西
shanshui（默认）	两重远山，云雾飘过	云雾
lotus	俯看荷塘：荷叶、荷花、浮萍	鲤鱼绕开内容游动，鼠标靠近会散开，落墨处会游过来
qingming	清明上河长卷：群山城郭、宝塔城楼、两岸酒旗飞檐、横跨两岸的木拱虹桥	长卷向左展开，船夫撑船，行人过桥，落墨惊散行人
jieqi	二十四节气，每个节气一幅画面，默认显示今天所在的节气	见下表；页面开着时跨入下一个节气，会以墨晕的方式过渡过去
beiming	北冥：俯看深海，浪下一头鲸的影子	鲸缓缓游动，约一分钟浮起又沉没一次，浮浅时在海面留下平静的鲸迹；鼠标触到它会下潜，落墨引它游近
dafeijing	大肥鲸：一条圆滚滚的鲸，角落里一碗白米饭——饭是留白，只在饭堆边上撒几个「米」	饿了就游去埋头干饭，米粒飞进嘴里，碗里的饭变少、鲸越吃越胖；吃饱打嗝，从喷气孔喷出一串米，瘪回原样，碗里慢慢续满。落墨处撒一把米引它来吃，鼠标戳它会压扁、回弹、笑出「哈」

荷塘、清明上河、节气、北冥和大肥鲸带一点淡彩（朱、胭脂、赭石、花青），设 tint={false} 只用墨色。

二十四节气

scene="jieqi" 按太阳黄经判断今天所在的节气（误差约一刻钟）。用 term 固定显示某个节气，或用 date 显示某一天的节气：

<InkPond scene="jieqi" />                          // 今天的节气，跟着时间走
<InkPond scene="jieqi" term="shuangjiang" />       // 只显示霜降
<InkPond scene="jieqi" date={new Date(2027, 0, 20)} /> // 那一天的节气（大寒）

jieqiAt(date) 返回某一时刻所在节气的 term，JIEQI 列出全部 24 个（id、名称、黄经）。

节气	term	画面	点击落墨时 / 鼠标
立春	lichun	冰面从一点裂开，裂缝旁冒出「芽」	落墨处成为新的破冰点
雨水	yushui	「雨」斜落，水面一圈圈涟漪	鼠标左右决定风向
惊蛰	jingzhe	闪电劈下、全屏一闪，「虫」从地里被震起	落墨处落雷
春分	chunfen	画面一半昼一半夜，朱色分界线起伏，燕子穿线	分界线跟随鼠标
清明	qingming	垂下的柳丝摆动，朱色纸鸢，细雨	鼠标拨开柳丝
谷雨	guyu	牡丹层层绽开，花瓣随雨飘落	落墨处开出新花
立夏	lixia	蛙鸣化作声波，层层叠加	鼠标靠近蛙叫得更急；落墨处一圈声波
小满	xiaoman	麦浪一道道滚过	鼠标处麦子被压低
芒种	mangzhong	朱色插秧线横扫水田，留下成行秧苗	落墨处插秧线移过去
夏至	xiazhi	朱色烈日、旋转的光芒，地面热浪扭曲	太阳缓缓跟随鼠标
小暑	xiaoshu	热气羽流上升扭动，蝉鸣	鼠标处吹来凉风
大暑	dashu	夜草丛上萤火游走，拖出光点	萤火被鼠标吸引
立秋	liqiu	大片留白，一片「叶」飘落入水	鼠标吹偏落叶
处暑	chushu	朱色热区被湍动的锋面推出画面，露出花青，鹰盘旋	鼠标处就地降温
白露	bailu	草叶上露珠凝结，饱满后滑落	碰到露珠它就滑落
秋分	qiufen	满月被朱色直径平分，直径缓慢自转	直径指向鼠标
寒露	hanlu	雁阵在「人」字和「一」字之间变换，地面菊丛	雁阵避开鼠标
霜降	shuangjiang	六角霜花从边缘生长，朱色枫叶飘落	鼠标的暖意融霜
立冬	lidong	水波由快到慢冻成冰纹，开裂后解冻	落墨处加一个波源
小雪	xiaoxue	三层景深的疏雪	鼠标吹开雪花

荷塘	山水

安装

npm i inkpond

用 React 时还需要 react（18 及以上，可选的 peer 依赖）。

npm i github:shin4/inkpond

从 GitHub 安装时会现场构建 dist/：

• npm 11 会对带构建脚本的依赖给出 allow-scripts 提示，安装照常完成；如果你的配置禁止依赖运行脚本，执行 npm approve-scripts inkpond。

• bun 默认不运行依赖的脚本，也不安装依赖的开发依赖。需要项目里有 TypeScript，并信任 inkpond：

  bun add -d typescript
  bun add github:shin4/inkpond
  bun pm trust inkpond
  

用法

React

import { InkPond } from "inkpond/react";
import "inkpond/inkpond.css";

<main style={{ position: "relative" }}>
  <InkPond scene="lotus" active={isEmpty} />
  <section data-inkpond-avoid="">…问候语…</section>
  <form data-inkpond-avoid="">…输入框…</form>
</main>

• 画布铺满最近的定位父元素，并从它接收鼠标事件。
• 带 data-inkpond-avoid 的元素周围自动留白，后来才出现的元素也会被识别。
• active 表示这一块是否在屏幕上；标签页切到后台会自动暂停。
• 其他选项只在挂载时读一次，想改就换一个 key 重新挂载。
• 组件已标记 "use client"，可以直接放进 Next.js App Router 的服务端组件里。Vue、Svelte 的接入示例见 常见问题。

不用 React

import { createInkPond } from "inkpond";
import "inkpond/inkpond.css";

const pond = createInkPond(document.querySelector("canvas.inkpond")!, {
  scene: "qingming",
});
pond.setActive(false); // 这一块被隐藏时
pond.destroy();        // 卸载时

主动拨动水面

页面自己也可以起波、落墨，比如打字时起涟漪、发送时落墨。坐标是视口坐标（clientX / clientY）：

pond.ripple(x, y, 0.4); // 一圈水波，强度 0–1，默认 1
pond.drop(x, y);        // 落墨；落在留白元素上会被拒绝，返回 false

React 里通过 pondRef 拿到同一个对象：

const pondRef = useRef<InkPond | null>(null); // InkPond 类型来自 "inkpond"
<InkPond pondRef={pondRef} />
// 之后：pondRef.current?.ripple(x, y)

暂停、减少动画模式和静帧档下，这两个调用不生效。

选项

选项	默认值	说明
scene	"shanshui"	shanshui / lotus / qingming / jieqi / beiming / dafeijing
term	今天的节气	仅 jieqi：固定显示某个节气，如 "qingming"
date	现在	仅 jieqi：显示这一天的节气，之后不再随时间切换
tint	true	是否画淡彩；false 只用墨色
active	true	是否在屏幕上；后台标签页总会暂停
strength	0.45	场景画面的墨色浓淡，不影响水波和墨迹
waveSpeed	1	水波速度倍数
cellSize	跟随档位（16）	字格大小（CSS px，12–48），即字号；越小字越多、越费；降档后不会小于该档的字格（轻量档 22）
levels	场景自带	替换主地面（山水的山、荷塘和清明的水面、北冥和大肥鲸的海面）的字表，从淡到浓；换字需要自备字体；节气场景不使用
reducedMotion	跟随系统	开启后只画一张静止画面，不响应鼠标
avoidAttribute	data-inkpond-avoid	标记留白区域的属性名
avoidPadding	20	留白元素四周完全空出的宽度（CSS px）
avoidFade	140	留白边缘墨色恢复的过渡宽度（CSS px）
fontUrl	场景自带子集	设为 null 只用后备字体
fontFamily / fallbackFonts	场景自带 / 宋体系	字体名和后备字体
tierStorageKey	inkpond.tier	记住降级档位的 localStorage 键；null 不记

颜色：墨色取画布的 color，可用 CSS 变量 --inkpond-ink 设置，--inkpond-alpha 是最深处的不透明度。淡彩来自 --inkpond-zhu（朱）、--inkpond-yanzhi（胭脂）、--inkpond-zhe（赭石）、--inkpond-huaqing（花青）。inkpond.css 已处理 prefers-color-scheme 以及 <html> 上的 .dark / data-theme="dark"，主题切换后颜色自动更新。

性能

每个字只栅格化一次存进图集，之后每帧只贴图；静止的画面按窗口尺寸预先算好，云雾等慢变层每 4 帧重算一次。

This is the beginning of the README. Read the rest at the original. Read the full README ↗