@cmchu/screen-full

Screenfull.js

Introduction

This module provides a straightforward set of APIs to control the browser's fullscreen functionality and listen for changes and errors in the fullscreen state. By encapsulating the native fullscreen APIs, it enables developers to uniformly handle fullscreen operations across different browsers.

Installation

Install using npm or yarn:

npm install @cmchu/screen-full
# or
yarn add @cmchu/screen-full

Usage

Importing the Module

First, import the screenfull module into your project.

import screenfull from '@cmchu/screen-full';

Core Functions

• Check & Request Fullscreen

  • screenfull.isEnabled: Checks if the current browser supports fullscreen mode.
  • screenfull.isFullscreen: Checks if the current page is in fullscreen.
  • screenfull.request() or screenfull.requestFullscreen(element?, options?): Requests to make an element fullscreen. If no element is specified, it attempts to make the entire document fullscreen by default.

• Exit Fullscreen

  • screenfull.exit() or screenfull.exitFullscreen(element?): Exits fullscreen mode. If no element is specified, it attempts to exit the current fullscreen element.

• Event Listening

  • screenfull.onChange(callback) or screenfull.fullscreenchange(callback): Listens for changes in the fullscreen state.
  • screenfull.onError(callback) or screenfull.fullscreenerror(callback): Listens for fullscreen errors.

• Get Fullscreen Element

  • screenfull.fullElement: Retrieves the current fullscreen element.

Keyboard Controls

• The module automatically intercepts the default behavior of the F11 and Esc keys to implement one-click fullscreen entry/exit functionality.

API Reference

• screenfull.isEnabled: A boolean indicating whether the browser supports the fullscreen API.
• screenfull.isFullscreen: A boolean indicating whether the current page is in fullscreen mode.
• screenfull.request(element?, options?): Enters fullscreen. Optional parameters include the element to be made fullscreen and fullscreen options.
• screenfull.exit(element?): Exits fullscreen mode.
• screenfull.onChange(callback): Registers a listener for changes in the fullscreen state.
• screenfull.onError(callback): Registers a listener for fullscreen errors.
• screenfull.fullElement: Retrieves the current DOM element in fullscreen.
• handleKeyDown(event): An internal function handling keyboard events, automatically responding to F11 and Esc keys.

Considerations

• Ensure compliance with the Same-Origin Policy and user interaction requirements in practical applications, as some browsers may restrict non-user-initiated fullscreen operations.
• The module includes automatic handling of F11 and Esc shortcut keys. Modify or remove this logic as per your application's needs.

Example

import screenfull from '@cmchu/screen-full';

if (screenfull.isEnabled) {
  screenfull.request(); // Enter fullscreen
  screenfull.onChange(() => { // Listen for fullscreen state changes
    if (screenfull.isFullscreen) {
      console.log("Entered fullscreen");
    } else {
      console.log("Exited fullscreen");
    }
  });
} else {
  console.log("Your browser does not support the fullscreen API.");
}

License

This code example is licensed under the MIT License. Please adhere to the terms of relevant open-source licenses when using it.