CKEditor5——Utils(工具类理解)

如果对CK5的代码有所理解的话，大概知道，CK5有一个非常重要的工具包项目，这个工具包非常重要，提供了CK5最基础的一些功能。比如：集合类Collection、事件类EmitterMixin、观察者类ObservableMixin等。

今天我们暂缓学些以上的类，主要理解一个关于dom的类,那就是Position和Rect类，因为这两个类是CK5中弹出balloon工具条的基础类。我会一点点学习它的原理。

我们首先看看Rect类

Rect属性

这个类的属性很简单，主要有六个：

top、left、bottom、right、width、height。看到了吧，实际上这个类就是一个dom元素在文档中的位置信息和大小信息，只不过这里有一个关系要记住：

bottom = top + height;

right = left + width;

Rect方法

首先我们需要理解的就是构造器

constructor(source) 

这个构造器看似简单，实际上它接受的参数可以是多种类型，比如：

HTMLElement | Range | Window | ClientRect | DOMRect | Rect | Object

它可以接受基本dom元素，nativeRange，window对象，ClientRect对象，DomRect类型，它自身类型，甚至Object都可以。

这里需要注意的是：

默认情况下，HTML 元素的矩形包括其 CSS 边框和滚动条（如果有），窗口的矩形也包括滚动条。

在这种情况下，我们需要获得出去边框和滚动条的Rect，那就用到了下面的方法。

为了说明这个构造器的source的多样性，我还是用官网的代码来说明一下：

// Rect of an HTMLElement. 这里是常用dom元素
const rectA = new Rect( document.body );

// Rect of a DOM Range. 这里是选择区域的第一个Range
const rectB = new Rect( document.getSelection().getRangeAt( 0 ) );

// Rect of a window (web browser viewport). window对象
const rectC = new Rect( window );

// Rect out of an object.  实际上就是Object对象
const rectD = new Rect( { top: 0, right: 10, bottom: 10, left: 0, width: 10, height: 10 } );

// Rect out of another Rect instance. 
const rectE = new Rect( rectD );

// Rect out of a ClientRect. //这里是一个ClientRect对象
const rectF = new Rect( document.body.getClientRects().item( 0 ) );

excludeScrollbarsAndBorders() → Rect

调用这个方法就可以返回一个不包含边框和滚动条的Rect对象。

另外Rect这个类还包含一些比较有用的方法，简单说一下：

clone() ： Rect

复制一个对象

contains(anotherRect) : Boolean

当前对象是否包含参数对象

getArea() : Number

返回Rect的面积

getIntersection(anotherRect) : Rect

 返回两个Rect的交集

getIntersectionArea(anotherRect) : Number

返回两个Rect的交集的面积

getVisible() : Rect | null

返回一个新的矩形，原始矩形的一部分，它实际上对用户可见，例如由父元素 rect 裁剪的原始 rect，其在 CSS 中设置了溢出而不是“可见”。如果没有这样的可见矩形，即当矩形被一个或多个祖先限制时，则返回 null。

isEqual(anotherRect) : Boolean

两个Rect是否相等

moveBy(x , y ) : Rect

将Rect移动一定的偏移量

moveTo(x , y) : Rect

移动Rect，使其左上角落在所需的 [ x, y ] 位置。

此外还有两个静态方法

getBoundingRect( rects ) → Rect | null

返回一个包含所有给定矩形的边界矩形

getDomRangeRects( range ) → Array.<Rect>

返回给定原生 DOM 范围的矩形数组。

不难看出，这个类实际上就是对dom中的矩形元素框的一个抽象，所以理解这些方法对于我们后续学习Position是很有帮助的。

Position属性

Position的基本属性也不错，主要有三个: name、top、left。这三个属性主要用于命名和定位。另外一个属性config，这个属性暂时不是很重要

Position方法

最重要的是构造器方法

constructor( [ positioningFunction ], [ options ] = { options.elementRect, options.targetRect, options.viewportRect, [options.positionedElementAncestor] } )

在构造器中，有两个参数，第一个是定位函数，另一个是可选的配置对象，我们先看看这个配置对象Options

Options属性

这个对象主要有六个属性：

element : Element

实际就是需要定位的元素

target : HTMLElement | Range | Window | ClientRect | DOMRect | Rect | Object | function

这个是定位元素相对的目标元素

positions : Array<positioningFunction>>

一组定位使用的函数

这三个元素值最重要的属性，另外三个属性可以查看官网的说明

这里再介绍一下定位函数

positioningFunction

定位函数有三个重要的参数

第一个是targetRect,第二个是elementRect,第三个是viewportRect

// This simple position will place the element directly under the target, in the middle:
//
//	    [ Target ]
//	+-----------------+
//	|     Element     |
//	+-----------------+
//
const position = ( targetRect, elementRect, [ viewportRect ] ) => ( {
	top: targetRect.bottom,
	left: targetRect.left + targetRect.width / 2 - elementRect.width / 2,
	name: 'bottomMiddle',

	// Note: The config is optional.
	config: {
		zIndex: '999'
	}
} );

这个函数会返回一个对象，对象包含以下属性

top、left、name、config。实际上就是定位需要的属性以及为定位命一个名字。

有了Position元素后，这个类中还有一个关键的方法：

getOptimalPosition()

这个方法会返回一个定位最优的位置来帮助我们的定位元素进行定位。有了这些功能，我们大概就能理解balloon工具条的原理啦。如果希望我分析源码的话，欢迎留言。