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

أضاف الإصدار 10 من Internet Explorer والإصدارات الأحدث ميزة تتيح استخدام الأمرَين "قطع" و"نسخ" من خلال الأسلوب Document.execCommand(). اعتبارًا من الإصدار 43 من Chrome، أصبحت هذه الأوامر متاحة أيضًا في Chrome.

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

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

مثال بسيط

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

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

<p>Email me at <a class="js-emaillink" href="mailto:matt@example.co.uk">matt@example.co.uk</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()، حيث يعرض القيمة false إذا لم يكن الأمر متوافقًا أو مفعّلاً. نلفّ execCommand() في أسلوبَي try وcatch لأنّ الأمرَين cut وcopy يمكن أن يتسببا في حدوث خطأ في بعض السيناريوهات.

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

باستخدام textarea وزر في ملف 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() هو أنّ المتصفّح قد يتيح القص والنسخ، ولكن لن يتم تفعيلهما إذا لم يتم اختيار أي نص في الوقت الحالي. يكون ذلك مفيدًا في السيناريوهات التي لا يتم فيها ضبط اختيار النص آليًا وتريد التأكّد من أنّه سيتم تنفيذ الإجراء على النحو المتوقّع، وإلا عليك عرض رسالة للمستخدم.

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

تتوافق هذه الأوامر مع الإصدار 10 من Internet Explorer والإصدار 43 من Chrome والإصدار 41 من Firefox والإصدار 29 من Opera والإصدارات الأحدث.

لا يتيح Safari هذه الأوامر.

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

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