yutent edited this page
SDK默认注入一段js代码, 用于实现 js与python后端通信。
注入对象
SDK注入了一个叫native的全局对象
env 环境变量 (0.4.0起支持)
// 这里默认所有的 js 文件, 都是以 ESM 方式引入的
console.log(native.env)
{
"HOME_DIR": "", // 当前用户的主目录 /home/xxx
"CONFIG_DIR": "", // 当前用户的配置目录 /home/xxx/.config
"CACHE_DIR": "" // 当前用户的缓存目录 /home/xxx/.cache
}
正常情况下, 应用的配置和缓存, 都应该放在这几个目录中
退出应用
.quit()(0.7.0已废弃, 请使用native.app.quit())。
app对象
提供基本的app属性读取和常规操作。
.name应用名称(由python设置).version应用版本.quit()无参数, 该方法不仅会关闭当前窗口, 甚至会退出当前应用(具体以各应用的配置)。.relaunch()无参数, 重启应用。.getLocale()无参数, 获取当前的语言环境。
shell对象
类似electron的shell对象的功能, 用于对系统进行一些简单的操作。
.openExternal(url)调用系统默认的浏览器打开指定URL。.showItemInFolder(path)打开指定路径的文件对话框窗口。.openPath(path)打开指定文件/目录。.trashItem(path)将指定文件/目录移入回收站。
fs对象
提供了一系列常用的文件系统的操作方法, 要注意的是, js与python的通信, 是通过信号与槽机制实现的, 传递大量数据会引发性能问题导致应用卡死或闪退, 所以, 通常只建议进行少量数据的交互。 大文件的下载保存, 应该交由python内部处理。
如无特殊说明, 以下方法, 所传的文件路径, 均为绝对路径; 返回值都是一个Promise对象
.access(filepath, mode = 'r')以特定的模式访问文件, 对应python的open方法的参数, 一般用于判断文件是否有给定的权限(如读、写等), 返回true或false..read(filepath, mode = 'r')读取文件内容, 如是读取二制文件的话, 返回的内容是 Uint8Array, 其他则返回字符串文本.write(filepath, content = '' ,mode = 'w')写入文件, 可以写字符串文本, 也可以二进制数据(Uint8Array), 文件不存在则自动创建.append(filepath, content = '' ,mode = 'w')同write方法, 区别是, 这个文件只会追加内容到原有文件中, 不会整个替换.exists(filepath)判断文件/目录是否存在.list(filepath)列出指定路径的所有文件 (不递归子目录).isfile(filepath)判断给定路径是否是一个文件.isdir(filepath)判断给定路径是否是一个目录.remove(filepath)删除给定的路径 (文件或目录, 若是目录, 会递归删除所有的文件, 需要小心操作).rename(filepath, target)重命名文件/目录.copy(filepath, target)复制文件/目录
image 原生图片对象
.image(filepath)可返回一个原生图片对象NativeImage, 这个方法, 一般用于将图片写进剪切板中。需要时, 也可以调用toJPEG()、toPNG()、toDataURL()来获取前端可用图片数据。
clipboard 对象
一般来说, js 可以通过navigator.clipboard实现自己想要的功能, 为避免某些环境下, navigator.clipboard读取不正常时, 可以调用原生的剪切板
.readText()读取剪切板中的文本内容.writeText(value)往剪切板中, 写入文本内容.readImage()读取剪切板中的图片, 返回的是NativeImage对象.writeImage(img)往剪切板中写入图片, 需要传入NativeImage对象.clear()清空剪切板中的内容
screen 对象
返回屏幕的基础信息, 如分辨率等。
.getAllDisplays()返回所有的屏幕(支持多显示器)的信息.getPrimaryDisplay()只返回主显示器的信息
globalShortcut 对象
全局快捷键的设置对象。(需要安装依赖gir1.2-keybinder-3.0)
.enabled获取是否支持设置系统快捷键。.register(keyMap, callback)注册快捷键.unregister(keyMap)注销快捷键.unregisterAll(keyMaps)批量注销快捷键
tray 托盘对象
可用于创建和管理托盘图标。
.create()创建托盘图标.remove()移除托盘图标.set_icon(name)设置托盘图标, 只传名称即可, 自动读取系统主题中的图标.set_attention_icon(name)设置通知托盘图标, 一般可用于有重要消息时, 显示的图标样式.set_title(name)设置鼠标划过图标时显示的文本, 即将废弃。.set_status(stat = 0), 0为隐藏, 1为显示, 2为显示attention状态
opener 父窗口对象 【0.5.0新增】
指的是应用的父窗口对象(
Gtk.Window)。
.postMessage(data)向父窗口发送数据父窗口, 可以通过
window.addEventListener('message', callback)接收子窗口发送的数据, 父窗口可使用ev.source.postMessage()向该子窗口发送消息【0.6.0新增】。 没有父窗口时, 则会指向当前窗口。
// 父窗口
window.addEventListener('message', ev => {
console.log(ev.uuid) // 若有uuid, 则说明这条消息是从子窗口发来的。 否则为 父窗口或自身发来的。
// 可以向消息来源的窗口发送回执消息 (要注意, 若没有 ev.uuid 时, 谨慎调用, 否则会一直死循环的)
// 这是 0.6.0新增的支持功能
ev.source.postMessage('已收到')
})
// 子窗口
native.opener.postMessage('我是来自子窗口的消息')
children 子窗口对象 【0.6.0新增】
.postMessage(data, uuid = null)向子窗口发送数据, uuid为子窗口的uuid, 可不传向子窗口发送消息, 若不传子窗口的uuid时, 则会向所有的子窗口同时发送消息。若没有子窗口时, 会发送到当前窗口。
window 窗口对象
指的是应用的窗口对象(Gtk.Window)。
-
uuid窗口唯一标识。 只是给你看的, 没啥用。【0.6.0新增】 -
.create(options = {})创建新窗口, 对比window.open(), 这里创建的窗口, 提供更多高级的配置项。【0.5.0新增】 options 结构如下
- url
<string>, 这个不多说了 - wmclass
<string>, 窗口的类名, 默认为WebEngine, 这个不会在功能上有影响, 仅会在系统通知等地方需会显示应用类名的地方有区别 - title
<string>, 窗口标题, 默认为WebEngine, 当frame为false时, 这个标题也不会显示, 但是在rofi等应用上, 能看到 - frame
<boolean>, 是否显示窗口边框(包括标题等), 为false, 将创建一个无边框窗口 - width
<int>, 窗口宽度, 像素为单位, 不用写单位 - height
<int>, 窗口的高度 - x
<int>, 窗口打开时, 位于显示器的横坐标(以左上角为原点) - y
<int>, 窗口打开时, 位于显示器的纵坐标 - always_on_top
<boolean>,打开的窗口, 保持一直在最上层。 - resizable
<boolean>, 窗口是否允许调整大小(这个在不同的桌面环境下, 不一定生效) - icon
<string>, 【0.6.0新增】图标名称,Linux专用, 只传图标名即可, 会自动读取主题中的图标(如果存在的话) - icon_path
<string>, 【0.6.0新增】图标文件的绝对路径, 1:1大小, png格式。 - uuid
<string>, 【0.6.0新增】新建窗口的uuid, 不可重复, 否则发送消息只有第1个能收到, 不传则随机生成值。
- url
-
.close()当前当前窗口, 效果等同于JS的原生方法window.close()。 这里仅用于以防万一window.close()无响应时, 可改用本方法关闭。【0.5.0新增】
-
.isVisible()判断当前应用窗口是否显示在桌面中 -
.toggleVisible()切换显示/隐藏 -
.hide()隐藏窗口(最小化到托盘) -
.show()显示窗口 -
.fullscreen()全屏 -
.unfullscreen()取消全屏 -
.maximize()最大化窗口 -
.unmaximize()取消最大化窗口 -
.setTitle(title)修改窗口标题 (WM环境, 如没有标题栏时, 窗口不会有任何变化) -
.resize(width, height)修改窗口大小, 单位像素 -
.move(x, y)移动窗口, 以左上角为坐标原点 -
.setOpacity()设置窗口透明度(废弃中), 这个设置, 不仅背景透明, 整个窗口都会透明。 -
.alwayOnTop()设置窗口永远在最上面, 多个窗口都设置在最上面的话, 按设置先后顺序, 后面设置的, 更高。 -
.alwayOnBotttom()设置窗口永远在下面
notify 系统通知
正常webkit已经给了通知权限, 可使用js的notifycation对象创建系统通知。
如需要更符合原生风格的通知样式, 可以调用这个方法创建通知。
.notify({ title, summary, icon, progress = 0, urgency = 0, callback })支持设置图标、进度条等
md5
对文本计算md5值
proxy 对象 (0.4.0起支持)
可设置webview的网络的代理, 默认走系统代理设置。
.disable()禁用代理设置.system()使用系统代理设置(不同的桌面环境, 不一定有效果, gnome系、kde桌面是可以的).custom(url, ignoreHosts)自定义代理设置,url为完整的代理地址(包含协议, 服务地址, 端口), 支持http, https, socks53种代理协议;ignoreHosts为可选参数, 用于设置代理跳过某些域名。
handler (0.4.0起支持)
该对象是一切API的基础, 上面所有的方法, 最后都调用这个方法来实现与python的通信, 如果上面的API不满足你的需求, 可以自行调用这个方法(前提是python后端有接收额外的信号)。
python后端可使用create_bridge(), 创建自定义桥接信号处理, 详情见 自定义桥接