程式庫

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

取得程式庫存取權

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

您需要要納入的程式庫指令碼 ID。如果您有權存取程式庫,即可在「專案設定」 頁面找到指令碼 ID。

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

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

使用程式庫

使用內含的程式庫時,請按照預設服務的使用方式操作。舉例來說,如果 Test 是程式庫的 ID,請輸入 Test 後接上一個句點,即可查看程式庫中的方法清單。

如要開啟所附加程式庫的參考資料文件,請按照下列步驟操作:

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

移除媒體庫

在指令碼編輯器左側的程式庫名稱旁邊,依序按一下「更多」圖示 >「移除」>「移除程式庫」

更新程式庫

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

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

建立及分享資料庫

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

  1. 建立指令碼的版本化部署作業
  2. 與程式庫的所有潛在使用者共用至少檢視層級的存取權。
  3. 將指令碼 ID 提供給這些使用者,您可以在「專案設定」頁面中找到這組 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);
  }

下圖以 Script Properties 為例,說明非共用資源:

未共用資源

以下表格列出共用和不共用的資源,供您參考:

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

測試程式庫

如要測試程式庫,請使用首要部署。任何具有編輯器層級存取權的指令碼使用者,都可以使用主部署作業。

為程式庫偵錯

在含有程式庫的專案中使用偵錯工具時,您可以逐步開啟所附程式庫的函式。程式碼會以僅供檢視模式顯示在偵錯工具中,且顯示正確的版本。