适用于DrBlack System Service的扩展开发文档

在开始编写扩展之前,请先做好以下准备工作:

一个你喜爱的文本编辑器/IDE
你需要实现的功能
实现的思路(通过Node.js即JavaScript)

1.首先新建一个文件夹

2.建立元数据文件

新建一个JSON文件,在其中填入以下内容,并根据下方的字段说明对您的实际情况修改内容。

{
	"name": "Hello World",
	"description": "This is a sample extension",
	"author": "Yuameshi",
	"versionCode": 1,
	"version": "1.0",
	"minimumDbssVersionCode": 0,
	"package": "xyz.han-han.example.extension",
	"injectToRendererProcess": "index.js",
	"injectToMainProcess": "main.js"
}
字段名称数据类型数据描述
name字符串(String)扩展名称
description字符串(String)扩展描述
author字符串(String)扩展作者
versionCode数字(Number)版本号
version字符串(String)版本名称
minimumDbssVersionCode数字(Number)最低支持的DrBlack System Service版本代码(详见于此页面
package字符串(String)包名,命名规则见下
injectToMainProcess字符串(String)注入到主进程的脚本相对路径
injectToRenderer字符串(String)注入到渲染进程的脚本相对路径
字段说明

包名(Package字段)说明

什么是包名 ?

DBSS使用包名(Package Name)作为应用的唯一标识。即:包名必须唯一,一个包名代表一个扩展,不允许两个扩展使用同样的包名。包名主要用于DBSS识别应用,几乎不会被最终用户看到。

包名的命名规则

可以包含大写字母(A到Z)、小写字母(a到z)、数字和下划线,可以用点(英文句号)分隔,隔开的每一段都必须以字母开头。

避免包名冲突

因为包名是唯一标识,为了避免与其他扩展的包名重复,产生冲突,您可以这样命名:
将您的域名反转过来作为前缀,比如如果您的域名是example.com,那么包名可以用com.example开头,这样可以有效的避免重复
在后面增加描述产品名称的字符,比如您的扩展将用于修改主题,可以命名为com.example.theme
如果您没有域名,可以使用自己的邮箱作为前缀,比如 com.qq.WoDeYouXiang

包名冲突如何处理?

如果您发现您尚未发布的扩展,包名和其他开发者已经发布的扩展重复了,建议立刻修改扩展的包名,避免冲突。
如果您的扩展已经发布了,但是在提交扩展时,被告知已经有其他开发者上传了同包名的扩展,可以按照指示,联系[email protected]处理。

请注意

扩展发布后,请不要修改包名,一旦您修改了包名,就会被当作一个新的扩展,旧版用户也无法直接更新扩展。

注入脚本路径说明(injectToMain/RendererProcess字段)说明

路径为相对路径,程序在调用时将调用对应的脚本注入到对应的进程,如果您的脚本位于scripts文件夹下,文件名为index.js,则填写scripts/index.js,如果位于根目录下,文件名为main.js,则直接填写main.js

3.开始编写脚本

DBSS的运行环境中包含Node支持,当前暂不支持引入外部依赖,只能引入DBSS具有的依赖,DBSS当前包含的依赖列表如下所示:

你可以在以下站点找到它们的文档

Electron
@electron/remote
Node.js
electron-prompt
node-stream-zip
regedit
sudo-prompt(于2.0.0(7)新增)
systeminformation(于2.0.0(7)新增)
mime(于2.0.0(7)新增)
electron-store(于2.0.0(7)新增)
ses(于2.0.0(7)新增)
fs-extra(已于2.0.0(7)移除)
node-powershell(已于2.0.0(7)移除)
bytenode(已于2.0.0(7)移除)

自DBSS 2.0.0(7)开始,您可以引入自定义依赖,依赖必须放在扩展根目录下或根目录下的node_modules文件夹内,但是目前DBSS扩展能在主进程中引入ES Modul入模块(引入时请使用import2函数,import()会抛出SES_IMPORT_INJECTED错误),在渲染进程冲,您只能通过require()引入,所以请您谨慎选择依赖。

另外,require在引入依赖时将优先引入DBSS的依赖,如DBSS使用了[email protected] ,而您的扩展附带了[email protected],则require将优先使用DBSS的[email protected]而不是您附带的[email protected],除非您使用绝对路径引入。

另外,DBSS现在使用的安全ECMAScript执行环境为ses,由于它的限制,不能将整个global/globalThis变量暴露给插件脚本,所以我选择了一些常用的API并暴露给插件文件。

在主进程,此列表有:

require
import2(import)
console
Math
JSON
RegExp
Date
setTimeout
clearTimeout
setInterval
clearInterval
Buffer
process
String
Number
Boolean
Array
Object
Reflect
Proxy
WeakMap
WeakSet
Map
Set
Symbol
Promise
Atomics
SharedArrayBuffer
WebAssembly
decodeURI
decodeURIComponent
encodeURI
encodeURIComponent
eval
isFinite
isNaN
parseFloat
parseInt
Uint8Array
Uint8ClampedArray
Uint16Array
Uint32Array
Int8Array
Int16Array
Int32Array
Float32Array
Float64Array
BigInt64Array
BigUint64Array
ArrayBuffer
DataView

渲染进程除了包含主进程所有的并额外包含了documentalertpromptcomfirm,但是没有import2(其实是有,用不了而已)和SharedArrayBuffer

4.打包扩展及发布

将扩展工作目录下需要的文件添加到一个ZIP格式的压缩文件中,然后提交到[email protected]处,由我们进行审核,测试,发布。

附录:DBSS内建的一些API的参考

若您有任何问题或需要DBSS的源代码来进行更进一步的参考,可以联系[email protected] 或者进群[email protected]我或者加我群984522347。

DBSS的所有API,如无说明都将包含在一个名为dbss的全局变量中。

FluentUI CSS:

最低支持版本:2.0.0(7)

可用位置:渲染进程

DBSS将在渲染进程内初始化扩展内全局变量dbss.libDbssCssUrl,值为Fluent UI CSS的URL路径,通过link标签引入后可以使用DBSS的CSS库。

libDbssUrl和libDbssPath:

最低支持版本:2.0.0(7)

可用位置:渲染进程

DBSS将在渲染进程内初始化扩展内全局变量dbss.libDbssUrldbss.libDbssPath,值分别为DBSS库的URL路径和文件路径,可以通过require引入然后可以使用DBSS库的一些函数。

extensionPath变量:

最低支持版本:2.0.0(7)

可用位置:渲染进程、主进程

DBSS将在渲染进程内初始化扩展内全局变量dbss.extensionPath,值为当前扩展的根目录路径。

prompt函数:

最低支持版本:1.0.0(0)

可用位置:渲染进程

由于Electron默认在渲染进程中不支持prompt函数,我通过封装electron-prompt制作了一个prompt函数,其定义如下:

function prompt(title: string, content: string, initData?: string, inputAttrs?: {
    required?: 'true' | 'false';
    type?: string;
}): Promise<unknown>

其中content参数支持HTML标签,虽然标明的返回是unknown,但大多数情况下此函数的返回值都是string

请注意,此函数不在对象dbss内而在globalThis中,即您调用时请使用prompt(...)而不是dbss.prompt(...)

点赞

发表回复