Quoi de neuf dans l’API ONLYOFFICE 9.4 : guide du développeur sur les dernières mises à jour

La version 9.4 d’ONLYOFFICE introduit des améliorations majeures de l’API pour les intégrations, les plugins personnalisés et l’automatisation des feuilles de calcul. Cet article met en lumière les principales mises à jour de l’API ONLYOFFICE Docs, de l’API de plugins et macros et de l’API JavaScript Office, et explique ce qu’elles signifient pour les développeurs.

API ONLYOFFICE Docs 9.4

Support de la langue croate

Le croate (hr) a été ajouté à la liste des langues d’interface prises en charge. Si vous développez des applications localisées pour les utilisateurs parlant croate, vous pouvez l’inclure dans votre configuration linguistique sans contournements.

Données de rôle et d’utilisateur dans l’événement onStartFilling

L’événement onStartFilling inclut maintenant un paramètre roles qui transporte des informations sur le rôle et l’utilisateur. Cela facilite la création d’expériences de remplissage de formulaires conscientes des rôles, par exemple, en dirigeant les utilisateurs vers les champs pour lesquels ils sont responsables ou en déclenchant une logique conditionnelle en fonction de qui remplit le formulaire et dans quelle capacité.

function onStartFilling(event) {
  const roles = event.data;
  console.log("Rôles :", roles);
}

const config = {
  // ...
  events: {
    onStartFilling,
  },
};
const docEditor = new DocsAPI.DocEditor("placeholder", config);

Correction de fuite de mémoire dans destroyEditor

Une fuite de mémoire dans la méthode destroyEditor a été corrigée. Auparavant, l’appel à destroyEditor ne nettoyait pas complètement les ressources allouées. Si votre application crée et détruit fréquemment des instances de l’éditeur, par exemple dans des configurations d’application à page unique ou des flux de prévisualisation de documents, cette correction améliore directement l’empreinte mémoire de votre intégration au fil du temps.

Champ supprimé

Le champ obsolète editorConfig.customization.commentAuthorOnly a été supprimé. Si votre intégration fait toujours référence à ce paramètre, il est maintenant temps de le retirer pour éviter tout comportement inattendu.

Journalisation des commandes de plugin pour un débogage plus facile

L’un des ajouts les plus pratiques pour les développeurs de plugins est la journalisation des commandes de plugin. Activez la sortie de débogage des commandes de plugin directement dans la console du navigateur. Si vous avez passé du temps à déboguer le comportement des plugins en devinant quelles commandes sont réellement exécutées, cette fonctionnalité supprime une quantité significative de friction. Elle vous donne une visibilité directe sur le flux d’exécution du plugin sans avoir besoin d’instrumenter votre propre journalisation.

Blocage de plugins spécifiques au chargement

Le nouveau paramètre editorConfig.plugins.disable vous permet d’empêcher des plugins spécifiques de se charger lors de l’initialisation de l’éditeur. Cela est utile lorsque vous intégrez l’éditeur dans un environnement contrôlé et que vous souhaitez restreindre la fonctionnalité à ce qui est pertinent pour vos utilisateurs, sans avoir à modifier les fichiers de plugin eux-mêmes. C’est une approche plus propre, au niveau de la configuration, pour gérer la surface des plugins.

Consultez le changelog complet pour l’API Docs

API ONLYOFFICE de plugins et macros 9.4

Nouvelles méthodes de contrôle du curseur

Deux nouvelles méthodes ont été ajoutées à window.Asc.plugin.executeMethod pour l’API Document :

• MoveCursorToField : déplace le curseur vers un champ de formulaire spécifique ;
• MoveCursorOutsideField : déplace le curseur vers une position en dehors du champ actuel.

Asc.plugin.executeMethod("MoveCursorToField", [fieldId, true]);

Asc.plugin.executeMethod("MoveCursorOutsideField", [fieldId, false]);

Celles-ci sont particulièrement utiles pour les plug-ins qui guident les utilisateurs à travers la complétion de formulaires ou automatisent la navigation champ par champ dans les documents. Au lieu de compter sur l’interaction de l’utilisateur pour avancer dans les champs, votre plug-in peut contrôler la position du curseur de manière programmatique.

Amélioration du contrôle StartAction et EndAction

La méthode StartAction accepte deux nouveaux paramètres : lockScroll et keepSelection. La méthode EndAction gagne scrollToTarget et cancel. Ensemble, cela donne aux plug-ins un meilleur contrôle sur l’état de l’éditeur pendant l’exécution des macros. Vous pouvez préserver la sélection de l’utilisateur, empêcher le défilement indésirable pendant les opérations automatisées, ou annuler une séquence d’actions proprement — tout cela contribue à une expérience de plug-in plus stable et prévisible.

Consultez le changelog complet pour l’API de plugins et macros

API JavaScript Office 9.4

C’est la partie la plus vaste de la version 9.4. L’API JavaScript Office acquiert de nouvelles capacités dans l’ensemble des opérations sur les documents, la gestion des données des feuilles de calcul, les contrôles de formulaires et plus encore. Consultez la liste complète des nouvelles méthodes

Fusion de documents

Une nouvelle méthode Api/MergeDocuments a été ajoutée à l’API Document. Cela vous permet de combiner plusieurs documents en un seul – une capacité très demandée pour des scénarios d’automatisation tels que la génération de rapports, l’assemblage de contrats et le traitement de documents en lot.

API de couleur unifiée dans tous les éditeurs

La méthode Api/Color est disponible dans les API de documents texte, feuilles de calcul, présentations et fichiers PDF. Avoir une interface de couleur cohérente dans les quatre types d’éditeurs simplifie le code qui doit appliquer un style à travers différents formats de document. Vous n’avez plus besoin d’une logique de gestion des couleurs spécifique au format pour les opérations courantes.

Support des formulaires de signature

La version 9.4 introduit la classe ApiSignatureForm, disponible à la fois dans l’API Document et l’API Form. Avec elle viennent les méthodes GetValue et SetValue pour lire et écrire les données des champs de signature. Cela ouvre la possibilité de gérer programmatiquement les champs de signature qui sont utiles pour des flux de travail nécessitant le préremplissage, la validation ou l’extraction des données de signature dans le cadre d’un pipeline de traitement de documents plus large.

// La méthode GetValue de ApiSignatureForm renvoie les données de l'image de signature stockées dans le formulaire.

// Créez un formulaire de signature, ajoutez-le au document et lisez sa valeur actuelle.

let doc = Api.GetDocument();
let signatureForm = Api.CreateSignatureForm({"key": "Signature", "tip": "Veuillez signer ici", "required": true, "placeholder": "Signature"});
signatureForm.Value = "https://static.onlyoffice.com/assets/docs/samples/img/onlyoffice_logo.png";
let paragraph = doc.GetElement(0);
paragraph.AddElement(signatureForm);
let value = signatureForm.GetValue();
paragraph = Api.CreateParagraph();
paragraph.AddText("Valeur du formulaire de signature : " + value);
doc.Push(paragraph);

De plus, la nouvelle méthode Api/CreateSignatureForm de l’API de formulaires vous permet de créer des champs de formulaire de signature à partir de zéro via du code, sans avoir besoin d’insertion manuelle.

Détection de l’état du formulaire

La méthode ApiFormBase/IsFilled, ajoutée à la fois dans l’API de documents texte et l’API de formulaires, vous permet de vérifier si un champ de formulaire donné a été rempli. C’est un ajout simple mais important pour toute logique de validation ou de soumission. Inspectez l’état de complétion du formulaire sans analyser directement le contenu des champs.

Inspection du surlignage du formulaire

Deux nouvelles méthodes (ApiDocument/GetFormsHighlight et ApiDocument/GetControlsHighlight) sont disponibles dans les API de documents et de formulaires. Celles-ci vous permettent de récupérer les paramètres de surlignage actuels appliqués aux champs de formulaire et aux contrôles de contenu. Si votre intégration gère la configuration d’affichage des formulaires ou doit refléter les états de surlignage dans des éléments d’interface utilisateur externes, ces méthodes fournissent l’accès en lecture qui faisait défaut auparavant.

API complète pour les objets de liste de feuilles de calcul

Il s’agit de la nouveauté la plus riche en fonctionnalités de la version 9.4. L’API de feuilles de calcul comprend une classe ApiListObject complète pour travailler avec des objets de table structurés (objets liste), ainsi que des classes auxiliaires pour les colonnes, les lignes et le tri.

Les capacités clés comprennent :

• Création et récupération d’objets liste via ApiWorksheet/AddListObject et ApiWorksheet/GetListObjects
• Lecture et écriture des propriétés de table telles que le nom, le nom d’affichage, le texte alternatif, le style, les en-têtes, les totaux, et les paramètres de filtre automatique
• Accès aux plages de table incluant les lignes d’en-tête, les plages de corps de données, et les lignes de totaux
• Gestion des colonnes et des lignes via ApiListColumn et ApiListRow, avec méthodes pour les noms, les index, les plages, le calcul de totaux et la suppression
• Support de tri via les nouvelles classes ApiSort, ApiSortFields, et ApiSortField — couvrant l’orientation de tri, la correspondance des majuscules, les critères de tri (valeur ou couleur), la priorité et plus encore

Si votre intégration implique un gestionnaire de données structurées dans des feuilles de calcul telles que les imports de données, la création de tables dynamiques, la génération de rapports, cette nouveauté étend considérablement ce que vous pouvez faire sans demander aux utilisateurs de manipuler les tables manuellement.

Nouvelles méthodes de Remplissage et de Formule dans les feuilles de calcul

Quatre méthodes de remplissage directionnel ont été ajoutées à ApiRange : FillDown, FillUp, FillRight, FillLeft.

Celles-ci reflètent le comportement de remplissage de la feuille de calcul que les utilisateurs déclenchent manuellement, désormais disponible pour une utilisation programmatique. Associées à la nouvelle méthode ApiRange/SetFormula, vous pouvez construire une automatisation qui construit dynamiquement des plages drivées par des formules. C’est utile pour les rapports générés, les feuilles de calcul avec modèles et l’automatisation de la saisie de données.

La méthode Api/GetDefNames a également été ajoutée à l’API de feuilles de calcul, vous donnant accès aux noms définis (plages nommées) dans un classeur.

Contrôles de mise en forme des formulaires de texte

La classe ApiTextForm gagne quatre nouvelles méthodes dans les API de documents et de formulaires :

• GetFormat/SetFormat : lire et appliquer un masque de format au champ de texte
• GetAllowedSymbols/SetAllowedSymbols : contrôler quels caractères les utilisateurs peuvent entrer

Celles-ci sont essentielles pour créer des formulaires de saisie de données validés, par exemple en imposant des formats de date, en restreignant l’entrée aux caractères numériques, ou en appliquant des masques personnalisés pour les numéros de téléphone ou les identifiants.

Inspection des propriétés de paragraphe

Un ensemble de méthodes Get a été ajouté à ApiParaPr dans l’API de documents texte, couvrant :

• Propriétés de bordure : haut, gauche, droite, bas, entre
• Pagination : GetKeepLines, GetKeepNext, GetPageBreakBefore, GetWidowControl
• Liste : GetNumPr
• Onglets : GetTabs
• Espacement : GetContextualSpacing

Ceci comble une lacune de longue date. Vous pouviez définir beaucoup de ces propriétés par programmation, mais les lire n’était pas toujours possible. Vous pouvez inspecter le formatage des paragraphes sans avoir besoin de solutions de contournement, ce qui est particulièrement utile pour les outils d’analyse de documents et les scripts de validation de modèles.

Couleur de contrôle de contenu

La classe ApiInlineLvlSdt dans l’API de documents prend en charge les méthodes SetColor et GetColor. Vous pouvez attribuer et lire des couleurs de surlignage pour les contrôles de contenu en ligne, rendant plus facile la création d’expériences de formulaire visuellement distinctes ou la mise en évidence des contrôles en fonction de leur état.

// Comment changer la couleur d'un contrôle de contenu en ligne dans un document ?

// Appliquez une couleur RGB spécifique pour distinguer visuellement un contrôle de contenu dans un document.

let doc = Api.GetDocument();
let paragraph = doc.GetElement(0);
let inlineLvlSdt = Api.CreateInlineLvlSdt();
let run = Api.CreateRun();
run.AddText("Ceci est un contrôle de contenu de texte en ligne avec une couleur de tag bleu.");
inlineLvlSdt.AddElement(run, 0);
inlineLvlSdt.SetColor(Api.RGB(0, 0, 255));
paragraph.AddInlineLvlSdt(inlineLvlSdt);