StylesMap (engine/view)

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

Properties

• readonly

  isEmpty : booleanmodule:engine/view/stylesmap~StylesMap#isEmpty

  See source

  Returns true if style map has no styles set.

• readonly

  size : numbermodule:engine/view/stylesmap~StylesMap#size

  See source

  Number of styles defined.

• private

  _cachedExpandedStyleNames : null | Array<string>module:engine/view/stylesmap~StylesMap#_cachedExpandedStyleNames

  See source

  Cached list of expanded style names for faster access.

• private

  _cachedStyleNames : null | Array<string>module:engine/view/stylesmap~StylesMap#_cachedStyleNames

  See source

  Cached list of style names for faster access.

• private readonly

  _styleProcessor : StylesProcessormodule:engine/view/stylesmap~StylesMap#_styleProcessor

  See source

  An instance of the StylesProcessor.

• private

  _styles : Stylesmodule:engine/view/stylesmap~StylesMap#_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 )module:engine/view/stylesmap~StylesMap#constructor

  See source

  Creates Styles instance.

  Parameters

  styleProcessor : StylesProcessor

• clear() → voidmodule:engine/view/stylesmap~StylesMap#clear

  See source

  Removes all styles.

  Returns

  void

• getAsString( propertyName ) → undefined | stringmodule:engine/view/stylesmap~StylesMap#getAsString

  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 ] ) → undefined | StyleValuemodule:engine/view/stylesmap~StylesMap#getNormalized

  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

  undefined | StyleValue

• getStyleNames( expand ) → Array<string>module:engine/view/stylesmap~StylesMap#getStyleNames

  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>module:engine/view/stylesmap~StylesMap#getStylesEntries

  See source

  Returns normalized styles entries for further processing.

  Returns

  Array<PropertyDescriptor>

• has( name ) → booleanmodule:engine/view/stylesmap~StylesMap#has

  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

• isSimilar( other ) → booleanmodule:engine/view/stylesmap~StylesMap#isSimilar

  See source

  Returns true if both attributes have the same styles.

  Parameters

  other : StylesMap

  Returns

  boolean

• keys() → Array<string>module:engine/view/stylesmap~StylesMap#keys

  See source

  Alias for getStyleNames.

  Returns

  Array<string>

• remove( names ) → voidmodule:engine/view/stylesmap~StylesMap#remove

  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

  names : ArrayOrItem<string>

  Style name or an array of names.

  Returns

  void

• set( styles ) → voidmodule:engine/view/stylesmap~StylesMap#set:CONFIG_OBJECT

  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 ) → voidmodule:engine/view/stylesmap~StylesMap#set:KEY_VALUE

  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 ) → StylesMapmodule:engine/view/stylesmap~StylesMap#setTo

  See source

  Set styles map to a new value.

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

  Parameters

  inlineStyle : string

  Returns

  StylesMap

• toString() → stringmodule:engine/view/stylesmap~StylesMap#toString

  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

• internal

  _canMergeFrom( other ) → booleanmodule:engine/view/stylesmap~StylesMap#_canMergeFrom

  See source

  Used by _canMergeAttributesFrom to verify if the given attribute can be merged without conflicts into the attribute.

  This method is indirectly used by the DowncastWriter while down-casting an AttributeElement to merge it with other AttributeElement.

  Parameters

  other : StylesMap

  Returns

  boolean

• internal

  _clone() → StylesMapmodule:engine/view/stylesmap~StylesMap#_clone

  See source

  Clones the attribute value.

  Returns

  StylesMap

• internal

  _getConsumables( [ name ] ) → Array<string>module:engine/view/stylesmap~StylesMap#_getConsumables

  See source

  Returns a list of consumables for the attribute. This includes related styles.

  Could be filtered by the given style name.

  Parameters

  [ name ] : string

  Returns

  Array<string>

• internal

  _getTokensMatch( tokenPattern, valuePattern ) → undefined | Array<string>module:engine/view/stylesmap~StylesMap#_getTokensMatch

  See source

  Used by the Matcher to collect matching styles.

  Parameters

  tokenPattern : string | true | RegExp

  The matched style name pattern.

  valuePattern : string | true | RegExp

  The matched style value pattern.

  Returns

  undefined | Array<string>

  An array of matching tokens (style names).

• internal

  _isMatching( other ) → booleanmodule:engine/view/stylesmap~StylesMap#_isMatching

  See source

  Used by _canSubtractAttributesOf to verify if the given attribute can be fully subtracted from the attribute.

  This method is indirectly used by the DowncastWriter while down-casting an AttributeElement to unwrap the AttributeElement.

  Parameters

  other : StylesMap

  Returns

  boolean

• internal

  _mergeFrom( other ) → voidmodule:engine/view/stylesmap~StylesMap#_mergeFrom

  See source

  Used by _mergeAttributesFrom to merge a given attribute into the attribute.

  This method is indirectly used by the DowncastWriter while down-casting an AttributeElement to merge it with other AttributeElement.

  Parameters

  other : StylesMap

  Returns

  void

• private

  _cleanEmptyObjectsOnPath( path ) → voidmodule:engine/view/stylesmap~StylesMap#_cleanEmptyObjectsOnPath

  See source

  Removes empty objects upon removing an entry from internal object.

  Parameters

  path : string

  Returns

  void