Range API

.. index:: K.range

K.range(mixed)

创建或选取KRange对象，KRange是原生Range的封装，包含大部分W3C Range接口，此外还有包含KRange和原生Range之间的转换功能。

• 参数:

  • document|range mixed: document或原生range

• 返回: KRange对象

示例:

range = K.range(document);
range = K.range(originalRange);

.. index:: START_TO_START

K.START_TO_START

调用 :ref:`KRange.compareBoundaryPoints` 时使用。

.. index:: START_TO_END

K.START_TO_END

调用 :ref:`KRange.compareBoundaryPoints` 时使用。

.. index:: END_TO_END

K.END_TO_END

调用 :ref:`KRange.compareBoundaryPoints` 时使用。

.. index:: END_TO_START

K.END_TO_START

调用 :ref:`KRange.compareBoundaryPoints` 时使用。

.. index:: startContainer

startContainer

range的开始节点。

.. index:: startOffset

startOffset

range的开始节点位置。

.. index:: endContainer

endContainer

range的结束节点。

.. index:: endOffset

endOffset

range的结束节点的位置。

.. index:: collapsed

collapsed

range的折叠状态，当range处于折叠状态时true，否则false。。

.. index:: commonAncestor

commonAncestor()

取得KRange的共同祖先。

• 参数: 无
• 返回: Element

示例:

var range = K.range(document);
var element = range.commonAncestor();

.. index:: setStart

setStart(node , offset)

设置KRange的开始节点和位置。

• 参数:

  • Node node: 任意节点
  • Int offset: 位置

• 返回: KRange

示例:

var range = K.range(document);
range.setStart(document.body, 1);

.. index:: setEnd

setEnd(node , offset)

设置KRange的结束节点和位置。

• 参数:

  • Node node: 任意节点
  • Int offset: 位置

• 返回: KRange

示例:

var range = K.range(document);
range.setEnd(document.body, 2);

.. index:: setStartBefore

setStartBefore(node)

将Node的开始位置设置成Range的开始位置。

• 参数:

  • Node node: 任意节点

• 返回: KRange

示例:

var range = K.range(document);
range.setStartBefore(K('div#id')[0]);

.. index:: setStartAfter

setStartAfter(node)

将Node的结束位置设置成Range的开始位置。

• 参数:

  • Node node: 任意节点

• 返回: KRange

示例:

var range = K.range(document);
range.setStartAfter(K('div#id')[0]);

.. index:: setEndBefore

setEndBefore(node)

将Node的开始位置设置成Range的结束位置。

• 参数:

  • Node node: 任意节点

• 返回: KRange

示例:

var range = K.range(document);
range.setEndBefore(K('div#id')[0]);

.. index:: setEndAfter

setEndAfter(node)

将Node的结束位置设置成Range的结束位置。

• 参数:

  • Node node: 任意节点

• 返回: KRange

示例:

var range = K.range(document);
range.setEndAfter(K('div#id')[0]);

.. index:: selectNode

selectNode(node)

将Node的开始位置和结束位置分别设置成Range的开始位置和结束位置。

• 参数:

  • Node node: 任意节点

• 返回: KRange

示例:

var range = K.range(document);
range.selectNode(K('div#id')[0]);

.. index:: selectNodeContents

selectNodeContents(node)

将Node的子节点的开始位置和结束位置分别设置成Range的开始位置和结束位置。对于文本节点和无结束符的元素，相当于使用selectNode。

• 参数:

  • Node node: 任意节点

• 返回: KRange

示例:

var range = K.range(document);
range.selectNodeContents(K('div#id')[0]);

.. index:: collapse

collapse(toStart)

折叠KRange，当toStart为true时向前折叠，false时向后折叠。

• 参数:

  • Boolean toStart: 折叠方向

• 返回: KRange

示例:

var range = K.range(document);
range.selectNodeContents(K('div#id')[0]);
range.collapse(true);

.. index:: compareBoundaryPoints

compareBoundaryPoints(how , range)

根据how参数比较2个range的边界。

• 参数:

  • Int how: 位置信息，可设置K.START_TO_START、K.START_TO_END、K.END_TO_END、K.END_TO_START。
  • Range range: 目标Range

• 返回: 当this range在目标range的左侧时返回-1，在目标range的右侧时返回1，相同时返回0。

how参数的方向规则：

• K.START_TO_START：比较目标range的开始位置和this range的开始位置。
• K.START_TO_END：比较目标range的开始位置和this range的结束位置。
• K.END_TO_END：比较目标range的结束位置和this range的结束位置。
• K.END_TO_START：比较目标range的结束位置和this range的开始位置。

示例:

var range1 = K.range(document);
range1.selectNode(K('div#id')[0]);
var range2 = K.range(document);
range2.selectNode(K('div#id p')[0]);
var cmp = range1.compareBoundaryPoints(K.START_TO_START, range2);

.. index:: cloneRange

cloneRange()

复制KRange。

• 参数: 无
• 返回: KRange

示例:

var range = K.range(document);
range.selectNodeContents(K('div#id')[0]);
var newRange = range.cloneRange();

.. index:: toString

toString()

返回KRange的文本内容。

• 参数: 无
• 返回: String

示例:

var range = K.range(document);
range.selectNodeContents(K('div#id')[0]);
var text = range.toString();

.. index:: cloneContents

cloneContents()

复制并返回KRange的内容。

• 参数: 无
• 返回: documentFragment

示例:

var range = K.range(document);
range.selectNodeContents(K('div#id')[0]);
var fragment = range.cloneContents();

.. index:: deleteContents

deleteContents()

删除KRange的内容。

• 参数: 无
• 返回: KRange

示例:

var range = K.range(document);
range.selectNodeContents(K('div#id')[0]);
range.deleteContents();

.. index:: extractContents

extractContents()

删除并返回KRange的内容。

• 参数: 无
• 返回: documentFragment

示例:

var range = K.range(document);
range.selectNodeContents(K('div#id')[0]);
var fragment = range.extractContents();

.. index:: insertNode

insertNode(node)

将指定Node插入到KRange的开始位置。

• 参数:

  • Node node: 任意Node或documentFragment

• 返回: KRange

示例:

var range = K.range(document);
range.selectNodeContents(K('#id1')[0]);
range.insertNode(K('#id2')[0]);

.. index:: surroundContents

surroundContents(node)

用指定Node围住KRange的内容。

• 参数:

  • Element node: 任意节点

• 返回: KRange

示例:

var range = K.range(document);
range.selectNodeContents(K('#id1')[0]);
range.surroundContents(K('#id2')[0]);

.. index:: isControl

isControl()

判断当前KRange是否可选择的Contral Range。

• 参数: 无
• 返回: Boolean

示例:

var range = K.range(document);
range.selectNodeContents(K('#id1')[0]);
var bool = range.isControl();

.. index:: get

get([hasControlRange])

将KRange转换成原生Range并返回。

• 参数:

  • Boolean hasControlRange: 是否包含Contral Range

• 返回: Range

示例:

var range = K.range(document);
range.selectNodeContents(K('#id1')[0]);
var originalRange = range.get();

.. index:: html

html()

返回KRange内容的HTML。

• 参数: 无
• 返回: HTML string

示例:

var range = K.range(document);
range.selectNodeContents(K('#id1')[0]);
var html = range.html();

.. index:: down

down()

降低range的位置。

• 参数: 无
• 返回: KRange

示例:

// <p><strong><span>123</span>abc</strong>def</p>
range.setStart(strong, 1);
range.down();
console.log(range.startContainer, range.startOffset); // print "abc", 0

.. index:: up

up()

提高range的位置。

• 参数: 无
• 返回: KRange

示例:

// <p><strong><span>123</span>abc</strong>def</p>
range.setStart("abc", 0);
range.up();
console.log(range.startContainer, range.startOffset); // print strong, 1

.. index:: enlarge

enlarge()

扩大边界。

• 参数: 无
• 返回: KRange

示例:

// <p><strong><span>123</span>abc</strong>def</p>
range.setStart("123", 0);
range.setEnd("abc", 3);
range.enlarge();
console.log(range.startContainer, range.startOffset); // print p, 0
console.log(range.endContainer, range.endOffset); // print p, 1

.. index:: shrink

shrink()

缩小边界。

• 参数: 无
• 返回: KRange

示例:

// <p><strong><span>123</span>abc</strong></p>
range.setStart(p, 0);
range.setEnd(p, 1);
range.shrink();
console.log(range.startContainer, range.startOffset); // print "123", 0
console.log(range.endContainer, range.endOffset); // print "abc", 3

.. index:: createBookmark

createBookmark([serialize])

创建bookmark。(插入临时节点标记位置)

• 参数:

  • Boolean serialize: bookmark类型，默认值为false，true时bookmark包含临时节点的ID，false时bookmark包含临时节点的Element。

• 返回: bookmark

示例:

bookmark = range.createBookmark();
console.log(bookmark); // print {start: startNode, end: endNode}

bookmark = range.createBookmark(true);
console.log(bookmark); // print {start: 'start_node_id', end: 'end_node_id'}

.. index:: moveToBookmark

moveToBookmark(bookmark)

根据bookmark重新设置range。

• 参数:

  • Object bookmark: 通过 :ref:`KRange.createBookmark` 得到的bookmark

• 返回: KRange

示例:

bookmark = range.createBookmark();
// 在这里执行一些改变DOM的处理
// ...
range.moveToBookmark(bookmark);