Palances Liao on web.dev

How to use multiple screens

2022-10-10T00:00:00Z

The modern way #

Using `window.getScreenDetails()` #

To make sure your browser supports the getScreenDetails() method, first check if it exists on the window object. Then, call window.getScreenDetails() to get attached screens. Adding an event listener to adapt to changed screen details allows you to manage multiple screens according to the needs of your app.

if ('getScreenDetails' in window) {
  // The Window Management API is supported.
  const screenDetails = await window.getScreenDetails();
  screenDetails.addEventListener('screenschange', (event) => {
    // Handle screens change.
  });
}

Browser support

Chrome 100, Supported 100
Firefox, Not supported
Edge 100, Supported 100
Safari, Not supported

The classic way #

Using the window.screen method #

There's no classic way to control multi-screen layouts, but you can fall back to controlling the current screen by using the window.screen property and polyfill the new API shape.

if (!('getScreenDetails' in window)) {
  // Returning a one-element array with the current screen,
  // noting that there might be more.
  window.getScreenDetails = async () => [window.screen];
  // Set to `false`, noting that this might be a lie.
  window.screen.isExtended = false;
}

Browser support

Chrome 1, Supported 1
Firefox 1, Supported 1
Edge 12, Supported 12
Safari 1, Supported 1

Source

Progressive enhancement #

The demo below shows how you can handle multiple screens with the Window Management API. The code checks the browser capability first and then falls back to the classic way.

const detectButton = document.querySelector('#detectScreen');
const createButton = document.querySelector('#create');
const permissionLabel = document.querySelector('#permissionStatus');
const screensAvailLabel = document.querySelector('#screensAvail');
const popupUrl = './popup.html';
let screenDetails = undefined;
let permission = undefined;
let currentScreenLength = undefined;

detectButton.addEventListener('click', async () => {
  if ('getScreenDetails' in window) {
    screenDetails = await window.getScreenDetails();
    screenDetails.addEventListener('screenschange', (event) => {
      if (screenDetails.screens.length !== currentScreenLength) {
        currentScreenLength = screenDetails.screens.length;
        updateScreenInfo();
      }
    });
    try {
      permission =
        (await navigator.permissions.query({ name: 'window-management' })).state === 'granted'
          ? 'Granted'
          : 'No Permission';
    } catch (err) {
      console.error(err);
    }
    currentScreenLength = screenDetails.screens.length;
    updateScreenInfo();
  } else {
    screenDetails = window.screen;
    permission = 'Window Management API - NOT SUPPORTED';
    currentScreenLength = 1;
    updateScreenInfo();
  }
});

createButton.addEventListener('click', () => {
  let screen = screenDetails.screens[Math.floor(Math.random() * currentScreenLength)];
  options = {
    x: screen.availLeft,
    y: screen.availTop,
    width: screen.availWidth,
    height: screen.availHeight,
  };
  window.open(popupUrl, '_blank', getFeaturesFromOptions(options));
});

function getFeaturesFromOptions(options) {
  return (
    'left=' +
    options.x +
    ',top=' +
    options.y +
    ',width=' +
    options.width +
    ',height=' +
    options.height
  );
}

updateScreenInfo = () => {
  screensAvailLabel.innerHTML = currentScreenLength;
  permissionLabel.innerHTML = permission;
  if ('getScreenDetails' in window && screenDetails.screens.length > 1) {
    createButton.disabled = false;
  } else {
    createButton.disabled = true;
  }
};

Demo #

How to handle files opened from the file explorer

2022-10-10T00:00:00Z

The modern way #

Using the File Handling API #

First, declare the file_handlers attribute in your web app manifest. The File Handling API requires you to specify the action property (a handling URL) and the accept property, which is an object with MIME types as keys and arrays of the particularly corresponding file extensions.

{
  "file_handlers": [
    {
      "action": "./",
      "accept": {
        "image/*": [".jpg", ".jpeg", ".png", ".webp", ".svg"]
      }
    }
  ]
}

Next, you need to use the File Handling API to imperatively deal with opened files via the launchQueue.

if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  launchQueue.setConsumer((launchParams) => {
    if (!launchParams.files.length) {
      return;
    }
    for (const fileHandle of launchParams.files) {
      // Handle the file.
    }
  });
}

Browser support

Chrome 102, Supported 102
Firefox, Not supported
Edge 102, Supported 102
Safari, Not supported

The classic way #

Using the classic `DataTransferItem.getAsFile()` method #

If the File Handling API is not supported, you can still drag and drop files from the file explorer into the app. The DataTransferItem.getAsFile() method returns the drag data item's File object. If the item is not a file, this method returns null. While you can read the file, there is no way to write back to it. This method has the disadvantage that it does not support directories.

Browser support

Chrome 11, Supported 11
Firefox 50, Supported 50
Edge 12, Supported 12
Safari 5.1, Supported 5.1

Source

Progressive enhancement #

The snippet below uses the File Handling API when it's available, and additionally registers drag and drop handlers so dragged files can be handled.

Declare the file types that can be handled in the web app manifest. Browsers that don't support the File Handling API will just ignore this.

{
  "file_handlers": [
    {
      "action": "./",
      "accept": {
        "image/*": [".jpg", ".jpeg", ".png", ".webp", ".svg"]
      }
    }
  ]
}

// File Handling API
const handleLaunchFiles = () => {
  window.launchQueue.setConsumer((launchParams) => {
    if (!launchParams.files.length) {
      return;
    }
    launchParams.files.forEach(async (handle) => {
      const file = await handle.getFile();
      console.log(`File: ${file.name}`);
      // Do something with the file.
    });
  });
};

if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  handleLaunchFiles();
}

// This is the drag and drop zone.
const elem = document.querySelector('main');
// Prevent navigation.
elem.addEventListener('dragover', (e) => {
  e.preventDefault();
});
// Visually highlight the drop zone.
elem.addEventListener('dragenter', (e) => {
  elem.style.outline = 'solid red 1px';
});
// Visually unhighlight the drop zone.
elem.addEventListener('dragleave', (e) => {
  elem.style.outline = '';
});
// This is where the drop is handled.
elem.addEventListener('drop', async (e) => {
  // Prevent navigation.
  e.preventDefault();
  // Unhighlight the drop zone.
  elem.style.outline = '';
  // Prepare an array of promises…
  const fileHandlesPromises = [...e.dataTransfer.items]
    // …by including only files (where file misleadingly means actual file _or_
    // directory)…
    .filter((item) => item.kind === 'file')
    // …and, depending on previous feature detection…
    .map((item) => item.getAsFile());
  // Loop over the array of promises.
  for await (const handle of fileHandlesPromises) {
    // This is where we can actually exclusively act on the files.
    if (handle.isFile) {
      console.log(`File: ${handle.name}`);
      // Do something with the file.
    }
  }
});

Demo #

How to receive shared files

2022-10-10T00:00:00Z

The modern way #

First, declare a share_target in your web app manifest that lists an action (your URL that handles shared files), a method ("POST" for files) and an enctype ("multipart/form-data" for files) and a params object that contains a files property with an array of objects with a name and accept property that list the sharable file types and the name to obtain them.

{
  "share_target": {
    "action": "/receive-files/",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": {
      "files": [
        {
          "name": "image",
          "accept": ["image/jpeg", "image/png", "image/webp", "image/gif"]
        }
      ]
    }
  }
}

You then need to handle incoming POST requests in the service worker. The file is temporarily stored in a media cache, so it can be consumed in the client. This can be done by redirecting the app to a URL with a special marker query parameter like share-target.

self.addEventListener('fetch', (fetchEvent) => {
  if (fetchEvent.request.url.endsWith('/receive-files/') && fetchEvent.request.method === 'POST') {
    return fetchEvent.respondWith(
      (async () => {
        const formData = await fetchEvent.request.formData();
        const image = formData.get('image');
        const keys = await caches.keys();
        const mediaCache = await caches.open(keys.filter((key) => key.startsWith('media'))[0]);
        await mediaCache.put('shared-image', new Response(image));
        return Response.redirect('./?share-target', 303);
      })(),
    );
  }
});

Finally, you need to consume the file in the client.

window.addEventListener('load', async () => {
  if (location.search.includes('share-target')) {
    const keys = await caches.keys();
    const mediaCache = await caches.open(
      keys.filter((key) => key.startsWith('media'))[0],
    );
    const image = await mediaCache.match('shared-image');
    if (image) {
      const blob = await image.blob();
      await mediaCache.delete('shared-image');
      // Handle the shared file somehow.
    }
  }
});

Browser support

Chrome 89, Supported 89
Firefox, Not supported
Edge 89, Supported 89
Safari, Not supported

Source

Demo #

How to share files

2022-10-10T00:00:00Z

The modern way #

Using the Web Share API's `share()` method #

To share files, call navigator.share(). Note that you should always check if files can be shared with navigator.canShare() and make sure your site is using HTTPS before calling the share() method.

// Assume `blob` is a PNG image file.
const data = {
  files: [
    new File([blob], 'image.png', {
      type: blob.type,
    }),
  ],
  title: 'My title',
  text: 'My text',
};
if (navigator.canShare(data)) {
  await navigator.share(data);
}

Browser support

Chrome 89, Supported 89
Firefox 71, Behind a flag
Edge 93, Supported 93
Safari 12.1, Supported 12.1

Source

The classic way #

The next best thing to offer to the user if the Web Share API is not supported is falling back to letting the user download the file, so they can share it manually, for example, via email or via a messenger or online social network app.

Browser support

Chrome 15, Supported 15
Firefox 20, Supported 20
Edge 13, Supported 13
Safari 10.1, Supported 10.1

Source

Progressive enhancement #

The method below uses the Web Share API when the browser supports it and when the data can be shared based on the supported file types. Else, it falls back to downloading the file.

const button = document.querySelector('button');
const img =  document.querySelector('img');

// Feature detection
const webShareSupported = 'canShare' in navigator;
// Update the button action text.
button.textContent = webShareSupported ? 'Share' : 'Download';

const shareOrDownload = async (blob, fileName, title, text) => {
  // Using the Web Share API.
  if (webShareSupported) {
    const data = {
      files: [
        new File([blob], fileName, {
          type: blob.type,
        }),
      ],
      title,
      text,
    };
    if (navigator.canShare(data)) {
      try {
        await navigator.share(data);
      } catch (err) {
        if (err.name !== 'AbortError') {
          console.error(err.name, err.message);
        }
      } finally {
        return;
      }
    }
  }
  // Fallback implementation.
  const a = document.createElement('a');
  a.download = fileName;
  a.style.display = 'none';
  a.href = URL.createObjectURL(blob);
  a.addEventListener('click', () => {
    setTimeout(() => {
      URL.revokeObjectURL(a.href);
      a.remove();
    }, 1000)
  });
  document.body.append(a);
  a.click();
};

button.addEventListener('click', async () => {
  const blob = await fetch(img.src).then(res => res.blob());
  await shareOrDownload(blob, 'cat.png', 'Cat in the snow', 'Getting cold feet…');
});

Palances Liao on web.dev

How to use multiple screens

The modern way #

Using `window.getScreenDetails()` #

The classic way #

Using the window.screen method #

Progressive enhancement #

Further reading #

Demo #

How to handle files opened from the file explorer

The modern way #

Using the File Handling API #

The classic way #

Using the classic `DataTransferItem.getAsFile()` method #

Progressive enhancement #

Further reading #

Demo #

How to receive shared files

The modern way #

Further reading #

Demo #

How to share files

The modern way #

The classic way #

Progressive enhancement #

Further reading #

Demo #

Palances Liao on web.dev

How to use multiple screens

The modern way #

Using window.getScreenDetails() #

The classic way #

Using the window.screen method #

Progressive enhancement #

Further reading #

Demo #

How to handle files opened from the file explorer

The modern way #

Using the File Handling API #

The classic way #

Using the classic DataTransferItem.getAsFile() method #

Progressive enhancement #

Further reading #

Demo #

How to receive shared files

The modern way #

Using the Web Share Target API #

Further reading #

Demo #

How to share files

The modern way #

Using the Web Share API's share() method #

The classic way #

Progressive enhancement #

Further reading #

Demo #

Using `window.getScreenDetails()` #

Using the classic `DataTransferItem.getAsFile()` method #

Using the Web Share API's `share()` method #