跳转到主内容

深度链接 (Deep Links)

概览

本指南将会指导你配置 Electron 应用为 特定协议 的默认处理器。

通过此教程,您会掌握如何设置您的应用以拦截并处理任意特定协议的URL的点击事件。 在本指南中,我们假定这个协议名为“electron-fiddle://”。

示例

主进程(main.js)

首先,我们需要从electron导入所需的模块。 这些模块有助于控制应用的生命周期,或创建原生的浏览器窗口。

const { app, BrowserWindow, shell } = require('electron')
const path = require('path')

其次,我们将应用注册为“electron-fiddle://”协议的处理器。

if (process.defaultApp) {
if (process.argv.length >= 2) {
app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])
}
} else {
app.setAsDefaultProtocolClient('electron-fiddle')
}

现在我们定义负责创建浏览器窗口的函数,并加载应用的 index.html 文件。

let mainWindow

const createWindow = () => {
// 创建浏览器窗口
mainWindow = new BrowserWindow({
width: 800,
height: 600,
webPreferences: {
preload: path.join(__dirname, 'preload.js')
}
})

mainWindow.loadFile('index.html')
}

紧接着,我们将创建 BrowserWindow 并在应用中定义如何处理此外部协议被点击的事件。

这段代码在 Windows 和 Linux 上会与 MacOS 有所不同。 这是因为这两个平台会触发 second-instance 事件,而不是 open-url 事件,而且 Windows 需要额外的代码才能在同一个 Electron 实例中打开协议链接的内容。 请点击 此处 了解更多

Windows 和 Linux 的代码示例:

const gotTheLock = app.requestSingleInstanceLock()

if (!gotTheLock) {
app.quit()
} else {
app.on('second-instance', (event, commandLine, workingDirectory) => {
// 用户正在尝试运行第二个实例,我们需要让焦点指向我们的窗口
if (mainWindow) {
if (mainWindow.isMinimized()) mainWindow.restore()
mainWindow.focus()
}
// 命令行是一个字符串数组,其中最后一个元素是深度链接的URL。
dialog.showErrorBox('Welcome Back', `You arrived from: ${commandLine.pop()}`)
})

// 创建主窗口,加载应用程序的其他部分,等等...
app.whenReady().then(() => {
createWindow()
})
}

MacOS 代码示例:

// Electron 在完成初始化,并准备创建浏览器窗口时,
// 会调用这个方法。
// 部分 API 在 ready 事件触发后才能使用。
app.whenReady().then(() => {
createWindow()
})

// 处理协议 在本例中,我们选择显示一个错误提示对话框。
app.on('open-url', (event, url) => {
dialog.showErrorBox('欢迎回来', `导向自: ${url}`)
})

最后,我们还需要处理应用的关闭事件。

// 在除 MacOS 的其他平台上,当所有窗口关闭后,退出当前应用。 在 MacOS 上,
// 应用及其菜单栏通常会保持活跃状态,
// 直到用户明确按下 Cmd + Q 退出应用
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') app.quit()
})

重要提醒:

打包

在 macOS 和 Linux 上,此功能仅在应用打包后才有效。 在命令行启动的开发版中无效。 当您打包应用程序时,你需要确保应用程序的 macOS Info.plist 和 Linux .desktop 文件已更新以包含新的协议处理程序。 一些绑定和分发应用程序的 Electron 工具会自动为你处理

Electron Forge

如果您使用 Electron Forge,请调整 macOS 支持的 packagerConfig ,以及适当调整 Linux 制造商的 Linux 支持配置,在 Forge 配置 (请注意以下示例仅显示添加配置时所需更改的最低值)

{
"config": {
"forge": {
"packagerConfig": {
"protocols": [
{
"name": "Electron Fiddle",
"schemes": ["electron-fiddle"]
}
]
},
"makers": [
{
"name": "@electron-forge/maker-deb",
"config": {
"mimeType": ["x-scheme-handler/electron-fiddle"]
}
}
]
}
}
}

Electron Packager

对于 macOS 支持:

如果您正在使用 Electron Packager 的 API,添加对协议处理程序的支持类似于 Electron Forge 的处理方式, 其他 protocols 是传递到 packager 函数的 Packager 选项的一部分。

const packager = require('electron-packager')

packager({
// ...other options...
protocols: [
{
name: 'Electron Fiddle',
schemes: ['electron-fiddle']
}
]

}).then(paths => console.log(`SUCCESS: Created ${paths.join(', ')}`))
.catch(err => console.error(`ERROR: ${err.message}`))

如果您使用 Electron Packager 的 CLI,请使用 --protocol--protocol-name 标志。 例如:

npx electron-packager . --protocol=electron-fiddle --protocol-name="Electron Fiddle"

结论

启动 Electron 应用后,在浏览器内键入包含该自定义协议的 URL,如 "electron-fiddle://open" ,观察应用是否正确响应并显示一个错误提示对话框。

// Modules to control application life and create native browser window
const { app, BrowserWindow, ipcMain, shell, dialog } = require('electron')
const path = require('path')

let mainWindow

if (process.defaultApp) {
if (process.argv.length >= 2) {
app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])
}
} else {
app.setAsDefaultProtocolClient('electron-fiddle')
}

const gotTheLock = app.requestSingleInstanceLock()

if (!gotTheLock) {
app.quit()
} else {
app.on('second-instance', (event, commandLine, workingDirectory) => {
// Someone tried to run a second instance, we should focus our window.
if (mainWindow) {
if (mainWindow.isMinimized()) mainWindow.restore()
mainWindow.focus()
}

dialog.showErrorBox('Welcome Back', `You arrived from: ${commandLine.pop().slice(0, -1)}`)
})

// Create mainWindow, load the rest of the app, etc...
app.whenReady().then(() => {
createWindow()
})

app.on('open-url', (event, url) => {
dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)
})
}

function createWindow () {
// Create the browser window.
mainWindow = new BrowserWindow({
width: 800,
height: 600,
webPreferences: {
preload: path.join(__dirname, 'preload.js')
}
})

mainWindow.loadFile('index.html')
}

// Quit when all windows are closed, except on macOS. There, it's common
// for applications and their menu bar to stay active until the user quits
// explicitly with Cmd + Q.
app.on('window-all-closed', function () {
if (process.platform !== 'darwin') app.quit()
})

// Handle window controls via IPC
ipcMain.on('shell:open', () => {
const pageDirectory = __dirname.replace('app.asar', 'app.asar.unpacked')
const pagePath = path.join('file://', pageDirectory, 'index.html')
shell.openExternal(pagePath)
})