Framework JavaScript

Nous fournissons un framework JavaScript destiné à vous aider dans le développement d'adaptateurs, overlays et docks. Vous trouverez ci-dessous l'ensemble des constantes, fonctions et classes exposées, regroupées par thématiques.

Code commun

Il s'agit ici du code exporté par tous les fichiers JavaScript listés ci-dessous.

Constantes

nom	type	valeur
load	string	'load'
session	string	'session'
alerts	string	'alerts'
chat	string	'chat'
other	string	'other'
facebook	string	'facebook'
kick	string	'kick'
tiktok	string	'tiktok'
trovo	string	'trovo'
twitch	string	'twitch'
youtube	string	'youtube'
event	string	'event'
merch	string	'merch'
tip	string	'tip'
redemption	string	'redemption'
reward	string	'reward'
subscriber	string	'subscriber'
cheer	string	'cheer'
elixir	string	'elixir'
follower	string	'follower'
raid	string	'raid'
sponsor	string	'sponsor'
superChat	string	'superchat'
fan	string	'fan'
like	string	'like'
videoLike	string	'videolike'
supporter	string	'supporter'
share	string	'share'
stars	string	'stars'
gift	string	'gift'
message	string	'message'
deleteMessage	string	'delete-message'
deleteMessages	string	'delete-messages'
botCounter	string	'bot:counter'

URL

parameters

L'objet parameters contient les paramètres appliqués à la page courante par le biais de la query string, hormis les paramètres lang, fonts, theme et zoom (dans le cas du fichier adapters.js) puis queueDuration, antiSpamDelta, antiSpamThreshold et volume (dans le cas du fichier overlay.js). Cet objet est sûr pour l'indexation. Les paramètres système sont décrits en détails sur la page dédiée aux overlays.

Événements

Listener

La classe Listener sert à faciliter l'écoute d'événements. Sa signature TypeScript est la suivante :

type Callback = (event: Event) => any;

type Options = {
  delegate?: string;
  passive?: false;
};

declare class Listener {
  constructor(event: string, callback: Callback, host?: EventTarget, options?: Options);
  on(): void;
  off(): void;
}

Paramètres

nom	description	optionnel
event	Nom de l'événement à écouter	non
callback	Fonction appelée lors de l'événement	non
host	Objet sur lequel écouter l'événement	oui (window par défaut)
options	Objet décrivant le comportement à ajouter à l'écouteur d'événements	oui
options.delegate	Sélecteur CSS pour utiliser la délégation d'événements	oui
options.passive	Définit si l'événement est passif (true) ou non (false)	oui (true par défaut)

Méthodes

nom	description
on	Démarre l'écoute de l'événement (appelée à l'initialisation)
off	Stoppe l'écoute de l'événement

Exemple

const listener = new Listener('click', e => console.log(e), document.body);

listener.off();
listener.on();

new Listener(
  'click',
  (target, e) => console.log(target, e),
  document.body,
  { delegate: 'button.danger' }
);

Fichier adapters.js

Le fchier adapters.js contient tout ce qui peut être utile au développement d'adaptateurs, en complément du code commun décrit ci-dessus.

<script type="module">
  import {} from 'https://obs.multistream.tools/v1/adapters.js';
</script>

danger

N'ajoutez pas de hash ni de query string à l'URL d'import du fichier sans quoi le module serait exécuté plusieurs fois au lieu d'une seule, ceci pouvant donner lieu à des effets de bord indésirables.

Constantes

nom	type	valeur
wildCard	string	'*'
onWidgetLoad	string	'onWidgetLoad'
onEventReceived	string	'onEventReceived'
onSessionUpdate	string	'onSessionUpdate'

Plateformes

Les classes Platform, Facebook, Kick, TikTok, Trovo, Twitch et YouTube sont décrites sur la page dédiée aux pateformes.

Adaptateurs

Les classes Adapter, StreamElementsAdapter, FacebookStreamElementsAdapter, KickStreamElementsAdapter, TrovoStreamElementsAdapter, TwitchStreamElementsAdapter, YouTubeStreamElementsAdapter et TikFinityAdapter sont décrites sur la page dédiée aux adaptateurs.

Fichier overlay.js

Le fichier overlay.js contient tout ce qui peut être utile au développement d'overlays et docks, en complément du code commun décrit ci-dessus.

<script type="module">
  import {} from 'https://obs.multistream.tools/v1/overlay.js';
</script>

danger

N'ajoutez pas de hash ni de query string à l'URL d'import du fichier sans quoi le module serait exécuté plusieurs fois au lieu d'une seule, ceci pouvant donner lieu à des effets de bord indésirables.

Constantes

nom	type	valeur
mute	string	'mute'
pause	string	'pause'
skip	string	'skip'

Raccourcis

nom	valeur
arrayFrom	Array.from
isArray	Array.isArray
jsonParse	JSON.parse
jsonStringify	JSON.stringify
objectAssign	Object.assign
objectCreate	Object.create
objectEntries	Object.entries
objectKeys	Object.keys
origin	location.origin
pathName	location.pathname
queryString	location.search
html	document.documentElement
head	document.head
body	document.body

Utilitaires

isString

La fonction isString permet de savoir si la valeur passée en paramètre est une chaîne de caractères ou non. Sa signature TypeScript est la suivante :

declare const isString: (value: any) => boolean;

Paramètres

nom	description	optionnel
value	Valeur à tester	non

Exemple

isString(''); // true
isString({}); // false

isNumber

La fonction isNumber permet de savoir si la valeur passée en paramètre est un nombre ou non. Sa signature TypeScript est la suivante :

declare const isNumber: (value: any) => boolean;

Paramètres

nom	description	optionnel
value	Valeur à tester	non

Exemple

isNumber(1); // true
isNumber('1'); // false

isTrue

La fonction isTrue permet de savoir si la valeur passée en paramètre est true ou non. Sa signature TypeScript est la suivante :

declare const isTrue: (value: any) => boolean;

Paramètres

nom	description	optionnel
value	Valeur à tester	non

Exemple

isTrue(true); // true
isTrue('true'); // false
isTrue(new Boolean(true)); // false

isFalse

La fonction isFalse permet de savoir si la valeur passée en paramètre est false ou non. Sa signature TypeScript est la suivante :

declare const isFalse: (value: any) => boolean;

Paramètres

nom	description	optionnel
value	Valeur à tester	non

Exemple

isFalse(false); // true
isFalse('false'); // false
isFalse(new Boolean(false)); // false

notTrue

La fonction notTrue permet de savoir si la valeur passée en paramètre n'est pas true. Sa signature TypeScript est la suivante :

declare const notTrue: (value: any) => boolean;

Paramètres

nom	description	optionnel
value	Valeur à tester	non

Exemple

notTrue(false); // true
notTrue(true); // false

notFalse

La fonction notFalse permet de savoir si la valeur passée en paramètre n'est pas false. Sa signature TypeScript est la suivante :

declare const notFalse: (value: any) => boolean;

Paramètres

nom	description	optionnel
value	Valeur à tester	non

Exemple

notFalse(true); // true
notFalse(false); // false

validate

La fonction validate permet de tester si la valeur passée en paramètre satisfait un prédicat donné ; si le prédicat retourne true, l'appel à la fonction validate retourne la valeur passée en paramètre. Sa signature TypeScript est la suivante :

type Predicate = (value: any) => boolean;

declare const validate: (predicate: Predicate, value: any, fallback?: any) => any;

Paramètres

nom	description	optionnel
predicate	Prédicat de test	non
value	Valeur à tester	non
fallback	Valeur par défaut	oui (undefined par défaut)

Exemple

let { exampleParam } = parameters;

exampleParam = validate(isString, exampleParam, ''); // `exampleParam` or `''`

validateString

La fonction validateString permet de tester si la valeur passée en paramètre est une chaîne de caractères ; si oui, l'appel à la fonction validateString retourne la valeur passée en paramètre. Sa signature TypeScript est la suivante :

declare const validateString: (value: any, fallback?: any) => any;

Paramètres

nom	description	optionnel
value	Valeur à tester	non
fallback	Valeur par défaut	oui ('' par défaut)

Exemple

let { exampleParamA, exampleParamB } = parameters;

exampleParamA = validateString(exampleParamA); // `exampleParamA` or `''`
exampleParamB = validateString(exampleParamB, 'fallback'); // `exampleParamB` or `'fallback'`
validateString('', 'fallback'); // 'fallback'

validateNumber

La fonction validateNumber permet de tester si la valeur passée en paramètre est un nombre ; si oui, l'appel à la fonction validateNumber retourne la valeur passée en paramètre. Sa signature TypeScript est la suivante :

declare const validateNumber: (value: any, fallback?: any) => any;

Paramètres

nom	description	optionnel
value	Valeur à tester	non
fallback	Valeur par défaut	oui (undefined par défaut)

Exemple

let { exampleParamA, exampleParamB } = parameters;

exampleParamA = validateNumber(exampleParamA); // `exampleParamA` or `undefined`
exampleParamB = validateNumber(exampleParamB, 42); // `exampleParamB` or `42`
validateNumber(0, 9000); // 0

validateArray

La fonction validateArray permet de tester si la valeur passée en paramètre est une chaîne de caractères ; si oui, l'appel à la fonction validateArray retourne un tableau contenant les valeurs passées en paramètre, séparées par des virgules. Sa signature TypeScript est la suivante :

type Mapper = (value: string) => any;

declare const validateArray: (value: string, fallback?: string, mapper?: Mapper) => any[];

Paramètres

nom	description	optionnel
value	Valeur à tester	non
fallback	Valeur par défaut	oui
mapper	Une fonction servant à modifier chaque valeur du tableau	oui

Exemple

let { exampleParamA, exampleParamB, exampleParamC } = parameters;

exampleParamA = validateArray(exampleParamA); // instanceof Array
exampleParamB = validateArray(exampleParamB, 'valueA,valueB'); // instanceof Array
exampleParamC = validateArray(exampleParamC, undefined, value => value.toLowerCase()); // instanceof Array

validateSet

La fonction validateSet permet de tester si la valeur passée en paramètre est une chaîne de caractères ; si oui, l'appel à la fonction validateSet retourne une instance de la classe Set contenant les valeurs passées en paramètre, séparées par des virgules. Sa signature TypeScript est la suivante :

type Mapper = (value: string) => any;

declare const validateSet: (value: string, fallback?: string, mapper?: Mapper) => Set<any>;

Paramètres

nom	description	optionnel
value	Valeur à tester	non
fallback	Valeur par défaut	oui
mapper	Une fonction servant à modifier chaque valeur du set	oui

Exemple

let { exampleParamA, exampleParamB, exampleParamC } = parameters;

exampleParamA = validateSet(exampleParamA); // instanceof Set
exampleParamB = validateSet(exampleParamB, 'valueA,valueB'); // instanceof Set
exampleParamC = validateSet(exampleParamC, undefined, value => value.toLowerCase()); // instanceof Set

getTruthyArray

La fonction getTruthyArray permet de s'assurer que la valeur passée en paramètre est un tableau de données et effectue la conversion si ce n'est pas le cas ; les valeurs dites falsy sont filtrées. Sa signature TypeScript est la suivante :

declare const getTruthyArray: (value: any | any[]) => any[];

Paramètres

nom	description	optionnel
value	Valeur à convertir en tableau si besoin	non

Exemple

getTruthyArray(['']); // []
getTruthyArray(''); // []
getTruthyArray([{}]); // [{}]
getTruthyArray({}); // [{}]

getTruthySet

La fonction getTruthySet permet d'initialiser une instance de la classe Set contenant les valeurs passées en paramètre, une ou plusieurs sous la forme d'un tableau ; les valeurs dites falsy sont filtrées. Sa signature TypeScript est la suivante :

declare const getTruthySet: (value: any | any[]) => Set<any>;

Paramètres

nom	description	optionnel
value	Valeur(s) contenue(s) dans le Set créé	non

Exemple

getTruthySet(['', {}]).size; // 1
getTruthySet('').size; // 0
getTruthySet({}).size; // 1

alias

La fonction alias permet de verouiller les premiers paramètres d'une fonction donnée ; si la valeur du paramètre first est un tableau, la valeur de retour sera un tableau de fonctions. Sa signature TypeScript est la suivante :

type Callback = (...args: any[]) => any;

declare const alias: (callback: Callback, first: any | any[], ...args: any[]) => Callback | Callback[];

Paramètres

nom	description	optionnel
callback	Fonction pour laquelle on veut verouiller les paramètres	non
first	Premier paramètre à verouiller, traité différemment s'il s'agit d'un tableau	non
...args	Éventuels paramètres supplémentaires	oui

Exemple

const [log1, log2] = alias(console.log, [1, 2]);
log1(2); // 1 2
log2(3); // 2 3

const log3 = alias(console.log, 3, 4);
log3(5, 6); // 3 4 5 6

get

La fonction get permet de récupérer ou affecter la valeur stockée dans une map donnée pour une clé donnée ; si aucune valeur truthy n'existe, une instance de la classe passée en paramètre sera créée, stockée et retournée. Sa signature TypeScript est la suivante :

type Class = {
  new (...args: any[]): any;
};

declare const get: (map: Map<any, any>, key: any, Class?: Class) => any;

Paramètres

nom	description	optionnel
map	Instance de la classe Map sur laquelle récupérer ou affecter la valeur	non
key	Clé pour laquelle récupérer ou affecter la valeur sur la map	non
Class	Classe instanciée et stockée dans la map si aucune valeur truthy n'existe pour la clé donnée	oui (Map par défaut)

Exemple

const key1 = 'key1';
const map = new Map([[key1, 1]]);

get(map, key1); // 1
get(map, key1, Set); // 1
get(map, 'key2'); // instanceof Map
get(map, 'key3', Set); // instanceof Set

getSafeObject

La fonction getSafeObject permet de construire une copie sûre pour l'indexation d'objets fusionnés passés en paramètres, c'est à dire sans chaîne de prototype. Sa signature TypeScript est la suivante :

declare const getSafeObject: (...objects: object[]) => object;

Paramètres

nom	description	optionnel
objects	Objets pour lesquels créer une copie sûre pour l'indexation	non

Exemple

const key = 'key';
const object = { [key]: 'value' };

object[key]; // 'value'
typeof object.hasOwnProperty; // 'function'

const safeObject = getSafeObject(object);

safeObject[key]; // 'value'
typeof safeObject.hasOwnProperty; // 'undefined'

getSafeObject({ a: 1 }, { a: 2, b: 1 }); // { a: 2, b: 1 }

removeProperties

La fonction removeProperties permet de supprimer des propriétés sur un objet passé en paramètre, en mutant celui-ci. Sa signature TypeScript est la suivante :

declare const removeProperties: (object: object, ...keys: string[]) => object;

Paramètres

nom	description	optionnel
object	Objet sur lequel supprimer des propriétés	non
keys	Noms des différentes propriétés à supprimer	oui

Exemple

const objectA = { a: 1, b: 2, c: 3 };

removeProperties(objectA, 'a'); // objectA is now { b: 2, c: 3 }
removeProperties(objectA, 'b', 'c'); // objectA is now {}

const objectB = { a: 1, b: 2, c: 3 };

removeProperties(objectB); // objectB is now {}

toMilliSeconds

La fonction toMilliSeconds permet de convertir en millisecondes un nombre de secondes passé en paramètre. Sa signature TypeScript est la suivante :

declare const toMilliSeconds: (seconds: number) => number;

Paramètres

nom	description	optionnel
seconds	Nombre de secondes à convertir en millisecondes	non

Exemple

toMilliSeconds(5); // 5000

split

La fonction split permet de séparer plusieurs valeurs, délimitées par un séparateur donné, à partir d'une chaîne de caractères passée en paramètre. Sa signature TypeScript est la suivante :

declare const split: (value: string, separator?: string) => string[];

Paramètres

nom	description	optionnel
value	Potentiellement plusieurs valeurs	non
separator	Séparateur délimitant les différentes valeurs	oui (',' par défaut)

Exemple

split('value1,value2'); // ['value1', 'value2']
split('value3|value4', '|'); // ['value3', 'value4']

template

La fonction template permet de remplacer plusieurs valeurs, dans une chaîne de caractères passée en paramètre, par des données également fournies. Sa signature TypeScript est la suivante :

declare const template: (value: string, data: object) => string;

Paramètres

nom	description	optionnel
value	Chaîne de caractères contenant des valeurs à remplacer	non
data	Données par lesquelles remplacer ces valeurs	non

Exemple

template('Hello {who}! {notFound}', { who: 'world' }); // 'Hello world! {notFound}'

Mappings

Mapping

La classe Mapping sert à associer différents événements pour des plateformes différentes, par exemple pour regrouper les événements follower (Twitch) et subscriber (YouTube) ayant un sens similaire ; il s'agit d'une sous-classe de la classe String native. Sa signature TypeScript est la suivante :

type Mappings = {
  [platform: string]: string;
};

type Mapped = string | Mapping;

declare class Mapping extends String {
  constructor(event: string, mappings: Mappings, group?: true);
  get group(): boolean;
  map(platform: string): Mapped;
  is(event: Mapped, platform: string): boolean;
  format(): string;
}

Paramètres

nom	description	optionnel
event	Nom de l'événement de base, celui le plus commun	non
mappings	Objet définissant les variantes pour des plateformes spécifiques	non
group	Indique si l'événement peut être un groupe (voir les adaptateurs)	oui

Propriétés

nom	description
group	Indique si l'événement peut être un groupe

Méthodes

nom	description
map	Retourne la variante associée à la plateforme donnée, ou le mapping lui-même
is	Retourne true si l'événement passé en paramètre correspond à la plateforme donnée, false à l'inverse
format	Retourne une représentation formatée du mapping, utile notamment pour un éventuel affichage

Exemple

const cheerMapping = new Mapping(cheer, {
  [trovo]: elixir,
  [youtube]: superChat
});

cheerMapping.group; // false
cheerMapping.map(trovo); // elixir
cheerMapping.map(twitch); // cheerMapping
cheerMapping.map(youtube); // superChat
cheerMapping.is(follower, trovo); // false
cheerMapping.is(cheer, twitch); // true
cheerMapping.is(superChat, youtube); // true
cheerMapping.format(); // 'cheer, elixir (trovo), superchat (youtube)'

Pré-configurés

Nous fournissons les mappings suivants, prêts à l'emploi, pour vous éviter de les modéliser vous-même.

mapping	événements
cheerMapping	cheer, stars (Facebook), elixir (Trovo), superChat (YouTube)
followerMapping	follower, fan (Facebook), subscriber (YouTube)
merchMapping	merch
raidMapping	raid
shareMapping	share
subscriberMapping	subscriber, supporter (Facebook), sponsor (YouTube)
tipMapping	tip
likeMapping	like, videoLike (Facebook)

URL

getOrigin

La fonction getOrigin permet d'extraire l'origine d'une URL passée en paramètre. Sa signature TypeScript est la suivante :

declare const getOrigin: (url: string) => string;

Paramètres

nom	description	optionnel
url	URL pour laquelle on veut extraire l'origine	non

Exemple

getOrigin('https://obs.multistream.tools/v1/overlay.js'); // 'https://obs.multistream.tools'

getParams

La fonction getParams permet de construire un objet, sûr pour l'indexation, à partir d'une query string passée en paramètre. Sa signature TypeScript est la suivante :

type Params = {
  [key: string]: boolean | number | string | null | undefined;
};

declare const getParams: (queryString: string) => Params;

Paramètres

nom	description	optionnel
queryString	Query string avec ou sans '?' au début	non

info

Vous pouvez utiliser directement paramName et !paramName comme raccourcis pour respectivement paramName=true et paramName=false.

Exemple

getParams('?param1=a&param2=1&param3=-10.5&param4&!param5'); // { param1: 'a', param2: 1, param3: -10.5, param4: true, param5: false }

reloadPage

La fonction reloadPage permet de recharger la page courante. Sa signature TypeScript est la suivante :

declare const reloadPage: () => void;

showTab

La fonction showTab permet d'afficher un onglet donné (voir notre framework CSS) à partir d'un élément du DOM passé en paramètre, la navigation peut être optionnelle grâce au paramètre force. Sa signature TypeScript est la suivante :

declare const showTab: (element: HTMLElement, force?: false) => void;

Paramètres

nom	description	optionnel
element	Doit contenir une propriété id dont la valeur correspond à celle d'un onglet	non
force	Force (true) ou non (false) la navigation si un autre onglet est déjà affiché	oui (true par défaut)

Exemple

const tab1 = document.getElementById('tab1');
const tab2 = document.getElementById('tab2');

showTab(tab1);
showTab(tab2, false);

zoom

La constante nommée zoom correspond à la valeur passée en tant que paramètre système du même nom ; ou 1 par défaut.

queueDuration

La constante nommée queueDuration correspond à la valeur passée en tant que paramètre système du même nom ; ou 10 par défaut.

antiSpamDelta

La constante nommée antiSpamDelta correspond à la valeur passée en tant que paramètre système du même nom ; ou 1 par défaut.

antiSpamThreshold

La constante nommée antiSpamThreshold correspond à la valeur passée en tant que paramètre système du même nom ; ou 3 par défaut.

volume

La constante nommée volume correspond à la valeur passée en tant que paramètre système du même nom ; ou 1 par défaut.

HTTP

request

La fonction request permet d'initier des requêtes HTTP. Il s'agit d'un simple wrapper autour de la méthode window.fetch, fonctionnant exactement de la même manière que celle-ci, la seule différence étant ici qu'une erreur est bien renvoyée en cas de réponse en erreur.

DOM

prepend

La fonction prepend permet d'insérer du contenu au début d'un élément du DOM donné, une ou plusieurs valeurs sous la forme d'un tableau ; les valeurs dites falsy sont filtrées. Sa signature TypeScript est la suivante :

type Content = string | HTMLElement;

declare const prepend: (content: Content | Content[], host?: HTMLElement) => HTMLElement;

Paramètres

nom	description	optionnel
content	Contenu à insérer	non
host	Élément dans lequel insérer le contenu	oui (document.body par défaut)

Exemple

const world = document.createElement('p');
world.textContent = 'world';

prepend(['hello', world, null]); // document.body
prepend('hello world'); // document.body

append

La fonction append fonctionne de la même manière que la fonction prepend à la différence près qu'elle permet d'insérer du contenu à la fin d'un élément du DOM donné.

replaceChildren

La fonction replaceChildren fonctionne de la même manière que la fonction prepend à la différence près qu'elle permet de remplacer totalement le contenu d'un élément du DOM donné.

removeChildren

La fonction removeChildren permet de supprimer le contenu d'un élément du DOM donné. Sa signature TypeScript est la suivante :

declare const removeChildren: (host?: HTMLElement) => HTMLElement;

Paramètres

nom	description	optionnel
host	Élément pour lequel supprimer le contenu	oui (document.body par défaut)

Exemple

const hello = document.createElement('p');
hello.textContent = 'hello';

removeChildren(); // document.body
removeChildren(hello); // hello

setClasses

La fonction setClasses permet d'ajouter/retirer des classes CSS sur un élément du DOM, une ou plusieurs valeurs sous la forme d'un tableau ; les valeurs dites falsy sont filtrées. Sa signature TypeScript est la suivante :

declare const setClasses: (classes: string | string[], host?: HTMLElement, add?: false) => HTMLElement;

Paramètres

nom	description	optionnel
classes	Classes CSS à ajouter ou supprimer	non
host	Élément sur lequel ajouter/supprimer les classes	oui (document.body par défaut)
add	Ajouter (true) ou supprimer (false) les classes	oui (true par défaut)

Exemple

setClasses(['classA', 'classB']); // document.body
setClasses('classB', undefined, false); // document.body

setData

La fonction setData permet d'ajouter et réinitialiser des données sur un élément du DOM donné. Sa signature TypeScript est la suivante :

declare const setData: (data: object, host?: HTMLElement, reset?: true) => HTMLElement;

Paramètres

nom	description	optionnel
data	Données à ajouter à l'élément	non
host	Élément sur lequel ajouter/réinitialiser les données	oui (document.body par défaut)
reset	Réinitialiser (true) ou non (false) les données	oui (false par défaut)

Exemple

setData({ data1: 1 }); // document.body
setData({ data2: 2 }, undefined, true); // document.body
setData(null, undefined, true); // document.body

element

La fonction element permet de créer un élément du DOM en lui ajoutant optionnellement des classes CSS, du contenu, des données et des propriétés ; les valeurs dites falsy sont filtrées pour les classes CSS et le contenu. Sa signature TypeScript est la suivante :

type Content = string | HTMLElement;

type Properties = {
  classes?: string | string[];
  content: Content | Content[];
  data?: object;
  [key: string]: any;
};

declare const element: (tag: string, properties?: Properties) => HTMLElement;

Paramètres

nom	description	optionnel
tag	Type de balise de l'élément à créer	non
properties	Propriétés à initialiser sur l'élément créé	oui

Exemple

element('div'); // instanceof HTMLDivElement

element('p', {
  classes: 'classA',
  content: 'hello world',
  data: { data1: 1 },
  id: 'elementId'
}); // instanceof HTMLParagraphElement

button

La fonction button est un raccourci vers la fonction element permettant de créer des éléments de type button ; le paramètre properties reste inchangé. Sa signature TypeScript est la suivante :

type Type = 'button' | 'reset' | 'submit';

declare const button: (properties?: Properties, type?: Type) => HTMLButtonElement;

Paramètres

nom	description	optionnel
properties	Propriétés à initialiser sur le bouton créé	oui
type	Valeur à configurer pour la propriété type	oui ('button' par défaut)

Exemple

button(); // instanceof HTMLButtonElement
button({ content: 'Click me!' }, 'submit'); // instanceof HTMLButtonElement

img

La fonction img est un raccourci vers la fonction element permettant de créer des éléments de type img ; le paramètre properties reste inchangé. Sa signature TypeScript est la suivante :

type CrossOrigin = 'anonymous' | 'use-credentials' | '';

declare const img: (src: string, properties?: Properties, crossOrigin?: CrossOrigin) => HTMLImageElement;

Paramètres

nom	description	optionnel
src	Source de l'image à créer	non
properties	Propriétés à initialiser sur l'image crééé	oui
crossOrigin	Valeur à configurer pour la propriété crossOrigin	oui ('anonymous' par défaut)

Exemple

const src = 'https://example.com/image.jpg';

img(src); // instanceof HTMLImageElement
img(src, { classes: 'classA' }, 'use-credentials'); // instanceof HTMLImageElement

input

La fonction input est un raccourci vers la fonction element permettant de créer des éléments de type input ; le paramètre properties reste inchangé.

label

La fonction label est un raccourci vers la fonction element permettant de créer des éléments de type label ; le paramètre properties reste inchangé.

li

La fonction li est un raccourci vers la fonction element permettant de créer des éléments de type li ; le paramètre properties reste inchangé.

fieldset

La fonction fieldset est un raccourci vers la fonction element permettant de créer des éléments de type fieldset ; le paramètre properties reste inchangé.

div

La fonction div est un raccourci vers la fonction element permettant de créer des éléments de type div ; le paramètre properties reste inchangé.

span

La fonction span est un raccourci vers la fonction element permettant de créer des éléments de type span ; le paramètre properties reste inchangé.

enable

La fonction enable permet d'activer ou désactiver un élément du DOM (élément intéractif). Sa signature TypeScript est la suivante :

type Host = HTMLButtonElement | HTMLFieldSetElement | HTMLOptGroupElement | HTMLOptionElement | HTMLSelectElement | HTMLTextAreaElement | HTMLInputElement;

declare const enable: (host: Host, enabled?: false) => Host;

Paramètres

nom	description	optionnel
host	Élément à activer/désactiver	non
enabled	Activer (true) ou désactiver (false) l'élément	oui (true par défaut)

Exemple

const button = element('button');

enable(button); // button
enable(button, false); // button

getInputValue

La fonction getInputValue permet de récupérer la valeur de la propriété value d'un élément du DOM ; selon les paramètres passés en entrée, cette valeur peut être une liste. Sa signature TypeScript est la suivante :

type ValueNode = Node & {
  value: string;
};

type Host = ValueNode | RadioNodeList | undefined | null;

declare const getInputValue: (host: Host, multiple?: true) => any | any[];

Paramètres

nom	description	optionnel
host	Élément pour lequel récupérer la valeur de la propriété value	non
multiple	Indique si l'élément doit être traité comme une liste (true) ou non (false)	oui (false par défaut)

Exemple

const input = element('input', { value: 'hello world' });

getInputValue(input); // 'hello world'
getInputValue(input, true); // ['hello world']
getInputValue(undefined); // undefined
getInputValue(undefined, true); // []

crossOrigin

La fonction crossOrigin permet de configurer la valeur de la propriété crossOrigin d'un élément du DOM. Sa signature TypeScript est la suivante :

type Host = HTMLAudioElement | HTMLImageElement | HTMLLinkElement | HTMLScriptElement | HTMLVideoElement;

type Value = 'anonymous' | 'use-credentials' | '';

declare const crossOrigin: (host: Host, value?: Value) => Host;

Paramètres

nom	description	optionnel
host	Élément pour lequel configurer la valeur de la propriété crossOrigin	non
value	Valeur à configurer pour la propriété crossOrigin	oui ('anonymous' par défaut)

Exemple

const image = element('img');

crossOrigin(image); // image
crossOrigin(image, 'use-credentials'); // image

hide

La fonction hide permet de masquer ou afficher un élément du DOM donné en ajoutant ou retirant la classe CSS nommée hidden, exposée par notre framework CSS. Sa signature TypeScript est la suivante :

declare const hide: (hidden?: false, host?: HTMLElement) => HTMLElement;

Paramètres

nom	description	optionnel
hidden	Masque (true) ou affiche (false) l'élément donné	oui (true par défaut)
host	Élément à masquer ou afficher	oui (document.body par défaut)

Exemple

hide(); // document.body
hide(false); // document.body

setText

La fonction setText permet de modifier le contenu textuel d'un élément du DOM donné. Sa signature TypeScript est la suivante :

declare const setText: (text: string, host?: HTMLElement) => HTMLElement;

Paramètres

nom	description	optionnel
text	Nouveau contenu textuel pour l'élément donné	non
host	Élément pour lequel modifier le contenu textuel	oui (document.body par défaut)

Exemple

setText('hello world'); // document.body

setVariable

La fonction setVariable permet de configurer/supprimer la valeur d'une variable CSS sur un élément du DOM donné. Sa signature TypeScript est la suivante :

type Value = string | number | undefined | null;

declare const setVariable: (name: string, value: Value, host?: HTMLElement) => HTMLElement;

Paramètres

nom	description	optionnel
name	Nom de la variable CSS à configurer	non
value	Valeur de la variable CSS à configurer, undefined ou null pour supprimer	non
host	Élément sur lequel modifier la variable CSS	oui (document.documentElement par défaut)

Exemple

setVariable('hello world'); // document.body

selectAll

La fonction selectAll permet de récupérer un tableau (array) d'éléments du DOM à l'aide d'un sélecteur CSS. Sa signature TypeScript est la suivante :

declare const selectAll: (selector: string, host?: HTMLElement) => HTMLElement[];

Paramètres

nom	description	optionnel
selector	Sélecteur CSS pour localiser les éléments	non
host	Élément depuis lequel séléctionner les éléments	oui (document.documentElement par défaut)

Exemple

selectAll('meta'); // HTMLMetaElement[]
selectAll('div', body); // HTMLDivElement[]

selectOne

La fonction selectOne permet de récupérer un élément du DOM à l'aide d'un sélecteur CSS. Sa signature TypeScript est la suivante :

declare const selectOne: (selector: string, host?: HTMLElement) => HTMLElement | null;

Paramètres

nom	description	optionnel
selector	Sélecteur CSS pour localiser l'élément	non
host	Élément depuis lequel séléctionner l'élément	oui (document.documentElement par défaut)

Exemple

selectOne('meta'); // HTMLMetaElement
selectOne('div', body); // HTMLDivElement

Événements

ClickListener

La classe ClickListener est une sous-classe de la classe Listener décrite précédemment ; celle-ci sert à faciliter l'écoute d'événements de type click. Sa signature TypeScript est la suivante :

declare class ClickListener extends Listener {
  constructor(callback: Callback, host?: EventTarget, passive?: false);
}

Espace de nommage

Namespace

La classe Namespace sert à créer un espace de nommage dans le but d'éviter d'éventuelles collisions. Les clés générées sont automatiquement préfixées par l'origine de la page courante ; un suffixe personnalisé peut être ajouté si besoin. Sa signature TypeScript est la suivante :

declare class Namespace {
  constructor(suffix?: string, prefix?: string);
  key(name: string): string;
}

Paramètres

nom	description	optionnel
suffix	Suffixe personnalisé pour toutes les clés générées	oui
prefix	Préfixe personnalisé pour toutes les clés générées	oui (origin par défaut)

Méthodes

nom	description
key	Génère une clé préfixée pour éviter des conflits de nommage

Exemple

const namespaceA = new Namespace();
namespaceA.key('keyName'); // '<currentPageOrigin>.keyName'

const namespaceB = new Namespace('suffixName');
namespaceB.key('otherName'); // '<currentPageOrigin>suffixName.otherName'

Persistence

Store

La classe Store sert à sauvegarder des données dans le stockage local du navigateur ; il s'agit d'une sous-classe de la classe Namespace décrite précédemment. Les clés de stockage sont automatiquement préfixées par l'adresse (origin + pathName) de la page courante pour éviter, par défaut, tout éventuel conflit. Sa signature TypeScript est la suivante :

type Suffix = boolean | null | string;

declare class Store extends Namespace {
  constructor(suffix?: Suffix);
  set(key: string, value: any): void;
  get(key: string): any | null;
  remove(key: string): void;
}

Paramètres

nom	description	optionnel
suffix	Suffixe personnalisé pour toutes les clés générées, permet de partager un stockage plus facilement	oui (pathName par défaut)

astuce

Si la valeur du paramètre suffix est true, le préfixe automatique des clés de stockage s'arrêtera au répertoire contenant le ficher HTML courant. De cette manière il est plus simple de partager un même store entre différents fichiers HTML stockés au même niveau d'un même répertoire, sans avoir à définir un suffixe personnalisé.

Méthodes

nom	description
get	Récupère une valeur précédemment stockée pour une clé donnée
set	Stocke/écrase une valeur pour une clé donnée
remove	Supprime une valeur précédemment stockée pour une clé donnée

Exemple

const store = new Store();
const key = 'counter';

store.get(key); // null
store.set(key, 1);
store.set(key, 2);
store.get(key); // 2
store.remove(key);

Formulaires

Form

La classe Form sert à ajouter du comportement à un formulaire comme par exemple persister les valeurs de certains champs ; il s'agit d'une sous-classe de la classe Store décrite précédemment. Sa signature TypeScript est la suivante :

type ResetCallback = () => any;

type ChangeCallback = (name: string, element: HTMLElement) => any;

type SubmitCallback = (event: SubmitEvent) => any;

type Options = {
  persisted?: string[] | true;
  reset?: ResetCallback;
  change?: ChangeCallback;
  submit: SubmitCallback;
};

type Suffix = boolean | null | string;

type FieldBuilder = (removeButton: HTMLButtonElement) => HTMLElement;

declare class Form extends Store {
  constructor(host: HTMLFormElement, options: Options, suffix?: Suffix);
  buildRemovableField(fieldBuilder: FieldBuilder, buttonText?: string): HTMLElement;
  addRemovableFieldOnClick(clickHost: HTMLElement, addHost: HTMLElement, fieldBuilder: FieldBuilder, buttonText?: string): [ClickListener, CLickListener];
}

Paramètres

nom	description	optionnel
host	Élément de formulaire auquel ajouter le comportement	non
options	Objet décrivant le comportement à ajouter au formulaire	non
options.persisted	Liste de noms des champs (attribut name) dont la valeur (valide) doit être persistée, ou true pour tous	oui
options.reset	Fonction à appeler après un reset du formulaire si celui-ci a un bouton reset et que l'option persisted est utilisée	oui
options.change	Fonction à appeler au changement de valeur des champs persistés, si valides	oui
options.submit	Fonction à appeler à la soumission du formulaire (la méthode event.preventDefault est appelée en interne)	non
suffix	Suffixe personnalisé pour toutes les clés générées, permet de partager un stockage plus facilement	oui (pathName par défaut)

Méthodes

nom	description
buildRemovableField	Crée un champ pouvant être supprimé en cliquant sur un bouton
addRemovableFieldOnClick	Ajoute des champs, pouvant être supprimés, à une liste en cliquant sur un élément donné

info

La méthode addRemovableFieldOnClick appelle buildRemovableField en interne, notre dock s'appuie par exemple sur celle-ci dans son onglet Réglages. L'élément clickHost passé en paramètre est automatiquement activé.

Le texte du bouton de suppression par défaut est 'Remove' et la classe CSS danger lui est automatiquement ajoutée.

La valeur de retour de cette méthode est un tuple contenant deux instances de ClickListener, une pour l'écouteur d'ajout attaché à l'élément clickHost et l'autre pour l'écouteur de suppression attaché à l'élément addHost.

Le premier élément enfant de celui créé via la fonction fieldBuilder passée en paramètre, portant l'attribut required, recevra automatiquement le focus.

Exemple

const formElement = document.getElementById('form');

const form = new Form(formElement, {
  persisted: ['fieldA', 'fieldB'], // Pass `true` to persist all fields.
  reset() {
    console.log('reset');
  },
  change(fieldName, field) {
    console.log('change', fieldName, field);
  },
  submit(event) {
    console.log('submit', event);
  }
});

const itemBuilder = removeButton => li({
  content: [element('input'), removeButton]
});

form.buildRemovableField(itemBuilder); // instanceof HTMLLIElement

const addButton = document.getElementById('add');
const fieldsList = document.getElementById('list');

const [
  additionClickListener, // instanceof ClickListener
  removalClickListener // instanceof ClickListener
] = form.addRemovableFieldOnClick(addButton, fieldsList, itemBuilder, 'Delete');

additionClickListener.off();
removalClickListener.off();

File d'attente

Queue

La classe Queue sert à créer et gérer des files d'attente de type FIFO (First In First Out). Sa signature TypeScript est la suivante :

type Callback = () => void;

declare class Queue {
  constructor(duration?: number, manual?: true);
  add(onStart: Callback, onEnd?: Callback): void;
  pause(paused?: false): void;
  skip(): void;
  clear(): void;
  dispose(): void;
}

Paramètres

nom	description	optionnel
duration	Durée de la mise en attente, exprimée en secondes	oui (parameters.queueDuration par défaut)
manual	Réagit automatiquement (false) ou non (true) aux événements système pause et skip	oui (false par défaut)

Méthodes

nom	description
add	Ajoute un nouvel élément dans la file d'attente
pause	Met en pause ou reprend l'exécution de la file d'attente
skip	Passe directement à l'élément suivant dans la file d'attente, n'a aucun effet quand celle-ci est en pause
clear	Permet de totalement vider la file d'attente
dispose	Méthode de nettoyage à appeler, quand le paramètre manual vaut false, si l'instance n'est plus utilisée ou que l'on souhaite la déconnecter des événements système

info

Les fonctions onStart et onEnd sont respectivement appelées quand un élément commence à sortir de la file d'attente et après que celui-ci en soit totalement sorti. La fonction onEnd est optionnelle.

Exemple

const queue = new Queue(25);

[1, 2, 3].forEach(number => queue.add(
  () => console.log('onStart', number),
  () => console.log('onEnd', number)
));

queue.pause();
queue.pause(false);
queue.skip();
queue.clear();
queue.dispose();

Spam

AntiSpam

La classe AntiSpam sert à vérifier qu'une action donnée n'est pas considérée comme du spam. Sa signature TypeScript est la suivante :

declare class AntiSpam {
  constructor(threshold?: number, delta?: number);
  check(action: any): boolean;
}

Paramètres

nom	description	optionnel
threshold	Nombre de maximum de répétitions acceptées pour une même action	oui (parameters.antiSpamThreshold par défaut)
delta	Durée après laquelle une même action ne sera plus considérée comme du spam, exprimée en secondes	oui (parameters.antiSpamDelta par défaut)

Méthodes

nom	description
check	Retourne true si l'action donnée n'est pas considérée comme du spam, false à l'inverse

Exemple

const antiSpam = new AntiSpam(2, 0.5);
const action = 'action';

antiSpam.check(action); // true
antiSpam.check(action); // true
antiSpam.check(action); // false

Audio

Sound

La classe Sound sert à jouer des fichiers audio ; il s'agit d'une sous-classe de la classe Audio native, ajoutant simplement des commodités manquantes. Sa signature TypeScript est la suivante :

type CrossOrigin = 'anonymous' | 'use-credentials' | '';

declare class Sound extends Audio {
  constructor(url: string, volume?: number, crossOrigin?: CrossOrigin, manual?: true);
  stop(): void;
  mute(muted?: false): void;
  dispose(): void;
}

Paramètres

nom	description	optionnel
url	Adresse du fichier audio à charger	non
volume	Volume de lecture du fichier audio, entre 0 et 1	oui (parameters.volume par défaut)
crossOrigin	Valeur à configurer pour la propriété crossOrigin	oui ('anonymous' par défaut)
manual	Réagit automatiquement (false) ou non (true) aux événements système mute	oui (false par défaut)

Méthodes

nom	description
stop	Stoppe totalement la lecture du fichier audio
mute	Coupe (true) ou remet (false) le son sans arrêter la lecture du fichier audio
dispose	Méthode de nettoyage à appeler, quand le paramètre manual vaut false, si l'instance n'est plus utilisée ou que l'on souhaite la déconnecter des événements système

Exemple

const sound = new Sound('<fileURL>', 0.5);

sound.play();
sound.mute();
sound.mute(false);
sound.stop();
sound.dispose();

Communication

Emitter

La classe Emitter sert à émettre des événements personnalisés dans notre système en créant des émetteurs dédiés. Sa signature TypeScript est la suivante :

declare class CustomEvent {
  emit(data?: any, otherProperties?: object): void;
  toString(): string;
}

declare class Emitter {
  constructor(crossOrigin?: boolean, namespace?: string);
  [eventName: string]: CustomEvent;
}

Paramètres

nom	description	optionnel
crossOrigin	Indique si les événements émis peuvent être reçus par des overlays d'origines différentes (true)	oui (false par défaut)
namespace	Ajoute un espace de nommage aux événements émis, conseillé quand crossOrigin vaut true	oui

Exemple

const { customEvent } = new Emitter();
const props = { key: 'value' };
const data = { props };

customEvent.emit(); // Emitted event: { category: '<namespace>.customEvent' }
customEvent.emit(data); // Emitted event: { category: '<namespace>.customEvent', data }
customEvent.emit(data, props); // Emitted event: { category: '<namespace>.customEvent', data, ...props }
customEvent.emit(undefined, props); // Emitted event: { category: '<namespace>.customEvent', ...props }

Observer

La classe Observer sert à écouter les événements émis dans notre système, natifs ou personnalisés ; il s'agit d'une sous-classe de la classe Listener décrite précédemment. Sa signature TypeScript est la suivante :

type Id = string;

type AlertData = {
  name: string;
  sender?: string;
  message?: string;
  tier?: string;
  amount?: number;
};

type SessionData = {
  [key: string]: object | object[];
};

type LoadData = {
  session: SessionData;
};

type ChatData = object;

type MessageData = {
  renderedText: string;
  data: {
    userId: Id;
    msgId: Id;
    nick: string;
    displayName: string;
  };
};

type DeleteMessageData = {
  msgId: Id;
};

type DeleteMessagesData = {
  userId: Id;
};

type OtherData = object;

type Event<T = undefined, U = undefined> = {
  data: T;
  event: U;
  [key: string]: any;
};

type PlatformEvent<T, U = undefined> = Event<T, U> & {
  platform: string;
  group?: Id;
  root?: true;
};

type Callback<T> = (event: T) => any;

type SystemEvents = {
  load?: Callback<PlatformEvent<LoadData>>;
  session?: Callback<PlatformEvent<SessionData>>;
  alerts?: Callback<PlatformEvent<AlertData, string>>;
  chat?: Callback<
    PlatformEvent<MessageData, 'message'> |
    PlatformEvent<DeleteMessageData, 'delete-message'> |
    PlatformEvent<DeleteMessagesData, 'delete-messages'> |
    PlatformEvent<ChatData, string>
  >;
  other?: Callback<PlatformEvent<OtherData, string>>;
  mute?: Callback<Event<boolean>>;
  pause?: Callback<Event<boolean>>;
  skip?: Callback<Event>;
};

type CustomEvents = {
  [key: string]: Callback<Event<any, any>>;
};

type Events = SystemEvents | CustomEvents;

declare class Observer extends Listener {
  constructor(events: Events);
}

Parameters

nom	description	optionnel
events	Objet listant les fonctions à appeler à la réception d'événements donnés	non

Exemple

const logger = type => data => console.log(type, data);

const { customEvent } = new Emitter();

const observer = new Observer({
  // System events.
  load: logger('load'),
  session: logger('session'),
  alerts: logger('alerts'),
  chat: logger('chat'),
  other: logger('other'),
  mute: logger('mute'),
  pause: logger('pause'),
  skip: logger('skip'),
  // OBS related system events.
  getCurrentScene: logger('getCurrentScene'),
  obsSceneChanged: logger('obsSceneChanged'),
  // Custom event.
  [customEvent]: logger(customEvent.toString())
});

observer.off();
observer.on();

OBS

obsAPI

L'objet obsAPI permet de faire appel à l'API JavaScript d'OBS en créant des émetteurs d'événements dédiés ou en récupérant des noms d'événements à observer, la liste complète des possibiltés est disponible sur cette page. Sa signature TypeScript est la suivante :

declare class OBSEvent {
  emit(...args: any[]): void;
  toString(): string;
}

declare const obsAPI: { [eventName: string]: OBSEvent | string };

Exemple

const {
  SceneChanged,
  pluginVersion,
  getCurrentScene,
  setCurrentScene,
  stopStreaming
} = obsAPI;

new Observer({
  [SceneChanged]({ data }) {
    // Do whatever you want with the data here.
    // `data.name` contains the name of the new scene.
  },
  [pluginVersion]({ data }) {
    // Do whatever you want with the value here.
  },
  [getCurrentScene]({ data }) {
    // Do whatever you want with the value here.
  }
});

// Getters.
pluginVersion.emit();
getCurrentScene.emit();

// Setters.
setCurrentScene.emit('new scene name');
stopStreaming.emit();

Theming

loadStyles

La fonction loadStyles permet de charger une feuille de styles donnée. Sa signature TypeScript est la suivante :

type CrossOrigin = 'anonymous' | 'use-credentials' | '';

declare const loadStyles: (url: string, crossOrigin: CrossOrigin) => HTMLLinkElement;

Parameters

nom	description	optionnel
url	Adresse de la feuille de styles à charger (URL locale, distante ou de données)	non
crossOrigin	Valeur à configurer pour la propriété crossOrigin	oui ('anonymous' par défaut)

Example

loadStyles('<stylesheetURL>'); // instanceof HTMLLinkElement
loadStyles('<stylesheetDataURL>', 'use-credentials'); // instanceof HTMLLinkElement

loadFonts

La fonction loadFonts permet de charger des polices de caractères via l'API Google Fonts et de les appliquer par le biais des variables CSS --fontFamily1 à --fontFamilyN. Sa signature TypeScript est la suivante :

declare const loadFonts: (query: string) => HTMLLinkElement | false;

attention

Si le paramètre global nommé fonts est utilisé, soit pour modifier les polices soit pour les désactiver, tout appel à la fonction loadFonts n'aura aucun effet et la valeur de retour sera false.

Vous ne devez appeler cette fonction qu'une seule fois pour charger toutes les polices dont vous auriez besoin ; utilisez ensuite les variables CSS pour permuter dynamiquement ces polices, si vous le souhaitez.

La valeur du paramètre family de l'API Google Fonts doit toujours venir en premier et la valeur du paramètre display est block par défaut.

Parameters

nom	description	optionnel
query	Requête Google Fonts, sans ?family=	non

Example

loadFonts('Droid+Sans|Tangerine:bold&display=auto'); // instanceof HTMLLinkElement or false

Internationalisation

defaultLang

La constante nommée defaultLang correspond à la valeur par défaut de l'attribut lang positionné sur la balise html de la page Web associée à votre overlay/dock.

attention

Il est important de toujours affecter une valeur par défaut à cet attribut pour des raisons d'accessibilité et que notre système d'internationalisation puisse fonctionner correctement. Par exemple :

<html lang="en"></html>

currentLang

La constante nommée currentLang correspond à la valeur passée en tant que paramètre système nommé lang ; ou à celle de la propriété navigator.language par défaut, soit la langue du navigateur affichant la page Web de votre overlay/dock (en l'occurrence celle de l'interface utilisateur d'OBS).

i18n

La fonction i18n permet d'aider à la traduction de messages. Vous ne devriez appeller celle-ci qu'une seule fois et seulement si votre overlay/dock doit être traduit dans plusieurs langues. Sa signature TypeScript est la suivante :

type Translations = {
  [lang: string]: object;
};

declare const i18n: (translations?: Translations) => object;

Paramètres

nom	description	optionnel
translations	Objets contenant des données de traduction, indexées par langage	oui

Exemple

// Given `lang="en"` on `html` tag, `'fr'` as `lang` system parameter value
// and `<div data-i18n="hello">Hello</div>` in `body` element.

i18n().hello; // 'Hello' (default value)

// 'Bonjour'
const { hello } = i18n({
  fr: { hello: 'Bonjour' },
  es: { hello: 'Holà' }
});

document.documentElement.lang; // 'fr'

info

Quand aucune donnée de traduction n'est passé en paramètre, la fonction i18n synchronise simplement la valeur de l'attribut lang, sur la balise html de la page, avec celle de la constante nommée currentLang décrite ci-dessus ; ce qui peut être utile lorsque vous souhaitez gérer les traductions d'une autre manière.

Quand des données de traduction sont passée en paramètre, la fonction i18n cherche à déterminer la correspondance la plus proche entre les langues définies et la valeur de la constante nommée currentLang ; cette correspondance, si trouvée, est ensuite appliquée comme valeur de l'attribut lang sur la balise html de la page. Par exemple :

// Given `lang="fr"` on `html` tag and `'en-US'` as `lang` system parameter value.

// 'Color'
const { color } = i18n({
  'en-GB': { color: 'Colour' },
  en: { color: 'Color' }
});

document.documentElement.lang; // 'en'

Dans les deux cas, la fonction i18n parcourt chaque élément DOM de la page possédant un attribut data-i18n et :

• remplace son contenu textuel automatiquement par toute éventuelle donnée de traduction, de type string, dont la clé correspond à la valeur de l'attribut data-i18n en question
• récupère/retourne son contenu textuel quand aucune donnée de traduction n'est définie pour la clé en question

La valeur de retour de la fonction i18n est donc on objet contenant la fusion des données de traduction pour la langue souhaitée (si définies) et de celles de la langue par défaut. Cet objet est sûr pour l'indexation.

astuce

Il est également possible de définir des données de traduction de types autres que string, elle ne seront simplement pas appliquées automatiquement mais manuellement, comme vous le désirez. Par exemple :

const helloEN = user => `Hello ${user}!`;

const helloFR = user => `Bonjour ${user} !`;

const { hello = helloEN } = i18n({ fr: { hello: helloFR } });

setText(hello('TheFrenchBiff'));

Vous pouvez aussi passer des données de traduction pour la langue par défaut, ce qui peut être notamment utile dans le cas de messages dynamiques ne faisant pas partie du contenu initial de la page (contenu pour lequel on préférerait l'utilisation des attributs data-i18n précédemment évoqués).

// Given `lang="en"` on `html` tag, `'fr'` as `lang` system parameter value
// and `<div data-i18n="hello">Hello</div>` in `body` element.

const {
  hello, // 'Bonjour'
  you, // 'toi'
  message // 'message'
} = i18n({
  [defaultLang]: { you: 'you', message: 'message' },
  fr: { hello: 'Bonjour', you: 'toi' }
});

Notez qu'il est tout à fait possible d'omettre toute donnée de traduction pour laquelle la valeur n'est pas différente de celle par défaut.

Pour un exemple pratique, rendez-vous sur notre page dédiée au développement d'overlays.