瀏覽代碼

Expand documentation for new block filler methods.

Maciej Gołaszewski 6 年之前
父節點
當前提交
2ee5b90678
共有 2 個文件被更改,包括 47 次插入22 次删除
  1. 12 11
      packages/ckeditor5-engine/src/view/domconverter.js
  2. 35 11
      packages/ckeditor5-engine/src/view/filler.js

+ 12 - 11
packages/ckeditor5-engine/src/view/domconverter.js

@@ -50,7 +50,7 @@ export default class DomConverter {
 	 * Creates DOM converter.
 	 *
 	 * @param {Object} options Object with configuration options.
-	 * @param {Function} [options.blockFillerMode='br'] Block filler mode - either 'br' or 'nbsp'.
+	 * @param {module:engine/view/filler~blockFillerMode} [options.blockFillerMode='br'] Type of a block filler w
 	 */
 	constructor( options = {} ) {
 		// Using WeakMap prevent memory leaks: when the converter will be destroyed all referenced between View and DOM
@@ -64,6 +64,7 @@ export default class DomConverter {
 		// I've been here. Seen stuff. Afraid of code now.
 
 		/**
+		 * The mode of a block filler used by DOM converter.
 		 *
 		 * @readonly
 		 * @member {String} module:engine/view/domconverter~DomConverter#blockFillerMode
@@ -71,16 +72,6 @@ export default class DomConverter {
 		this.blockFillerMode = options.blockFillerMode || 'br';
 
 		/**
-		 * Block {@link module:engine/view/filler filler} creator, which is used to create all block fillers during the
-		 * view to DOM conversion and to recognize block fillers during the DOM to view conversion.
-		 *
-		 * @readonly
-		 * @private
-		 * @member {Function} module:engine/view/domconverter~DomConverter#blockFiller
-		 */
-		this._blockFiller = this.blockFillerMode == 'br' ? BR_FILLER : NBSP_FILLER;
-
-		/**
 		 * Tag names of DOM `Element`s which are considered pre-formatted elements.
 		 *
 		 * @readonly
@@ -97,6 +88,16 @@ export default class DomConverter {
 		this.blockElements = [ 'p', 'div', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6' ];
 
 		/**
+		 * Block {@link module:engine/view/filler filler} creator, which is used to create all block fillers during the
+		 * view to DOM conversion and to recognize block fillers during the DOM to view conversion.
+		 *
+		 * @readonly
+		 * @private
+		 * @member {Function} module:engine/view/domconverter~DomConverter#_blockFiller
+		 */
+		this._blockFiller = this.blockFillerMode == 'br' ? BR_FILLER : NBSP_FILLER;
+
+		/**
 		 * DOM to View mapping.
 		 *
 		 * @private

+ 35 - 11
packages/ckeditor5-engine/src/view/filler.js

@@ -130,18 +130,14 @@ export function getDataWithoutFiller( domText ) {
  *		isBlockFiller( brFillerInstance, 'br' ); // true
  *		isBlockFiller( brFillerInstance, 'nbsp' ); // false
  *
+ * **Note:**: For 'nbsp' mode the method also checks context of a node so it cannot be a detached node.
+ *
  * @param {Node} domNode DOM node to check.
- * @param {String} blockFillerMode Block filler mode - either 'br' or 'nbsp'.
+ * @param {module:engine/view/filler~blockFillerMode} mode Mode of a block filler.
  * @returns {Boolean} True if a node is considered a block filler for given mode.
  */
-export function isBlockFiller( domNode, blockFillerMode ) {
-	if ( blockFillerMode == 'br' ) {
-		return domNode.isEqualNode( BR_FILLER_REF );
-	}
-
-	const isNBSP = isText( domNode ) && domNode.data == '\u00A0';
-
-	return isNBSP && hasBlockParent( domNode ) && domNode.parentNode.childNodes.length === 1;
+export function isBlockFiller( domNode, mode ) {
+	return mode == 'br' ? domNode.isEqualNode( BR_FILLER_REF ) : isNbspFillerFiller( domNode );
 }
 
 /**
@@ -170,10 +166,38 @@ function jumpOverInlineFiller( evt, data ) {
 	}
 }
 
+// Checks if given node is a nbsp block filler.
+//
+// A   is a block filler only if it is a single child of a block element.
+//
+// @param {Node} domNode DOM node.
+// @returns {Boolean}
+function isNbspFillerFiller( domNode ) {
+	const isNBSP = isText( domNode ) && domNode.data == '\u00A0';
+
+	return isNBSP && hasBlockParent( domNode ) && domNode.parentNode.childNodes.length === 1;
+}
+
+// Name of DOM nodes that are considered a block.
 const blockElements = [ 'p', 'div', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6' ];
 
-function hasBlockParent( node ) {
-	const parent = node.parentNode;
+// Checks if domNode has block parent.
+//
+// @param {Node} domNode DOM node.
+// @returns {Boolean}
+function hasBlockParent( domNode ) {
+	const parent = domNode.parentNode;
 
 	return parent && parent.tagName && blockElements.includes( parent.tagName.toLowerCase() );
 }
+
+/**
+ * Enum representing type of the block filler.
+ *
+ * Possible values:
+ *
+ * * `br` - for `<br>` block filler used in editing view,
+ * * `nbsp` - for `&nbsp;` block fillers used in the data.
+ *
+ * @typedef {String} module:engine/view/filler~blockFillerMode
+ */