توسيع نطاق تطبيق "جداول بيانات Google" باستخدام الإضافات
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
جداول بيانات Google هو حلّ جداول بيانات مستنِد إلى السحابة الإلكترونية يتيح التعاون في الوقت الفعلي ويتضمّن أدوات فعّالة لتصوّر البيانات ومعالجتها ومشاركتها.
يمكنك توسيع نطاق "جداول بيانات Google" باستخدام إضافات تساعدك في تحسين سير العمل المخصّص، وإنشاء اتصال بأنظمة تابعة لجهات خارجية، ودمج بيانات "جداول بيانات Google" مع تطبيقات Google Workspace الأخرى (مثل "العروض التقديمية من Google").
يمكنك الاطّلاع على إضافات "جداول بيانات Google" التي أنشأها الآخرون على Google Workspace Marketplace.
الإجراءات التي يمكنك اتّخاذها
في ما يلي بعض الإجراءات التي يمكنك تنفيذها باستخدام إضافة توسّع نطاق "جداول بيانات Google":
يتم إنشاء إضافات "جداول بيانات Google" باستخدام "برمجة تطبيقات Google". لمزيد من المعلومات حول كيفية الوصول إلى "جداول بيانات Google" وإدارتها باستخدام Apps Script، يُرجى الاطّلاع على توسيع نطاق "جداول بيانات Google".
بنية ورقة البيانات
يتكوّن جدول بيانات Google Sheets من ورقة واحدة أو أكثر. كل ورقة هي في الأساس شبكة ثنائية الأبعاد من الخلايا التي يمكن تخزين النصوص أو الأرقام أو الروابط أو القيم الأخرى فيها. تُسمّى مجموعة من خلية واحدة أو أكثر من الخلايا المتجاورة نطاقًا.
توفّر خدمة جداول البيانات في Apps Script عدة فئات لتمثيل البُنى التنظيمية في "جداول بيانات Google" (مثل Sheet وRange). يمكنك استخدام هذه الفئات لقراءة بيانات "جداول بيانات Google" وتعديلها وسلوكها.
العوامل التي تؤدي إلى الظهور
تسمح المشغّلات في "برمجة تطبيقات Google" لمشروع نص برمجي بتنفيذ دالة محدّدة عند استيفاء شروط معيّنة، مثل فتح جدول بيانات أو تثبيت إضافة.
اطّلِع على مشغّلات الإضافات لمزيد من المعلومات حول المشغّلات التي يمكن استخدامها مع إضافات "جداول بيانات Google" والقيود التي تنطبق على استخدامها.
الدوال المخصّصة
تتضمّن "جداول بيانات Google" عددًا من الدوال المضمّنة مثل SUM وAVERAGE التي يمكن استدعاؤها من داخل خلية في "جدول بيانات Google".
يمكن أن تحدّد إضافات Sheets دوال مخصّصة إضافية لتكملة هذه الدوال المضمّنة. عندما يثبّت المستخدم الإضافة، تصبح أي دوال مخصّصة محدّدة مضمّنة في الإضافة متاحة على الفور. من الممكن أن تتألف الإضافة من تعريفات الدوال المخصّصة فقط. تتم مشاركة تعريفات الدوال المخصّصة بشكل أساسي مع الآخرين من خلال نشر إضافة تحتوي على التعريفات.
إنشاء دوال مخصّصة للإضافات
يمكن استخدام أي دالة محدّدة في مشروع نص برمجي خاص بميزة إضافية كدالة مخصّصة. بعد تنفيذ الدالة وتثبيت الإضافة، يمكنك استدعاء الدالة المخصّصة كما تفعل مع أي دالة مضمّنة أخرى في "جداول بيانات Google": في خلية في جدول بيانات، أدخِل = متبوعًا باسم الدالة وأي مَعلمات مطلوبة. إذا لم تكن هناك أخطاء، يتم وضع النتيجة التي تعرضها الدالة في خلية "ورقة Google"، مع تجاوزها إلى الخلايا المجاورة حسب الحاجة.
عند إنشاء دوال مخصّصة في إضافة، يجب اتّباع الإرشادات العامة للدوال المخصّصة:
بالإضافة إلى ذلك، هناك بعض الاعتبارات الخاصة التي يجب أخذها في الحسبان عند استخدام الدوال المخصّصة المحدّدة في الإضافات:
- عند تسمية الدالة، حاوِل إنشاء اسم فريد، ربما يكون مرتبطًا باسم الإضافة. إذا حدّدت إضافتان أو أكثر مثبّتتان دالات مخصّصة بالاسم نفسه، يمكن للمستخدمين استخدام إحداها فقط.
- يجب أن توضّح الإضافة الوظائف المخصّصة التي تقدّمها.
احرص على تقديم تعليقات JSDoc دقيقة للدوال المخصّصة حتى تتمكّن "برمجة تطبيقات Google" من عرض معلومات الإكمال التلقائي للمستخدم. بالإضافة إلى ذلك، ننصحك بتقديم مستندات إضافية حول الدوال المخصّصة، إما في الإضافة نفسها أو في صفحة ويب مخصّصة لدعم الإضافة.
- تتعذّر الدوال المخصّصة التي لا تكتمل في أقل من 30 ثانية ويظهر الخطأ
Internal error executing the custom function. يمكنك تقديم تجربة جيدة للمستخدم من خلال الحدّ من مقدار المعالجة التي تجريها في دالة مخصّصة.
تحسين الدالة حيثما أمكن ذلك
- لا يمكن للدوال المخصّصة استخدام خدمات Apps Script التي تتطلّب تفويضًا،
وستتعذّر مع ظهور الخطأ
You do not have permission to call X service إذا تمت محاولة ذلك. استخدِم فقط
الخدمات المسموح بها
في الدالة المخصّصة.
- تؤدي كل دالة مخصّصة في ورقة إلى إجراء طلب منفصل إلى خوادم Apps Script. إذا حاول مستخدم استخدام دوال مخصّصة في عدد كبير جدًا من الخلايا، قد يتم تنفيذ الدوال ببطء. للتخفيف من حدة هذه المشكلة، ننصحك بإبقاء الدوال المخصّصة بسيطة قدر الإمكان. إذا كنت بحاجة إلى أن تنفّذ الدالة معالجة معقّدة أو موسّعة، لا تستخدِم دالة مخصّصة، بل وفِّر هذه الوظيفة من خلال عنصر قائمة أو مربّع حوار أو تفاعل في الشريط الجانبي بدلاً من ذلك.
وحدات ماكرو في "جداول بيانات Google"
تتيح لك وحدات الماكرو تسجيل الإجراءات التي تتخذها في "جداول بيانات Google" وتكرارها لاحقًا باستخدام اختصار لوحة المفاتيح. عند إنشاء وحدة ماكرو في ورقة، تتم إضافتها كـ دالة ماكرو في مشروع مرتبط بتلك الورقة في "برمجة تطبيقات Google". لمزيد من المعلومات حول وحدات الماكرو، اطّلِع على وحدات ماكرو "جداول بيانات Google".
لا يمكن توزيع وحدات ماكرو "جداول بيانات Google" مع الإضافات. إذا تضمّنت تعريفًا لوحدة ماكرو في بيان إضافة، لن يكون هذا التعريف متاحًا لمستخدمي هذه الإضافة.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-07-31 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-31 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eGoogle Sheets add-ons enhance spreadsheets with custom workflows, external system connections, and integration with other Google Workspace apps.\u003c/p\u003e\n"],["\u003cp\u003eAdd-ons, built using Apps Script, enable data manipulation, custom menus, dialogs, and functions, triggered by specific events.\u003c/p\u003e\n"],["\u003cp\u003eCustom functions extend Google Sheets' built-in formulas, accessible directly within cells, but require adherence to naming and usage guidelines.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Sheet add-ons provide extended functionality but cannot currently distribute or utilize pre-recorded macros.\u003c/p\u003e\n"]]],["Google Sheets add-ons, built with Apps Script, extend functionality by allowing users to read, edit, visualize, and format data. They can access the Google Sheets API, create custom menus, dialogs, sidebars, and custom functions. Add-ons can also use triggers to run functions on specific events. Custom functions, when created within an add-on, become immediately available to users after installation, following specific naming and usage guidelines. Macros, while recordable actions in Sheets, are not distributable with add-ons.\n"],null,["# Extending Google Sheets with add-ons\n\n[Google Sheets](https://workspace.google.com/products/sheets/) is a cloud-based\nspreadsheet solution with real-time collaboration and powerful tools to\nvisualize, process and communicate data.\n\nYou can extend Sheets with add-ons that build customized workflow improvements,\nestablish connectivity to third-party systems, and integrate your Sheets data\nwith other Google Workspace applications (like\nGoogle Slides).\n\nYou can see the Sheets add-ons others have built on the\n[Google Workspace Marketplace](https://workspace.google.com/marketplace/category/works-with-spreadsheet).\n\nWhat you can do\n---------------\n\nHere are a few things you can do with an add-on that extends Google Sheets:\n\n- You can read, edit, visualize, and format data in Google Sheets spreadsheets using the built-in Apps Script [Spreadsheet service](/apps-script/reference/spreadsheet). The service also lets you create and modify conditional formatting and data validation rules.\n- You can use the Apps Script [advanced Sheets service](/apps-script/advanced/sheets) to access the [Google Sheets API](/workspace/sheets/api) directly.\n- You can create [custom menus](/workspace/add-ons/concepts/menus) and define multiple [custom dialogs and sidebars](/workspace/add-ons/concepts/dialogs) interfaces using standard HTML and CSS.\n- You can include [custom function](#custom_functions) definitions in your add-on.\n- You can use add-ons [triggers](#triggers) that run specified functions when certain triggering events occur.\n\nSheets add-ons are built using Apps Script. To learn more about how to access\nand manage Google Sheets with Apps Script, see\n[Extending Google Sheets](/apps-script/guides/sheets).\n\nSheet structure\n---------------\n\nA Google Sheets spreadsheet consists of one or more sheets. Each sheet is\nessentially a 2D grid of cells into which text, numbers, links, or other\nvalues can be stored. A group of one or more adjacent cells is called a\n*range*.\n\nThe Apps Script [Spreadsheet service](/apps-script/reference/spreadsheet)\nprovides several classes to represent organizational structures in Sheets\n(such as [`Sheet`](/apps-script/reference/spreadsheet/sheet) and\n[`Range`](/apps-script/reference/spreadsheet/range)). You can use these\nclasses to read and modify Sheets data and behavior.\n\nTriggers\n--------\n\nApps Script [triggers](/workspace/add-ons/concepts/editor-triggers) let a script project\nexecute a specified function when certain conditions are met, such as when a\nspreadsheet is opened or when an add-on is installed.\n\nSee [add-on triggers](/workspace/add-ons/concepts/editor-triggers) for more information\non what triggers can be used with Sheets add-ons and what restrictions apply\nto their use.\n\nCustom functions\n----------------\n\nGoogle Sheets has a number of\n[built-in functions](https://support.google.com/docs/table/25273?ref_topic=1361471)\nlike `SUM` and `AVERAGE` that can be invoked from within a Google Sheet cell.\nSheets add-ons can define additional\n[custom functions](/apps-script/guides/sheets/functions) to supplement these\nbuilt-in functions. When a user\ninstalls the add-on, any defined custom functions included with the add-on\nbecome available immediately. It is possible for an add-on to consist of\nonly custom function definitions. Custom function definitions are primarily\nshared with others by publishing an add-on containing the definitions.\n\n### Creating add-on custom functions\n\nAny function defined in an add-on script project can be used as a custom\nfunction. Once the function is implemented and the add-on is installed, you\ncan call the custom function like any other built-in Sheets function: in a\nSheet cell, enter the `=` followed by the name of the function and any required\nparameters. If there are no errors, the result returned by the function is\nplaced in the Sheet cell, overflowing to neighboring cells as necessary.\n\nWhen creating custom functions in an add-on you should follow\nthe general custom function guidelines:\n\n- [Function naming guidelines](/apps-script/guides/sheets/functions#naming)\n- [Defining function arguments](/apps-script/guides/sheets/functions#arguments)\n- [Defining the function return value](/apps-script/guides/sheets/functions#return_values)\n- [Custom function data types](/apps-script/guides/sheets/functions#data_types)\n- [Enabling autocomplete using JSDoc](/apps-script/guides/sheets/functions#autocomplete)\n- [Services custom functions can use](/apps-script/guides/sheets/functions#using_apps_script_services)\n- [Optimizing custom functions](/apps-script/guides/sheets/functions#optimization)\n\nIn addition, custom functions defined in add-ons have some special\nconsiderations:\n\n- When naming your function, try to create a unique name, perhaps related to the name of your add-on. If two or more installed add-ons define custom functions with the same name, users can only use one of them.\n- Your add-on should clearly communicate what custom functions it provides. Be sure to provide accurate JSDoc comments for your custom functions so that Apps Script can present [autocomplete](/apps-script/guides/sheets/functions#autocomplete) information to the user. In addition, consider providing additional documentation of the custom functions either in the add-on itself or on an add-on support web page.\n- Custom functions that don't complete in under 30 seconds fail with an `Internal error executing the custom function` error. Build a good user experience by limiting the amount of processing you do in a custom function. [Optimize](/apps-script/guides/sheets/functions#optimization) the function where you can.\n- Custom functions can't use Apps Script services that require authorization, and fail with a `You do not have permission to call X service` error if this is attempted. Only use the [permitted services](/apps-script/guides/sheets/functions#using_apps_script_services) in your custom function.\n- Each custom function in a sheet results in a separate call to the Apps Script servers. If a user attempts to use custom functions in too many cells, the functions may execute slowly. To mitigate this, keep your custom functions as simple as possible. If you need the function to perform complex or extended processing, don't use a custom function---provide that functionality via a menu item, dialog, or sidebar interaction instead.\n\nSheets macros\n-------------\n\n[Macros](https://support.google.com/docs/answer/7665004) let you record actions\ntaken in Google Sheets and repeat them later with a keyboard shortcut. When a\nmacro is created in a sheet, it is added as a *macro function* in an Apps\nScript project [bound](/apps-script/guides/bound) to that sheet. For more\ninformation about macros, see\n[Google Sheets macros](/apps-script/guides/sheets/macros).\n\nUnfortunately, Sheets macros *can't* be distributed with add-ons. If you include\na macro definition in an add-on's manifest, it is unavailable to users of that\nadd-on."]]
