@ckeditor/ckeditor5-heading

  • Version 41.4.2
  • Published
  • 619 kB
  • 1 dependency
  • GPL-2.0-or-later license

Install

npm i @ckeditor/ckeditor5-heading
yarn add @ckeditor/ckeditor5-heading
pnpm add @ckeditor/ckeditor5-heading

Overview

Headings feature for CKEditor 5.

Index

Classes

class Heading

class Heading extends Plugin {}
  • The headings feature.

    For a detailed overview, check the guide and the .

    This is a "glue" plugin which loads the and .

    module:core/plugin~Plugin

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [typeof HeadingEditing, typeof HeadingUI];

class HeadingButtonsUI

class HeadingButtonsUI extends Plugin {}
  • The HeadingButtonsUI plugin defines a set of UI buttons that can be used instead of the standard drop down component.

    This feature is not enabled by default by the plugin and needs to be installed manually to the editor configuration.

    Plugin introduces button UI elements, which names are same as model property from .

    ClassicEditor
    .create( {
    plugins: [ ..., Heading, Paragraph, HeadingButtonsUI, ParagraphButtonUI ]
    heading: {
    options: [
    { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
    { model: 'heading1', view: 'h2', title: 'Heading 1', class: 'ck-heading_heading1' },
    { model: 'heading2', view: 'h3', title: 'Heading 2', class: 'ck-heading_heading2' },
    { model: 'heading3', view: 'h4', title: 'Heading 3', class: 'ck-heading_heading3' }
    ]
    },
    toolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3' ]
    } )
    .then( ... )
    .catch( ... );

    NOTE: The 'paragraph' button is defined in by the plugin which needs to be loaded manually as well.

    It is possible to use custom icons by providing icon config option in . For the default configuration standard icons are used.

method init

init: () => void;

class HeadingCommand

class HeadingCommand extends Command {}
  • The heading command. It is used by the to apply headings.

constructor

constructor(editor: Editor, modelElements: string[]);
  • Creates an instance of the command.

    Parameter editor

    Editor instance.

    Parameter modelElements

    Names of the element which this command can apply in the model.

property modelElements

readonly modelElements: string[];
  • Set of defined model's elements names that this command support. See .

property value

value: string | false;
  • If the selection starts in a heading (which ) the value is set to the name of that heading model element. It is set to false otherwise.

    Modifiers

    • @readonly

method execute

execute: (options: { value: string }) => void;
  • Executes the command. Applies the heading to the selected blocks or, if the first selected block is a heading already, turns selected headings (of this level only) to paragraphs.

    Parameter

    options.value Name of the element which this command will apply in the model. execute

method refresh

refresh: () => void;

class HeadingEditing

class HeadingEditing extends Plugin {}
  • The headings engine feature. It handles switching between block formats – headings and paragraph. This class represents the engine part of the heading feature. See also . It introduces heading1-headingN commands which allow to convert paragraphs into headings.

constructor

constructor(editor: Editor);

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly [any];

method afterInit

afterInit: () => void;

method init

init: () => void;

class HeadingUI

class HeadingUI extends Plugin {}
  • The headings UI feature. It introduces the headings dropdown.

property pluginName

static readonly pluginName: string;

method init

init: () => void;

class Title

class Title extends Plugin {}
  • The Title plugin.

    It splits the document into Title and Body sections.

property pluginName

static readonly pluginName: string;

property requires

static readonly requires: readonly ['Paragraph'];

method getBody

getBody: (options?: Record<string, unknown>) => string;
  • Returns the body of the document.

    Note that it is not recommended to use this method together with features that insert markers to the data output, like comments or track changes features. If such markers start in the title and end in the body, the result of this method might be incorrect.

    Parameter options

    Additional configuration passed to the conversion process. See .

    Returns

    The body of the document.

method getTitle

getTitle: (options?: Record<string, unknown>) => string;
  • Returns the title of the document. Note that because this plugin does not allow any formatting inside the title element, the output of this method will be a plain text, with no HTML tags.

    It is not recommended to use this method together with features that insert markers to the data output, like comments or track changes features. If such markers start in the title and end in the body, the result of this method might be incorrect.

    Parameter options

    Additional configuration passed to the conversion process. See .

    Returns

    The title of the document.

method init

init: () => void;

Interfaces

interface HeadingConfig

interface HeadingConfig {}
  • The configuration of the heading feature. The option is used by the feature.

    ClassicEditor
    .create( {
    heading: ... // Heading feature config.
    } )
    .then( ... )
    .catch( ... );

    See .

property options

options?: Array<HeadingOption>;
  • The available heading options.

    The default value is:

    const headingConfig = {
    options: [
    { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
    { model: 'heading1', view: 'h2', title: 'Heading 1', class: 'ck-heading_heading1' },
    { model: 'heading2', view: 'h3', title: 'Heading 2', class: 'ck-heading_heading2' },
    { model: 'heading3', view: 'h4', title: 'Heading 3', class: 'ck-heading_heading3' }
    ]
    };

    It defines 3 levels of headings. In the editor model they will use heading1, heading2, and heading3 elements. Their respective view elements (so the elements output by the editor) will be: h2, h3, and h4. This means that if you choose "Heading 1" in the headings dropdown the editor will turn the current block to <heading1> in the model which will result in rendering (and outputting to data) the <h2> element.

    The title and class properties will be used by the headings dropdown to render available options. Usually, the first option in the headings dropdown is the "Paragraph" option, hence it's also defined on the list. However, you don't need to define its view representation because it's handled by the feature (which is required by the feature).

    You can **read more** about configuring heading levels and **see more examples** in the guide.

    Note: In the model you should always start from heading1, regardless of how the headings are represented in the view. That's assumption is used by features like to know which element they should use when applying the first level heading.

    The defined headings are also available as values passed to the 'heading' command under their model names. For example, the below code will apply <heading1> to the current selection:

    editor.execute( 'heading', { value: 'heading1' } );

interface HeadingElementOption

interface HeadingElementOption {}

    property class

    class: string;
    • The class which will be added to the dropdown item representing this option.

    property icon

    icon?: string;
    • Icon used by . It can be omitted when using the default configuration.

    property model

    model:
    | 'heading1'
    | 'heading2'
    | 'heading3'
    | 'heading4'
    | 'heading5'
    | 'heading6';
    • Name of the model element to convert.

    property title

    title: string;
    • The user-readable title of the option.

    property upcastAlso

    upcastAlso?: ArrayOrItem<ViewElementDefinition | MatcherPattern>;
    • An array with all matched elements that the view-to-model conversion should also accept.

    property view

    view: ViewElementDefinition;
    • Definition of a view element to convert from/to.

    interface TitleConfig

    interface TitleConfig {}
    • The configuration of the .

      ClassicEditor
      .create( document.querySelector( '#editor' ), {
      plugins: [ Title, ... ],
      title: {
      placeholder: 'My custom placeholder for the title'
      },
      placeholder: 'My custom placeholder for the body'
      } )
      .then( ... )
      .catch( ... );

      See .

    property placeholder

    placeholder?: string;
    • Defines a custom value of the placeholder for the title field.

      Read more in .

    Type Aliases

    type HeadingOption

    type HeadingOption =
    | HeadingElementOption
    | HeadingParagraphOption
    | HeadingCustomElementOption;
    • Heading option descriptor.

    Package Files (8)

    Dependencies (1)

    Dev Dependencies (0)

    No dev dependencies.

    Peer Dependencies (0)

    No peer dependencies.

    Badge

    To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

    You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@ckeditor/ckeditor5-heading.

    • Markdown
      [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@ckeditor/ckeditor5-heading)
    • HTML
      <a href="https://www.jsdocs.io/package/@ckeditor/ckeditor5-heading"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>