程式庫

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

取得程式庫的存取權

如要在專案中加入程式庫，您至少須具備該程式庫的資料檢視層級存取權。如果您不是要納入圖書館的作者，請與作者聯絡並要求存取權。

您必須具備所要加入程式庫的指令碼 ID。如果您可以存取程式庫，可以在「專案設定」 頁面中找到指令碼 ID。

將程式庫新增至指令碼專案

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

使用程式庫

使用內含預設服務的程式庫。舉例來說，如果 Test 是程式庫的 ID，請在緊接輸入 Test 後加上半形句號，以查看程式庫中的方法清單。

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

在指令碼編輯器左側的程式庫名稱旁邊，依序點選「更多」圖示 >「在新分頁中開啟」。

移除程式庫

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

更新程式庫

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

  1. 在編輯器左側的「程式庫」下方，按一下資料庫名稱。
  2. 進行所需修改並按一下「儲存」。

建立及分享程式庫

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

  1. 為指令碼建立版本化部署。
  2. 至少與程式庫的所有潛在使用者共用最低的資料檢視層級存取權。
  3. 為這些使用者提供指令碼 ID (可在「Project settings」(專案設定) 頁面找到)。

最佳做法

以下是編寫程式庫時應遵循的準則：

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

  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) {
    return ScriptProperties.getProperty(key);
  }

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

非共用資源

下表列出了共用和非共用的資源，方便您參考：

資源 共用* 未分享** 附註
鎖定 在程式庫中建立時，所有包括指令碼都能看到相同的執行個體。
指令碼內容 在程式庫中建立時，所有包括指令碼都能看到相同的執行個體。
快取 在程式庫中建立時，所有包括指令碼都能看到相同的執行個體。
觸發條件 內含的指令碼不會觸發在程式庫中建立的簡易觸發條件。
ScriptApp
UiApp
使用者屬性
記錄器和執行轉錄稿
網站、試算表和其他容器 呼叫 getActive() 會傳回包含指令碼的容器。
郵件應用程式和 Gmail 應用程式
* 這表示程式庫沒有專屬的功能/資源例項，而是使用由叫用該程式庫的指令碼建立的執行個體。
** 這表示程式庫有專屬的資源/功能執行個體，且使用程式庫的所有指令碼皆可共用且存取該執行個體。

測試程式庫

如要測試程式庫，請使用 Head Deployment。凡是具備指令碼編輯者層級存取權的使用者，都可以使用主要部署作業。

對程式庫進行偵錯

在包含程式庫的專案中使用偵錯工具時，您可以進入已納入程式庫的函式。程式碼會在偵錯工具中顯示 (處於唯讀模式) 和正確版本時顯示。