171 lines
4.2 KiB
Markdown
171 lines
4.2 KiB
Markdown
# Background Page Navigation Examples
|
|
|
|
This document demonstrates how to use the new `backgroundPage` parameter to open URLs in background pages using minimized windows.
|
|
|
|
## Overview
|
|
|
|
The `backgroundPage` parameter allows you to open URLs without interrupting the user's current workflow. When set to `true`, it creates a minimized window that runs in the background instead of opening a new tab or focused window.
|
|
|
|
## Usage Examples
|
|
|
|
### 1. Basic Background Page Navigation
|
|
|
|
```json
|
|
{
|
|
"name": "chrome_navigate",
|
|
"arguments": {
|
|
"url": "https://example.com",
|
|
"backgroundPage": true
|
|
}
|
|
}
|
|
```
|
|
|
|
This will:
|
|
|
|
1. Create a new window with the specified URL
|
|
2. Immediately minimize the window to keep it in the background
|
|
3. Return window and tab information for reference
|
|
|
|
### 2. Natural Language Background Navigation
|
|
|
|
```json
|
|
{
|
|
"name": "chrome_navigate_natural",
|
|
"arguments": {
|
|
"query": "open google",
|
|
"backgroundPage": true
|
|
}
|
|
}
|
|
```
|
|
|
|
This will:
|
|
|
|
1. Process the natural language query ("open google" → "https://www.google.com")
|
|
2. Create a minimized window with the processed URL
|
|
3. Keep the window running in the background
|
|
|
|
### 3. Background Page with Custom Dimensions
|
|
|
|
```json
|
|
{
|
|
"name": "chrome_navigate",
|
|
"arguments": {
|
|
"url": "https://example.com",
|
|
"backgroundPage": true,
|
|
"width": 1920,
|
|
"height": 1080
|
|
}
|
|
}
|
|
```
|
|
|
|
The window will be created with the specified dimensions before being minimized.
|
|
|
|
### 4. Parameter Precedence
|
|
|
|
When both `newWindow` and `backgroundPage` are specified:
|
|
|
|
```json
|
|
{
|
|
"name": "chrome_navigate",
|
|
"arguments": {
|
|
"url": "https://example.com",
|
|
"newWindow": true,
|
|
"backgroundPage": true
|
|
}
|
|
}
|
|
```
|
|
|
|
The `backgroundPage` parameter takes precedence, and the URL will be opened in a minimized window.
|
|
|
|
## Use Cases
|
|
|
|
### 1. Background Data Loading
|
|
|
|
Open data-heavy pages in the background while continuing to work:
|
|
|
|
```json
|
|
{
|
|
"name": "chrome_navigate",
|
|
"arguments": {
|
|
"url": "https://dashboard.example.com/reports",
|
|
"backgroundPage": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. Preloading Content
|
|
|
|
Preload content that will be needed later:
|
|
|
|
```json
|
|
{
|
|
"name": "chrome_navigate_natural",
|
|
"arguments": {
|
|
"query": "youtube trending",
|
|
"backgroundPage": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Background Monitoring
|
|
|
|
Open monitoring or status pages in the background:
|
|
|
|
```json
|
|
{
|
|
"name": "chrome_navigate",
|
|
"arguments": {
|
|
"url": "https://status.example.com",
|
|
"backgroundPage": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## Response Format
|
|
|
|
When using `backgroundPage: true`, the response will include:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Opened URL in background page (minimized window)",
|
|
"windowId": 123,
|
|
"tabs": [
|
|
{
|
|
"tabId": 456,
|
|
"url": "https://example.com"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Implementation Details
|
|
|
|
The background page functionality:
|
|
|
|
1. Creates a new window using `chrome.windows.create()` with full dimensions
|
|
2. Sets `focused: false` to avoid stealing focus
|
|
3. Sets `state: 'normal'` to ensure proper initial window state
|
|
4. Waits 1 second for page load and proper dimension establishment
|
|
5. Calls `chrome.windows.update()` with `state: 'minimized'` to move to background
|
|
6. Returns window and tab information for future reference
|
|
|
|
This approach ensures web automation tools can properly interact with the page even when minimized, as the window maintains its proper dimensions and DOM accessibility.
|
|
|
|
## Comparison with Regular Navigation
|
|
|
|
| Parameter | Behavior |
|
|
| --------------------------------------- | ------------------------------------------------------------------------- |
|
|
| `backgroundPage: false` (default) | Opens in new tab or focused window |
|
|
| `backgroundPage: true` | Opens full-size window, then minimizes (automation-compatible background) |
|
|
| `newWindow: true` | Opens in new focused window |
|
|
| `newWindow: true, backgroundPage: true` | Opens full-size window, then minimizes (backgroundPage wins) |
|
|
|
|
## Browser Compatibility
|
|
|
|
This feature requires:
|
|
|
|
- Chrome extension with `windows` permission
|
|
- Chrome browser (Chromium-based browsers)
|
|
- The `chrome.windows.WindowState.MINIMIZED` API support
|