Document: execCommand() メソッド - Web API | MDN

Toggle sidebar

Theme

OS default
Light
Dark

日本語

Remember language Learn more

Document: execCommand() メソッド

非推奨;: この機能は非推奨になりました。まだ対応しているブラウザーがあるかもしれませんが、すでに関連するウェブ標準から削除されているか、削除の手続き中であるか、互換性のためだけに残されている可能性があります。使用を避け、できれば既存のコードは更新してください。このページの下部にある互換性一覧表を見て判断してください。この機能は突然動作しなくなる可能性があることに注意してください。

非標準: この機能は標準化されていません。非標準の機能はブラウザーの対応が限られ、将来的に変更または削除される可能性があるため、本番環境での使用は推奨されません。ただし、標準の選択肢が存在しない特定のケースでは、有効な代替手段となる場合があります。

メモ: execCommand() メソッドは非推奨となっていますが、まだ有効な代替手段を持たない有効な用途がいくつか存在します。例えば、直接的な DOM 操作とは異なり、execCommand() による変更では、取り消しバッファー（編集履歴）が保持されます。このような用途では、引き続きこのメソッドを使用することができますが、document.queryCommandSupported() などを使用して、ブラウザー間の互換性を検証してください。

execCommand メソッドは、複数の異なるコマンドを実装しています。クリップボードへのアクセスを提供するものもあれば、フォーム入力フィールドや contenteditable の要素、文書全体（デザインモードに切り替えた場合）を編集するためのものもあります。

クリップボードにアクセスするには、execCommand() よりも新しいクリップボード API が推奨されます。

多くのコマンドは、文書の選択範囲に対して影響を及ぼします。例えば、一部のコマンド（太字、斜体など）は現在選択されているテキストを整形する一方で、他のコマンドは選択範囲を削除したり、新しい要素を挿入したり（選択範囲を置き換えたり）、行全体に影響を与えたり（インデント）します。変更することができるのは現在アクティブになっている編集可能な要素だけですが、一部のコマンド（copyなど）は編集可能な要素がなくても動作します。

メモ: execCommand() によって行われた変更は、ブラウザーや構成によって beforeinput と input イベントを発生させる場合と発生させない場合があります。起動されると、イベントのハンドラーは execCommand() を返す前に実行されます。制作者はこのような再帰的な呼び出し、特にこれらのイベントに応答して execCommand() を呼び出す場合には注意が必要です。Firefox 82 以降、入れ子になった execCommand() 呼び出しは常に失敗します。バグ 1634262 を参照してください。

構文

execCommand(commandName, showDefaultUI, valueArgument)

引数

commandName

文字列で、実行するコマンドの名前を指定します。以下のコマンドが使用できます。

backColor

文書の背景色を変更します。 styleWithCss モードでは、文書ではなく含まれているブロックの背景色に影響します。この場合、引数として <color> 値の文字列を渡す必要があります。

bold

選択範囲または挿入位置の太字のオンとオフを切り替えます。

contentReadOnly

内容の文書の読み取り専用または編集可能を切り替えます。引数として true または false の論理値が必要です。

copy

現在の選択範囲をクリップボードにコピーします。この動作が有効になる条件は、ブラウザーによって様々であり、時の経過により発展する可能性があります。このコマンドが使用可能かどうかは、ブラウザーの互換性の節で確認してください。

createLink

選択範囲からハイパーリンクを作成しますが、選択範囲があるときだけです。ハイパーリンクの href の引数として、URI 文字列が必要です。 URI は少なくとも1文字を含む必要があり、ホワイトスペースでもかまいません。

cut

現在の選択範囲を除去して、クリップボードにコピーします。いつこの動作が有効になるかはブラウザーによって様々であり、条件は時期によって変化しています。使用方法の詳細は互換性一覧表で確認してください。

decreaseFontSize

選択範囲の前後または挿入位置に <small> タグを追加します。

defaultParagraphSeparator

編集可能なテキスト領域に新しい段落が作成された時の、段落区切りを変更します。

delete

現在の選択範囲を削除します。

enableAbsolutePositionEditor

絶対配置の要素を移動させるためのグラバーを有効化または無効化します。 Firefox 64 以降では、既定で無効です。 (Firefox バグ 1490641)

enableInlineTableEditing

表の行/列の挿入・削除コントロールを有効または無効にします。 Firefox 64 以降では、既定で無効です。 (Firefox バグ 1490641)

enableObjectResizing

画像、表、絶対配置の要素、などの大きさの変更が可能なオブジェクトにおいて、大きさ変更用のハンドルを有効化または無効化します。 Firefox 64 以降では、既定で無効です。 (Firefox バグ 1490641)

fontName

選択範囲または挿入位置のフォント名を変更します。引数としてフォント名の文字列（"Arial" など）が必要です。

fontSize

選択範囲または挿入位置のフォントサイズを変更します。引数として 1 - 7 の整数値が必要です。

foreColor

選択範囲または挿入位置のフォント色を変更します。引数として 16 進表記で色の値の文字列が必要です。

formatBlock

現在の選択範囲を含む行の前後に HTML ブロックレベル要素を追加し、すでに存在する場合は、その行を含むブロック要素に置き換えます (Firefox では <blockquote> は例外です。 — これはブロック要素を囲みます)。引数としてタグ名の文字列が必要です。実質的にすべてのブロックレベル要素を利用することができます。（古い Edge は見出しタグ H1–H6, ADDRESS, PRE のみに対応しており、"<H1>" のように山かっこで囲む必要があります。）

forwardDelete

カーソル位置より前の文字を 1 文字削除します。これは、 Windows のキーボードで Delete キーを押すのと同じ動作です。

heading

選択範囲または挿入位置の行の周りに見出し要素を追加します。引数としてタグ名の文字列（つまり "H1" や "H6"）が必要です。 (Safari は対応していません。)

hiliteColor

選択範囲または挿入位置の背景色を変更します。引数として color 値の文字列が必要です。この機能は useCSS を true にしないと使えません。

increaseFontSize

選択範囲または挿入位置に <big> タグを追加します。

indent

選択範囲または挿入位置を含む行を字下げします。Firefox では、選択範囲が字下げレベルの異なる複数行にわたる場合、選択範囲内の最も字下げの少ない行のみが字下げされます。

insertBrOnReturn

Enter キーで <br> 要素を挿入するか現在のブロック要素を二分割するかを制御します。

insertHorizontalRule

挿入位置に <hr> 要素を挿入するか、選択範囲を置き換えるかします。

insertHTML

挿入位置に HTML マークアップの TrustedHTML インスタンスまたは文字列を挿入します (選択範囲は削除されます)。正しい HTML マークアップが必要です。

警告: 入力は HTML として構文解析され、DOM に書き込まれます。このような API はインジェクションシンクと呼ばれ、入力が攻撃者から来たものであれば、クロスサイトスクリプティング (XSS)攻撃の経路となる可能性があります。

このリスクを軽減するには、文字列の代わりに常に TrustedHTML オブジェクトを割り当て、信頼型を強制するようにしてください。詳しくは信頼型 API を参照してください。

insertImage

挿入位置に画像を挿入します (選択範囲は削除されます)。引数として画像の src のための URL 文字列が必要です。この文字列の要求事項は、 createLink と同じです。

insertLineBreak

選択範囲を削除し、改行要素で置き換えます。

insertOrderedList

選択範囲または挿入位置に番号付き順序付きリストを生成します。

insertUnorderedList

選択範囲または挿入位置行頭記号付き順序なしリストを生成します。

insertParagraph

選択範囲の前後または現在の行に段落を挿入します。

insertText

挿入位置に与えられたプレーンテキストを挿入します (選択範囲は削除されます)。

italic

選択範囲または挿入位置のイタリック体のオンとオフを切り替えます。

justifyCenter

選択範囲または挿入位置を中央揃えにします。

justifyFull

選択範囲または挿入位置を両端揃えにします。

justifyLeft

選択範囲または挿入位置を左寄せにします。

justifyRight

選択範囲または挿入位置を右寄せにします。

outdent

選択範囲または挿入位置を含む行の字下げを戻します。

paste

クリップボードのコンテンツを挿入位置に貼り付け（ペースト）します（現在の選択範囲は置き換えられます）。

この機能はウェブコンテンツでは無効とされていますが、一部のブラウザーではクリップボード API を通じて実装されています。これらのブラウザーでは、この機能を利用するには一時的な活性化が要求され、また、オリジンを越えたコンテンツを貼り付ける際にはポップアップ UI の確認が必要です。詳しくは、ブラウザーの互換性一覧表を参照してください。

redo

前回の undo コマンドを元に戻します。

removeFormat

現在の選択範囲からすべての書式を削除します。

selectAll

編集可能領域のすべてのコンテンツを選択します。

strikeThrough

選択範囲または挿入位置の取り消し線のオンとオフを切り替えます。

subscript

選択範囲または挿入位置の下付き文字のオンとオフを切り替えます。

superscript

選択範囲または挿入位置の上付き文字のオンとオフを切り替えます。

underline

選択範囲または挿入位置の下線のオンとオフを切り替えます。

undo

最後に実行したコマンドを取り消します。

unlink

選択されたハイパーリンクからアンカー要素を削除します。

useCSS

生成するマークアップに HTML タグと CSS のどちらを使用するかを切り替えます。引数として true/false の論理値が必要です。

メモ: この引数は論理が逆です（つまり、false で CSS が使用され、true で HTML が使用される）。これは styleWithCSS に置き換えられ、非推奨になりました。

styleWithCSS

useCSS コマンドを置き換えるものです。true はマークアップ時に style 属性が生成または変更され、false では書式要素が生成されます。

AutoUrlDetect

ブラウザーの自動リンクの動作を変更します。

showDefaultUI

論理値で、既定のユーザーインターフェイスを表示するかどうかを指示します。 Mozilla では未実装です。

valueArgument

入力引数を必要とするコマンド向けのもので、その情報を提供する文字列です。例えば、 insertImage では挿入する画像の URL です。引数が不要な場合は null を指定してください。

返値

論理値で、コマンドが対応していないか無効であれば false になります。

メモ: document.execCommand() はユーザーの操作の中で行われた場合にのみ true を返します。コマンドを呼び出す前に、ブラウザーが対応しているかどうかを調べるために返値を使用しないでください。

例

insertText の使用

この例では、2 つの非常に基本的な HTML エディターを示しています。<textarea> 要素を用いたものと、 <pre> 要素に contenteditable 属性を設定したものを用いたものです。

"Bold" または "Italic" ボタンをクリックすると、要素に適切なタグが挿入され、insertText を使用して編集履歴が保存されるので、ユーザーは操作を元に戻すことができます。

HTML

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">いくらかのテキスト。</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">いくらかのテキスト。</pre>

JavaScript

js
// アクションボタンを準備
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),
    );
  }
}

// カーソルの位置にテキストを挿入するか、選択したテキストを置き換えます
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("貼り付けに失敗しました。execCommand に対応していません。");
  }
}

結果

paste の使用

この例には、<textarea> 要素と、そこにコンテンツを貼り付けるために使用することができる <button> 要素が含まれています。

HTML

html
<button id="paste">貼り付け</button>
<hr />
<textarea id="text_box">いくらかのテキスト。</textarea>

JavaScript

js
const pasteButton = document.querySelector("#paste");
const textBox = document.querySelector("#text_box");

pasteButton.addEventListener("click", () => {
  textBox.focus();

  let pasted = document.execCommand("paste", false);
  if (!pasted) {
    textBox.textContent =
      "貼り付けに失敗しました。execCommand に対応していません。";
  }
});

結果

クリップボード API を使用してこの機能を実装しているブラウザーでは、テキストエリア内のテキストなど、同一オリジンのコンテンツをコピーし、それを貼り付けて選択されているコンテンツを置き換えることができるはずです。他のページや場所からコピーしたテキストなど、オリジンを越えるコンテンツを貼り付けようとする場合は、まず表示される「貼り付け」 UI を選択する必要があります。