I. Introduction▲
Avec l’arrivée du nouvel agent IA dans ONLYOFFICE, les utilisateurs peuvent interagir en langage naturel avec leurs documents, feuilles de calcul et présentations. En plus des fonctions intégrées (résumés, reformulations, analyses, etc.), il est désormais possible d’ajouter vos propres fonctions personnalisées.
Dans ce guide, nous allons voir :
- ce que sont les fonctions IA et leur rôle ;
- pourquoi créer vos propres fonctions ;
- où et comment les enregistrer ;
- un exemple concret de fonction personnalisée ;
- et les bonnes pratiques pour aller plus loin.
II. Qu’est-ce qu’une fonction IA ?▲
Une fonction IA est un bloc de logique qui dit à l’agent IA :
- quelle requête envoyer au modèle ;
- et comment insérer ou manipuler le contenu dans le document.
En pratique, c’est une passerelle entre votre modèle IA (par exemple GPT, LLaMA ou Mistral) et l’API Office d’ONLYOFFICE.
Exemple : la fonction commentText permet de générer automatiquement un commentaire ou une note de bas de page sur le texte sélectionné.
III. Pourquoi créer vos propres fonctions ?▲
- Adapter l’IA à vos besoins : par exemple générer des résumés spécialisés, ajouter des références automatiques, créer des visualisations.
- Automatiser vos tâches : gagner du temps sur des actions répétitives.
- Étendre les éditeurs : transformer l’agent IA en un outil qui colle parfaitement à votre flux de travail.
IV. Logique générale de l’ajout d’une fonction IA personnalisée▲
Toutes les fonctions personnalisées se trouvent dans le répertoire helpers du plugin IA, avec une organisation par éditeur :
- cell.js – Fonctions IA pour l’éditeur de feuilles de calcul ;
- slide.js – Fonctions IA pour l’éditeur de présentations ;
- word.js – Fonctions d’IA pour l’éditeur de documents texte.
Lorsque vous créez une nouvelle fonction personnalisée, ajoutez-la au fichier approprié pour l’éditeur auquel elle appartient.
V. Étapes pour ajouter une fonction personnalisée▲
Le processus d’ajout d’une fonction personnalisée comprend deux phases principales :
- enregistrement de la fonction : enregistre la fonction IA et ses métadonnées dans l’environnement de l’agent ;
- exécution de la fonction : met en œuvre la logique de base, qui comprend l’envoi de requêtes au modèle IA et la manipulation du contenu des documents à l’aide de notre API Office.
Exemple : la fonction commentText
Voici un exemple complet qui ajoute un commentaire ou une note de bas de page générée par l’IA.
- Enregistrement
On crée un objet RegisteredFunction :
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
let func = new RegisteredFunction();
func.name = "commentText";
func.params = [ "type (string): whether to add as a 'comment' or as a 'footnote' default is 'comment')"
]; AI functions for the Document Editor
func.examples = [ "If you need to explain selected text as a comment, respond with:\n" +
"[functionCalling (commentText)]: {\"prompt\" : \"Explain this text\", \"type\": \"comment\"}",
"If you need to add a footnote to selected text, respond with:\n" +
"[functionCalling (commentText)]: {\"prompt\" : \"Add a footnote to this text\", \"type\": \"footnote\"}",
"If you need to comment selected text, respond with:\n" +
"[functionCalling (commentText)]: {\"prompt\" : \"Comment this text\"}",
"If you need to explain selected text as a footnote, respond with:\n" +
"[functionCalling (commentText)]: {\"prompt\" : \"Explain this text\", \"type\": \"footnote\"}"
]
Ici :
- func.name : le nom que l’IA utilisera pour appeler cette fonction (par exemple, « commentText »).
- func.params : une liste des paramètres que la fonction attend de l’IA. Par exemple :
– prompt (string) : une description ou une instruction pour le commentaire.
– type (string) : « comment » ou « footnote » — spécifie ce qu’il faut insérer.
- func.examples : exemples d’appels de fonction corrects pour l’IA.
-
func.description : explique à l’IA à quoi sert la fonction.
Ces paramètres sont utilisés par l’IA. L’objet RegisteredFunction() est défini dans le fichier helperFunc.js.
- Logique d’exécution
La fonction récupère le texte sélectionné, envoie une requête au modèle IA, puis insère le résultat en commentaire ou en note de bas de page :
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
func.call = async function(params) {
let type = params.type;
let isFootnote = "footnote" === type;
// Executes a block of code inside the editor's context using the office=js API.
let text = await Asc.Editor.callCommand(function(){
let doc = Api.GetDocument();
// Gets the current selected text range.
let range = doc.GetRangeBySelect();
let text = range ? range.GetText() : "";
if (!text)
{ text = doc.GetCurrentWord(); // Selects the current word so comments can be applied to it.
doc.SelectCurrentWord(); } return text;
Construisez l’invite pour l’IA en combinant params.prompt et le texte sélectionné.
let argPromt = params.prompt + ":\n" + text;
Initialisez l’objet AI.Request.create à l’aide de AI.Request.create. L’objet est défini dans le fichier engine.js. Cet objet facilite l’envoi d’une requête au modèle d’IA.
Envoyez la requête à l’aide de chatRequest() et recevez le résultat dans un rappel.
Insérez la réponse sous forme de commentaire ou de note de bas de page à l’aide de AddFootnote() ou AddComment().
Implémentation d’AddFootnote :
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
if (isFootnote)
{ let addFootnote = true;
// Sends a prompt to the AI model and processes the response via callback. Can stream or wait.
let result = await requestEngine.chatRequest(argPromt, false, async function(data) {
if (!data)
return;
// Marks the end of a logical group or block action in the editor.
await checkEndAction();
Asc.scope.data = data; Asc.scope.model = requestEngine.modelUI.name; if (addFootnote)
{ // Executes a block of code inside the editor's context using the document model API.
await Asc.Editor.callCommand(function(){
// Returns the main document object, which gives access to all editing, structure, and selection APIs.
Api.GetDocument().AddFootnote(); }); addFootnote = false;
} // Inserts the AI-generated result into the document at the current selection or cursor.
await Asc.Library.PasteText(data);
});
Implémentation d’AddComment :
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
let commentId = null;
// Sends a prompt to the AI model and processes the response via callback. Can stream or wait.
let result = await requestEngine.chatRequest(argPromt, false, async function(data) {
if (!data)
return;
// Marks the end of a logical group or block action in the editor.
await checkEndAction();
Asc.scope.data = data; Asc.scope.model = requestEngine.modelUI.name; Asc.scope.commentId = commentId; // Executes a block of code inside the editor's context using the document model API.
commentId = await Asc.Editor.callCommand(function(){
// Returns the main document object, which gives access to all editing, structure, and selection APIs.
let doc = Api.GetDocument();
let commentId = Asc.scope.commentId;
if (!commentId)
{ // Gets the current selected text range, which can be modified or annotated.
let range = doc.GetRangeBySelect();
if (!range)
return null;
let comment = range.AddComment(Asc.scope.data, Asc.scope.model, "uid" + Asc.scope.model);
if (!comment)
return null;
doc.ShowComment([comment.GetId()]); return comment.GetId();
} let comment = doc.GetCommentById(commentId);
if (!comment)
return commentId;
comment.SetText(comment.GetText() + scope.data); return commentId;
}); }); }
Remarque !
Pour garantir que l’ensemble des modifications puisse être annulé après l’exécution de la requête, nous utilisons les méthodes StartAction et EndAction dans la fonction commentText.
Implémentation complète de la fonction commentText avec commentaires :
Remarque !
Pour que vos fonctions IA personnalisées soient disponibles dans l’éditeur de documents, vous devez modifier le bloc getWordFunctions dans le fichier word.js. Cette fonction collecte et renvoie toutes les fonctions WORD_FUNCTIONS enregistrées que l’agent IA peut appeler.
funcs.push(WORD_FUNCTIONS.myCustomFunction());
VI. Bonnes pratiques▲
Toujours encapsuler vos actions avec StartAction et EndAction → permet d’annuler facilement les modifications.
Fournir des exemples clairs dans func.examples → l’IA saura mieux utiliser votre fonction.
Tester dans chaque éditeur (Word, Spreadsheet, Presentation) → le comportement peut varier.
Documenter vos fonctions pour les partager avec la communauté open source.
VII. Conclusion▲
Avec l’agent IA d’ONLYOFFICE, vous n’êtes pas limité aux fonctions par défaut. Grâce aux fonctions personnalisées, vous pouvez :
- enrichir vos documents ;
- automatiser vos flux de travail ;
- et transformer vos éditeurs en véritables assistants intelligents adaptés à vos besoins.