# 格式化方法

本頁說明 `MDEditor` 插入 Markdown 格式的方法：插入位置、選取範圍的處理，以及何時輸出 HTML 標籤而不是 Markdown 記號。

## 插入位置

| 編輯器狀態 | 行為 |
|---|---|
| 游標在編輯器內（有無選取皆可） | 在游標處插入；有選取時把選取內容包起來，選取中的換行會被移除 |
| 從未取得游標 | 在最後一列附加；最後一列為空時直接改寫該列 |

插入後游標移到記號內側，並寫入一筆復原紀錄；`autosave` 為真時同時更新預覽。

## Markdown 或 HTML

行內格式方法的第一個參數是事件物件，用來判斷是否按著修飾鍵：

| `event.metaKey` 或 `event.ctrlKey` | 輸出 |
|---|---|
| 假（工具列點擊、傳入 `{}`） | Markdown 記號，例如 `**text**` |
| 真（快捷鍵觸發） | HTML 標籤，例如 `<b>text</b>` |

因此 `Cmd/Ctrl+B` 插入的是 `<b></b>`，點工具列按鈕插入的是 `****`。這些方法會讀取 `event.metaKey`，未傳參數時會拋出 `TypeError`；程式呼叫時請傳 `{}`。

## 行內格式

| 方法 | Markdown | HTML（修飾鍵） |
|---|---|---|
| `bold(event)` | `**text**` | `<b>text</b>` |
| `italic(event)` | `*text*` | `<i>text</i>` |
| `strikethrough(event)` | `~~text~~` | `<s>text</s>` |
| `underline(event)` | `<u>text</u>` | `<u>text</u>` |
| `marker(event)` | `==text==` | `<mark>text</mark>` |
| `sup(event)` | `^text^` | `<sup>text</sup>` |
| `sub(event)` | `~text~` | `<sub>text</sub>` |
| `code(event)` | `` `text` `` | `<code>text</code>` |

`underline()` 沒有 Markdown 寫法，一律輸出 `<u>`。`code()` 在跨多列選取時改為在選取範圍上下各插入一列 ` ``` `，形成程式碼區塊。

## 標題

```javascript
editor.heading({}, 2);
```

| 參數 | 說明 |
|---|---|
| `event` | 同上；有修飾鍵時輸出 `<h2></h2>` |
| `num` | `1`～`6` 對應 `#`～`######`；`0` 會移除既有的 `#` 前綴 |

有選取時會先去掉該列原本開頭的 `#` 與空白，再套用新的層級。

## 區塊格式

| 方法 | 每列前綴 | 無游標時 |
|---|---|---|
| `blockquote()` | `> ` | 附加 `> ` 一列 |
| `ul()` | `- ` | 附加 `-` 一列 |
| `ol()` | `1. ` | 附加 `1.` 一列 |

選取多列時每一列都加上前綴；`ol()` 不會遞增編號，所有列都是 `1.`，渲染時由 `<ol>` 自動編號。

## 連結與圖片

| 方法 | 輸出 | 忽略條件 |
|---|---|---|
| `link(title, href)` | `[title](href)` | `title` 與 `href` 皆為空 |
| `image(src, alt, title)` | `![title 或 alt](src)` | `src` 為空 |

`image()` 的方括號內優先使用 `title`，為空才用 `alt`；不會輸出 Markdown 的 `"title"` 屬性。在游標處插入時，結尾會多一個空白。