یک کتابخانه، یک پروژه اسکریپت است که توابع آن را میتوان در اسکریپتهای دیگر دوباره استفاده کرد.
به کتابخانه دسترسی پیدا کنید
برای افزودن یک کتابخانه به پروژه خود، باید حداقل به آن دسترسی سطح مشاهده داشته باشید. اگر شما نویسنده کتابخانهای که میخواهید اضافه کنید نیستید، با نویسنده تماس بگیرید و درخواست دسترسی کنید.
شما به شناسه اسکریپت کتابخانهای که میخواهید اضافه کنید نیاز دارید. وقتی به کتابخانه دسترسی پیدا کردید، میتوانید شناسه اسکریپت را در صفحه پروژه پیدا کنید.
یک کتابخانه به پروژه اسکریپت خود اضافه کنید
- در سمت چپ ویرایشگر اسکریپت برنامهها، کنار «کتابخانهها»، روی کتابخانه کلیک کنید.
- در فیلد «شناسه اسکریپت»، شناسه اسکریپت کتابخانه را وارد کنید.
- روی «جستجو» کلیک کنید.
- روی منوی کشویی Version کلیک کنید و نسخه کتابخانه مورد استفاده را انتخاب کنید.
- بررسی کنید که آیا نام پیشفرض "شناسه" همان نامی است که میخواهید با این کتابخانه استفاده کنید یا خیر. این نامی است که اسکریپت شما برای ارجاع به کتابخانه از آن استفاده میکند. برای مثال، اگر آن را روی
Testتنظیم کنید، میتوانید متدی از آن کتابخانه را به صورت زیر فراخوانی کنید:Test.libraryMethod(). - روی افزودن کلیک کنید.
از یک کتابخانه استفاده کنید
از کتابخانهی موجود خود مانند یک سرویس پیشفرض استفاده کنید. برای مثال، اگر Test شناسهی کتابخانهی شماست، بلافاصله پس از آن Test را تایپ کنید تا لیست متدهای موجود در کتابخانه را مشاهده کنید.
مستندات مرجع برای یک کتابخانهی موجود را میتوان با دنبال کردن مراحل زیر باز کرد:
در سمت چپ ویرایشگر اسکریپت، کنار نام کتابخانه، روی More > Open in a new tab کلیک کنید.
حذف یک کتابخانه
در سمت چپ ویرایشگر اسکریپت، کنار نام کتابخانه، روی More > Remove > Remove library کلیک کنید.
بهروزرسانی یک کتابخانه
شما میتوانید نسخه کتابخانه را تغییر دهید یا شناسه آن را بهروزرسانی کنید.
- در سمت چپ ویرایشگر، در قسمت «کتابخانهها»، روی نام کتابخانه کلیک کنید.
- تغییرات خود را اعمال کنید و روی ذخیره کلیک کنید.
ایجاد و اشتراکگذاری کتابخانه
برای استفاده و اشتراکگذاری پروژه اسکریپت خود به عنوان یک کتابخانه، مراحل زیر را دنبال کنید.
- یک نسخه از اسکریپت خود ایجاد کنید .
- حداقل دسترسی سطح مشاهده را با همه کاربران بالقوه کتابخانه به اشتراک بگذارید.
- به آن کاربران شناسه اسکریپت را بدهید که میتوانید آن را در صفحه پروژه پیدا کنید.
بهترین شیوهها
در اینجا چند دستورالعمل برای نوشتن یک کتابخانه آورده شده است:
- یک نام معنادار برای پروژه خود انتخاب کنید، زیرا وقتی کتابخانه شما توسط دیگران اضافه میشود، به عنوان شناسه پیشفرض استفاده میشود.
- اگر میخواهید یک یا چند متد از اسکریپت شما برای کاربران کتابخانه قابل مشاهده (یا استفاده) نباشد، میتوانید نام متد را با یک زیرخط (_) به پایان برسانید. به عنوان مثال،
myPrivateMethod_(). - فقط ویژگیهای سراسری قابل شمارش برای کاربران کتابخانه قابل مشاهده هستند. این شامل تعریف توابع، متغیرهایی که خارج از یک تابع با
varایجاد میشوند و ویژگیهایی که صریحاً روی شیء سراسری تنظیم شدهاند، میشود. برای مثال،Object.defineProperty()با مقداردهیenumerableبهfalse، نمادی را ایجاد میکند که میتوانید در کتابخانه خود استفاده کنید، اما این نماد توسط کاربران شما قابل دسترسی نیست. اگر میخواهید کاربران کتابخانه شما از قابلیت تکمیل خودکار ویرایشگر اسکریپت و مستندات تولید شده خودکار استفاده کنند، باید مستنداتی به سبک JSDoc برای تمام توابع خود داشته باشید. در اینجا مثالی آورده شده است:
/** * Raises a number to the given power, and returns the result. * * @param {number} base the number we're raising to a power * @param {number} exp the exponent we're raising the base to * @return {number} the result of the exponential calculation */ function power(base, exp) { ... }
محدودهبندی منابع
وقتی با کتابخانهها کار میکنید، دو نوع منبع وجود دارد: اشتراکی و غیر اشتراکی. منبع اشتراکی به این معنی است که هم کتابخانه و هم اسکریپتِ دربرگیرنده، به یک نمونه از منبع دسترسی داخلی دارند. نمودار زیر یک منبع اشتراکی را با استفاده از مثالِ ویژگیهای کاربر نشان میدهد:
یک منبع غیراشتراکی به این معنی است که هم کتابخانه و هم اسکریپت شامل آن، فقط به نمونه منبع خود دسترسی داخلی دارند. با این حال، یک کتابخانه میتواند با داشتن توابع صریح که روی منابع غیراشتراکی خود عمل میکنند، به آنها دسترسی داشته باشد. در اینجا مثالی از تابعی که میتوانید در کتابخانه خود برای نمایش ویژگیهای اسکریپت آن قرار دهید، آورده شده است:
function getLibraryProperty(key) {
const scriptProperties = PropertiesService.getScriptProperties();
return scriptProperties.getProperty(key);
}
نمودار زیر یک منبع غیر مشترک را با استفاده از مثال Script Properties نشان میدهد:
این جدول منابع مشترک و غیر مشترک را برای مرجع شما فهرست میکند:
| منبع | به اشتراک گذاشته شده* | غیر مشترک** | یادداشتها |
|---|---|---|---|
| قفل |  | همین نمونه هنگام ایجاد در کتابخانه برای همه، از جمله اسکریپتها، قابل مشاهده است. | |
| ویژگیهای اسکریپت | | همین نمونه هنگام ایجاد در کتابخانه برای همه، از جمله اسکریپتها، قابل مشاهده است. | |
| حافظه پنهان | | همین نمونه هنگام ایجاد در کتابخانه برای همه، از جمله اسکریپتها، قابل مشاهده است. | |
| محرکها | | تریگرهای سادهای که در کتابخانه ایجاد میشوند، توسط اسکریپتِ شاملکننده، فعال نمیشوند. | |
| اسکریپتاپ | | ||
| یوآیاپ | | ||
| ویژگیهای کاربر | | ||
| ثبت کننده و رونوشت اجرا | | ||
| سایتها، برگهها و سایر کانتینرها | | فراخوانی تابع getActive() کانتینر اسکریپت شامل شده را برمیگرداند. | |
| میلاپ و جیمیلاپ | | ||
| * این بدان معناست که کتابخانه نمونهی مخصوص به خود از آن ویژگی/منبع را ندارد و در عوض از نمونهای که توسط اسکریپتی که آن را فراخوانی کرده ایجاد شده است، استفاده میکند. ** این بدان معناست که کتابخانه نمونهی مخصوص به خود از منبع/ویژگی را دارد و تمام اسکریپتهایی که از کتابخانه استفاده میکنند، به همان نمونه دسترسی دارند و آن را به اشتراک میگذارند. | |||
تست یک کتابخانه
برای آزمایش کتابخانه خود، از استقرار سر استفاده کنید. هر کسی که دسترسی سطح ویرایشگر به اسکریپت داشته باشد میتواند از استقرار سر استفاده کند.
اشکالزدایی یک کتابخانه
وقتی از اشکالزدا در پروژهای که شامل یک کتابخانه است استفاده میکنید، میتوانید وارد تابعی از کتابخانهی موجود شوید. کد در اشکالزدا در حالت فقط مشاهده و در نسخه مناسب نمایش داده میشود.