库是一种脚本项目,其函数可在其他脚本中重复使用。

获得对库的访问权限

如需将库添加到项目中,您必须至少拥有对该库的查看权限。如果您不是要添加的库的作者,请与作者联系并申请访问权限。

您需要提供要添加的库的脚本 ID。获得对该库的访问权限后,您可以在项目设置 页面上找到脚本 ID。

将库添加到脚本项目中

  1. 在 Apps Script 编辑器的左侧,点击“库”旁边的“添加库”图标
  2. 在“脚本 ID”字段中,粘贴该库的脚本 ID。
  3. 点击查找
  4. 点击版本下拉菜单,然后选择要使用的库版本。
  5. 检查默认的“标识符”名称是否是您要与此库搭配使用的名称。这是脚本用于引用库的名称。例如,如果您将其设置为 Test,则可以按如下方式调用该库的方法:Test.libraryMethod()
  6. 点击添加

使用库

使用您添加的库就像使用默认服务一样。例如,如果 Test 是库的标识符,请输入 Test 后跟一个英文句点,以查看库中的方法列表。

您可以按照以下步骤打开包含的库的参考文档:

在脚本编辑器的左侧,点击库名称旁边的“更多”图标 > 在新标签页中打开

移除媒体库

在脚本编辑器的左侧,点击库名称旁边的“更多”图标 > 移除 > 移除库

更新库

您可以更改库的版本或更新其标识符。

  1. 在编辑器左侧的“库”下,点击相应库的名称。
  2. 进行更改,然后点击保存

创建和共享库

如需将脚本项目作为库使用和共享,请按以下步骤操作。

  1. 为脚本创建版本化部署
  2. 与该库的所有潜在用户至少共享查看级访问权限。
  3. 向这些用户提供脚本 ID,该 ID 位于项目设置 页面上。

最佳做法

以下是编写库时需要遵循的一些准则:

  1. 为您的项目选择一个有意义的名称,因为当其他人包含您的库时,该名称会用作默认标识符。
  2. 如果您不希望库用户看到(也无法使用)脚本的一个或多个方法,可以将方法名称以下划线结尾。例如 myPrivateMethod_()
  3. 只有可枚举的全局属性对库用户可见。这包括函数声明、使用 var 在函数外部创建的变量,以及在全局对象上显式设置的属性。例如,将 enumerable 设置为 falseObject.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() 会返回包含脚本的容器。
MailApp 和 GmailApp
* 这意味着该库没有自己的功能/资源实例,而是使用调用它的脚本创建的实例。
** 这意味着库具有自己的资源/功能实例,并且使用该库的所有脚本共享该实例并对其拥有访问权限。

测试库

如需测试您的库,请使用主部署。对脚本拥有编辑器级访问权限的任何人都可以使用主部署。

调试库

在包含库的项目中使用调试程序时,您可以进入所包含库的函数。代码会以“只能查看”模式显示在调试程序中,并且显示正确的版本。