148 lines
3.3 KiB
Markdown
148 lines
3.3 KiB
Markdown
# Screen Capture Tool
|
|
|
|
A standalone utility for capturing screenshots from user's screen using the native Browser Screen Capture API.
|
|
|
|
## Features
|
|
|
|
- 📸 Capture screenshots from user-selected screen/window
|
|
- 🎯 No external dependencies
|
|
- ⚡ Returns canvas for flexible post-processing
|
|
- 🛡️ Graceful error handling
|
|
- ♿ Respects user permissions
|
|
|
|
## Installation
|
|
|
|
Copy the `screen-capture` folder to your project:
|
|
|
|
```
|
|
your-project/
|
|
├── tools/
|
|
│ └── screen-capture/
|
|
│ ├── index.js
|
|
│ └── README.md
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Screenshot Capture
|
|
|
|
```javascript
|
|
import { captureScreenshot } from './tools/screen-capture/index.js';
|
|
|
|
const canvas = await captureScreenshot();
|
|
if (canvas) {
|
|
// Canvas is ready for use
|
|
// Convert to File, display, or manipulate further
|
|
}
|
|
```
|
|
|
|
### Convert to File
|
|
|
|
```javascript
|
|
import { captureScreenshot, canvasToFile } from './tools/screen-capture/index.js';
|
|
|
|
const canvas = await captureScreenshot();
|
|
if (canvas) {
|
|
const file = await canvasToFile(canvas, 'my-screenshot.png');
|
|
// Use file with FormData, attachments, etc.
|
|
}
|
|
```
|
|
|
|
### One-liner with Blob
|
|
|
|
```javascript
|
|
const canvas = await captureScreenshot();
|
|
canvas?.toBlob((blob) => {
|
|
const file = new File([blob], `screenshot-${Date.now()}.png`, { type: 'image/png' });
|
|
// Use file...
|
|
});
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### `captureScreenshot()`
|
|
|
|
**Returns:** `Promise<Canvas | null>`
|
|
|
|
Opens native browser dialog for user to select screen/window to capture. Returns a canvas element containing the screenshot, or null if user cancels or error occurs.
|
|
|
|
**Example:**
|
|
```javascript
|
|
const canvas = await captureScreenshot();
|
|
```
|
|
|
|
### `canvasToFile(canvas, filename?)`
|
|
|
|
**Parameters:**
|
|
- `canvas` (Canvas): Canvas element to convert
|
|
- `filename` (string, optional): Custom filename. Defaults to `screenshot-{timestamp}.png`
|
|
|
|
**Returns:** `Promise<File>`
|
|
|
|
Converts canvas to PNG File object for easy handling in file uploads or attachments.
|
|
|
|
**Example:**
|
|
```javascript
|
|
const file = await canvasToFile(canvas, 'custom-name.png');
|
|
```
|
|
|
|
## Browser Support
|
|
|
|
Requires browsers supporting the Screen Capture API:
|
|
- Chrome 72+
|
|
- Edge 79+
|
|
- Firefox 66+
|
|
- Safari 13+
|
|
|
|
Note: User must grant permission for each capture request.
|
|
|
|
## Error Handling
|
|
|
|
The tool gracefully handles:
|
|
- User cancellation of the capture dialog
|
|
- Browser permission denial
|
|
- Browser incompatibility
|
|
- Missing canvas/video support
|
|
|
|
All errors are logged to console and return null.
|
|
|
|
## Examples
|
|
|
|
### React Component
|
|
|
|
```jsx
|
|
import { captureScreenshot, canvasToFile } from './tools/screen-capture/index.js';
|
|
|
|
export function ScreenshotButton() {
|
|
const handleCapture = async () => {
|
|
const canvas = await captureScreenshot();
|
|
if (canvas) {
|
|
const file = await canvasToFile(canvas);
|
|
console.log('Screenshot captured:', file.name);
|
|
}
|
|
};
|
|
|
|
return <button onClick={handleCapture}>Take Screenshot</button>;
|
|
}
|
|
```
|
|
|
|
### With Form Submission
|
|
|
|
```javascript
|
|
import { captureScreenshot, canvasToFile } from './tools/screen-capture/index.js';
|
|
|
|
const canvas = await captureScreenshot();
|
|
if (canvas) {
|
|
const file = await canvasToFile(canvas);
|
|
|
|
const formData = new FormData();
|
|
formData.append('screenshot', file);
|
|
|
|
await fetch('/api/upload', { method: 'POST', body: formData });
|
|
}
|
|
```
|
|
|
|
## License
|
|
|
|
MIT - Use freely in your projects
|