تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إصلاح الأخطاء في الرمز الذي تم تحويله

تعمل إضافة "محوِّل النصوص البرمجية" على التشغيل الآلي لمعظم عملية التحويل، ولكن قد تحتاج إلى إجراء تعديلات على بعض واجهات برمجة التطبيقات والعناصر الأخرى لإنهاء الرمز البرمجي.

استخدِم هذا الدليل لفهم ملفات Apps Script (ملفات GS) التي تمت إضافتها إلى مشروعك، وتفسير أنواع الأخطاء المختلفة، والتعرّف على كيفية حلّ الأخطاء.

فهم ملفات "برمجة تطبيقات Google" التي تمت إضافتها إلى مشروعك

تتم إضافة ملفات GS إضافية إلى مشروعك على "برمجة تطبيقات Google" للمساعدة في ما يلي:

يمكنك تحديد الثوابت والقيم في لغة VBA التي لا تتوفّر في Apps Script.
تنفيذ واجهات برمجة التطبيقات غير المحوَّلة
حلّ المشاكل المتعلّقة بخيارات المنتج

تتم إضافة ملفات GS التالية إلى مشروعك على Apps Script:

Library.gs
Unimplemented_constructs.gs
Variant_resolutions.gs

`Library.gs`

بشكل عام، ليس عليك تعديل أي شيء في ملف library.gs.

يحدِّد ملف library.gs الدوالّ والثوابت التي تم استخدامها في رمز VBA الذي لا يتوفّر في Apps Script. يساعد ذلك رمز Apps Script الجديد في أن يشبه رمز VBA بشكلٍ أفضل. بالإضافة إلى ذلك، لا تحتاج إلى تكرار التعريفات في كل مر يتم فيه استخدام الدوال أو الثوابت من ملف library.gs.

`Unimplemented_constructs.gs`

يعالج ملف unimplemented_constructs.gs بنى أو واجهات برمجة تطبيقات تعذّر تحويلها باستخدام "محوِّل الماكرو". من المحتمل أن تحتاج إلى تعديل هذا الملف لكي يعمل الرمز البرمجي على النحو المطلوب.

مثلاً: `Window.Activate()`

في ما يلي مثال على واجهة برمجة تطبيقات غير متوافقة تُسمى Window.Activate(). تُنشئ إضافة "محوِّل الماكرو" دالة جديدة في Apps Script تحمل اسمًا مشابهًا و تحدّدها في ملف unimplemented_constructs.gs. بما أنّ دالة VBA غير متوافقة، تُعرِض دالة Apps Script الجديدة استثناءً.

تتم إضافة الدالة الجديدة إلى رمز Apps Script المحوَّل في كل مكان تم فيه استخدام واجهة برمجة التطبيقات الأصلية في رمز VBA.

إذا عثرت على حلّ بديل لإعادة إنشاء سلوك واجهة برمجة التطبيقات الأصلية، لن تحتاج سوى إلى تعديل تعريف الدالة في ملف unimplemented_constructs.gs. بعد تعريف الدالة هناك، يتم تطبيقها في كل مكان تظهر فيه الدالة في مشروعك على Apps Script.

في ما يلي المثال في رمز:

رمز VBA الأصلي

Window.activate()

رمز Apps Script المحوَّل الذي تمت إضافته مضمّنًا

_api_window_activate();

تمّت إضافة تعريف الدالة إلى ملف unimplemented_constructs.gs

/**
 * Could not convert window.activate API. Please add relevant code in the
 * following function to implement it.
 * This API has been used at the following locations in the VBA script.
 *     module1 : line 3
 *
 * We couldn't find an equivalent API in Apps Script for this VBA API. Please
 * reconsider if this function call is critical, otherwise consider implementing
 * it in a different way.
 */
function _api_window_activate(CallingObject) {
  ThrowException("API window.activate not supported yet.");
}

`Variant_resolutions.gs`

تتم إضافة ملف variant_resolutions.gs إلى مشروعك على Apps Script إذا تعذّر تحديد نوع العنصر. يمكن أن يحدث ذلك لأسباب متعدّدة، مثل أن تتضمّن واجهة برمجة التطبيقات أنواعًا متعدّدة من القيم المعروضة أو أن يتمّ تعريف العنصر على أنّه أحد الصيغ نفسها.

يضيف "محوِّل الوحدات النمطية" دالة جديدة إلى هذا الملف تُسمى __handle_resolve_<api>() تحلّ محلّ واجهة برمجة التطبيقات المعنيّة وتساعد في تحديد نوع العنصر.

في بعض الحالات، قد تحتاج إلى تعديل الدالة __handle_resolve_<api>() للإعلان يدويًا عن نوع العنصر. راجِع نوع العنصر غير المتوافق.

مثلاً: `name()`

تحدِّد العديد من أنواع الكائنات في VBA واجهة برمجة تطبيقات name(). عادةً ما يكون العنصر المكافئ في Apps Script هو getName()، ولكن ليس لكل نوع من أنواع الكائنات. يمكن أن تحدث عدة حالات بديلة:

يُطلق على واجهة برمجة التطبيقات المعادل للعنصر اسمًا مختلفًا عن getName().
لا يتضمّن العنصر واجهة برمجة التطبيقات Apps Script API للحصول على اسمه.
لا يتوفّر عنصر Apps Script مكافئ.

عندما لا يتم تحديد نوع العنصر، ينشئ "محوِّل الوحدات النمطية" دالة جديدة باسم __handle_resolve_name في ملف variant_resolutions.gs.

في ما يلي المثال في رمز:

رمز VBA الأصلي

a = Selection.name

في هذه الحالة، يتمّ استدعاء واجهة برمجة التطبيقات name() للاختيار الحالي. يمكن أن يكون الاختيار كائن ورقة بيانات أو كائن شكل. إذا كان عنصر "ورقة بيانات"، يكون الرمز هو getName()، ولكن إذا كان عنصر "شكل"، لا يتوفّر رمز مماثل له في Apps Script.

رمز Apps Script تم تحويله وإضافته مضمّنًا

a = __handle_resolve_name({}, getActiveSelection(), {});

تتم إضافة الدالة __handle_resolve_name() أدناه إلى ملف variant_resolution.gs لحلّ أنواع العناصر المختلفة. تتحقّق الدالة من نوع العنصر، ثم تستخدِم getName() إذا كان متاحًا، أو تُرسِل خطأً إذا لم يكن getName() متاحًا.

تمّت إضافة تعريف الدالة إلى ملف variant_resolution.gs

function __handle_resolve_name(ExecutionContext, CallingObject, params_map) {
  var found_api_variant = false;
  var return_value;
  if (String(CallingObject) == "Sheet") {
    if (!ExecutionContext.isLhs) {
      return_value = CallingObject.getName();
      found_api_variant = true;
    }
  }
  if (CallingObject instanceof ChartInSheet) {
    if (!ExecutionContext.isLhs) {
      return_value = CallingObject.getName();
      found_api_variant = true;
    }
  }
  if (!found_api_variant) {
    ThrowException("API .name not supported yet.");
  }
  return return_value;
}

العثور على الأخطاء

عند مواجهة خطأ في رمز Apps Script المحوَّل، تحدِّد الرسالة نوع الخطأ وموقعه. يعتمد تنسيق رسالة الخطأ على وقت تشغيل Apps Script الذي تستخدمه.

إذا كنت تستخدم وقت التشغيل التلقائي لـ V8، ستظهر لك رسالة خطأ تشبه الرسالة التالية:

_api_windows_active (unimplemented_constructs:2:3)

وهذا يعني أنّ الخطأ يقع في ملف unimplemented_constructs.gs في السطر 2، الحرف 3.

إذا كنت تستخدم وقت تشغيل Rhino المتوقّف نهائيًا، سيظهر لك خطأ يشبه ما يلي:

unimplemented_constructs:2 (_api_windows_active)

وهذا يعني أنّ الخطأ يقع في ملف unimplemented_constructs.gs في السطر 2.

أنواع الأخطاء

يمكنك إصلاح معظم الأخطاء التي تواجهها في ملفّي unimplemented_constructs.gs وvariant_resolution.gs الموضّحين أعلاه.

تشمل أنواع الأخطاء التي قد تواجهها ما يلي:

واجهة برمجة تطبيقات غير مُطبَّقة
بنية لغوية غير مفعَّلة
واجهة برمجة تطبيقات متوافقة جزئيًا
الحاجة إلى إجراء يدوي
خطأ متعمّد

واجهة برمجة تطبيقات لم يتم تنفيذها

واجهة برمجة تطبيقات غير مفعّلة هي واجهة برمجة تطبيقات لا يمكن لخدمة "محوِّل وحدات الماكرو" تحويلها من VBA إلى "برمجة تطبيقات Google"، ولا تتوفّر طريقة بديلة معروفة لواجهة برمجة التطبيقات.

تتم عادةً إضافة واجهات برمجة التطبيقات غير المُطبَّقة كوظائف فارغة، وفي بعض الأحيان مع توقيعات فارغة، إلى ملف unimplemented_constructs.gs. إذا تعذّر تحديد نوع العنصر، قد تتم إضافة واجهة برمجة التطبيقات غير المُطبَّقة إلى ملف variant_resolution.gs بدلاً من ذلك.

في تقرير التوافق الذي أنشأته قبل التحويل، تم تصنيف واجهة برمجة التطبيقات هذه على أنّها تتطلّب مزيدًا من التحقيق.

إذا لم تصحِّح هذا النوع من واجهات برمجة التطبيقات في رمز VBA قبل تحويل ملفك، berikut adalah cara munculnya di proyek Apps Script:

/**
* Could not convert . Please add relevant code in the following
* function to implement it.
* This API has been used at the following locations in the VBA script.
*      : 
* We couldn't find an equivalent API in Apps Script for this VBA API. Please
* reconsider if this function call is critical, otherwise consider implementing
* it in a different way.
* @param param1 {}
* @param param2 {}
* ...
* @return {}
*/
function _api_<API_name>(param1, param2, ....) {
  ThrowException("API  not supported yet.");
}

إصلاح أخطاء واجهة برمجة التطبيقات غير المُطبَّقة

حدِّد واجهة برمجة التطبيقات غير المُطبَّقة باستخدام واجهات برمجة التطبيقات الحالية لـ Apps Script أو مكتبات JS. لإجراء ذلك، اتّبع الخطوات التالية:

افتح رمز Apps Script المحوَّل في موضع الخطأ. اطّلِع على العثور على الأخطاء.
فوق الدالة، اقرأ التعليق الذي تمت إضافته. في بعض الحالات، يقترح التعليق كيفية تنفيذ واجهة برمجة التطبيقات في Apps Script.
إذا لم تتمكّن من العثور على طريقة لتنفيذ واجهة برمجة التطبيقات في Apps Script، ننصحك بإزالتها من الرمز البرمجي.
إذا لم تتمكّن من العثور على حلّ بديل أو إزالة واجهة برمجة التطبيقات هذه من الرمز البرمجي وظهرت علامة الخطأ هذه في الماكرو، لن تتمكّن من تحويل هذا الماكرو.

أمثلة على أخطاء واجهة برمجة التطبيقات غير المُطبَّقة

في ما يلي أمثلة على سيناريوهات واجهات برمجة التطبيقات غير المنفَّذة وكيفية حلّها:

لا تتوفّر واجهة برمجة تطبيقات مماثلة: يعرض حلًا بديلاً غير مباشر لـ Chart.Protect، وهي واجهة برمجة تطبيقات غير متوفّرة في برمجة التطبيقات.
نوع عنصر غير معروف: يعرض كيفية التعامل مع نوع عنصر هوvariabel، وكيفية تنفيذ نوع عنصر غير متوافق يمكن إعادة إنشائه في Apps Script.

المثال 1: عدم توفّر بديل لـ Apps Script أو واجهة برمجة تطبيقات غير معروفة

في هذا المثال، لم يتم تحويل Chart.Protect تلقائيًا لأنّه ليس هناك طريقة لحماية رسم بياني في "جداول بيانات Google".

/**
* Could not convert chart.protect API. Please add relevant code in the following
* function to implement it.
*
* This API has been used at the following locations in the VBA script.
*     sheet1 : line 3
* You can use the following Apps Script APIs to convert it.
*
* Comments : Auto conversion of Chart.Protect is not supported yet. If the API is
* critical for the workflow the user can implement the unimplemented handler
* method in the generated code, else comment out the throw statement.
*
* @param {Object} CallingObject represents the parent object using which the API
* has been called.
* @param {string} Password
* @param {boolean} DrawingObjects
* @param {boolean} Contents
* @param {boolean} Scenarios
* @param {boolean} UserInterfaceOnly
*
*/
function _api_chart_protect(
   CallingObject, Password, DrawingObjects, Contents, Scenarios,
   UserInterfaceOnly) {
 ThrowException('API chart.protect not supported yet.');
}

على الرغم من أنّه لا يمكنك حماية مخطّط بياني، يمكنك حماية نطاق البيانات في المخطّط كي لا يمكن تغيير البيانات.

في ما يلي مثال على تنفيذ حماية النطاق:

/**
* Could not convert chart.protect API. Please add relevant code in the following
* function to implement it.
* This API has been used at the following locations in the VBA script.
*     sheet1 : line 3
*
* You can use the following Apps Script APIs to convert it.
* Comments : Auto conversion of Chart.Protect is not supported yet. If the API
* is critical for the workflow the user can implement the unimplemented handler
* method in the generated code, else comment out the throw statement.
*
* @param {Object} CallingObject represents the parent object using which the API
* has been called.
* @param {string} Password
* @param {boolean} DrawingObjects
* @param {boolean} Contents
* @param {boolean} Scenarios
* @param {boolean} UserInterfaceOnly
*/
function _api_chart_protect(
  CallingObject, Password, DrawingObjects, Contents, Scenarios, UserInterfaceOnly) {
var ranges = CallingObject.getChart().getRanges();
for (var i = 0; i < ranges.length; i++) {
  // Note that this does not lock the range for the document owner.
  ranges[i].protect();
}
}

المثال 2: نوع عنصر غير متوافق

عندما يكون نوع العنصر غير معروف، تتم إضافة خطأ واجهة برمجة التطبيقات غير المُنفَّذ إلى ملف variant_resolution.gs. يوضّح المثال التالي المزيد من المعلومات عن مثال name() واجهة برمجة التطبيقات VBA أعلاه. يُرجى الاطّلاع على variant_resolution.gs.

في هذا المثال، ستتعرّف على ما يلي:

كيفية تحويل واجهة برمجة التطبيقات name() إلى دالة جديدة فيملف variant_resolution.gs
كيفية استدعاء الدالة الجديدة في الرمز البرمجي المحوَّل
كيفية إنشاء حل بديل لCommandBar، وهو نوع عنصر غير متوافق، في Apps Script

1. بما أنّ الرمز المحوَّل لا يمكنه تحديد نوع العنصر المحدّد الذي يتم استدعاء name() ، ينشئ "محوِّل العلامات" دالة جديدة تُسمّى __handle_resolve_name، كما هو موضّح أدناه.

function __handle_resolve_name(ExecutionContext, CallingObject, params_map) {
 var found_api_variant = false;
 var return_value;
  if (String(CallingObject) == "Sheet") {
    if (!ExecutionContext.isLhs) {
      return_value = CallingObject.getName();
      found_api_variant = true;
    }
  }
  if (CallingObject instanceof ChartInSheet) {
    if (!ExecutionContext.isLhs) {
      return_value = CallingObject.getName();
      found_api_variant = true;
    }
  }
  if (!found_api_variant) {
    ThrowException('API .name not supported yet.');
  }
  return return_value;
}

2. لنفترض أنّ رمز VBA يحدِّد دالة PrintName() تستدعي name() واجهة برمجة التطبيقات. يظهر رمز VBA أدناه:

‘Defining a function that prints the name of the object in parameter
Sub PrintName(obj as Variant)
  Debug.Print obj.Name
End Sub

بما أنّ دالة name()‎ يتمّ استدعاؤها على عنصر هو متغيّر، فإنّ الرمز المحوَّل لا يعرف نوع العنصر في وقت التحويل. سيستدعي رمز "برمجة تطبيقات Google" المُحوَّل الدالة __handle_resolve_name:

function PrintName(obj) {
  Logger.log(_handle_resolve_name(obj));
}

3. لنفترض أنّ رمز VBA يستدعي الدالة PrintName() على نوع العنصر CommandBar. يظهر رمز VBA أدناه:

PrintName Application.CommandBars.item("Standard")

لا يمكن استخدام CommandBar في Apps Script، وبالتالي، لا يمكن استخدام المرحلتَين اللتين تم استخدامهما في رمز VBA أعلاه.

Application.CommandBars(): في VBA، يؤدي ذلك إلى عرض قائمة بجميع عناصر CommandBar.
CommandBars.item(): في VBA، يؤدي ذلك إلى عرض عنصر CommandBar محدّد.

بما أنّ نوع العنصر هذا غير متوافق مع Apps Script، فإنّ الرمز المُحوَّل يُنشئ الدوالّ التالية في ملف unimplemented_constructs.gs التي عليك تحديدها.

_api_application_commandbars()
_api_commandbars_item()

يتمّ استدعاء الدوالّ في الرمز المُحوَّل كما هو موضّح أدناه:

PrintName(_api_commandbars_item(_api_application_commandbars(), "Standard")))

Here’s how the new functions are added to the unimplemented_construct.gs file:

function _api_application_commandbars(CallingObject) {
  ThrowException('API application.commandbars not supported yet.');
}
function _api_commandbars_item(CallingObject, index) {
  ThrowException('API commandbars.item not supported yet.');
}

لاستخدام الدوالّ الجديدة، اتّبِع الخطوات التالية:

3.1 تحديد نوع عنصر جديد ينشئ وظائف CommandBars ومجموعة جديدة من CommandBars مشابهة لما هو متوفّر في VBA

3.2 أضِف طريقة getName() لنوع العنصر الجديد.

تظهر الخطوتان 3.1 و3.2 في الرمز أدناه. يتم إنشاء عناصر القائمة كنوع كائن جديد يحاكي سلوك CommandBars.

// Our Implementation of CommandBar using Menu objects.

function CommandBar(name) {
  this.name = name;
  // Create a menu object to represent the commandbar.
  this.menu = SpreadsheetApp.getUi().createMenu(name);
  // Create methods for retrieving or updating the name of the object
  this.getName = function() {
    return this.name;
  };
  this.updateName = function(name) {
    this.name = name;
  };
  // ========================================================================
  // Implement other methods of CommandBar objects that are used in the script.
  // =====================================================================
  return this;
}
// Our implementation of the collection of CommandBars that exists in VBA
function CommandBars() {
  this.commandBars = [];
  this.getCommandBar = function(name) {
    for (var i = 0; i < this.commandBars.length; i++) {
      if (!this.commandBars[i].getName() == name) {
        return this.commandBars[i];
      }
    }
    // No commandBar with the name exists, create a new one and return.
    var commandBar = new CommandBar(name);
    this.commandBars.push(commandBar);
    return commandBar;
  };
  return this;
}
// Create a global object that represents CommandBars collection.
var GlobalCommandBars = new CommandBars();

3.3 عدِّل الدالة __handle_resolve_name في ملف variant_resolution.gs لمعالجة نوع العنصر الجديد. أضِف قسمًا إلى الدالة، كما هو موضّح أدناه:

function __handle_resolve_name(ExecutionContext, CallingObject, params_map) {
 var found_api_variant = false;
 var return_value;
 if (String(CallingObject) == "Sheet") {
   if (!ExecutionContext.isLhs) {
     return_value = CallingObject.getName();
     found_api_variant = true;
   }
 }
 if (CallingObject instanceof ChartInSheet) {
   if (!ExecutionContext.isLhs) {
     return_value = CallingObject.getName();
     found_api_variant = true;
   }
 }
 // New section added below
 // ========================================================================
 if (CallingObject instanceof CommandBar) {
   objectExtend(params_map, {VALUETOSET: params_map.param0});
   if (ExecutionContext.isLhs) {
     // Call the setter method.
     CallingObject.updateName(params_map.VALUETOSET);
     found_api_variant = true;
   } else {
     // Getter is called, return the commandbar name,
     return_value = CallingObject.getName();
     found_api_variant = true;
   }
 }
 // ========================================================================
 // New section added above
 if (!found_api_variant) {
   ThrowException('API .name not supported yet.');
 }
 return return_value;
}

3.4 حدِّد الدالتَين اللتين تم إنشاؤهما في ملف unimplemented_constructs.gs (_api_application_commandbars() و_api_commandbars_item()). تضمن هذه الخطوة عملية تنفيذ طلبات الدالة الأصلية.

//This is straightforward based on the implementation of a CommandBar and the
// CommandBars collection above:
function _api_application_commandbars(CallingObject) {
 return GlobalCommandBars;
}
function _api_commandbars_item(CallingObject, index) {
 return CallingObject.getCommandBar(index);
}

تراكيب لغوية غير مفعَّلة

البنية هي عنصر من لغة الرموز البرمجية التي تتحكّم في تدفّق التنفيذ أو عرض البيانات. على سبيل المثال، الحلقات والتصنيفات والأحداث وعمليات الانتقال إلى علامة معيّنة. في ما يلي قائمة بجميع بنى VBA.

إنّ البنى التي لا يمكن لأداة تحويل الوحدات النمطية تحويلها تُعدّ بنى لغوية غير مفعَّلة.

عندما يرصد "محوِّل الوحدات النمطية" أنّه تم استخدام تركيبة لغة لم يتم تنفيذها، فإنه يُدرج تعليقًا TODO.

لا تتوفّر البنى التالية لبرنامج VBA:

إصلاح أخطاء بنية اللغة غير المُطبَّقة

عدِّل الرمز البرمجي لكي لا يعتمد منطقك على بنية اللغة غير المتوافقة.
افتح رمز Apps Script المحوَّل في موضع الخطأ. راجِع مقالة العثور على الأخطاء.
استنادًا إلى منطق الرمز، عدِّله بطريقة لا تتطلّب استخدام بنية اللغة غير المتوافقة.
إذا لم تتمكّن من العثور على طريقة لإعادة كتابة الرمز البرمجي بدون بنية اللغة غير المتوافقة، لن تتمكّن من تحويل هذه الماكرو.

أمثلة على أخطاء بنية اللغة غير المنفَّذة

إنّ إحدى بنى اللغة غير المُطبَّقة الأكثر شيوعًا هي عبارة GoTo. يمكنك استبدال بعض عبارات GoTo في لغة VBA بدورات. في ما يلي مثالان على استخدام الحلقات بدلاً من عبارات GoTo.

المثال 1: استبدال `GoTo` بـ `While Loop`

رمز VBA الأصلي

Sub Test()
 a = 0
 start: Debug.Print a
 While a < 100
   a = a + 1
   If a Mod 3 == 0
     Goto start
   End If
 Wend
End Sub

رمز Apps Script المكافئ

function test() {
 var a = 0;
 start: do {
   console.log(a);
   while (a < 100) {
     a = a + 1;
     if (a % 3 == 0) {
       continue start;
     }
   }
   break start;
 } while (true);
}

المثال 2: استبدال GoTo بحلقة For

رمز VBA الأصلي

Sub Test()
 a = 0
 For i = 1 to 100
   For j = 1 to 10
     a =a a + 1
     If i + j > 50
       GoTo endLoop
     End If
   Next j
 Next i
 endLoop: MsgBox a
End Sub

رمز Apps Script المكافئ

function test() {
 var a = 0;
 endLoop: for (var i = 1; i <= 100; i++) {
    for  (var j = 0; j <=10; j++) {
      If (i + j > 50) {
        break endLoop;
      }
    }
 }
 Browser.msgBox(a);
}

   break start;
 } while (true);
}

واجهة برمجة تطبيقات متوافقة جزئيًا

بالنسبة إلى واجهات برمجة التطبيقات المتوافقة جزئيًا، تكون بعض مَعلمات الإدخال متوافقة مع Apps Script وبعضها غير متوافق.

على سبيل المثال، يتم استخدام واجهة برمجة التطبيقات VBA API legend_position لتحديد التعليق التوضيحي في أحد رسومات PERT البيانية في Excel. وهو يتيح أنواعًا متعدّدة من قيم الإدخال، بما في ذلك:

‫xlLegendPositionBottom: تضع وسيلة الإيضاح في أسفل الرسم البياني.
‫xlLegendPositionCorner: تضع وسيلة الإيضاح في زاوية الرسم البياني.
xlLegendPositionCustom: تضع التسمية التوضيحية في مواضع مخصّصة على الرسم البياني.

يحتوي Apps Script على رمز برمجي مكافئ لا يتيح سوى بعض هذه القيم. القيم التالية غير متوافقة:

xlLegendPositionCorner
xlLegendPositionCustom

لرصد القيم غير المتوافقة لواجهات برمجة التطبيقات المتوافقة جزئيًا في الرمز البرمجي المحوَّل، تتم إضافة شرط التحقّق من الصحة إلى ملف library.gs الذي يتحقّق من تلك القيم. على سبيل المثال:

if (position == xlLegendPositionCorner ||
     position == xlLegendPositionCustom) {
   position = _handle_legend_position_error(position);
}

إذا عثر شرط التحقّق على إحدى القيم غير المتوافقة، يتم إنشاء دالة _handle_<API_name>_error لمعالجة الخطأ في ملف unimplemented_constructs.gs.

تُعرِض الدالة خطأ من النوع user error ولن تستبدِل القيمة بقيمة متوافقة. على سبيل المثال:

/**
* Throw error message for unsupported legend position.
* The VBA API Legend.Position which can take values xlLegendPositionTop,
* xlLegendPositionLeft, xlLegendPositionBottom, xlLegendPositionRight,
* xlLegendPositionCorner, xlLegendPositionCustom. It is partially supported in
* Apps Scripts that supports only a subset of the values (does not support
* xlLegendPositionCorner and xlLegendPositionCustom).
* @param {string} position
*/
function _handle_legend_position_error(position) {
// Please comment the throw statement and return a supported position value
// instead.
// Values that are supported here are xlLegendPositionTop,
// xlLegendPositionLeft, xlLegendPositionBottom, xlLegendPositionRight.
throw new Error(
   'Google Sheets does not support legend position: ' + position);
}

إصلاح أخطاء واجهة برمجة التطبيقات المتوافقة جزئيًا

حدِّد الدالة _handle_<API_name>_error لاستبدال القيم غير المتوافقة بحل بديل مقبول لاحتياجاتك.

افتح رمز Apps Script المحوَّل في موضع الخطأ. اطّلِع على العثور على الأخطاء.
اقرأ التعليق أعلاه على الدالة لمعرفة القيم المتوافقة والقيم غير المتوافقة.
بالنسبة إلى القيم غير المتوافقة، حدِّد القيم المتوافقة التي يمكن أن تعمل كبديل مناسب.
عدِّل الدالة _handle_<API_name>_error لعرض قيمة متوافقة بدلاً من ذلك.
إذا لم تتمكّن من العثور على طريقة لاستبدال القيمة غير المتوافقة، لن تتمكّن من تحويل هذه الماكرو.

مثال على خطأ في واجهة برمجة التطبيقات متوافقة جزئيًا

يوضّح المثال التالي المزيد من المعلومات حول واجهة برمجة التطبيقات VBA API legend_position المذكورة أعلاه. اطّلِع على واجهة برمجة التطبيقات المتوافقة جزئيًا.

في ما يلي مثال على رمز VBA الأصلي الذي يستخدم قيمة غير متوافقة، xlLegendPositionCustom.

Charts(1).Legend.Position = xlLegendPositionCustom

تُضيف إضافة "محوِّل الماكرو" الدالة التالية إلى ملف unimplemented_constructs.gs:

/**
* Throw error message for unsupported legend position.
* The VBA API Legend.Position which can take values xlLegendPositionTop,
* xlLegendPositionLeft, xlLegendPositionBottom, xlLegendPositionRight,
* xlLegendPositionCorner, xlLegendPositionCustom. It is partially supported in
* Apps Scripts that supports only a subset of the values (does not support
* xlLegendPositionCorner and xlLegendPositionCustom).
* @param {string} position
*/
function _handle_legend_position_error(position) {
// Please comment the throw statement and return a supported position value
// instead.
// Values that are supported here are xlLegendPositionTop,
// xlLegendPositionLeft, xlLegendPositionBottom, xlLegendPositionRight.
throw new Error(
   'Google Sheets does not support legend position: ' + position);
}

مطلوب إجراء يدوي

تشير الحالة يلزم إجراء يدوي إلى أنّه يمكن تحويل واجهة برمجة التطبيقات VBA إلى Apps Script، ولكن يلزم حل بديل.

في تقرير التوافق الذي أنشأته قبل التحويل، تم تصنيف هذا النوع من واجهة برمجة التطبيقات على أنّه متوافق مع حلول بديلة.

إذا لم تصحِّح هذا النوع من واجهات برمجة التطبيقات في رمز VBA قبل تحويل ملفك، berikut adalah cara munculnya di proyek Apps Script:

/**
* Could not convert  API. Please add relevant code in the following
* function to implement it.
* This API has been used at the following locations in the VBA script.
*      : 
*
* You can use the following Apps Script APIs to convert it.
* Apps Script APIs : 
* Apps Script documentation links : 
*
* @param param1 {}
* @param param2 {}
* ...
* @return {}
*/
function _api_<API_name>(param1, param2, ....) {
 ThrowException("API  not supported yet.");
}

إصلاح الأخطاء التي تتطلّب إجراءً يدويًا

يمكنك تنفيذ حل بديل لواجهة برمجة التطبيقات لكي تعمل على النحو المطلوب. 1. افتح رمز Apps Script المحوَّل في موضع الخطأ. اطّلِع على العثور على الأخطاء. 1. اقرأ التعليق أعلاه للدالة لمعرفة واجهات برمجة التطبيقات التي يمكن استخدامها لمحاولة حلّ المشكلة. 1. إذا لم تتمكّن من العثور على حلّ بديل مناسب، ننصحك بإزالة واجهة برمجة التطبيقات من الرمز البرمجي. 1. إذا لم تتمكّن من العثور على حلّ بديل أو إزالة واجهة برمجة التطبيقات هذه من الرمز البرمجي وتلقّى الماكرو خطأً، لن تتمكّن من تحويل هذا الماكرو.

أمثلة على الأخطاء التي تتطلّب إجراءً يدويًا

في ما يلي أمثلة على واجهات برمجة التطبيقات التي تُظهر أخطاء تتطلّب إجراءً يدويًا وكيفية حلّها:

Implement a workaround for Autocorrect.Addreplacement.
Implement a workaround for workbook.open(): يوضّح هذا المثال كيفية فتح الملفات في Google Drive باستخدام Apps Script.

المثال 1: `Autocorrect.Addreplacement`

في المثال التالي، يمكن تحويل واجهة برمجة التطبيقات VBA API Autocorrect.Addreplacement، ولكنّها تحتاج إلى حل بديل. يقترح "محوِّل الماكرو" كيفية تنفيذ الدالة في تعليقات التعليمات البرمجية.

/**
* Could not convert autocorrect.addreplacement API. Please add relevant code in
* the following function to implement it.
* This API has been used at the following locations in the VBA script.
*     sheet1 : line 3
* You can use the following Apps Script APIs to convert it.
* Apps Script APIs : FindReplaceRequest , onEdit
* Apps Script documentation links :
* https://developers.google.com/apps-script/reference/script/spreadsheet-trigger-builder#onedit
* https://developers.google.com/sheets/api/eap/reference/rest/v4/spreadsheets/request?hl=en#findreplacerequest

* Comments : AutoCorrect.AddReplacement was not converted, but there is an
* equivalent option you can implement manually. Use onEdit and FindReplaceRequest
* APIs instead, see https://developers.google.com/apps-script/reference/script/spreadsheet-trigger-builder#onedit
* and https://developers.google.com/sheets/api/eap/reference/rest/v4/spreadsheets/request?hl=en#findreplacerequest.
* For more information on API manual implementation, see
* https://developers.google.com/apps-script/guides/macro-converter/fix-conversion-errors.

* @param {Object} CallingObject represents the parent object using which the API
* has been called.
* @param {string} What
* @param {string} Replacement
* @return {string}
*/

function _api_autocorrect_addreplacement(CallingObject, What, Replacement) {
  ThrowException('API autocorrect.addreplacement not supported yet.');

}

في ما يلي عملية تنفيذ واجهة برمجة التطبيقات Autocorrect.Addreplacement:

var AUTO_CORRECTIONS = "AUTO_CORRECTIONS";
// Need to get the autocorrections set in previous sessions and use them.
var savedAutoCorrections = PropertiesService.getDocumentProperties().getProperty(AUTO_CORRECTIONS);
var autoCorrections = savedAutoCorrections ? JSON.parse(savedAutoCorrections) : {};
function onEdit(e) {
autoCorrect(e.range);
}
function autoCorrect(range) {
for (key in autoCorrections) {
// Replace each word that needs to be auto-corrected with their replacements.
range.createTextFinder(key)
.matchCase(true)
.matchEntireCell(false)
.matchFormulaText(false)
.useRegularExpression(false)
.replaceAllWith(autoCorrections[key]);
}
}
/**
* Could not convert autocorrect.addreplacement API. Please add relevant code in
* the following function to implement it.
* This API has been used at the following locations in the VBA script.
* sheet1 : line 3
*
* You can use the following Apps Script APIs to convert it.
* Apps Script APIs : createTextFinder , onEdit
* Apps Script documentation links : https://developers.google.com/apps-script/reference/script/spreadsheet-trigger-builder#onedit ,
createTextFinder
* Comments : AutoCorrect.AddReplacement was not converted, but there is an
* equivalent option you can implement manually. Use onEdit and FindReplaceRequest
* APIs instead, see https://developers.google.com/apps-script/reference/script/spreadsheet-trigger-builder#onedit
* and createTextFinder. For more information on API manual implementation, see
* https://developers.google.com/apps-script/guides/macro-converter/fix-conversion-errors.
*
* @param {Object} CallingObject represents the parent object using which the API has been called.
* @param {string} What
* @param {string} Replacement
*
* @return {string}
*/

function _api_autocorrect_addreplacement(CallingObject, What, Replacement) {
autoCorrections[What] = Replacement;
// Store the updated autoCorrections in the properties so that future executions use the correction.
PropertiesService.getDocumentProperties().setProperty(AUTO_CORRECTIONS, JSON.stringify(autoCorrections));
}

المثال 2: `Workbook.open()`

تفتح واجهة برمجة التطبيقات VBA API workbook.open() ملفًا على الجهاز استنادًا إلى مسار ملف.

لنفترض أنّ هناك ملفين يتم فتحهما بواسطة workbook.open() في رمز VBA:

الملف 1: C:\Data\abc.xlsx
الملف 2: C:\Data\xyz.xlsx

يوضّح الجدول التالي كيفية استبدال "محوِّل الماكرو" Workbook.open() بـ Apps Script في كل مكان يتم فيه استخدام Workbook.open() لفتح الملف 1:

var spreadSheetId =
   _handle_mso_excel_get_google_spreadsheet_id("C:\Data\abc.xlsx");
var spreadSheet = SpreadsheetApp.openById(spreadSheetId);

تتم إضافة الخطأ أدناه إلى ملف unimplemented_constructs.gs في مشروع "برمجة تطبيقات Google":

/**
* Method to return the spreadsheet id manually.
*
* @param {string} FileName ID of the spreadsheet to be opened.
* @return {string} return the spreadsheet id.
*/
function _handle_mso_excel_get_google_spreadsheet_id(FileName) {
 // Upload the Excel files being opened by the API to Google Drive and convert
 // them to Google Sheets.
 // Determine the spreadsheet ID of the Google Sheets file created.
 // Implement this method to return the corresponding spreadsheet ID when given
 //the original file path as parameter.
 throw new Error('Please return the spreadsheet ID corresponding to filename: ' + FileName);
 return '';
}

وفقًا للتعليمات الواردة في التعليقات في العيّنة أعلاه، عليك تحويل الملفات المستهدَفة إلى ملفات "جداول بيانات Google" على Google Drive.

تظهر أرقام تعريف جداول بيانات Google المقابلة مميّزة بالخطّ العريض أدناه:

الملف رقم 1: C:\Data\abc.xlsx يصبح https://docs.google.com/spreadsheets/d/abc123Abc123Abc123abc
الملف رقم 2: C:\Data\abc.xlsx يصبح https://docs.google.com/spreadsheets/d/xyz456Xyz456xYz456xyZ

بعد ذلك، عدِّل الرمز في دالة "برمجة تطبيقات Google" لفتح الملفات حسب رقم التعريف، كما هو موضح أدناه:

/**
* Method to return the spreadsheet id manually.
*
* @param {string} FileName ID of the spreadsheet to be opened.
* @return {string} return the spreadsheet id.
*/
function _handle_mso_excel_get_google_spreadsheet_id(FileName) {
 // Upload the Excel files being opened by the API to Google Drive and convert
 //them to Google Sheets.
 // Determine the spreadsheet ID of the Google Sheets file created.
 // Implement this method to return the corresponding spreadsheet ID when given
 //the original file path as parameter
 if (Filename.indexOf("abc.xlsx") >= 0) {
   return "abc123Abc123Abc123abc";
 } else if (Filename.indexOf("xyz.xlsx") >= 0) {
   return "xyz456Xyz456xYz456xyZ";
 }

خطأ متعمد

تتم إضافة أخطاء مقصودة إلى الرمز البرمجي المحوَّل لمحاكاة سلوك الخطأ في رمز VBA الأصلي. لست بحاجة إلى تعديل هذه الأخطاء.

مثال على خطأ متعمّد

إذا حاولت الوصول إلى عنصر خارج حدود صفيف في VBA، يُرسِل الرمز البرمجي استثناءً. في Apps Script، يعرض الرمز قيمة غير محدّدة.

لتجنُّب النتائج غير المتوقّعة، يضيف "محوِّل الماكرو" رمزًا في Apps Script يؤدي إلى طرح استثناء في حال محاولة الوصول إلى عناصر خارج حدود الصفيف.

يظهر هذا المثال في الرمز البرمجي أدناه:

رمز VBA الأصلي

Dim arr
arr = Array("apple", "orange")
MsgBox arr(5)
Will throw the following error:
Subscript out of range

رمز Apps Script المحوَّل (قبل إضافة خطأ الاستثناء)

var arr;
arr = ["apple", "orange"];
Browser.msgBox(arr[5]);
Will return this value and not throw an error:
undefined

رمز Apps Script الذي تمت إضافته لطرح خطأ الاستثناء

/**
* Extend the regular JS array to support VB style indexing with a get method.
* @returns{*} value at the index
*/
Array.prototype.get = function() {
 var curr_res = this;
 for (var i = 0; i < arguments.length; i++) {
   if (!Array.isArray(curr_res) || curr_res.length < arguments[i]) {
     throw new Error(‘Converted VBA Error (Intentional Error): Subscript out of range’);
   }
   curr_res = curr_res[arguments[i]];
 }
 return curr_res;
};
var arr;
arr  = ["apple", "orange"];
Browser.msgBox(arr.get(5));

إصلاح الأخطاء في الرمز الذي تم تحويله

فهم ملفات "برمجة تطبيقات Google" التي تمت إضافتها إلى مشروعك

Library.gs

Unimplemented_constructs.gs

مثلاً: Window.Activate()

Variant_resolutions.gs

مثلاً: name()

العثور على الأخطاء

أنواع الأخطاء

واجهة برمجة تطبيقات لم يتم تنفيذها

إصلاح أخطاء واجهة برمجة التطبيقات غير المُطبَّقة

أمثلة على أخطاء واجهة برمجة التطبيقات غير المُطبَّقة

المثال 1: عدم توفّر بديل لـ Apps Script أو واجهة برمجة تطبيقات غير معروفة

المثال 2: نوع عنصر غير متوافق

تراكيب لغوية غير مفعَّلة

إصلاح أخطاء بنية اللغة غير المُطبَّقة

أمثلة على أخطاء بنية اللغة غير المنفَّذة

المثال 1: استبدال GoTo بـ While Loop

المثال 2: استبدال GoTo بحلقة For

واجهة برمجة تطبيقات متوافقة جزئيًا

إصلاح أخطاء واجهة برمجة التطبيقات المتوافقة جزئيًا

مثال على خطأ في واجهة برمجة التطبيقات متوافقة جزئيًا

مطلوب إجراء يدوي

إصلاح الأخطاء التي تتطلّب إجراءً يدويًا

أمثلة على الأخطاء التي تتطلّب إجراءً يدويًا

المثال 1: Autocorrect.Addreplacement

المثال 2: Workbook.open()

خطأ متعمد

مثال على خطأ متعمّد

مقالات ذات صلة

`Library.gs`

`Unimplemented_constructs.gs`

مثلاً: `Window.Activate()`

`Variant_resolutions.gs`

مثلاً: `name()`

المثال 1: استبدال `GoTo` بـ `While Loop`

المثال 1: `Autocorrect.Addreplacement`

المثال 2: `Workbook.open()`