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).

The styles map is capable of normalizing style names so e.g. the following operations are possible:

Filtering

Properties

  • isEmpty : Boolean

    Returns true if style map has no styles set.

    See source

  • size : Number

    Number of styles defined.

    See source

  • _styleProcessor : StylesProcessor

    private

    An instance of the StylesProcessor.

    See source

  • _styles : Object

    private

    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.

    See source

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

Methods

  • constructor( styleProcessor )

    Creates Styles instance.

    See source

    Parameters

    styleProcessor : StylesProcessor

  • clear()

    Removes all styles.

    See source

  • getAsString( propertyName ) → String | undefined

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

    See source
    // 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

    String | undefined

  • getNormalized( name ) → Object | String | undefined

    Returns a normalized style object or a single value.

    See source
    // 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

    Object | String | undefined

  • getStyleNames( [ expand ] ) → Array.<String>

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

    See source

    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>

  • has( name ) → Boolean

    Checks if a given style is set.

    See source
    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 )

    Removes given style.

    See source
    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.

  • set( nameOrObject, valueOrObject )

    Sets a given style.

    See source

    Can insert one by one:

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

    or many styles at once:

    styles.set( {
	color: 'blue',
	'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

    nameOrObject : String | Object

    Style property name or object with multiple properties.

    valueOrObject : String | Object

    Value to set.

  • setTo( inlineStyle )

    Set styles map to a new value.

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

    Parameters

    inlineStyle : String

  • toString() → String

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

    See source
    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

  • _cleanEmptyObjectsOnPath( path )

    private

    Removes empty objects upon removing an entry from internal object.

    See source

    Parameters

    path : String

  • _getStylesEntries() → Array.<PropertyDescriptor>

    private

    Returns normalized styles entries for further processing.

    See source

    Returns

    Array.<PropertyDescriptor>