UNPKG

4.49 kBTypeScriptView Raw
1/**
2 * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
3 * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
4 */
5/**
6 * @module image/imageupload/imageuploadediting
7 */
8import { Plugin, type Editor } from 'ckeditor5/src/core.js';
9import { type Element, type Writer, type DataTransfer } from 'ckeditor5/src/engine.js';
10import { Notification } from 'ckeditor5/src/ui.js';
11import { ClipboardPipeline } from 'ckeditor5/src/clipboard.js';
12import { FileRepository, type UploadResponse, type FileLoader } from 'ckeditor5/src/upload.js';
13import ImageUtils from '../imageutils.js';
14/**
15 * The editing part of the image upload feature. It registers the `'uploadImage'` command
16 * and the `imageUpload` command as an aliased name.
17 *
18 * When an image is uploaded, it fires the {@link ~ImageUploadEditing#event:uploadComplete `uploadComplete`} event
19 * that allows adding custom attributes to the {@link module:engine/model/element~Element image element}.
20 */
21export default class ImageUploadEditing extends Plugin {
22 /**
23 * @inheritDoc
24 */
25 static get requires(): readonly [typeof FileRepository, typeof Notification, typeof ClipboardPipeline, typeof ImageUtils];
26 static get pluginName(): "ImageUploadEditing";
27 /**
28 * An internal mapping of {@link module:upload/filerepository~FileLoader#id file loader UIDs} and
29 * model elements during the upload.
30 *
31 * Model element of the uploaded image can change, for instance, when {@link module:image/image/imagetypecommand~ImageTypeCommand}
32 * is executed as a result of adding caption or changing image style. As a result, the upload logic must keep track of the model
33 * element (reference) and resolve the upload for the correct model element (instead of the one that landed in the `$graveyard`
34 * after image type changed).
35 */
36 private readonly _uploadImageElements;
37 /**
38 * @inheritDoc
39 */
40 constructor(editor: Editor);
41 /**
42 * @inheritDoc
43 */
44 init(): void;
45 /**
46 * @inheritDoc
47 */
48 afterInit(): void;
49 /**
50 * Reads and uploads an image.
51 *
52 * The image is read from the disk and as a Base64-encoded string it is set temporarily to
53 * `image[src]`. When the image is successfully uploaded, the temporary data is replaced with the target
54 * image's URL (the URL to the uploaded image on the server).
55 */
56 protected _readAndUpload(loader: FileLoader): Promise<void>;
57 /**
58 * Creates the `srcset` attribute based on a given file upload response and sets it as an attribute to a specific image element.
59 *
60 * @param data Data object from which `srcset` will be created.
61 * @param image The image element on which the `srcset` attribute will be set.
62 */
63 protected _parseAndSetSrcsetAttributeOnImage(data: Record<string, unknown>, image: Element, writer: Writer): void;
64}
65/**
66 * Returns `true` if non-empty `text/html` is included in the data transfer.
67 */
68export declare function isHtmlIncluded(dataTransfer: DataTransfer): boolean;
69/**
70 * An event fired when an image is uploaded. You can hook into this event to provide
71 * custom attributes to the {@link module:engine/model/element~Element image element} based on the data from
72 * the server.
73 *
74 * ```ts
75 * const imageUploadEditing = editor.plugins.get( 'ImageUploadEditing' );
76 *
77 * imageUploadEditing.on( 'uploadComplete', ( evt, { data, imageElement } ) => {
78 * editor.model.change( writer => {
79 * writer.setAttribute( 'someAttribute', 'foo', imageElement );
80 * } );
81 * } );
82 * ```
83 *
84 * You can also stop the default handler that sets the `src` and `srcset` attributes
85 * if you want to provide custom values for these attributes.
86 *
87 * ```ts
88 * imageUploadEditing.on( 'uploadComplete', ( evt, { data, imageElement } ) => {
89 * evt.stop();
90 * } );
91 * ```
92 *
93 * **Note**: This event is fired by the {@link module:image/imageupload/imageuploadediting~ImageUploadEditing} plugin.
94 *
95 * @eventName ~ImageUploadEditing#uploadComplete
96 * @param data The `uploadComplete` event data.
97 */
98export type ImageUploadCompleteEvent = {
99 name: 'uploadComplete';
100 args: [data: ImageUploadCompleteData];
101};
102export type ImageUploadCompleteData = {
103 /**
104 * The data coming from the upload adapter.
105 */
106 data: UploadResponse;
107 /**
108 * The model {@link module:engine/model/element~Element image element} that can be customized.
109 */
110 imageElement: Element;
111};
112
\No newline at end of file