کتابخانه ها

کتابخانه یک پروژه اسکریپت است که می توان از عملکردهای آن در اسکریپت های دیگر استفاده کرد.

به یک کتابخانه دسترسی پیدا کنید

برای گنجاندن یک کتابخانه در پروژه خود، باید حداقل دسترسی سطح دید به آن داشته باشید. اگر نویسنده کتابخانه ای نیستید که می خواهید اضافه کنید، با نویسنده تماس بگیرید و درخواست دسترسی کنید.

شما به شناسه اسکریپت کتابخانه ای که می خواهید اضافه کنید نیاز دارید. هنگامی که به کتابخانه دسترسی دارید، می توانید شناسه اسکریپت را در صفحه settings پروژه پیدا کنید.

یک کتابخانه به پروژه اسکریپت خود اضافه کنید

1. در سمت چپ ویرایشگر Apps Script، در کنار «Libraries»، روی Add a library add کلیک کنید.
2. در قسمت «شناسه اسکریپت»، شناسه اسکریپت کتابخانه را جای‌گذاری کنید.
3. روی Look up کلیک کنید.
4. روی منوی کشویی Version کلیک کنید و نسخه کتابخانه را برای استفاده انتخاب کنید.
5. بررسی کنید که آیا نام پیش‌فرض "Identifier" همان نامی است که می‌خواهید با این کتابخانه استفاده کنید. این نامی است که اسکریپت شما برای ارجاع به کتابخانه استفاده می کند. به عنوان مثال، اگر آن را روی Test تنظیم کنید، می توانید متدی از آن کتابخانه را به صورت زیر فراخوانی کنید: Test.libraryMethod() .
6. روی افزودن کلیک کنید.

از کتابخانه استفاده کنید

همانطور که از یک سرویس پیش فرض استفاده می کنید از کتابخانه گنجانده شده خود استفاده کنید. به عنوان مثال، اگر Test شناسه کتابخانه شما است، بلافاصله Test و سپس یک نقطه را تایپ کنید تا لیست روش های موجود در کتابخانه را مشاهده کنید.

اسناد مرجع برای یک کتابخانه گنجانده شده را می توان با دنبال کردن مراحل زیر باز کرد:

در سمت چپ ویرایشگر اسکریپت، در کنار نام کتابخانه، روی More more_vert > باز کردن در یک برگه جدید کلیک کنید.

یک کتابخانه را حذف کنید

در سمت چپ ویرایشگر اسکریپت، در کنار نام کتابخانه، روی More more_vert > Remove > Remove library کلیک کنید.

یک کتابخانه را به روز کنید

می توانید نسخه کتابخانه را تغییر دهید یا شناسه آن را به روز کنید.

1. در سمت چپ ویرایشگر، در بخش «کتابخانه‌ها»، روی نام کتابخانه کلیک کنید.
2. تغییرات خود را انجام دهید و روی ذخیره کلیک کنید.

ایجاد و اشتراک گذاری کتابخانه

برای استفاده و به اشتراک گذاری پروژه اسکریپت خود به عنوان یک کتابخانه، مراحل زیر را دنبال کنید.

1. یک استقرار نسخه ای از اسکریپت خود ایجاد کنید .
2. حداقل دسترسی سطح مشاهده را با همه کاربران بالقوه کتابخانه به اشتراک بگذارید.
3. به آن کاربران شناسه اسکریپت را بدهید که در صفحه settings پروژه یافت می شود.

بهترین شیوه ها

در اینجا چند دستورالعمل وجود دارد که هنگام نوشتن یک کتابخانه باید رعایت کنید:

1. یک نام معنادار برای پروژه خود انتخاب کنید زیرا زمانی که کتابخانه شما توسط دیگران گنجانده می شود، به عنوان شناسه پیش فرض استفاده می شود.
2. اگر می‌خواهید یک یا چند روش از اسکریپت شما برای کاربران کتابخانه‌تان قابل مشاهده (و یا قابل استفاده) نباشد، می‌توانید نام روش را با زیرخط پایان دهید. به عنوان مثال، myPrivateMethod_() .
3. فقط ویژگی های سراسری شمارش شده برای کاربران کتابخانه قابل مشاهده است. این شامل اعلان‌های تابع، متغیرهای ایجاد شده خارج از یک تابع با var و ویژگی‌هایی است که به صراحت روی شی سراسری تنظیم شده‌اند. برای مثال، Object.defineProperty() با مجموعه enumerable روی false نمادی را ایجاد می کند که می توانید در کتابخانه خود استفاده کنید، اما این نماد توسط کاربران شما قابل دسترسی نیست.

4. اگر می خواهید کاربران کتابخانه شما از تکمیل خودکار ویرایشگر اسکریپت و مستندات تولید شده به طور خودکار استفاده کنند، باید برای همه عملکردهای خود اسنادی به سبک 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) { ... }
   

محدوده منابع

هنگامی که با کتابخانه ها کار می کنید دو نوع منبع وجود دارد: اشتراکی و غیر اشتراکی. یک منبع مشترک به این معنی است که هم کتابخانه و هم اسکریپت شامل دسترسی داخلی به یک نمونه از منبع دارند. نمودار زیر یک منبع مشترک را با استفاده از مثال User Properties نشان می دهد:

یک منبع مشترک به این معنی است که هم کتابخانه و هم اسکریپت شامل تنها به نمونه خود از منبع دسترسی داخلی دارند. با این حال، یک کتابخانه می‌تواند دسترسی به منابع مشترک خود را با داشتن توابع صریح که بر روی آنها کار می‌کنند، فراهم کند. در اینجا نمونه ای از تابعی است که می توانید در کتابخانه خود برای نمایش ویژگی های اسکریپت آن قرار دهید:

  function getLibraryProperty(key) {
    return ScriptProperties.getProperty(key);
  }

نمودار زیر یک منبع به اشتراک گذاشته نشده را با استفاده از مثال ویژگی های اسکریپت نشان می دهد:

این جدول منابع مشترک و غیر مشترک را برای مرجع شما فهرست می کند:

منبع	به اشتراک گذاشته شده*	به اشتراک گذاشته نشده**	یادداشت ها
قفل کنید			هنگامی که در کتابخانه ایجاد می شود، همان نمونه برای همه از جمله اسکریپت ها قابل مشاهده است.
ویژگی های اسکریپت			هنگامی که در کتابخانه ایجاد می شود، همان نمونه برای همه از جمله اسکریپت ها قابل مشاهده است.
حافظه پنهان			هنگامی که در کتابخانه ایجاد می شود، همان نمونه برای همه از جمله اسکریپت ها قابل مشاهده است.
محرک ها			محرک های ساده ایجاد شده در کتابخانه توسط اسکریپت شامل فعال نمی شوند.
ScriptApp
UiApp
ویژگی های کاربر
لاگر و رونوشت اجرا
سایت ها، ورق ها و سایر ظروف			فراخوانی getActive() محفظه اسکریپت شامل را برمی گرداند.
MailApp و GmailApp
* این بدان معنی است که کتابخانه نمونه خود را از ویژگی/منبع ندارد و در عوض از نمونه ای استفاده می کند که توسط اسکریپتی که آن را فراخوانی کرده است ایجاد شده است. ** این بدان معنی است که کتابخانه نمونه خود را از منبع/ویژگی دارد و تمام اسکریپت هایی که از کتابخانه استفاده می کنند به اشتراک گذاشته شده و به همان نمونه دسترسی دارند.

یک کتابخانه را تست کنید

برای آزمایش کتابخانه خود، از استقرار هد استفاده کنید. هر کسی که در سطح ویرایشگر به اسکریپت دسترسی داشته باشد، می‌تواند از استقرار هد استفاده کند.

اشکال زدایی یک کتابخانه

هنگامی که از دیباگر در پروژه ای که شامل کتابخانه است استفاده می کنید، می توانید وارد تابعی از کتابخانه موجود شوید. کد در دیباگر در حالت فقط مشاهده و در نسخه مناسب نمایش داده می شود.