Skip to main content

深层链接

¥Deep Links

概述​

¥Overview

本指南将引导你完成将 Electron 应用设置为特定 protocol 的默认处理程序的过程。

¥This guide will take you through the process of setting your Electron app as the default handler for a specific protocol.

在本教程结束时，我们将设置我们的应用来拦截和处理任何以特定协议开头的点击 URL。在本指南中，我们将使用的协议是“electron-fiddle://”。

¥By the end of this tutorial, we will have set our app to intercept and handle any clicked URLs that start with a specific protocol. In this guide, the protocol we will use will be "electron-fiddle://".

示例​

¥Examples

主进程（main.js）​

¥Main Process (main.js)

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

¥First, we will import the required modules from electron. These modules help control our application lifecycle and create a native browser window.

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

接下来，我们将继续注册我们的应用来处理所有“electron-fiddle://”协议。

¥Next, we will proceed to register our application to handle all "electron-fiddle://" protocols.

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 文件的函数。

¥We will now define the function in charge of creating our browser window and load our application's index.html file.

let mainWindow

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

  mainWindow.loadFile('index.html')
}

在下一步中，我们将创建 BrowserWindow 并告诉我们的应用如何处理单击外部协议的事件。

¥In this next step, we will create our BrowserWindow and tell our application how to handle an event in which an external protocol is clicked.

与 MacOS 相比，此代码在 Windows 和 Linux 中会有所不同。这是因为两个平台都发出 second-instance 事件而不是 open-url 事件，并且 Windows 需要额外的代码才能打开同一 Electron 实例中的协议链接的内容。了解有关 此处 的更多信息。

¥This code will be different in Windows and Linux compared to MacOS. This is due to both platforms emitting the second-instance event rather than the open-url event and Windows requiring additional code in order to open the contents of the protocol link within the same Electron instance. Read more about this here.

Windows 和 Linux 代码：​

¥Windows and Linux code:

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()
    }
    // the commandLine is array of strings in which last element is deep link url
    dialog.showErrorBox('Welcome Back', `You arrived from: ${commandLine.pop()}`)
  })

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

苹果系统代码：​

¥MacOS code:

// This method will be called when Electron has finished
// initialization and is ready to create browser windows.
// Some APIs can only be used after this event occurs.
app.whenReady().then(() => {
  createWindow()
})

// Handle the protocol. In this case, we choose to show an Error Box.
app.on('open-url', (event, url) => {
  dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)
})

最后，我们将添加一些额外的代码来处理有人关闭我们的应用的情况。

¥Finally, we will add some additional code to handle when someone closes our application.

// 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', () => {
  if (process.platform !== 'darwin') app.quit()
})

重要注意​

¥Important notes

封装​

¥Packaging

在 macOS 和 Linux 上，此功能仅在你的应用打包时才起作用。当你从命令行在开发中启动它时，它将不起作用。打包应用时，你需要确保应用的 macOS Info.plist 和 Linux .desktop 文件已更新以包含新的协议处理程序。一些用于打包和分发应用的 Electron 工具会为你处理此问题。

¥On macOS and Linux, this feature will only work when your app is packaged. It will not work when you're launching it in development from the command-line. When you package your app you'll need to make sure the macOS Info.plist and the Linux .desktop files for the app are updated to include the new protocol handler. Some of the Electron tools for bundling and distributing apps handle this for you.

Electron Forge​

如果你使用 Electron Forge，请在 锻造配置 中调整 packagerConfig 以支持 macOS，并调整适当的 Linux 制造商的配置以支持 Linux（请注意，以下示例仅显示添加配置更改所需的最低限度）：

¥If you're using Electron Forge, adjust packagerConfig for macOS support, and the configuration for the appropriate Linux makers for Linux support, in your Forge configuration (please note the following example only shows the bare minimum needed to add the configuration changes):

{
  "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 支持：

¥For macOS support:

如果你使用 Electron Packager 的 API，添加对协议处理程序的支持与 Electron Forge 的处理方式类似，只不过 protocols 是传递给 packager 函数的 Packager 选项的一部分。

¥If you're using Electron Packager's API, adding support for protocol handlers is similar to how Electron Forge is handled, except protocols is part of the Packager options passed to the packager function.

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 标志。例如：

¥If you're using Electron Packager's CLI, use the --protocol and --protocol-name flags. For example:

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

结论​

¥Conclusion

启动 Electron 应用后，你可以在浏览器中输入包含自定义协议的 URL，例如 "electron-fiddle://open"，并观察应用将响应并显示错误对话框。

¥After you start your Electron app, you can enter in a URL in your browser that contains the custom protocol, for example "electron-fiddle://open" and observe that the application will respond and show an error dialog box.

docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app (33.2.0)Open in Fiddle
// Modules to control application life and create native browser window
const { app, BrowserWindow, ipcMain, shell, dialog } = require('electron/main')
const path = require('node: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)
})