程式庫

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

取得程式庫存取權

新版編輯器

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

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

舊版編輯器

如要在專案中納入程式庫,您至少要具備該資料庫的讀取層級權限。如果您不是想納入的圖書館作者,就必須與作者聯絡,要求對方授予存取權。

您也需要包含程式庫的專案金鑰。如果您可以存取程式庫,就可以在「File > Project Properties...」下方找到專案金鑰。否則,您必須要求程式庫的作者將專案金鑰提供給您。

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

新版編輯器

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

舊版編輯器

  1. 選取「Resources > library...」(資源 > Library...)
  2. 將您要使用的程式庫專案金鑰貼到「Add Library」(新增程式庫) 文字方塊中。
  3. 按一下「Add」,將程式庫新增至專案。
  4. 按一下「Version」下拉式選單,然後選取這個程式庫的版本。
  5. 查看您要用於這個程式庫的預設 ID 名稱。這是指令碼用來參照程式庫的名稱。舉例來說,如果您將這個值設為 Test,即可呼叫該程式庫的方法,如下所示:Test.libraryMethod()
  6. 如要覆寫所選版本,請啟用「開發模式」。詳情請參閱測試程式庫並進行偵錯
  7. 按一下「Save」(儲存) 以儲存您新增的程式庫,並關閉對話方塊。

使用程式庫

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

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

新版編輯器

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

舊版編輯器

  1. 選取「Resource > library」(資源 & 程式庫)
  2. 包含的程式庫名稱是開啟新瀏覽器分頁的連結,其中包含這個程式庫的參考說明文件。

移除媒體庫

新版編輯器

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

舊版編輯器

  1. 選取「資源 &程式庫」
  2. 按一下程式庫右側的「X」按鈕將其刪除。
  3. 按一下「儲存」,讓變更生效。

更新程式庫

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

新版編輯器

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

舊版編輯器

  1. 在編輯器頂端,按一下「資源與程式庫」
  2. 進行所需修改並按一下 [儲存]。

建立及分享程式庫

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

新版編輯器

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

舊版編輯器

  1. 儲存版本的指令碼專案。
  2. 至少授予程式庫中所有潛在使用者的讀取層級權限。
  3. 請為使用者提供程式庫的專案金鑰,並位於「File > Project Properties」下方。

最佳做法

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

  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);
  }

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

未共用的資源

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

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

測試程式庫

新版編輯器

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

舊版編輯器

編寫程式庫並執行大量測試時,建議您使用開發模式。開發模式開啟後,下列項目就會變成 true:

  1. 擁有指令碼編輯者層級存取權的使用者可以對程式庫專案中的檔案進行最新的變更,即使未儲存為版本也一樣。
  2. 無論開發模式為開啟還是關閉,只有具備指令碼讀取層級存取權的使用者仍會使用所選版本。

對程式庫進行偵錯

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