JavaScript/Document/execCommand

عندما ينتقل مستند HTML إلى نمط التّصميم designMode فإنّ كائن المستند يوفّر التّابع Document.execCommand()‎ الذي يسمح للمستخدم بتنفيذ الأوامر للتعامل مع محتويات المنطقة القابلة للتّعديل. تؤثّر معظم هذه الأوامر على محتويات المستند الموجودة (تعديل النصوص لجعلها بخط عريض أو مائل مثلًا)، فيما تُدخِل بعض الأوامر الأخرى عناصر جديدة (مثل إضافة رابط) أو تؤثّر على كامل السّطر (مثل إزاحته). عند استخدام الخاصيّة contentEditable، فاستدعاء التّابع Document.execCommand()‎ يؤثّر على العنصر المُفعّل القابل للتعديل حاليًّا.

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

bool = document.execCommand(aCommandName, aShowDefaultUI, aValueArgument)

القيمة المعادة

قيمة منطقيّة Boolean تكون قيمتها false إن كان الأمر معطّلًا أو غير مدعوم. لاحظ أنّ التّابع يُعيد true فقط في حالة تفاعل المستخدم مع التّابع، أي أنّه لا يجب استخدامه للتحقّق من دعم المتصفّحات قبل تصيير (rendering) عنصرٍ يستدعي أمرًا معيّنًا.

المعاملات

aCommandName

سلسة نصيّة من النّوع DOMString تُحدّد اسم الأمر المرغوب تنفيذه. انظر قائمة الأوامر الممكنة.

aShowDefaultUI

قيمة منطقيّة Boolean تشير إلى ما إذا وجب عرض واجهة المستخدم الافتراضيّة. هذا المعامل غير متوافر في متصفّح FireFox.

aValueArgument

يُستخدم للأوامر التي تتطلب مُدخلًا (مثل الأمر insertImage الذي يحتاج إلى رابط URL الصّورة المرغوب إدخالها والذي تكون قيمته هي قيمة هذا المعامل)، هذا مُعامل يُمثّل سلسلة نصيّة من النّوع DOMString يُتيح المعلومات التي يحتاج إليها الأمر المرغوب تنفيذه. مرّر للمعامل القيمة null إن لم يحتج الأمر إلى أية معطيات.

الأوامر

backColor

يُغيّر لون خلفيّة المستند. في نمط backColor، يؤثّر الأمر على لون خلفيّة الكتلة المُحتَوية (containing block) عوضًا عن ذلك. يتطلّب هذا تمرير سلسلة نصيّة من النّوع <color> كمُعامل. لاحظ أنّ متصفّح IE يستعمل هذا الأمر لضبط لون خلفيّة النّص.

bold

يضبط ما إذا كان النّص عريضًا أم لا للنصّ المُظلّل أو النّص في نقطة الإدخال. يستعمل IE العنصر <strong> عوضًا عن العنصر <b>.

contentReadOnly

يجعل من محتوى النّص قابلًا للقراءة فقط أو قابلًا للتّعديل. هذا الأمر يتطلّب تمرير قيمة منطقيّة true أو false كمُعامل (غير مدعوم في متصفّح IE).

copy

ينسخ النّص المظلّل حاليًّا إلى الحافظة (clipboard). تتفاوت شروط تفعيل هذا الأمر من متصفّح إلى آخر. انظر جدول المتصفّحات المدعومة للتحقّق ممّا إذا كان في مقدورك استعماله في حالتك أم لا.

createLink

ينشئ رابطًا من النّص المظلّل في حالة كان هناك نصّ مظلّل. هذا يتطلّب تمرير سلسلة نصيّة تحتوي على عنوان URI الرّابط إلى الأمر كمُعامل، يجب على عنوان URI أن يحتوي على الأقل على محرف واحد يُمكن له أن يكون مساحةً بيضاء (يُمكن أن ينشئ متصفّح IE رابطًا بقيمة عنوان URI تُساوي null).

cut

يقصّ النصّ المُظلّل حاليًّا وينسخه إلى الحافظة. تتفاوت شروط تفعيل هذا الأمر من متصفّح إلى آخر. انظر جدول المتصفّحات المدعومة للتحقّق ممّا إذا كان في مقدورك استعماله في حالتك أم لا.

decreaseFontSize

يُضيف العنصر <small> حول النصّ المُظلّل أو في نقطة الإدخال (غير مدعوم في متصفّح IE).

defaultParagraphSeparator

يغيّر فاصل الفقرات (paragraph separator) المُستخدَم عند إنشاء فقرات جديدة في أمكنة النّصوص القابلة للتّعديل.

delete

يحذف النصّ المظلَّل حاليًّا.

enableInlineTableEditing

يُفعّل أو يُعطّل التّحكم في إنشاء وحذف أعمدة وخانات الجدول. (غير مدعوم في متصفّح IE).

enableObjectResizing

يُفعّل أو يُعطّل مقابض التحكم في الحجم على الصور والكائنات الأخرى القابلة لإعادة ضبط حجمها (غير مدعوم في متصفّح IE).

fontName

يُغيّر اسم الخطّ للنّص المُظلّل أو في نقطة الإدخال. هذا يتطلّب تمرير سلسلة نصيّة تمثّل اسم الخطّ (‎"‎Arial‎"‎ مثلًا) إلى الأمر كمُعامل.

fontSize

يُغيّر حجم الخطّ للنّص المُظلّل أو في نقطة الإدخال. هذا يتطلّب تمرير حجم خطّ متوافق مع HTML (أي من 1 إلى 7) إلى الأمر كمُعامل.

foreColor

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

formatBlock

يُضيف وسم HTML الذي يتحكّم في الكتل النّصيّة حول السّطر الذي يحتوي النّص المظلّل، مُبدِلًا وسم الكتلة الذي يحتوي السّطر إن كان موجودًا (في متصفّح Firefox، الوسم BLOCKQUOTE استثناء، إذ سيغطّي أي وسم كتلة مُحتوى أصلًا). يتطلّب الأمر تمرير سلسلة نصيّة تمثّل اسم الوسم إلى الأمر كمُعامل. يُمكن استخدام جميع وسوم تنسيق الكتل (مثل ‎‎"H1"‎ و‎"P"‎ و‎"DL"‎ و‎"BLOCKQUOTE"‎). لكنّ متصفّح IE يدعم فقط وسوم الترويسات من H1 إلى H6 والوسم ADDRESS والوسم PRE، والتي يجب أن تشمل علامات <> كذلك كما في الوسم ‎"‎‎<H1‎>‎"‎‎.

forwardDelete

يحذف المحرف الموجود أمام موقع مؤشّر الكتابة (علامة الإقحام). وله نفس تأثير الضّغط على زرّ DELETE في لوحة المفاتيح.

heading

يُضيف وسم ترويسة حول نصّ مظلّل أو سطر نقطة إدخال. يتطلّب الأمر تمرير سلسلة نصيّة تمثّل اسم الوسم إلى الأمر كمُعامل (مثل‎‎ ‎"‎H1"‎ أو ‎"H6"‎) (غير مدعوم في متصفّح IE ومتصفّح Safari).

hiliteColor

يُغيّر لون خلفيّة النّص المظلَّل أو في نقطة الإدخال. هذا يتطلّب تمرير سلسلة نصيّة تمثّل قيمة اللون إلى الأمر كمُعامل. يجب تفعيل الخيار UseCSS ليعمل هذا (غير مدعوم في متصفّح IE).

increaseFontSize

يُضيف وسم BIG حول النّص المظلَّل أو في نقطة الإدخال. (غير مدعوم في متصفّح IE).

indent

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

insertBrOnReturn

يتحكّم فيما إذا كان زرّ ENTER على لوحة المفاتيح سيُدخل وسم br أو سيقسم وسم الكتلة الحاليّ إلى اثنين. (غير مدعوم في متصفّح IE).

insertHorizontalRule

يُدخل مسطرة أفقيّة (<hr>) عند نقطة الإدخال (ويحذف النصّ المظلّل).

insertHTML

يُدخل سلسلة نصيّة تحتوي على شيفرة HTML عند نقطة الإدخال (ويحذف النصّ المظلّل). يتطلّب تمرير سلسلة نصيّة تمثّل شيفرة HTML صالحة كمُعامل للأمر (غير مدعوم في متصفّح IE).

insertImage

يُدخل صورةً عند نقطة الإدخال (ويحذف النصّ المظلّل). هذا يتطلّب تمرير سلسلة نصيّة تحتوي على عنوان URI الصورة إلى الأمر كمُعامل، يجب على عنوان URI أن يحتوي على الأقل على محرف واحد يُمكن له أن يكون مساحةً بيضاء (يُمكن أن ينشئ متصفّح IE رابطًا بقيمة عنوان URI تُساوي null).

insertOrderedList

ينشئ قائمةً مرتّبةً مرقّمةً للنّص المظلَّل أو عند نقطة الإدخال.

insertUnorderedList

ينشئ قائمةً منقّطةً غير مرتّبةٍ للنّص المظلَّل أو عند نقطة الإدخال.

insertParagraph

يُدخل فقرةً حول النّص المظلَّل أو السّطر الحالي. (يُدخل متصفّح IE فقرة عند نقطة الإدخال ويحذف النّص المظلّل).

insertText

يُدخل النّص المعطى عند نقطة الإدخال (ويحذف النصّ المظلّل).

italic

يغيّر بين ميلان الخطّ وعدمه للنّص المظلّل أو عند نقطة الإدخال. يستعمل متصفّح IE الوسم <em> عوضًا عن الوسم <i>.

justifyCenter

يضع النّص المظلَّل أو نقطة الإدخال في المنتصف.

justifyFull

يضبط طول النّص المظلَّل أو نقطة الإدخال بمساحات مناسبة لتكون الأسطر متساوية الطّول.

justifyLeft

ينقل النّص المظلَّل أو نقطة الإدخال إلى اليسار.

justifyRight

ينقل النّص المظلَّل أو نقطة الإدخال إلى اليمين.

outdent

يزيل الإزاحة عن السّطر الذي يحتوي على النّص المظلَّل أو نقطة الإدخال.

paste

يلصق محتويات الحافظة عند نقطة الإدخال (ويُبدِل النّص المظلّل). وهو مُعطّل لمحتويات الويب.

redo

إعادة تنفيذ آخر أمر مُلغَى.

removeFormat

إزالة كامل التّنسيق للنّص المظلَّل.

selectAll

يُظلّل كامل محتويات المكان القابل للتّعديل.

strikeThrough

يُشطّب أو يُزيل التّشطيب على النّص المظلَّل أو في نقطة الإدخال.

subscript

يُفعّل أو يُعطّل الرموز السّفليّة على النّص المظلَّل أو في نقطة الإدخال.

superscript

يُفعّل أو يُعطّل الرموز العلويّة على النّص المظلَّل أو في نقطة الإدخال.

underline

يُفعّل أو يُعطّل السّطر السّفلي على النّص المظلَّل أو في نقطة الإدخال.

undo

يُلغي آخر أمر نُفِّذ.

unlink

يُزيل الرّابط على الرّابط المظلَّل.

useCSS

خيارٌ لاستخدام وسوم HTML أو تنسيقات CSS للهيكلة المولَّدة. وهو أمر مهمل لا يجب استخدامه، استخدم الأمر styleWithCSS عوضًا عنه.

styleWithCSS

استبدل الأمر useCSS، يتطلّب تمرير قيمة منطقيّة true (يُعدّل أو يُولّد تنسيقات CSS في الهيكلة) أو false (يولّد عناصر مُنسِّقة) كمعامل.

مثال

انظر هذا المثال على CodePen.

دعم المتصفّحات

الميزة	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	نعم	نعم	نعم	؟	؟	نعم
insertBrOnReturn	لا	لا	نعم	لا	لا	لا
copy وcut	نعم	نعم	41	9	29	10
defaultParagraphSeparator	نعم	نعم	55	لا	نعم	لا

مصادر ومواصفات

• مواصفة HTML Editing APIs