Документ: метод execCommand()

Устаревшее: Эта функция больше не рекомендуется. Хотя некоторые браузеры могут её всё ещё поддерживать, она может быть уже удалена из соответствующих веб-стандартов, находится в процессе удаления или поддерживается только для совместимости. Избегайте её использования и, если возможно, обновите существующий код; обратитесь к таблице совместимости в конце этой страницы для принятия решения. Имейте в виду, что эта функция может перестать работать в любой момент.

Метод execCommand реализует множество различных команд. Некоторые из них предоставляют доступ к буферу обмена, а другие предназначены для редактирования форменных элементов, contenteditable элементов или целых документов (при переключении в режим проектирования).

Для доступа к буферу обмена рекомендуется использовать новый API буфера обмена вместо execCommand(). Однако нет замены для команд редактирования: в отличие от прямой манипуляции DOM, изменения, выполняемые execCommand() сохраняют буфер отмены (историю редактирования).

Большинство команд влияют на выделение документа. Например, некоторые команды (жирный шрифт, курсив и т. д.) форматируют текущий выделенный текст, в то время как другие удаляют выделение, вставляют новые элементы (заменяя выделение) или влияют на целую строку (отступ). Модифицироваться может только активный редактируемый элемент, но некоторые команды (например, copy) могут работать без редактируемого элемента.

Примечание: Изменения, выполняемые execCommand() могут или не могут вызывать события beforeinput и input, в зависимости от браузера и конфигурации. Если они вызваны, обработчики событий будут выполнены до того, как execCommand() вернётся. Разработчикам следует быть осторожными при таких рекурсивных вызовах, особенно если они вызывают execCommand() в ответ на эти события. Начиная с Firefox 82, вложенные вызовы execCommand() всегда будут завершаться ошибкой, см. баг 1634262.

Синтаксис

execCommand(aCommandName, aShowDefaultUI, aValueArgument)

Параметры

aCommandName: Строка, указывающая имя команды для выполнения. Ниже перечислены поддерживаемые команды:

backColor: Изменяет цвет фона документа. В режиме styleWithCss это влияет на цвет фона содержащего блока. Требуется строка значения <color> в качестве аргумента значения.
bold: Включает/выключает жирный шрифт для выделенного фрагмента или в точке вставки.
contentReadOnly: Делает содержимое документа только для чтения или редактируемым. Требуется логическое значение true/false в качестве аргумента значения.
copy: Копирует текущий выделенный фрагмент в буфер обмена. Условия включения этого поведения зависят от браузера и эволюционировали со временем. Проверьте таблицу совместимости, чтобы определить, можете ли вы использовать эту функцию в вашем случае.
createLink: Создаёт гиперссылку из выделенного фрагмента, только если есть выделение. Требуется строка URI в качестве аргумента значения для href гиперссылки. URI должен содержать хотя бы один символ, который может быть пробелом.
cut: Удаляет текущий выделенный фрагмент и копирует его в буфер обмена. Условия включения этой функции зависят от браузера и эволюционировали со временем. Проверьте таблицу совместимости для получения подробностей о её использовании.
decreaseFontSize: Добавляет тег <small> вокруг выделенного фрагмента или в точке вставки.
defaultParagraphSeparator: Изменяет разделитель абзацев, используемый при создании новых абзацев в редактируемых областях текста.
delete: Удаляет текущий выделенный фрагмент.
enableAbsolutePositionEditor: Включает или выключает маркер, позволяющий перемещать элементы с абсолютным позиционированием. Маркер отключен по умолчанию в Firefox 64 (Firefox bug 1490641).
enableInlineTableEditing: Включает или выключает элементы управления вставкой и удалением строк/столбцов таблицы. Элементы управления отключены по умолчанию в Firefox 64 (Firefox bug 1490641).
enableObjectResizing: Включает или выключает маркеры изменения размера изображений, таблиц и элементов с абсолютным позиционированием и других объектов, допускающих изменение размера. Маркеры отключены по умолчанию в Firefox 64 (Firefox bug 1490641).
fontName: Изменяет имя шрифта для выделенного фрагмента или в точке вставки. Требуется строка имени шрифта (например, "Arial") в качестве аргумента значения.
fontSize: Изменяет размер шрифта для выделенного фрагмента или в точке вставки. Требуется целое число от 1 до 7 в качестве аргумента значения.
foreColor: Изменяет цвет шрифта для выделенного фрагмента или в точке вставки. Требуется строка шестнадцатеричного значения цвета в качестве аргумента.
formatBlock: Добавляет HTML-элемент уровня блока вокруг строки, содержащей текущий выделенный фрагмент, заменяя элемент блока, содержащий строку, если он существует (в Firefox, <blockquote> — исключение, он обернёт любой содержащий элемент блока). Требуется строка имени тега в качестве аргумента значения. Практически все элементы уровня блока могут быть использованы. (Legacy Edge поддерживает только теги заголовков H1 – H6, ADDRESS, и PRE, которые должны быть заключены в угловые скобки, например, "<H1>".)
forwardDelete: Удаляет символ перед позицией курсора, идентично нажатию клавиши Delete на клавиатуре Windows.
heading: Добавляет элемент заголовка вокруг строки с выделением или точкой вставки. Требуется строка имени тега в качестве аргумента значения (например, "H1", "H6"). (Не поддерживается Safari.)
highlightColor: Изменяет цвет фона выделенного фрагмента или в точке вставки. Требуется строка значения цвета в качестве аргумента. useCSS должен быть true для корректной работы.
increaseFontSize: Добавляет тег <big> вокруг выделенного фрагмента или в точке вставки.
indent: Отступает строку, содержащую выделенный фрагмент или точку вставки. В Firefox, если выделение охватывает несколько строк на разных уровнях отступов, отступятся только наименее отступаемые строки в выделении.
insertBrOnReturn: Управляет тем, вставляет ли клавиша Enter элемент <br>, или разделяет текущий элемент блока на два.
insertHorizontalRule: Вставляет элемент <hr> в точку вставки или заменяет им выделенный фрагмент.
insertHTML: Вставляет строку HTML в точку вставки (удаляет выделение). Требуется допустимая строка HTML в качестве аргумента значения.
insertImage: Вставляет изображение в точку вставки (удаляет выделение). Требуется строка URL для src изображения в качестве аргумента значения. Требования к этой строке такие же, как и к createLink.
insertOrderedList: Создаёт нумерованный упорядоченный список для выделенного фрагмента или в точке вставки.
insertUnorderedList: Создаёт маркированный неупорядоченный список для выделенного фрагмента или в точке вставки.
insertParagraph: Вставляет абзац вокруг выделенного фрагмента или текущей строки.
insertText: Вставляет заданный обычный текст в точку вставки (удаляет выделение).
italic: Включает/выключает курсив для выделенного фрагмента или в точке вставки.
justifyCenter: Центрирует выделенный фрагмент или точку вставки.
justifyFull: Выравнивает выделенный фрагмент или точку вставки по ширине.
justifyLeft: Выравнивает выделенный фрагмент или точку вставки по левому краю.
justifyRight: Выравнивает выделенный фрагмент или точку вставки по правому краю.
outdent: Уменьшает отступ строки, содержащей выделенный фрагмент или точку вставки.
paste: Вставляет содержимое буфера обмена в точку вставки (заменяет текущий выделенный фрагмент). Отключено для веб-контента.
redo: Повторяет предыдущую отмену.
removeFormat: Удаляет все форматирование из текущего выделенного фрагмента.
selectAll: Выделяет всё содержимое редактируемой области.
strikeThrough: Включает/выключает зачёркивание для выделенного фрагмента или в точке вставки.
subscript: Включает/выключает подстрочный шрифт для выделенного фрагмента или в точке вставки.
superscript: Включает/выключает надстрочный шрифт для выделенного фрагмента или в точке вставки.
underline: Включает/выключает подчёркивание для выделенного фрагмента или в точке вставки.
undo: Отменяет последнюю выполненную команду.
unlink: Удаляет элемент якоря из выбранной гиперссылки.
useCSS Устаревшее: Переключает использование HTML-тегов или CSS для сгенерированной разметки. Требуется логическое значение true/false в качестве аргумента значения.

Примечание: Этот аргумент логически обратный (т.е., используйте false для использования CSS, true для использования HTML). Это устарело в пользу styleWithCSS.
styleWithCSS

Заменяет команду useCSS. true изменяет/генерирует style атрибуты в разметке, false генерирует презентационные элементы.
AutoUrlDetect: Изменяет поведение автоматического создания ссылок браузера.

aShowDefaultUI

Логическое значение, указывающее, должен ли быть показан стандартный пользовательский интерфейс. В Mozilla это не реализовано.

aValueArgument

Для команд, требующих входного аргумента, это строка, предоставляющая эту информацию. Например, insertImage требует URL изображения для вставки. Укажите null если аргумент не нужен.

Значение возврата

Логическое значение, которое false если команда не поддерживается или отключена.

Примечание: document.execCommand() возвращает только true если она вызвана в рамках пользовательского взаимодействия. Вы не можете использовать её для проверки поддержки браузера перед вызовом команды.

Примеры

Пример использования execCommand с элементами contentEditable на CodePen.

Использование insertText

Этот пример демонстрирует два очень простых HTML редактора: один использует элемент <textarea>, а другой — элемент <pre> с атрибутом contenteditable.

Нажатие кнопок «Жирный» или «Курсив» вставляет соответствующие теги в элемент, используя insertText для сохранения истории редактирования, чтобы пользователь мог отменить действие.

HTML

<h2>textarea</h2>

<div class="actions" data-for="textarea">
  <button data-el="b">Bold</button>
  <button data-el="i">Italic</button>
</div>

<textarea class="editarea">Some text.</textarea>

<h2>contenteditable</h2>

<div class="actions" data-for="pre">
  <button data-el="b">Bold</button>
  <button data-el="i">Italic</button>
</div>

<pre contenteditable="true" class="editarea">Some text.</pre>

JavaScript

// Prepare action buttons
const buttonContainers = document.querySelectorAll(".actions");

for (const buttonContainer of buttonContainers) {
  const buttons = buttonContainer.querySelectorAll("button");
  const pasteTarget = buttonContainer.getAttribute("data-for");

  for (const button of buttons) {
    const elementName = button.getAttribute("data-el");
    button.addEventListener("click", () =>
      insertText(`<${elementName}></${elementName}>`, pasteTarget),
    );
  }
}

// Inserts text at cursor, or replaces selected text
function insertText(newText, selector) {
  const textarea = document.querySelector(selector);
  textarea.focus();

  let pasted = true;
  try {
    if (!document.execCommand("insertText", false, newText)) {
      pasted = false;
    }
  } catch (e) {
    console.error("error caught:", e);
    pasted = false;
  }

  if (!pasted) {
    console.error("paste unsuccessful, execCommand not supported");
  }
}

Результат

Спецификации

Спецификация не найдена

Данные спецификации не найдены для api.Document.execCommand.
Проверьте проблемы на этой странице или внесите недостающую spec_url в mdn/browser-compat-data. Также убедитесь, что спецификация включена в w3c/browser-specs.

Совместимость с браузерами

	Рабочие столы					Мобильные устройства
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox для Android	Opera Android	Safari на iOS	Samsung Internet	WebView Android
`execCommand`	1	12	69 ["С Firefox 82 вложенные вызовы не поддерживаются (возвращается `false`). См. ошибку 1634262.", "До Firefox 89 работа с содержимым элементов `<input>` и `<textarea>` с помощью команд `Document.execCommand()` требует обходных путей (см. ошибку 1220696)."] 1–69 Поддерживается только для `HTMLDocument`, а не для всех объектов `Document`.	9	1.3	18	79 ["С Firefox для Android 82 вложенные вызовы не поддерживаются (возвращается `false`). См. ошибку 1634262.", "До Firefox для Android 89 работа с содержимым элементов `<input>` и `<textarea>` с помощью команд `Document.execCommand()` требует обходных путей (см. ошибку 1220696)."] 4–79 Поддерживается только для `HTMLDocument`, а не для всех объектов `Document`.	10.1	1	1.0	4.4
`copy`	42	12	41	29	10	42	41	29	10	4.0	42
`cut`	42	12	41	29	10	42	41	29	10	4.0	42
`defaultParagraphSeparator`	Нет	≤18–79	55	Нет	Нет	Нет	55	Нет	Нет	Нет	Нет
`insertBrOnReturn`	Нет	Нет	1.5	Нет	Нет	Нет	4	Нет	Нет	Нет	Нет

См. также

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand