UNPKG

2.57 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 */
5import type { Editor } from 'ckeditor5/src/core.js';
6import type Autoformat from './autoformat.js';
7/**
8 * The block autoformatting engine. It allows to format various block patterns. For example,
9 * it can be configured to turn a paragraph starting with `*` and followed by a space into a list item.
10 *
11 * The autoformatting operation is integrated with the undo manager,
12 * so the autoformatting step can be undone if the user's intention was not to format the text.
13 *
14 * See the {@link module:autoformat/blockautoformatediting~blockAutoformatEditing `blockAutoformatEditing`} documentation
15 * to learn how to create custom block autoformatters. You can also use
16 * the {@link module:autoformat/autoformat~Autoformat} feature which enables a set of default autoformatters
17 * (lists, headings, bold and italic).
18 *
19 * @module autoformat/blockautoformatediting
20 */
21/**
22 * Creates a listener triggered on {@link module:engine/model/document~Document#event:change:data `change:data`} event in the document.
23 * Calls the callback when inserted text matches the regular expression or the command name
24 * if provided instead of the callback.
25 *
26 * Examples of usage:
27 *
28 * To convert a paragraph into heading 1 when `- ` is typed, using just the command name:
29 *
30 * ```ts
31 * blockAutoformatEditing( editor, plugin, /^\- $/, 'heading1' );
32 * ```
33 *
34 * To convert a paragraph into heading 1 when `- ` is typed, using just the callback:
35 *
36 * ```ts
37 * blockAutoformatEditing( editor, plugin, /^\- $/, ( context ) => {
38 * const { match } = context;
39 * const headingLevel = match[ 1 ].length;
40 *
41 * editor.execute( 'heading', {
42 * formatId: `heading${ headingLevel }`
43 * } );
44 * } );
45 * ```
46 *
47 * @param editor The editor instance.
48 * @param plugin The autoformat plugin instance.
49 * @param pattern The regular expression to execute on just inserted text. The regular expression is tested against the text
50 * from the beginning until the caret position.
51 * @param callbackOrCommand The callback to execute or the command to run when the text is matched.
52 * In case of providing the callback, it receives the following parameter:
53 * * match RegExp.exec() result of matching the pattern to inserted text.
54 */
55export default function blockAutoformatEditing(editor: Editor, plugin: Autoformat, pattern: RegExp, callbackOrCommand: string | ((context: {
56 match: RegExpExecArray;
57}) => unknown)): void;