添加：文本选择模式下，点击恢复功能

2025-12-10 18:36:51 +08:00
parent 760f3ec0d0
commit 86c47ba772
7 changed files with 255 additions and 877 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,172 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+BlurText is a Chrome/Edge browser extension (Manifest V3) for protecting privacy during screen sharing and recording by blurring sensitive text on web pages. The extension is written in vanilla JavaScript with no framework dependencies.
+
+**Key Characteristics:**
+- Chinese language UI (all text, comments, and documentation in Chinese)
+- Manifest V3 standard with Chrome Extension APIs
+- CSS `filter: blur()` for visual obfuscation
+- Chrome Storage API for local configuration persistence
+
+## Architecture
+
+### Core Components
+
+**Extension Structure:**
+1. **[manifest.json](manifest.json)** - Extension configuration (Manifest V3)
+2. **[popup.html](popup.html)** + **[popup.js](popup.js)** - Browser action UI and control logic
+3. **[content.js](content.js)** - Content script injected into all web pages (core functionality)
+4. **[content.css](content.css)** - Injected styles for blur effects and UI overlays
+
+### Communication Flow
+
+```
+User clicks extension icon
+  → popup.js loads and displays UI
+  → User toggles blur mode or changes settings
+  → popup.js sends chrome.tabs.sendMessage() to content.js
+  → content.js applies blur mode or updates settings
+  → content.js stores state in blurredElements Set
+```
+
+**Message Types (popup.js → content.js):**
+- `toggleBlurMode` - Enable/disable blur mode with mode and intensity
+- `clearAll` - Remove all blur effects
+- `updateIntensity` - Change blur strength on existing blurred elements
+- `switchMode` - Change between element and selection modes
+
+**Message Types (content.js → popup.js):**
+- `blurModeDisabled` - Notify when user presses ESC to exit
+
+### Two Blur Modes
+
+**1. Element Mode (`blurMode = 'element'`)**
+- Default mode with crosshair cursor
+- Click any DOM element to toggle blur
+- Hover shows dashed outline highlight
+- Stores references to blurred elements in `blurredElements` Set
+- Does NOT modify DOM structure (only adds/removes CSS classes)
+
+**2. Selection Mode (`blurMode = 'selection'`)**
+- Select text with mouse drag
+- Floating button appears below selection
+- Wraps selected text in `<span class="blurtext-blurred blurtext-selection-wrapped">`
+- Uses `Range.surroundContents()` - can fail on complex HTML structures
+- Error handling shows user-friendly message on failure
+
+### State Management
+
+**Global State (content.js):**
+```javascript
+let isBlurMode = false;           // Whether blur mode is active
+let blurMode = 'element';          // 'element' or 'selection'
+let blurIntensity = 10;            // 5-20px blur strength
+let blurredElements = new Set();   // References to blurred elements
+let hintElement = null;            // Top notification bar
+let blurButton = null;             // Floating blur button (selection mode)
+```
+
+**Persistence:**
+- Only `blurIntensity` is stored in `chrome.storage.local`
+- Blurred elements are NOT persisted across page refreshes (noted as future feature)
+
+### CSS Architecture
+
+**Key CSS Classes:**
+- `.blurtext-blurred` - Applied to blurred elements, uses `--blur-intensity` CSS variable
+- `.blurtext-mode` - Added to `<body>` in element mode for crosshair cursor
+- `.blurtext-highlight` - Dashed outline on hover in element mode
+- `.blurtext-hint` - Top notification bar with gradient background
+- `.blurtext-blur-button` - Floating button in selection mode
+- `.blurtext-selection-wrapped` - Marks spans created by selection mode
+
+**Important:** All styles use `!important` to override page styles
+
+## Development Commands
+
+This extension has no build process. Load directly as unpacked extension:
+
+1. Open `chrome://extensions/` or `edge://extensions/`
+2. Enable "Developer mode"
+3. Click "Load unpacked extension"
+4. Select this directory
+
+**Testing:**
+- Make code changes
+- Go to `chrome://extensions/` and click the refresh icon on BlurText
+- Reload any tabs where you want to test changes
+- Click extension icon to open popup and test functionality
+
+## Common Development Patterns
+
+### Adding New Message Handlers
+
+**In content.js:**
+```javascript
+chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
+  if (request.action === 'yourNewAction') {
+    // Handle the action
+    console.log('[BlurText] Your action:', request);
+  }
+});
+```
+
+**In popup.js:**
+```javascript
+chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
+  chrome.tabs.sendMessage(tabs[0].id, {
+    action: 'yourNewAction',
+    someData: value
+  });
+});
+```
+
+### Modifying Blur Behavior
+
+All blur effects are controlled by the `.blurtext-blurred` class in [content.css](content.css):
+```css
+.blurtext-blurred {
+  filter: blur(var(--blur-intensity, 10px)) !important;
+  /* ... other styles ... */
+}
+```
+
+The intensity is set via inline style in [content.js](content.js):
+```javascript
+element.style.setProperty('--blur-intensity', `${blurIntensity}px`);
+```
+
+### Event Listener Management
+
+Pattern used for mode switching:
+1. Remove all event listeners when changing modes
+2. Add new listeners based on current mode
+3. Clean up UI elements (highlights, buttons) from previous mode
+
+See `updateModeUI()` in [content.js](content.js:93-124) for reference implementation.
+
+## Key Constraints & Design Decisions
+
+1. **No persistence across refreshes** - Blurred elements are not saved (future feature per [CHANGELOG.md](CHANGELOG.md))
+2. **Local-only processing** - No network requests, no external dependencies
+3. **Visual-only protection** - Blur is CSS effect only, does not modify actual page data
+4. **Selection mode limitations** - `Range.surroundContents()` fails on complex nested HTML (error is caught and user is notified)
+5. **Popup auto-closes** - Normal browser behavior after user interacts with page
+
+## File Purpose Reference
+
+- **[icon-generator.html](icon-generator.html)** - Standalone tool for generating extension icons (not part of runtime)
+- **[test.html](test.html)** - Local test page for development
+- **icons/** - PNG icons in sizes 16, 32, 48, 128 (required by manifest)
+
+## Language & Localization
+
+All user-facing strings are in Chinese. When adding features:
+- Console logs use English with `[BlurText]` prefix
+- UI text, hints, and notifications use Chinese
+- Code comments are in Chinese
+- Follow existing patterns in [popup.html](popup.html) and [content.js](content.js)