8
0
Marek Lewandowski 6 лет назад
Родитель
Сommit
f66c72eea3

+ 18 - 8
packages/ckeditor5-widget/src/resizecontext.js

@@ -19,11 +19,18 @@ const WIDTH_ATTRIBUTE_NAME = 'width';
  */
 export default class ResizeContext {
 	constructor( options ) {
-		// HTMLElement??? - @todo seems to be not needed.
-		// this.resizeHost = null;
-		// view/UiElement
+		/**
+		 * View to a wrapper containing all the resizer-related views.
+		 *
+		 * @member {module:engine/view/uielement~UIElement}
+		 */
 		this.resizeWrapperElement = null;
-		// view/Element
+
+		/**
+		 * View of a widget associated with the resizer.
+		 *
+		 * @member {module:engine/view/element~Element}
+		 */
 		this.widgetWrapperElement = null;
 
 		this.resizeStrategy = new ResizerTopBound( this, options );
@@ -69,6 +76,7 @@ export default class ResizeContext {
 	}
 
 	/**
+	 * Method to be called to attach a resizer to a given widget element.
 	 *
 	 * @param {module:engine/view/element~Element} widgetElement Widget's wrapper.
 	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer
@@ -259,9 +267,10 @@ export default class ResizeContext {
 
 	/**
 	 *
-	 * @param {module:@ckeditor/ckeditor5-core/src/editor/editor~Editor} editor
-	 * @param {module:@ckeditor/ckeditor5-engine/src/view/element~Element} widgetWrapperElement
-	 * @returns {module:@ckeditor/ckeditor5-engine/src/model/element~Element|undefined}
+	 * @param {module:core/editor/editor~Editor} editor
+	 * @param {module:engine/view/element~Element} widgetWrapperElement
+	 * @returns {module:engine/model/element~Element|undefined}
+	 * @protected
 	 */
 	_getModel( editor, widgetWrapperElement ) {
 		return editor.editing.mapper.toModelElement( widgetWrapperElement );
@@ -275,9 +284,9 @@ export default class ResizeContext {
 	}
 
 	/**
-	 * @private
 	 * @param {String} resizerPosition Expected resizer position like `"top-left"`, `"bottom-right"`.
 	 * @returns {String} A prefixed HTML class name for the resizer element
+	 * @private
 	 */
 	_getResizerClass( resizerPosition ) {
 		return `ck-widget__resizer-${ resizerPosition }`;
@@ -303,6 +312,7 @@ export default class ResizeContext {
 	/**
 	 * @param {String} position Like `"top-left"`.
 	 * @returns {String} Inverted `position`.
+	 * @protected
 	 */
 	_invertPosition( position ) {
 		const parts = position.split( '-' );

+ 46 - 3
packages/ckeditor5-widget/src/widgetresizer.js

@@ -29,7 +29,9 @@ const WIDTH_ATTRIBUTE_NAME = 'width';
  */
 
 /**
- * The base class for widget features. This type provides a common API for reusable features of widgets.
+ * Widget resize feature plugin.
+ *
+ * Use the {@link #apply} method to create resizer for a provided widget.
  */
 export default class WidgetResizer extends Plugin {
 	/**
@@ -120,10 +122,51 @@ export default class WidgetResizer extends Plugin {
 	}
 
 	/**
+	 * Method that applies a resizer to a given `widgetElement`.
+	 *
+	 * ```js
+	 * conversion.for( 'editingDowncast' ).elementToElement( {
+	 *		model: 'image',
+	 *		view: ( modelElement, viewWriter ) => {
+	 *			const widget = toImageWidget( createImageViewElement( viewWriter ), viewWriter, t( 'image widget' ) );
+	 *
+	 *			editor.plugins.get( 'WidgetResizer' ).apply( widget, viewWriter );
+	 *
+	 *			return widget;
+	 *		}
+	 *	} );
+	 * ```
+	 *
+	 * You can use the `options` parameter to customize the behavior of the resizer:
+	 *
+	 * ```js
+	 * conversion.for( 'editingDowncast' ).elementToElement( {
+	 *			model: 'image',
+	 *			view: ( modelElement, viewWriter ) => {
+	 *				const widget = toImageWidget( createImageViewElement( viewWriter ), viewWriter, t( 'image widget' ) );
+	 *
+	 *				editor.plugins.get( 'WidgetResizer' ).apply( widget, viewWriter, {
+	 *					getResizeHost( wrapper ) {
+	 *						return wrapper.querySelector( 'img' );
+	 *					},
+	 *					getAspectRatio( resizeHost ) {
+	 *						return resizeHost.naturalWidth / resizeHost.naturalHeight;
+	 *					},
+	 *					isCentered( context ) {
+	 *						const imageStyle = context._getModel( editor, context.widgetWrapperElement ).getAttribute( 'imageStyle' );
+	 *
+	 *						return !imageStyle || imageStyle == 'full';
+	 *					}
+	 *				} );
+	 *
+	 *				return widget;
+	 *			}
+	 *		} );
+	 * ```
+	 *
 	 * @param {module:engine/view/containerelement~ContainerElement} widgetElement
 	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer
 	 * @param {module:widget/widgetresizer~ResizerOptions} [options] Resizer options.
-	 * @memberof WidgetResizer
 	 */
 	apply( widgetElement, writer, options ) {
 		const context = new ResizeContext2( options );
@@ -154,7 +197,7 @@ export default class WidgetResizer extends Plugin {
 
 	_registerSchema() {
 		const editor = this.editor;
-		// Allow bold attribute on text nodes.
+
 		editor.model.schema.extend( 'image', {
 			allowAttributes: WIDTH_ATTRIBUTE_NAME
 		} );