UNPKG

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