Analysis and Solution for document.addEventListener('load') Failure in Greasemonkey Scripts

Problem Phenomenon and Background

During Greasemonkey user script development, developers often encounter situations where document.addEventListener('load', function) fails to work properly. Specifically, the event listener registers successfully, but the corresponding callback function is never executed. This issue does not produce any error messages on the surface, making debugging particularly challenging.

Root Cause Analysis

Through detailed technical analysis, the core issue is identified as differences between Greasemonkey's execution environment and standard web environments. In Greasemonkey's operational mechanism, the load event listener of the document object suffers from reliability problems. This is primarily due to the complex interaction between Greasemonkey script execution timing and page loading processes.

From a technical implementation perspective, Greasemonkey scripts typically begin execution when DOM content has loaded but external resources are still loading. At this point, the load event of the document may have already fired, or cannot be properly captured due to the isolation of the execution environment.

Solution: window.addEventListener Alternative

The most effective solution to this problem is using window.addEventListener('load', function) instead of document.addEventListener. These two methods use identical parameters but exhibit significant differences in reliability within the Greasemonkey environment.

Here is the corrected code example:

// ==UserScript==
// @name        wifi-autologin
// @namespace   lf-ns
// @description Hopefully autologins to a captive portal
// @include     *://1.1.1.1/*
// @version     1
// @run-at document-end
// ==/UserScript==

window.addEventListener('load', submitAction);

Impact of Greasemonkey 4 Updates

The issues mentioned in the reference article further confirm the importance of execution timing. After the Greasemonkey 4 update, script execution timing changed, causing compatibility issues for many user scripts that relied on specific loading sequences.

Specifically, scripts may execute before variable definitions in page <script> tags, resulting in errors like $ is not defined. Even when using window.addEventListener('load', ...), execution blocking issues may still occur in certain scenarios.

Best Practice Recommendations

Based on the above analysis, we recommend following these best practices in Greasemonkey script development:

First, always prefer window.addEventListener('load', callback) over document.addEventListener('load', callback). This approach offers better reliability and compatibility in Greasemonkey environments.

Second, properly utilize the @run-at metadata directive to control script execution timing. The document-end directive ensures script execution after DOM parsing completes, but the asynchronicity of external resource loading should still be considered.

For scenarios requiring access to specific JavaScript library instances within the page, we recommend combining multiple event listening strategies:

// Multiple event listeners to ensure execution timing
window.addEventListener('DOMContentLoaded', function() {
    // Handling when DOM is ready
});

window.addEventListener('load', function() {
    // Handling after all resources are loaded
});

In-depth Technical Principles

From the perspective of browser event models, the load event of the window object and the load event of the document object should theoretically fire at the same time. However, in Greasemonkey's sandboxed environment, event propagation mechanisms may be subject to additional influences.

Greasemonkey runs user scripts by creating isolated JavaScript execution environments. While this isolation mechanism enhances security, it also introduces special behaviors in event listening. In such environments, event listeners on the window object are generally more stable and reliable than those on the document object.

Compatibility Considerations

It's important to note that while window.addEventListener('load') performs well in most modern browsers and Greasemonkey versions, differences may still exist in very old environments. We recommend thorough cross-environment testing before actual deployment.

For situations requiring support for multiple user script managers, consider adding environment detection logic:

// Environment-adapted event listening
if (typeof GM_info !== 'undefined') {
    // Greasemonkey/Tampermonkey environment
    window.addEventListener('load', mainFunction);
} else {
    // Standard web environment
    document.addEventListener('DOMContentLoaded', mainFunction);
}

Conclusion

The failure of document.addEventListener('load') in Greasemonkey scripts stems from the特殊性 of the execution environment. By switching to window.addEventListener('load') and properly controlling execution timing, this issue can be effectively resolved. Additionally, understanding changes brought by Greasemonkey version updates helps in writing more robust and compatible user scripts.