程式庫

程式庫是指令碼專案，其中的函式可在其他指令碼中重複使用。

存取圖書館

如要在專案中加入程式庫，您必須至少擁有程式庫的檢視層級存取權。如要加入的程式庫不是您所撰寫，請與作者聯絡並要求存取權。

您需要納入程式庫的指令碼 ID。存取程式庫後，您可以在「專案設定」 頁面找到指令碼 ID。

在指令碼專案中新增程式庫

  1. 在 Apps Script 編輯器的左側，按一下「程式庫」旁邊的「新增程式庫」圖示 。
  2. 在「指令碼 ID」欄位中，貼上程式庫的指令碼 ID。
  3. 按一下「查詢」。
  4. 按一下「版本」下拉式選單，然後選取要使用的程式庫版本。
  5. 確認預設的「識別碼」名稱是否要與這個程式庫搭配使用。這是指令碼用來參照程式庫的名稱。舉例來說，如果將其設為 Test，則可以呼叫該程式庫的方法，如下所示：Test.libraryMethod()。
  6. 按一下 [新增]。

使用程式庫

使用內建程式庫的方式與使用預設服務相同。舉例來說，如果 Test 是程式庫的 ID，請輸入 Test，然後立即輸入半形句號，即可查看程式庫中的方法清單。

如要開啟隨附程式庫的參考文件，請按照下列步驟操作：

在指令碼編輯器的左側，按一下程式庫名稱旁邊的「更多」，然後選取「在新分頁中開啟」。

移除媒體庫

在指令碼編輯器左側，依序點選程式庫名稱旁邊的「更多」圖示 「移除」>「移除程式庫」。

更新程式庫

您可以變更程式庫版本或更新其 ID。

  1. 在編輯器左側的「程式庫」下方，按一下程式庫名稱。
  2. 進行變更，然後按一下「儲存」。

建立及共用程式庫

如要將指令碼專案當做程式庫使用及共用，請按照下列步驟操作。

  1. 建立指令碼的版本化部署作業。
  2. 與所有可能的程式庫使用者分享至少檢視層級的存取權。
  3. 將指令碼 ID 提供給這些使用者，指令碼 ID 位於「專案設定」頁面。

最佳做法

撰寫程式庫時，請遵守下列準則：

  1. 請為專案選擇有意義的名稱，因為其他人納入程式庫時，這個名稱會做為預設 ID。
  2. 如果不想讓程式庫使用者看到 (或使用) 某個或多個指令碼方法，可以在方法名稱結尾加上底線。例如 myPrivateMethod_()。
  3. 程式庫使用者只能看到可列舉的全球屬性。包括函式宣告、以 var 在函式外部建立的變數，以及在全域物件上明確設定的屬性。舉例來說，如果將 Object.defineProperty() 設為 enumerablefalse，系統會建立可在程式庫中使用的符號，但使用者無法存取這個符號。

  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) { ... }

資源範圍

使用程式庫時，資源可分為共用和非共用兩種。共用資源是指程式庫和包含的指令碼都內建存取相同資源例項的權限。下圖以「使用者屬性」為例，說明共用資源：

共用資源

如果資源未共用，表示程式庫和包含的指令碼都只能存取資源的執行個體。不過，程式庫可以提供存取權給未共用的資源，方法是讓明確函式對這些資源執行作業。以下範例函式會納入程式庫，以公開指令碼屬性：

  function getLibraryProperty(key) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

下圖以指令碼屬性為例，說明非共用資源：

未共用的資源

下表列出共用和非共用資源，供您參考：

資源 已分享* 未共用** 附註
鎖定 在程式庫中建立的執行個體會對所有人 (包括指令碼) 顯示。
指令碼內容 在程式庫中建立的執行個體會對所有人 (包括指令碼) 顯示。
快取 在程式庫中建立的執行個體會對所有人 (包括指令碼) 顯示。
觸發條件 程式庫中建立的簡易觸發條件不會由包含的指令碼觸發。
ScriptApp
UiApp
使用者屬性
記錄器和執行記錄
Google 協作平台、試算表和其他容器 呼叫 getActive() 會傳回包含指令碼的容器。
MailApp 和 GmailApp
* 這表示程式庫沒有自己的功能/資源執行個體，而是使用呼叫該程式庫的指令碼所建立的執行個體。
** 這表示程式庫有自己的資源/功能執行個體，且使用該程式庫的所有指令碼都會共用並存取該執行個體。

測試程式庫

如要測試程式庫，請使用 Head 部署作業。只要具備指令碼的編輯者層級存取權，就能使用 Head 部署作業。

偵錯程式庫

在包含程式庫的專案中使用偵錯工具時，您可以逐步進入所含程式庫的函式。程式碼會以唯讀模式顯示在偵錯工具中，且為正確版本。