الفرق بين المراجعتين لصفحة: «JavaScript/Document/cookie»

مراجعة 16:23، 18 مارس 2018

تُستعمل هذه الخاصيّة للحصول على ملفّات الارتباط (cookies) المُرتبطة بالمُستند الحالي وضبطها، للتعامل مع ملفّات الارتباط ببساطة أكثر، انظر إطار العمل البسيط هذا.

البنية العامة

الحصول على جميع ملفّات تعريف الارتباط المتاحة

allCookies = document.cookie;

المُتغيّر allCookies أعلاه عبارة عن سلسلة نصيّة تحتوي على قائمة بجميع ملفات الارتباط مفصولة بفاصلة منقوطة (;)، وهي على شكل مفتاح=قيمة.

ضبط ملفّ ارتباط جديد

document.cookie = newCookie;

في الشيفرة أعلاه، المُتغيّر newCookie عبارة عن سلسلة نصيّة على شكل مفتاح=قيمة. لاحظ أنّك تستطيع أن تضبط أو تُحدّث ملفّ ارتباط واحد فقط في كل مرّة باستعمال هذه الطّريقة. وضَع في ذهنك ما يلي كذلك:

يُمكن لأيّ من قيم خصائص ملفّات الارتباط التّالية أن تتبَع اختياريا زوج المفتاح وقيمته، وذلك عبر تحديد ملفّ الارتباط المُرادِ ضبطه أو تحديثه ويجب على قيم الخصائص هذه أن تُسبَق بفاصلة منقوطة كفاصِل:
- ‎;path=path (يقبل قيما مثل '/' و'‎/mydir')، إن لم تُحدَّد أيّة قيمة، فقيمته الافتراضيّة هي المسار الحاليّ لمكان المُستند الحاليّ. يجب على المسار أن يكون مُطلقًا (absolute)، انظر RFC 6265. للمزيد من المعلومات حول كيفيّة استعمال المسارات النسبيّة (relative paths)، انظر هذه الفقرة.
- ‎;domain=domain (يقبل قيما مثل 'example.com' أو 'subdomain.example.com'). إن لم تحدَّد أيّة قيمة، فقيمته الافتراضيّة هي جزء المُضيف الخاصّ بمكان المُستند الحالي (لا يشمل النّطاقات الفرعيّة). وعلى عكس المُواصفات السّابقة، فالنّقط في آخر أسماء النّطاقات ستُتجاهل، لكنّ المتصفحات قد تمنع ضبط ملفّ تعريف يحتوي على هذه النّقط. إن حُدِّد النّطاق، فالنّطاقات الفرعيّة دائما ما تكون مشمولة.
- ‎;max-age=max-age-in-seconds عدد الثواني التي سيكون فيها ملفّ الارتباط ذا صلاحيّة، يُمكن أن تكون قيمته مثلا 60*60*24*365 أو 31536000 ليكون ملفّ الارتباط صالحا لسنة واحدة.
- ;expires=date-in-GMTString-format تُحدّد تاريخ انتهاء صلاحيّة ملفّ الارتباط، إن لم تُضبَط قيمةٍ لأي من expires أو max-age فستنتهي صلاحيّة ملفّ الارتباط في نهاية الجلسة. انظر Date.toUTCString‎() لفهم كيفيّة تحويل تاريخٍ إلى قيمة تُمثِّل التاريخ في توقيت UTC (وهي الصّيغة المطلوبة لهذه الخاصيّة). مُلاحظة: عندما تكون المعلومات الخاصّة بالمُستخدم حسّاسة فمن المهم على تطبيق الويب الخاص بك أن يقوم إزالة صلاحيّة بيانات ملفّ الارتباط بعد مُدّة زمنيّة مُعيّنة، لا يجب أبدا الاعتماد على المُتصفح ليُزيل ملفات الارتباط الخاصّة بالجلسة، إذ بعض المتصفحات تمنع ملفات الارتباط من أن تنتهي صلاحيّتها أبَدِيًّا.
- ‎;secure اسمح لملفّ الارتباط أن ينتقل فقط على بروتوكول آمن مثل https.
يُمكن للسلسة النصّية التي تُمثّل قيمة ملفّ الارتباط أن تستعمل الـتّابع encodeURIComponent()‎ للتأكد من أنّ السلسلة النّصية لا تحتوي على أية فاصلة أو فاصلة منقوطة أو مساحة بيضاء (والتي تُعتبر قيما غير مسموح بها في قيم ملفّات الارتباط).
بعض تطبيقات عملاء المُستخدمين (user agent) تدعم السابِقات التّاليّة لملفّات الارتباط:
- ‎__Secure-‎ تُخبِر المُتصفح بوجوب وضع ملفّات الارتباط المنقولة على قناة آمنة فقط في الطّلبات.
- ‎__Host-‎ تُخبِر المُتصفح بأنّ امتداد ملفّ الارتباط محدود في مسار يُمنح من طرف الخادوم إضافة إلى وجوب كون ملفّ الارتباط من أصل آمن. إن لم يمنح الخادوم المسار، فستُستعمل قيمة عنوان URI الخاصّ بمُجلّد الطّلب. وتُخبر كذلك المُتصفحَ بأنّ خاصّية النّطاق domain لا يجب أن تُضبَط، ما يمنع إرسال ملفّ الارتباط إلى نطاق آخر. يجب على خاصّية المسار path أن تُساويَ دائما الأصل مُتصفّح Chrome. مُلاحظة: تُعتبر العارضة (-) جزءا من السّابقة. يُمكن لهذه السّابقات أن تُضبط فقط في حالة ضُبِطت الخاصيّة secure كذلك.

@@ سطر 16: / سطر 16: @@
 * يُمكن لأيّ من قيم خصائص ملفّات الارتباط التّالية أن تتبَع اختياريا زوج المفتاح وقيمته، وذلك عبر تحديد ملفّ الارتباط المُرادِ ضبطه أو تحديثه ويجب على قيم الخصائص هذه أن تُسبَق بفاصلة منقوطة كفاصِل:
-** ‎<code>;path=path</code> (يقبل قيما مثل <code>'/'</code> و<code>'‎/mydir'</code>)،  إن لم تُحدَّد أيّة قيمة، فقيمته الافتراضيّة هي المسار الحاليّ لمكان المُستند الحاليّ. يجب على المسار أن يكون مُطلقًا (absolute)، انظر RFC 6265. للمزيد من المعلومات حول كيفيّة استعمال المسارات النسبيّة (relative paths)، انظر [[هذه الفقرة]].
+** ‎<code>;path=path</code> (يقبل قيما مثل <code>'/'</code> و<code>'‎/mydir'</code>)،  إن لم تُحدَّد أيّة قيمة، فقيمته الافتراضيّة هي المسار الحاليّ لمكان المُستند الحاليّ. يجب على المسار أن يكون مُطلقًا (absolute)، انظر [https://tools.ietf.org/html/rfc6265 RFC 6265]. للمزيد من المعلومات حول كيفيّة استعمال المسارات النسبيّة (relative paths)، انظر [[هذه الفقرة]].
 ** ‎<code>;domain=domain</code> (يقبل قيما مثل <code>'example.com'</code> أو <code>'subdomain.example.com'</code>). إن لم تحدَّد أيّة قيمة، فقيمته الافتراضيّة هي جزء المُضيف الخاصّ بمكان المُستند الحالي (لا يشمل النّطاقات الفرعيّة). وعلى عكس المُواصفات السّابقة، فالنّقط في آخر أسماء النّطاقات ستُتجاهل، لكنّ المتصفحات قد تمنع ضبط ملفّ تعريف يحتوي على هذه النّقط. إن حُدِّد النّطاق، فالنّطاقات الفرعيّة دائما ما تكون مشمولة.
 **‎<code>;max-age=max-age-in-seconds</code> عدد الثواني التي سيكون فيها ملفّ الارتباط ذا صلاحيّة، يُمكن أن تكون قيمته مثلا <code>60*60*24*365</code> أو <code>31536000</code> ليكون ملفّ الارتباط صالحا لسنة واحدة.
 ** <code>;expires=date-in-GMTString-format</code> تُحدّد تاريخ انتهاء صلاحيّة ملفّ الارتباط، إن لم تُضبَط قيمةٍ لأي من <code>expires</code> أو <code>max-age</code> فستنتهي صلاحيّة ملفّ الارتباط في نهاية الجلسة. انظر <code>[[JavaScript/Date/toUTCString | Date.toUTCString‎()]]</code> لفهم كيفيّة تحويل تاريخٍ إلى قيمة تُمثِّل التاريخ في توقيت UTC (وهي الصّيغة المطلوبة لهذه الخاصيّة). '''مُلاحظة:''' عندما تكون المعلومات الخاصّة بالمُستخدم حسّاسة فمن المهم على تطبيق الويب الخاص بك أن يقوم إزالة صلاحيّة بيانات ملفّ الارتباط بعد مُدّة زمنيّة مُعيّنة، لا يجب أبدا الاعتماد على المُتصفح ليُزيل ملفات الارتباط الخاصّة بالجلسة، إذ بعض المتصفحات تمنع ملفات الارتباط من أن تنتهي صلاحيّتها أبَدِيًّا.
+** ‎<code>;secure</code> اسمح لملفّ الارتباط أن ينتقل فقط على بروتوكول آمن مثل https.
-* ‎<code>;secure</code> اسمح لملفّ الارتباط أن ينتقل فقط على بروتوكول آمن مثل https.
 * يُمكن للسلسة النصّية التي تُمثّل قيمة ملفّ الارتباط أن تستعمل الـتّابع <code>encodeURIComponent()</code>‎ للتأكد من أنّ السلسلة النّصية لا تحتوي على أية فاصلة أو فاصلة منقوطة أو مساحة بيضاء (والتي تُعتبر قيما غير مسموح بها في قيم ملفّات الارتباط).
 * بعض تطبيقات عملاء المُستخدمين (user agent) تدعم السابِقات التّاليّة لملفّات الارتباط:
 ** ‎<code>__Secure-‎</code> تُخبِر المُتصفح بوجوب وضع ملفّات الارتباط المنقولة على قناة آمنة فقط في الطّلبات.
 ** ‎<code>__Host-‎</code> تُخبِر المُتصفح بأنّ امتداد ملفّ الارتباط محدود في مسار يُمنح من طرف الخادوم إضافة إلى وجوب كون ملفّ الارتباط من أصل آمن. إن لم يمنح الخادوم المسار، فستُستعمل قيمة عنوان URI الخاصّ بمُجلّد الطّلب. وتُخبر كذلك المُتصفحَ بأنّ خاصّية النّطاق <code>domain</code> لا يجب أن تُضبَط، ما يمنع إرسال ملفّ الارتباط إلى نطاق آخر. يجب على خاصّية المسار <code>path</code> أن تُساويَ دائما الأصل مُتصفّح Chrome. '''مُلاحظة:''' تُعتبر العارضة (-) جزءا من السّابقة. يُمكن لهذه السّابقات أن تُضبط فقط في حالة ضُبِطت الخاصيّة <code>secure</code> كذلك.