程式庫

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

取得程式庫存取權

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

您必須擁有要納入的程式庫指令碼 ID。可以存取程式庫時,您可以在「Project Settings」 頁面中找到指令碼 ID。

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

  1. 在 Apps Script 編輯器的左側,按一下「程式庫」旁邊的「新增程式庫 」。
  2. 在「指令碼 ID」欄位中,貼上程式庫的指令碼 ID。
  3. 按一下「查詢」
  4. 按一下「版本」下拉式選單,然後選取要使用的程式庫版本。
  5. 查看預設的「ID"名稱」是您要用於這個程式庫的名稱。這是指令碼用來參照程式庫的名稱。舉例來說,如果您將這個值設為 Test,即可呼叫該程式庫的方法,如下所示:Test.libraryMethod()
  6. 按一下「新增」。

使用程式庫

使用包含的程式庫時,請使用預設服務。舉例來說,如果 Test 是程式庫的 ID,請輸入 Test,後面加上半形句號,即可查看程式庫中的方法清單。

您可以按照下列步驟開啟所含程式庫的參考說明文件:

在指令碼編輯器的左側,按一下資料庫名稱旁的「更多」圖示 >「在新分頁開啟」

移除媒體庫

在指令碼編輯器左側,按一下程式庫名稱旁的「更多」圖示 >Remove >Remove library

更新程式庫

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

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

建立及分享程式庫

如要使用並分享指令碼專案做為程式庫,請按照下列步驟操作。

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

最佳做法

編寫程式庫時,請遵循下列規範:

  1. 為專案選擇一個有意義的名稱,因為該程式庫將包含您在程式庫內的預設 ID。
  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) { ... }
    

資源範圍

使用程式庫時,有兩種類型:共用和非共用。共用資源代表程式庫和內含的指令碼都擁有對同一資源執行個體的內建存取權。下圖說明使用使用者屬性範例的共用資源:

共用資源

非共用資源表示程式庫和內含的指令碼都只有資源資源的內建存取權。不過,程式庫可透過提供明確函式,將其提供給未共用的資源來存取。以下是在程式庫中加入的函式範例,可用於公開其指令碼屬性:

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

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

未共用的資源

下表列出共用和未共用的資源:

資源 共用* 未共用** Notes
鎖定 在程式庫中建立指令碼時,所有執行個體皆可查看相同的執行個體。
指令碼內容 在程式庫中建立指令碼時,所有執行個體皆可查看相同的執行個體。
快取 在程式庫中建立指令碼時,所有執行個體皆可查看相同的執行個體。
觸發條件 在程式庫中建立的簡易觸發條件不會由包含的指令碼觸發。
指令碼應用程式
UiApp
使用者屬性
記錄器和執行轉錄稿
協作平台、試算表和其他容器 呼叫 getActive() 會傳回包含指令碼的容器。
MailApp 和 GmailApp
* 這表示程式庫本身沒有特徵/資源的專屬執行個體,而是使用叫用該指令碼的指令碼建立的執行個體。
** 這表示資料庫有自己的資源/功能執行個體,且使用程式庫的所有指令碼都會共用且可存取該執行個體。

測試程式庫

如要測試程式庫,請使用頭部部署作業。具備指令碼編輯者層級存取權的使用者皆可使用頭部部署。

對程式庫進行偵錯

如果在包含程式庫的專案中使用偵錯工具,則可以進入內含程式庫的函式。程式碼會以僅供檢視的模式和正確的版本顯示在偵錯工具中。