گسترش Google Sheets با افزونه‌ها
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
Google Sheets یک راه‌حل صفحه‌گسترده مبتنی بر ابر با همکاری هم‌زمان و ابزارهای قدرتمند برای تجسم، پردازش و برقراری ارتباط داده‌ها است.
می‌توانید کاربرگ‌نگار را با افزونه‌هایی گسترش دهید که بهبودهای گردش کار سفارشی‌سازی شده ایجاد می‌کنند، اتصال به سیستم‌های شخص ثالث را ایجاد می‌کنند و داده‌های کاربرگ‌نگار خود را با سایر برنامه‌های Google Workspace (مانند Google Slides) یکپارچه می‌کنند.
می‌توانید افزونه‌های Sheets را که دیگران در Google Workspace Marketplace ساخته‌اند، ببینید.
کاری که می توانید انجام دهید
در اینجا چند کار وجود دارد که می توانید با افزونه ای که Google Sheets را گسترش می دهد انجام دهید:
افزونه‌های Sheets با استفاده از Apps Script ساخته می‌شوند. برای کسب اطلاعات بیشتر درباره نحوه دسترسی و مدیریت Google Sheets با Apps Script، به گسترش Google Sheets مراجعه کنید.
ساختار ورق
یک صفحه گسترده Google Sheets از یک یا چند صفحه تشکیل شده است. هر صفحه در اصل یک شبکه دو بعدی از سلول ها است که متن، اعداد، پیوندها یا مقادیر دیگر را می توان در آن ذخیره کرد. گروهی از یک یا چند سلول مجاور را محدوده می نامند.
سرویس Apps Script Spreadsheet چندین کلاس را برای نمایش ساختارهای سازمانی در Sheets (مانند Sheet و Range ) ارائه می‌کند. می توانید از این کلاس ها برای خواندن و اصلاح داده ها و رفتار Sheets استفاده کنید.
محرک ها
راه‌اندازهای Apps Script به یک پروژه اسکریپت اجازه می‌دهد تا زمانی که شرایط خاصی وجود دارد، مانند زمانی که صفحه‌گسترده باز می‌شود یا زمانی که یک افزونه نصب می‌شود، یک عملکرد مشخص را اجرا کند.
برای اطلاعات بیشتر در مورد اینکه چه محرک هایی را می توان با برافزاهای Sheets استفاده کرد و چه محدودیت هایی برای استفاده از آنها اعمال می شود، به محرک های افزودنی مراجعه کنید.
توابع سفارشی
Google Sheets تعدادی توابع داخلی مانند SUM و AVERAGE دارد که می‌توان آنها را از داخل یک سلول Google Sheet فراخوانی کرد. افزونه‌های Sheets می‌توانند توابع سفارشی اضافی را برای تکمیل این توابع داخلی تعریف کنند. هنگامی که کاربر افزونه را نصب می کند، هر توابع سفارشی تعریف شده همراه با افزونه بلافاصله در دسترس قرار می گیرد. این امکان وجود دارد که یک افزونه فقط از تعاریف تابع سفارشی تشکیل شده باشد. تعاریف تابع سفارشی در درجه اول با انتشار یک افزونه حاوی تعاریف با دیگران به اشتراک گذاشته می شود.
ایجاد توابع سفارشی افزودنی
هر تابعی که در یک پروژه اسکریپت الحاقی تعریف شده باشد می تواند به عنوان یک تابع سفارشی استفاده شود. هنگامی که تابع اجرا شد و افزونه نصب شد، می‌توانید تابع سفارشی را مانند هر تابع دیگر برگه‌های داخلی فراخوانی کنید: در یک سلول Sheet، = را وارد کنید و نام تابع و هر پارامتر مورد نیاز را وارد کنید. اگر خطایی وجود نداشته باشد، نتیجه برگردانده شده توسط تابع در سلول Sheet قرار می گیرد و در صورت لزوم به سلول های همسایه سرریز می شود.
هنگام ایجاد توابع سفارشی در یک افزونه، باید دستورالعمل های کلی عملکرد سفارشی را دنبال کنید:
علاوه بر این، توابع سفارشی تعریف شده در افزونه ها ملاحظات خاصی دارند:
- هنگام نامگذاری تابع خود، سعی کنید یک نام منحصر به فرد ایجاد کنید، که احتمالاً مربوط به نام افزونه شما باشد. اگر دو یا چند افزونه نصب شده توابع سفارشی را با یک نام تعریف کنند، کاربران فقط می توانند از یکی از آنها استفاده کنند.
- افزونه شما باید به وضوح نشان دهد که چه عملکردهای سفارشی ارائه می دهد. حتما نظرات JSDoc دقیقی را برای عملکردهای سفارشی خود ارائه دهید تا Apps Script بتواند اطلاعات تکمیل خودکار را به کاربر ارائه دهد. علاوه بر این، ارائه اسناد اضافی از عملکردهای سفارشی را در خود افزونه یا در یک صفحه وب پشتیبانی افزونه در نظر بگیرید.
- توابع سفارشی که در کمتر از 30 ثانیه کامل نمی شوند با
Internal error executing the custom function شکست می خورند. با محدود کردن میزان پردازشی که در یک عملکرد سفارشی انجام می دهید، یک تجربه کاربری خوب ایجاد کنید. در جایی که می توانید عملکرد را بهینه کنید . - توابع سفارشی نمی‌توانند از سرویس‌های Apps Script که نیاز به مجوز دارند استفاده کنند و با خطای
You do not have permission to call X service در صورت تلاش، با شکست مواجه می‌شوند. فقط از خدمات مجاز در عملکرد سفارشی خود استفاده کنید. - هر تابع سفارشی در یک برگه منجر به تماس جداگانه ای با سرورهای Apps Script می شود. اگر کاربر بخواهد از توابع سفارشی در تعداد زیادی سلول استفاده کند، ممکن است توابع به کندی اجرا شوند. برای کاهش این امر، عملکردهای سفارشی خود را تا حد امکان ساده نگه دارید. اگر به این تابع برای انجام پردازش های پیچیده یا گسترده نیاز دارید، از یک تابع سفارشی استفاده نکنید—به جای آن، این عملکرد را از طریق یک آیتم منو، گفتگو یا تعامل نوار کناری ارائه دهید.
ماکروهای برگه
ماکروها به شما امکان می دهند اقدامات انجام شده در Google Sheets را ضبط کنید و بعداً با یک میانبر صفحه کلید آنها را تکرار کنید. هنگامی که یک ماکرو در یک برگه ایجاد می شود، به عنوان یک تابع ماکرو در پروژه Apps Script متصل به آن صفحه اضافه می شود. برای اطلاعات بیشتر درباره ماکروها، ماکروهای Google Sheets را ببینید.
متأسفانه، ماکروهای Sheets را نمی‌توان با افزونه‌ها توزیع کرد. اگر یک تعریف کلان را در مانیفست افزونه اضافه کنید، برای کاربران آن افزونه در دسترس نیست.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-07-30 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-07-30 بهوقت ساعت هماهنگ جهانی."],[[["\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."]]
