clipboard polyfill

clipboard-polyfill

️ لا تحتاج إلى clipboard-polyfill لنسخ النص! ️

ملاحظة: اعتبارًا من عام 2020، يمكنك استخدام navigator.clipboard.writeText(...) في الإصدارات الثابتة لجميع المتصفحات الرئيسية. ستكون هذه المكتبة مفيدة لك فقط إذا كنت تريد:

• استهداف المتصفحات القديمة جدًا (انظر أدناه لمعرفة التوافق) لنسخ النص،
• نسخ text/html في Firefox ≥126،
• استخدم ClipboardItem API في Firefox ≥126، أو
• polyfill شكل واجهة برمجة التطبيقات (API) في بيئة غير متصفح (على سبيل المثال في jsdom ).

راجع قسم التوافق أدناه لمزيد من التفاصيل.

---

ملخص

يجعل النسخ على الويب سهلاً مثل:

 clipboard . writeText ( "hello world" ) ;

هذه المكتبة عبارة عن ponyfill/polyfill لواجهة برمجة تطبيقات الحافظة غير المتزامنة الحديثة المستندة إلى Promise .

الاستخدام

إذا كنت تستخدم npm ، فقم بتثبيت:

npm install clipboard-polyfill

نموذج تطبيق ينسخ النص إلى الحافظة:

 import * as clipboard from "clipboard-polyfill" ;

function handler ( ) {
  clipboard . writeText ( "This text is plain." ) . then (
    ( ) => { console . log ( "success!" ) ; } ,
    ( ) => { console . log ( "error!" ) ; }
  ) ;
}

window . addEventListener ( "DOMContentLoaded" , function ( ) {
  const button = document . body . appendChild ( document . createElement ( "button" ) ) ;
  button . textContent = "Copy" ;
  button . addEventListener ( "click" , handler ) ;
} ) ;

ملحوظات:

• تحتاج إلى استدعاء عملية الحافظة استجابةً لإيماءة المستخدم (على سبيل المثال، معالج الحدث للنقر على button ).
  • قد تسمح بعض المتصفحات بعملية حافظة واحدة فقط لكل إيماءة.

async / await بناء الجملة

 import * as clipboard from "clipboard-polyfill" ;

async function handler ( ) {
  console . log ( "Previous clipboard text:" , await clipboard . readText ( ) ) ;

  await clipboard . writeText ( "This text is plain." ) ;
}

window . addEventListener ( "DOMContentLoaded" , function ( ) {
  const button = document . body . appendChild ( document . createElement ( "button" ) ) ;
  button . textContent = "Copy" ;
  button . addEventListener ( "click" , handler ) ;
} ) ; 

المزيد من أنواع MIME (أنواع البيانات)

 import * as clipboard from "clipboard-polyfill" ;

async function handler ( ) {
  console . log ( "Previous clipboard contents:" , await clipboard . read ( ) ) ;

  const item = new clipboard . ClipboardItem ( {
    "text/html" : new Blob (
      [ "<i>Markup</i> <b>text</b>. Paste me into a rich text editor." ] ,
      { type : "text/html" }
    ) ,
    "text/plain" : new Blob (
      [ "Fallback markup text. Paste me into a rich text editor." ] ,
      { type : "text/plain" }
    ) ,
  } ) ;
  await clipboard . write ( [ item ] ) ;
}

window . addEventListener ( "DOMContentLoaded" , function ( ) {
  const button = document . body . appendChild ( document . createElement ( "button" ) ) ;
  button . textContent = "Copy" ;
  button . addEventListener ( "click" , handler ) ;
} ) ;

تحقق من مواصفات Clipboard API لمزيد من التفاصيل.

ملحوظات:

• ستحتاج إلى استخدام وظائف async لبناء جملة await .
• في الوقت الحالي، يُعد text/plain text/html أنواع البيانات الوحيدة التي يمكن كتابتها في الحافظة عبر معظم المتصفحات.
• إذا حاولت نسخ أنواع بيانات غير مدعومة، فقد يتم إسقاطها بصمت (مثل Safari 13.1) أو قد يؤدي الاتصال إلى ظهور خطأ (مثل Chrome 83). بشكل عام، ليس من الممكن معرفة متى يتم إسقاط أنواع البيانات.
• في بعض المتصفحات الحالية، قد تقوم read() ‎ بإرجاع مجموعة فرعية من أنواع البيانات المدعومة فقط، حتى لو كانت الحافظة تحتوي على المزيد من أنواع البيانات. لا توجد طريقة لمعرفة ما إذا كان هناك المزيد من أنواع البيانات.

overwrite-globals

إذا كنت تريد أن تقوم المكتبة باستبدال واجهة برمجة التطبيقات للحافظة العامة بتطبيقاتها، فقم باستيراد clipboard-polyfill/overwrite-globals . سيؤدي هذا إلى تحويل المكتبة من ponyfill إلى polyfill مناسب، بحيث يمكنك كتابة التعليمات البرمجية كما لو تم تنفيذ واجهة برمجة التطبيقات للحافظة غير المتزامنة بالفعل في متصفحك:

 import "clipboard-polyfill/overwrite-globals" ;

async function handler ( ) {
  const item = new window . ClipboardItem ( {
    "text/html" : new Blob (
      [ "<i>Markup</i> <b>text</b>. Paste me into a rich text editor." ] ,
      { type : "text/html" }
    ) ,
    "text/plain" : new Blob (
      [ "Fallback markup text. Paste me into a rich text editor." ] ,
      { type : "text/plain" }
    ) ,
  } ) ;

  navigator . clipboard . write ( [ item ] ) ;
}

window . addEventListener ( "DOMContentLoaded" , function ( ) {
  const button = document . body . appendChild ( document . createElement ( "button" ) ) ;
  button . textContent = "Copy" ;
  button . addEventListener ( "click" , handler ) ;
} ) ;

لا يُنصح بهذا الأسلوب، لأنه قد يكسر أي تعليمات برمجية أخرى تتفاعل مع عموميات واجهة برمجة التطبيقات للحافظة، وقد يكون غير متوافق مع تطبيقات المتصفح المستقبلية.

إصدار ملف مسطح مع Promise المتضمن

إذا كنت بحاجة إلى الحصول على إصدار "يعمل فقط"، فقم بتنزيل clipboard-polyfill.window-var.promise.es5.js وقم بتضمينه باستخدام علامة <script> :

 < script src =" ./clipboard-polyfill.window-var.promise.es5.js " > </ script >
< button onclick =" copy() " > Copy text! </ button >
< script >
  // `clipboard` is defined on the global `window` object.
  function copy ( ) {
    clipboard . writeText ( "hello world!" ) ;
  }
</ script >

التجميع / هز الشجرة / التصغير / CommonJS

بفضل وسائل الراحة التي يوفرها نظام JS البيئي الحديث، لم نعد نقدم إنشاءات شجرة مهزوزة أو مصغّرة أو CommonJS بعد الآن. للحصول على مثل هذه التصميمات دون فقدان التوافق، قم بتمرير تصميمات clipboard-polyfill من خلال esbuild . على سبيل المثال:

mkdir temp && cd temp && npm install clipboard-polyfill esbuild

# Minify the ES6 build:
echo ' export * from "clipboard-polyfill"; ' | npx esbuild --format=esm --target=es6 --bundle --minify

# Include just the `writeText()` export and minify:
echo ' export { writeText } from "clipboard-polyfill"; ' | npx esbuild --format=esm --target=es6 --bundle --minify

# Minify an ES5 build:
cat node_modules/clipboard-polyfill/dist/es5/window-var/clipboard-polyfill.window-var.promise.es5.js | npx esbuild --format=esm --target=es5 --bundle --minify

# Get a CommonJS build:
echo ' export * from "clipboard-polyfill"; ' | npx esbuild --format=cjs --target=es6 --bundle

لماذا clipboard-polyfill ؟

قامت المتصفحات بتطبيق العديد من واجهات برمجة تطبيقات الحافظة بمرور الوقت، وتعد الكتابة إلى الحافظة دون إثارة الأخطاء في العديد من المتصفحات القديمة والحالية أمرًا صعبًا إلى حد ما. في كل متصفح يدعم النسخ إلى الحافظة بطريقة ما، تحاول clipboard-polyfill العمل بشكل أقرب ما يمكن إلى واجهة برمجة التطبيقات للحافظة غير المتزامنة. (انظر أعلاه للاطلاع على إخلاء المسؤولية والقيود.)

راجع هذا العرض التقديمي للحصول على تاريخ أطول للوصول إلى الحافظة على الويب.

التوافق

• ☑️: يحتوي المتصفح على دعم الحافظة غير المتزامنة الأصلية.
• ✅: clipboard-polyfill تضيف الدعم.
• : الدعم غير ممكن.
• تشير أسماء المتصفحات ذات الخط العريض إلى أحدث التغييرات الوظيفية للإصدارات الثابتة من المتصفحات الحديثة.

كتابة الدعم حسب الإصدار الأقدم للمتصفح:

المتصفح	writeText()	write() (HTML)	write() (تنسيقات أخرى)
سفاري 13.1	☑️	☑️	☑️ ( image/uri-list ، image/png )
كروم 86ᵃ / إيدج 86	☑️	☑️	☑️ ( image/png )
كروم 76ᵃ / إيدج 79	☑️	✅	☑️ ( image/png )
كروم 66ᵃ / فايرفوكس 63	☑️	✅
سفاري 10 / كروم 42ᵃ / إيدج / فايرفوكس 41	✅	✅ᵇ
اي 9	✅ᶜ

قراءة الدعم:

المتصفح	readText()	read() (HTML)	read() (تنسيقات أخرى)
سفاري 13.1	☑️	☑️	☑️ ( image/uri-list ، image/png )
كروم 76ᵃ / إيدج 79	☑️		☑️ ( image/png )
كروم 66ᵃ	☑️
اي 9	✅ᶜ
فايرفوكس

• ᵃ يتضمن أيضًا إصدارات Edge وOpera وBrave وVivaldi وما إلى ذلك بناءً على الإصدار المقابل من Chrome.
• ᵇ لم يعمل HTML بشكل صحيح على Safari على الأجهزة المحمولة في الإصدارات القليلة الأولى من الإصدار 10.
• ᶜ في Internet Explorer، ستحتاج إلى ملء window.Promise وعد إذا كنت تريد أن تعمل المكتبة.
• ᵈ في الإصدارات الأقدم من Edge (Spartan):
  • قد لا يكون من الممكن معرفة ما إذا كانت عملية النسخ قد نجحت (Edge Bug #14110451، Edge Bug #14080262). سوف تقوم clipboard-polyfill دائمًا بالإبلاغ عن النجاح في هذه الحالة.
  • يتم نسخ نوع البيانات الأخير الذي تحدده فقط إلى الحافظة (Edge Bug #14080506). ضع في اعتبارك وضع نوع البيانات الأكثر أهمية في الكائن الذي تقوم بتمريره إلى مُنشئ ClipboardItem .
  • لم تتم كتابة نوع البيانات text/html باستخدام تنسيق CF_HTML المتوقع. لا تحاول clipboard-polyfill التغلب على هذا الأمر، نظرًا لأن 1) سيتطلب استنشاق إصدار المتصفح الهش، 2) لا يتعطل مستخدمو Edge عمومًا في الإصدار < 17، و3) سيكون وضع الفشل للمتصفحات الأخرى هو تلك الحافظة غير الصالحة يتم نسخ HTML. (خطأ في الحافة #14372529، #73)

يستخدم clipboard-polyfill مجموعة متنوعة من الأساليب البحثية للتغلب على أخطاء التوافق. يرجى إعلامنا إذا كنت تواجه مشكلات في التوافق مع أي من المتصفحات المذكورة أعلاه.

تاريخ

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

المتصفح	النسخة الأولى تدعم navigator.clipboard.writeText(...)	تاريخ الافراج عنه
الكروم	66+	أبريل 2018
فايرفوكس	53+	أكتوبر 2018
حافة	79+ (أول إصدار قائم على الكروم)	يناير 2020
سفاري	13.1+	مارس 2020

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

يعود تاريخ هذا المشروع إلى الوقت الذي كان فيه الوصول إلى الحافظة في JS بالكاد ممكنًا، وكانت جهود واجهة برمجة التطبيقات للحافظة المريحة متوقفة. (راجع هذا العرض التقديمي للحصول على مزيد من السياق.) ولحسن الحظ، تتوفر الآن واجهة برمجة تطبيقات مريحة بنفس الوظيفة في جميع المتصفحات الحديثة منذ عام 2020:

• 2015: بدأت المتصفحات في دعم استدعاء document.execCommand("copy") البائد (مع العديد والعديد من المشكلات).
• 2015: بدأت هذا المشروع باسم clipboard.js (قبل نصف عام من اختيار @zenorocha نفس الاسم؟).
• 2016: تجديد المناقشات حول واجهة برمجة تطبيقات الحافظة غير المتزامنة (على سبيل المثال، وثيقة الاقتراح، crbug.com/593475 ).
• 2017: تمت إعادة تسمية هذا المشروع إلى clipboard-polyfill ليعكس إصلاحًا شاملاً لواجهة برمجة التطبيقات v2 المتوافقة مع مسودة المواصفات.
• 2018: بدأت المتصفحات في دعم navigator.clipboard.writeText() .
• 2020: تبدأ المتصفحات في دعم navigator.clipboard.write() (بما في ذلك دعم text/html ).

شكرًا لـ Gary Kacmarcik وHalvord Steen وآخرين للمساعدة في إحياء واجهة برمجة التطبيقات للحافظة غير المتزامنة!

هذه طريقة معقدة للغاية!

إذا كنت تحتاج فقط إلى نسخ النص في المتصفحات الحديثة، ففكر في استخدام navigator.clipboard.writeText() مباشرة: https://caniuse.com/mdn-api_clipboard_writetext

إذا كنت بحاجة إلى نسخ نص في المتصفحات القديمة أيضًا، فيمكنك أيضًا تجربة هذا الجوهر للحصول على حل اختراق بسيط.