الفرق بين المراجعتين لصفحة: «JavaScript/Document/execCommand»

المراجعة الحالية بتاريخ 16:05، 7 أكتوبر 2022

عندما ينتقل مستند 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 العنصر  عوضًا عن العنصر .

`contentReadOnly`

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

`copy`

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

`createLink`

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

`cut`

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

`decreaseFontSize`

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

`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

@@ سطر 14: / سطر 14: @@
 ====<code>aShowDefaultUI</code>====
-قيمة منطقيّة <code>[[JavaScript/Boolean|Boolean]]</code> تشير إلى ما إذا وجب عرض واجهة المستخدم الافتراضيّة. هذا المعامل غير متوفّر في متصفّح FireFox.
+قيمة منطقيّة <code>[[JavaScript/Boolean|Boolean]]</code> تشير إلى ما إذا وجب عرض واجهة المستخدم الافتراضيّة. هذا المعامل غير متوافر في متصفّح FireFox.
 ====<code>aValueArgument</code>====
@@ سطر 21: / سطر 21: @@
 ===الأوامر===
 ====<code>backColor</code>====
-يُغيّر لون خلفيّة المستند. في نمط <code>backColor</code>، يؤثّر الأمر على لون خلفيّة الكتلة المُحتَوية (containing block) عوضًا عن ذلك. يتطلّب هذا تمرير سلسلة نصيّة من النّوع <code><color></code> كمُعامل. لاحظ أنّ متصفّح IE يستعمل هذا الأمر لضبط لون خلفيّة النّص.
+يُغيّر لون خلفيّة المستند. في نمط <code>backColor</code>، يؤثّر الأمر على لون خلفيّة الكتلة المُحتَوية (containing block) عوضًا عن ذلك. يتطلّب هذا تمرير سلسلة نصيّة من النّوع <code>[[CSS/color value|<color>]]</code> كمُعامل. لاحظ أنّ متصفّح IE يستعمل هذا الأمر لضبط لون خلفيّة النّص.
 ====<code>bold</code>====
-يضبط ما إذا كان النّص عريضًا أو لا للنصّ المُظلّل أو النّص في نقطة الإدخال. يستعمل IE الوسم <code>[[HTML/strong|<nowiki><strong></nowiki>]]</code> عوضًا عن الوسم <code>[[HTML/b|<nowiki><b></nowiki>]]</code>.
+يضبط ما إذا كان النّص عريضًا أم لا للنصّ المُظلّل أو النّص في نقطة الإدخال. يستعمل IE العنصر <code>[[HTML/strong|<nowiki><strong></nowiki>]]</code> عوضًا عن العنصر <code>[[HTML/b|<nowiki><b></nowiki>]]</code>.
 ====<code>contentReadOnly</code>====
-يجعل من محتوى النّص قابلًا للقراءة فقط أو قابلًا للتّعديل. هذا الأمر يتطلّب تمرير قيمة منطقيّة <code>true</code> أو <code>false</code> كمُعامل. (غير مدعوم في متصفّح IE).
+يجعل من محتوى النّص قابلًا للقراءة فقط أو قابلًا للتّعديل. هذا الأمر يتطلّب تمرير قيمة منطقيّة <code>true</code> أو <code>false</code> كمُعامل (غير مدعوم في متصفّح IE).
 ====<code>copy</code>====
-ينسخ النّص المظلّل حاليًّا إلى الحافظة (clipboard). تتفاوت شروط تفعيل هذا الأمر من متصفّح إلى آخر. انظر جدول المتصفّحات المدعومة للتحقّق ممّا إذا كان في مقدورك استعماله في حالتك أو لا.
+ينسخ النّص المظلّل حاليًّا إلى الحافظة (clipboard). تتفاوت شروط تفعيل هذا الأمر من متصفّح إلى آخر. انظر جدول المتصفّحات المدعومة للتحقّق ممّا إذا كان في مقدورك استعماله في حالتك أم لا.
 ====<code>createLink</code>====
-ينشئ رابطًا من النّص المظلّل في حالة كان هناك نصّ مظلّل.  هذا يتطلّب تمرير سلسلة نصيّة تحتوي على عنوان URI الرّابط إلى الأمر كمُعامل، يجب على عنوان URI أن يحتوي على الأقل على محرف واحد يُمكن له أن يكون مساحةً بيضاء. (يُمكن أن ينشئ متصفّح IE رابطًا بقيمة عنوان URI تُساوي <code>null</code>).
+ينشئ رابطًا من النّص المظلّل في حالة كان هناك نصّ مظلّل. هذا يتطلّب تمرير سلسلة نصيّة تحتوي على عنوان URI الرّابط إلى الأمر كمُعامل، يجب على عنوان URI أن يحتوي على الأقل على محرف واحد يُمكن له أن يكون مساحةً بيضاء (يُمكن أن ينشئ متصفّح IE رابطًا بقيمة عنوان URI تُساوي <code>null</code>).
 ====<code>cut</code>====
-يقصّ النصّ المُظلّل حاليًّا وينسخه إلى الحافظة. تتفاوت شروط تفعيل هذا الأمر من متصفّح إلى آخر. انظر جدول المتصفّحات المدعومة للتحقّق ممّا إذا كان في مقدورك استعماله في حالتك أو لا.
+يقصّ النصّ المُظلّل حاليًّا وينسخه إلى الحافظة. تتفاوت شروط تفعيل هذا الأمر من متصفّح إلى آخر. انظر جدول المتصفّحات المدعومة للتحقّق ممّا إذا كان في مقدورك استعماله في حالتك أم لا.
 ====<code>decreaseFontSize</code>====
-يُضيف وسم <code>[[HTML/small|<nowiki><small></nowiki>]]</code> حول النصّ المُظلّل أو في نقطة الإدخال. (غير مدعوم في متصفّح IE).
+يُضيف العنصر <code>[[HTML/small|<nowiki><small></nowiki>]]</code> حول النصّ المُظلّل أو في نقطة الإدخال (غير مدعوم في متصفّح IE).
 ====<code>defaultParagraphSeparator</code>====
-يغيّر فاصل الفقرات (paragraph separator) المُستخدَم عند إنشاء فقرات جديدة في أمكنة النّصوص القابلة للتّعديل. انظر صفحة [https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Editable_content#Differences_in_markup_generation الفروقات في توليد الهيكلة] للمزيد من المعلومات.
+يغيّر فاصل الفقرات (paragraph separator) المُستخدَم عند إنشاء فقرات جديدة في أمكنة النّصوص القابلة للتّعديل.
 ====<code>delete</code>====
 يحذف النصّ المظلَّل حاليًّا.
@@ سطر 48: / سطر 48: @@
 ====<code>enableObjectResizing</code>====
-يُفعّل أو يُعطّل مقابض التحكم في الحجم على الصور والكائنات الأخرى القابلة لإعادة ضبط حجمها. (غير مدعوم في متصفّح IE).
+يُفعّل أو يُعطّل مقابض التحكم في الحجم على الصور والكائنات الأخرى القابلة لإعادة ضبط حجمها (غير مدعوم في متصفّح IE).
 ====<code>fontName</code>====
 يُغيّر اسم الخطّ للنّص المُظلّل أو في نقطة الإدخال. هذا يتطلّب تمرير سلسلة نصيّة تمثّل اسم الخطّ (<code>‎"‎Arial‎"‎</code> مثلًا) إلى الأمر كمُعامل.
@@ سطر 64: / سطر 64: @@
 ====<code>heading</code>====
-يُضيف وسم ترويسة حول نصّ مظلّل أو سطر نقطة إدخال.  يتطلّب الأمر تمرير سلسلة نصيّة تمثّل اسم الوسم إلى الأمر كمُعامل (مثل‎‎ ‎"‎H1"‎ أو ‎"H6"‎). (غير مدعوم في متصفّح IE ومتصفّح Safari).
+يُضيف وسم ترويسة حول نصّ مظلّل أو سطر نقطة إدخال.  يتطلّب الأمر تمرير سلسلة نصيّة تمثّل اسم الوسم إلى الأمر كمُعامل (مثل‎‎ ‎"‎H1"‎ أو ‎"H6"‎) (غير مدعوم في متصفّح IE ومتصفّح Safari).
 ====<code>hiliteColor</code>====
-يُغيّر لون خلفيّة النّص المظلَّل أو في نقطة الإدخال. هذا يتطلّب تمرير سلسلة نصيّة تمثّل قيمة اللون إلى الأمر كمُعامل. يجب تفعيل الخيار <code>UseCSS</code> ليعمل هذا. (غير مدعوم في متصفّح IE).
+يُغيّر لون خلفيّة النّص المظلَّل أو في نقطة الإدخال. هذا يتطلّب تمرير سلسلة نصيّة تمثّل قيمة اللون إلى الأمر كمُعامل. يجب تفعيل الخيار <code>UseCSS</code> ليعمل هذا (غير مدعوم في متصفّح IE).
 ====<code>increaseFontSize</code>====
@@ سطر 79: / سطر 79: @@
 ====<code>insertHorizontalRule</code>====
-يُدخل مسطرة أفقيّة عند نقطة الإدخال (ويحذف النصّ المظلّل).
+يُدخل مسطرة أفقيّة (<code>[[HTML/hr|<nowiki><hr></nowiki>]]</code>) عند نقطة الإدخال (ويحذف النصّ المظلّل).
 ====<code>insertHTML</code>====
-يُدخل سلسلة نصيّة تحتوي على شيفرة HTML عند نقطة الإدخال (ويحذف النصّ المظلّل). يتطلّب تمرير سلسلة نصيّة تمثّل شيفرة HTML صالحة كمُعامل للأمر. (غير مدعوم في متصفّح IE).
+يُدخل سلسلة نصيّة تحتوي على شيفرة HTML عند نقطة الإدخال (ويحذف النصّ المظلّل). يتطلّب تمرير سلسلة نصيّة تمثّل شيفرة HTML صالحة كمُعامل للأمر (غير مدعوم في متصفّح IE).
 ====<code>insertImage</code>====
-يُدخل صورةً عند نقطة الإدخال (ويحذف النصّ المظلّل). هذا يتطلّب تمرير سلسلة نصيّة تحتوي على عنوان URI الصورة إلى الأمر كمُعامل، يجب على عنوان URI أن يحتوي على الأقل على محرف واحد يُمكن له أن يكون مساحةً بيضاء. (يُمكن أن ينشئ متصفّح IE رابطًا بقيمة عنوان URI تُساوي <code>null</code>).
+يُدخل صورةً عند نقطة الإدخال (ويحذف النصّ المظلّل). هذا يتطلّب تمرير سلسلة نصيّة تحتوي على عنوان URI الصورة إلى الأمر كمُعامل، يجب على عنوان URI أن يحتوي على الأقل على محرف واحد يُمكن له أن يكون مساحةً بيضاء (يُمكن أن ينشئ متصفّح IE رابطًا بقيمة عنوان URI تُساوي <code>null</code>).
 ====<code>insertOrderedList</code>====
 ينشئ قائمةً مرتّبةً مرقّمةً للنّص المظلَّل أو عند نقطة الإدخال.
@@ سطر 146: / سطر 146: @@
 ====<code>useCSS</code>====
-خيارٌ لاستخدام وسوم HTML أو تنسيقات CSS للهيكلة المولَّدة. وهو أمر مهمل لا يجب استخدامه، استخدم الأمر <code>styleWithCSS</code> عوضًا عنه.
+خيارٌ لاستخدام وسوم HTML أو تنسيقات [[CSS]] للهيكلة المولَّدة. وهو أمر مهمل لا يجب استخدامه، استخدم الأمر <code>styleWithCSS</code> عوضًا عنه.
 ====<code>styleWithCSS</code>====
-يُبدل الأمر <code>useCSS</code>، يتطلّب تمرير قيمة منطقيّة <code>true</code> (يُعدّل أو يُولّد تنسيقات CSS في الهيكلة) أو <code>false</code> (يولّد عناصر مُنسِّقة) كمعامل.
+استبدل الأمر <code>useCSS</code>، يتطلّب تمرير قيمة منطقيّة <code>true</code> (يُعدّل أو يُولّد تنسيقات CSS في الهيكلة) أو <code>false</code> (يولّد عناصر مُنسِّقة) كمعامل.
 ==مثال==