jsdom-browser.screen-orientation

The implementation of the Screen Orientation API for jsdom-browser.

jsdom-browser is a simulator of a Web browser with JSDOM.

This module is implemented along the Screen Orientation API on 26 September 2018. This specification may become older than the latest version.

Install

$ npm install jsdom-browser.screen-orientation

Usage

Creates and updates the current orientation type and angle

Creates a ScreenOrientation object and its config object:

const { ScreenConfig } = require('jsdom-browser.screen')
const { ScreenOrientation, ScreenOrientationConfig } = require('jsdom-browser.screen-orientation')

const { JSDOM } = require('jsdom')
const window = new JSDOM().window

const screenConfig = new ScreenConfig({ width: 768, height: 1024 })
screenConfig.configure(window.screen)

const orientationConfig = new ScreenOrientationConfig({
  relationsOfTypeAndAngle: {
    'landscape-primary': 0,
    'portrait-primary': 90,
    'landscape-secondary': 180,
    'portrait-secondary': 270,
  }
})
const orientation = ScreenOrientation.create([], {
  associatedDocument: window.document,
})
orientationConfig.configure(orientation)
window.screen.orientation = orientation


orientation.addEventListener('change', () => {
  console.log(`Orientation was changed: ${orientation.type}`);
})
orientation.onchange = () => {
  console.log(`Orientation was changed (onchange): ${orientation.type}`);
}
orientationConfig.on('change', cfg => {
  console.log(`Orientation was changed (config): ${cfg.currentType}`)
})

Gets the current orientation type and angle:

window.screen.width // => 1024
window.screen.height // => 768
window.screen.orientation.type  // => 'landscape-primary'
window.screen.orientation.angle // => 0

screenConfig.width // => 768
screenConfig.height // => 1024
screenConfig.deviceAngle // => 0
screenConfig.screenAngle // => 0
screenConfig.baseAngle   // => 90

orientationConfig.currentType // => 'landscape-primary'
orientationConfig.currentAngle // => 0
orientationConfig.orientations
// => ['portrait-primary', 
//     'landscape-primary',
//     'portrait-secondary',
//     'landscape-secondary' ]

Simulates of rotating screen:

screenConfig.deviceAngle = -110
orientationConfig.handleRotation()

window.screen.width // => 768
window.screen.height // => 1024
window.screen.orientation.type  // => 'portrait-primary'
window.screen.orientation.angle // => 90

screenConfig.width // => 768
screenConfig.height // => 1024
screenConfig.deviceAngle // => -110
screenConfig.screenAngle // => 90
screenConfig.baseAngle   // => 90

orientationConfig.currentType // => 'portrait-primary'
orientationConfig.currentAngle // => 90
orientationConfig.orientations
// => ['portrait-primary', 
//     'landscape-primary',
//     'portrait-secondary',
//     'landscape-secondary' ]

The output to console is as follows:

Orientation was changed (config): portrait-primary
Orientation was changed: portrait-primary
Orientation was changed (onchange): portrait-primary

Lock the orientation

orientation.lock('landscape').then(() => {
  console.log('Orientation was locked')

  window.screen.width // => 1024
  window.screen.height // => 768
  window.screen.orientation.type  // => 'landscape-primary'
  window.screen.orientation.angle // => 0

  screenConfig.width // => 768
  screenConfig.height // => 1024
  screenConfig.deviceAngle // => -110
  screenConfig.screenAngle // => 0
  screenConfig.baseAngle   // => 90

  orientationConfig.currentType // => 'landscape-primary'
  orientationConfig.currentAngle // => 0

  orientationConfig.orientations
  // => ['landscape-primary',
  //     'landscape-secondary']
}).catch(() => {
  console.log('Orientation lock was rejected')
})

The output to console is as follows:

Orientation was locked
Orientation was changed (config): landscape-primary
Orientation was changed: landscape-primary
Orientation was changed (onchange): landscape-primary

Unlock the orientation

orientation.unlock()

window.screen.width // => 1024
window.screen.height // => 768
window.screen.orientation.type  // => 'landscape-primary'
window.screen.orientation.angle // => 0

screenConfig.width // => 768
screenConfig.height // => 1024
screenConfig.deviceAngle // => -110
screenConfig.screenAngle // => 0
screenConfig.baseAngle   // => 90

orientationConfig.currentType // => 'landscape-primary'
orientationConfig.currentAngle // => 0

orientatonConfig.orientations
// => ['portrait-primary',
//     'landscape-primary',
//     'portrait-secondary',
//     'landscape-secondary' ]

API

class ScreenOrientation : EventTarget

Is an implementation of ScreenOrientation API.

Properties:

| Name | Type | Description | |:---------|:------:|:--------------| | type | string | The current orientation type. (read only) | | angle | number | The current orientation angle. (read only ) | | onchange | function | The change event handler. |

lock (lockType) => Promise

Locks the orientation to an orientation type set associated with the specified orientation lock type.

Parameters:

| Parameter | Type | Description | |:-----------|:------:|:---------------------------| | lockType | string | An orientation lock type |

Returns:

A promise object

unlock () => Void

Locks the orientation to default orientation set.

class ScreenOrientationConfig

Is a configuration class to configure a ScreenOrientation object.

Properties:

| Name | Type | Description | |:-------------|:------:|:----------------------| | currentType | string | The current orientation type. | | currentAngle | number | The current orientation angle. | | onchange | function | The change event handler. | | orientations | Array | The current orientation lock types. | | defaultOrientation | Array | The orientation lock types in default and when unlocked. | | isSupportLocking | boolean | The flag to simulate user agent which is not support locking. (false in default) | | isSecurityError | boolean | The flag to simulate behavior that user agent doesn't meet the security conditions. (false in default) | | isActiveOrientationLock | boolean | The flag to simulte behavior of inactive orientation lock. (true in default) |

constructor (screenConfig, initConfig) => ScreenOrientationConfig

Creates an instance of this class. This constructor requires screenConfig as the first argument to get its device angle, screen angle and orientation config array of which elements are the ScreenOrientationConfig objects dangled a same top window. Also, this constructor can accept initConfig as the second argument to configure this instance.

Parameters:

| Parameter | Type | Description | |:---------------|:--------------:|:----------------| | screenConfig | ScreenConfig | The config object of window.screen | | initConfig | object | ScreenOrientationConfig | The initial configuration object of which properties are as follows. |

• Properties of initConfig

  See ./src/default.js

  | Name | Type | Description | |:------------|:------:|:--------------| | deviceAngle | number | An angle of device which is used when updating orientation. | | relationsOfTypeAndAngle | object | A mapping of orientation types and orientation angles. | | defaultOrientation | Array | An array of orientation types when orientation is unlocked. | | isSecurityError | boolean | A flag to cause a security error forcely when locking. | | isActiveOrientationLock | boolean | A flag to abort locking because of not active orientatin lock. | | messages | object | Messages for some errors. |

update () => Void

Updates the orientation type and angle with the device angle of the ScreenConfig object and the orientations property of this object.

This method fires no change event even if this orientation type is changed.

handleRotation () => Void

Updates the orientation type and angle with the device angle of the ScreenConfig object and the orientations property of this object.

This method fires change events to the orientations associated with the current document, the top document and the all other descendant documents of the top document if this orientation type is changed.

handleVisible () => Void

Updates the orientation type and angle with the device angle of the ScreenConfig object and the orientations property of this object.

This method fires a change event to the current orientation if this orientation type is changed.

on (eventName, handler) => Void

Registers an event handler of an event of which name is eventName.

WebIDL

See the Screen Orientation API,

[Exposed=Window]
interface ScreenOrientation : EventTarget {
  Promise<void> lock(OrientationLockType orientation);
  void unlock();
  readonly attribute OrientationType type;
  readonly attribute unsigned short angle;
  attribute EventHandler onchange;
};

License

Copyright (C) 2018 Takayuki Sato

This program is free software under MIT License. See the file LICENSE in this distribution for more details.