imageresize.js 5.7 KB

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