Преглед на файлове

Review image commands documentation.

Maciej Gołaszewski преди 7 години
родител
ревизия
bf2eb85381

+ 14 - 0
packages/ckeditor5-image/docs/features/image.md

@@ -40,6 +40,20 @@ You can see the demo of an editor with the base image feature enabled below:
 	The base image feature, unlike in CKEditor 4, does not support any user interface for inserting or managing images. Its sole purpose is to lay ground for other plugins (mentioned above) to build the target user experience. This pattern (composition of atomic features) is common for CKEditor 5 and allows the developers to build their own customized experience by implementing specific subfeatures differently.
 </info-box>
 
+### Image insert command
+
+The Image feature introduces the {@link module:image/image/imageinsertcommand~ImageInsertCommand `'imageInsert'` command. The command accepts one parameter `source` of image to insert:
+
+```js
+editor.execute( 'imageInsert', { source: '/path/to/image.jpg' } );
+```
+
+The command can be also used to insert multiple images at once by passing an array of sources:
+
+```js
+editor.execute( 'imageInsert', { source: [ '/path/to/image1.jpg', '/path/to/image2.jpg' ] } );
+```
+
 ## Image contextual toolbar
 
 The {@link module:image/imagetoolbar~ImageToolbar} plugin introduces a contextual toolbar for images. The toolbar appears when an image is selected and can be configured to contain any buttons you want. Usually, these will be image-related options such as the text alternative (which is introduced by the base image plugin) button and [image styles buttons](#image-styles).

+ 16 - 0
packages/ckeditor5-image/src/image/imageinsertcommand.js

@@ -13,6 +13,22 @@ import { insertImage, isImageAllowed } from './utils';
 /**
  * Insert image command.
  *
+ * The command is registered by the {@link module:image/image/imageediting~ImageEditing} as `'imageInsert'`.
+ *
+ * To insert image at the current selection (according to the {@link module:widget/utils~findOptimalInsertionPosition} algorithm),
+ * execute the command and specify the image source:
+ *
+ *		editor.execute( 'imageInsert', { source: 'http://url.to.the/image' } );
+ *
+ *	It is also possible to insert multiple images at once:
+ *
+ *		editor.execute( 'imageInsert', {
+ *			source:  [
+ *				'path/to/image.jpg',
+ *				'path/to/other-image.jpg'
+ *			]
+ *		} );
+ *
  * @extends module:core/command~Command
  */
 export default class ImageInsertCommand extends Command {

+ 22 - 0
packages/ckeditor5-image/src/imageupload/imageuploadcommand.js

@@ -14,6 +14,28 @@ import { insertImage, isImageAllowed } from '../image/utils';
 /**
  * Image upload command.
  *
+ * The command is registered by the {@link module:image/imageupload/imageuploadediting~ImageUploadEditing} as `'imageUpload'`.
+ *
+ * To upload an image at the current selection (according to the {@link module:widget/utils~findOptimalInsertionPosition} algorithm),
+ * execute the command and pass the native image file instance:
+ *
+ *		this.listenTo( editor.editing.view.document, 'clipboardInput', ( evt, data ) => {
+ *			// Assuming that only images were pasted:
+ *			const images = Array.from( data.dataTransfer.files );
+ *
+ *			// Upload the first image:
+ *			editor.execute( 'imageUpload', { file: images[ 0 ] } );
+ *		} );
+ *
+ *	It is also possible to insert multiple images at once:
+ *
+ *		editor.execute( 'imageUpload', {
+ *			file: [
+ *				file1,
+ *				file2
+ *			]
+ *		} );
+ *
  * @extends module:core/command~Command
  */
 export default class ImageUploadCommand extends Command {