قص الأوامر ونسخها

Matt Gaunt

أضاف الإصدار IE10 والإصدارات الأحدث دعمًا لأوامر "الاقتصاص والدمج" و"النسخ" من خلال الإجراء Document.execCommand(). اعتبارًا من الإصدار 43 من Chrome، تتوفّر هذه الأوامر أيضًا في متصفِّح Chrome.

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

يصبح ذلك مفيدًا للغاية عند دمجه مع Selection API لتحديد النص آليًا لتحديد النص الذي يتم نسخه إلى الحافظة، وسنطّلع على مزيد من التفاصيل لاحقًا في هذه المقالة.

مثال بسيط

على سبيل المثال، دعنا نضيف زرًا ينسخ عنوان البريد الإلكتروني إلى حافظة المستخدم.

نضيف عنوان البريد الإلكتروني في ملف HTML الخاص بنا مع زر لبدء النسخ عند النقر فوقه:

<p>Email me at <a class="js-emaillink" href="mailto:[e-mail]">[e-mail]</a></p>

<p><button class="js-emailcopybtn"><img src="./images/copy-icon.png" /></button></p>

بعد ذلك، نريد في JavaScript إضافة معالج أحداث النقر إلى الزر الذي نختار فيه نص عنوان البريد الإلكتروني من علامة الارتساء js-emaillink، وننفذ أمر نسخ بحيث يظهر عنوان البريد الإلكتروني في حافظة المستخدم، ثم نلغي اختيار عنوان البريد الإلكتروني حتى لا يرى المستخدم هذا الاختيار.

var copyEmailBtn = document.querySelector('.js-emailcopybtn');
copyEmailBtn.addEventListener('click', function(event) {
    // Select the email link anchor text
    var emailLink = document.querySelector('.js-emaillink');
    var range = document.createRange();
    range.selectNode(emailLink);
    window.getSelection().addRange(range);

    try {
    // Now that we've selected the anchor text, execute the copy command
    var successful = document.execCommand('copy');
    var msg = successful ? 'successful' : 'unsuccessful';
    console.log('Copy email command was ' + msg);
    } catch(err) {
    console.log('Oops, unable to copy');
    }

    // Remove the selections - NOTE: Should use
    // removeRange(range) when it is supported
    window.getSelection().removeAllRanges();
});

ما نفعله هنا هو استخدام طريقة في Selection API، window.getSelection() لضبط "اختيار" النص بشكل آلي على الرابط، وهو النص الذي نريد نسخه إلى حافظة المستخدم. بعد استدعاء document.execCommand() يمكننا إزالة التحديد عن طريق استدعاء window.getSelection().removeAllRanges(). إذا أردت التأكد من أن كل شيء يعمل كما هو متوقع، يمكنك فحص استجابة document.execCommand()، لأنه يعرض خطأ إذا لم يكن الأمر مدعومًا أو ممكنًا. نلتف الأمر execCommand() في محاولة ونكتشف أن الأمرين "قص" و"نسخ" يمكن أن يؤديا إلى حدوث خطأ في بعض السيناريوهات.

يمكن استخدام الأمر 'cut' للحقول النصية حيث تريد إزالة محتوى النص وإتاحة الوصول إليه عبر الحافظة.

استخدام منطقة نصية وزر في ملف HTML:

<p><textarea class="js-cuttextarea">Hello I'm some text</textarea></p>

<p><button class="js-textareacutbtn" disable>Cut Textarea</button></p>

يمكننا تنفيذ ما يلي لقص المحتوى:

var cutTextareaBtn = document.querySelector('.js-textareacutbtn');

cutTextareaBtn.addEventListener('click', function(event) {
    var cutTextarea = document.querySelector('.js-cuttextarea');
    cutTextarea.select();

    try {
    var successful = document.execCommand('cut');
    var msg = successful ? 'successful' : 'unsuccessful';
    console.log('Cutting text command was ' + msg);
    } catch(err) {
    console.log('Oops, unable to cut');
    }
});

queryCommandSupported وqueryCommandEnabled

قبل طلب البيانات document.execCommand()، عليك التأكّد من أنّ واجهة برمجة التطبيقات هذه متوافقة باستخدام الطريقة document.queryCommandSupported(). في المثال أعلاه، يمكننا تعيين حالة الزر "إيقاف" بناءً على الدعم مثل:

copyEmailBtn.disabled = !document.queryCommandSupported('copy');

يكمن الفرق بين document.queryCommandSupported() وdocument.queryCommandEnabled() في أنّه يمكن استخدام القص والنسخ من خلال المتصفح، ولكن إذا لم يتم تحديد أي نص حاليًا، لن يتم تفعيلهما. يكون هذا مفيدًا في السيناريوهات التي لا تحدد فيها النص آليًا وترغب في التأكد من أن الأمر سيعمل على النحو المتوقع، وإلا يقدم رسالة إلى المستخدم.

التوافق مع المتصفح

تتوفر هذه الأوامر في IE 10 وChrome 43 وFirefox 41 و+ Opera 29 والإصدارات الأحدث.

لا يدعم Safari هذه الأوامر.

الأخطاء المعروفة

• سيؤدي الاستدعاء بـ queryCommandSupported() من devtools دائمًا إلى عرض خطأ.
• في الوقت الحالي، لا يعمل القطع إلا عند تحديد النص آليًا.