document.execCommand

HTML ドキュメントが designMode へ切り替えられると、document オブジェクトは execCommand メソッドを露呈します。このメソッドは、編集可能領域のコンテンツを操作するコマンドを実行します。多くのコマンド (bold、italics、他) は document 内の選択範囲に影響を及ぼしますが、その他に新しい要素を挿入 (リンクを追加) するコマンドや行全体 (字下げ) に影響を及ぼすコマンドもあります。contentEditable を使用した場合、execCommand() メソッドは現在アクティブな編集可能要素に影響を及ぼします。

構文

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

戻り値

コマンドがサポートされていないか有効な場合、Boolean の値は false です。

引数

aCommandName

実行するコマンドの名前を指定する DOMString。使用可能なコマンドの一覧は、Commands セクションをご覧ください。

aShowDefaultUI

デフォルトのユーザインターフェースを表示するかどうかを指示する Boolean 値。Mozilla では未実装です。

aValueArgument

追加の引数を必要とするコマンドの引数 (例えば、insertImage では挿入する画像の URL)。引数の値は DOMString です。引数が不要な場合は null を指定します。

コマンド

backColor

document の背景色を変更します。styleWithCss モードでは、document ではなく含まれているブロックの背景色に影響します。引数として <color> 値の文字列を渡す必要があります。ただし、Internet Explorer はテキストの背景色を設定するのに使用します。

bold

選択範囲または挿入位置の太字のオンとオフを切り替えます。(Internet Explorer は <b> タグではなく、<strong> タグを使用します。)

contentReadOnly

コンテンツドキュメントを読み取り専用または編集可能にします。引数として true または false の真偽値を渡す必要があります。(Internet Explorer ではサポートされていません。)

copy

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

createLink

選択範囲がある場合、選択範囲からアンカーリンクを生成します。引数として HREF URI 文字列を渡す必要があります。この URI には少なくとも 1 文字以上含めてください。空白文字も可能です。 (Internet Explorer は null 値で URI のリンクを生成できます。)

cut

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

decreaseFontSize

選択範囲の前後または挿入位置に <small> タグを追加します。(Internet Explorer ではサポートされていません。)

delete

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

enableInlineTableEditing

table の行および列の挿入・削除コントロールを有効または無効にします。(Internet Explorer ではサポートされていません。)

enableObjectResizing

画像や他のサイズ変更可能なオブジェクトのサイズ変更を有効または無効にします。(Internet Explorer ではサポートされていません。)

fontName

選択範囲または挿入位置のフォント名を変更します。引数としてフォント名 (例えば "Arial") の文字列を渡す必要があります。

fontSize

選択範囲または挿入位置のフォントサイズを変更します。引数として HTML フォントサイズ (1 から 7) の数値を渡す必要があります。

fontColor

選択範囲または挿入位置のフォント色を変更します。引数として color 値の文字列を渡す必要があります。

formatBlock

選択範囲を含む行の前後に HTML ブロック様式のタグを追加し、すでに存在する場合は、その行を含むブロック要素を置き換えます (Firefox では BLOCKQUOTE は例外です。これはブロック要素を包みます)。引数としてタグ名の文字列を渡す必要があります。実際は、すべてのブロック様式のタグ ("H1", "P", "DL", "BLOCKQUOTE" など) が使用可能です。(Internet Explorer は、見出しタグ H1 ～ H6, ADDRESS, PRE のみをサポートし、"<H1>" のようにタグデリミタを含める必要があります。)

forwardDelete

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

heading

選択範囲の前後または挿入位置の行に見出しタグを追加します。引数としてタグ名の文字列 (例、"H1", "H6") を渡す必要があります。(Internet Explorer と Safari ではサポートされていません。)

hiliteColor

選択範囲または挿入位置の背景色を変更します。引数として color 値の文字列を渡す必要があります。この機能は UseCSS をオンにしないと使えません。(Internet Explorer ではサポートされていません。)

increaseFontSize

選択範囲または挿入位置に BIG タグを追加します。(Internet Explorer ではサポートされていません。)

indent

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

insertBrOnReturn

Enter キーで BR タグを挿入するか現在のブロック要素を二分割するかを制御します。(Internet Explorer ではサポートされていません。)

insertHorizontalRule

挿入位置に水平線を挿入します (選択範囲は削除されます)。

insertHTML

挿入位置に HTML 文字列を挿入します (選択範囲は削除されます)。引数として正しい HTML 文字列を渡す必要があります。(Internet Explorer ではサポートされていません。)

insertImage

挿入位置に画像を挿入します (選択範囲は削除されます)。引数として画像の SRC URI 文字列を渡す必要があります。URI には少なくとも 1 文字以上含めてください。空白文字も可能です。(Internet Explorer は null 値で URI のリンクを生成できます。)

insertOrderedList

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

insertUnorderedList

選択範囲または挿入位置に箇条書きリストを生成します。

insertParagraph

選択範囲の前後または現在の行に段落を挿入します。(Internet Explorer は挿入位置に段落を挿入し、現在の選択範囲を削除します。)

insertText

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

italic

選択範囲または挿入位置のイタリック体のオンとオフを切り替えます。(Internet Explorer は I タグではなく、EM タグを使用します。)

justifyCenter

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

justifyFull

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

justifyLeft

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

justifyRight

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

outdent

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

paste

クリップボードのコンテンツを挿入位置に貼り付け (ペースト) します (現在の選択範囲は置き換えられます)。クリップボードの機能は user.js 設定ファイルで有効にしておかなければなりません。注釈 [1] 参照。

redo

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

removeFormat

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

selectAll

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

strikeThrough

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

subscript

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

superscript

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

underline

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

undo

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

unlink

選択されたアンカーリンクからアンカータグを削除します。

useCSS

生成されたマークアップに HTML タグと CSS のどちらを使うかを切り替えます。引数として true または false の真偽値を渡す必要があります。注記: この引数は論理的に逆です。つまり、false で CSS が使用され、true で HTML が使用されます。(Internet Explorer ではサポートされていません。) このコマンドは推奨されません。代わりに styleWithCSS コマンドを使用してください。

styleWithCSS

useCSS コマンドを置き換え、引数が期待通りに動作するコマンドです。つまり、引数に true を渡すとマークアップ内に style 属性が生成または変更され、false を渡すと書式要素が生成されます。

例

CodePen に 使用例 があります。

仕様

ブラウザ実装状況

[1] Firefox 41 より前のバージョンでは、クリップボード機能を user.js 設定ファイルで有効にする必要があります。詳しい情報は、A brief guide to Mozilla preferences を参照してください。コマンドがサポートされていないか有効な場合、execCommand は false を返す代わりに例外を発生させます。Firefox 41 以降では、ウィンドウ (semi-trusted script) をポップアップできるどのイベントハンドラでも、クリップボードがデフォルトで有効です。

参照

• HTMLElement.contentEditable
• document.designMode
• Mozilla におけるリッチテキスト編集
• Scribe's "Browser Inconsistencies" documentation with bugs related to document.execCommand.?