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