Mengelola beberapa tampilan dengan Window Management API

Dapatkan informasi tentang layar yang terhubung dan memosisikan jendela yang terkait dengan layar tersebut.

Thomas Steiner

Berhasil: Window Management API adalah bagian dari project kemampuan dan sekarang tersedia dari Chrome 100.

API Pengelolaan Jendela

Dengan Window Management API, Anda dapat menghitung tampilan yang terhubung ke mesin dan menempatkan jendela di layar tertentu.

Catatan: Window Management API berbeda dengan Properti Segmen Viewport yang diusulkan, yang berkaitan dengan representasi area jendela yang berada di layar terpisah (berdekatan), misalnya, pada perangkat foldable.

Catatan: Window Management API sebelumnya dikenal sebagai Multi-Screen Window Placement API.

Kasus penggunaan yang disarankan

Contoh situs yang dapat menggunakan API ini antara lain:

• Editor grafis multi-aplikasi à la Gimp dapat menempatkan berbagai alat pengeditan di jendela yang diposisikan secara akurat.
• Desktop perdagangan virtual dapat menampilkan tren pasar di beberapa periode yang dapat dilihat dalam mode layar penuh.
• Aplikasi slideshow dapat menampilkan catatan pembicara di layar utama internal dan presentasi di proyektor eksternal.

Cara menggunakan Window Management API

Permasalahan

Pendekatan yang telah teruji oleh waktu untuk mengontrol jendela, Window.open(), sayangnya tidak mengetahui layar tambahan. Meskipun beberapa aspek API ini tampak sedikit kuno, seperti parameter DOMString windowFeatures, API ini memberikan manfaat yang baik bagi kami selama bertahun-tahun. Untuk menentukan posisi jendela, Anda dapat meneruskan koordinat sebagai left dan top (atau screenX dan screenY) serta meneruskan ukuran yang diinginkan sebagai width dan height (atau masing-masing innerWidth dan innerHeight). Misalnya, untuk membuka jendela 400×300 pada 50 piksel dari kiri dan 50 piksel dari atas, ini adalah kode yang dapat Anda gunakan:

const popup = window.open(
  'https://example.com/',
  'My Popup',
  'left=50,top=50,width=400,height=300',
);

Anda bisa mendapatkan informasi tentang layar saat ini dengan melihat properti window.screen, yang menampilkan objek Screen. Ini adalah {i>output<i} di MacBook Pro 13" saya:

window.screen;
/* Output from my MacBook Pro 13″:
  availHeight: 969
  availLeft: 0
  availTop: 25
  availWidth: 1680
  colorDepth: 30
  height: 1050
  isExtended: true
  onchange: null
  orientation: ScreenOrientation {angle: 0, type: "landscape-primary", onchange: null}
  pixelDepth: 30
  width: 1680
*/

Seperti kebanyakan orang yang bekerja di bidang teknologi, saya harus beradaptasi dengan realitas kerja baru dan menyiapkan kantor di rumah pribadi saya. Nama saya terlihat seperti di foto di bawah ini (jika tertarik, Anda dapat membaca detail lengkap tentang konfigurasi saya). iPad di samping MacBook saya terhubung ke laptop melalui Sidecar, jadi kapan pun saya perlukan, saya dapat dengan cepat mengubah iPad menjadi layar kedua.

Penyiapan multilayar.

Jika ingin memanfaatkan layar yang lebih besar, saya bisa menempatkan pop-up dari contoh kode di atas ke layar kedua. Saya melakukannya seperti ini:

popup.moveTo(2500, 50);

Ini hanya tebakan, karena tidak ada cara untuk mengetahui dimensi layar kedua. Info dari window.screen hanya mencakup layar bawaan, tetapi tidak mencakup layar iPad. width layar bawaan yang dilaporkan adalah 1680 piksel, jadi berpindah ke 2500 piksel mungkin berhasil menggeser jendela ke iPad, karena I kebetulan mengetahui bahwa jendela ini terletak di sebelah kanan MacBook saya. Bagaimana cara melakukan ini secara umum? Ternyata, ada cara yang lebih baik daripada menebak-nebak. Cara tersebut adalah Window Management API.

Deteksi fitur

Untuk memeriksa apakah Window Management API didukung, gunakan:

if ('getScreenDetails' in window) {
  // The Window Management API is supported.
}

Izin window-management

Catatan: Nama izin window-placement lama tidak lagi didukung.

Sebelum dapat menggunakan Window Management API, saya harus meminta izin dari pengguna untuk melakukannya. Izin window-management dapat dikueri dengan Permissions API seperti:

let granted = false;
try {
  const { state } = await navigator.permissions.query({ name: 'window-management' });
  granted = state === 'granted';
} catch {
  // Nothing.
}

Meskipun browser dengan nama izin lama dan baru digunakan, pastikan untuk menggunakan kode defensif saat meminta izin, seperti dalam contoh di bawah.

async function getWindowManagementPermissionState() {
  let state;
  // The new permission name.
  try {
    ({ state } = await navigator.permissions.query({
      name: "window-management",
    }));
  } catch (err) {
    return `${err.name}: ${err.message}`;
  }
  return state;
}

document.querySelector("button").addEventListener("click", async () => {
  const state = await getWindowManagementPermissionState();
  document.querySelector("pre").textContent = state;
});

Browser dapat memilih untuk menampilkan permintaan izin secara dinamis saat mencoba pertama kali menggunakan salah satu metode dari API baru. Baca terus untuk mempelajari lebih lanjut.

Properti window.screen.isExtended

Untuk mengetahui apakah lebih dari satu layar terhubung ke perangkat saya, saya mengakses properti window.screen.isExtended. Metode akan menampilkan true atau false. Untuk penyiapan saya, metode ini menampilkan true.

window.screen.isExtended;
// Returns `true` or `false`.

Metode getScreenDetails()

Setelah mengetahui bahwa penyiapan saat ini adalah multilayar, saya bisa mendapatkan informasi selengkapnya tentang layar kedua menggunakan Window.getScreenDetails(). Memanggil fungsi ini akan menampilkan prompt izin bertanya apakah situs dapat membuka dan menempatkan jendela di layar. Fungsi ini menampilkan promise yang di-resolve dengan objek ScreenDetailed. Di MacBook Pro 13 dengan iPad yang terhubung, ini mencakup kolom screens dengan dua objek ScreenDetailed:

await window.getScreenDetails();
/* Output from my MacBook Pro 13″ with the iPad attached:
{
  currentScreen: ScreenDetailed {left: 0, top: 0, isPrimary: true, isInternal: true, devicePixelRatio: 2, …}
  oncurrentscreenchange: null
  onscreenschange: null
  screens: [{
    // The MacBook Pro
    availHeight: 969
    availLeft: 0
    availTop: 25
    availWidth: 1680
    colorDepth: 30
    devicePixelRatio: 2
    height: 1050
    isExtended: true
    isInternal: true
    isPrimary: true
    label: "Built-in Retina Display"
    left: 0
    onchange: null
    orientation: ScreenOrientation {angle: 0, type: "landscape-primary", onchange: null}
    pixelDepth: 30
    top: 0
    width: 1680
  },
  {
    // The iPad
    availHeight: 999
    availLeft: 1680
    availTop: 25
    availWidth: 1366
    colorDepth: 24
    devicePixelRatio: 2
    height: 1024
    isExtended: true
    isInternal: false
    isPrimary: false
    label: "Sidecar Display (AirPlay)"
    left: 1680
    onchange: null
    orientation: ScreenOrientation {angle: 0, type: "landscape-primary", onchange: null}
    pixelDepth: 24
    top: 0
    width: 1366
  }]
}
*/

Informasi tentang layar yang terhubung tersedia di array screens. Perhatikan bagaimana nilai left untuk iPad dimulai pada 1680, yang merupakan width dari layar bawaan. Hal ini memungkinkan saya menentukan dengan tepat bagaimana layar disusun secara logis (di samping satu sama lain, di atas satu sama lain, dll.). Kini terdapat data untuk setiap layar guna menunjukkan apakah layar yang digunakan isInternal dan apakah layar tersebut isPrimary. Perhatikan bahwa layar bawaan belum tentu merupakan layar utama.

Kolom currentScreen adalah objek aktif yang sesuai dengan window.screen saat ini. Objek ini diupdate pada penempatan jendela lintas-layar atau perubahan perangkat.

Catatan: Implementasi API terbaru Chromium menampilkan label layar yang disediakan oleh platform pokok, seperti "Built-in Retina Display", bukan placeholder yang kurang deskriptif, seperti "Internal Display 1".

Peristiwa screenschange

Satu-satunya hal yang hilang sekarang adalah cara untuk mendeteksi kapan pengaturan layar saya berubah. Peristiwa baru, screenschange, melakukan hal tersebut: peristiwa tersebut diaktifkan setiap kali konstelasi layar diubah. (Perhatikan bahwa "screens" adalah bentuk jamak dalam nama peristiwa.) Ini berarti peristiwa diaktifkan setiap kali layar baru atau layar yang ada (secara fisik atau virtual dalam kasus Sidecar) dicolokkan atau dicabut.

Perhatikan bahwa Anda perlu mencari detail layar baru secara asinkron, peristiwa screenschange sendiri tidak menyediakan data ini. Untuk mencari detail layar, gunakan objek live dari antarmuka Screens yang di-cache.

const screenDetails = await window.getScreenDetails();
let cachedScreensLength = screenDetails.screens.length;
screenDetails.addEventListener('screenschange', (event) => {
  if (screenDetails.screens.length !== cachedScreensLength) {
    console.log(
      `The screen count changed from ${cachedScreensLength} to ${screenDetails.screens.length}`,
    );
    cachedScreensLength = screenDetails.screens.length;
  }
});

Peristiwa currentscreenchange

Jika saya hanya tertarik dengan perubahan pada layar saat ini (yaitu, nilai objek live currentScreen), saya dapat memproses peristiwa currentscreenchange.

const screenDetails = await window.getScreenDetails();
screenDetails.addEventListener('currentscreenchange', async (event) => {
  const details = screenDetails.currentScreen;
  console.log('The current screen has changed.', event, details);
});

Peristiwa change

Terakhir, jika hanya tertarik untuk mengubah layar konkret, saya dapat memproses peristiwa change layar tersebut.

const firstScreen = (await window.getScreenDetails())[0];
firstScreen.addEventListener('change', async (event) => {
  console.log('The first screen has changed.', event, firstScreen);
});

Opsi layar penuh baru

Hingga saat ini, Anda dapat meminta agar elemen ditampilkan dalam mode layar penuh melalui metode requestFullScreen() yang bernama tepat. Metode ini mengambil parameter options tempat Anda dapat meneruskan FullscreenOptions. Sejauh ini, satu-satunya propertinya adalah navigationUI. Window Management API menambahkan properti screen baru yang memungkinkan Anda menentukan layar mana yang akan digunakan untuk memulai tampilan layar penuh. Misalnya, jika Anda ingin membuat layar utama menjadi layar penuh:

try {
  const primaryScreen = (await getScreenDetails()).screens.filter((screen) => screen.isPrimary)[0];
  await document.body.requestFullscreen({ screen: primaryScreen });
} catch (err) {
  console.error(err.name, err.message);
}

Isi Ulang

Anda tidak dapat mem-polyfill Window Management API, tetapi Anda dapat meng-shim bentuknya sehingga Anda dapat membuat kode secara eksklusif terhadap API baru:

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;
}

Aspek lain dari API, yaitu berbagai peristiwa perubahan layar dan properti screen dari FullscreenOptions, tidak akan pernah diaktifkan atau secara diam-diam diabaikan oleh browser yang tidak didukung.

Demo

Jika Anda seperti saya, terus pantau perkembangan berbagai mata uang kripto. (Kenyataannya, saya sangat tidak menyukainya karena saya menyukai planet ini, tetapi, untuk alasan artikel ini, anggap saja saya telah melakukannya.) Untuk memantau mata uang kripto yang saya miliki, saya telah mengembangkan aplikasi web yang memungkinkan saya menonton pasar dalam segala situasi kehidupan, seperti dari tempat tidur saya, tempat saya memiliki konfigurasi satu layar yang memadai.

Bersantai dan menonton pasar.

Hal ini berkaitan dengan kripto, pasar bisa sangat sibuk kapan saja. Jika ini terjadi, saya bisa dengan cepat pindah ke meja saya di mana saya memiliki pengaturan multi-layar. Saya dapat mengklik jendela mata uang apa pun dan dengan cepat melihat detail lengkap dalam tampilan layar penuh di layar berlawanan. Di bawah ini adalah foto terbaru saya yang diambil saat pertumpahan darah YCY terakhir. Hal itu membuat saya benar-benar lengah dan meninggalkan saya dengan tangan di wajah.

Panicky, menyaksikan pertumpahan darah YCY.

Anda dapat mencoba-coba demo yang disematkan di bawah ini, atau melihat kode sumbernya di glitch.

Keamanan dan izin

Tim Chrome telah merancang dan menerapkan Window Management API menggunakan prinsip inti yang ditentukan dalam Mengontrol Akses ke Fitur Platform Web yang Canggih, termasuk kontrol pengguna, transparansi, dan ergonomi. Window Management API mengekspos informasi baru tentang layar yang terhubung ke perangkat, sehingga meningkatkan permukaan pelacakan sidik jari pengguna, terutama mereka yang memiliki beberapa layar yang terhubung secara konsisten ke perangkat. Sebagai salah satu mitigasi masalah privasi ini, properti layar yang terekspos dibatasi ke jumlah minimum yang diperlukan untuk kasus penggunaan penempatan umum. Izin pengguna diperlukan agar situs mendapatkan informasi multilayar dan menempatkan jendela di layar lain. Meskipun Chromium menampilkan label layar yang mendetail, browser bebas menampilkan yang kurang deskriptif (atau bahkan label kosong).

Kontrol pengguna

Pengguna memiliki kontrol penuh atas eksposur penyiapannya. Mereka dapat menerima atau menolak permintaan izin, dan mencabut izin yang sebelumnya diberikan melalui fitur informasi situs di browser.

Kontrol perusahaan

Pengguna Chrome Enterprise dapat mengontrol beberapa aspek Window Management API seperti yang diuraikan di bagian yang relevan dalam setelan Atomic Policy Groups.

Transparansi

Fakta apakah izin untuk menggunakan Window Management API telah diberikan ditampilkan dalam informasi situs browser dan juga dapat dikueri melalui Permissions API.

Persistensi izin

Browser tetap memberikan izin. Izin dapat dicabut melalui informasi situs browser.

Masukan

Tim Chrome ingin mengetahui pengalaman Anda saat menggunakan Window Management API.

Beri tahu kami tentang desain API

Apakah ada sesuatu pada API yang tidak berfungsi seperti yang Anda harapkan? Atau apakah ada metode atau properti yang hilang yang Anda butuhkan untuk menerapkan ide Anda? Punya pertanyaan atau komentar tentang model keamanan?

• Laporkan masalah spesifikasi di repo GitHub yang sesuai, atau tambahkan pendapat Anda ke masalah yang sudah ada.

Melaporkan masalah terkait penerapan

Apakah Anda menemukan bug pada implementasi Chrome? Atau apakah implementasinya berbeda dari spesifikasi?

• Laporkan bug di new.crbug.com. Pastikan Anda menyertakan detail sebanyak mungkin, petunjuk sederhana untuk mereproduksi, dan masukkan Blink>Screen>MultiScreen di kotak Components. Glitch berfungsi dengan baik untuk berbagi repro yang cepat dan mudah.

Menunjukkan dukungan untuk API

Apakah Anda berencana menggunakan Window Management API? Dukungan publik Anda membantu tim Chrome memprioritaskan fitur dan menunjukkan kepada vendor browser lain betapa pentingnya mendukung mereka.

• Bagikan rencana Anda untuk menggunakannya di rangkaian pesan Discourse WiCG.
• Kirim tweet ke @ChromiumDev menggunakan hashtag #WindowManagement serta beri tahu kami di mana dan bagaimana Anda menggunakannya.
• Minta vendor browser lain untuk mengimplementasikan API.

Link bermanfaat

• Draf spesifikasi
• Penjelasan untuk umum
• Demo Window Management API | Sumber demo Window Management API
• Bug pelacakan Chromium
• Entri ChromeStatus.com
• Komponen Blink: Blink>Screen>MultiScreen
• Tinjauan TAG
• Niat untuk Bereksperimen

Ucapan terima kasih

Spesifikasi Window Management API diedit oleh Victor Costan, Joshua Bell, dan Mike Wasserman. API tersebut diterapkan oleh Mike Wasserman dan Adrienne Walker. Artikel ini ditinjau oleh Joe Medley, François Beaufort, dan Kayce Basques. Terima kasih kepada Laura Torrent Puig untuk fotonya.