heading.js 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114
  1. /**
  2. * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /**
  6. * @module heading/heading
  7. */
  8. import HeadingEditing from './headingediting';
  9. import HeadingUI from './headingui';
  10. import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
  11. import '../theme/heading.css';
  12. /**
  13. * The headings feature.
  14. *
  15. * It loads the {@link module:heading/headingediting~HeadingEditing heading editing feature}
  16. * and {@link module:heading/headingui~HeadingUI heading UI feature}.
  17. *
  18. * For a detailed overview, check the {@glink features/headings Headings feature documentation}.
  19. *
  20. * @extends module:core/plugin~Plugin
  21. */
  22. export default class Heading extends Plugin {
  23. /**
  24. * @inheritDoc
  25. */
  26. static get requires() {
  27. return [ HeadingEditing, HeadingUI ];
  28. }
  29. /**
  30. * @inheritDoc
  31. */
  32. static get pluginName() {
  33. return 'Heading';
  34. }
  35. }
  36. /**
  37. * The configuration of the heading feature. Introduced by the {@link module:heading/headingediting~HeadingEditing} feature.
  38. *
  39. * Read more in {@link module:heading/heading~HeadingConfig}.
  40. *
  41. * @member {module:heading/heading~HeadingConfig} module:core/editor/editorconfig~EditorConfig#heading
  42. */
  43. /**
  44. * The configuration of the heading feature.
  45. * The option is used by the {@link module:heading/headingediting~HeadingEditing} feature.
  46. *
  47. * ClassicEditor
  48. * .create( {
  49. * heading: ... // Heading feature config.
  50. * } )
  51. * .then( ... )
  52. * .catch( ... );
  53. *
  54. * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
  55. *
  56. * @interface HeadingConfig
  57. */
  58. /**
  59. * The available heading options.
  60. *
  61. * The default value is:
  62. *
  63. * const headingConfig = {
  64. * options: [
  65. * { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
  66. * { model: 'heading1', view: 'h2', title: 'Heading 1', class: 'ck-heading_heading1' },
  67. * { model: 'heading2', view: 'h3', title: 'Heading 2', class: 'ck-heading_heading2' },
  68. * { model: 'heading3', view: 'h4', title: 'Heading 3', class: 'ck-heading_heading3' }
  69. * ]
  70. * };
  71. *
  72. * It defines 3 levels of headings. In the editor model they will use `heading1`, `heading2`, and `heading3` elements.
  73. * Their respective view elements (so the elements output by the editor) will be: `h2`, `h3`, and `h4`. This means that
  74. * if you choose "Heading 1" in the headings dropdown the editor will turn the current block to `<heading1>` in the model
  75. * which will result in rendering (and outputting to data) the `<h2>` element.
  76. *
  77. * The `title` and `class` properties will be used by the `headings` dropdown to render available options.
  78. * Usually, the first option in the headings dropdown is the "Paragraph" option, hence it's also defined on the list.
  79. * However, you don't need to define its view representation because it's handled by
  80. * the {@link module:paragraph/paragraph~Paragraph} feature (which is required by
  81. * the {@link module:heading/headingediting~HeadingEditing} feature).
  82. *
  83. * You can **read more** about configuring heading levels and **see more examples** in
  84. * the {@glink features/headings Headings} guide.
  85. *
  86. * Note: In the model you should always start from `heading1`, regardless of how the headings are represented in the view.
  87. * That's assumption is used by features like {@link module:autoformat/autoformat~Autoformat} to know which element
  88. * they should use when applying the first level heading.
  89. *
  90. * The defined headings are also available as values passed to `heading` command under their model names.
  91. * For example, the below code will apply `<heading1>` to the current selection:
  92. *
  93. * editor.execute( 'heading', { value: 'heading1' } );
  94. *
  95. * @member {Array.<module:heading/heading~HeadingOption>} module:heading/heading~HeadingConfig#options
  96. */
  97. /**
  98. * Heading option descriptor.
  99. *
  100. * @typedef {Object} module:heading/heading~HeadingOption
  101. * @property {String} model Name of the model element to convert.
  102. * @property {module:engine/view/elementdefinition~ElementDefinition} view Definition of a view element to convert from/to.
  103. * @property {String} title The user-readable title of the option.
  104. * @property {String} class The class which will be added to the dropdown item representing this option.
  105. */