8
0

imageresize.js 6.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module image/imageresize
  7. */
  8. import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
  9. import ImageResizeButtons from './imageresize/imageresizebuttons';
  10. import ImageResizeEditing from './imageresize/imageresizeediting';
  11. import ImageResizeHandles from './imageresize/imageresizehandles';
  12. import '../theme/imageresize.css';
  13. /**
  14. * The image resize plugin.
  15. *
  16. * It adds a possibility to resize each image using handles.
  17. *
  18. * @extends module:core/plugin~Plugin
  19. */
  20. export default class ImageResize extends Plugin {
  21. /**
  22. * @inheritDoc
  23. */
  24. static get requires() {
  25. return [ ImageResizeEditing, ImageResizeHandles, ImageResizeButtons ];
  26. }
  27. /**
  28. * @inheritDoc
  29. */
  30. static get pluginName() {
  31. return 'ImageResize';
  32. }
  33. }
  34. /**
  35. * The available options are `'px'` or `'%'`.
  36. *
  37. * Determines the size unit applied to the resized image.
  38. *
  39. * ClassicEditor
  40. * .create( editorElement, {
  41. * image: {
  42. * resizeUnit: 'px'
  43. * }
  44. * } )
  45. * .then( ... )
  46. * .catch( ... );
  47. *
  48. *
  49. * This option is used by the {@link module:image/imageresize~ImageResize} feature.
  50. *
  51. * @default '%'
  52. * @member {String} module:image/image~ImageConfig#resizeUnit
  53. */
  54. /**
  55. * The image resize options.
  56. *
  57. * Each option should have at least these two properties:
  58. *
  59. * * name: The name of the UI component registered in the global
  60. * {@link module:core/editor/editorui~EditorUI#componentFactory component factory} of the editor,
  61. * representing the button a user can click to change the size of an image,
  62. * * value: An actual image width applied when a user clicks the mentioned button
  63. * ({@link module:image/imageresize/imageresizecommand~ImageResizeCommand} gets executed).
  64. * The value property is combined with the {@link module:image/image~ImageConfig#resizeUnit `config.image.resizeUnit`} (`%` by default).
  65. * For instance: `value: '50'` and `resizeUnit: '%'` will render as `'50%'` in the UI.
  66. *
  67. * **Resetting the image size**
  68. *
  69. * If you want to set an option that will reset image to its original size, you need to pass a `null` value
  70. * to one of the options. The `:original` token is not mandatory, you can call it anything you wish, but it must reflect
  71. * in the standalone buttons configuration for the image toolbar.
  72. *
  73. * ClassicEditor
  74. * .create( editorElement, {
  75. * image: {
  76. * resizeUnit: "%",
  77. * resizeOptions: [ {
  78. * name: 'imageResize:original',
  79. * value: null
  80. * },
  81. * {
  82. * name: 'imageResize:50',
  83. * value: '50'
  84. * },
  85. * {
  86. * name: 'imageResize:75',
  87. * value: '75'
  88. * } ]
  89. * }
  90. * } )
  91. * .then( ... )
  92. * .catch( ... );
  93. *
  94. * **Resizing images using a dropdown**
  95. *
  96. * With resize options defined, you can decide whether you want to display them as a dropdown or as standalone buttons.
  97. * For the dropdown, you need to pass only the `imageResize` token to the
  98. {@link module:image/image~ImageConfig#toolbar `config.image.toolbar`}. The dropdown contains all defined options by default:
  99. *
  100. * ClassicEditor
  101. * .create( editorElement, {
  102. * image: {
  103. * resizeUnit: "%",
  104. * resizeOptions: [ {
  105. * name: 'imageResize:original',
  106. * value: null
  107. * },
  108. * {
  109. * name: 'imageResize:50',
  110. * value: '50'
  111. * },
  112. * {
  113. * name: 'imageResize:75',
  114. * value: '75'
  115. * } ],
  116. * toolbar: [ 'imageResize', ... ],
  117. * }
  118. * } )
  119. * .then( ... )
  120. * .catch( ... );
  121. *
  122. * **Resizing images using individual buttons**
  123. *
  124. * If you want to have separate buttons for {@link module:image/imageresize/imageresizebuttons~ImageResizeOption each option},
  125. * pass their names to the {@link module:image/image~ImageConfig#toolbar `config.image.toolbar`} instead. Please keep in mind
  126. * that this time **you must define the additional
  127. * {@link module:image/imageresize/imageresizebuttons~ImageResizeOption `icon` property}**:
  128. *
  129. * ClassicEditor
  130. * .create( editorElement, {
  131. * image: {
  132. * resizeUnit: "%",
  133. * resizeOptions: [ {
  134. * name: 'imageResize:original',
  135. * value: null,
  136. * icon: 'original'
  137. * },
  138. * {
  139. * name: 'imageResize:25',
  140. * value: '25',
  141. * icon: 'small'
  142. * },
  143. * {
  144. * name: 'imageResize:50',
  145. * value: '50',
  146. * icon: 'medium'
  147. * },
  148. * {
  149. * name: 'imageResize:75',
  150. * value: '75',
  151. * icon: 'large'
  152. * } ],
  153. * toolbar: [ 'imageResize:25', 'imageResize:50', 'imageResize:75', 'imageResize:original', ... ],
  154. * }
  155. * } )
  156. * .then( ... )
  157. * .catch( ... );
  158. *
  159. * **Customizing resize button labels**
  160. *
  161. * You can set your own label for each resize button. To do that, add the `label` property like in the example below.
  162. *
  163. * * When using the **dropdown**, the labels are displayed on the list of all options when you open the dropdown.
  164. * * When using **standalone buttons**, the labels will are displayed as tooltips when a user hovers over the button.
  165. *
  166. * ClassicEditor
  167. * .create( editorElement, {
  168. * image: {
  169. * resizeUnit: "%",
  170. * resizeOptions: [ {
  171. * name: 'imageResize:original',
  172. * value: null,
  173. * label: 'Original size'
  174. * // Note: add the "icon" property if you're configuring a standalone button.
  175. * },
  176. * {
  177. * name: 'imageResize:50',
  178. * value: '50',
  179. * label: 'Medium size'
  180. * // Note: add the "icon" property if you're configuring a standalone button.
  181. * },
  182. * {
  183. * name: 'imageResize:75',
  184. * value: '75',
  185. * label: 'Large size'
  186. * // Note: add the "icon" property if you're configuring a standalone button.
  187. * } ]
  188. * }
  189. * } )
  190. * .then( ... )
  191. * .catch( ... );
  192. *
  193. * **Default value**
  194. *
  195. * The following configuration is used by default:
  196. *
  197. * resizeOptions = [
  198. * {
  199. * name: 'imageResize:original',
  200. * value: null,
  201. * icon: 'original'
  202. * },
  203. * {
  204. * name: 'imageResize:25',
  205. * value: '25',
  206. * icon: 'small'
  207. * },
  208. * {
  209. * name: 'imageResize:50',
  210. * value: '50',
  211. * icon: 'medium'
  212. * },
  213. * {
  214. * name: 'imageResize:75',
  215. * value: '75',
  216. * icon: 'large'
  217. * }
  218. * ];
  219. *
  220. * @member {Array.<module:image/imageresize/imageresizebuttons~ImageResizeOption>} module:image/image~ImageConfig#resizeOptions
  221. */