Class

StylesMap (engine/view)

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

class

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.

  • size : Number

    Number of styles defined.

  • _styleProcessor : StylesProcessor

    private

    An instance of the StylesProcessor.

  • _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.

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

Methods

  • constructor( styleProcessor )

    Creates Styles instance.

    Parameters

    styleProcessor : StylesProcessor
  • clear()

    Removes all styles.

  • getAsString( propertyName ) → String | undefined

    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

    String | undefined
  • getNormalized( name ) → Object | String | undefined

    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

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

    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>
  • has( name ) → Boolean

    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 )

    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.

  • set( nameOrObject, valueOrObject )

    Sets a given style.

    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.

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

    Parameters

    inlineStyle : String
  • toString() → String

    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
  • _cleanEmptyObjectsOnPath( path )

    private

    Removes empty objects upon removing an entry from internal object.

    Parameters

    path : String
  • _getStylesEntries() → Array.<PropertyDescriptor>

    private

    Returns normalized styles entries for further processing.

    Returns

    Array.<PropertyDescriptor>