Designing for Different Devices (Viewport Size, Touch/Hover, etc.)

תיעוד מדריכי מפתחים
1

This document outlines the APIs used to adapt Discourse’s user interface for different devices.

Viewport Size

The most important characteristic to consider is the viewport size. We design “mobile first” and then add customizations for larger devices as needed. The breakpoints we use are:

Breakpoint Size Pixels (at 16px body font size)
sm 40rem 640px
md 48rem 768px
lg 64rem 1024px
xl 80rem 1280px
2xl 96rem 1536px

To use these in an SCSS file, add @use "lib/viewport"; at the top of the file, then use one of the available mixins:

@use "lib/viewport";

@include viewport.from(lg) {
  // SCSS rules here will be applied to
  // devices larger than the lg breakpoint
}

@include viewport.until(sm) {
  // SCSS rules here will be applied to
  // devices smaller than the sm breakpoint
}

@include viewport.between(sm, md) {
  // SCSS rules here will be applied to
  // devices with a size between the sm
  // and md breakpoints
}

In general, SCSS is the recommended way to handle layout differences based on viewport size. For advanced cases, the same breakpoints can be accessed in Ember components via the capabilities service. For example:

import Component from "@glimmer/component";
import { service } from "@ember/service";

class MyComponent extends Component {
  @service capabilities;

  <template>
    {{#if this.capabilities.viewport.lg}}
      This text will be displayed for devices larger than the lg breakpoint
    {{/if}}

    {{#unless this.capabilities.viewport.sm}}
      This text will be displayed for devices smaller than the sm breakpoint
    {{/unless}}
  </template>
}

These properties are reactive, and Ember will automatically re-render the relevant parts of the template as the browser is resized.

Touch & Hover

Some devices only have touchscreens, some only have a traditional mouse pointer, and some have both. Importantly, touchscreen users cannot “hover” over elements. Therefore, interfaces should be designed to work entirely without hover states, with hover-specific enhancements added for devices that support them.

There are several ways to detect touch/hover capability via CSS and JavaScript. For consistency, we recommend using Discourse’s helpers instead of those CSS/JS APIs directly.

For CSS, you can target the .discourse-touch and .discourse-no-touch classes, which are added to the <html> element. These are determined based on the (any-pointer: coarse) media query.

For example:

html.discourse-touch {
  // SCSS rules here will apply to devices with a touch screen,
  // including mobiles/tablets and laptops/desktops with touch screens.
}

html.discourse-no-touch {
  // SCSS rules here will apply to devices with no touch screen.
}

This information is also available in Ember components via the capabilities service:

import Component from "@glimmer/component";
import { service } from "@ember/service";

class MyComponent extends Component {
  @service capabilities;

  <template>
    {{#if this.capabilities.touch}}
      This text will be displayed for devices with a touch screen
    {{/if}}

    {{#unless this.capabilities.touch}}
      This text will be displayed for devices with no touch screen
    {{/unless}}
  </template>
}

Legacy Mobile / Desktop Modes

Historically, Discourse shipped two completely different layouts and stylesheets for “mobile” and “desktop” views, based on the browser’s user-agent. Developers would target these modes by putting CSS in specific mobile/desktop directories, by using the .mobile-view/.desktop-view HTML classes, and the site.mobileView boolean in JavaScript.

These techniques are now considered deprecated and should be replaced with the viewport and capability-based strategies discussed above. We will be removing the dedicated modes in the near future, making “mobile mode” an alias for “viewport width less than sm” for backwards compatibility.

This document is version controlled - suggest changes on github.

9 לייקים
2

אז משהו כזה יהיה מיושן?

@service site;
...
const mobileView = this.site.mobileView;
3

אם אתה עושה זאת בהקשר סטטי, אז כן, זה לא יהיה תואם ל-“מצב מובייל מבוסס תצוגה” הקרוב (מושבת כעת).

אם אתה מבצע את הבדיקה בהקשר של מעקב אוטומטי כמו זה:

@service site;
...

<template>
  {{#if this.site.mobileView}}
    ...
  {{/if}}
</template>

אז Ember ירנדר מחדש אוטומטית דברים כאשר הערך הבוליאני mobileView משתנה (כלומר, כאשר הדפדפן משנה את גודלו). אז זה בסדר.

4

אז רק כדי להיות בטוח, הכנסתו ל-getter היא פסה, אבל לא הכנסתה ל-<template>?

5

הכנסתו ל-getter זה גם בסדר, מכיוון ש-Ember יעקוב אחריו באופן אוטומטי.

@service site;

get shouldRender(){
  return this.site.mobileView;
}


<template>
  {{#if this.shouldRender}}
    ...
  {{/if}}
</template>

^^ זה בסדר

דוגמה גרועה תהיה

export default apiInitializer((api) => {
  if(api.container.lookup("service:site").mobileView){
    api.renderInOutlet("some-outlet", <template>My content</template>)
  }
});

מכיוון שבמצב זה, mobileView נבדק רק כאשר היישום עולה. שינוי גודל הדפדפן לא יפעיל מחדש את ה-initializer.

לכן היית מבצע refactor למשהו כמו

export default apiInitializer((api) => {
  const site = api.container.lookup("service:site");
  api.renderInOutlet("some-outlet", <template>
    {{#if site.mobileView}}My content{{/if}}
  </template>);
});

כך ששינויים ב-mobileView ייכנסו לתוקף כאשר הדפדפן משנה את גודלו.

3 לייקים
6

הובן כעת. תודה על ההסבר!

לייק 1
7

“Deprecation notice: Accessing capabilities.viewport.sm during the site initialization phase is not recommended. Using these values during initialization can lead to errors and inconsistencies when the browser window is resized. Please move these checks to a component, transformer, or API callback that executes during page rendering. [deprecation id: discourse.static-viewport-initialization]”

I’ve been using initialisers to switch on and off various functionality based on whether we are in a mobile view or not (e.g. changing the default Homepage, adding a community section link for example). These aren’t really meant to be dynamic and reactive - suggestions welcome on how to treat these use cases and make sure I can defeat this notice.

לייק 1
8

The general recommendation is: don’t do that. Why should those kind of experiences differ based on the size of the screen?

A useful thought experiment is: how do you expect it to behave on folding phones or tablets, which don’t explicitly fit into the mobile/desktop buckets.

If you really do want this kind of behaviour change to be based on the user-agent of the browser (as the old mobile/desktop modes worked), then we have capabilities.isMobileDevice, which quite literally checks for the word “mobile” in the user-agent string:

לייק 1
9

well in my case it’s that I provide the option for desktop to switch homepage to the tag intersections route - whose interface doesn’t exist on mobile … (though the route actually works - additional controls are hidden)

… but point taken, I’ll probably rethink this!

לייק 1
10

Interesting! I wonder if that’s deliberate… I feel like it should work on any device :thinking:

2 לייקים