Mengelola beberapa tampilan dengan Window Management API

Dapatkan informasi tentang layar yang terhubung dan posisi jendela yang relatif terhadap layar tersebut.

Thomas Steiner

Berhasil: Window Management API adalah bagian dari project kapabilitas dan kini tersedia dari Chrome 100.

API Pengelolaan Jendela

Window Management API memungkinkan Anda menghitung tampilan yang terhubung ke komputer Anda dan untuk menempatkan jendela pada layar tertentu.

Catatan: Window Management API berbeda dengan yang diusulkan Properti Segmen Area Pandang, yang berkaitan dengan representasi region jendela yang berada di layar (berdekatan), misalnya, di 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 tersedia Gimp dapat menempatkan berbagai alat pengeditan di jendela yang diposisikan secara akurat.
• Bagian perdagangan virtual dapat menunjukkan tren pasar di banyak jendela yang dapat dilihat di 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 teruji waktu untuk mengontrol jendela, Sayangnya, Window.open() mengetahui adanya layar tambahan. Meskipun beberapa aspek API ini tampak agak kuno, seperti windowFeatures DOMString, tetap membantu kami dengan baik selama bertahun-tahun. Untuk menentukan position, Anda dapat meneruskan koordinat left dan top (atau screenX dan screenY masing-masing) dan teruskan ukuran sebagai width dan height (atau innerWidth dan innerHeight). Misalnya, untuk membuka Jendela 400×300 pada jarak 50 piksel dari kiri dan 50 piksel dari atas, ini adalah kode yang dapat menggunakan:

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 window.screen, yang menampilkan objek Screen. Ini adalah output 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 menyesuaikan diri dengan realitas kerja yang baru dan mempersiapkan ruang kerja di rumah pribadi. Catatan saya tampak seperti di foto di bawah ini (jika tertarik, Anda dapat membaca detail selengkapnya tentang konfigurasi saya). iPad di samping MacBook saya terhubung ke laptop melalui Sidecar, jadi kapan pun saya membutuhkannya, saya bisa dengan cepat mengubah iPad ke layar kedua.

Penyiapan multilayar.

Jika saya ingin memanfaatkan layar yang lebih besar, saya bisa meletakkan {i>popup<i} dari contoh kode di atas ke layar kedua. Saya melakukannya seperti ini:

popup.moveTo(2500, 50);

Ini adalah perkiraan kasar, karena tidak ada cara untuk mengetahui dimensi layar kedua. Info dari window.screen hanya mencakup layar bawaan, tetapi tidak layar iPad. width yang dilaporkan layar bawaan adalah 1680 piksel, jadi berpindah ke 2500 piksel mungkin berupaya menggeser ke iPad, karena saya kebetulan tahu bahwa letaknya di sebelah kanan MacBook saya. Cara dapatkah saya melakukan ini dalam kasus 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 yang 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 ini:

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

Saat 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 pada saat pertama kali mencoba menggunakan salah satu metode API baru. Baca terus untuk mempelajari lebih lanjut.

Properti window.screen.isExtended

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

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

Metode getScreenDetails()

Sekarang, setelah saya tahu bahwa pengaturan saat ini adalah multilayar, saya bisa mendapatkan informasi lebih lanjut tentang layar kedua menggunakan Window.getScreenDetails(). Memanggil fungsi ini akan menampilkan dialog izin akses yang bertanya apakah situs dapat terbuka dan menempatkan jendela di layar saya. Fungsi ini menampilkan promise yang di-resolve dengan objek ScreenDetailed. Pada MacBook Pro 13 saya dengan iPad yang tersambung, 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 dalam array screens. Perhatikan bagaimana nilai left untuk iPad dimulai pada 1680, yang persis dengan width dari layar bawaan. Ini memungkinkan saya untuk menentukan dengan tepat bagaimana layar-layar disusun secara logis (berdekatan, di atas satu sama lain, dll.). Kini ada juga data untuk setiap layar guna menunjukkan apakah layar tersebut adalah isInternal dan apakah permintaan itu isPrimary. Perhatikan bahwa layar bawaan belum tentu merupakan layar utama.

Kolom currentScreen adalah objek aktif yang sesuai dengan window.screen saat ini. Objek diperbarui 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 ketika pengaturan layar saya berubah. Peristiwa baru, screenschange, melakukan hal itu: menyala setiap kali konstelasi layar diubah. (Pemberitahuan bahwa "layar" adalah jamak dalam nama peristiwa.) Ini berarti peristiwa aktif 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 melihat detail layar, gunakan objek aktif dari cache Antarmuka Screens.

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 aktif 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 saya hanya tertarik pada perubahan pada layar konkret, saya bisa mendengarkan Peristiwa change.

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 alamat requestFullScreen() . Metode ini mengambil parameter options tempat Anda dapat meneruskan FullscreenOptions. Sejauh ini, satu-satunya propertinya telah navigationUI Window Management API menambahkan properti screen baru yang memungkinkan Anda menentukan di layar mana untuk memulai tampilan layar penuh. Misalnya, jika Anda ingin membuat layar utama 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);
}

Polyfill

Tidak mungkin mem-polyfill Window Management API, tetapi Anda dapat melakukan shim pada 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 API, yaitu berbagai peristiwa perubahan layar dan properti screen dari FullscreenOptions, tidak akan pernah diaktifkan atau diabaikan secara diam-diam oleh browser yang tidak mendukung.

Demo

Jika Anda seperti saya, Anda harus memperhatikan perkembangan berbagai jenis mata uang kripto. (Kenyataannya, saya tidak benar-benar menyukai planet ini, tetapi demi artikel ini, anggap saja bahwa saya did.) Untuk melacak mata uang kripto yang saya miliki, saya telah mengembangkan aplikasi web yang memungkinkan saya untuk melihat pasar dalam segala situasi kehidupan, seperti dari tempat tidur yang nyaman, di mana saya memiliki pengaturan satu layar.

Bersantai dan mengamati pasar.

Tentang kripto ini, pasar bisa menjadi ramai kapan saja. Jika ini terjadi, saya bisa cepat ke meja kerja di mana saya memiliki pengaturan multilayar. Saya bisa mengklik jendela mata uang apa pun dan melihat detail lengkapnya dengan cepat dalam tampilan layar penuh di layar yang berlawanan. Di bawah ini adalah foto terbaru dari yang saya ambil selama pertumpahan darah YCY terakhir. Video menangkap benar-benar lengah dan meninggalkan saya dengan tangan di atas wajah.

Panicky, menyaksikan pertumpahan darah YCY.

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

Keamanan dan izin

Tim Chrome telah merancang dan mengimplementasikan Window Management API menggunakan 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, meningkatkan permukaan pelacakan sidik jari pengguna, terutama mereka yang memiliki beberapa layar yang terhubung secara konsisten ke perangkat mereka. Sebagai satu mitigasi masalah privasi ini, properti layar terekspos dibatasi hingga batas minimum untuk kasus penggunaan penempatan umum. Izin pengguna diperlukan agar situs mendapatkan multilayar informasi dan menempatkan jendela di layar lain. Sementara Chromium menampilkan label layar yang mendetail, browser bebas untuk menampilkan label yang kurang deskriptif (atau bahkan label kosong).

Kontrol pengguna

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

Kontrol perusahaan

Pengguna Chrome Enterprise dapat mengontrol beberapa aspek Window Management API sebagai diuraikan di bagian yang relevan dalam Grup Kebijakan Atom setelan.

Transparansi

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

Persistensi izin

Browser tetap memberikan izin. Izin dapat dicabut melalui situs browser tidak akurat atau tidak sesuai.

Masukan

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

Beri tahu kami tentang desain API

Apakah ada sesuatu terkait API yang tidak berfungsi seperti yang Anda harapkan? Atau apakah ada metode yang hilang yang dibutuhkan untuk menerapkan ide Anda? Memiliki pertanyaan atau komentar tentang keamanan model?

• Ajukan masalah spesifikasi di repo GitHub yang sesuai, atau tambahkan pendapat Anda ke masalah performa.

Laporkan masalah terkait penerapan

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

• Laporkan bug di new.crbug.com. Pastikan untuk menyertakan detail sebanyak yang Anda dapat, petunjuk sederhana untuk reproduksi, dan masukkan Blink>Screen>MultiScreen di Kotak Komponen. Glitch sangat cocok untuk membagikan repro dengan cepat dan mudah.

Menunjukkan dukungan untuk API

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

• Bagikan rencana Anda untuk menggunakannya di thread Discourse WICG.
• Kirim tweet ke @ChromiumDev menggunakan hashtag #WindowManagement dan beri tahu kami di mana dan bagaimana Anda menggunakannya.
• Minta vendor browser lain untuk menerapkan API.

Link bermanfaat

• Draf spesifikasi
• Penjelasan untuk publik
• Demo Window Management API | Demo Window Management API sumber
• Bug pelacakan Chromium
• Entri ChromeStatus.com
• Komponen Kedipan: Blink>Screen>MultiScreen
• Peninjauan TAG
• Niat untuk Bereksperimen

Ucapan terima kasih

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