highlight.js 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193
  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 highlight/highlight
  7. */
  8. import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
  9. import HighlightEditing from './highlightediting';
  10. import HighlightUI from './highlightui';
  11. /**
  12. * The highlight plugin.
  13. *
  14. * For a detailed overview, check the {@glink features/highlight Highlight feature} documentation.
  15. *
  16. * This is a "glue" plugin which loads the {@link module:highlight/highlightediting~HighlightEditing} and
  17. * {@link module:highlight/highlightui~HighlightUI} plugins.
  18. *
  19. * @extends module:core/plugin~Plugin
  20. */
  21. export default class Highlight extends Plugin {
  22. /**
  23. * @inheritDoc
  24. */
  25. static get requires() {
  26. return [ HighlightEditing, HighlightUI ];
  27. }
  28. /**
  29. * @inheritDoc
  30. */
  31. static get pluginName() {
  32. return 'Highlight';
  33. }
  34. }
  35. /**
  36. * The highlight option descriptor. See {@link module:highlight/highlight~HighlightConfig} to learn more.
  37. *
  38. * {
  39. * model: 'pinkMarker',
  40. * class: 'marker-pink',
  41. * title: 'Pink Marker',
  42. * color: 'var(--ck-highlight-marker-pink)',
  43. * type: 'marker'
  44. * }
  45. *
  46. * @typedef {Object} module:highlight/highlight~HighlightOption
  47. * @property {String} title The user-readable title of the option.
  48. * @property {String} model The unique attribute value in the model.
  49. * @property {String} color The CSS `var()` used for the highlighter. The color is used in the user interface to represent the highlighter.
  50. * There is a possibility to use the default color format like rgb, hex or hsl, but you need to care about the color of `<mark>`
  51. * by adding CSS classes definition.
  52. * @property {String} class The CSS class used on the `<mark>` element in the view. It should match the `color` setting.
  53. * @property {'marker'|'pen'} type The type of highlighter:
  54. *
  55. * * `'marker'` &ndash; Uses the `color` as the `background-color` style,
  56. * * `'pen'` &ndash; Uses the `color` as the font `color` style.
  57. */
  58. /**
  59. * The configuration of the {@link module:highlight/highlight~Highlight} feature.
  60. *
  61. * Read more in {@link module:highlight/highlight~HighlightConfig}.
  62. *
  63. * @member {module:highlight/highlight~HighlightConfig} module:core/editor/editorconfig~EditorConfig#highlight
  64. */
  65. /**
  66. * The configuration of the {@link module:highlight/highlight~Highlight highlight feature}.
  67. *
  68. * ClassicEditor
  69. * .create( editorElement, {
  70. * highlight: ... // Highlight feature configuration.
  71. * } )
  72. * .then( ... )
  73. * .catch( ... );
  74. *
  75. * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
  76. *
  77. * @interface HighlightConfig
  78. */
  79. /**
  80. * The available highlight options. The default value is:
  81. *
  82. * options: [
  83. * {
  84. * model: 'yellowMarker',
  85. * class: 'marker-yellow',
  86. * title: 'Yellow marker',
  87. * color: 'var(--ck-highlight-marker-yellow)',
  88. * type: 'marker'
  89. * },
  90. * {
  91. * model: 'greenMarker',
  92. * class: 'marker-green',
  93. * title: 'Green marker',
  94. * color: 'var(--ck-highlight-marker-green)',
  95. * type: 'marker'
  96. * },
  97. * {
  98. * model: 'pinkMarker',
  99. * class: 'marker-pink',
  100. * title: 'Pink marker',
  101. * color: 'var(--ck-highlight-marker-pink)',
  102. * type: 'marker'
  103. * },
  104. * {
  105. * model: 'blueMarker',
  106. * class: 'marker-blue',
  107. * title: 'Blue marker',
  108. * color: 'var(--ck-highlight-marker-blue)',
  109. * type: 'marker'
  110. * },
  111. * {
  112. * model: 'redPen',
  113. * class: 'pen-red',
  114. * title: 'Red pen',
  115. * color: 'var(--ck-highlight-pen-red)',
  116. * type: 'pen'
  117. * },
  118. * {
  119. * model: 'greenPen',
  120. * class: 'pen-green',
  121. * title: 'Green pen',
  122. * color: 'var(--ck-highlight-pen-green)',
  123. * type: 'pen'
  124. * }
  125. * ]
  126. *
  127. * There are two types of highlighters available:
  128. *
  129. * * `'marker'` &ndash; Rendered as a `<mark>` element, styled with the `background-color`.
  130. * * `'pen'` &ndash; Rendered as a `<mark>` element, styled with the font `color`.
  131. *
  132. * **Note**: The highlight feature provides a stylesheet with the CSS classes and corresponding colors defined
  133. * as CSS variables.
  134. *
  135. * :root {
  136. * --ck-highlight-marker-yellow: #fdfd77;
  137. * --ck-highlight-marker-green: #63f963;
  138. * --ck-highlight-marker-pink: #fc7999;
  139. * --ck-highlight-marker-blue: #72cdfd;
  140. * --ck-highlight-pen-red: #e91313;
  141. * --ck-highlight-pen-green: #118800;
  142. * }
  143. *
  144. * .marker-yellow { ... }
  145. * .marker-green { ... }
  146. * .marker-pink { ... }
  147. * .marker-blue { ... }
  148. * .pen-red { ... }
  149. * .pen-green { ... }
  150. *
  151. * It is possible to define the `color` property directly as `rgba(R, G, B, A)`,
  152. * `#RRGGBB[AA]` or `hsla(H, S, L, A)`. In such situation, the color will **only** apply to the UI of
  153. * the editor and the `<mark>` elements in the content must be styled by custom classes provided by
  154. * a dedicated stylesheet.
  155. *
  156. * **Note**: It is recommended for the `color` property to correspond to the class in the content
  157. * stylesheet because it represents the highlighter in the user interface of the editor.
  158. *
  159. * ClassicEditor
  160. * .create( editorElement, {
  161. * highlight: {
  162. * options: [
  163. * {
  164. * model: 'pinkMarker',
  165. * class: 'marker-pink',
  166. * title: 'Pink Marker',
  167. * color: 'var(--ck-highlight-marker-pink)',
  168. * type: 'marker'
  169. * },
  170. * {
  171. * model: 'redPen',
  172. * class: 'pen-red',
  173. * title: 'Red Pen',
  174. * color: 'var(--ck-highlight-pen-red)',
  175. * type: 'pen'
  176. * },
  177. * ]
  178. * }
  179. * } )
  180. * .then( ... )
  181. * .catch( ... );
  182. *
  183. * @member {Array.<module:highlight/highlight~HighlightOption>} module:highlight/highlight~HighlightConfig#options
  184. */