js cookie
v3.0.5
واجهة برمجة تطبيقات بسيطة وخفيفة الوزن JavaScript للتعامل مع ملفات تعريف الارتباط
إذا كنت تشاهد هذا على https://github.com/js-cookie/js-cookie ، فأنت تقرأ الوثائق للفرع الرئيسي. عرض الوثائق لأحدث الإصدار. ؟
يدعم JavaScript Cookie NPM تحت اسم js-cookie .
npm i js-cookie تحتوي حزمة NPM على حقل module يشير إلى متغير وحدة ES للمكتبة ، وذلك أساسًا لتوفير الدعم لمنحات ES Acked Bundlers ، في حين يشير حقل browser الخاص به إلى وحدة UMD للتوافق الكامل للخلف.
لا تدعم جميع المتصفحات وحدات ES أصليًا بعد . لهذا السبب ، توفر حزمة/إصدار NPM كل من متغير وحدة ES و UMD وقد ترغب في تضمين وحدة ES جنبًا إلى جنب مع عودة UMD لحساب ذلك:
بدلاً من ذلك ، قم بتضمين JS-Cookie عبر JSDelivr CDN.
استيراد المكتبة:
import Cookies from 'js-cookie'
// or
const Cookies = require ( 'js-cookie' )قم بإنشاء ملف تعريف ارتباط ، صالح عبر الموقع بأكمله:
Cookies . set ( 'name' , 'value' )قم بإنشاء ملف تعريف ارتباط ينتهي صلاحيته بعد 7 أيام من الآن ، وهو صالح عبر الموقع بأكمله:
Cookies . set ( 'name' , 'value' , { expires : 7 } )إنشاء ملف تعريف ارتباط منتهي الصلاحية ، صالح لمسار الصفحة الحالية:
Cookies . set ( 'name' , 'value' , { expires : 7 , path : '' } )اقرأ ملف تعريف الارتباط:
Cookies . get ( 'name' ) // => 'value'
Cookies . get ( 'nothing' ) // => undefinedاقرأ جميع ملفات تعريف الارتباط المرئية:
Cookies . get ( ) // => { name: 'value' }ملاحظة: لا يمكن قراءة ملف تعريف ارتباط معين عن طريق تمرير إحدى سمات ملفات تعريف الارتباط (التي قد تكون أو لا يتم استخدامها عند كتابة ملف تعريف الارتباط المعني):
Cookies . get ( 'foo' , { domain : 'sub.example.com' } ) // `domain` won't have any effect...! سيكون ملف تعريف الارتباط الذي يحمل اسم foo متاحًا فقط على .get() إذا كان مرئيًا من حيث يتم استدعاء الرمز ؛ لن يكون لسمة المجال و/أو المسار تأثير عند القراءة.
حذف ملفات تعريف الارتباط:
Cookies . remove ( 'name' )حذف ملف تعريف ارتباط صالح لمسار الصفحة الحالية:
Cookies . set ( 'name' , 'value' , { path : '' } )
Cookies . remove ( 'name' ) // fail!
Cookies . remove ( 'name' , { path : '' } ) // removed! مهم! عند حذف ملف تعريف الارتباط ولا تعتمد على السمات الافتراضية ، يجب أن تمر بنفس path الدقيق ، domain ، والسمات secure sameSite التي تم استخدامها لتعيين ملف تعريف الارتباط:
Cookies . remove ( 'name' , { path : '' , domain : '.yourdomain.com' , secure : true } )ملاحظة: إزالة ملف تعريف الارتباط غير الموجود لا يثير أي استثناء ولا يعيد أي قيمة.
إذا كان هناك أي خطر من التعارض مع Cookies لمساحة الاسم ، فستسمح لك طريقة noConflict بتحديد مساحة اسم جديدة والحفاظ على الأصل. هذا مفيد بشكل خاص عند تشغيل البرنامج النصي على مواقع الطرف الثالث على سبيل المثال كجزء من عنصر واجهة مستخدم أو SDK.
// Assign the js-cookie api to a different variable and restore the original "window.Cookies"
var Cookies2 = Cookies . noConflict ( )
Cookies2 . set ( 'name' , 'value' ) ملاحظة: لا تكون طريقة .noConflict ضرورية عند استخدام AMD أو CommonJs ، وبالتالي لا تتعرض في تلك البيئات.
هذا المشروع هو RFC 6265 متوافق. يتم تشفير جميع الشخصيات الخاصة غير المسموح بها في اسم ملف تعريف الارتباط أو قيمة ملفات تعريف الارتباط مع كل من UTF-8 من سداسي الأسلوب السداسي باستخدام ترميز النسبة المئوية. الشخصية الوحيدة في اسم ملف تعريف الارتباط أو قيمة ملفات تعريف الارتباط المسموح بها ولا تزال مشفرة هي شخصية ٪ % ، يتم هروبها من أجل تفسير المدخلات في المئة على أنها حرفية. يرجى ملاحظة أن استراتيجية الترميز/فك التشفير الافتراضية تهدف إلى أن تكون قابلة للتشغيل فقط بين ملفات تعريف الارتباط التي تتم قراءتها/كتبها JS-Cookie. لتجاوز استراتيجية الترميز/فك التشفير الافتراضية ، تحتاج إلى استخدام محول.
ملاحظة: وفقًا لـ RFC 6265 ، قد يتم حذف ملفات تعريف الارتباط الخاصة بك إذا كانت كبيرة جدًا أو أن هناك الكثير من ملفات تعريف الارتباط في نفس المجال ، والمزيد من التفاصيل هنا.
يمكن تعيين الإعدادات الافتراضية لسمات ملفات تعريف الارتباط على مستوى العالم عن طريق إنشاء مثيل من واجهة برمجة التطبيقات عبر withAttributes() ، أو بشكل فردي لكل مكالمة إلى Cookies.set(...) عن طريق تمرير كائن عادي كوسيطة الأخيرة. تتجاوز سمات المكالمة السمات الافتراضية.
تحديد متى سيتم إزالة ملف تعريف الارتباط. يجب أن تكون القيمة Number سيتم تفسيره على أنه أيام من وقت الإنشاء أو مثيل Date . إذا تم حذفه ، يصبح ملف تعريف الارتباط ملف تعريف ارتباط للجلسة.
لإنشاء ملف تعريف ارتباط ينتهي في أقل من يوم واحد ، يمكنك التحقق من الأسئلة الشائعة على الويكي.
الافتراضي: تتم إزالة ملف تعريف الارتباط عندما يغلق المستخدم المتصفح.
أمثلة:
Cookies . set ( 'name' , 'value' , { expires : 365 } )
Cookies . get ( 'name' ) // => 'value'
Cookies . remove ( 'name' ) String تشير إلى المسار الذي يكون فيه ملف تعريف الارتباط مرئيًا.
تقصير: /
أمثلة:
Cookies . set ( 'name' , 'value' , { path : '' } )
Cookies . get ( 'name' ) // => 'value'
Cookies . remove ( 'name' , { path : '' } )ملاحظة بخصوص Internet Explorer:
نظرًا لوجود خطأ غامض في تطبيق Wininet InternetGetCookie الأساسي ، فإن IE's document.cookie لن يعيد ملف تعريف الارتباط إذا تم تعيينه مع سمة مسار تحتوي على اسم ملف.
(من Internet Explorer Cookie Internals (FAQ))
هذا يعني أنه لا يمكن للمرء تعيين مسار باستخدام window.location.pathname في حالة يحتوي اسم المسار على اسم ملف مثل SO: /check.html (أو على الأقل ، لا يمكن قراءة ملف تعريف الارتباط هذا بشكل صحيح).
في الواقع ، يجب ألا تسمح أبدًا للمدخلات غير الموثوقة بتعيين سمات ملفات تعريف الارتباط أو قد تتعرض لهجوم XSS.
String تشير إلى مجال صالح حيث يجب أن يكون ملف تعريف الارتباط مرئيًا. سيكون ملف تعريف الارتباط مرئيًا لجميع النطاقات الفرعية.
الافتراضي: ملف تعريف الارتباط مرئي فقط للمجال أو النطاق الفرعي للصفحة التي تم إنشاء ملف تعريف الارتباط ، باستثناء Internet Explorer (انظر أدناه).
أمثلة:
على افتراض ملف تعريف ارتباط يتم إنشاؤه على site.com :
Cookies . set ( 'name' , 'value' , { domain : 'subdomain.site.com' } )
Cookies . get ( 'name' ) // => undefined (need to read at 'subdomain.site.com')ملاحظة بخصوص السلوك الافتراضي لـ Internet Explorer:
س 3: إذا لم أحدد سمة مجال (من أجل) ملف تعريف الارتباط ، أي يرسله إلى جميع النطاقات الفرعية المتداخلة على أي حال؟ ج: نعم ، سيتم إرسال ملف تعريف ارتباط على example.com إلى sub2.sub1.example.com. يختلف Internet Explorer عن المتصفحات الأخرى في هذا الصدد.
(من Internet Explorer Cookie Internals (FAQ))
هذا يعني أنه إذا حذفت سمة domain ، فسيكون مرئيًا لنطاق فرعي في IE.
إما true أو false ، مع الإشارة إلى ما إذا كان نقل ملفات تعريف الارتباط يتطلب بروتوكول آمن (HTTPS).
الافتراضي: لا يوجد متطلبات بروتوكول آمنة.
أمثلة:
Cookies . set ( 'name' , 'value' , { secure : true } )
Cookies . get ( 'name' ) // => 'value'
Cookies . remove ( 'name' ) String ، تسمح للتحكم في ما إذا كان المتصفح يرسل ملف تعريف الارتباط مع طلبات المواقع المتقاطعة.
الافتراضي: لم يتم تعيينه.
لاحظ أن المتصفحات الأكثر حداثة تصنع "LAX" القيمة الافتراضية حتى دون تحديد أي شيء هنا.
أمثلة:
Cookies . set ( 'name' , 'value' , { sameSite : 'strict' } )
Cookies . get ( 'name' ) // => 'value'
Cookies . remove ( 'name' ) const api = Cookies . withAttributes ( { path : '/' , domain : '.example.com' } ) قم بإنشاء مثيل جديد من واجهة برمجة التطبيقات التي تتجاوز تنفيذ فك التشفير الافتراضي. جميع الأساليب التي تعتمد في فك التشفير المناسب للعمل ، مثل Cookies.get() Cookies.get('name') سيتم استخدام القيمة التي تم إرجاعها كقيمة ملف تعريف الارتباط.
مثال من قراءة أحد ملفات تعريف الارتباط التي لا يمكن فك تشفيرها إلا باستخدام وظيفة escape :
document . cookie = 'escaped=%u5317'
document . cookie = 'default=%E5%8C%97'
var cookies = Cookies . withConverter ( {
read : function ( value , name ) {
if ( name === 'escaped' ) {
return unescape ( value )
}
// Fall back to default for all other cookies
return Cookies . converter . read ( value , name )
}
} )
cookies . get ( 'escaped' ) // 北
cookies . get ( 'default' ) // 北
cookies . get ( ) // { escaped: '北', default: '北' }قم بإنشاء مثيل جديد من واجهة برمجة التطبيقات التي تتجاوز تطبيق الترميز الافتراضي:
Cookies . withConverter ( {
write : function ( value , name ) {
return value . toUpperCase ( )
}
} ) npm i @types/js-cookieتحقق من مستندات الخوادم
تحقق من المبادئ التوجيهية المساهمة
يجب أن يتم إطلاق الإصدار عبر Release عمل تصرفات GitHub ، بحيث تحتوي الحزم المنشورة على NPMJS.com
يتم إنشاء إصدارات Github كمسودة وتحتاج إلى نشرها يدويًا! (هذا لذلك نحن قادرون على صياغة ملاحظات الإصدار المناسبة قبل النشر.)
شكرًا جزيلاً لـ Browserstack لتوفير اختبار المستعرض غير المحدود مجانًا.
