CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

Matcher (engine/view)

@ckeditor/ckeditor5-engine/src/view/matcher

class
See source

View matcher class. Instance of this class can be used to find elements that match given pattern.

Filtering

Properties

  • _patterns : Array.<(String | RegExp | Object)>

    private

Methods

  • constructor( [ pattern ] )

    Creates new instance of Matcher.

    See source

    Parameters

    [ pattern ] : String | RegExp | Object

    Match patterns. See add method for more information.

  • add( pattern = { [pattern.name], [pattern.attributes], [pattern.classes], [pattern.styles] } )

    Adds pattern or patterns to matcher instance.

    See source
    // String.
matcher.add( 'div' );

// Regular expression.
matcher.add( /^\w/ );

// Single class.
matcher.add( {
    classes: 'foobar'
} );

    See MatcherPattern for more examples.

    Multiple patterns can be added in one call:

    matcher.add( 'div', { classes: 'foobar' } );

    Parameters

    pattern : Object | String | RegExp | function

    Object describing pattern details. If string or regular expression is provided it will be used to match element's name. Pattern can be also provided in a form of a function - then this function will be called with each element as a parameter. Function's return value will be stored under match key of the object returned from match or matchAll methods.

    Properties
    [ pattern.name ] : String | RegExp

    Name or regular expression to match element's name.

    [ pattern.attributes ] : Object

    Object with key-value pairs representing attributes to match. Each object key represents attribute name. Value under that key can be either:

    • true - then attribute is just required (can be empty),
    • a string - then attribute has to be equal, or
    • a regular expression - then attribute has to match the expression.
    [ pattern.classes ] : String | RegExp | Array

    Class name or array of class names to match. Each name can be provided in a form of string or regular expression.

    [ pattern.styles ] : Object

    Object with key-value pairs representing styles to match. Each object key represents style name. Value under that key can be either a string or a regular expression and it will be used to match style value.

  • getElementName() → String | null

    Returns the name of the element to match if there is exactly one pattern added to the matcher instance and it matches element name defined by string (not RegExp). Otherwise, returns null.

    See source

    Returns

    String | null

    Element name trying to match.

  • match( element ) → Object | null

    Matches elements for currently stored patterns. Returns match information about first found element, otherwise returns null.

    See source

    Example of returned object:

    {
    element: <instance of found element>,
    pattern: <pattern used to match found element>,
    match: {
        name: true,
        attributes: [ 'title', 'href' ],
        classes: [ 'foo' ],
        styles: [ 'color', 'position' ]
    }
}

    Parameters

    element : Element

    View element to match against stored patterns.

    Returns

    Object | null

    result

    Element

    result.element Matched view element.

    Object | String | RegExp | function

    result.pattern Pattern that was used to find matched element.

    Object

    result.match Object representing matched element parts.

    Boolean

    [result.match.name] True if name of the element was matched.

    Array

    [result.match.attributes] Array with matched attribute names.

    Array

    [result.match.classes] Array with matched class names.

    Array

    [result.match.styles] Array with matched style names.

    Related:

  • matchAll( element ) → Array.<Object> | null

    Matches elements for currently stored patterns. Returns array of match information with all found elements. If no element is found - returns null.

    See source

    Parameters

    element : Element

    View element to match against stored patterns.

    Returns

    Array.<Object> | null

    Array with match information about found elements or null. For more information see match method description.

    Related: