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

获取媒体库的访问权限

如需在项目中添加库,您必须至少具有该库的视图级访问权限。如果您不是想要添加的库的作者,请与作者联系并请求访问权限。

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

向脚本项目添加库

  1. 在 Apps 脚本编辑器的“库”旁边,点击“添加库”图标
  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 设置为 false 时,Object.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
界面
用户属性
日志记录器和执行转录
网站、电子表格和其他容器 调用 getActive() 将返回包含脚本的容器。
MailApp 和 GmailApp
* 这意味着库没有自己的功能/资源实例,并且使用由调用该实例的脚本创建的实例。
** 这意味着库有自己的资源/功能实例,并且使用库的所有脚本共享并且有权访问该实例。

测试库

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

调试库

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