ソースを参照

Introduce UpcastConversionData for element-to-element conversion. Fix docs.

Maciej Gołaszewski 5 年 前
コミット
2e7c739d99
1 ファイル変更29 行追加15 行削除
  1. 29 15
      packages/ckeditor5-engine/src/conversion/upcastdispatcher.js

+ 29 - 15
packages/ckeditor5-engine/src/conversion/upcastdispatcher.js

@@ -78,8 +78,8 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  *
  *		// Convert all elements which have no custom converter into a paragraph (autoparagraphing).
  *		editor.data.upcastDispatcher.on( 'element', ( evt, data, conversionApi ) => {
- *			// Try to consume the element.
- *			if ( conversionApi.consumable.consume( data.viewItem, { name: data.viewItem.name } ) ) {
+ *			// Check if element can be converted.
+ *			if ( !conversionApi.consumable.test( data.viewItem, { name: data.viewItem.name } ) ) {
  *				// When element is already consumed by higher priority converters then do nothing.
  *				return;
  *			}
@@ -92,6 +92,9 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  *				return;
  *			}
  *
+ *			// Consume the inserted element.
+ *			conversionApi.consumable.consume( data.viewItem, { name: data.viewItem.name } ) );
+ *
  *			// Convert children to paragraph.
  *			const { modelRange } = conversionApi.convertChildren( data.viewItem,  paragraph ) );
  *
@@ -478,14 +481,9 @@ export default class UpcastDispatcher {
 	 * all elements conversion or to conversion of specific elements.
 	 *
 	 * @event element
-	 * @param {Object} data Conversion data. Keep in mind that this object is shared by reference between all
-	 * callbacks that will be called. This means that callbacks can override values if needed, and those values will
-	 * be available in other callbacks.
-	 * @param {module:engine/view/item~Item} data.viewItem Converted item.
-	 * @param {module:engine/model/position~Position} data.modelCursor Position where a converter should start changes.
-	 * Change this value for the next converter to tell where the conversion should continue.
-	 * @param {module:engine/model/range~Range} data.modelRange The current state of conversion result. Every change to
-	 * converted element should be reflected by setting or modifying this property.
+	 * @param {module:engine/conversion/upcastdispatcher~UpcastConversionData} data Conversion data. Keep in mind that this object is shared
+	 * by reference between all callbacks that will be called. This means that callbacks can override values if needed, and those values
+	 * will be available in other callbacks.
 	 * @param {module:engine/conversion/upcastdispatcher~UpcastConversionApi} conversionApi Conversion utilities to be used by callback.
 	 */
 
@@ -638,7 +636,8 @@ function createContextTree( contextDefinition, writer ) {
  *			return;
  *		}
  *
- * The split result is saved and {@link #updateConversionResult} should be used to update conversion data.
+ * The split result is saved and {@link #updateConversionResult} should be used to update
+ * {@link module:engine/conversion/upcastdispatcher~UpcastConversionData conversion data}.
  *
  * @method #safeInsert
  * @param {module:engine/model/node~Node} node Node to insert.
@@ -647,12 +646,11 @@ function createContextTree( contextDefinition, writer ) {
  */
 
 /**
- * Updates the conversion result and sets proper `data.modelRange` and next `data.modelCursor` after the conversion.
+ * Updates the conversion result and sets proper {@link module:engine/conversion/upcastdispatcher~UpcastConversionData#modelRange} and
+ * next {@link module:engine/conversion/upcastdispatcher~UpcastConversionData#modelCursor} after the conversion.
  * Used together with {@link #safeInsert} enables you to easily convert elements without worrying if the node was split
  * during its children conversion.
  *
- * If given `element` was not split, an array with single element is returned.
- *
  * Example of a usage in a converter code:
  *
  *		const myElement = conversionApi.writer.createElement( 'myElement' );
@@ -668,7 +666,8 @@ function createContextTree( contextDefinition, writer ) {
  *
  * @method #updateConversionResult
  * @param {module:engine/model/element~Element} element
- * @returns {Array.<module:engine/model/element~Element>}
+ * @param {module:engine/conversion/upcastdispatcher~UpcastConversionData} data Conversion data.
+ * @param {module:engine/conversion/upcastdispatcher~UpcastConversionApi} conversionApi Conversion utilities to be used by callback.
  */
 
 /**
@@ -775,3 +774,18 @@ function createContextTree( contextDefinition, writer ) {
  *
  * @member {module:engine/model/writer~Writer} #writer
  */
+
+/**
+ * Conversion data.
+ *
+ * **Note:** Keep in mind that this object is shared by reference between all conversion callbacks that will be called.
+ * This means that callbacks can override values if needed, and those values will be available in other callbacks.
+ *
+ * @typedef {Object} module:engine/conversion/upcastdispatcher~UpcastConversionData
+ *
+ * @property {module:engine/view/item~Item} viewItem Converted item.
+ * @property {module:engine/model/position~Position} modelCursor Position where a converter should start changes.
+ * Change this value for the next converter to tell where the conversion should continue.
+ * @property {module:engine/model/range~Range} [modelRange] The current state of conversion result. Every change to
+ * converted element should be reflected by setting or modifying this property.
+ */