# Konva.js 中文文档

> Konva 是基于 HTML5 Canvas 的 2D JavaScript 框架，支持图形绘制、事件、拖拽、
> 变换、动画、滤镜与高性能缓存。本站是 Konva 官方文档的中文翻译。

- 站点：https://konva-doc-cn.front-end-js.top
- 官方英文文档：https://konvajs.org/
- 官方仓库：https://github.com/konvajs/konva
- 全文版本：https://konva-doc-cn.front-end-js.top/llms-full.txt

## 开始

- [开始](https://konva-doc-cn.front-end-js.top/docs/intro)：Konva 入门：安装方式（npm、yarn、CDN）、Stage 舞台与 Layer 图层的层次结构，以及一个最小可运行的 Canvas 绘图示例。

## 教程目录

- [教程目录](https://konva-doc-cn.front-end-js.top/docs/overview)：Konva 中文教程总目录：图形、样式、事件、变换、拖拽、滤镜、动画、序列化与性能优化等核心主题，以及中文环境、框架集成、编辑器功能、升级迁移四个原创专题。

## 图形

- [Arc 弧形](https://konva-doc-cn.front-end-js.top/docs/shapes/arc)：用 Konva.Arc 绘制弧形：由 innerRadius、outerRadius、angle 与 clockwise 定义，可做成环形的一段或扇环。
- [Arrow 箭头](https://konva-doc-cn.front-end-js.top/docs/shapes/arrow)：用 Konva.Arrow 绘制箭头：points 定义路径，pointerLength 与 pointerWidth 控制箭头大小，支持双向箭头。
- [Circle 圆形](https://konva-doc-cn.front-end-js.top/docs/shapes/circle)：用 Konva.Circle 绘制圆形：radius 定义半径，x、y 为圆心坐标，可设置 fill、stroke 与 strokeWidth。
- [Custom 自定义图形](https://konva-doc-cn.front-end-js.top/docs/shapes/custom)：用 Konva.Shape 创建自定义图形：在 sceneFunc 中拿到 Canvas 上下文自行绘制，并调用 context.fillStrokeShape(shape) 让 Konva 接管填充、描边与阴影。
- [Ellipse 椭圆](https://konva-doc-cn.front-end-js.top/docs/shapes/ellipse)：用 Konva.Ellipse 绘制椭圆：radiusX 与 radiusY 分别定义横纵半径，x、y 为中心点坐标。
- [Group 分组](https://konva-doc-cn.front-end-js.top/docs/shapes/group)：Konva.Group 把多个图形当作整体移动、缩放、旋转与裁剪；它是容器不是图形，没有填充与描边，width() 恒为 0，包围盒要用 getClientRect()。
- [Image 图片](https://konva-doc-cn.front-end-js.top/docs/shapes/image)：用 Konva.Image 在 Canvas 上渲染图片：传入已加载完成的 HTMLImageElement，并通过 width、height 控制显示尺寸。
- [Label 标签](https://konva-doc-cn.front-end-js.top/docs/shapes/label)：用 Konva.Label 创建带背景的文本标签，可组合 Konva.Tag 做出气泡提示（tooltip），支持指针方向与圆角。
- [Line 线条总览](https://konva-doc-cn.front-end-js.top/docs/shapes/line)：Konva.Line 的四种形态由 closed 与 tension 两个属性组合决定：直线、多边形、样条曲线与 Blob；points 是扁平数组而非坐标对数组。
- [Blob 图形](https://konva-doc-cn.front-end-js.top/docs/shapes/line-blob)：用 Konva.Line 配合 closed 为 true 与 tension 绘制不规则闭合曲线（blob），tension 越大曲线越圆润。
- [Polygon 多边形](https://konva-doc-cn.front-end-js.top/docs/shapes/line-polygon)：用 Konva.Line 配合 closed 为 true 绘制多边形：points 数组按顺序给出各顶点坐标，首尾自动闭合。
- [Line 简单线条](https://konva-doc-cn.front-end-js.top/docs/shapes/line-simple-line)：用 Konva.Line 绘制简单线条：points 数组以 [x1,y1,x2,y2,...] 的形式给出各点坐标，可设置 stroke 与 strokeWidth。
- [Spline 样条曲线](https://konva-doc-cn.front-end-js.top/docs/shapes/line-spline)：用 Konva.Line 配合 tension 属性绘制平滑样条曲线，tension 为 0 时退化为折线，数值越大弯曲越明显。
- [SVG Path 路径](https://konva-doc-cn.front-end-js.top/docs/shapes/path)：用 Konva.Path 渲染 SVG 路径：data 属性直接接受 SVG 的 d 字符串，适合把矢量图导入 Canvas 或以数据字符串描述复杂图形。
- [Rect 矩形](https://konva-doc-cn.front-end-js.top/docs/shapes/rect)：用 Konva.Rect 绘制矩形：设置位置、宽高、填充与描边，并可通过 cornerRadius 指定统一圆角或四角独立的圆角数组。
- [Regular Polygon 等边多边形](https://konva-doc-cn.front-end-js.top/docs/shapes/regular-polygon)：用 Konva.RegularPolygon 绘制正多边形：sides 指定边数、radius 指定外接圆半径，Konva 10 起还支持 cornerRadius 圆角。
- [Ring 环形](https://konva-doc-cn.front-end-js.top/docs/shapes/ring)：用 Konva.Ring 绘制环形：innerRadius 与 outerRadius 分别定义内外半径，常用于进度环与甜甜圈图。
- [Sprite 精灵图](https://konva-doc-cn.front-end-js.top/docs/shapes/sprite)：用 Konva.Sprite 播放精灵图动画：animations 定义每个动画的帧矩形序列，frameRate 控制播放速度，start() 启动播放。
- [Star 星形](https://konva-doc-cn.front-end-js.top/docs/shapes/star)：用 Konva.Star 绘制星形：numPoints 指定角数，innerRadius 与 outerRadius 分别定义内外顶点到中心的距离。
- [Text 文字](https://konva-doc-cn.front-end-js.top/docs/shapes/text)：用 Konva.Text 在 Canvas 上绘制文本：支持 fontSize、fontFamily、fontStyle、align、lineHeight、width 自动换行与 ellipsis 省略号。
- [Text 路径文字](https://konva-doc-cn.front-end-js.top/docs/shapes/text-path)：用 Konva.TextPath 让文字沿 SVG 路径排列：data 给出路径，text 给出文字内容，常用于弧形标题与环绕文字。
- [Wedge 扇形](https://konva-doc-cn.front-end-js.top/docs/shapes/wedge)：用 Konva.Wedge 绘制扇形：radius 定义半径、angle 定义张角、rotation 定义起始角度，常用于饼图。

## 样式

- [混合模式](https://konva-doc-cn.front-end-js.top/docs/styling/blend-mode)：用 Konva 的 globalCompositeOperation 设置混合模式，支持 multiply、screen、overlay 等全部 Canvas 合成操作，可实现遮罩与叠色效果。
- [Fill 填充](https://konva-doc-cn.front-end-js.top/docs/styling/fill)：用 Konva 的 fill 属性或 fill() 方法填充图形。除纯色外还支持图案填充、线性渐变与径向渐变。
- [填充与描边的顺序](https://konva-doc-cn.front-end-js.top/docs/styling/fill-stroke-order)：fillAfterStrokeEnabled 控制 Konva 先填充还是先描边，默认 false（先填充、描边压在上面）；只有半透明描边或粗描边才看得出区别。
- [隐藏/显示图形](https://konva-doc-cn.front-end-js.top/docs/styling/hide-and-show)：用 Konva 的 visible 属性或 hide()、show() 方法控制图形显隐。隐藏的节点不参与绘制，也不响应事件。
- [Line Join 边角](https://konva-doc-cn.front-end-js.top/docs/styling/line-join)：用 Konva 的 lineJoin 属性设置线段拐角样式：miter 尖角（默认）、bevel 斜角、round 圆角。
- [鼠标指针样式](https://konva-doc-cn.front-end-js.top/docs/styling/mouse-cursor)：改变 Konva 舞台上的鼠标指针样式：监听 mouseenter 与 mouseleave，在回调中设置 stage.container() 的 CSS cursor。
- [Opacity 透明度](https://konva-doc-cn.front-end-js.top/docs/styling/opacity)：用 Konva 的 opacity 属性设置图形透明度，取值 0 到 1，0 为完全透明、1 为完全不透明，默认值为 1。
- [Shadow 阴影](https://konva-doc-cn.front-end-js.top/docs/styling/shadow)：用 Konva 的 shadowColor、shadowOffset、shadowBlur 与 shadowOpacity 给图形添加阴影，实例化后也可用同名方法调整。
- [Stroke 笔画](https://konva-doc-cn.front-end-js.top/docs/styling/stroke)：用 Konva 的 stroke 与 strokeWidth 设置图形描边颜色和宽度，也可用 stroke()、strokeWidth() 方法在运行时修改。

## 事件

- [事件绑定](https://konva-doc-cn.front-end-js.top/docs/events/binding-events)：用 Konva 的 on() 方法绑定事件：支持 click、dblclick、mouseover、mouseout、mousedown、mouseup、mousemove、wheel 等桌面事件。
- [取消事件冒泡](https://konva-doc-cn.front-end-js.top/docs/events/cancel-propagation)：用 Konva 的 cancelBubble 阻止事件冒泡：在子节点事件中设为 true，事件对象就不会继续向父级图层与舞台传递。
- [自定义事件监听范围](https://konva-doc-cn.front-end-js.top/docs/events/custom-hit-region)：用 Konva 的 hitFunc 自定义命中区域：可以把可点击范围做得比图形本身更大以便于操作，也可简化命中图绘制来提升渲染性能。
- [桌面/移动端事件支持](https://konva-doc-cn.front-end-js.top/docs/events/desktop-and-mobile)：用事件对同时兼容桌面与移动端：on() 中传入 "mousedown touchstart"、"mouseup touchend" 这样的组合，一次绑定覆盖两种设备。
- [事件委托](https://konva-doc-cn.front-end-js.top/docs/events/event-delegation)：Konva 事件委托：把事件处理器绑定到父节点（图层或分组），通过事件对象的 target 属性识别实际被点击的子图形。
- [触发事件](https://konva-doc-cn.front-end-js.top/docs/events/fire-events)：用 Konva 的 fire() 方法以编程方式触发事件：既可触发 click、mouseover 等内置事件，也可触发自定义事件。
- [图片事件](https://konva-doc-cn.front-end-js.top/docs/events/image-events)：用 Konva 的 drawHitFromCache() 生成精确的图片命中区域，使透明像素不再响应事件——默认情况下图片的透明部分同样可点击。
- [键盘事件](https://konva-doc-cn.front-end-js.top/docs/events/keyboard-events)：Konva 没有内置 keydown、keyup 键盘事件。本文说明如何借助容器的 tabIndex 与 DOM 事件监听，在 Canvas 上响应键盘输入。
- [控制对象是否被监听事件](https://konva-doc-cn.front-end-js.top/docs/events/listen-for-events)：用 Konva 的 listening() 控制节点是否参与事件监听。改变该属性后需要重绘受影响图层的命中图，事件才会真正生效。
- [移动端事件](https://konva-doc-cn.front-end-js.top/docs/events/mobile-events)：用 Konva 的 on() 绑定移动端事件：支持 touchstart、touchmove、touchend、tap、dbltap 以及拖拽相关事件。
- [移动端的滚动和原生事件](https://konva-doc-cn.front-end-js.top/docs/events/mobile-scrolling)：Konva 默认阻止指针交互的浏览器默认行为以避免误滚动。若需保留页面滚动，把图形的 preventDefault 属性设为 false。
- [移动端 tap 与 click](https://konva-doc-cn.front-end-js.top/docs/events/mobile-tap-and-click)：Konva 按输入类型只派发 click 或 tap 之一，并默认对触摸事件调用 preventDefault 抑制浏览器的合成点击；把 preventDefault 关掉会让双重触发回来。
- [多重事件](https://konva-doc-cn.front-end-js.top/docs/events/multi-event)：用 Konva 的 on() 一次绑定多个事件：把多个事件类型用空格分隔写在同一个字符串里，共用同一个回调函数。
- [Pointer 指针事件](https://konva-doc-cn.front-end-js.top/docs/events/pointer-events)：Konva 的 pointerdown / pointermove / pointerup 统一处理鼠标、触摸与手写笔，并按 pointerType 同时派发对应的鼠标或触摸事件——混着监听会收到两次。
- [通过名称移除事件](https://konva-doc-cn.front-end-js.top/docs/events/remove-by-name)：用命名空间事件精准解绑：绑定时写成 click.myNamespace，之后用 off(".myNamespace") 只移除该命名空间下的监听器。
- [移除事件](https://konva-doc-cn.front-end-js.top/docs/events/remove-event)：用 Konva 的 off() 方法移除事件监听，传入事件类型即可解除该节点上对应的绑定。
- [Stage 事件](https://konva-doc-cn.front-end-js.top/docs/events/stage-events)：Konva 的事件从图形开始冒泡，点击空白处不会触发任何事件。本文给出两种方案：铺一层透明矩形，或监听 contentClick 等 content 系列事件。

## 拖拽与释放

- [拖拽/释放](https://konva-doc-cn.front-end-js.top/docs/drag-and-drop)：Konva 拖放入门：用 draggable 属性让图形可拖动，并用 on() 绑定 dragstart、dragmove、dragend 事件，桌面与移动端通用。
- [复杂的拖拽区域](https://konva-doc-cn.front-end-js.top/docs/drag-and-drop/complex-drag-and-drop)：用 Konva 的 dragBoundFunc 定义复杂拖拽边界：把拖拽限制在直线下方、圆形区域内或任意自定义路径中。
- [拖拽组](https://konva-doc-cn.front-end-js.top/docs/drag-and-drop/drag-a-group)：拖拽 Konva 分组：实例化 Konva.Group 时设置 draggable 为 true，或调用 draggable() 方法，组内所有图形会一起移动。
- [拖拽线](https://konva-doc-cn.front-end-js.top/docs/drag-and-drop/drag-a-line)：拖拽 Konva 线条：实例化 Konva.Line 时设置 draggable 为 true，或调用 draggable() 方法，同时支持桌面与移动端。
- [拖拽舞台](https://konva-doc-cn.front-end-js.top/docs/drag-and-drop/drag-a-stage)：拖拽整个 Konva 舞台：给 Stage 设置 draggable 后，拖动画布任意位置都能平移整个舞台，常用于实现画布漫游。
- [拖拽图片](https://konva-doc-cn.front-end-js.top/docs/drag-and-drop/drag-an-image)：拖拽 Konva 图片：实例化 Konva.Image 时设置 draggable 为 true，或调用 draggable() 方法，自动兼容桌面与移动端。
- [拖拽事件](https://konva-doc-cn.front-end-js.top/docs/drag-and-drop/drag-events)：用 on() 监听 Konva 的拖拽事件：dragstart 拖拽开始、dragmove 拖拽过程中持续触发、dragend 拖拽结束。
- [释放事件](https://konva-doc-cn.front-end-js.top/docs/drag-and-drop/drop-events)：Konva 不内置 drop 事件，本文演示如何自行实现 drop、dragenter、dragleave、dragover 检测——关键是把被拖对象移到单独图层。
- [简单的拖拽区域](https://konva-doc-cn.front-end-js.top/docs/drag-and-drop/simple-drag-bounds)：用 Konva 的 dragBoundFunc 约束拖拽方向：限制图形只能水平、垂直或沿对角线移动，也可限制在盒子或圆形范围内。

## 剪辑

- [裁剪函数](https://konva-doc-cn.front-end-js.top/docs/clipping/clipping-function)：用 Konva 容器的 clipFunc 属性以自定义函数定义任意形状的裁剪区域，在回调中拿到 canvas 上下文自行绘制路径，不受矩形限制。
- [裁剪区域](https://konva-doc-cn.front-end-js.top/docs/clipping/clipping-regions)：用 Konva 容器的 clip 属性设置矩形裁剪区域，超出 x、y、width、height 范围的内容不会绘制。适用于 Group、Layer 与 Stage。

## 分组与图层

- [更换容器](https://konva-doc-cn.front-end-js.top/docs/groups-and-layers/change-containers)：用 Konva 的 moveTo() 把节点从一个容器移到另一个容器。容器可以是舞台、图层或分组，分组之间也能相互移动。
- [分组](https://konva-doc-cn.front-end-js.top/docs/groups-and-layers/groups)：用 Konva.Group 把多个图形组合在一起，之后可以对整组统一平移、旋转或缩放。分组还能嵌套，形成更复杂的节点树。
- [分层](https://konva-doc-cn.front-end-js.top/docs/groups-and-layers/layering)：调整 Konva 节点层级：moveToTop()、moveToBottom()、moveUp()、moveDown() 与 zIndex()，同样适用于图层之间的排序。
- [zIndex 层级](https://konva-doc-cn.front-end-js.top/docs/groups-and-layers/z-index)：Konva 的 zIndex 是节点在父容器 children 里的索引，不是 CSS 那样的全局值；设置越界会告警但仍然执行，效果等同 moveToTop。

## 滤镜

- [模糊滤镜](https://konva-doc-cn.front-end-js.top/docs/filters/blur)：用 Konva.Filters.Blur 给图片做模糊：先调 cache() 缓存节点，再用 filters() 应用滤镜，模糊强度由 blurRadius 控制。
- [Brighten 亮度（已弃用）](https://konva-doc-cn.front-end-js.top/docs/filters/brighten)：Konva.Filters.Brighten 已被标记弃用，官方建议改用 Brightness；两者共用 brightness 属性但一个是加法一个是乘法，迁移时必须同时改值。
- [Brightness 亮度](https://konva-doc-cn.front-end-js.top/docs/filters/brightness)：Konva.Filters.Brightness 按乘数调整亮度，中性值为 1，与已弃用的 Brighten 共用 brightness 属性但语义相反——一个是乘法一个是加法。
- [Contrast 对比度](https://konva-doc-cn.front-end-js.top/docs/filters/contrast)：Konva.Filters.Contrast 调整对比度，取值 −100 到 100，内部换算为 ((contrast+100)/100) 的平方；设为 −100 时画面变成纯灰而不是低对比。
- [CSS 原生滤镜](https://konva-doc-cn.front-end-js.top/docs/filters/css-filters)：Konva 10 的 filters 除了接受 Konva.Filters 函数，还接受 blur(6px)、saturate(1.8) 这类 CSS 滤镜字符串。全部为字符串时走浏览器原生实现，比逐像素处理快。
- [Custom Filter 自定义滤镜](https://konva-doc-cn.front-end-js.top/docs/filters/custom-filter)：写自己的 Konva 滤镜：函数签名在 10.6.0 起是 (imageData, pixelRatio)，必须用 pixelRatio 把节点坐标换算成缓存像素，否则效果在高分屏上尺寸减半。
- [Emboss 浮雕](https://konva-doc-cn.front-end-js.top/docs/filters/emboss)：Konva.Filters.Emboss 模拟浮雕效果，由 embossStrength、embossWhiteLevel、embossDirection 与 embossBlend 控制；方向值传错不会报错，会静默回退到 top-left。
- [Enhance 自动增强](https://konva-doc-cn.front-end-js.top/docs/filters/enhance)：Konva.Filters.Enhance 把每个通道拉伸到满量程，对已经占满 0–255 的图片完全没有效果——实测本站三张示例图的改变像素数都是 0。
- [灰度滤镜](https://konva-doc-cn.front-end-js.top/docs/filters/grayscale)：用 Konva.Filters.Grayscale 把图片转为灰度。使用任何滤镜前都必须先调用 cache() 缓存节点。
- [HSL 色相饱和亮度](https://konva-doc-cn.front-end-js.top/docs/filters/hsl)：Konva.Filters.HSL 通过 hue、saturation、luminance 调色；hue 与 saturation 两个属性与 HSV 滤镜共用，同时启用会让色相旋转应用两次。
- [HSV 色相饱和明度](https://konva-doc-cn.front-end-js.top/docs/filters/hsv)：Konva.Filters.HSV 通过 hue、saturation、value 调色；value 提亮时比 HSL 的 luminance 更能保住色彩浓度，但 hue 与 saturation 与 HSL 共用属性。
- [反相滤镜](https://konva-doc-cn.front-end-js.top/docs/filters/invert)：用 Konva.Filters.Invert 反转图片颜色。与其他滤镜一样，需先调用 cache() 缓存节点再通过 filters() 应用。
- [万花筒](https://konva-doc-cn.front-end-js.top/docs/filters/kaleidoscope)：用 Konva.Filters.Kaleidoscope 制作万花筒效果，由 kaleidoscopePower 控制分片数量、kaleidoscopeAngle 控制起始角度。
- [Mask 背景抠除](https://konva-doc-cn.front-end-js.top/docs/filters/mask)：Konva.Filters.Mask 靠采样图片四个角推断背景色再抠掉它；四个角的颜色必须彼此接近，否则滤镜什么也不做且不报错。
- [多个滤镜](https://konva-doc-cn.front-end-js.top/docs/filters/multiple-filters)：给同一个 Konva 节点叠加多个滤镜：filters() 接收一个滤镜数组，按数组顺序依次作用于缓存后的位图。
- [Noise 噪点](https://konva-doc-cn.front-end-js.top/docs/filters/noise)：Konva.Filters.Noise 给每个像素加上对称的随机扰动；噪点在每次滤镜运行时重新生成，所以动画里逐帧重跑会产生闪烁。
- [Pixelate 马赛克](https://konva-doc-cn.front-end-js.top/docs/filters/pixelate)：Konva.Filters.Pixelate 把图像打成方块；pixelSize 的单位是节点坐标而非缓存像素，所以块的视觉大小不随 cache 的 pixelRatio 变化。
- [RGB 单色调](https://konva-doc-cn.front-end-js.top/docs/filters/rgb)：Konva.Filters.RGB 按像素亮度把整张图重染成单一色调，不是在原色上叠加；它与 RGBA 共用 red/green/blue 属性但算法完全不同。
- [RGBA 叠色](https://konva-doc-cn.front-end-js.top/docs/filters/rgba)：用 Konva.Filters.RGBA 调整图片的红、绿、蓝与透明度分量，实现整体调色或半透明叠色效果。
- [Sepia 棕褐色](https://konva-doc-cn.front-end-js.top/docs/filters/sepia)：Konva.Filters.Sepia 用固定矩阵做旧照片的棕褐色调，没有任何配置项，强度不可调；需要半程效果只能自己写自定义滤镜插值。
- [Solarize 曝光反转](https://konva-doc-cn.front-end-js.top/docs/filters/solarize)：Konva.Filters.Solarize 把亮度高于阈值的像素反相；阈值硬编码为 128，没有配置项，需要可调阈值只能自己写自定义滤镜。
- [Threshold 二值化](https://konva-doc-cn.front-end-js.top/docs/filters/threshold)：Konva.Filters.Threshold 把每个通道推到 0 或 255；它的循环步长是 1 而不是 4，所以 alpha 通道也被二值化，半透明边缘会变成硬锯齿。

## 补间动画

- [控制器](https://konva-doc-cn.front-end-js.top/docs/tweens/all-controls)：Konva.Tween 的播放控制：play() 播放、pause() 暂停、reverse() 反向、reset() 重置、finish() 直接结束、seek() 跳到指定时间点。
- [全部补间动画](https://konva-doc-cn.front-end-js.top/docs/tweens/all-easings)：Konva 全部缓动函数一览：Linear、Ease、Back、Elastic、Bounce 与 Strong 各系列的实际运动曲线对比演示。
- [简单的补间动画](https://konva-doc-cn.front-end-js.top/docs/tweens/common-easings)：Konva 常用缓动函数：EaseIn 由慢到快、EaseOut 由快到慢、EaseInOut 两头慢中间快，通过 Tween 的 easing 属性设置。
- [复杂补间动画](https://konva-doc-cn.front-end-js.top/docs/tweens/complex-tweening)：把多段 Konva.Tween 用 onFinish 串联，并配合 Konva.Animation 逐帧更新渐变色标——fillLinearGradientColorStops 无法用 Tween 直接过渡。
- [补间动画完成事件](https://konva-doc-cn.front-end-js.top/docs/tweens/finish-event)：用 Konva.Tween 的 onFinish 回调在补间动画结束时执行逻辑，常用于串联多段动画或在动画完成后清理节点。
- [线性缓动](https://konva-doc-cn.front-end-js.top/docs/tweens/linear-easing)：用 Konva.Tween 对节点的数值属性做过渡动画：x、y、rotation、width、height、opacity 等都可以，调用 play() 启动。
- [滤镜效果](https://konva-doc-cn.front-end-js.top/docs/tweens/tween-filter)：用 Konva.Tween 对滤镜参数做过渡动画，本例演示让 blurRadius 在动画过程中变化，实现由清晰到模糊的渐变效果。

## 动画

- [创建自定义动画](https://konva-doc-cn.front-end-js.top/docs/animations/create-an-animation)：用 Konva.Animation 创建自定义逐帧动画：动画函数可拿到 frame 的 time、timeDiff 与 frameRate，据此计算每一帧的状态。
- [移动](https://konva-doc-cn.front-end-js.top/docs/animations/moving)：用 Konva.Animation 让图形沿轨迹移动：在每个动画帧中修改节点的 x、y 坐标，实现平滑的位移动画。
- [旋转](https://konva-doc-cn.front-end-js.top/docs/animations/rotation)：用 Konva.Animation 实现旋转动画：分别演示绕左上角、绕自身中心点与绕外部点旋转，关键在 offset 与 rotation 的配合。
- [缩放](https://konva-doc-cn.front-end-js.top/docs/animations/scaling)：用 Konva.Animation 实现缩放动画：分别演示 x 轴、y 轴单独缩放与以指定边为基准的缩放，通过每帧修改 scale 完成。
- [停止动画](https://konva-doc-cn.front-end-js.top/docs/animations/stop-animation)：用 Konva.Animation 的 stop() 停止动画、start() 重新启动，适合按钮控制或页面不可见时暂停以节省性能。
- [文字动画](https://konva-doc-cn.front-end-js.top/docs/animations/text-animations)：用 Konva.Animation 做打字机与逐字跳动：文字必须按字素切分否则 emoji 会被劈开，改 text() 会触发重新排版，比改坐标贵得多。

## 选择器

- [id 选择器](https://konva-doc-cn.front-end-js.top/docs/selectors/select-by-id)：用 Konva 的 find("#id") 按 id 查找节点，返回数组；只需要一个结果时用 findOne()。适用于舞台、图层、分组与图形。
- [名称选择器](https://konva-doc-cn.front-end-js.top/docs/selectors/select-by-name)：用 Konva 的 find(".name") 按 name 属性查找节点，返回 Konva.Collection 数组，可用其 each() 方法快速遍历。
- [类型选择器](https://konva-doc-cn.front-end-js.top/docs/selectors/select-by-type)：用 Konva 的 find("Circle") 按节点类型查找，返回匹配的 Konva.Collection 数组，适合批量操作同一类图形。

## 数据与序列化

- [序列化的最佳实践](https://konva-doc-cn.front-end-js.top/docs/data-and-serialization/best-practices)：toJSON 只保存属性不保存函数，它是渲染层快照而不是数据模型；把它直接存进数据库等于把业务数据绑死在第三方库的内部格式上。
- [复杂导出](https://konva-doc-cn.front-end-js.top/docs/data-and-serialization/complex-load)：加载包含图片与事件绑定的复杂 Konva 舞台：先用 Konva.Node.create() 还原节点树，再用选择器手动补回图片与事件——二者无法被序列化。
- [导出高清图片](https://konva-doc-cn.front-end-js.top/docs/data-and-serialization/high-quality-export)：toDataURL / toImage / toCanvas / toBlob 的 pixelRatio 默认是 1 而不是设备像素比，导出图在高分屏上天生糊一半；cache() 的默认值却相反。
- [序列化](https://konva-doc-cn.front-end-js.top/docs/data-and-serialization/serialize-a-stage)：用 Konva 的 toJSON() 把舞台序列化为 JSON 字符串，便于存入网络存储或离线数据库。图层、组与图形同样支持序列化。
- [简单导出](https://konva-doc-cn.front-end-js.top/docs/data-and-serialization/simple-load)：用 Konva.Node.create() 反序列化 JSON 字符串还原节点。还原舞台时可传入可选的 container 参数指定挂载容器。
- [舞台 Data URL](https://konva-doc-cn.front-end-js.top/docs/data-and-serialization/stage-data-url)：用 Konva 的 toDataURL() 把舞台导出为 Data URL，可指定 MIME 类型与图片质量。注意画布被跨域图片污染后该方法会失败。

## 性能优化

- [技巧](https://konva-doc-cn.front-end-js.top/docs/performance/all-performance-tips)：Konva 性能优化清单：批量绘制、图层管理、图形缓存、关闭完美绘制、禁用事件监听、描边优化与内存泄漏规避，逐条给出适用场景。
- [防止内存溢出](https://konva-doc-cn.front-end-js.top/docs/performance/avoid-memory-leaks)：避免 Konva 内存泄漏：彻底删除节点用 destroy()，仅临时移出用 remove()。destroy() 之后的节点不可复用，引擎已解除全部引用。
- [批量绘制](https://konva-doc-cn.front-end-js.top/docs/performance/batch-draw)：用 Konva 的 batchDraw() 合并高频重绘：mousemove 每秒可触发数百次，直接调 draw() 会超出浏览器重绘能力导致动画跳帧。
- [关闭 Perfect Drawing](https://konva-doc-cn.front-end-js.top/docs/performance/disable-perfect-draw)：关闭 Konva 的完美绘制：同时设置填充、描边与透明度时，引擎会启用缓冲画布消除交叠处的深色细线，用 perfectDrawEnabled(false) 可省去这层开销。
- [图层管理](https://konva-doc-cn.front-end-js.top/docs/performance/layer-management)：Konva 图层管理是性能优化的首要手段：每个 Layer 对应一个独立的 canvas 元素，把动态内容与静态内容分层可避免整屏重绘。
- [禁用事件监听](https://konva-doc-cn.front-end-js.top/docs/performance/listening-false)：用 listening(false) 把图形移出命中检测区域以提升性能。例如按钮组里只让矩形响应点击，文本不参与命中图绘制。
- [动画优化](https://konva-doc-cn.front-end-js.top/docs/performance/optimize-animation)：优化 Konva 动画：当某一帧没有任何节点状态变化时在动画函数里 return false，Konva 会跳过该帧的图层更新。
- [描边绘制优化](https://konva-doc-cn.front-end-js.top/docs/performance/optimize-strokes)：优化 Konva 描边性能：图形同时有填充与极细描边时，用 strokeHitEnabled(false) 把描边移出命中检测。描边对命中判定关键时不要使用。
- [图形缓存](https://konva-doc-cn.front-end-js.top/docs/performance/shape-caching)：用 Konva 的 cache() 把复杂图形预渲染为位图，显著降低每帧重绘开销。教程实测缓存后绘制性能提升约 4 倍，适用于舞台、图层、分组与图形。
- [形状重绘](https://konva-doc-cn.front-end-js.top/docs/performance/shape-redraw)：用 shape.draw() 只重绘单个节点而非整个图层。注意该图形会画在当前画布之上，若节点位于其他节点下方或设有透明度则不适用。

## 选择与变换

- [选中、缩放与旋转](https://konva-doc-cn.front-end-js.top/docs/select-and-transform/basic-demo)：用 Konva.Transformer 给图形加上可拖拽的控制柄，实现选中、缩放与旋转，并支持 Shift 多选与在空白处拖拽框选。
- [从中心缩放](https://konva-doc-cn.front-end-js.top/docs/select-and-transform/centered-scaling)：Konva Transformer 的 centeredScaling 让图形以自身中心为基准缩放，拖动任一角时向两侧同时伸缩；按住 ALT 可临时切换。
- [逐锚点定制样式](https://konva-doc-cn.front-end-js.top/docs/select-and-transform/complex-styling)：用 Konva Transformer 的 anchorStyleFunc 对每个锚点单独设置外观，可按名称区分旋转把手、四角与四边中点。
- [强制更新控制柄](https://konva-doc-cn.front-end-js.top/docs/select-and-transform/force-update)：Konva Transformer 通过节点的变化事件自动更新控制柄，但感知不到分组内部的深层改动，这时需要手动调用 forceUpdate()。
- [描边不随缩放变粗](https://konva-doc-cn.front-end-js.top/docs/select-and-transform/ignore-stroke)：缩放时描边会跟着变粗。两种解法：在 transformend 里把 scale 折算进 width/height 后复位，或直接设 strokeScaleEnabled 为 false。
- [保持宽高比](https://konva-doc-cn.front-end-js.top/docs/select-and-transform/keep-ratio)：Konva Transformer 的 keepRatio 默认为 true，拖动角锚点时保持宽高比；按住 SHIFT 可临时反转该行为。
- [缩放尺寸限制](https://konva-doc-cn.front-end-js.top/docs/select-and-transform/resize-limits)：用 Konva Transformer 的 boundBoxFunc 限制图形的最大最小尺寸。返回钳制后的包围盒而非直接返回旧框，避免快速拖动时手感发黏。
- [缩放吸附](https://konva-doc-cn.front-end-js.top/docs/select-and-transform/resize-snaps)：Konva Transformer 的 anchorDragBoundFunc 让缩放锚点吸附到网格或参考线。注意 keepRatio 会在其后执行并覆盖吸附结果。
- [缩放文字](https://konva-doc-cn.front-end-js.top/docs/select-and-transform/resize-text)：Konva Transformer 改的是 scale，直接缩放文字会把字形拉变形。正确做法是在 transform 事件里把缩放量折算成 width 并复位 scaleX。
- [旋转吸附](https://konva-doc-cn.front-end-js.top/docs/select-and-transform/rotation-snaps)：用 Konva Transformer 的 rotationSnaps 让旋转吸附到 0、90、180、270 等特定角度，吸附范围由 rotationSnapTolerance 控制。
- [中止变换](https://konva-doc-cn.front-end-js.top/docs/select-and-transform/stop-transform)：用 Konva Transformer 的 stopTransform() 以编程方式结束正在进行的变换。它不会回滚，图形停在中止那一刻的状态。
- [变换事件](https://konva-doc-cn.front-end-js.top/docs/select-and-transform/transform-events)：Konva 的 transformstart、transform、transformend 事件绑在被变换的图形上而非 Transformer 上；transform 高频触发，重活应放到 transformend。
- [自定义控制柄样式](https://konva-doc-cn.front-end-js.top/docs/select-and-transform/transformer-styling)：调整 Konva Transformer 的锚点填充、描边、尺寸、圆角与边框样式，让控制柄与产品风格一致，并适配触屏的点按精度。

## 选型指南

- [Canvas 库怎么选](https://konva-doc-cn.front-end-js.top/docs/guides/best-canvas-library)：按需求维度对比 Konva、Fabric.js、PixiJS、原生 Canvas 与 SVG：交互复杂度、图形数量、渲染后端、包体积与生态，给出可直接套用的选型结论。
- [为什么选择 Konva](https://konva-doc-cn.front-end-js.top/docs/guides/why-konva)：Konva 解决的核心问题：把 Canvas 的一次性绘制变成可持有状态、可响应事件、可独立变换的对象树，以及它相对原生 Canvas、SVG、Fabric.js、PixiJS 的适用边界。

## Node.js 环境

- [在 Node.js 中使用 Konva](https://konva-doc-cn.front-end-js.top/docs/nodejs/nodejs-setup)：Konva 10 的服务端渲染：canvas-backend 与 skia-backend 两个入口、必须同时导入 konva 本体的原因、导出 PNG 到文件，以及容器里中文变方框的成因与解决。

## 升级与迁移

- [从 Fabric.js 迁移](https://konva-doc-cn.front-end-js.top/docs/migration/from-fabric)：Fabric.js 与 Konva 的概念与 API 对照：画布与舞台、对象与节点、内置控制柄与 Transformer、事件名、序列化，以及 Fabric 内置而 Konva 需要自己实现的功能。
- [升级到 Konva 10](https://konva-doc-cn.front-end-js.top/docs/migration/upgrade-to-v10)：从 Konva 8、9 升级到 10 的逐项清单：ESM 与 require 写法、Node 端画布后端、文本定位变化、Brighten 改名，以及 10.x 小版本里容易踩到的行为变化。

## 框架与工程集成

- [在 Next.js 中使用](https://konva-doc-cn.front-end-js.top/docs/integration/nextjs)：Konva 10 与 react-konva 19 在 Next.js App Router 下只需 use client，不必再用 dynamic 关闭 SSR。说明服务端渲染的实际输出、水合不一致与按需加载。
- [在 Nuxt 中使用](https://konva-doc-cn.front-end-js.top/docs/integration/nuxt)：vue-konva 的 v-stage 在 setup 阶段就创建 Konva.Stage，Nuxt 服务端渲染时会报 document is not defined。用 ClientOnly、.client.vue 组件或按路由关闭 SSR 解决。

## 中文环境

- [中文字体加载](https://konva-doc-cn.front-end-js.top/docs/china/chinese-fonts)：中文 Web 字体晚于 Konva.Text 创建时，已有节点的换行与基线不会自动更新。用 document.fonts.load 预加载，或对已有节点强制重排。
- [文字编辑与中文输入法](https://konva-doc-cn.front-end-js.top/docs/china/ime-text-editing)：Konva 文字就地编辑要叠一个 textarea。中文输入法下，确认候选词的回车会被误当成提交；Safari 还需额外判断 keyCode 229。
- [在小程序中使用 Konva](https://konva-doc-cn.front-end-js.top/docs/china/mini-program)：Konva 依赖 DOM 创建画布，不能直接运行在微信小程序的逻辑层。可选方案是 web-view 内嵌 H5、uni-app 与 Taro 的 H5 端，或改用小程序原生 Canvas 2D。
- [移动端画布内存上限](https://konva-doc-cn.front-end-js.top/docs/china/webview-canvas-limits)：iOS 与微信内置浏览器对 canvas 面积和总内存都有上限，超出后画布白屏、导出为空。按 Konva 的图层结构估算占用，并降低 pixelRatio 与图层数。

## 编辑器常用功能

- [复制与粘贴](https://konva-doc-cn.front-end-js.top/docs/editor/clipboard)：Konva 节点的复制粘贴：画布内用 clone，跨页面用 toObject 写入系统剪贴板再 Node.create 还原；Image 节点的图片不会被序列化，粘贴系统图片则读 clipboardData。
- [快捷键](https://konva-doc-cn.front-end-js.top/docs/editor/keyboard-shortcuts)：给 Konva 编辑器加删除、方向键微调、全选、Ctrl/Cmd 组合键：监听位置、焦点管理、跳过输入框与输入法组合输入，以及拦截浏览器默认行为。
- [标尺与参考线](https://konva-doc-cn.front-end-js.top/docs/editor/rulers-and-guides)：给 Konva 画布加随缩放平移更新刻度的标尺，并从标尺拖出参考线、让图形吸附。关键是变换内容图层而不是整个舞台。

## 帮助

- [帮助](https://konva-doc-cn.front-end-js.top/docs/support)：Konva 使用中遇到问题时的求助渠道：StackOverflow 提问、GitHub Issues 报告缺陷、官方路线图与更新日志，以及国内可达的替代渠道。

## 其他

- [Konva.js 中文文档](https://konva-doc-cn.front-end-js.top)：Konva.js 中文文档。Konva 是基于 HTML5 Canvas 的 2D JavaScript 框架，支持图形绘制、事件、拖拽、变换、动画、滤镜与高性能缓存，适用于桌面与移动端的交互式图形应用。
- [关于 Konva](https://konva-doc-cn.front-end-js.top/docs/about)：Konva 的项目背景、版本演进的几个分水岭（10.0 的 ESM 迁移、10.4 的字素排版、10.6 的滤镜尺度修正）、许可证与维护现状，以及本中文站与官方文档的关系。
- [AI 工具与 Konva](https://konva-doc-cn.front-end-js.top/docs/ai-tools)：让 AI 编程助手正确生成 Konva 代码：可直接投喂的 llms.txt 与 llms-full.txt、AI 最常写出的过时 API（get、Collection.each、konva/cmj）与纠正方式。
- [支持 Konva](https://konva-doc-cn.front-end-js.top/docs/donate)：Konva 是 MIT 许可的开源项目，由个人长期维护。本页说明可以通过哪些方式支持它，以及国内开发者和企业更实际的回馈路径。
- [常见问题汇总](https://konva-doc-cn.front-end-js.top/docs/faq)：Konva 高频问题集中解答：图形不显示、点不中、导出图片被污染、中文字体不生效、拖拽卡顿、序列化丢事件等，每条给出排查顺序与对应文档。
- [周边工具](https://konva-doc-cn.front-end-js.top/docs/tools)：Konva 生态工具清单：官方框架绑定 react-konva / vue-konva / svelte-konva、TypeScript 类型、调试与性能分析手段，以及社区常用的配套库。