widget.js 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476
  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 widget/widget
  7. */
  8. import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
  9. import MouseObserver from '@ckeditor/ckeditor5-engine/src/view/observer/mouseobserver';
  10. import { getLabel, isWidget, WIDGET_SELECTED_CLASS_NAME } from './utils';
  11. import { getCode, keyCodes, parseKeystroke } from '@ckeditor/ckeditor5-utils/src/keyboard';
  12. import env from '@ckeditor/ckeditor5-utils/src/env';
  13. import '../theme/widget.css';
  14. const selectAllKeystrokeCode = parseKeystroke( 'Ctrl+A' );
  15. /**
  16. * The widget plugin. It enables base support for widgets.
  17. *
  18. * See {@glink api/widget package page} for more details and documentation.
  19. *
  20. * This plugin enables multiple behaviors required by widgets:
  21. *
  22. * * The model to view selection converter for the editing pipeline (it handles widget custom selection rendering).
  23. * If a converted selection wraps around a widget element, that selection is marked as
  24. * {@link module:engine/view/selection~Selection#isFake fake}. Additionally, the `ck-widget_selected` CSS class
  25. * is added to indicate that widget has been selected.
  26. * * The mouse and keyboard events handling on and around widget elements.
  27. *
  28. * @extends module:core/plugin~Plugin
  29. */
  30. export default class Widget extends Plugin {
  31. /**
  32. * @inheritDoc
  33. */
  34. static get pluginName() {
  35. return 'Widget';
  36. }
  37. /**
  38. * @inheritDoc
  39. */
  40. init() {
  41. const view = this.editor.editing.view;
  42. const viewDocument = view.document;
  43. /**
  44. * Holds previously selected widgets.
  45. *
  46. * @private
  47. * @type {Set.<module:engine/view/element~Element>}
  48. */
  49. this._previouslySelected = new Set();
  50. // Model to view selection converter.
  51. // Converts selection placed over widget element to fake selection
  52. this.editor.editing.downcastDispatcher.on( 'selection', ( evt, data, conversionApi ) => {
  53. // Remove selected class from previously selected widgets.
  54. this._clearPreviouslySelectedWidgets( conversionApi.writer );
  55. const viewWriter = conversionApi.writer;
  56. const viewSelection = viewWriter.document.selection;
  57. const selectedElement = viewSelection.getSelectedElement();
  58. let lastMarked = null;
  59. for ( const range of viewSelection.getRanges() ) {
  60. for ( const value of range ) {
  61. const node = value.item;
  62. // Do not mark nested widgets in selected one. See: #57.
  63. if ( isWidget( node ) && !isChild( node, lastMarked ) ) {
  64. viewWriter.addClass( WIDGET_SELECTED_CLASS_NAME, node );
  65. this._previouslySelected.add( node );
  66. lastMarked = node;
  67. // Check if widget is a single element selected.
  68. if ( node == selectedElement ) {
  69. viewWriter.setSelection( viewSelection.getRanges(), { fake: true, label: getLabel( selectedElement ) } );
  70. }
  71. }
  72. }
  73. }
  74. }, { priority: 'low' } );
  75. // If mouse down is pressed on widget - create selection over whole widget.
  76. view.addObserver( MouseObserver );
  77. this.listenTo( viewDocument, 'mousedown', ( ...args ) => this._onMousedown( ...args ) );
  78. // Handle custom keydown behaviour.
  79. this.listenTo( viewDocument, 'keydown', ( ...args ) => this._onKeydown( ...args ), { priority: 'high' } );
  80. // Handle custom delete behaviour.
  81. this.listenTo( viewDocument, 'delete', ( evt, data ) => {
  82. if ( this._handleDelete( data.direction == 'forward' ) ) {
  83. data.preventDefault();
  84. evt.stop();
  85. }
  86. }, { priority: 'high' } );
  87. }
  88. /**
  89. * Handles {@link module:engine/view/document~Document#event:mousedown mousedown} events on widget elements.
  90. *
  91. * @private
  92. * @param {module:utils/eventinfo~EventInfo} eventInfo
  93. * @param {module:engine/view/observer/domeventdata~DomEventData} domEventData
  94. */
  95. _onMousedown( eventInfo, domEventData ) {
  96. const editor = this.editor;
  97. const view = editor.editing.view;
  98. const viewDocument = view.document;
  99. let element = domEventData.target;
  100. // Do nothing for single or double click inside nested editable.
  101. if ( isInsideNestedEditable( element ) ) {
  102. // But at least triple click inside nested editable causes broken selection in Safari.
  103. // For such event, we select the entire nested editable element.
  104. // See: https://github.com/ckeditor/ckeditor5/issues/1463.
  105. if ( env.isSafari && domEventData.domEvent.detail >= 3 ) {
  106. const mapper = editor.editing.mapper;
  107. const modelElement = mapper.toModelElement( element );
  108. this.editor.model.change( writer => {
  109. domEventData.preventDefault();
  110. writer.setSelection( modelElement, 'in' );
  111. } );
  112. }
  113. return;
  114. }
  115. // If target is not a widget element - check if one of the ancestors is.
  116. if ( !isWidget( element ) ) {
  117. element = element.findAncestor( isWidget );
  118. if ( !element ) {
  119. return;
  120. }
  121. }
  122. domEventData.preventDefault();
  123. // Focus editor if is not focused already.
  124. if ( !viewDocument.isFocused ) {
  125. view.focus();
  126. }
  127. // Create model selection over widget.
  128. const modelElement = editor.editing.mapper.toModelElement( element );
  129. this._setSelectionOverElement( modelElement );
  130. }
  131. /**
  132. * Handles {@link module:engine/view/document~Document#event:keydown keydown} events.
  133. *
  134. * @private
  135. * @param {module:utils/eventinfo~EventInfo} eventInfo
  136. * @param {module:engine/view/observer/domeventdata~DomEventData} domEventData
  137. */
  138. _onKeydown( eventInfo, domEventData ) {
  139. const keyCode = domEventData.keyCode;
  140. const isLtrContent = this.editor.locale.contentLanguageDirection === 'ltr';
  141. const isForward = keyCode == keyCodes.arrowdown || keyCode == keyCodes[ isLtrContent ? 'arrowright' : 'arrowleft' ];
  142. let wasHandled = false;
  143. // Checks if the keys were handled and then prevents the default event behaviour and stops
  144. // the propagation.
  145. if ( isArrowKeyCode( keyCode ) ) {
  146. wasHandled = this._handleArrowKeys( isForward );
  147. } else if ( isSelectAllKeyCode( domEventData ) ) {
  148. wasHandled = this._selectAllNestedEditableContent() || this._selectAllContent();
  149. } else if ( keyCode === keyCodes.enter ) {
  150. wasHandled = this._handleEnterKey( domEventData.shiftKey );
  151. }
  152. if ( wasHandled ) {
  153. domEventData.preventDefault();
  154. eventInfo.stop();
  155. }
  156. }
  157. /**
  158. * Handles delete keys: backspace and delete.
  159. *
  160. * @private
  161. * @param {Boolean} isForward Set to true if delete was performed in forward direction.
  162. * @returns {Boolean|undefined} Returns `true` if keys were handled correctly.
  163. */
  164. _handleDelete( isForward ) {
  165. // Do nothing when the read only mode is enabled.
  166. if ( this.editor.isReadOnly ) {
  167. return;
  168. }
  169. const modelDocument = this.editor.model.document;
  170. const modelSelection = modelDocument.selection;
  171. // Do nothing on non-collapsed selection.
  172. if ( !modelSelection.isCollapsed ) {
  173. return;
  174. }
  175. const objectElement = this._getObjectElementNextToSelection( isForward );
  176. if ( objectElement ) {
  177. this.editor.model.change( writer => {
  178. let previousNode = modelSelection.anchor.parent;
  179. // Remove previous element if empty.
  180. while ( previousNode.isEmpty ) {
  181. const nodeToRemove = previousNode;
  182. previousNode = nodeToRemove.parent;
  183. writer.remove( nodeToRemove );
  184. }
  185. this._setSelectionOverElement( objectElement );
  186. } );
  187. return true;
  188. }
  189. }
  190. /**
  191. * Handles arrow keys.
  192. *
  193. * @private
  194. * @param {Boolean} isForward Set to true if arrow key should be handled in forward direction.
  195. * @returns {Boolean|undefined} Returns `true` if keys were handled correctly.
  196. */
  197. _handleArrowKeys( isForward ) {
  198. const model = this.editor.model;
  199. const schema = model.schema;
  200. const modelDocument = model.document;
  201. const modelSelection = modelDocument.selection;
  202. const objectElement = modelSelection.getSelectedElement();
  203. // If object element is selected.
  204. if ( objectElement && schema.isObject( objectElement ) ) {
  205. const position = isForward ? modelSelection.getLastPosition() : modelSelection.getFirstPosition();
  206. const newRange = schema.getNearestSelectionRange( position, isForward ? 'forward' : 'backward' );
  207. if ( newRange ) {
  208. model.change( writer => {
  209. writer.setSelection( newRange );
  210. } );
  211. }
  212. return true;
  213. }
  214. // If selection is next to object element.
  215. // Return if not collapsed.
  216. if ( !modelSelection.isCollapsed ) {
  217. return;
  218. }
  219. const objectElement2 = this._getObjectElementNextToSelection( isForward );
  220. if ( !!objectElement2 && schema.isObject( objectElement2 ) ) {
  221. this._setSelectionOverElement( objectElement2 );
  222. return true;
  223. }
  224. }
  225. /**
  226. * Handles the enter key, giving users and access to positions in the editable directly before
  227. * (<kbd>Shift</kbd>+<kbd>Enter</kbd>) or after (<kbd>Enter</kbd>) the selected widget.
  228. * It improves the UX, mainly when the widget is the first or last child of the root editable
  229. * and there's no other way to type after or before it.
  230. *
  231. * @private
  232. * @param {Boolean} isBackwards Set to true if the new paragraph is to be inserted before
  233. * the selected widget (<kbd>Shift</kbd>+<kbd>Enter</kbd>).
  234. * @returns {Boolean|undefined} Returns `true` if keys were handled correctly.
  235. */
  236. _handleEnterKey( isBackwards ) {
  237. const model = this.editor.model;
  238. const modelSelection = model.document.selection;
  239. const selectedElement = modelSelection.getSelectedElement();
  240. if ( shouldInsertParagraph( selectedElement, model.schema ) ) {
  241. model.change( writer => {
  242. let position = writer.createPositionAt( selectedElement, isBackwards ? 'before' : 'after' );
  243. const paragraph = writer.createElement( 'paragraph' );
  244. // Split the parent when inside a block element.
  245. // https://github.com/ckeditor/ckeditor5/issues/1529
  246. if ( model.schema.isBlock( selectedElement.parent ) ) {
  247. const paragraphLimit = model.schema.findAllowedParent( position, paragraph );
  248. position = writer.split( position, paragraphLimit ).position;
  249. }
  250. writer.insert( paragraph, position );
  251. writer.setSelection( paragraph, 'in' );
  252. } );
  253. return true;
  254. }
  255. }
  256. /**
  257. * Extends the {@link module:engine/model/selection~Selection document's selection} to span the entire
  258. * content of the nested editable if already anchored in one.
  259. *
  260. * See: {@link module:engine/model/schema~Schema#getLimitElement}.
  261. *
  262. * @private
  263. */
  264. _selectAllNestedEditableContent() {
  265. const model = this.editor.model;
  266. const documentSelection = model.document.selection;
  267. const limitElement = model.schema.getLimitElement( documentSelection );
  268. if ( documentSelection.getFirstRange().root == limitElement ) {
  269. return false;
  270. }
  271. model.change( writer => {
  272. writer.setSelection( writer.createRangeIn( limitElement ) );
  273. } );
  274. return true;
  275. }
  276. /**
  277. * Handles <kbd>CTRL + A</kbd> when widget is selected.
  278. *
  279. * @private
  280. * @returns {Boolean} Returns true if widget was selected and selecting all was handled by this method.
  281. */
  282. _selectAllContent() {
  283. const model = this.editor.model;
  284. const editing = this.editor.editing;
  285. const view = editing.view;
  286. const viewDocument = view.document;
  287. const viewSelection = viewDocument.selection;
  288. const selectedElement = viewSelection.getSelectedElement();
  289. // Only widget is selected.
  290. // https://github.com/ckeditor/ckeditor5-widget/issues/23
  291. if ( selectedElement && isWidget( selectedElement ) ) {
  292. const widgetParent = editing.mapper.toModelElement( selectedElement.parent );
  293. model.change( writer => {
  294. writer.setSelection( writer.createRangeIn( widgetParent ) );
  295. } );
  296. return true;
  297. }
  298. return false;
  299. }
  300. /**
  301. * Sets {@link module:engine/model/selection~Selection document's selection} over given element.
  302. *
  303. * @private
  304. * @param {module:engine/model/element~Element} element
  305. */
  306. _setSelectionOverElement( element ) {
  307. this.editor.model.change( writer => {
  308. writer.setSelection( writer.createRangeOn( element ) );
  309. } );
  310. }
  311. /**
  312. * Checks if {@link module:engine/model/element~Element element} placed next to the current
  313. * {@link module:engine/model/selection~Selection model selection} exists and is marked in
  314. * {@link module:engine/model/schema~Schema schema} as `object`.
  315. *
  316. * @private
  317. * @param {Boolean} forward Direction of checking.
  318. * @returns {module:engine/model/element~Element|null}
  319. */
  320. _getObjectElementNextToSelection( forward ) {
  321. const model = this.editor.model;
  322. const schema = model.schema;
  323. const modelSelection = model.document.selection;
  324. // Clone current selection to use it as a probe. We must leave default selection as it is so it can return
  325. // to its current state after undo.
  326. const probe = model.createSelection( modelSelection );
  327. model.modifySelection( probe, { direction: forward ? 'forward' : 'backward' } );
  328. const objectElement = forward ? probe.focus.nodeBefore : probe.focus.nodeAfter;
  329. if ( !!objectElement && schema.isObject( objectElement ) ) {
  330. return objectElement;
  331. }
  332. return null;
  333. }
  334. /**
  335. * Removes CSS class from previously selected widgets.
  336. *
  337. * @private
  338. * @param {module:engine/view/downcastwriter~DowncastWriter} writer
  339. */
  340. _clearPreviouslySelectedWidgets( writer ) {
  341. for ( const widget of this._previouslySelected ) {
  342. writer.removeClass( WIDGET_SELECTED_CLASS_NAME, widget );
  343. }
  344. this._previouslySelected.clear();
  345. }
  346. }
  347. // Returns 'true' if provided key code represents one of the arrow keys.
  348. //
  349. // @param {Number} keyCode
  350. // @returns {Boolean}
  351. function isArrowKeyCode( keyCode ) {
  352. return keyCode == keyCodes.arrowright ||
  353. keyCode == keyCodes.arrowleft ||
  354. keyCode == keyCodes.arrowup ||
  355. keyCode == keyCodes.arrowdown;
  356. }
  357. // Returns 'true' if provided (DOM) key event data corresponds with the Ctrl+A keystroke.
  358. //
  359. // @param {module:engine/view/observer/keyobserver~KeyEventData} domEventData
  360. // @returns {Boolean}
  361. function isSelectAllKeyCode( domEventData ) {
  362. return getCode( domEventData ) == selectAllKeystrokeCode;
  363. }
  364. // Returns `true` when element is a nested editable or is placed inside one.
  365. //
  366. // @param {module:engine/view/element~Element}
  367. // @returns {Boolean}
  368. function isInsideNestedEditable( element ) {
  369. while ( element ) {
  370. if ( element.is( 'editableElement' ) && !element.is( 'rootElement' ) ) {
  371. return true;
  372. }
  373. // Click on nested widget should select it.
  374. if ( isWidget( element ) ) {
  375. return false;
  376. }
  377. element = element.parent;
  378. }
  379. return false;
  380. }
  381. // Checks whether the specified `element` is a child of the `parent` element.
  382. //
  383. // @param {module:engine/view/element~Element} element An element to check.
  384. // @param {module:engine/view/element~Element|null} parent A parent for the element.
  385. // @returns {Boolean}
  386. function isChild( element, parent ) {
  387. if ( !parent ) {
  388. return false;
  389. }
  390. return Array.from( element.getAncestors() ).includes( parent );
  391. }
  392. // Checks if enter key should insert paragraph. This should be done only on elements of type object (excluding inline objects).
  393. //
  394. // @param {module:engine/model/element~Element} element And element to check.
  395. // @param {module:engine/model/schema~Schema} schema
  396. function shouldInsertParagraph( element, schema ) {
  397. return element && schema.isObject( element ) && !schema.isInline( element );
  398. }