库是一个脚本项目,其函数可在其他脚本中重复使用。
获取图书馆的访问权限
如需在项目中添加库,您必须至少具有对该库的视图级访问权限。如果您不是所要添加库的作者,请联系作者并请求访问权限。
您需要要包含的库的脚本 ID。如果您有权访问该库,就可以在项目设置
页面上找到脚本 ID。向脚本项目添加库
- 在 Apps 脚本编辑器左侧的“库”旁边,点击“添加库”图标 。
- 在“脚本 ID”字段中,粘贴相应库的脚本 ID。
- 点击查找。
- 点击版本下拉列表,然后选择要使用的库的版本。
- 检查默认的“标识符”名称是否是要用于此库的名称。这是您的脚本用来引用库的名称。例如,如果您将其设为
Test
,则可以按如下方式调用该库的一个方法:Test.libraryMethod()
。 - 点击添加。
使用库
像使用默认服务一样使用包含的库。例如,如果 Test
是库的标识符,请输入 Test
,后跟英文句点,以查看库中的方法列表。
您可以按照以下步骤打开所包含库的参考文档:
在脚本编辑器的左侧,在相应库的名称旁边,依次点击“More”(更多)图标
> Open in a new tab(在新标签页中打开)。移除库
在脚本编辑器的左侧,在库名称旁边,依次点击“更多”图标
>“移除”>“移除库”。更新库
您可以更改库的版本或更新其标识符。
- 在编辑器左侧的“库”下,点击库的名称。
- 进行更改,然后点击保存。
创建和共享媒体库
如需将脚本项目作为库使用和共享,请按以下步骤操作。
- 为您的脚本创建版本化部署。
- 至少与库的所有潜在用户共享数据视图级别的访问权限。
- 为这些用户提供脚本 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() 将返回包含脚本的容器。 |
||
MailApp 和 GmailApp | |||
* 这意味着库没有自己的功能/资源实例,而是使用由调用它的脚本创建的实例。
** 这意味着库有自己的资源/功能实例,并且使用该库的所有脚本共享并访问该实例。 |
测试库
如需测试您的库,请使用 head 部署。对脚本拥有编辑者级访问权限的任何人都可以使用 head 部署。
调试库
在包含库的项目中使用调试程序时,您可以单步进入所包含库的函数。代码会以正确的版本显示在调试程序中的“只能查看”模式下。