A lightweight JS library for watching DOM element creation and removal using Mutation Observers.
此腳本不應該直接安裝，它是一個供其他腳本使用的函式庫。欲使用本函式庫，請在腳本 metadata 寫上： // @require https://update.greasyfork.org/scripts/519079/1506007/arrivejs%20252.js
A lightweight JS library for watching DOM element creation and removal using Mutation Observers.
npm install arrive --save # Using NPM
Or download arrive.min.js directly.
// Basic usage
document.arrive(".test-elem", function(newElem) {
// newElem is the newly created element
});
// Watch within a specific container (recommended for better performance)
document.querySelector(".container").arrive(".test-elem", function(newElem) {
// More specific watching
});
// you can bind event to multiple elements at once
// this will bind arrive event to all the elements returned by document.querySelectorAll()
document.querySelectorAll(".box").arrive(".test-elem", function(newElem) {
});
Important: Promise-based syntax resolves only for the first matching element. For monitoring multiple or continuous element creation, use the callback approach described above.
Note: There's no need to use the
onceOnlyoption with Promise-based usage as Promises inherently resolve only once.
var newElem = await document.arrive(".test-elem");
// do stuff with the element
The arrive event accepts an optional configuration object:
{
// Watch for changes to existing elements' attributes
fireOnAttributesModification: false,
// Fire callback only once, then auto-unbind
onceOnly: false,
// Fire callback for elements that already exist in the DOM
existing: false,
// Call callback with null after specified milliseconds and Auto-unbind (0 = disabled)
timeout: 0
}
Example:
document.arrive(".test-elem", {
fireOnAttributesModification: true, // Watch for attribute changes
existing: true, // Include existing elements
onceOnly: true, // Fire callback only once
timeout: 5000 // Auto-unbind after 5 seconds call callback with null
}, (newElem) => {
console.log(newElem);
});
Use the leave event to detect when elements are removed from the DOM.
Important: Due to MutationObserver API limitations, the selector must be direct (e.g.,
.test-elem) and cannot use descendant or child combinators (e.g.,.page .test-elemis not allowed).
// Watch for element removal
document.querySelector(".container-1").leave(".test-elem", function(removedElem) {
// removedElem is the element that was just removed
});
// With options
document.querySelector(".container-1").leave(".test-elem", {
onceOnly: true, // Fire once per element
timeout: 5000 // Auto-unbind after 5 seconds
}, function(removedElem) {
// removedElem is the element that was just removed
});
For better performance, make sure to remove listeners when they are no longer needed:
// unbind all arrive events on document element
document.unbindArrive();
// unbind all arrive events on a specific element
document.querySelector(".box").unbindArrive();
// unbind all arrive events on document element which are watching for ".test-elem" selector
document.unbindArrive(".test-elem");
// unbind only a specific callback
document.unbindArrive(callbackFunc);
// unbind only a specific callback on ".test-elem" selector
document.unbindArrive(".test-elem", callbackFunc);
// unbind all arrive events (registered on any element)
Arrive.unbindAllArrive();
// Unbind all leave events on document element
document.unbindLeave();
// Unbind all leave events (registered on any element)
Arrive.unbindAllLeave();
If you use jQuery, you can call all arrive functions on jQuery elements as well:
// watch for element creation in the whole HTML document
$(document).arrive(".test-elem", function(newElem) {
// Note: newElem is a javascript element not a jQuery element
});
// this will attach arrive event to all elements returned by $(".container-1")
$(".container-1").arrive(".test-elem", function(newElem) {
// Note: newElem is a javascript element not a jQuery element
});
arrive.js is built over Mutation Observers which is introduced in DOM4. It's supported in latest versions of all popular browsers.
| Browser | Supported Versions |
|---|---|
| Google Chrome | 27.0+ |
| Firefox | 14.0+ |
| Safari | 6.1+ |
| Internet Explorer | 11.0+ |
| Opera | 14.0+ |
If you want to report a bug or request a feature, use the Issues section. Before creating a new issue, search the existing ones to make sure that you're not creating a duplicate. When reporting a bug, be sure to include OS/browser version and steps/code to reproduce the bug, a JSFiddle would be great.
If you want to contribute to arrive, here is the workflow you should use:
dev branch, create and checkout a new feature branch to work upon. (If you want to work on some minor bug fix, you can skip this step and continue to work in dev branch)/src/arrive.js)./tests/spec/arriveSpec.js file./tests/SpecRunner.html in a browser. There is a button 'Run tests without jQuery' at the top left of th page, click that button to make sure that the tests passes without jQuery. Run the test cases in all major browsers.Keywords
javascript, js, jquery, node.js, watch, listen, creation, dynamically, removal, new, elements, DOM, dynamic, detect, insertions, event, bind, live, livequery