cantoo-web-docs

Documentation for Cantoo Web

Intégration du script Cantoo Web

Ce projet permet d'ajouter facilement les fonctionnalités d'accessibilité de Cantoo Web à vos pages HTML.

🔧 Intégration

Pour intégrer le script à votre site, ajoutez simplement la balise suivante dans les pages HTML où vous souhaitez l'activer :

<script
  type="module"
  src="https://download.cantoo.fr/cantoo-web-xxx.js"
  defer
></script>

Remplacez xxx par le nom de votre projet, qui vous a été communiqué lors de notre collaboration.

---

📦 Installation via npm

Si vous utilisez un environnement Node.js ou un bundler moderne (Webpack, Vite, etc.), vous pouvez installer la bibliothèque via npm :

npm install @cantoo/cantoo-web

ou avec yarn :

yarn add @cantoo/cantoo-web

Utilisation de la fonction loadCantoo

La bibliothèque npm expose une fonction loadCantoo qui charge dynamiquement le script Cantoo Web et retourne une promesse avec l'objet global Cantoo :

import { loadCantoo } from "@cantoo/cantoo-web";

// Charger le script Cantoo Web
loadCantoo("https://download.cantoo.fr/cantoo-web-xxx.js")
  .then((Cantoo) => {
    console.log("Cantoo Web chargé avec succès");

    // Ou charger des paramètres personnalisés
    Cantoo.load({
      "vocal-dictation": {
        lang: "fr-FR",
      },
      "vocal-reading": {
        lang: "fr-FR",
        rate: 1.0,
      },
      "accessibility-options": {
        fontSize: 16,
        lineSpacing: 1.5,
      },
      "plugin-options": {
        language: "fr",
        activeOptions: [
          "vocalRecognition",
          "vocalSynthesis",
          "textCustomization",
        ],
      },
    });
  })
  .catch((error) => {
    console.error("Erreur lors du chargement de Cantoo Web:", error);
  });

Support TypeScript

La bibliothèque inclut des définitions TypeScript complètes pour l'API Cantoo Web. Vous bénéficiez ainsi de l'autocomplétion et de la vérification de types dans votre IDE :

import {
  loadCantoo,
  type Cantoo,
  type CantooWebData,
  type SetConfigParams,
} from "@cantoo/cantoo-web";

// Types disponibles pour l'objet Cantoo et ses paramètres
const params: CantooWebData = {
  "vocal-dictation": { lang: "fr-FR" },
  "vocal-reading": { lang: "fr-FR", rate: 1.0 },
  "accessibility-options": {},
  "plugin-options": {},
};

loadCantoo("https://download.cantoo.fr/cantoo-web-xxx.js").then(
  (cantoo: Cantoo) => {
    cantoo.load(params);
    const tweaks: SetConfigParams = { "plugin-options": { language: "fr" } };
    cantoo.setConfig(tweaks);
  },
);

Note : Remplacez xxx par le nom de votre projet dans l'URL du script.

---

🔄 Mises à jour

Les mises à jour du script sont automatiques. Aucune action n'est nécessaire de votre part pour bénéficier des dernières fonctionnalités et corrections.

---

🌐 Options : Élément global Cantoo

Une fois intégré, vous bénéficiez déjà de l'adaptation offerte par Cantoo Web et vous n'avez rien à faire. Toutefois, si vous souhaitez un niveau d'intégration plus fin, ou mettre à profit les fonctionnalités de Cantoo Web pour améliorer votre produit, le script expose un objet global nommé Cantoo contenant plusieurs fonctionnalités clés, permettant de contrôler les fonctionnalités de l'outil :

/**
 * Objet global Cantoo exposé par le script Cantoo Web.
 */
declare const Cantoo: {
  speech2text: Speech2Text;
  text2speech: Text2Speech;
  writeTextOnInput: (spokenText: string, inputTarget?: HTMLElement) => void;
  openCantooWebConfig: () => void;
  formatText: (html: string) => string;
  login: (login: string, password: string) => Promise<void>;
  logout: () => void;
  activate: () => void;
  deactivate: () => void;
  load: (params: CantooWebData) => void;
  setConfig: (params: SetConfigParams) => void;
  addParameterChangeListener: (listener: (params: CantooWebData) => void) => void;
  removeParameterChangeListener: (listener: (params: CantooWebData) => void) => void;
  addUsageEventListener: (listener: (event: UsageEvent) => void) => void;
  removeUsageEventListener: (listener: (event: UsageEvent) => void) => void;
};

/**
 * Types de données pour la dictée vocale.
 */
type VocalDictationData = {
  lang?: string;
};

/**
 * Types de données pour la lecture vocale.
 */
type VocalReadingData = {
  lang?: string;
  voice?: string;
  rate?: number;
  delay?: number;
};

/**
 * Types de données pour les options de plugin.
 */
type PluginOptionsData = {
  textExtractionOnModal?: boolean;
  activeOptions?: Array<'vocalRecognition' | 'vocalSynthesis' | 'textCustomization' | 'translator' | 'dictionary' | 'visualAssistance' | 'floatingBar' | 'readMode'>;
  language?: string;
};

/**
 * Interface définissant la structure des données de configuration Cantoo Web.
 * Cette interface est un enregistrement (Record) avec des clés spécifiques.
 */
interface CantooWebData {
  'vocal-dictation': VocalDictationData;
  'vocal-reading': VocalReadingData;
  'accessibility-options': AccessibilityOptions;
  'plugin-options': PluginOptionsData;
}

/** Mise à jour partielle — objet ou fonction recevant la config courante. */
type SetConfigParams =
  | Partial<CantooWebData>
  | ((current: CantooWebData) => Partial<CantooWebData>);

/**
 * Options d'accessibilité.
 */
interface AccessibilityOptions {
  wordSpacing?: number;
  syllableSpacing?: number;
  lineSpacing?: number;
  letterSpacing?: number;
  fontSize?: number;
  fontFamily?: string;

  syllableSeparator?: '|' | '-' | '/' | '+' | '·';
  colorByMode?: 'word' | 'syllable' | 'sound';
  colorSet?: string[];
  soundsColors?: { [sound: string]: string };
  soundsBackgroundColors?: Record<string, string>;
  specialStrategy?: {
    type?: 'bionic' | 'bounds' | 'sounds' | 'silent';
    bold?: boolean;
    color?: string;
  };

  vocalSynthesis?: boolean;
  vocalSynthesisSpeed?: number;
  vocalSynthesisFeedbackDelay?: number;
  vocalSynthesisKeyboardFeedback?: boolean;
  vocalSynthesisButtonFeedback?: boolean;
  vocalSynthesisLabelFeedback?: boolean;
  vocalSynthesisWritingFeedback?: boolean;

  magnifier?: boolean;
  magnifierZoom?: number;
  dictionary?: boolean;
  translator?: boolean;
  contrastMode?: 'highContrast' | 'darkMode';
  invertImages?: boolean;
  readBand?: boolean;
  bandWidth?: number;
  bandOpacity?: number;
}

🗣️ speech2text — Reconnaissance vocale (dictée)

/**
 * Gestion de la dictée vocale (reconnaissance vocale).
 */
interface Speech2Text {
  /**
   * Indique si la dictée est actuellement en cours.
   */
  isListening: boolean;

  /**
   * Démarre la reconnaissance vocale.
   *
   * @param onResult - Fonction appelée avec les résultats de la dictée.
   * @param localeProp - (optionnel) Code de langue à utiliser (ex: "fr-FR"). Si non fourni, la langue est déduite automatiquement.
   * @param onStartDownloadModel - (optionnel) Callback appelé au début du téléchargement d’un modèle vocal si nécessaire.
   * @param onEndDownloadModel - (optionnel) Callback appelé à la fin du téléchargement d’un modèle vocal.
   * @returns Une promesse qui se résout lorsque la dictée démarre.
   * @throws Une erreur si aucun locale n’est fourni ou détectable, si la Speech API n’est pas disponible ou si les permissions sont refusées.
   */
  start: (
    onResult: (results?: string[]) => void,
    localeProp?: string,
    onStartDownloadModel?: () => void,
    onEndDownloadModel?: () => void
  ) => Promise<void>;

  /**
   * Arrête la reconnaissance vocale.
   * @returns Une promesse qui se résout lorsque la dictée est arrêtée.
   */
  stop: () => Promise<void>;
}

🔊 text2speech — Synthèse vocale (lecture de texte)

/**
 * Gestion de la synthèse vocale (text-to-speech).
 */
interface Text2Speech {
  /**
   * Liste toutes les voix disponibles sur le système.
   * @returns Un tableau de voix utilisables.
   */
  readVoices: () => Voice[];

  /**
   * Retourne une voix à partir de son identifiant.
   * @param voiceId - Identifiant de la voix.
   * @returns L’objet SpeechSynthesisVoice correspondant.
   */
  getVoice: (voiceId: string) => SpeechSynthesisVoice;

  /**
   * Utterance en cours, si applicable.
   */
  utter: SpeechSynthesisUtterance;

  /**
   * Instance native de synthèse vocale, ou undefined si non disponible.
   */
  synth: SpeechSynthesis | undefined;

  /**
   * Lit un texte à haute voix.
   * @param readText - Le texte à lire.
   */
  readText: (readText: string) => void;

  /**
   * Configure les paramètres de synthèse vocale.
   * @param config - Objet de configuration.
   */
  setConfig: (config: {
    voice: string;
    lang: string;
    volume?: number;
    rate?: number;
    pitch?: number;
  }) => void;

  /**
   * Récupère la configuration actuelle de synthèse vocale.
   * @returns Les paramètres configurés.
   */
  getConfig: () => {
    voice: string | undefined;
    lang: string;
    volume: number;
    rate: number;
    pitch: number;
  };
}

🧠 writeTextOnInput — Insertion de texte dicté

/**
 * Insère un texte dicté dans un champ de saisie HTML.
 *
 * @param spokenText - Le texte à insérer.
 * @param inputTarget - (optionnel) L'élément HTML cible. Si non défini, le focus actuel est utilisé.
 */
declare function writeTextOnInput(spokenText: string, inputTarget?: HTMLElement): void;

⚙️ openCantooWebConfig — Ouverture de l’interface de configuration

/**
 * Ouvre l’interface de configuration utilisateur Cantoo Web.
 */
declare function openCantooWebConfig(): void;

🎨 formatText — Application des préférences d’accessibilité

/**
 * Applique les préférences d’accessibilité de l’utilisateur à un contenu HTML.
 *
 * @param html - Le HTML d’origine.
 * @returns Le HTML transformé avec les préférences appliquées.
 */
declare function formatText(html: string): string;

🔐 login — Connexion utilisateur

/**
 * Connecte un utilisateur à la base de données Cantoo.
 *
 * ⚠️ Un protocole doit être mis en place avec l’équipe Cantoo pour permettre l’enregistrement.
 *
 * @param login - Identifiant de l'utilisateur.
 * @param password - Mot de passe de l'utilisateur.
 * @returns Une promesse résolue à la fin de la connexion.
 */
declare function login(login: string, password: string): Promise<void>;

/**
 * Déconnecte l’utilisateur actuellement connecté.
 */
declare function logout(): void;

🟢 activate — Activer Cantoo Web

/**
 * Active toutes les fonctionnalités de Cantoo Web sur la page.
 */
declare function activate(): void;

🔴 deactivate — Désactiver Cantoo Web

/**
 * Désactive toutes les fonctionnalités de Cantoo Web sur la page.
 */
declare function deactivate(): void;

📥 load — Charger les paramètres de configuration

/**
 * Charge les paramètres de configuration de Cantoo Web.
 *
 * @param params - Les paramètres de configuration à charger.
 */
declare function load(params: CantooWebData): void;

🔧 setConfig — Mettre à jour partiellement la configuration

Contrairement à load, qui remplace le jeu de paramètres via l’événement cantooLoadParameters, setConfig applique une mise à jour partielle : seules les sections et champs fournis sont modifiés ; le reste de la configuration en cours est conservé. Pour chaque section (dictée, lecture, accessibilité, options du plugin), les nouvelles valeurs sont fusionnées avec les valeurs déjà stockées (fusion superficielle d’objet).

setConfig accepte deux formes :

• Un objet Partial<CantooWebData> — les sections fournies sont fusionnées directement.
• Une fonction (current: CantooWebData) => Partial<CantooWebData> — reçoit la configuration courante et retourne les sections à modifier (comme un setState React).

Le traitement prend effet lorsque l’extension a fini de charger ses paramètres initiaux ; techniquement, setConfig envoie un CustomEvent nommé cantooSetConfig sur document, avec le même détail que l’objet passé en argument.

/**
 * Met à jour partiellement la configuration Cantoo Web (merge par section).
 *
 * @param params - Objet partiel ou fonction recevant la config courante.
 */
declare function setConfig(params: SetConfigParams): void;

Exemples :

// Uniquement la taille de police et la vitesse de lecture, sans toucher au reste
window.Cantoo.setConfig({
  "accessibility-options": { fontSize: 18 },
  "vocal-reading": { rate: 1.1 },
});

// Activer le mode sombre
window.Cantoo.setConfig({
  "accessibility-options": { contrastMode: "darkMode" },
});

// Activer le mode haut contraste
window.Cantoo.setConfig({
  "accessibility-options": { contrastMode: "highContrast" },
});

// Activer la loupe (magnifier)
window.Cantoo.setConfig({
  "accessibility-options": { magnifier: true, magnifierZoom: 2 },
});

// Activer le bandeau de lecture
window.Cantoo.setConfig({
  "accessibility-options": { readBand: true, bandWidth: 80, bandOpacity: 0.5 },
});

// Inverser les images (utile en combinaison avec le mode sombre)
window.Cantoo.setConfig({
  "accessibility-options": { contrastMode: "darkMode", invertImages: true },
});

// Utiliser une fonction pour lire la config courante (comme un setState React)
window.Cantoo.setConfig((current) => {
  const rate = current["vocal-reading"]?.rate ?? 1;
  return {
    "vocal-reading": { rate: Math.min(rate + 0.1, 2) },
  };
});

// Toggle du mode sombre en fonction de l'état actuel
window.Cantoo.setConfig((current) => ({
  "accessibility-options": {
    contrastMode:
      current["accessibility-options"]?.contrastMode === "darkMode"
        ? undefined
        : "darkMode",
  },
}));

👂 addParameterChangeListener — Ajouter un écouteur de changement de paramètres

/**
 * Ajoute un écouteur pour les changements de paramètres de configuration.
 *
 * @param listener - Fonction appelée lors des changements de paramètres.
 */
declare function addParameterChangeListener(
  listener: (params: CantooWebData) => void
): void;

🗑️ removeParameterChangeListener — Supprimer un écouteur de changement de paramètres

/**
 * Supprime un écouteur de changement de paramètres précédemment ajouté.
 *
 * @param listener - L'écouteur à supprimer.
 */
declare function removeParameterChangeListener(
  listener: (params: CantooWebData) => void
): void;

📊 addUsageEventListener — Ajouter un écouteur d'événements d'utilisation

/**
 * Type d'événement d'utilisation de Cantoo Web.
 */
type UsageEvent =
  | "CANTOO_READ_TEXT"
  | "CANTOO_ADAPT_TEXT"
  | "CANTOO_DICTATE_TEXT"
  | "CANTOO_TRANSLATED_TEXT"
  | "CANTOO_DEFINED_TEXT";

/**
 * Ajoute un écouteur pour les événements d'utilisation de Cantoo Web.
 * Permet de suivre les actions effectuées par les utilisateurs.
 *
 * @param listener - Fonction appelée lors des événements d'utilisation.
 */
declare function addUsageEventListener(
  listener: (event: UsageEvent) => void
): void;

Exemple d'utilisation :

Cantoo.addUsageEventListener((event) => {
  console.log("Événement d'utilisation:", event);
  // Exemple: "CANTOO_READ_TEXT" lorsqu'un utilisateur utilise la synthèse vocale
});

🗑️ removeUsageEventListener — Supprimer un écouteur d'événements d'utilisation

/**
 * Supprime un écouteur d'événements d'utilisation précédemment ajouté.
 *
 * @param listener - L'écouteur à supprimer.
 */
declare function removeUsageEventListener(
  listener: (event: UsageEvent) => void
): void;

---

🎯 Désactivation sur certains éléments

🚫 Classe CSS cantoo-ignore-vocal-recognition - Désactiver la reconnaissance vocale

Si vous souhaitez gérer manuellement la dictée vocale dans certains champs de saisie, vous pouvez utiliser la classe CSS cantoo-ignore-vocal-recognition. Vous pourrez alors créer votre propre bouton pour déclencher et arrêter la reconnaissance vocale et l'ajouter à votre propre barre d'outils

<!-- Cet input n'aura pas le bouton de dictée vocale inséré automatiquement -->
<input type="text" class="cantoo-ignore-vocal-recognition" />

Cette classe empêche l’insertion automatique du bouton de dictée vocale dans l’élément ciblé. Vous pouvez ainsi utiliser les fonctions de l’API window.Cantoo.speech2text pour implémenter votre propre logique de traitement, et placer le bouton dans votre barre d’outils ou à l’emplacement de votre choix.

🚫 Classe CSS cantoo-ignore-hover-events - Désactiver la barre d'outils au survol

Si vous souhaitez empêcher l’affichage du Tooltip Cantoo lors du survol d’un élément ou de ses enfants, ajoutez la classe CSS cantoo-ignore-hover-events à cet élément.

<!-- Aucun Tooltip Cantoo ne sera affiché lors du survol de cet élément ou de ses enfants -->
<div class="cantoo-ignore-hover-events">...</div>

Cette classe désactive l’apparition du Tooltip Cantoo sur l’élément ciblé ainsi que sur tous ses descendants lors d’un survol avec la souris.

ℹ️ Note : Il reste possible de sélectionner du texte dans ces éléments pour l’adapter, même si le Tooltip n’apparaît pas au survol.

🚫 Classe CSS cantoo-ignore-all - Désactiver complètement Cantoo Web sur un élément

Si vous souhaitez empêcher toute interaction Cantoo Web (barre d'outils au survol et barre d'outils lors de la sélection) sur un élément, ajoutez la classe CSS cantoo-ignore-all à cet élément.

<!-- Cantoo Web sera totalement désactivé sur cet élément -->
<div class="cantoo-ignore-all">...</div>

Cette classe désactive à la fois l’apparition du Tooltip Cantoo au survol et l’apparition de la barre d'outils lors de la sélection sur l’élément ciblé et ses descendants.

---

❓ Assistance

Pour toute question ou pour obtenir un nom de projet, veuillez contacter notre équipe Cantoo.

---

© Cantoo - Tous droits réservés.