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` Capitalizes the first letter of a 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.
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 `number` \| `undefined` Returns a safe canvas resolution for the current device. Returns `1` on iOS to avoid memory issues, `undefined` otherwise.
getShadowRoot( a: `Node` ) #	Returns `ShadowRoot` \| `null` Returns the shadow root of the element or null
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` Returns the UTC offset in minutes for a given timezone.
getWeek( date: `Date`, _utc: `boolean` ) #	Returns `number` Returns week number for a given date.
getWeekYear( date: `Date`, _utc: `boolean` ) #	Returns `number` Returns a "week year" of the given date. @since 5.3.0
getYearDay( date: `Date`, utc: `boolean` ) #	Returns `number` Returns a year day.
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` Returns `true` if the current device is running iOS.
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` Converts a value that can be a number or `Percent` to an absolute number relative to the given full value.
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
sanitizeHTML( html: `string` ) #	Returns `string` Sanitizes an HTML string by stripping out constructs that are practically only used for cross-site scripting (XSS) attacks, while leaving legitimate markup intact. Specifically it removes: `<script>`, `<iframe>`, `<object>`, `<embed>` and similar dangerous tags; inline event handler attributes (`onerror`, `onload`, `onclick`, ...); `javascript:` / `vbscript:` (and similar) protocol URLs in attributes; inline styles that smuggle in scripts via `expression()`, `url(javascript:...)`, `behavior`, or `-moz-binding`. This is applied to any HTML that gets injected via `innerHTML` (e.g. `html` and `labelHTML` settings, HTML tooltips, modal content, and export menu labels), because chart data and labels frequently originate from untrusted back-ends. @since 5.19.0
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.
stripFormatTags( text: `string` ) #	Returns `string` Strips inline formatting tags (square brackets) from the string.
stripTags( text: `string` ) #	Returns `string` Strips all tags from the string.
trim( text: `string` ) #	Returns `string` Removes whitespace from both ends of a string.
trimLeft( text: `string` ) #	Returns `string` Removes whitespace from the beginning of a string.
trimRight( text: `string` ) #	Returns `string` Removes whitespace from the end of a string.
truncateTextWithEllipsis( text: `string`, maxLength: `number`, breakWords: `boolean`, ellipsis: `string` ) #	Returns `string` Truncates a string to a maximum length, appending an ellipsis.

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

Capitalizes the first letter of a 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.

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 number | undefined

Returns a safe canvas resolution for the current device.

Returns 1 on iOS to avoid memory issues, undefined otherwise.

getShadowRoot(

a: Node

)

Returns ShadowRoot | null

Returns the shadow root of the element or null

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

Returns the UTC offset in minutes for a given timezone.

getWeek(

date: Date,
_utc: boolean

)

Returns number

Returns week number for a given date.

getWeekYear(

date: Date,
_utc: boolean

)

Returns number

Returns a "week year" of the given date.

@since 5.3.0

getYearDay(

date: Date,
utc: boolean

)

Returns number

Returns a year day.

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

Returns true if the current device is running iOS.

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

Converts a value that can be a number or Percent to an absolute number relative to the given full value.

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

sanitizeHTML(

html: string

)

Returns string

Sanitizes an HTML string by stripping out constructs that are practically only used for cross-site scripting (XSS) attacks, while leaving legitimate markup intact. Specifically it removes:

<script>, <iframe>, <object>, <embed> and similar dangerous tags;
inline event handler attributes (onerror, onload, onclick, ...);
javascript: / vbscript: (and similar) protocol URLs in attributes;
inline styles that smuggle in scripts via expression(), url(javascript:...), behavior, or -moz-binding.

This is applied to any HTML that gets injected via innerHTML (e.g. html and labelHTML settings, HTML tooltips, modal content, and export menu labels), because chart data and labels frequently originate from untrusted back-ends.

@since 5.19.0

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.

stripFormatTags(

text: string

)

Returns string

Strips inline formatting tags (square brackets) from the string.

stripTags(

text: string

)

Returns string

Strips all tags from the string.

trim(

text: string

)

Returns string

Removes whitespace from both ends of a string.

trimLeft(

text: string

)

Returns string

Removes whitespace from the beginning of a string.

trimRight(

text: string

)

Returns string

Removes whitespace from the end of a string.

truncateTextWithEllipsis(

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

)

Returns string

Truncates a string to a maximum length, appending an ellipsis.