با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
کتابخانه یک پروژه اسکریپت است که می توان از عملکردهای آن در اسکریپت های دیگر استفاده کرد.
به یک کتابخانه دسترسی پیدا کنید
برای گنجاندن یک کتابخانه در پروژه خود، باید حداقل دسترسی سطح دید به آن داشته باشید. اگر نویسنده کتابخانه ای نیستید که می خواهید اضافه کنید، با نویسنده تماس بگیرید و درخواست دسترسی کنید.
شما به شناسه اسکریپت کتابخانه ای که می خواهید اضافه کنید نیاز دارید. هنگامی که به کتابخانه دسترسی دارید، می توانید شناسه اسکریپت را در صفحه settingsپروژه پیدا کنید.
یک کتابخانه به پروژه اسکریپت خود اضافه کنید
در سمت چپ ویرایشگر Apps Script، در کنار «Libraries»، روی Add a library add کلیک کنید.
در قسمت «شناسه اسکریپت»، شناسه اسکریپت کتابخانه را جای‌گذاری کنید.
روی Look up کلیک کنید.
روی منوی کشویی Version کلیک کنید و نسخه کتابخانه را برای استفاده انتخاب کنید.
بررسی کنید که آیا نام پیش‌فرض "Identifier" همان نامی است که می‌خواهید با این کتابخانه استفاده کنید. این نامی است که اسکریپت شما برای ارجاع به کتابخانه استفاده می کند. به عنوان مثال، اگر آن را روی Test تنظیم کنید، می توانید متدی از آن کتابخانه را به صورت زیر فراخوانی کنید: Test.libraryMethod() .
روی افزودن کلیک کنید.
از کتابخانه استفاده کنید
همانطور که از یک سرویس پیش فرض استفاده می کنید از کتابخانه گنجانده شده خود استفاده کنید. به عنوان مثال، اگر Test شناسه کتابخانه شما است، بلافاصله Test و سپس یک نقطه را تایپ کنید تا لیست روش های موجود در کتابخانه را مشاهده کنید.
اسناد مرجع برای یک کتابخانه گنجانده شده را می توان با دنبال کردن مراحل زیر باز کرد:
در سمت چپ ویرایشگر اسکریپت، در کنار نام کتابخانه، روی More more_vert> باز کردن در یک برگه جدید کلیک کنید.
یک کتابخانه را حذف کنید
در سمت چپ ویرایشگر اسکریپت، در کنار نام کتابخانه، روی More more_vert> Remove > Remove library کلیک کنید.
یک کتابخانه را به روز کنید
می توانید نسخه کتابخانه را تغییر دهید یا شناسه آن را به روز کنید.
در سمت چپ ویرایشگر، در بخش «کتابخانه‌ها»، روی نام کتابخانه کلیک کنید.
تغییرات خود را انجام دهید و روی ذخیره کلیک کنید.
ایجاد و اشتراک گذاری کتابخانه
برای استفاده و به اشتراک گذاری پروژه اسکریپت خود به عنوان یک کتابخانه، مراحل زیر را دنبال کنید.
حداقل دسترسی سطح مشاهده را با همه کاربران بالقوه کتابخانه به اشتراک بگذارید.
به آن کاربران شناسه اسکریپت را بدهید که در صفحه settingsپروژه یافت می شود.
بهترین شیوه ها
در اینجا چند دستورالعمل وجود دارد که هنگام نوشتن یک کتابخانه باید رعایت کنید:
یک نام معنادار برای پروژه خود انتخاب کنید زیرا زمانی که کتابخانه شما توسط دیگران گنجانده می شود، به عنوان شناسه پیش فرض استفاده می شود.
اگر می‌خواهید یک یا چند روش از اسکریپت شما برای کاربران کتابخانه‌تان قابل مشاهده (و یا قابل استفاده) نباشد، می‌توانید نام روش را با زیرخط پایان دهید. به عنوان مثال، myPrivateMethod_() .
فقط ویژگی های سراسری شمارش شده برای کاربران کتابخانه قابل مشاهده است. این شامل اعلان‌های تابع، متغیرهای ایجاد شده خارج از یک تابع با var و ویژگی‌هایی است که به صراحت روی شی سراسری تنظیم شده‌اند. برای مثال، Object.defineProperty() با مجموعه ای enumerable روی false نمادی را ایجاد می کند که می توانید در کتابخانه خود استفاده کنید، اما این نماد توسط کاربران شما قابل دسترسی نیست.
اگر می خواهید کاربران کتابخانه شما از تکمیل خودکار ویرایشگر اسکریپت و مستندات تولید شده به طور خودکار استفاده کنند، باید برای همه عملکردهای خود اسنادی به سبک JSDoc داشته باشید. در اینجا یک مثال است:
هنگامی که با کتابخانه ها کار می کنید دو نوع منبع وجود دارد: اشتراکی و غیر اشتراکی. یک منبع مشترک به این معنی است که هم کتابخانه و هم اسکریپت شامل دسترسی داخلی به یک نمونه از منبع دارند. نمودار زیر یک منبع مشترک را با استفاده از مثال User Properties نشان می دهد:
یک منبع مشترک به این معنی است که هم کتابخانه و هم اسکریپت شامل تنها به نمونه خود از منبع دسترسی داخلی دارند. با این حال، یک کتابخانه می‌تواند دسترسی به منابع مشترک خود را با داشتن توابع صریح که بر روی آنها کار می‌کنند، فراهم کند. در اینجا نمونه ای از تابعی است که می توانید در کتابخانه خود برای نمایش ویژگی های اسکریپت آن قرار دهید:
نمودار زیر یک منبع به اشتراک گذاشته نشده را با استفاده از مثال ویژگی های اسکریپت نشان می دهد:
این جدول منابع مشترک و غیر مشترک را برای مرجع شما فهرست می کند:
منبع
به اشتراک گذاشته شده*
به اشتراک گذاشته نشده**
یادداشت ها
قفل کنید
هنگامی که در کتابخانه ایجاد می شود، همان نمونه برای همه از جمله اسکریپت ها قابل مشاهده است.
ویژگی های اسکریپت
هنگامی که در کتابخانه ایجاد می شود، همان نمونه برای همه از جمله اسکریپت ها قابل مشاهده است.
حافظه پنهان
هنگامی که در کتابخانه ایجاد می شود، همان نمونه برای همه از جمله اسکریپت ها قابل مشاهده است.
محرک ها
محرک های ساده ایجاد شده در کتابخانه توسط اسکریپت شامل فعال نمی شوند.
ScriptApp
UiApp
ویژگی های کاربر
لاگر و رونوشت اجرا
سایت ها، ورق ها و سایر ظروف
فراخوانی getActive() محفظه اسکریپت شامل را برمی گرداند.
MailApp و GmailApp
* این بدان معنی است که کتابخانه نمونه خود را از ویژگی/منبع ندارد و در عوض از نمونه ای استفاده می کند که توسط اسکریپتی که آن را فراخوانی کرده است ایجاد شده است. ** این بدان معنی است که کتابخانه نمونه خود را از منبع/ویژگی دارد و تمام اسکریپت هایی که از کتابخانه استفاده می کنند به اشتراک گذاشته شده و به همان نمونه دسترسی دارند.
یک کتابخانه را تست کنید
برای آزمایش کتابخانه خود، از استقرار هد استفاده کنید. هر کسی که در سطح ویرایشگر به اسکریپت دسترسی داشته باشد، می‌تواند از استقرار هد استفاده کند.
اشکال زدایی یک کتابخانه
هنگامی که از دیباگر در پروژه ای که شامل کتابخانه است استفاده می کنید، می توانید وارد تابعی از کتابخانه موجود شوید. کد در دیباگر در حالت فقط مشاهده و در نسخه مناسب نمایش داده می شود.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eLibraries in Apps Script enable code reuse across different scripts but can impact execution speed, especially in UI-heavy applications or add-ons.\u003c/p\u003e\n"],["\u003cp\u003eTo use a library, you need its Script ID and at least view-level access, then add it to your project specifying the version and identifier.\u003c/p\u003e\n"],["\u003cp\u003eLibraries are accessed like built-in services; use the identifier followed by a period to view available methods.\u003c/p\u003e\n"],["\u003cp\u003eWhen creating a library, use meaningful names, consider visibility of methods (using underscores for private ones), and provide JSDoc documentation for user-facing functions.\u003c/p\u003e\n"],["\u003cp\u003eLibraries and scripts share certain resources like User Properties, while others, like Script Properties, are not shared and require explicit functions for access.\u003c/p\u003e\n"]]],[],null,["# Libraries\n\nA library is a script project whose functions can be reused in other scripts.\n| **Warning:** A script that uses a library [doesn't run as quickly](/apps-script/guides/support/best-practices#avoid_libraries_in_ui-heavy_scripts) as it would if all the code were contained within a single script project. Although libraries can make development and maintenance more convenient, use them sparingly in projects where speed is critical. Because of this issue, library use should be limited in [add-ons](/workspace/add-ons/overview).\n\nGain access to a library\n------------------------\n\nTo include a library in your project you must have at least view-level\naccess to it. If you aren't the author of the library that you want to\ninclude, contact the author and request access.\n\nYou need the script ID of the library you want to include. When you have\naccess to the library, you can find the script ID on the **Project Settings**\nsettings page.\n\nAdd a library to your script project\n------------------------------------\n\n1. At the left of the Apps Script editor, next to \"Libraries,\" click Add a library add.\n2. In the \"Script ID\" field, paste in the script ID of the library.\n3. Click **Look up** . If you encounter an error, make sure that you have at least view-level access to the project that you're trying to include.\n4. Click the **Version** dropdown and select the version of the library to use.\n5. Check to see if the default \"Identifier\" name is the one that you want to use with this library. This is the name that your script uses to refer to the library. For example, if you set it to `Test` then you can call a method of that library as follows: `Test.libraryMethod()`. If you use an identifier name that matches the name of an already existing service, such as [`MailApp`](/apps-script/reference/mail/mail-app), or a previously added library, then the library you have added most recently overrides the existing service or library.\n6. Click **Add**.\n\nUse a library\n-------------\n\nUse your included library as you would use a default service. For\nexample, if `Test` is the identifier for your library, type\n`Test` immediately followed by a period to see the list of methods in the library.\n\nThe reference documentation for an included library can be opened by following\nthese steps:\n\nAt the left of the script editor, next to the library name, click More\nmore_vert **\\\u003e Open in a new tab**.\n\nRemove a library\n----------------\n\nAt the left of the script editor, next to the library name, click More\nmore_vert **\\\u003e Remove \\\u003e Remove library**.\n| If a library is deleted by the author you still need to remove it from your list of included libraries.\n\nUpdate a library\n----------------\n\nYou can change the version of the library or update its identifier.\n\n1. At the left of the editor, under \"Libraries,\" click the name of the library.\n2. Make your changes and click **Save**.\n\nCreate and share a library\n--------------------------\n\nTo use and share your script project as a library, follow the below steps.\n\n1. [Create a versioned deployment](/apps-script/guides/versions) of your script.\n2. Share at least view-level access with all potential users of the library.\n3. Give those users the script ID, which can be found on the **Project\n settings** settings page.\n\n### Best practices\n\nHere are some guidelines to follow when writing a library:\n\n1. Choose a meaningful name for your project since it's used as the default identifier when your library is included by others.\n2. If you want one or more methods of your script to not be visible (nor usable) to your library users, you can end the name of the method with an underscore. For example, `myPrivateMethod_()`.\n3. Only enumerable global properties are visible to library users. This includes function declarations, variables created outside a function with `var`, and properties explicitly set on the global object. For example, `Object.defineProperty()` with `enumerable` set to `false` creates a symbol you can use in your library, but this symbol isn't accessible by your users.\n4. If you want your library users to make use of the script editor autocomplete and\n the automatically generated documentation, you must have JSDoc-style\n documentation for all your functions. Here's an example:\n\n /**\n * Raises a number to the given power, and returns the result.\n *\n * @param {number} base the number we're raising to a power\n * @param {number} exp the exponent we're raising the base to\n * @return {number} the result of the exponential calculation\n */\n function power(base, exp) { ... }\n\n### Resource scoping\n\nThere are two types of resources when you are working with libraries: shared\nand not-shared. A shared resource means that both the library and the including\nscript have a built-in access to the same instance of the resource. The\nfollowing diagram illustrates a shared resource using the example of\nUser Properties:\n\nA not-shared resource means that both library and the including script have\nbuilt-in access only to their instance of the resource. However, a library can\nprovide access to its not-shared resources by having explicit functions that\noperate on them. Here is an example of a function that you would include in\nyour library to expose its Script Properties: \n\n function getLibraryProperty(key) {\n const scriptProperties = PropertiesService.getScriptProperties();\n return scriptProperties.getProperty(key);\n }\n\nThe following diagram illustrates a not-shared resource using the example of\nScript Properties:\n\nThis table lists the shared and not-shared resources for your reference:\n\n| Resource | Shared\\* | Not-Shared\\*\\* | Notes |\n|------------------------------------|----------|----------------|------------------------------------------------------------------------------------|\n| Lock | | | The same instance is visible to all including scripts when created in the library. |\n| Script Properties | | | The same instance is visible to all including scripts when created in the library. |\n| Cache | | | The same instance is visible to all including scripts when created in the library. |\n| Triggers | | | Simple triggers created in library are not triggered by the including script. |\n| ScriptApp | | | |\n| UiApp | | | |\n| User Properties | | | |\n| Logger and execution transcript | | | |\n| Sites, Sheets and other containers | | | A call to `getActive()` returns the container of the including script. |\n| MailApp and GmailApp | | | |\n\nTest a library\n--------------\n\nTo test your library, use the head deployment. Anyone who has editor-level\naccess to the script can use the head deployment.\n| You still need at least one version of the library saved.\n\nDebug a library\n---------------\n\nWhen you use the debugger in a project that includes a library you\ncan step into a function of the included library. The code shows up in\nthe debugger in view-only mode and at the right version."]]
