18 KiB

Raw Blame History

Projekt razširitve brskalnika, 2. del: Klic API-ja, uporaba lokalnega shranjevanja

Predhodni kviz

Uvod

Se spomnite razširitve brskalnika, ki ste jo začeli graditi? Trenutno imate lepo oblikovan obrazec, vendar je v bistvu statičen. Danes ga bomo oživili tako, da ga povežemo z resničnimi podatki in mu dodamo spomin.

Pomislite na računalnike za nadzor misije Apollo - niso prikazovali le fiksnih informacij. Nenehno so komunicirali z vesoljskimi plovili, posodabljali telemetrijske podatke in si zapomnili ključne parametre misije. Takšno dinamično vedenje bomo gradili danes. Vaša razširitev bo dostopala do interneta, pridobivala resnične okoljske podatke in si zapomnila vaše nastavitve za naslednjič.

Integracija API-ja se morda sliši zapleteno, vendar gre v bistvu za to, da naučite svojo kodo, kako komunicirati z drugimi storitvami. Ne glede na to, ali pridobivate podatke o vremenu, družbenih omrežjih ali informacijah o ogljičnem odtisu, kot bomo storili danes, gre za vzpostavljanje teh digitalnih povezav. Raziskali bomo tudi, kako brskalniki lahko ohranijo informacije - podobno kot knjižnice uporabljajo kartoteke za shranjevanje lokacij knjig.

Do konca te lekcije boste imeli razširitev brskalnika, ki pridobiva resnične podatke, shranjuje uporabniške nastavitve in zagotavlja gladko izkušnjo. Začnimo!

✅ Sledite oštevilčenim segmentom v ustreznih datotekah, da boste vedeli, kam postaviti svojo kodo.

Priprava elementov za manipulacijo v razširitvi

Preden lahko vaš JavaScript manipulira z vmesnikom, potrebuje reference na specifične HTML elemente. Pomislite na to kot na teleskop, ki ga je treba usmeriti na določene zvezde - preden je Galileo lahko preučeval Jupitrove lune, je moral najti in se osredotočiti na Jupiter.

V datoteki index.js bomo ustvarili const spremenljivke, ki zajamejo reference na vsak pomemben element obrazca. To je podobno, kot da bi znanstveniki označili svojo opremo - namesto da bi vsakič iskali po celotnem laboratoriju, lahko neposredno dostopajo do tistega, kar potrebujejo.

// 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');

Kaj ta koda počne:

Zajame elemente obrazca z uporabo document.querySelector() in CSS razrednih selektorjev
Ustvari reference na vnosna polja za ime regije in API ključ
Vzpostavi povezave z elementi za prikaz rezultatov podatkov o porabi ogljika
Pripravi dostop do UI elementov, kot so indikatorji nalaganja in sporočila o napakah
Shrani vsako referenco elementa v const spremenljivko za enostavno ponovno uporabo v kodi

Dodajanje poslušalcev dogodkov

Zdaj bomo poskrbeli, da vaša razširitev reagira na uporabniške akcije. Poslušalci dogodkov so način, kako vaša koda spremlja interakcije uporabnikov. Pomislite nanje kot na operaterje v zgodnjih telefonskih centralah - poslušali so dohodne klice in povezali prave kroge, ko je nekdo želel vzpostaviti povezavo.

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

Razumevanje teh konceptov:

Pripne poslušalca za oddajo obrazca, ki se sproži, ko uporabniki pritisnejo Enter ali kliknejo oddaj
Poveže poslušalca za klik na gumb za čiščenje, da ponastavi obrazec
Posreduje objekt dogodka (e) funkcijam za obdelavo za dodatni nadzor
Pokliče funkcijo init() takoj, da nastavi začetno stanje vaše razširitve

✅ Opazite skrajšano sintakso puščice, ki se tukaj uporablja. Ta sodoben pristop JavaScripta je bolj čist kot tradicionalni izrazi funkcij, vendar oba delujeta enako dobro!

Izdelava funkcij za inicializacijo in ponastavitev

Ustvarimo logiko inicializacije za vašo razširitev. Funkcija init() je kot navigacijski sistem ladje, ki preverja svoje instrumente - določa trenutno stanje in ustrezno prilagaja vmesnik. Preveri, ali je nekdo že uporabljal vašo razširitev in naloži njihove prejšnje nastavitve.

Funkcija reset() uporabnikom omogoča svež začetek - podobno kot znanstveniki ponastavijo svoje instrumente med eksperimenti, da zagotovijo čiste podatke.

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

Razčlenitev dogajanja:

Pridobi shranjen API ključ in regijo iz lokalnega shranjevanja brskalnika
Preveri, ali gre za novega uporabnika (brez shranjenih poverilnic) ali za uporabnika, ki se vrača
Prikaže obrazec za nastavitev za nove uporabnike in skrije druge elemente vmesnika
Samodejno naloži shranjene podatke za uporabnike, ki se vračajo, in prikaže možnost ponastavitve
Upravlja stanje uporabniškega vmesnika glede na razpoložljive podatke

Ključni koncepti o lokalnem shranjevanju:

Ohranja podatke med sejami brskalnika (za razliko od shranjevanja sej)
Shranjuje podatke kot ključ-vrednost pare z uporabo getItem() in setItem()
Vrne null, ko za določen ključ ni podatkov
Ponuja preprost način za zapomnitev uporabniških nastavitev in preferenc

💡 Razumevanje shranjevanja v brskalniku: LocalStorage je kot dajanje trajnega spomina vaši razširitvi. Pomislite, kako je starodavna Aleksandrijska knjižnica shranjevala zvitke - informacije so ostale na voljo, tudi ko so učenjaki odšli in se vrnili.

Ključne značilnosti:

Ohranja podatke tudi po zaprtju brskalnika

Preživi ponovne zagone računalnika in zrušitve brskalnika

Ponuja veliko prostora za shranjevanje uporabniških preferenc

Omogoča takojšen dostop brez zamud omrežja

Pomembna opomba: Vaša razširitev brskalnika ima svoje izolirano lokalno shranjevanje, ki je ločeno od običajnih spletnih strani. To zagotavlja varnost in preprečuje konflikte z drugimi spletnimi mesti.

Shranjene podatke si lahko ogledate tako, da odprete orodja za razvijalce brskalnika (F12), se pomaknete na zavihek Application in razširite razdelek Local Storage.

⚠️ Varnostni vidik: V produkcijskih aplikacijah shranjevanje API ključev v LocalStorage predstavlja varnostna tveganja, saj JavaScript lahko dostopa do teh podatkov. Za namene učenja ta pristop deluje, vendar bi morale prave aplikacije za občutljive poverilnice uporabljati varno shranjevanje na strežniški strani.

Obdelava oddaje obrazca

Zdaj bomo obdelali, kaj se zgodi, ko nekdo odda vaš obrazec. Privzeto brskalniki ob oddaji obrazcev ponovno naložijo stran, vendar bomo prestregli to vedenje, da ustvarimo bolj gladko izkušnjo.

Ta pristop je podoben temu, kako nadzor misije obravnava komunikacijo z vesoljskimi plovili - namesto da bi za vsako sporočilo ponastavili celoten sistem, ohranjajo neprekinjeno delovanje med obdelavo novih informacij.

Ustvarite funkcijo, ki zajame dogodek oddaje obrazca in izlušči uporabnikov vnos:

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

V zgornjem primeru smo:

Preprečili privzeto vedenje oddaje obrazca, ki bi osvežilo stran
Izluščili vrednosti uporabniškega vnosa iz polj za API ključ in regijo
Posredovali podatke obrazca funkciji setUpUser() za obdelavo
Ohranili vedenje enostranske aplikacije z izogibanjem osvežitvi strani

✅ Ne pozabite, da vaša polja obrazca HTML vključujejo atribut required, zato brskalnik samodejno preveri, da uporabniki pred zagonom te funkcije zagotovijo tako API ključ kot regijo.

Nastavitev uporabniških preferenc

Funkcija setUpUser je odgovorna za shranjevanje uporabniških poverilnic in začetek prvega klica API-ja. To ustvari gladek prehod od nastavitve do prikaza rezultatov.

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

Korak za korakom, kaj se dogaja:

Shrani API ključ in ime regije v lokalno shranjevanje za prihodnjo uporabo
Prikaže indikator nalaganja, da obvesti uporabnike, da se podatki pridobivajo
Počisti morebitna prejšnja sporočila o napakah z zaslona
Razkrije gumb za čiščenje, da lahko uporabniki pozneje ponastavijo svoje nastavitve
Začne klic API-ja za pridobivanje resničnih podatkov o porabi ogljika

Ta funkcija ustvarja brezhibno uporabniško izkušnjo z upravljanjem tako trajanja podatkov kot posodobitev uporabniškega vmesnika v eni usklajeni akciji.

Prikaz podatkov o porabi ogljika

Zdaj bomo povezali vašo razširitev z zunanjimi viri podatkov prek API-jev. To vašo razširitev spremeni iz samostojnega orodja v nekaj, kar lahko dostopa do informacij v realnem času z interneta.

Razumevanje API-jev

API-ji so način, kako različne aplikacije komunicirajo med seboj. Pomislite nanje kot na telegrafski sistem, ki je povezoval oddaljena mesta v 19. stoletju - operaterji so pošiljali zahteve oddaljenim postajam in prejemali odgovore z zahtevanimi informacijami. Vsakič, ko preverite družbena omrežja, vprašate glasovnega asistenta ali uporabite aplikacijo za dostavo, API-ji omogočajo te izmenjave podatkov.

Ključni koncepti o REST API-jih:

REST pomeni 'Representational State Transfer'
Uporablja standardne metode HTTP (GET, POST, PUT, DELETE) za interakcijo s podatki
Vrača podatke v predvidljivih formatih, običajno JSON
Ponuja dosledne URL-je za različne vrste zahtev

✅ CO2 Signal API, ki ga bomo uporabili, ponuja podatke o ogljični intenzivnosti električnih omrežij po vsem svetu v realnem času. To pomaga uporabnikom razumeti okoljski vpliv njihove porabe električne energije!

💡 Razumevanje asinhronega JavaScripta: Ključna beseda async omogoča vaši kodi, da hkrati obravnava več operacij. Ko zahtevate podatke s strežnika, ne želite, da se vaša celotna razširitev zamrzne - to bi bilo, kot da bi letalski nadzor ustavil vse operacije, medtem ko čaka na odgovor enega letala.

Ključne prednosti:

Ohranja odzivnost razširitve med nalaganjem podatkov

Omogoča, da druga koda nadaljuje izvajanje med omrežnimi zahtevami

Izboljša berljivost kode v primerjavi s tradicionalnimi vzorci povratnih klicev

Omogoča elegantno obravnavo napak pri težavah z omrežjem

Tukaj je kratek video o async:

🎥 Kliknite na sliko zgoraj za video o async/await.

Ustvarite funkcijo za pridobivanje in prikaz podatkov o porabi ogljika:

// 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.';
	}
}

Razčlenitev dogajanja:

Uporablja sodobni fetch() API namesto zunanjih knjižnic, kot je Axios, za čistejšo kodo brez odvisnosti
Izvede ustrezno preverjanje napak z response.ok, da zgodaj ujame neuspehe API-ja
Obravnava asinhrone operacije z async/await za bolj berljiv potek kode
Avtenticira z CO2 Signal API-jem z uporabo glave auth-token
Razčleni podatke odgovora JSON in izlušči informacije o ogljični intenzivnosti
Posodobi več UI elementov s formatiranimi okoljskimi podatki
Ponuja uporabniku prijazna sporočila o napakah, ko klici API-ja ne uspejo

Ključni sodobni koncepti JavaScripta, ki so prikazani:

Predloge nizov s sintakso ${} za čisto oblikovanje nizov
Obravnava napak z bloki try/catch za robustne aplikacije
Vzorec async/await za elegantno obravnavo omrežnih zahtev
Razčlenjevanje objektov za izluščenje specifičnih podatkov iz odgovorov API-ja
Verižna metoda za več manipulacij DOM-a

✅ Ta funkcija prikazuje več pomembnih konceptov spletnega razvoja - komunikacijo z zunanjimi strežniki, obravnavo avtentikacije, obdelavo podatkov, posodabljanje vmesnikov in elegantno obravnavo napak. To so temeljne veščine, ki jih profesionalni razvijalci redno uporabljajo.

🎉 Kaj ste dosegli: Ustvarili ste razširitev brskalnika, ki:

Povezuje z internetom in pridobiva resnične okoljske podatke
Ohranja uporabniške nastavitve med sejami
Obravnava napake elegantno, namesto da bi se zrušila
Ponuja gladko, profesionalno uporabniško izkušnjo

Preizkusite svoje delo tako, da zaženete npm run build in osvežite svojo razširitev v brskalniku. Zdaj imate funkcionalen sledilnik ogljičnega odtisa. Naslednja lekcija bo dodala funkcionalnost dinamičnih ikon za dokončanje razširitve.

Izziv z GitHub Copilot Agent 🚀

Uporabite način Agent za dokončanje naslednjega izziva:

Opis: Izboljšajte razširitev brskalnika z dodajanjem izboljšav pri obravnavi napak in funkcij za uporabniško izkušnjo. Ta izziv vam bo pomagal pri vadbi dela z API-ji, lokalnim shranjevanjem in manipulacijo DOM-a z uporabo sodobnih vzorcev JavaScripta.

Navodilo: Ustvarite izboljšano različico funkcije displayCarbonUsage, ki vključuje: 1) Mehanizem za ponovni poskus pri neuspelih klicih API-ja z eksponentnim povratnim časom, 2) Validacijo vnosa za kodo regije pred izvedbo klica API-ja, 3) Animacijo nalaganja z indikatorji napredka, 4) Predpomnjenje odgovorov API-ja v lokalnem shranjevanju z časovnimi žigi poteka (predpomnjenje za 30 minut) in 5) Funkcijo za prikaz zgodovinskih podatkov iz prejšnjih klicev API-ja. Prav tako dodajte ustrezne komentarje v slogu TypeScript JSDoc za dokumentiranje vseh parametrov funkcij in vrst vrnjenih vrednosti.

Več o načinu agent si preberite tukaj.

🚀 Izziv

Razširite svoje razumevanje API-jev z raziskovanjem bogastva API-jev, ki temeljijo na brskalniku in so na voljo za spletni razvoj. Izberite enega od V tej lekciji ste se naučili o LocalStorage in API-jih, oboje zelo uporabno za profesionalnega spletnega razvijalca. Ali lahko razmislite, kako ti dve stvari delujeta skupaj? Razmislite, kako bi zasnovali spletno stran, ki bi shranjevala elemente za uporabo z API-jem.

Naloga

Posvojite API

Omejitev odgovornosti:
Ta dokument je bil preveden z uporabo storitve za prevajanje AI Co-op Translator. Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da lahko avtomatizirani prevodi vsebujejo napake ali netočnosti. Izvirni dokument v njegovem maternem jeziku je treba obravnavati kot avtoritativni vir. Za ključne informacije priporočamo profesionalni človeški prevod. Ne prevzemamo odgovornosti za morebitne nesporazume ali napačne razlage, ki izhajajo iz uporabe tega prevoda.

18 KiB Raw Blame History