Element Picker

Reusable element picker library for userscripts.

此脚本不应直接安装。它是供其他脚本使用的外部库，要使用该库请加入元指令 // @require https://update.greasyfork.org/scripts/589922/1893812/Element%20Picker.js

提问、发表评价或者举报此脚本。

作者: hdyzen
版本: 0.0.3
创建于: 2026-08-04
更新于: 2026-08-05
大小: 32.2 KB
许可证: 暂无

Element Picker

A DOM element selection library designed for Userscripts and browser extensions. It features a premium draggable interface, an advanced selector engine, interactive DOM traversal, and theme customization support.

Features

Advanced Selector Engine: Generates the shortest possible unique CSS selector (supports id, data-attributes, and automatically calculates :nth-child).
Draggable Interface: Interactive floating panel with DOM breadcrumbs, directional arrow navigation, and customizable action buttons.
X-Ray Mode: Hold Alt to bypass invisible overlays and select the elements hidden underneath them.
Promise-Based API: Easily capture elements asynchronously using the .pickOnce() method.
Shadow DOM Support: Identifies the real elements inside open Shadow DOMs.
Customizable Themes: Change primary colors, backgrounds, and text via the API.
Global Hotkeys: Native support for keyboard shortcuts (e.g., Ctrl+Shift+E) to enable or disable the picker.

How to Use

1. Initialization

To use the library, call the global elementPicker(config) function and store the generated instance.

// Initializes with a global keyboard shortcut (optional)
const picker = elementPicker({ 
    toggleHotkey: 'Ctrl+Shift+E' 
});

2. Simple Mode (Promise API)

If you just need the user to click an element and return the result, use pickOnce(). The interface closes automatically after the click.

async function captureImage() {
    // Enables the picker allowing ONLY images
    const element = await picker.pickOnce({ filter: 'img' });

    console.log("Selected image:", element.src);
}

3. Continuous Mode and Custom Actions

You can inject your own buttons into the floating bar. These buttons will appear when an element is "locked" (clicked).

const picker = elementPicker();

// Adds a custom button
const actionId = picker.addAction({
    label: 'Extract Data',
    primary: true, // Highlights the button
    onClick: (el) => {
        console.log("Extracted text:", el.innerText);
        picker.disable(); // Closes the picker after the action
    }
});

// Enables the picker with restrictions (optional)
picker.enable({
    exclude: 'header, footer, .ads' // Ignores these elements
});

API Documentation

`elementPicker(globalConfig)`

Creates a new picker instance.

globalConfig (Object):
toggleHotkey (String): Shortcut to toggle the picker globally (e.g., 'Ctrl+Shift+E').

Core Methods

`enable(options)`

Enables the selection interface.

options (Object):
filter (String): CSS selector. If defined, only elements that match this selector can be picked (e.g., 'div, a').
exclude (String): CSS selector. Elements matching this will be ignored by the mouse.

`disable()`

Disables and hides the interface, removing the overlays from the screen.

`toggle(options)`

Switches between enable() and disable().

`pickOnce(options) -> Promise<Element>`

Enables the picker, waits for the user to click an element, disables the picker, and returns the element inside a Promise.

`destroy()`

Completely removes the library from the page (deletes the UI from the Shadow DOM, clears global listeners, and empties all callbacks).

Custom Actions (Buttons)

`addAction(config) -> String`

Adds a button to the bar when an element is selected. Returns a unique id.

config: { label: String, primary: Boolean, onClick: Function(Element) }

`removeAction(id)`

Removes a specific action using the id returned by addAction.

`removeAllActions()`

Removes all custom injected buttons.

Events and States

`onSelect(callback) -> Function`

Registers a function to be called every time an element is "locked" (clicked). Returns an unsubscribe function.

const unsub = picker.onSelect((el) => console.log(el));
// unsub(); // Stops listening

`isEnabled() -> Boolean`

Returns true if the selection interface is currently active.

`getHoveredElement() -> Element | null`

Returns the element currently under the mouse cursor.

`getSelectedElement() -> Element | null`

Returns the currently locked (clicked) element.

`setSelectedElement(element)`

Forces the selection/lock on a specific element via code. Triggers the onSelect callbacks.

Customization

`setTheme(colors)`

Overrides the UI CSS variables. Colors must be valid CSS strings (Hex, RGB, HSL, etc.).

picker.setTheme({
    primary: '#10B981',       // Highlight color (green)
    background: '#1F2937',    // UI bar background
    text: '#FFFFFF',          // Main text color
    highlightBorder: 'red',   // Hover border color
});

Available properties: primary, background, text, textMuted, border, divider, pillBackground, highlightBorder, badgeBackground, badgeText, buttonBackground, buttonText.

Commands and Keyboard Shortcuts

When the Picker is enabled, the following shortcuts are available:

Key	Action	Context
`Alt` (Hold)	X-Ray Mode: Bypasses overlays. Hides the hovered element to focus on what is underneath it.	Hovering
`Esc`	Disables the Element Picker (`disable()`).	Always
`Click`	Locks/Unlocks the selection on the current element.	Hovering
`Arrows (↑ ↓ ← →)`	DOM Traversal: Navigates through the DOM tree starting from the locked element (Parent, First Child, Previous Sibling, Next Sibling).	Locked Element

Contributing / Author

Developed by hdyzen. Designed for GreasyFork scripts. Feel free to report bugs, suggest performance improvements, or create forks to adapt it to your needs.