docs/javascript/new-api_browser.md

   1 # Browser and Screen Sizes - JavaScript API
   2
   3 ## `Ui/Screen`
   4
   5 CSS offers powerful media queries that alter the layout depending on the screen
   6 sizes, including but not limited to changes between landscape and portrait mode
   7 on mobile devices.
   8
   9 The `Ui/Screen` module exposes a consistent interface to execute JavaScript code
  10 based on the same media queries that are available in the CSS code already. It
  11 features support for unmatching and executing code when a rule matches for the
  12 first time during the page lifecycle.
  13
  14 ### Supported Aliases
  15
  16 You can pass in custom media queries, but it is strongly recommended to use the
  17 built-in media queries that match the same dimensions as your CSS.
  18
  19 | Alias | Media Query |
  20 |---|---|
  21 | `screen-xs` | `(max-width: 544px)` |
  22 | `screen-sm` | `(min-width: 545px) and (max-width: 768px)` |
  23 | `screen-sm-down` | `(max-width: 768px)` |
  24 | `screen-sm-up` | `(min-width: 545px)` |
  25 | `screen-sm-md` | `(min-width: 545px) and (max-width: 1024px)` |
  26 | `screen-md` | `(min-width: 769px) and (max-width: 1024px)` |
  27 | `screen-md-down` | `(max-width: 1024px)` |
  28 | `screen-md-up` | `(min-width: 769px)` |
  29 | `screen-lg` | `(min-width: 1025px)`
  30
  31 ### `on(query: string, callbacks: Object): string`
  32
  33 Registers a set of callback functions for the provided media query, the possible
  34 keys are `match`, `unmatch` and `setup`. The method returns a randomly generated
  35 UUIDv4 that is used to identify these callbacks and allows them to be removed
  36 via `.remove()`.
  37
  38 ### `remove(query: string, uuid: string)`
  39
  40 Removes all callbacks for a media query that match the UUIDv4 that was previously
  41 obtained from the call to `.on()`.
  42
  43 ### `is(query: string): boolean`
  44
  45 Tests if the provided media query currently matches and returns true on match.
  46
  47 ### `scrollDisable()`
  48
  49 Temporarily prevents the page from being scrolled, until `.scrollEnable()` is
  50 called.
  51
  52 ### `scrollEnable()`
  53
  54 Enables page scrolling again, unless another pending action has also prevented
  55 the page scrolling.
  56
  57 ## `Environment`
  58
  59 !!! warning "The `Environment` module uses a mixture of feature detection and user agent sniffing to determine the browser and platform. In general, its results have proven to be very accurate, but it should be taken with a grain of salt regardless. Especially the browser checks are designed to be your last resort, please use feature detection instead whenever it is possible!"
  60
  61 Sometimes it may be necessary to alter the behavior of your code depending on
  62 the browser platform (e. g. mobile devices) or based on a specific browser in
  63 order to work-around some quirks.
  64
  65 ### `browser(): string`
  66
  67 Attempts to detect browsers based on their technology and supported CSS vendor
  68 prefixes, and although somewhat reliable for major browsers, it is highly
  69 recommended to use feature detection instead.
  70
  71 Possible values:
  72  - `chrome` (includes Opera 15+ and Vivaldi)
  73  - `firefox`
  74  - `safari`
  75  - `microsoft` (Internet Explorer and Edge)
  76  - `other` (default)
  77
  78 ### `platform(): string`
  79
  80 Attempts to detect the browser platform using user agent sniffing.
  81
  82 Possible values:
  83  - `ios`
  84  - `android`
  85  - `windows` (IE Mobile)
  86  - `mobile` (generic mobile device)
  87  - `desktop` (default)