كيفية التعامل مع طلبات “API” غير المتزامنة داخل الدوال المخصصة في “ONLYOFFICE”

تُعد الدوال المخصصة وسيلة قوية ومرنة لتوسيع إمكانيات محرر الجداول في “ONLYOFFICE”. وفي إطار سعي فريقنا المستمر لتطوير المنصة، جاء إصدار 9.0 من “ONLYOFFICE Docs” بدعم جديد لتنفيذ طلبات “API” غير المتزامنة داخل الدوال المخصصة. في هذا المقال، سنرشدكم إلى كيفية دمج هذه الميزة في حلولكم الخاصة.

نظرة عامة على الدوال المخصصة في “ONLYOFFICE”

تُعتبر الدوال المخصصة إضافة مرنة وقوية إلى مكتبة الماكرو في محرر الجداول. فهي تتيح لكم إنشاء دوالكم الخاصة وتصديرها لاستخدامها مباشرة داخل الجداول.

(function () {
    /**
      * This is a custom function that can be used in the editor.
      * @customfunction

      * @param {number} value - description of the parameter.
      * @returns {number} Description of the returned data.
      */
    function customFunctionName(value) {
        // Add your custom calculation logic here
        return // your calculation result;
    }
    // Register the custom function with the editor
    Api.AddCustomFunction(customFunctionName);
})();

أين تجدونها: عرض < ماكرو < الدوال المخصصة

ما الجديد؟

مع إصدار 9.0 من “ONLYOFFICE Docs”، أصبح بإمكانكم الآن استدعاء دوال غير متزامنة (“asynchronous”) داخل سكريبتاتكم المخصصة.

هذا يعني أنه يمكنكم الآن:

•  إرسال طلبات ويب غير متزامنة إلى أي خدمة.
•  التفاعل مع مزودي الذكاء الاصطناعي عبر “API” غير متزامن.
•  استخدام كود “JavaScript” غير متزامن داخل الدوال.
•  معالجة الاستجابات غير المتزامنة.
•  تصدير النتائج مباشرة إلى الجدول.

  (function () {
    // Make an asynchronous request
    let asyncFunc = async function (value) {
      let request = await fetch("https://yourURL");
      const jsonData = await request.json();
      if (value === undefined) {
        value = 2;
      }
      return jsonData;
    };
    /**
     * This is a custom function that can be used in the editor.
     * @customfunction

     * @param {number} value - description of the parameter.
     * @returns {number} Description of the returned data.
     */
    async function customFunctionName(value) {
      // Call the asynchronous function and return its result
      return await asyncFunc(value);
    }
    // Register the custom function with the editor
    Api.AddCustomFunction(customFunctionName);
  })();

استخدام طلبات “API” غير المتزامنة داخل دالة مخصصة

في هذا المثال، سنستخدم واجهة “Sales Tax API” من موقع “API Ninjas”، التي تُرجع نسبة ضريبة المبيعات حسب رمز “ZIP” لأي ولاية أمريكية.

تنويه: لاستخدام هذه الدالة المخصصة، ستحتاجون إلى مفتاح “API” خاص بكم، يمكن الحصول عليه مجانًا من موقع “API Ninjas”.

بناء الماكرو

أولًا، نقوم بتعريف دالة غير متزامنة باسم getSalesTax:

let getSalesTax = async function (value) {
}

تأخذ هذه الدالة معاملًا يمثل رمز “ZIP” أمريكي.

إذا لم يُقدّم رمز “ZIP”، يتم استخدام الرمز الافتراضي 90210:

let getSalesTax = async function (value) {
}
 if (undefined === value) {
      value = 90210;
    }

بما أن بعض الرموز تبدأ بصفر، نحرص على تحويل الرمز إلى سلسلة مكونة من 5 أرقام.

 // Convert to string and add missing zeros if needed
    let zipStr = value.toString();
    while (zipStr.length < 5) {
      zipStr = '0' + zipStr;
    }

مثلًا: 31 يصبح 00031.

بعد ذلك، نقوم ببناء رابط الطلب من خلال إضافة رمز “ZIP” كوسيط.

ثم نرسل طلب “GET” إلى “API”:

 let request = await fetch(url, {
      method: 'GET',
      headers: {
        'X-Api-Key': 'yourAPIkey',
        'Content-Type': 'application/json'
      }
    });

بعد الاستجابة، نحول البيانات بصيغة “JSON” إلى كائن “JavaScript” قابل للاستخدام:

  let jsonData = await request.json();

نستخرج الحقل state_rate من أول عنصر في البيانات المُرجعة، وهو ما يمثل نسبة ضريبة المبيعات للرمز المقدم. وأخيرًا، نُرجع هذه القيمة:

 const taxRate = jsonData[0].state_rate;
    return taxRate;

بعد ذلك، نُعرّف معاملات الدالة المخصصة:

 /**
   * Function that returns state sales tax.
   * @customfunction

   * @param {number} value - zip code.
   * @returns {number} Returns state sales tax data.
   */

نحصل على الاستجابة من الدالة غير المتزامنة:

 async function salestax(value) {
    return await getSalesTax(value);
  }

ونسجّل الدالة لتصبح متاحة في الجداول:

  // Add the custom function 
  Api.AddCustomFunction(salestax);
})();

الآن، أصبح بإمكانكم استخدام دالة SALESTAX() مباشرة داخل الجدول!

الكود الكامل للدالة:

(function () {
  // Function that returns sales tax data from api-ninjas.com
  let getSalesTax = async function (value) {


    if (undefined === value) {
      value = 90210;
    }


    // Convert to string and add missing zeros if needed
    let zipStr = value.toString();
    while (zipStr.length < 5) {
      zipStr = '0' + zipStr;
    }


    const url = 'https://api.api-ninjas.com/v1/salestax?zip_code=' + zipStr;


    let request = await fetch(url, {
      method: 'GET',
      headers: {
        'X-Api-Key': 'yourAPIkey',
        'Content-Type': 'application/json'
      }
    });


    let jsonData = await request.json();
    const taxRate = jsonData[0].state_rate;
    return taxRate;
  };


  /**
   * Function that returns state sales tax.
   * @customfunction

   * @param {number} value - zip code.
   * @returns {number} Returns state sales tax data.
   */
  async function salestax(value) {
    return await getSalesTax(value);
  }


  // Add the custom function 
  Api.AddCustomFunction(salestax);
})();

احفظوا الدالة وشاهدوا النتائج مباشرة في الجدول. هذه الميزة الجديدة تفتح أمامكم آفاقًا أوسع لإنشاء حلول أكثر ذكاءً وتخصيصًا.

 

نأمل أن تساعدكم هذه الميزة على تطوير أدوات أكثر فعالية وتنوعًا في أعمالكم. في “ONLYOFFICE”، نضع بين أيديكم تقنيات مرنة وقابلة للتخصيص وفقًا لاحتياجاتكم الخاصة.

ندعوكم لتجربة الدوال غير المتزامنة بأنفسكم، واكتشاف الإمكانيات التي تتيحها. وإذا كانت لديكم أفكار أو اقتراحات، يسعدنا أن نسمع منكم دائمًا. نحن منفتحون على كل أشكال التعاون والملاحظات. بالتوفيق في تجاربكم الإبداعية!