20 KiB

Raw Permalink Blame History

Projek Sambungan Pelayar Bahagian 2: Panggil API, gunakan Penyimpanan Tempatan

Kuiz Pra-Kuliah

Pengenalan

Ingat sambungan pelayar yang anda mula bina? Sekarang anda mempunyai borang yang kelihatan menarik, tetapi ia masih statik. Hari ini kita akan menghidupkannya dengan menghubungkannya kepada data sebenar dan memberikannya memori.

Fikirkan tentang komputer kawalan misi Apollo - mereka tidak hanya memaparkan maklumat tetap. Mereka sentiasa berkomunikasi dengan kapal angkasa, dikemas kini dengan data telemetri, dan mengingati parameter misi kritikal. Itulah jenis tingkah laku dinamik yang kita bina hari ini. Sambungan anda akan mengakses internet, mengambil data alam sekitar sebenar, dan mengingati tetapan anda untuk masa akan datang.

Integrasi API mungkin kedengaran rumit, tetapi ia sebenarnya hanya mengajar kod anda bagaimana berkomunikasi dengan perkhidmatan lain. Sama ada anda mengambil data cuaca, suapan media sosial, atau maklumat jejak karbon seperti yang akan kita lakukan hari ini, semuanya tentang mewujudkan hubungan digital ini. Kita juga akan meneroka bagaimana pelayar boleh menyimpan maklumat - seperti perpustakaan menggunakan katalog kad untuk mengingati lokasi buku.

Pada akhir pelajaran ini, anda akan mempunyai sambungan pelayar yang mengambil data sebenar, menyimpan pilihan pengguna, dan memberikan pengalaman yang lancar. Mari kita mulakan!

✅ Ikuti segmen bernombor dalam fail yang sesuai untuk mengetahui di mana meletakkan kod anda

Sediakan elemen untuk dimanipulasi dalam sambungan

Sebelum JavaScript anda boleh memanipulasi antara muka, ia memerlukan rujukan kepada elemen HTML tertentu. Fikirkan ia seperti teleskop yang perlu diarahkan kepada bintang tertentu - sebelum Galileo dapat mengkaji bulan Jupiter, dia perlu mencari dan memfokuskan pada Jupiter itu sendiri.

Dalam fail index.js anda, kita akan mencipta pemboleh ubah const yang menangkap rujukan kepada setiap elemen borang penting. Ini serupa dengan bagaimana saintis melabelkan peralatan mereka - daripada mencari seluruh makmal setiap kali, mereka boleh mengakses apa yang mereka perlukan secara langsung.

// form fields
const form = document.querySelector('.form-data');
const region = document.querySelector('.region-name');
const apiKey = document.querySelector('.api-key');

// results
const errors = document.querySelector('.errors');
const loading = document.querySelector('.loading');
const results = document.querySelector('.result-container');
const usage = document.querySelector('.carbon-usage');
const fossilfuel = document.querySelector('.fossil-fuel');
const myregion = document.querySelector('.my-region');
const clearBtn = document.querySelector('.clear-btn');

Apa yang dilakukan oleh kod ini:

Menangkap elemen borang menggunakan document.querySelector() dengan pemilih kelas CSS
Mencipta rujukan kepada medan input untuk nama kawasan dan kunci API
Menjalin sambungan kepada elemen paparan hasil untuk data penggunaan karbon
Menyiapkan akses kepada elemen UI seperti indikator pemuatan dan mesej ralat
Menyimpan setiap rujukan elemen dalam pemboleh ubah const untuk kegunaan mudah sepanjang kod anda

Tambah pendengar acara

Sekarang kita akan membuat sambungan anda bertindak balas kepada tindakan pengguna. Pendengar acara adalah cara kod anda memantau interaksi pengguna. Fikirkan mereka seperti operator dalam pertukaran telefon awal - mereka mendengar panggilan masuk dan menyambungkan litar yang betul apabila seseorang ingin membuat sambungan.

form.addEventListener('submit', (e) => handleSubmit(e));
clearBtn.addEventListener('click', (e) => reset(e));
init();

Memahami konsep ini:

Melampirkan pendengar submit kepada borang yang dicetuskan apabila pengguna menekan Enter atau klik submit
Menyambungkan pendengar klik kepada butang kosong untuk menetapkan semula borang
Menghantar objek acara (e) kepada fungsi pengendali untuk kawalan tambahan
Memanggil fungsi init() dengan segera untuk menyediakan keadaan awal sambungan anda

✅ Perhatikan sintaks fungsi anak panah ringkas yang digunakan di sini. Pendekatan JavaScript moden ini lebih bersih daripada ekspresi fungsi tradisional, tetapi kedua-duanya berfungsi dengan baik!

Bina fungsi inisialisasi dan tetapan semula

Mari kita cipta logik inisialisasi untuk sambungan anda. Fungsi init() adalah seperti sistem navigasi kapal yang memeriksa instrumennya - ia menentukan keadaan semasa dan menyesuaikan antara muka dengan sewajarnya. Ia memeriksa sama ada seseorang telah menggunakan sambungan anda sebelum ini dan memuatkan tetapan mereka yang terdahulu.

Fungsi reset() memberikan pengguna permulaan baru - serupa dengan bagaimana saintis menetapkan semula instrumen mereka antara eksperimen untuk memastikan data bersih.

function init() {
	// Check if user has previously saved API credentials
	const storedApiKey = localStorage.getItem('apiKey');
	const storedRegion = localStorage.getItem('regionName');

	// Set extension icon to generic green (placeholder for future lesson)
	// TODO: Implement icon update in next lesson

	if (storedApiKey === null || storedRegion === null) {
		// First-time user: show the setup form
		form.style.display = 'block';
		results.style.display = 'none';
		loading.style.display = 'none';
		clearBtn.style.display = 'none';
		errors.textContent = '';
	} else {
		// Returning user: load their saved data automatically
		displayCarbonUsage(storedApiKey, storedRegion);
		results.style.display = 'none';
		form.style.display = 'none';
		clearBtn.style.display = 'block';
	}
}

function reset(e) {
	e.preventDefault();
	// Clear stored region to allow user to choose a new location
	localStorage.removeItem('regionName');
	// Restart the initialization process
	init();
}

Memecahkan apa yang berlaku di sini:

Mengambil kunci API dan kawasan yang disimpan dari penyimpanan tempatan pelayar
Memeriksa sama ada ini adalah pengguna kali pertama (tiada kelayakan yang disimpan) atau pengguna yang kembali
Menunjukkan borang persediaan untuk pengguna baru dan menyembunyikan elemen antara muka lain
Memuatkan data yang disimpan secara automatik untuk pengguna yang kembali dan memaparkan pilihan tetapan semula
Menguruskan keadaan antara muka pengguna berdasarkan data yang tersedia

Konsep utama tentang Penyimpanan Tempatan:

Menyimpan data antara sesi pelayar (tidak seperti penyimpanan sesi)
Menyimpan data sebagai pasangan kunci-nilai menggunakan getItem() dan setItem()
Mengembalikan null apabila tiada data wujud untuk kunci tertentu
Memberikan cara mudah untuk mengingati pilihan dan tetapan pengguna

💡 Memahami Penyimpanan Pelayar: LocalStorage adalah seperti memberikan sambungan anda memori yang berterusan. Fikirkan bagaimana Perpustakaan Alexandria kuno menyimpan gulungan - maklumat tetap tersedia walaupun apabila sarjana meninggalkan dan kembali.

Ciri utama:

Menyimpan data walaupun selepas anda menutup pelayar anda

Bertahan selepas komputer dihidupkan semula dan pelayar terhempas

Memberikan ruang penyimpanan yang besar untuk pilihan pengguna

Menyediakan akses segera tanpa kelewatan rangkaian

Nota Penting: Sambungan pelayar anda mempunyai penyimpanan tempatan yang terpencil yang berasingan daripada halaman web biasa. Ini memberikan keselamatan dan mengelakkan konflik dengan laman web lain.

Anda boleh melihat data yang disimpan dengan membuka Alat Pembangun pelayar (F12), pergi ke tab Application, dan mengembangkan bahagian Local Storage.

⚠️ Pertimbangan Keselamatan: Dalam aplikasi pengeluaran, menyimpan kunci API dalam LocalStorage menimbulkan risiko keselamatan kerana JavaScript boleh mengakses data ini. Untuk tujuan pembelajaran, pendekatan ini berfungsi dengan baik, tetapi aplikasi sebenar harus menggunakan penyimpanan pelayan yang selamat untuk kelayakan sensitif.

Tangani penghantaran borang

Sekarang kita akan menangani apa yang berlaku apabila seseorang menghantar borang anda. Secara lalai, pelayar akan memuat semula halaman apabila borang dihantar, tetapi kita akan memintas tingkah laku ini untuk mencipta pengalaman yang lebih lancar.

Pendekatan ini mencerminkan bagaimana kawalan misi menangani komunikasi kapal angkasa - bukannya menetapkan semula keseluruhan sistem untuk setiap penghantaran, mereka mengekalkan operasi berterusan sambil memproses maklumat baru.

Cipta fungsi yang menangkap acara penghantaran borang dan mengekstrak input pengguna:

function handleSubmit(e) {
	e.preventDefault();
	setUpUser(apiKey.value, region.value);
}

Dalam kod di atas, kita telah:

Menghalang tingkah laku penghantaran borang lalai yang akan menyegarkan halaman
Mengekstrak nilai input pengguna dari medan kunci API dan kawasan
Menghantar data borang kepada fungsi setUpUser() untuk diproses
Menjaga tingkah laku aplikasi satu halaman dengan mengelakkan penyegaran halaman

✅ Ingat bahawa medan borang HTML anda termasuk atribut required, jadi pelayar secara automatik mengesahkan bahawa pengguna memberikan kedua-dua kunci API dan kawasan sebelum fungsi ini dijalankan.

Tetapkan pilihan pengguna

Fungsi setUpUser bertanggungjawab untuk menyimpan kelayakan pengguna dan memulakan panggilan API pertama. Ini mencipta peralihan yang lancar dari persediaan kepada paparan hasil.

function setUpUser(apiKey, regionName) {
	// Save user credentials for future sessions
	localStorage.setItem('apiKey', apiKey);
	localStorage.setItem('regionName', regionName);
	
	// Update UI to show loading state
	loading.style.display = 'block';
	errors.textContent = '';
	clearBtn.style.display = 'block';
	
	// Fetch carbon usage data with user's credentials
	displayCarbonUsage(apiKey, regionName);
}

Langkah demi langkah, inilah yang berlaku:

Menyimpan kunci API dan nama kawasan ke penyimpanan tempatan untuk kegunaan masa depan
Menunjukkan indikator pemuatan untuk memberitahu pengguna bahawa data sedang diambil
Mengosongkan mesej ralat sebelumnya dari paparan
Menampilkan butang kosong untuk pengguna menetapkan semula tetapan mereka kemudian
Memulakan panggilan API untuk mengambil data penggunaan karbon sebenar

Fungsi ini mencipta pengalaman pengguna yang lancar dengan menguruskan kedua-dua penyimpanan data dan kemas kini antara muka pengguna dalam satu tindakan yang terkoordinasi.

Paparkan data penggunaan karbon

Sekarang kita akan menyambungkan sambungan anda kepada sumber data luaran melalui API. Ini mengubah sambungan anda daripada alat yang berdiri sendiri kepada sesuatu yang boleh mengakses maklumat masa nyata dari seluruh internet.

Memahami API

API adalah bagaimana aplikasi yang berbeza berkomunikasi antara satu sama lain. Fikirkan mereka seperti sistem telegraf yang menghubungkan bandar-bandar jauh pada abad ke-19 - operator akan menghantar permintaan kepada stesen jauh dan menerima respons dengan maklumat yang diminta. Setiap kali anda memeriksa media sosial, bertanya kepada pembantu suara soalan, atau menggunakan aplikasi penghantaran, API memudahkan pertukaran data ini.

Konsep utama tentang REST API:

REST bermaksud 'Representational State Transfer'
Menggunakan kaedah HTTP standard (GET, POST, PUT, DELETE) untuk berinteraksi dengan data
Mengembalikan data dalam format yang boleh diramal, biasanya JSON
Menyediakan titik akhir berasaskan URL yang konsisten untuk jenis permintaan yang berbeza

✅ API CO2 Signal yang akan kita gunakan menyediakan data intensiti karbon masa nyata dari grid elektrik di seluruh dunia. Ini membantu pengguna memahami kesan alam sekitar penggunaan elektrik mereka!

💡 Memahami JavaScript Asinkron: Kata kunci async membolehkan kod anda mengendalikan pelbagai operasi secara serentak. Apabila anda meminta data dari pelayan, anda tidak mahu keseluruhan sambungan anda membeku - itu seperti kawalan lalu lintas udara menghentikan semua operasi semasa menunggu satu pesawat untuk bertindak balas.

Manfaat utama:

Menjaga responsif sambungan semasa data dimuatkan

Membolehkan kod lain terus dilaksanakan semasa permintaan rangkaian

Meningkatkan kebolehbacaan kod berbanding corak panggilan balik tradisional

Membolehkan pengendalian ralat yang anggun untuk masalah rangkaian

Berikut adalah video ringkas tentang async:

🎥 Klik imej di atas untuk video tentang async/await.

Cipta fungsi untuk mengambil dan memaparkan data penggunaan karbon:

// Modern fetch API approach (no external dependencies needed)
async function displayCarbonUsage(apiKey, region) {
	try {
		// Fetch carbon intensity data from CO2 Signal API
		const response = await fetch('https://api.co2signal.com/v1/latest', {
			method: 'GET',
			headers: {
				'auth-token': apiKey,
				'Content-Type': 'application/json'
			},
			// Add query parameters for the specific region
			...new URLSearchParams({ countryCode: region }) && {
				url: `https://api.co2signal.com/v1/latest?countryCode=${region}`
			}
		});

		// Check if the API request was successful
		if (!response.ok) {
			throw new Error(`API request failed: ${response.status}`);
		}

		const data = await response.json();
		const carbonData = data.data;

		// Calculate rounded carbon intensity value
		const carbonIntensity = Math.round(carbonData.carbonIntensity);

		// Update the user interface with fetched data
		loading.style.display = 'none';
		form.style.display = 'none';
		myregion.textContent = region.toUpperCase();
		usage.textContent = `${carbonIntensity} grams (grams CO₂ emitted per kilowatt hour)`;
		fossilfuel.textContent = `${carbonData.fossilFuelPercentage.toFixed(2)}% (percentage of fossil fuels used to generate electricity)`;
		results.style.display = 'block';

		// TODO: calculateColor(carbonIntensity) - implement in next lesson

	} catch (error) {
		console.error('Error fetching carbon data:', error);
		
		// Show user-friendly error message
		loading.style.display = 'none';
		results.style.display = 'none';
		errors.textContent = 'Sorry, we couldn\'t fetch data for that region. Please check your API key and region code.';
	}
}

Memecahkan apa yang berlaku di sini:

Menggunakan API fetch() moden dan bukannya perpustakaan luaran seperti Axios untuk kod yang lebih bersih dan bebas pergantungan
Melaksanakan pemeriksaan ralat yang betul dengan response.ok untuk menangkap kegagalan API lebih awal
Mengendalikan operasi asinkron dengan async/await untuk aliran kod yang lebih mudah dibaca
Mengesahkan dengan API CO2 Signal menggunakan header auth-token
Menganalisis data respons JSON dan mengekstrak maklumat intensiti karbon
Mengemas kini pelbagai elemen UI dengan data alam sekitar yang diformatkan
Memberikan mesej ralat mesra pengguna apabila panggilan API gagal

Konsep JavaScript moden yang ditunjukkan:

Literal templat dengan sintaks ${} untuk pemformatan string yang bersih
Pengendalian ralat dengan blok try/catch untuk aplikasi yang kukuh
Corak async/await untuk mengendalikan permintaan rangkaian dengan anggun
Pemusnahan objek untuk mengekstrak data tertentu dari respons API
Rantai kaedah untuk pelbagai manipulasi DOM

✅ Fungsi ini menunjukkan beberapa konsep penting dalam pembangunan web - berkomunikasi dengan pelayan luaran, mengendalikan pengesahan, memproses data, mengemas kini antara muka, dan menguruskan ralat dengan anggun. Ini adalah kemahiran asas yang digunakan oleh pembangun profesional secara kerap.

🎉 Apa yang telah anda capai: Anda telah mencipta sambungan pelayar yang:

Menyambung ke internet dan mengambil data alam sekitar sebenar
Menyimpan tetapan pengguna antara sesi
Menguruskan ralat dengan anggun dan bukannya terhempas
Memberikan pengalaman pengguna yang lancar dan profesional

Uji kerja anda dengan menjalankan npm run build dan menyegarkan semula sambungan anda dalam pelayar. Anda kini mempunyai penjejak jejak karbon yang berfungsi. Pelajaran seterusnya akan menambah fungsi ikon dinamik untuk melengkapkan sambungan.

Cabaran Ejen GitHub Copilot 🚀

Gunakan mod Ejen untuk melengkapkan cabaran berikut:

Penerangan: Tingkatkan sambungan pelayar dengan menambah penambahbaikan pengendalian ralat dan ciri pengalaman pengguna. Cabaran ini akan membantu anda berlatih bekerja dengan API, penyimpanan tempatan, dan manipulasi DOM menggunakan corak JavaScript moden.

Arahan: Cipta versi yang dipertingkatkan bagi fungsi displayCarbonUsage yang termasuk: 1) Mekanisme percubaan semula untuk panggilan API yang gagal dengan backoff eksponen, 2) Pengesahan input untuk kod kawasan sebelum membuat panggilan API, 3) Animasi pemuatan dengan indikator kemajuan, 4) Caching respons API dalam localStorage dengan cap masa tamat (cache selama 30 minit), dan 5) Ciri untuk memaparkan data sejarah dari panggilan API sebelumnya. Juga tambahkan komen JSDoc gaya TypeScript yang sesuai untuk mendokumentasikan semua parameter fungsi dan jenis pengembalian.

Ketahui lebih lanjut tentang mod ejen di sini.

🚀 Cabaran

Luaskan pemahaman anda tentang API dengan meneroka kekayaan API berasaskan pelayar yang tersedia untuk pembangunan web. Pilih salah satu API pelayar ini dan bina demonstrasi kecil:

Geolocation API - Dapatkan lokasi semasa pengguna
Notification API - Hantar notifikasi desktop
HTML Drag and Drop API - Cipta antara muka seret interaktif
Web Storage API - Teknik penyimpanan tempatan lanjutan
Fetch API - Alternatif moden kepada XMLHttpRequest

Soalan penyelidikan untuk dipertimbangkan:

Masalah dunia nyata apa yang diselesaikan oleh API ini?
Bagaimana API ini mengendalikan ralat dan kes tepi?
Apakah pertimbangan keselamatan yang wujud semasa menggunakan API ini?
Sejauh mana API ini disokong di pelbagai pelayar?

Selepas penyelidikan anda, kenal pasti ciri-ciri apa yang menjadikan API mesra pembangun dan boleh dipercayai.

Kuiz Pasca-Kuliah

Kuiz pasca-kuliah

Ulasan & Kajian Sendiri

Anda telah mempelajari tentang LocalStorage dan API dalam pelajaran ini, kedua-duanya sangat berguna untuk pembangun web profesional. Bolehkah anda fikirkan bagaimana kedua-dua perkara ini berfungsi bersama? Fikirkan bagaimana anda akan merancang sebuah laman web yang akan menyimpan item untuk digunakan oleh API.

Tugasan

Adopt an API

Penafian:
Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI Co-op Translator. Walaupun kami berusaha untuk ketepatan, sila ambil perhatian bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang berwibawa. Untuk maklumat kritikal, terjemahan manusia profesional adalah disyorkan. Kami tidak bertanggungjawab atas sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini.

20 KiB Raw Permalink Blame History