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

获取图书馆访问权限

如需将某个库添加到项目中,您必须至少拥有该库的数据视图级访问权限。如果您不是要包含的库的作者,请与相应作者联系并请求访问权限。

您需要要添加的库的脚本 ID。如果有权访问该库,您可以在项目设置 页面上找到脚本 ID。

向脚本项目添加库

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

使用库

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

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

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

移除库

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

更新库

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

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

创建和共享库

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

  1. 为脚本创建版本化部署
  2. 与该媒体库的所有潜在用户至少共享数据视图级别的访问权限。
  3. 为这些用户提供脚本 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
* 这意味着该库没有自己的功能/资源实例,而是使用由调用它的脚本创建的实例。
** 这意味着库有自己的资源/功能实例,并且使用库的所有脚本共享并可以访问同一个实例。

测试库

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

调试库

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