mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

docs: navigation history example (#42980)

Browse source 
* docs: add fiddle example

* docs: add tutorial guide

* refactor: PR review comments

* refactor: add eof

* refactor: render navigation history and make demo better.

* refactor: fix broken links

* refactor: add eof newline

* docs: review feedback :)

* chore: lint add space around list

* doc: transformURL
This commit is contained in:
Alice Zhao 2024-09-23 10:18:26 -07:00 • committed by GitHub
parent 517d04de16
commit ceea1225a2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 321 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
docs/README.md
View file

@ -37,6 +37,7 @@ an issue:
* [Offline/Online Detection](tutorial/online-offline-events.md) * [Offline/Online Detection](tutorial/online-offline-events.md)
* [Represented File for macOS BrowserWindows](tutorial/represented-file.md) * [Represented File for macOS BrowserWindows](tutorial/represented-file.md)
* [Native File Drag & Drop](tutorial/native-file-drag-drop.md) * [Native File Drag & Drop](tutorial/native-file-drag-drop.md)
* [Navigation History](tutorial/navigation-history.md)
* [Offscreen Rendering](tutorial/offscreen-rendering.md) * [Offscreen Rendering](tutorial/offscreen-rendering.md)
* [Dark Mode](tutorial/dark-mode.md) * [Dark Mode](tutorial/dark-mode.md)
* [Web embeds in Electron](tutorial/web-embeds.md) * [Web embeds in Electron](tutorial/web-embeds.md)

32
docs/fiddles/features/navigation-history/index.html Normal file
View file

@ -0,0 +1,32 @@
<!DOCTYPE html>
<html>
<head>
<title>Enhanced Browser with Navigation History</title>
<link href="styles.css" rel="stylesheet" />
</head>
<body>
<div id="controls">
<button id="backBtn" title="Go back">Back</button>
<button id="forwardBtn" title="Go forward">Forward</button>
<button id="backHistoryBtn" title="Show back history">Back History</button>
<button id="forwardHistoryBtn" title="Show forward history">Forward History</button>
<input id="urlInput" type="text" placeholder="Enter URL">
<button id="goBtn" title="Navigate to URL">Go</button>
</div>
<div id="historyPanel" class="history-panel"></div>
<div id="description">
<h2>Navigation History Demo</h2>
<p>This demo showcases Electron's NavigationHistory API functionality.</p>
<p><strong>Back/Forward:</strong> Navigate through your browsing history.</p>
<p><strong>Back History/Forward History:</strong> View and select from your browsing history.</p>
<p><strong>URL Bar:</strong> Enter a URL and click 'Go' or press Enter to navigate.</p>
</div>
<script src="renderer.js"></script>
</body>
</html>

58
docs/fiddles/features/navigation-history/main.js Normal file
View file

@ -0,0 +1,58 @@
const { app, BrowserWindow, BrowserView, ipcMain } = require('electron')
const path = require('path')
function createWindow () {
const mainWindow = new BrowserWindow({
width: 1000,
height: 800,
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
nodeIntegration: false,
contextIsolation: true
}
})
mainWindow.loadFile('index.html')
const view = new BrowserView()
mainWindow.setBrowserView(view)
view.setBounds({ x: 0, y: 100, width: 1000, height: 800 })
view.setAutoResize({ width: true, height: true })
const navigationHistory = view.webContents.navigationHistory
ipcMain.handle('nav:back', () =>
navigationHistory.goBack()
)
ipcMain.handle('nav:forward', () => {
navigationHistory.goForward()
})
ipcMain.handle('nav:canGoBack', () => navigationHistory.canGoBack())
ipcMain.handle('nav:canGoForward', () => navigationHistory.canGoForward())
ipcMain.handle('nav:loadURL', (_, url) =>
view.webContents.loadURL(url)
)
ipcMain.handle('nav:getCurrentURL', () => view.webContents.getURL())
ipcMain.handle('nav:getHistory', () => {
return navigationHistory.getAllEntries()
})
view.webContents.on('did-navigate', () => {
mainWindow.webContents.send('nav:updated')
})
view.webContents.on('did-navigate-in-page', () => {
mainWindow.webContents.send('nav:updated')
})
}
app.whenReady().then(createWindow)
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') app.quit()
})
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) createWindow()
})

12
docs/fiddles/features/navigation-history/preload.js Normal file
View file

@ -0,0 +1,12 @@
const { contextBridge, ipcRenderer } = require('electron')
contextBridge.exposeInMainWorld('electronAPI', {
goBack: () => ipcRenderer.invoke('nav:back'),
goForward: () => ipcRenderer.invoke('nav:forward'),
canGoBack: () => ipcRenderer.invoke('nav:canGoBack'),
canGoForward: () => ipcRenderer.invoke('nav:canGoForward'),
loadURL: (url) => ipcRenderer.invoke('nav:loadURL', url),
getCurrentURL: () => ipcRenderer.invoke('nav:getCurrentURL'),
getHistory: () => ipcRenderer.invoke('nav:getHistory'),
onNavigationUpdate: (callback) => ipcRenderer.on('nav:updated', callback)
})

84
docs/fiddles/features/navigation-history/renderer.js Normal file
View file

@ -0,0 +1,84 @@
const backBtn = document.getElementById('backBtn')
const forwardBtn = document.getElementById('forwardBtn')
const backHistoryBtn = document.getElementById('backHistoryBtn')
const forwardHistoryBtn = document.getElementById('forwardHistoryBtn')
const urlInput = document.getElementById('urlInput')
const goBtn = document.getElementById('goBtn')
const historyPanel = document.getElementById('historyPanel')
async function updateButtons () {
const canGoBack = await window.electronAPI.canGoBack()
const canGoForward = await window.electronAPI.canGoForward()
backBtn.disabled = !canGoBack
backHistoryBtn.disabled = !canGoBack
forwardBtn.disabled = !canGoForward
forwardHistoryBtn.disabled = !canGoForward
}
async function updateURL () {
urlInput.value = await window.electronAPI.getCurrentURL()
}
function transformURL (url) {
if (!url.startsWith('http://') && !url.startsWith('https://')) {
const updatedUrl = 'https://' + url
return updatedUrl
}
return url
}
async function navigate (url) {
const urlInput = transformURL(url)
await window.electronAPI.loadURL(urlInput)
}
async function showHistory (forward = false) {
const history = await window.electronAPI.getHistory()
const currentIndex = history.findIndex(entry => entry.url === transformURL(urlInput.value))
if (!currentIndex) {
return
}
const relevantHistory = forward
? history.slice(currentIndex + 1)
: history.slice(0, currentIndex).reverse()
historyPanel.innerHTML = ''
relevantHistory.forEach(entry => {
const div = document.createElement('div')
div.textContent = `Title: ${entry.title}, URL: ${entry.url}`
div.onclick = () => navigate(entry.url)
historyPanel.appendChild(div)
})
historyPanel.style.display = 'block'
}
backBtn.addEventListener('click', () => window.electronAPI.goBack())
forwardBtn.addEventListener('click', () => window.electronAPI.goForward())
backHistoryBtn.addEventListener('click', () => showHistory(false))
forwardHistoryBtn.addEventListener('click', () => showHistory(true))
goBtn.addEventListener('click', () => navigate(urlInput.value))
urlInput.addEventListener('keypress', (e) => {
if (e.key === 'Enter') {
navigate(urlInput.value)
}
})
document.addEventListener('click', (e) => {
if (e.target !== historyPanel && !historyPanel.contains(e.target) &&
e.target !== backHistoryBtn && e.target !== forwardHistoryBtn) {
historyPanel.style.display = 'none'
}
})
window.electronAPI.onNavigationUpdate(() => {
updateButtons()
updateURL()
})
updateButtons()

58
docs/fiddles/features/navigation-history/style.css Normal file
View file

@ -0,0 +1,58 @@
body {
margin: 0;
font-family: Arial, sans-serif;
background-color: #f0f0f0;
}
#controls {
display: flex;
align-items: center;
padding: 10px;
background-color: #ffffff;
border-bottom: 1px solid #ccc;
}
button {
margin-right: 10px;
padding: 8px 12px;
font-size: 14px;
background-color: #4CAF50;
color: white;
border: none;
cursor: pointer;
transition: background-color 0.3s;
}
button:hover {
background-color: #45a049;
}
button:disabled {
background-color: #cccccc;
cursor: not-allowed;
}
#urlInput {
flex-grow: 1;
margin: 0 10px;
padding: 8px;
font-size: 14px;
}
#historyPanel {
display: none;
position: absolute;
top: 60px;
left: 10px;
background: white;
border: 1px solid #ccc;
padding: 10px;
max-height: 300px;
overflow-y: auto;
z-index: 1000;
}
#historyPanel div {
cursor: pointer;
padding: 5px;
}
#description {
background-color: #f0f0f0;
padding: 10px;
margin-top: 150px;
}

76
docs/tutorial/navigation-history.md Normal file
View file

@ -0,0 +1,76 @@
---
title: "Navigation History"
description: "The NavigationHistory API allows you to manage and interact with the browsing history of your Electron application."
slug: navigation-history
hide_title: false
---
# Navigation History
## Overview
The [NavigationHistory](../api/navigation-history.md) class allows you to manage and interact with the browsing history of your Electron application. This powerful feature enables you to create intuitive navigation experiences for your users.
## Accessing NavigationHistory
Navigation history is stored per [`WebContents`](../api/web-contents.md) instance. To access a specific instance of the NavigationHistory class, use the WebContents class's [`contents.navigationHistory` instance property](https://www.electronjs.org/docs/latest/api/web-contents#contentsnavigationhistory-readonly).
```js
const { BrowserWindow } = require('electron')
const mainWindow = new BrowserWindow()
const { navigationHistory } = mainWindow.webContents
```
## Navigating through history
Easily implement back and forward navigation:
```js @ts-type={navigationHistory:Electron.NavigationHistory}
// Go back
if (navigationHistory.canGoBack()) {
navigationHistory.goBack()
}
// Go forward
if (navigationHistory.canGoForward()) {
navigationHistory.goForward()
}
```
## Accessing history entries
Retrieve and display the user's browsing history:
```js @ts-type={navigationHistory:Electron.NavigationHistory}
const entries = navigationHistory.getAllEntries()
entries.forEach((entry) => {
console.log(`${entry.title}: ${entry.url}`)
})
```
Each navigation entry corresponds to a specific page. The indexing system follows a sequential order:
- Index 0: Represents the earliest visited page.
- Index N: Represents the most recent page visited.
## Navigating to specific entries
Allow users to jump to any point in their browsing history:
```js @ts-type={navigationHistory:Electron.NavigationHistory}
// Navigate to the 5th entry in the history, if the index is valid
navigationHistory.goToIndex(4)
// Navigate to the 2nd entry forward from the current position
if (navigationHistory.canGoToOffset(2)) {
navigationHistory.goToOffset(2)
}
```
Here's a full example that you can open with Electron Fiddle:
```fiddle docs/fiddles/features/navigation-history
```