程式庫是一種指令碼專案,其函式可在其他指令碼中重複使用。
取得程式庫存取權
如要在專案中加入程式庫,您至少須具備查看層級的存取權。如果您不是要納入資料庫的作者,請與作者聯絡並要求存取權。
您需要新增要納入的程式庫指令碼 ID。如果您有權存取程式庫,即可在「專案設定」
頁面找到指令碼 ID。在指令碼專案中新增程式庫
- 在 Apps Script 編輯器左側,按一下「程式庫」旁邊的「新增程式庫」圖示 。
- 在「指令碼 ID」欄位中,貼上程式庫的指令碼 ID。
- 按一下「查詢」。
- 按一下「Version」下拉式選單,然後選取要使用的程式庫版本。
- 檢查預設的「Identifier」名稱是否為您想搭配這個程式庫使用的名稱。這是指令碼用來參照程式庫的名稱。舉例來說,如果將其設為
Test
,即可呼叫該程式庫的方法,如下所示:Test.libraryMethod()
。 - 按一下「新增」。
使用程式庫
使用您隨附的程式庫,就像使用預設服務一樣。舉例來說,如果 Test
是程式庫的 ID,請輸入 Test
,然後加上半形句號,即可查看程式庫中的方法清單。
請按照下列步驟開啟內含程式庫的參考說明文件:
在指令碼編輯器左側,依序點選程式庫名稱旁邊的「更多」圖示
>「在新分頁中開啟」。移除資料庫
在指令碼編輯器的左側,依序點選程式庫名稱旁邊的「更多」圖示
>「移除」>「移除程式庫」。更新程式庫
您可以變更程式庫的版本或更新 ID。
- 在編輯器左側的「程式庫」下方,按一下程式庫名稱。
- 進行所需修改並按一下「儲存」。
建立及分享資料庫
如要以程式庫的形式使用及共用指令碼專案,請按照下列步驟操作。
- 為指令碼建立版本化部署。
- 與程式庫的所有潛在使用者共用至少檢視層級的存取權。
- 為這些使用者提供指令碼 ID,您可以在「專案設定」 頁面找到這個 ID。
最佳做法
編寫程式庫時,請遵循下列準則:
- 請為專案選擇有意義的名稱,因為當其他使用者納入您的程式庫時,就會使用這個名稱做為預設 ID。
- 如果希望程式庫使用者看不到 (或無法使用) 您指令碼的一或多個方法,可以在方法名稱結尾加上底線。例如
myPrivateMethod_()
。 - 程式庫使用者只能看到列舉的全域屬性。這包括函式宣告、使用
var
在函式外建立的變數,以及在全域物件上明確設定的屬性。例如,將enumerable
設為false
的Object.defineProperty()
會建立可在程式庫中使用的符號,但使用者無法存取這個符號。 如要讓程式庫使用者使用指令碼編輯器自動完成功能和自動產生的說明文件,所有函式都必須具有 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 部署。具備指令碼編輯者層級存取權的使用者都可以使用主要部署作業。
對程式庫偵錯
在含有程式庫的專案中使用偵錯工具時,您可以逐步開啟所附程式庫的函式。程式碼會顯示在偵錯工具的僅供檢視模式中,並以正確版本顯示。