Utils – amCharts 5 Documentation

Type module

Sources

Items from Utils can be imported/included and used via following ways.

/**
 * --------------------------------------------------------
 * Import via main package: core.ts
 * Access items like: am5.utils.myVariable
 *                    am5.utils.myFunction()
 * --------------------------------------------------------
 */
import * as am5 from "@amcharts/amcharts5";

/**
 * --------------------------------------------------------
 * Import via: Utils.ts
 * Access items like: $utils.myVariable
 *                    $utils.myFunction()
 * --------------------------------------------------------
 */
import * as $utils from "@amcharts/amcharts5/Utils";

/**
 * --------------------------------------------------------
 * Include via "index.js"
 * E.g.: "https://cdn.amcharts.com/lib/5/index.js"
 * Access items like: am5.utils.myVariable
 *                    am5.utils.myFunction()
 * --------------------------------------------------------
 */

Variables

Utils does not have any variables.

Functions

addSpacing( str: `string` ) #	Returns `string` Adds space before each uppercase letter.
alternativeColor( color: `iRGB`, lightAlternative: `iRGB`, darkAlternative: `iRGB` ) #	Returns `iRGB` Returns a color which contrasts more with the source `color`.
brighten( rgb: `$type.Optional`, percent: `number` ) #	Returns `$type.Optional` Returns a color that is `percent` brighter than the source `color`.
capitalizeFirst( text: `string` ) #	Returns `string`
contains( a: `Element`, b: `Element` ) #	Returns `boolean` Checks of element `a` contains element `b`.
escapeForRgex( value: `string` ) #	Returns `string` Escapes string so it can safely be used in a Regex.
get12Hours( hours: `number`, base?: `undefined` \| `number` ) #	Returns `number` Returns 12-hour representation out of the 24-hour hours.
getDayFromWeek( week: `number`, year: `number`, weekday: `number`, utc: `boolean` ) #	Returns `number` Returns a year day out of the given week number.
getEventKey( event: `KeyboardEvent` ) #	Returns `string`
getEventTarget( event: `Event` \| `Touch` ) #	Returns `void` Gets the target of the event, works for shadow DOM too.
getLightnessStep( value: `number`, percent: `number` ) #	Returns `number` Gets lightness step.
getMonthWeek( date: `Date`, utc: `boolean` ) #	Returns `number` Returns a week number in the month.
getSafeResolution() #	Returns `void`
getShadowRoot( a: `Node` ) #	Returns `ShadowRoot` \| `null` Returns the shadow root of the element or null
getStyle( dom: `HTMLElement`, property: `string` ) #	Returns `void`
getTimeZone( date: `Date`, long: `boolean`, savings: `boolean`, utc: `boolean`, timezone?: `undefined` \| `string` ) #	Returns `string` Returns a string name of the time zone.
getTimezoneOffset( timezone: `string`, targetDate?: `Date` ) #	Returns `number`
getWeek( date: `Date`, _utc: `boolean` ) #	Returns `number` Returns week number for a given date. @todo Account for UTC
getWeekYear( date: `Date`, _utc: `boolean` ) #	Returns `number` Returns a "week year" of the given date. @since 5.3.0 @todo Account for UTC
getYearDay( date: `Date`, utc: `boolean` ) #	Returns `number` Returns a year day. @todo Account for UTC
hslToHsv( hsl: `iHSL` ) #	Returns `iHSV` Converts HSL to HSV. https://en.wikipedia.org/wiki/HSL_and_HSV#HSL_to_HSV
hslToRgb( color: `iHSL` ) #	Returns `iRGB` Converts an HSL color value to RGB. Conversion formula adapted from http://en.wikipedia.org/wiki/HSL_color_space. Assumes h, s, and l are contained in the set [0, 1] and returns r, g, and b in the set [0, 255]. Function adapted from: http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c
hsvToHsl( hsv: `iHSV` ) #	Returns `iHSL` Converts HSV to HSL. https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_HSL
iOS() #	Returns `boolean`
isLight( color: `iRGB` ) #	Returns `boolean` Returns `true` if color is "light". Useful indetermining which contrasting color to use for elements over this color. E.g.: you would want to use black text over light background, and vice versa.
isLocalEvent( event: `IPointerEvent`, target: `Sprite` ) #	Returns `boolean` Returns `true` if pointer event originated on an element within Root. @since 5.2.8
isTouchEvent( ev: `MouseEvent` \| `Touch` ) #	Returns `boolean` Determines if pointer event originated from a touch pointer or mouse.
lighten( rgb: `$type.Optional`, percent: `number` ) #	Returns `$type.Optional` Returns a color that is `percent` brighter than the reference color.
onZoom( listener: () => `void` ) #	Returns `IDisposer` Function that adds an event listener which is triggered when the browser's zoom changes.
padString( value: `any`, len: `number`, char: `string` ) #	Returns `string` Pads a string with additional characters to certain length.
plainText( text: `string` ) #	Returns `string` Removes new lines and tags from a string.
ready( f: () => `void` ) #	Returns `void` Execute a function when DOM is ready. @since 5.0.2
relativeToValue( percent: `number` \| `Percent` \| `undefined` \| `null`, full: `number` ) #	Returns `number`
removeElement( el: `HTMLElement` ) #	Returns `void` Removes a DOM element.
rgbToHsl( color: `iRGB` ) #	Returns `iHSL` Converts an RGB color value to HSL. Conversion formula adapted from http://en.wikipedia.org/wiki/HSL_color_space. Assumes r, g, and b are contained in the set [0, 255] and returns h, s, and l in the set [0, 1]. Function adapted from: http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c
saturate( rgb: `$type.Optional`, saturation: `number` ) #	Returns `$type.Optional` Returns a new `iRGB` object based on `rgb` parameter with specific saturation applied. `saturation` can be in the range of 0 (fully desaturated) to 1 (fully saturated).
setInteractive( target: `HTMLElement`, interactive: `boolean` ) #	Returns `void` Disables or enables interactivity of a DOM element.
splitString( source: `string` ) #	Returns `string[]` Splits the string into separate characters. Keeps RTL words non-split.
stripTags( text: `string` ) #	Returns `string` Strips all tags from the string.
trim( text: `string` ) #	Returns `string`
trimLeft( text: `string` ) #	Returns `string`
trimRight( text: `string` ) #	Returns `string`
truncateTextWithEllipsis( text: `string`, maxLength: `number`, breakWords: `boolean`, ellipsis: `string` ) #	Returns `string`

addSpacing(

str: string

)

Returns string

Adds space before each uppercase letter.

alternativeColor(

color: iRGB,
lightAlternative: iRGB,
darkAlternative: iRGB

)

Returns iRGB

Returns a color which contrasts more with the source color.

brighten(

rgb: $type.Optional,
percent: number

)

Returns $type.Optional

Returns a color that is percent brighter than the source color.

capitalizeFirst(

text: string

)

Returns string

contains(

a: Element,
b: Element

)

Returns boolean

Checks of element a contains element b.

escapeForRgex(

value: string

)

Returns string

Escapes string so it can safely be used in a Regex.

get12Hours(

hours: number,
base?: undefined | number

)

Returns number

Returns 12-hour representation out of the 24-hour hours.

getDayFromWeek(

week: number,
year: number,
weekday: number,
utc: boolean

)

Returns number

Returns a year day out of the given week number.

getEventKey(

event: KeyboardEvent

)

Returns string

getEventTarget(

event: Event | Touch

)

Returns void

Gets the target of the event, works for shadow DOM too.

getLightnessStep(

value: number,
percent: number

)

Returns number

Gets lightness step.

getMonthWeek(

date: Date,
utc: boolean

)

Returns number

Returns a week number in the month.

getSafeResolution()

Returns void

getShadowRoot(

a: Node

)

Returns ShadowRoot | null

Returns the shadow root of the element or null

getStyle(

dom: HTMLElement,
property: string

)

Returns void

getTimeZone(

date: Date,
long: boolean,
savings: boolean,
utc: boolean,
timezone?: undefined | string

)

Returns string

Returns a string name of the time zone.

getTimezoneOffset(

timezone: string,
targetDate?: Date

)

Returns number

getWeek(

date: Date,
_utc: boolean

)

Returns number

Returns week number for a given date.

@todo Account for UTC

getWeekYear(

date: Date,
_utc: boolean

)

Returns number

Returns a "week year" of the given date.

@since 5.3.0
@todo Account for UTC

getYearDay(

date: Date,
utc: boolean

)

Returns number

Returns a year day.

@todo Account for UTC

hslToHsv(

hsl: iHSL

)

Returns iHSV

Converts HSL to HSV.

https://en.wikipedia.org/wiki/HSL_and_HSV#HSL_to_HSV

hslToRgb(

color: iHSL

)

Returns iRGB

Converts an HSL color value to RGB. Conversion formula adapted from http://en.wikipedia.org/wiki/HSL_color_space.

Assumes h, s, and l are contained in the set [0, 1] and returns r, g, and b in the set [0, 255].

Function adapted from:

http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c

hsvToHsl(

hsv: iHSV

)

Returns iHSL

Converts HSV to HSL.

https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_HSL

iOS()

Returns boolean

isLight(

color: iRGB

)

Returns boolean

Returns true if color is "light". Useful indetermining which contrasting color to use for elements over this color. E.g.: you would want to use black text over light background, and vice versa.

isLocalEvent(

event: IPointerEvent,
target: Sprite

)

Returns boolean

Returns true if pointer event originated on an element within Root.

@since 5.2.8

isTouchEvent(

ev: MouseEvent | Touch

)

Returns boolean

Determines if pointer event originated from a touch pointer or mouse.

lighten(

rgb: $type.Optional,
percent: number

)

Returns $type.Optional

Returns a color that is percent brighter than the reference color.

onZoom(

listener: () => void

)

Returns IDisposer

Function that adds an event listener which is triggered when the browser's zoom changes.

padString(

value: any,
len: number,
char: string

)

Returns string

Pads a string with additional characters to certain length.

plainText(

text: string

)

Returns string

Removes new lines and tags from a string.

ready(

f: () => void

)

Returns void

Execute a function when DOM is ready.

@since 5.0.2

relativeToValue(

percent: number | Percent | undefined | null,
full: number

)

Returns number

removeElement(

el: HTMLElement

)

Returns void

Removes a DOM element.

rgbToHsl(

color: iRGB

)

Returns iHSL

Converts an RGB color value to HSL. Conversion formula adapted from http://en.wikipedia.org/wiki/HSL_color_space.

Assumes r, g, and b are contained in the set [0, 255] and returns h, s, and l in the set [0, 1].

Function adapted from:

http://axonflux.com/handy-rgb-to-hsl-and-rgb-to-hsv-color-model-c

saturate(

rgb: $type.Optional,
saturation: number

)

Returns $type.Optional

Returns a new iRGB object based on rgb parameter with specific saturation applied.

saturation can be in the range of 0 (fully desaturated) to 1 (fully saturated).

setInteractive(

target: HTMLElement,
interactive: boolean

)

Returns void

Disables or enables interactivity of a DOM element.

splitString(

source: string

)

Returns string[]

Splits the string into separate characters. Keeps RTL words non-split.

stripTags(

text: string

)

Returns string

Strips all tags from the string.

trim(

text: string

)

Returns string

trimLeft(

text: string

)

Returns string

trimRight(

text: string

)

Returns string

truncateTextWithEllipsis(

text: string,
maxLength: number,
breakWords: boolean,
ellipsis: string

)

Returns string