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

Filtering

Properties

  • readonly

    isEmpty : boolean

    Returns true if style map has no styles set.

  • readonly

    size : number

    Number of styles defined.

  • private readonly

    _styleProcessor : StylesProcessor

    An instance of the StylesProcessor.

  • private

    _styles : Styles

    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() → void

    Removes all styles.

    Returns

    void
  • getAsString( propertyName ) → undefined | string

    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

    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>

    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>

    Returns normalized styles entries for further processing.

    Returns

    Array<PropertyDescriptor>
  • 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 ) → void

    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

    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

    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

    Set styles map to a new value.

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

    Parameters

    inlineStyle : string

    Returns

    void
  • 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
  • private

    _cleanEmptyObjectsOnPath( path ) → void

    Removes empty objects upon removing an entry from internal object.

    Parameters

    path : string

    Returns

    void