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