feat: add contents.getBackgroundThrottling() + backgroundThrottling property (#21036)

docs/api/modernization/property-updates.md

@@ -34,6 +34,7 @@ The Electron team is currently undergoing an initiative to convert separate gett
   * `fullscreenable`
   * `movable`
   * `closable`
+  * `backgroundThrottling`
 * `NativeImage`
   * `isMacTemplateImage`
 * `SystemPreferences` module

docs/api/web-contents.md

@@ -1812,6 +1812,11 @@ Returns `Promise<void>` - Indicates whether the snapshot has been created succes
 
 Takes a V8 heap snapshot and saves it to `filePath`.
 
+#### `contents.getBackgroundThrottling()`
+
+Returns `Boolean` - whether or not this WebContents will throttle animations and timers
+when the page becomes backgrounded. This also affects the Page Visibility API.
+
 #### `contents.setBackgroundThrottling(allowed)`
 
 * `allowed` Boolean
@@ -1879,3 +1884,8 @@ A [`Debugger`](debugger.md) instance for this webContents.
 [event-emitter]: https://nodejs.org/api/events.html#events_class_eventemitter
 [SCA]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
 [`postMessage`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
+
+#### `contents.backgroundThrottling`
+
+A `Boolean` property that determines whether or not this WebContents will throttle animations and timers
+when the page becomes backgrounded. This also affects the Page Visibility API.

lib/browser/api/browser-window.js

@@ -157,6 +157,9 @@ Object.assign(BrowserWindow.prototype, {
   setTouchBar (touchBar) {
     electron.TouchBar._setOnWindow(touchBar, this);
   },
+  getBackgroundThrottling () {
+    return this.webContents.getBackgroundThrottling();
+  },
   setBackgroundThrottling (allowed) {
     this.webContents.setBackgroundThrottling(allowed);
   }

lib/browser/api/web-contents.js

@@ -587,6 +587,11 @@ WebContents.prototype._init = function () {
     get: () => this.getFrameRate(),
     set: (rate) => this.setFrameRate(rate)
   });
+
+  Object.defineProperty(this, 'backgroundThrottling', {
+    get: () => this.getBackgroundThrottling(),
+    set: (allowed) => this.setBackgroundThrottling(allowed)
+  });
 };
 
 // Public APIs.

shell/browser/api/electron_api_web_contents.cc

@@ -1439,6 +1439,10 @@ void WebContents::NavigationEntryCommitted(
        details.is_same_document, details.did_replace_entry);
 }
 
+bool WebContents::GetBackgroundThrottling() const {
+  return background_throttling_;
+}
+
 void WebContents::SetBackgroundThrottling(bool allowed) {
   background_throttling_ = allowed;
 
@@ -2719,6 +2723,8 @@ void WebContents::BuildPrototype(v8::Isolate* isolate,
   prototype->SetClassName(gin::StringToV8(isolate, "WebContents"));
   gin_helper::Destroyable::MakeDestroyable(isolate, prototype);
   gin_helper::ObjectTemplateBuilder(isolate, prototype->PrototypeTemplate())
+      .SetMethod("getBackgroundThrottling",
+                 &WebContents::GetBackgroundThrottling)
       .SetMethod("setBackgroundThrottling",
                  &WebContents::SetBackgroundThrottling)
       .SetMethod("getProcessId", &WebContents::GetProcessID)

shell/browser/api/electron_api_web_contents.h

@@ -187,6 +187,7 @@ class WebContents : public gin_helper::TrackableObject<WebContents>,
   // See https://github.com/electron/electron/issues/15133.
   void DestroyWebContents(bool async);
 
+  bool GetBackgroundThrottling() const;
   void SetBackgroundThrottling(bool allowed);
   int GetProcessID() const;
   base::ProcessId GetOSProcessID() const;

spec-main/api-web-contents-spec.ts

@@ -1541,6 +1541,39 @@ describe('webContents module', () => {
     });
   });
 
+  describe('getBackgroundThrottling()', () => {
+    afterEach(closeAllWindows);
+    it('works via getter', () => {
+      const w = new BrowserWindow({ show: false });
+
+      w.webContents.setBackgroundThrottling(false);
+      expect(w.webContents.getBackgroundThrottling()).to.equal(false);
+
+      w.webContents.setBackgroundThrottling(true);
+      expect(w.webContents.getBackgroundThrottling()).to.equal(true);
+    });
+
+    it('works via property', () => {
+      const w = new BrowserWindow({ show: false });
+
+      w.webContents.backgroundThrottling = false;
+      expect(w.webContents.backgroundThrottling).to.equal(false);
+
+      w.webContents.backgroundThrottling = true;
+      expect(w.webContents.backgroundThrottling).to.equal(true);
+    });
+
+    it('works via BrowserWindow', () => {
+      const w = new BrowserWindow({ show: false });
+
+      (w as any).setBackgroundThrottling(false);
+      expect((w as any).getBackgroundThrottling()).to.equal(false);
+
+      (w as any).setBackgroundThrottling(true);
+      expect((w as any).getBackgroundThrottling()).to.equal(true);
+    });
+  });
+
   ifdescribe(features.isPrintingEnabled())('getPrinters()', () => {
     afterEach(closeAllWindows);
     it('can get printer list', async () => {