CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

StylesMap (engine/view)

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

class
See source

Styles map. Allows handling (adding, removing, retrieving) a set of style rules (usually, of an element).

Filtering

Properties

  • readonly

    isEmpty : boolean

    See source

    Returns true if style map has no styles set.

  • readonly

    size : number

    See source

    Number of styles defined.

  • private

    _cachedExpandedStyleNames : null | Array<string>

    See source

    Cached list of expanded style names for faster access.

  • private

    _cachedStyleNames : null | Array<string>

    See source

    Cached list of style names for faster access.

  • private readonly

    _styleProcessor : StylesProcessor

    See source

    An instance of the StylesProcessor.

  • private

    _styles : Styles

    See source

    Keeps an internal representation of styles map. Normalized styles are kept as object tree to allow unified modification and value access model using lodash's get, set, unset, etc methods.

    When no style processor rules are defined it acts as simple key-value storage.

Methods

  • constructor( styleProcessor )

    See source

    Creates Styles instance.

    Parameters

    styleProcessor : StylesProcessor

  • clear() → void

    See source

    Removes all styles.

    Returns

    void

  • getAsString( propertyName ) → undefined | string

    See source

    Returns property as a value string or undefined if property is not set.

    // Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginRules );

const styles = new Styles();
styles.setTo( 'margin:1px;' );
styles.set( 'margin-bottom', '3em' );

styles.getAsString( 'margin' ); // -> 'margin: 1px 1px 3em;'

    Note, however, that all sub-values must be set for the longhand property name to return a value:

    const styles = new Styles();
styles.setTo( 'margin:1px;' );
styles.remove( 'margin-bottom' );

styles.getAsString( 'margin' ); // -> undefined

    In the above scenario, it is not possible to return a margin value, so undefined is returned. Instead, you should use:

    const styles = new Styles();
styles.setTo( 'margin:1px;' );
styles.remove( 'margin-bottom' );

for ( const styleName of styles.getStyleNames() ) {
	console.log( styleName, styles.getAsString( styleName ) );
}
// 'margin-top', '1px'
// 'margin-right', '1px'
// 'margin-left', '1px'

    In general, it is recommend to iterate over style names like in the example above. This way, you will always get all the currently set style values. So, if all the 4 margin values would be set the for-of loop above would yield only 'margin', '1px':

    const styles = new Styles();
styles.setTo( 'margin:1px;' );

for ( const styleName of styles.getStyleNames() ) {
	console.log( styleName, styles.getAsString( styleName ) );
}
// 'margin', '1px'

    Note: To get a normalized version of a longhand property use the #getNormalized() method.

    Parameters

    propertyName : string

    Returns

    undefined | string

  • getNormalized( [ name ] ) → StyleValue

    See source

    Returns a normalized style object or a single value.

    // Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginRules );

const styles = new Styles();
styles.setTo( 'margin:1px 2px 3em;' );

styles.getNormalized( 'margin' );
// will log:
// {
//     top: '1px',
//     right: '2px',
//     bottom: '3em',
//     left: '2px'     // normalized value from margin shorthand
// }

styles.getNormalized( 'margin-left' ); // -> '2px'

    Note: This method will only return normalized styles if a style processor was defined.

    Parameters

    [ name ] : string

    Style name.

    Returns

    StyleValue

  • getStyleNames( expand ) → Array<string>

    See source

    Returns all style properties names as they would appear when using #toString().

    When expand is set to true and there's a shorthand style property set, it will also return all equivalent styles:

    stylesMap.setTo( 'margin: 1em' )

    will be expanded to:

    [ 'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left' ]

    Parameters

    expand : boolean

    Expand shorthand style properties and all return equivalent style representations.

    Defaults to false

    Returns

    Array<string>

  • getStylesEntries() → Array<PropertyDescriptor>

    See source

    Returns normalized styles entries for further processing.

    Returns

    Array<PropertyDescriptor>

  • has( name ) → boolean

    See source

    Checks if a given style is set.

    styles.setTo( 'margin-left:1px;' );

styles.has( 'margin-left' );    // -> true
styles.has( 'padding' );        // -> false

    Note: This check supports normalized style names.

    // Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginRules );

styles.setTo( 'margin:2px;' );

styles.has( 'margin' );         // -> true
styles.has( 'margin-top' );     // -> true
styles.has( 'margin-left' );    // -> true

styles.remove( 'margin-top' );

styles.has( 'margin' );         // -> false
styles.has( 'margin-top' );     // -> false
styles.has( 'margin-left' );    // -> true

    Parameters

    name : string

    Style name.

    Returns

    boolean

  • remove( name ) → void

    See source

    Removes given style.

    styles.setTo( 'background:#f00;margin-right:2px;' );

styles.remove( 'background' );

styles.toString();   // -> 'margin-right:2px;'

    Note: This method uses enabled style processor rules to normalize passed values.

    // Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginRules );

styles.setTo( 'margin:1px' );

styles.remove( 'margin-top' );
styles.remove( 'margin-right' );

styles.toString(); // -> 'margin-bottom:1px;margin-left:1px;'

    Parameters

    name : string

    Style name.

    Returns

    void

  • set( styles ) → void

    See source

    Sets many styles at once:

    styles.set( {
	color: 'blue',
	'margin-right': '1em'
} );

    It is equivalent to:

    styles.set( 'color', 'blue' );
styles.set( 'margin-right', '1em' );

    See set

    Parameters

    styles : Styles

    Returns

    void

  • set( name, value ) → void

    See source

    Sets a given style.

    Can insert one by one:

    styles.set( 'color', 'blue' );
styles.set( 'margin-right', '1em' );

    Note: This method uses enabled style processor rules to normalize passed values.

    // Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginRules );

styles.set( 'margin', '2px' );

    The above code will set margin to:

    styles.getNormalized( 'margin' );
// -> { top: '2px', right: '2px', bottom: '2px', left: '2px' }

    Which makes it possible to retrieve a "sub-value":

    styles.get( 'margin-left' );       // -> '2px'

    Or modify it:

    styles.remove( 'margin-left' );

styles.getNormalized( 'margin' );  // -> { top: '1px', bottom: '1px', right: '1px' }
styles.toString();                 // -> 'margin-bottom:1px;margin-right:1px;margin-top:1px;'

    This method also allows to set normalized values directly (if a particular styles processor rule was enabled):

    styles.set( 'border-color', { top: 'blue' } );
styles.set( 'margin', { right: '2em' } );

styles.toString();                 // -> 'border-color-top:blue;margin-right:2em;'

    Parameters

    name : string

    Style property name.

    value : StyleValue

    Value to set.

    Returns

    void

  • setTo( inlineStyle ) → void

    See source

    Set styles map to a new value.

    styles.setTo( 'border:1px solid blue;margin-top:1px;' );

    Parameters

    inlineStyle : string

    Returns

    void

  • toString() → string

    See source

    Returns a normalized style string. Styles are sorted by name.

    styles.set( 'margin' , '1px' );
styles.set( 'background', '#f00' );

styles.toString(); // -> 'background:#f00;margin:1px;'

    Note: This method supports normalized styles if defined.

    // Enable 'margin' shorthand processing:
editor.data.addStyleProcessorRules( addMarginRules );

styles.set( 'margin' , '1px' );
styles.set( 'background', '#f00' );
styles.remove( 'margin-top' );
styles.remove( 'margin-right' );

styles.toString(); // -> 'background:#f00;margin-bottom:1px;margin-left:1px;'

    Returns

    string

  • private

    _cleanEmptyObjectsOnPath( path ) → void

    See source

    Removes empty objects upon removing an entry from internal object.

    Parameters

    path : string

    Returns

    void