یک کتابخانه، یک پروژه اسکریپت است که توابع آن را میتوان در اسکریپتهای دیگر دوباره استفاده کرد.
اسکریپتی که از یک کتابخانه استفاده میکند، به سرعتی که اگر تمام کد در یک پروژه اسکریپت واحد قرار میگرفت، اجرا میشد، اجرا نمیشود . اگرچه کتابخانهها میتوانند توسعه و نگهداری را راحتتر کنند، اما در پروژههایی که سرعت بسیار مهم است، از آنها به مقدار کم استفاده کنید. به دلیل این مشکل، استفاده از کتابخانه باید در افزونههای Google Workspace محدود شود.
به کتابخانه دسترسی پیدا کنید
برای افزودن یک کتابخانه به پروژه خود، باید حداقل به آن دسترسی سطح مشاهده داشته باشید. اگر شما نویسنده کتابخانهای که میخواهید اضافه کنید نیستید، با نویسنده تماس بگیرید و درخواست دسترسی کنید.
شما به شناسه اسکریپت کتابخانهای که میخواهید اضافه کنید نیاز دارید. وقتی به کتابخانه دسترسی پیدا کردید، شناسه اسکریپت را در صفحه پروژه پیدا کنید.
یک کتابخانه به پروژه اسکریپت خود اضافه کنید
- در سمت چپ ویرایشگر اسکریپت برنامهها، کنار «کتابخانهها»، روی کتابخانه کلیک کنید.
- در فیلد «شناسه اسکریپت»، شناسه اسکریپت کتابخانه را وارد کنید.
- روی «جستجو» کلیک کنید.
- روی منوی کشویی 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 کانتینر اسکریپت شامل را برمیگرداند. | |
| میلاپ و جیمیلاپ | | ||
| * این بدان معناست که کتابخانه نمونهی مخصوص به خود از آن ویژگی/منبع را ندارد و در عوض از نمونهای که توسط اسکریپتی که آن را فراخوانی کرده ایجاد شده است، استفاده میکند. ** این بدان معناست که کتابخانه نمونهی مخصوص به خود از منبع/ویژگی را دارد و تمام اسکریپتهایی که از کتابخانه استفاده میکنند، به همان نمونه دسترسی دارند و آن را به اشتراک میگذارند. | |||
تست یک کتابخانه
برای آزمایش کتابخانه خود، از استقرار سر استفاده کنید. هر کسی که دسترسی سطح ویرایشگر به اسکریپت داشته باشد میتواند از استقرار سر استفاده کند.
شما هنوز به حداقل یک نسخه ذخیره شده از کتابخانه نیاز دارید.
اشکالزدایی یک کتابخانه
وقتی اسکریپتی را که شامل یک کتابخانه است اشکالزدایی میکنید، نمیتوانید وارد کد کتابخانه شوید یا نقاط توقف در آن تنظیم کنید. اگر سعی کنید در حالت اشکالزدایی وارد یک تابع کتابخانه شوید، اشکالزدا تابع را نادیده میگیرد و به خط بعدی در اسکریپت فراخواننده میرود.
استفاده از HEAD (حالت توسعه) برای نسخه کتابخانه، امکان ورود به کتابخانه یا رسیدن به نقاط توقف درون آن را فراهم نمیکند.
برای اشکالزدایی کد کتابخانه، از یکی از روشهای زیر استفاده کنید:
- اشکالزدایی از پروژه کتابخانه : پروژه اسکریپت کتابخانه را در ویرایشگر Apps Script باز کنید. برای آزمایش توابع کتابخانه با آرگومانهای خاص، یک تابع "آزمایشی" موقت در پروژه کتابخانه ایجاد کنید که توابع کتابخانه شما را فراخوانی کند، سپس آن تابع آزمایشی را در حالت اشکالزدایی اجرا کنید.
- ثبت وقایع : از
console.log()در توابع کتابخانه خود برای خروجی اطلاعات در گزارشهای اجرا استفاده کنید. وقتی کتابخانه توسط اسکریپت دیگری فراخوانی میشود، این گزارشها در گزارشهای اجرای اسکریپت فراخوانیکننده ظاهر میشوند.