JavaScript و JSON: الدليل الكامل

# JavaScript و JSON: الدليل الكامل

JavaScript و JSON مرتبطان بشكل وثيق. اسم JSON نفسه يأتي من JavaScript Object Notation.

مقدمة

العلاقة بين JavaScript و JSON

• نفس البنية - JSON مبني على كائنات JavaScript
• مدمج - دعم أصلي في المتصفح و Node.js
• سهل - التحويل بين الاثنين بسيط

JSON.parse()

التحليل الأساسي

// نص JSON
const jsonString = '{"الاسم": "أحمد", "العمر": 30}';

// تحويل إلى كائن JavaScript
const obj = JSON.parse(jsonString);

console.log(obj.الاسم);  // أحمد
console.log(obj.العمر);   // 30
console.log(typeof obj);  // object

تحليل المصفوفات

const jsonArray = '[1, 2, 3, 4, 5]';
const arr = JSON.parse(jsonArray);

console.log(arr);         // [1, 2, 3, 4, 5]
console.log(arr[0]);      // 1
console.log(Array.isArray(arr));  // true

معالجة الأخطاء

const badJSON = '{"الاسم": "أحمد", "العمر": 30,}';  // فاصلة زائدة

try {
  const obj = JSON.parse(badJSON);
} catch (error) {
  console.error('خطأ في التحليل:', error.message);
  // SyntaxError: Unexpected token } in JSON
}

معالج reviver

const jsonString = '{"الاسم": "أحمد", "تاريخ": "2026-01-16"}';

// معالج مخصص
const obj = JSON.parse(jsonString, (key, value) => {
  // تحويل التواريخ تلقائياً
  if (key === 'تاريخ') {
    return new Date(value);
  }
  return value;
});

console.log(obj.تاريخ);  // Date object
console.log(obj.تاريخ instanceof Date);  // true

JSON.stringify()

التحويل الأساسي

// كائن JavaScript
const obj = {
  الاسم: 'أحمد',
  العمر: 30,
  المدينة: 'الرياض'
};

// تحويل إلى JSON
const jsonString = JSON.stringify(obj);

console.log(jsonString);
// {"الاسم":"أحمد","العمر":30,"المدينة":"الرياض"}

التنسيق الجميل

const obj = {
  الاسم: 'أحمد',
  العمر: 30,
  العنوان: {
    المدينة: 'الرياض',
    الشارع: 'شارع الملك فهد'
  }
};

// مع مسافة بادئة 2
const formatted = JSON.stringify(obj, null, 2);

console.log(formatted);
/

{
  "الاسم": "أحمد",
  "العمر": 30,
  "العنوان": {
    "المدينة": "الرياض",
    "الشارع": "شارع الملك فهد"
  }
}
/

معالج replacer

const user = {
  الاسم: 'أحمد',
  العمر: 30,
  كلمةالسر: 'secret123',  // حساس
  البريد: 'ahmed@example.com'
};

// إزالة الحقول الحساسة
const safe = JSON.stringify(user, (key, value) => {
  if (key === 'كلمةالسر') {
    return undefined;  // تجاهل هذا الحقل
  }
  return value;
});

console.log(safe);
// {"الاسم":"أحمد","العمر":30,"البريد":"ahmed@example.com"}

اختيار المفاتيح

const user = {
  id: 1,
  الاسم: 'أحمد',
  العمر: 30,
  البريد: 'ahmed@example.com',
  كلمةالسر: 'secret'
};

// تضمين مفاتيح محددة فقط
const limited = JSON.stringify(user, ['id', 'الاسم', 'البريد']);

console.log(limited);
// {"id":1,"الاسم":"أحمد","البريد":"ahmed@example.com"}

تحويل أنواع البيانات

الأنواع المدعومة

const data = {
  نص: 'مرحباً',
  رقم: 42,
  عشري: 3.14,
  منطقي: true,
  لاشيء: null,
  مصفوفة: [1, 2, 3],
  كائن: { مفتاح: 'قيمة' }
};

console.log(JSON.stringify(data, null, 2));

الأنواع غير المدعومة

const data = {
  دالة: function() { return 'مرحباً'; },  // يتم تجاهلها
  غيرمعرف: undefined,                      // يتم تجاهلها
  رمز: Symbol('test'),                     // يتم تجاهلها
  تاريخ: new Date()                        // يتم تحويلها إلى string
};

console.log(JSON.stringify(data));
// {"تاريخ":"2026-01-16T10:30:00.000Z"}

العمل مع التواريخ

تحويل التواريخ

const data = {
  الاسم: 'أحمد',
  تاريخالميلاد: new Date('1994-05-15')
};

// التحويل الافتراضي (ISO string)
const json = JSON.stringify(data);
console.log(json);
// {"الاسم":"أحمد","تاريخالميلاد":"1994-05-15T00:00:00.000Z"}

// استعادة التاريخ
const restored = JSON.parse(json, (key, value) => {
  if (key === 'تاريخالميلاد') {
    return new Date(value);
  }
  return value;
});

console.log(restored.تاريخالميلاد instanceof Date);  // true

معالج تواريخ مخصص

// دالة مساعدة
function dateReplacer(key, value) {
  if (value instanceof Date) {
    return {
      __type: 'Date',
      __value: value.toISOString()
    };
  }
  return value;
}

function dateReviver(key, value) {
  if (value && value.__type === 'Date') {
    return new Date(value.__value);
  }
  return value;
}

// الاستخدام
const data = { تاريخ: new Date() };
const json = JSON.stringify(data, dateReplacer);
const restored = JSON.parse(json, dateReviver);

النسخ العميق

باستخدام JSON

const original = {
  الاسم: 'أحمد',
  العنوان: {
    المدينة: 'الرياض'
  },
  المهارات: ['JavaScript', 'Python']
};

// نسخ عميق
const copy = JSON.parse(JSON.stringify(original));

// تعديل النسخة لا يؤثر على الأصل
copy.العنوان.المدينة = 'جدة';
copy.المهارات.push('SQL');

console.log(original.العنوان.المدينة);  // الرياض
console.log(original.المهارات);           // ['JavaScript', 'Python']
console.log(copy.العنوان.المدينة);        // جدة
console.log(copy.المهارات);               // ['JavaScript', 'Python', 'SQL']

القيود

const data = {
  دالة: () => 'مرحباً',
  تاريخ: new Date(),
  مرجعدائري: null
};

data.مرجعدائري = data;  // مرجع دائري

try {
  JSON.stringify(data);
} catch (error) {
  console.error('خطأ:', error.message);
  // TypeError: Converting circular structure to JSON
}

العمل مع API

Fetch API

// طلب GET
fetch('https://api.example.com/users/1')
  .then(response => response.json())  // تحليل JSON تلقائياً
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('خطأ:', error);
  });

// طلب POST
const newUser = {
  الاسم: 'أحمد',
  البريد: 'ahmed@example.com'
};

fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(newUser)  // تحويل إلى JSON
})
  .then(response => response.json())
  .then(data => {
    console.log('تم الإنشاء:', data);
  });

async/await

async function getUser(id) {
  try {
    const response = await fetch(https://api.example.com/users/${id});
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('خطأ:', error);
    throw error;
  }
}

async function createUser(user) {
  const response = await fetch('https://api.example.com/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(user)
  });
  return await response.json();
}

// الاستخدام
const user = await getUser(1);
const newUser = await createUser({ الاسم: 'أحمد' });

LocalStorage

حفظ البيانات

// كائن JavaScript
const settings = {
  اللغة: 'ar',
  الموضوع: 'داكن',
  الإشعارات: true
};

// حفظ في localStorage
localStorage.setItem('settings', JSON.stringify(settings));

// قراءة من localStorage
const savedSettings = JSON.parse(localStorage.getItem('settings'));

console.log(savedSettings.اللغة);  // ar

دالة مساعدة

// حفظ
function saveToStorage(key, value) {
  try {
    localStorage.setItem(key, JSON.stringify(value));
    return true;
  } catch (error) {
    console.error('خطأ في الحفظ:', error);
    return false;
  }
}

// قراءة
function loadFromStorage(key, defaultValue = null) {
  try {
    const item = localStorage.getItem(key);
    return item ? JSON.parse(item) : defaultValue;
  } catch (error) {
    console.error('خطأ في القراءة:', error);
    return defaultValue;
  }
}

// الاستخدام
saveToStorage('user', { الاسم: 'أحمد' });
const user = loadFromStorage('user', {});

التحقق من الصحة

فحص بنية JSON

function isValidJSON(string) {
  try {
    JSON.parse(string);
    return true;
  } catch (error) {
    return false;
  }
}

// الاستخدام
console.log(isValidJSON('{"الاسم": "أحمد"}'));  // true
console.log(isValidJSON('{"الاسم": أحمد}'));    // false
console.log(isValidJSON('{invalid}'));          // false

التحقق من المخطط

function validateUser(user) {
  // التحقق من الحقول المطلوبة
  if (!user.الاسم || typeof user.الاسم !== 'string') {
    throw new Error('الاسم مطلوب ويجب أن يكون نصاً');
  }

  if (!user.العمر || typeof user.العمر !== 'number') {
    throw new Error('العمر مطلوب ويجب أن يكون رقماً');
  }

  if (user.العمر < 0 || user.العمر > 150) {
    throw new Error('العمر غير صالح');
  }

  return true;
}

// الاستخدام
try {
  const user = { الاسم: 'أحمد', العمر: 30 };
  validateUser(user);
  console.log('البيانات صالحة');
} catch (error) {
  console.error('خطأ في التحقق:', error.message);
}

تحسين الأداء

JSON الكبير

// تجنب التحليل المتكرر
const jsonString = '...';  // JSON كبير

// سيء
for (let i = 0; i < 1000; i++) {
  const data = JSON.parse(jsonString);  // تحليل متكرر
  // ...
}

// جيد
const data = JSON.parse(jsonString);  // تحليل مرة واحدة
for (let i = 0; i < 1000; i++) {
  // استخدام البيانات المحللة
  // ...
}

التخزين المؤقت

const cache = new Map();

function parseJSON(key, jsonString) {
  if (cache.has(key)) {
    return cache.get(key);
  }

  const parsed = JSON.parse(jsonString);
  cache.set(key, parsed);
  return parsed;
}

مكتبات JSON متقدمة

json5

import JSON5 from 'json5';

// JSON5 يدعم تعليقات وميزات إضافية
const data = JSON5.parse({

  // تعليق
  الاسم: 'أحمد',  // علامات اقتباس اختيارية للمفاتيح
  العمر: 30,
});  // فواصل زائدة مسموحة

superjson

import SuperJSON from 'superjson';

// يدعم Date، Map، Set، undefined، وغيرها
const data = {
  تاريخ: new Date(),
  مجموعة: new Set([1, 2, 3]),
  خريطة: new Map([['مفتاح', 'قيمة']])
};

const serialized = SuperJSON.stringify(data);
const deserialized = SuperJSON.parse(serialized);

أمثلة عملية

نموذج بيانات

class DataModel {
  constructor(data = {}) {
    this.data = data;
  }

  toJSON() {
    return JSON.stringify(this.data, null, 2);
  }

  fromJSON(json) {
    this.data = JSON.parse(json);
    return this;
  }

  save(key) {
    localStorage.setItem(key, this.toJSON());
  }

  load(key) {
    const json = localStorage.getItem(key);
    if (json) {
      this.fromJSON(json);
    }
    return this;
  }
}

// الاستخدام
const model = new DataModel({ الاسم: 'أحمد' });
model.save('user');

const loaded = new DataModel().load('user');

ملف تكوين

class Config {
  constructor(defaultConfig = {}) {
    this.config = { ...defaultConfig };
  }

  async load(url) {
    const response = await fetch(url);
    const config = await response.json();
    this.config = { ...this.config, ...config };
    return this;
  }

  get(key, defaultValue = null) {
    const keys = key.split('.');
    let value = this.config;

    for (const k of keys) {
      if (value && typeof value === 'object' && k in value) {
        value = value[k];
      } else {
        return defaultValue;
      }
    }

    return value;
  }
}

// الاستخدام
const config = new Config({ app: { name: 'تطبيقي' } });
await config.load('/config.json');

console.log(config.get('app.name'));
console.log(config.get('database.host', 'localhost'));

أفضل الممارسات

1. معالجة الأخطاء دائماً

// صحيح
try {
  const data = JSON.parse(jsonString);
} catch (error) {
  console.error('خطأ في التحليل:', error);
}

// خطأ
const data = JSON.parse(jsonString);  // قد يتعطل

2. استخدم التنسيق للتطوير

// للتطوير
console.log(JSON.stringify(data, null, 2));

// للإنتاج
const compact = JSON.stringify(data);

3. احذر من البيانات الحساسة

// لا ترسل معلومات حساسة
const user = {
  الاسم: 'أحمد',
  كلمةالسر: 'secret'  // خطر!
};

// أزل المعلومات الحساسة
const safe = JSON.stringify(user, (key, value) => {
  return key === 'كلمةالسر' ? undefined : value;
});

الملخص

JavaScript و JSON:

• دعم مدمج
• سهل الاستخدام
• سريع وفعال
• أساسي لتطوير الويب

استخدم JSON.parse() و JSON.stringify() بحكمة!