الأسبوع 10: Fetch API والتخزين المحلي
JS | async/await، JSON، Fetch API، localStorage
- Fetch API و localStorage — شرح عملي — ملف workshops.json وتحميله بـ fetch و async / await مع حالتي التحميل والخطأ، المفضلة وآخر تصفية والوضع الداكن في localStorage، ومسودة الاستمارة في sessionStorage · 10 دقائق
الأسبوع 10 - واجهة Fetch API والتخزين المحلي (localStorage)
تصميم وإدارة مواقع الإنترنت 1 — جامعة الأقصى
صيغة JSON (JavaScript Object Notation)
JSON صيغة نصية خفيفة لتخزين البيانات وتبادلها. تشبه كثيراً كائنات JavaScript لكن بقواعد أكثر صرامة. تقريباً جميع واجهات برمجة التطبيقات (API) تُرجع البيانات بصيغة JSON.
قواعد JSON
- المفاتيح يجب أن تكون نصوصاً بين علامتي تنصيص مزدوجتين
- القيم يمكن أن تكون: نصوصاً، أرقاماً، قيماً منطقية (boolean)، null، مصفوفات، كائنات
- لا فاصلة بعد آخر عنصر
- لا دوال ولا undefined ولا تعليقات
// JSON صحيح:
{
"name": "Ahmad",
"age": 25,
"isStudent": true,
"courses": ["Web Dev", "Database"],
"address": {
"city": "Gaza",
"country": "Palestine"
},
"graduationDate": null
}
JSON.stringify() - تحويل الكائن إلى نص JSON
const student = {
name: "Ahmad",
age: 25,
courses: ["Web Dev", "Database"]
};
// التحويل إلى نص JSON
const jsonString = JSON.stringify(student);
console.log(jsonString);
// '{"name":"Ahmad","age":25,"courses":["Web Dev","Database"]}'
console.log(typeof jsonString); // "string"
// JSON منسّق للقراءة (بإزاحة مسافتين)
const pretty = JSON.stringify(student, null, 2);
console.log(pretty);
// {
// "name": "Ahmad",
// "age": 25,
// "courses": [
// "Web Dev",
// "Database"
// ]
// }
JSON.parse() - تحويل نص JSON إلى كائن
const jsonStr = '{"name":"Ahmad","age":25}';
// تحويل نص JSON إلى كائن JavaScript
const obj = JSON.parse(jsonStr);
console.log(obj.name); // "Ahmad"
console.log(obj.age); // 25
console.log(typeof obj); // "object"
// انتبه من JSON غير الصحيح
try {
JSON.parse("not valid json");
} catch (error) {
console.error("Invalid JSON!", error.message);
}
التخزين المحلي (localStorage)
يتيح لك localStorage تخزين البيانات داخل المتصفح، وتبقى محفوظة حتى بعد إغلاق المتصفح. تُخزَّن البيانات على شكل أزواج (مفتاح - قيمة)، ويجب أن تكون المفاتيح والقيم نصوصاً.
// ---- العمليات الأساسية ----
// حفظ البيانات
localStorage.setItem("username", "Ahmad");
localStorage.setItem("theme", "dark");
// قراءة البيانات
const username = localStorage.getItem("username");
console.log(username); // "Ahmad"
// المفتاح غير الموجود يُرجع null
console.log(localStorage.getItem("xyz")); // null
// حذف عنصر محدد
localStorage.removeItem("theme");
// مسح كل بيانات localStorage
localStorage.clear();
// ---- تخزين الكائنات والمصفوفات ----
// يجب استخدام JSON.stringify() للحفظ و JSON.parse() للقراءة
const user = {
name: "Ahmad",
age: 25,
courses: ["Web Dev", "Database"]
};
// حفظ الكائن
localStorage.setItem("user", JSON.stringify(user));
// تحميل الكائن
const savedUser = JSON.parse(localStorage.getItem("user"));
console.log(savedUser.name); // "Ahmad"
// ---- حفظ مصفوفة وتحميلها ----
const todos = [
{ text: "Learn JavaScript", done: true },
{ text: "Build a project", done: false }
];
// الحفظ
localStorage.setItem("todos", JSON.stringify(todos));
// التحميل (مع قيمة بديلة في أول مرة)
const savedTodos = JSON.parse(localStorage.getItem("todos")) || [];
console.log(savedTodos);
// ---- نمط عملي ----
// تحميل البيانات أو استخدام القيمة الافتراضية
function loadData(key, defaultValue) {
const data = localStorage.getItem(key);
return data ? JSON.parse(data) : defaultValue;
}
// حفظ البيانات
function saveData(key, value) {
localStorage.setItem(key, JSON.stringify(value));
}
// طريقة الاستخدام
let tasks = loadData("tasks", []);
tasks.push({ text: "New task" });
saveData("tasks", tasks);
حدود localStorage
- مساحة تخزين تقارب 5-10 ميجابايت لكل نطاق (domain)
- يخزّن النصوص فقط (يجب تحويل الكائنات بـ stringify)
- متزامن (Synchronous)، وقد يُبطئ الصفحة مع البيانات الكبيرة
- لا تنتهي صلاحيته (يبقى للأبد حتى يتم مسحه)
- لا تخزّن أبداً بيانات حساسة (كلمات المرور، رموز الدخول tokens) في localStorage
تخزين الجلسة (sessionStorage)
يعمل sessionStorage تماماً مثل localStorage، لكن البيانات تُمسح عند إغلاق تبويب المتصفح.
// نفس أوامر localStorage
sessionStorage.setItem("tempData", "hello");
const data = sessionStorage.getItem("tempData");
sessionStorage.removeItem("tempData");
sessionStorage.clear();
| الميزة | localStorage | sessionStorage |
| تبقى بعد الإغلاق | نعم | لا (تُمسح) |
| مشتركة بين التبويبات | نعم (لنفس النطاق) | لا (لكل تبويب وحده) |
| حد المساحة | ~5-10 MB | ~5-10 MB |
| الاستخدام | تفضيلات المستخدم، البيانات المحفوظة | بيانات النماذج المؤقتة |
البرمجة غير المتزامنة (Asynchronous JavaScript)
لغة JavaScript أحادية المسار (Single-threaded) — أي أنها تنفّذ شيئاً واحداً فقط في كل لحظة. لكن ماذا عن العمليات التي تأخذ وقتاً، مثل جلب البيانات من الخادم؟ لا نريد أن تتجمّد الصفحة كلها أثناء الانتظار!
هنا يأتي دور البرمجة غير المتزامنة. فهي تسمح لـ JavaScript ببدء مهمة طويلة، ثم الاستمرار في تنفيذ باقي الكود أثناء انتظار انتهاء تلك المهمة.
دوال الاستدعاء الراجع (Callback Functions)
// الـ callback هي دالة نمرّرها كمُعامل (argument) إلى دالة أخرى
// ويتم "استدعاؤها لاحقاً" عند انتهاء العملية
// مثال: setTimeout (تعمل بعد فترة تأخير)
console.log("1. Start");
setTimeout(() => {
console.log("2. This runs after 2 seconds");
}, 2000);
console.log("3. End");
// ترتيب الناتج: 1, 3, 2
// تُطبع "3. End" قبل "2. This runs..." لأن setTimeout غير متزامنة!
// جحيم الاستدعاءات Callback Hell (مشكلة الـ callbacks)
getUser(1, (user) => {
getPosts(user.id, (posts) => {
getComments(posts[0].id, (comments) => {
console.log(comments);
// تداخل عميق = صعوبة في القراءة!
});
});
});
الوعود (Promises)
الوعد (Promise) يمثّل النتيجة التي ستصل لاحقاً من عملية غير متزامنة. ويكون في واحدة من ثلاث حالات:
- قيد الانتظار (Pending) — العملية لم تنتهِ بعد
- تم الوفاء (Fulfilled) (أو resolved) — العملية انتهت بنجاح
- مرفوض (Rejected) — العملية فشلت
// إنشاء Promise
const myPromise = new Promise((resolve, reject) => {
const success = true;
setTimeout(() => {
if (success) {
resolve("Data loaded!"); // تم الوفاء
} else {
reject("Failed to load"); // مرفوض
}
}, 1000);
});
// استخدام الـ Promise عبر .then() و .catch() و .finally()
myPromise
.then(result => {
console.log("Success:", result);
})
.catch(error => {
console.error("Error:", error);
})
.finally(() => {
console.log("Done (runs regardless)");
});
// تسلسل الـ Promises (يحل مشكلة callback hell!)
getUser(1)
.then(user => getPosts(user.id))
.then(posts => getComments(posts[0].id))
.then(comments => console.log(comments))
.catch(err => console.error(err));
// Promise.all - انتظر حتى تنجح جميع الـ promises
const p1 = fetch("/api/users");
const p2 = fetch("/api/posts");
const p3 = fetch("/api/comments");
Promise.all([p1, p2, p3])
.then(responses => {
console.log("All loaded!", responses);
})
.catch(err => {
console.error("One failed:", err);
});
// Promise.race - أول واحد ينجح أو يفشل هو الفائز
Promise.race([p1, p2])
.then(first => console.log("First to finish:", first));
async / await
async/await طريقة كتابة أبسط فوق الـ Promises، تجعل الكود غير المتزامن يبدو ويعمل كأنه كود متزامن عادي. وهي الطريقة الحديثة والمفضّلة للتعامل مع الـ Promises.
// سلسلة Promise عادية
fetch("https://jsonplaceholder.typicode.com/users/1")
.then(response => response.json())
.then(user => console.log(user.name))
.catch(err => console.error(err));
// نفس الشيء باستخدام async/await (أوضح بكثير!)
async function getUser() {
try {
const response = await fetch("https://jsonplaceholder.typicode.com/users/1");
const user = await response.json();
console.log(user.name);
} catch (error) {
console.error("Error:", error);
}
}
getUser();
// نسخة الدالة السهمية (Arrow function)
const getUser = async () => {
try {
const response = await fetch("https://jsonplaceholder.typicode.com/users/1");
const user = await response.json();
return user;
} catch (error) {
console.error(error);
}
};
// عدة استدعاءات await (بالتتابع)
async function loadData() {
const usersRes = await fetch("/api/users"); // انتظر
const postsRes = await fetch("/api/posts"); // ثم انتظر
const users = await usersRes.json();
const posts = await postsRes.json();
return { users, posts };
}
// await بالتوازي (أسرع!)
async function loadDataParallel() {
const [usersRes, postsRes] = await Promise.all([
fetch("/api/users"),
fetch("/api/posts")
]);
const users = await usersRes.json();
const posts = await postsRes.json();
return { users, posts };
}
قواعد أساسية
- لا يمكن استخدام
await إلا داخل دالة async
- دوال
async تُرجع دائماً Promise
- استخدم
try/catch لمعالجة الأخطاء (بدلاً من .catch())
مقدمة إلى واجهة Fetch API
الدالة fetch() هي الطريقة الحديثة لإرسال طلبات HTTP في JavaScript. وهي تُرجع Promise تنتهي بكائن استجابة Response.
// fetch بسيط
const response = await fetch("https://jsonplaceholder.typicode.com/posts");
// خصائص كائن الاستجابة Response
console.log(response.status); // 200
console.log(response.ok); // true (status 200-299)
console.log(response.statusText); // "OK"
console.log(response.headers); // كائن الترويسات Headers
console.log(response.url); // الرابط الذي تم جلبه
// استخراج البيانات من الاستجابة
const data = await response.json(); // قراءتها كـ JSON (الأكثر استخداماً)
const text = await response.text(); // قراءتها كنص عادي
const blob = await response.blob(); // بيانات ثنائية (صور، ملفات)
طلبات GET
// طلب GET بسيط
async function getPosts() {
try {
const response = await fetch("https://jsonplaceholder.typicode.com/posts");
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
const posts = await response.json();
console.log(posts); // مصفوفة من 100 منشور
console.log(posts[0].title); // عنوان أول منشور
} catch (error) {
console.error("Failed to fetch:", error);
}
}
getPosts();
// جلب عنصر واحد حسب الـ ID
async function getPost(id) {
const response = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`);
const post = await response.json();
return post;
}
// مع معاملات الاستعلام (query parameters)
async function searchPosts(userId) {
const url = `https://jsonplaceholder.typicode.com/posts?userId=${userId}`;
const response = await fetch(url);
const posts = await response.json();
return posts;
}
// عرض البيانات المجلوبة في الصفحة (DOM)
async function displayUsers() {
const response = await fetch("https://jsonplaceholder.typicode.com/users");
const users = await response.json();
const container = document.querySelector("#users");
container.innerHTML = users.map(user => `
<div class="user-card">
<h3>${user.name}</h3>
<p>${user.email}</p>
<p>${user.phone}</p>
</div>
`).join("");
}
طلبات POST
// طلب POST - إرسال بيانات إلى الخادم
async function createPost(title, body) {
try {
const response = await fetch("https://jsonplaceholder.typicode.com/posts", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
title: title,
body: body,
userId: 1
})
});
if (!response.ok) {
throw new Error("Failed to create post");
}
const newPost = await response.json();
console.log("Created:", newPost);
return newPost;
} catch (error) {
console.error("Error:", error);
}
}
createPost("My New Post", "This is the content.");
// طلب PUT (تحديث المورد كاملاً)
async function updatePost(id, data) {
const response = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`, {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(data)
});
return response.json();
}
// طلب DELETE (حذف)
async function deletePost(id) {
const response = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`, {
method: "DELETE"
});
return response.ok;
}
معالجة الأخطاء
// نمط شامل لمعالجة الأخطاء
async function fetchData(url) {
try {
const response = await fetch(url);
// fetch ترفض (reject) فقط عند أخطاء الشبكة
// أخطاء HTTP مثل (404, 500) تُعتبر نجاحاً! افحص response.ok
if (!response.ok) {
switch (response.status) {
case 400: throw new Error("Bad request");
case 401: throw new Error("Unauthorized");
case 403: throw new Error("Forbidden");
case 404: throw new Error("Not found");
case 500: throw new Error("Server error");
default: throw new Error(`HTTP ${response.status}`);
}
}
const data = await response.json();
return data;
} catch (error) {
// أخطاء الشبكة (انقطاع الاتصال، فشل DNS، CORS) + الأخطاء التي رميناها
if (error.name === "TypeError") {
console.error("Network error - check your connection");
} else {
console.error("Error:", error.message);
}
return null;
}
}
// الاستخدام مع حالة التحميل
async function loadUsers() {
const container = document.querySelector("#users");
const errorMsg = document.querySelector("#error");
// إظهار التحميل
container.innerHTML = "<p>Loading...</p>";
errorMsg.textContent = "";
try {
const response = await fetch("https://jsonplaceholder.typicode.com/users");
if (!response.ok) throw new Error("Failed to load users");
const users = await response.json();
// عرض البيانات
container.innerHTML = users.map(u => `<p>${u.name}</p>`).join("");
} catch (error) {
container.innerHTML = "";
errorMsg.textContent = error.message;
}
}
مهم: fetch() لا ترفض (reject) عند أخطاء HTTP!
الدالة fetch() ترفض فقط عند أعطال الشبكة (انقطاع الإنترنت، خطأ DNS). أما الاستجابة بخطأ HTTP مثل 404 أو 500 فتُعتبر ناجحة! لذلك افحص دائماً response.ok أو response.status.
التعامل مع واجهات API حقيقية
مفاهيم REST API
| طريقة HTTP | الإجراء | مثال |
GET | قراءة البيانات | جلب كل المستخدمين، جلب مستخدم واحد |
POST | إنشاء بيانات | إنشاء مستخدم جديد |
PUT | تحديث (استبدال) | تحديث الملف الشخصي كاملاً |
PATCH | تحديث (جزئي) | تحديث البريد الإلكتروني فقط |
DELETE | حذف البيانات | حذف مستخدم |
واجهات API مجانية للتدريب
- JSONPlaceholder:
https://jsonplaceholder.typicode.com (منشورات، مستخدمون، تعليقات)
- OpenWeatherMap:
https://api.openweathermap.org (تحتاج إلى مفتاح API مجاني)
- PokéAPI:
https://pokeapi.co/api/v2 (بيانات بوكيمون، لا تحتاج مفتاحاً)
- REST Countries:
https://restcountries.com/v3.1 (معلومات الدول، بدون مفتاح)
مثال كامل: واجهة API للطقس
// مثال باستخدام OpenWeatherMap API
const API_KEY = "YOUR_API_KEY"; // احصل على مفتاح مجاني من openweathermap.org
async function getWeather(city) {
const url = `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${API_KEY}&units=metric`;
try {
const response = await fetch(url);
if (response.status === 404) {
throw new Error("City not found");
}
if (!response.ok) {
throw new Error("Weather data unavailable");
}
const data = await response.json();
// استخراج البيانات المفيدة
const weather = {
city: data.name,
temp: Math.round(data.main.temp),
feels_like: Math.round(data.main.feels_like),
humidity: data.main.humidity,
description: data.weather[0].description,
icon: data.weather[0].icon,
wind: data.wind.speed
};
console.log(weather);
return weather;
} catch (error) {
console.error(error.message);
return null;
}
}
// حفظ سجل البحث في localStorage
function saveSearch(city) {
let history = JSON.parse(localStorage.getItem("searchHistory")) || [];
// أضف في البداية، وتجنّب التكرار
history = history.filter(h => h.toLowerCase() !== city.toLowerCase());
history.unshift(city);
// احتفظ بآخر 10 فقط
history = history.slice(0, 10);
localStorage.setItem("searchHistory", JSON.stringify(history));
}
الخلاصة
أصبحت الآن تعرف كيف تحفظ البيانات في المتصفح (localStorage)، وكيف تكتب JavaScript غير متزامن (Promises و async/await)، وكيف تستخدم واجهة Fetch API للتواصل مع الخوادم الخارجية. تدرّب على ذلك من خلال مهمتي تطبيق الطقس ومتتبّع الميزانية!بهذا نكون أنهينا أساسيات تطوير الواجهات الأمامية (HTML و CSS و JavaScript). بالتوفيق للجميع!
جامعة الأقصى — تصميم وإدارة مواقع الإنترنت 1