diff options
Diffstat (limited to 'files/zh-tw/web/api/document/execcommand/index.html')
| -rw-r--r-- | files/zh-tw/web/api/document/execcommand/index.html | 172 |
1 files changed, 172 insertions, 0 deletions
diff --git a/files/zh-tw/web/api/document/execcommand/index.html b/files/zh-tw/web/api/document/execcommand/index.html new file mode 100644 index 0000000000..c06cd0d89c --- /dev/null +++ b/files/zh-tw/web/api/document/execcommand/index.html @@ -0,0 +1,172 @@ +--- +title: Document.execCommand() +slug: Web/API/Document/execCommand +translation_of: Web/API/Document/execCommand +--- +<div>{{ApiRef("DOM")}}{{Obsolete_header}}</div> + +<p><span class="seoSummary">當 HTML 文件（document）被切換到 <code><a href="/en-US/docs/Web/API/Document/designMode">designMode</a></code> 時，它的 <code>document</code> 物件就會對外暴露 <strong><code>execCommand</code></strong> 方法作為操控目前可編輯區域的指令，譬如 <a href="/en-US/docs/Web/HTML/Element/input">form inputs</a> 或 <code><a href="/en-US/docs/Web/HTML/Global_attributes/contenteditable">contentEditable</a></code> 元素。</span></p> + +<p>多數的指令會作用在文件的<a href="/en-US/docs/Web/API/Selection">選取</a> （粗體、斜體等），而其他則像是插入新的元素（新增一個連結）或是影響一整列的文字（縮排）。當使用 <code>contentEditable</code> 時， <code>execCommand()</code> 會作用在目前活躍的可編輯元素上。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox"><em>document</em>.execCommand(<em>aCommandName</em>, <em>aShowDefaultUI</em>, <em>aValueArgument</em>) +</pre> + +<h3 id="回傳值">回傳值</h3> + +<p>如果該指令不被支援或停用將回傳一個 <code>false</code> 的 {{jsxref('Boolean')}} 值。</p> + +<div class="note"> +<p><strong>備註</strong>：只有在使用者互動的部分回傳 <code>true</code> 。請不要嘗試在呼叫指令前使用回傳值來確認瀏覽器是否支援。</p> +</div> + +<h3 id="參數">參數</h3> + +<dl> + <dt><code>aCommandName</code></dt> + <dd>一個 {{domxref("DOMString")}} 作為指定要執行的指令。所有可用的指令列表請見 {{anch("Commands")}} 。</dd> + <dt><code>aShowDefaultUI</code></dt> + <dd>一個 {{jsxref("Boolean")}} 作為指示是否顯示預設的使用者介面。 Mozilla 並未實作這項功能。</dd> + <dt><code>aValueArgument</code></dt> + <dd>針對需要提供輸入引數的指令，藉由 {{domxref("DOMString")}} 提供相關的資訊。譬如， <code>insertImage</code> 需要提供圖片的 URL 。若沒有引數的需求則可指定為 <code>null</code> 。</dd> +</dl> + +<h3 id="指令">指令</h3> + +<dl> + <dt><code>backColor</code></dt> + <dd>變更文件的背景色彩。在 <code>styleWithCss</code> 模式中，它作用於涵蓋區域的背景色彩。這個指令需要提供一個 {{cssxref("<color>")}} 值字串作為引數值。請留意， Internet Explorer 使用這個指令作為設定文字的背景色彩。</dd> + <dt><code>bold</code></dt> + <dd>切換選取區域插入點的粗體與否。 Internet Explorer 使用 {{HTMLElement("strong")}} 標籤而不是 {{HTMLElement("b")}}.</dd> + <dt><code>ClearAuthenticationCache</code></dt> + <dd>清除所有快取中的驗證憑證。</dd> + <dt><code>contentReadOnly</code></dt> + <dd>使內容文件成為唯讀或可編輯。此指令需要提供布林值 true/false 作為引數值。（Internet Explorer 不支援）。</dd> + <dt><code>copy</code></dt> + <dd>複製目前選取的區域到剪貼簿。各個瀏覽器對於這個指令的行為可能有所差異且不斷變更。如果你有使用這個指令的情境，請先查閱相容性表格來決定如何使用。</dd> + <dt><code>createLink</code></dt> + <dd>對選取的區域建立超連結，僅限於有選取內容。需要提供一個 <a href="/en-US/docs/Archive/Mozilla/URIs_and_URLs">URI</a> 字串值作為超連結的 <code>href</code> 。 URI 必須最少包含一個字元且可以是空白字元（Internet Explorer 會建立一個 <code>null</code> 值的連結）。</dd> + <dt><code>cut</code></dt> + <dd>移除目前選取的區域並複製到剪貼簿。各個瀏覽器對於這個指令的行為可能有所差異且不斷變更。使用細節請查閱<a href="#Browser_compatibility">相容性表格</a>。</dd> + <dt><code>decreaseFontSize</code></dt> + <dd>在選取區域或插入點的前後加入一個 {{HTMLElement("small")}} 標籤（ Internet Explorer 不支援）</dd> + <dt><code>defaultParagraphSeparator</code></dt> + <dd>變更可編輯文字區域於新增段落時的段落分隔器。更多細節請查閱 <a href="/zh-TW/docs/Web/Guide/HTML/Editable_content#Differences_in_markup_generation">產生 markup 的區別</a>。</dd> + <dt><code>delete</code></dt> + <dd>刪除目前選取的區域。</dd> + <dt><code>enableAbsolutePositionEditor</code></dt> + <dd>啟用或停用用於移動絕對定位元素的抓取器。這個指令在 Firefox 63 Beta/Dev 版本中預設停用（{{bug(1449564)}}）。</dd> + <dt><code>enableInlineTableEditing</code></dt> + <dd>啟用或停用表格的列 / 欄的插入及刪除。此指令在 Firefox 63 Beta/Dev 版本中預設停用 ({{bug(1449564)}})。</dd> + <dt><code>enableObjectResizing</code></dt> + <dd>啟用或停用圖片、表格、絕對定位元素、其他可重設大小物件的重設大小處理。此指令在 Firefox 63 Beta/Dev 版本中預設停用 ({{bug(1449564)}})。</dd> + <dt><code>fontName</code></dt> + <dd>變更選取區域或插入點的字型名稱。此指令需要字型名稱字串（如「Arial」）作為引數值。</dd> + <dt><code>fontSize</code></dt> + <dd>變更選取區域或插入點的字型大小。此指令需要 <code>1</code>-<code>7</code> 的整數作為引數值。</dd> + <dt><code>foreColor</code></dt> + <dd>變更選取區域或插入點的字型色彩。此指令需要十六進位的色彩字串作為引數值。</dd> + <dt><code>formatBlock</code></dt> + <dd>在目前選取區域的前後加入一個 HTML 區塊層級元素，若選取區域已經存在區塊元素則取代之。（在 Firefox 中， {{HTMLElement("blockquote")}} 是個例外——它會包裹住任何所包含的區塊元素）。 此指令需要一個標籤名稱字串作為引數值。幾乎所有區塊層級元素都可以使用（Internet Explorer and Edge 僅支援標題標籤 <code>H1</code>–<code>H6</code> 、 <code>ADDRESS</code> 、 <code>PRE</code> 且必須由角括號包裹起來，譬如 <code>"<H1>"</code> ）。</dd> + <dt><code>forwardDelete</code></dt> + <dd>刪除游標位置後的字元，等同於在 Windows 按下 Delete 鍵盤按鍵。</dd> + <dt><code>heading</code></dt> + <dd>在選取區域或插入點前後加入一個標題元素。此指令需要標籤名稱字串作為引數值（例：<code>"H1"</code>, <code>"H6"</code> ）（Internet Explorer 及 Safari 不支援）。</dd> + <dt><code>hiliteColor</code></dt> + <dd>變更選取區域或插入點的背景色彩。此指令需要一個色彩字串作為引數值。 <code>useCSS</code> 必須為 <code>true</code> 才能有作用（Internet Explorer 不支援）。</dd> + <dt><code>increaseFontSize</code></dt> + <dd>在選取區域或插入點前後加入一個 {{HTMLElement("big")}} 標題（Internet Explorer 不支援）。</dd> + <dt><code>indent</code></dt> + <dd>縮排選取區域或插入點所包含的列。在 Firefox ，如果選取的範圍跨越多列且不同的縮排層級，只有選取中最淺層縮排列的才會被縮排。</dd> + <dt><code>insertBrOnReturn</code></dt> + <dd>控制 Enter 按鍵按下時在目前區塊元素中插入 {{HTMLElement("br")}} 元素或分割成為兩個元素（Internet Explorer 不支援）。</dd> + <dt><code>insertHorizontalRule</code></dt> + <dd>在插入點插入一個 {{HTMLElement("hr")}} 元素或以它取代選取的內容。</dd> + <dt><code>insertHTML</code></dt> + <dd>在插入點插入一個 HTML 字串（會刪除選取內容）需要一個有效的 HTML 字串作為引數值（Internet Explorer 不支援）。</dd> + <dt><code>insertImage</code></dt> + <dd>在插入點插入一個圖片（會刪除選取內容）。需要一個 URL 字串作為圖片的 <code>src</code> 引數值。這個需求跟 <code>createLink</code> 的字串是一樣的。</dd> + <dt><code>insertOrderedList</code></dt> + <dd>在選取區域或插入點建立一個<a href="/zh-TW/docs/Web/HTML/Element/ol">有序的清單</a>。</dd> + <dt><code>insertUnorderedList</code></dt> + <dd>在選取區域或插入點建立一個<a href="/zh-TW/docs/Web/HTML/Element/ul">無序的清單</a>。</dd> + <dt><code>insertParagraph</code></dt> + <dd>在選取區域或目前列的前後插入<a href="/zh-TW/docs/Web/HTML/Element/p">段落</a>（Internet Explorer 會在插入點插入段落並刪除選取的內容）。</dd> + <dt><code>insertText</code></dt> + <dd>在插入點處插入給予的純文字（選取內容將被刪除）。</dd> + <dt><code>italic</code></dt> + <dd>切換選取區域或插入點的斜體開關（Internet Explorer 使用 {{HTMLElement("em")}} 元素而不是 {{HTMLElement("i")}} ）。</dd> + <dt><code>justifyCenter</code></dt> + <dd>置中對齊選取區域或插入點的內容。</dd> + <dt><code>justifyFull</code></dt> + <dd>左右對齊選取區域或插入點的內容。</dd> + <dt><code>justifyLeft</code></dt> + <dd>靠左對齊選取區域或插入點的內容。</dd> + <dt><code>justifyRight</code></dt> + <dd>靠右對齊選取區域或插入點的內容。</dd> + <dt><code>outdent</code></dt> + <dd>凸排選取區域或插入點所包含的列。</dd> + <dt><code>paste</code></dt> + <dd>在目前的插入點貼上剪貼簿的內容（取代目前選取的項目）。網頁內容無法使用。詳閱 [1]。</dd> + <dt><code>redo</code></dt> + <dd>復原上一個取消的指令。</dd> + <dt><code>removeFormat</code></dt> + <dd>移除目前選取區域所有的格式。</dd> + <dt><code>selectAll</code></dt> + <dd>選取可編輯區域的所有內容。</dd> + <dt><code>strikeThrough</code></dt> + <dd>切換選取區域或插入點的刪除線開關。</dd> + <dt><code>subscript</code></dt> + <dd>切換選取區域或插入點的 <a href="/zh-TW/docs/Web/HTML/Element/sub">subscript</a> 開關。</dd> + <dt><code>superscript</code></dt> + <dd>切換選取區域或插入點的 <a href="/zh-TW/docs/Web/HTML/Element/sup">superscript</a> 開關。</dd> + <dt><code>underline</code></dt> + <dd>切換選取區域或插入點的<a href="/zh-TW/docs/Web/HTML/Element/u">底線</a>開關。</dd> + <dt><code>undo</code></dt> + <dd>取消上一個執行的指令。</dd> + <dt><code>unlink</code></dt> + <dd>從選取的超連結刪除<a href="/zh-TW/docs/Web/HTML/Element/a">錨點元素</a>。</dd> + <dt><code>useCSS</code> {{Deprecated_inline}}</dt> + <dd>針對產生的 markup 使用 HTML 標籤或 CSS。此指令需要一個布林值 true/false 作為引數值。</dd> + <dd>注意：這個引述在邏輯上是反向的（舉例：使用 <code>false</code> 會使用 CSS ，反之使用 <code>true</code> 則使用 HTML 且 Internet Explorer 不支援。這個指令已經被棄用並由 <code>styleWithCSS</code> 取而代之。</dd> + <dt><code>styleWithCSS</code></dt> + <dd>取代 <code>useCSS</code> 的指令。 <code>true</code> 會在 markup 修改 / 產生 <code>style</code> 屬性， false 會產生展示用的元素。</dd> +</dl> + +<h2 id="範例">範例</h2> + +<p>一個在 CodePen 上展示<a href="https://codepen.io/chrisdavidmills/full/gzYjag/">如果使用</a>的範例。</p> + +<h2 id="規格">規格</h2> + +<table class="spectable standard-table"> + <tbody> + <tr> + <th scope="col">規格</th> + <th scope="col">狀態</th> + <th scope="col">備註</th> + </tr> + <tr> + <td><a href="https://w3c.github.io/editing/execCommand.html#execcommand()">execCommand</a></td> + <td></td> + <td></td> + </tr> + </tbody> +</table> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + + + +<p>{{Compat("api.Document.execCommand")}}</p> + +<h2 id="相關資訊">相關資訊</h2> + +<ul> + <li>{{domxref("HTMLElement.contentEditable")}}</li> + <li>{{domxref("document.designMode")}}</li> + <li><a href="/zh-TW/docs/Rich-Text_Editing_in_Mozilla">Rich-Text Editing in Mozilla</a></li> + <li><a href="https://github.com/guardian/scribe/blob/master/BROWSERINCONSISTENCIES.md">Scribe's "Browser Inconsistencies" documentation</a> with bugs related to <code>document.execCommand</code>.</li> +</ul> |