React 可視化開發工具 Shadow Widget 非正經入門（之六：markdown）

本系列博文從 Shadow Widget 做者的視角，解釋該框架的設計要點。本篇講解 Markdown 在 Shadow Widget 中的應用。

Markdown 在 Shadow Widget 中的應用

Shadow Widget 中 Markdown 採用 John Gruber 的 Markdown 語法規則。因爲 markdown 支持 <tag> 帶標籤的書寫方式，咱們就沒必要外尋特別的擴展方法，須要功能擴展的地方，都用 html 標籤的形式解決。

Shadow Widget 不僅用 markdown 表達文本段落，重要的是，它還用 markdown 實施界面編程。爲達到這個目標，咱們先對 John Gruber 的 markdown 語法作一點優化。

優化 markdown 語法

常規 markdown 語法都支持用 > 表達當前段落縮進一級。好比：

> 這一段縮進一個級別。

 > > 這一段縮進兩個級別。

這樣的 markdown 文本在獨立的 *.txt 或 *.md 文件中書寫沒問題，但若是挪到 html 網頁文件中，字母 '>' 會保存爲轉義格式 ">"。因此，咱們分析 markdown 語法時，要增長對 ">" 表示縮進的兼容處理。

從更嚴格角度去看，字母 '>' 規則算得上一個 Bug，由於 markdown 要內置支持 <tag> 標籤，就不應將 '<' 與 '>' 用做特殊語義標記，不然有損嚴謹性。

Shadow Widget 把轉義標籤也歸入到 markdown 文本內容中，須要以更嚴謹的方式表達縮進一級，咱們引用 "::" 表示法，拿它替換 '>'。好比：

:: 這一段縮進一個級別。

 :: :: 這一段縮進兩個級別。

把轉義標籤嵌到 markdown 文本中

Markdown 語法支持 <tag> 標籤，轉義標籤天然能用 markdown 書寫，好比：

<pre $=MarkedDiv key='marked' width='{0.9999}'>### 嵌入描述界面的轉義標籤

<div $=P key='p' width='{0.9999}'>
  <span $=Button key='test1'>test 1</span>
  <span $=Button key='test2'>test 2</span>
</div>

本例在 markdown 文本定義了 **兩個按鈕** 界面。

### 嵌入一個引用

<div key='pie' $='.body.auto1.pie_chart'></div>

在外部定義的構件（`.body.auto1.pie_chart`）將插入到 markdown 正文中使用。
</pre>

使用 markdown 的構件是 Div 類構件，在 markdown 嵌入轉義標籤的首層節點要求是 "非行內構件"，Panel 類、Div 類、P 類都可。嵌入的由轉義標籤描述的界面，表現爲一種 "段落"，與 markdown 描述的各段落一塊兒按順序排列。上面例子生成的節點樹以下：

marked            // MarkedDiv
    +-- markdown paragraph
    +-- p             // P
    |   +-- test1     // Button
    |   +-- test2     // Button
    +-- markdown paragraph
    +-- pie
    +-- markdown paragraph

在 markdown 中嵌入轉義標籤，使 markdown 的表達能力變得異常強大，Shadow Widget 編程能表達的界面都能嵌進來。嵌入的轉義標籤甚至還但是 markdown 構件，層層嵌套，深度沒有限制。

兩個 markdown 基礎類

Shadow Widget 內置提供 T.MarkedDiv 與 T.MarkedTable 兩個最基礎的 WTC 類定義，全部凡支持 markdown 的擴展 WTC 類都應從這兩個基類開始繼承。

在轉義標籤描述一個 markdown 節點，建議用 <pre> 標籤，<div> 也管用，但用 <pre> 可讓 markdown 文本少些特殊字符被轉義。<pre> 標籤的內容，遇到 "<" 或 ">" 仍會轉義，但用 <div> 表達時，若是內容有換行或嵌套的標籤，會有麻煩。

因此，下面兩種轉義標籤，咱們選擇第一種優於第二種：

<pre $=MarkedDiv>Hello, world</pre>
<div $=MarkedDiv>Hello, world</div>

MarkedDiv 經常使用來表達一維數據定義，MarkedTable 表達二維數據，行是一維，列是另外一維。這兩種構件都定義有 duals.nodes 屬性，對於前者，用 comp.duals.nodes[n] 的方式提取由轉義標籤訂義的各節點，對於後者，用 comp.duals.nodes[row][col] 提取第 row 行 col 列的經轉義標籤訂義的節點。

markdown 兼顧了機器可讀與人類可讀的需求

Markdown 被設計出來，主要用來簡化網頁內容編輯的，許多用戶（尤爲是做家）並不熟悉 html 標籤，讓他使用 <p> 或 <table> 撰寫文章會很困難，有了 Markdown 語法，普通人花 10 分鐘學一下，就能編寫具備漂亮界面的網文了。

Shadow Widget 繼承 markdown 這個優點，同時，在不引入太複雜操做前提下，努力提高界面表現力。從原理上講，markdown 可嵌入大部分 html 標籤，如 <div>, <p>, <table> 等，表現複雜用戶界面不是問題，問題是複雜的標籤只有前端開發人員會用。如今 Shadow Widget 把界面設計可視化了，未經編程訓練的普通人也能經過拖入樣板建立組件，再修改組件屬性來設計界面，因此，Shadow Widget 這項改進具備重大現實意義。

在 markdown 文本中嵌入特定界面，好比下面的直方統計圖：

典型操做步驟以下：

1. 在隱藏的膠片頁（設計態仍可見）中，拖入直方圖樣板，建立一個組件，而後選中該組件，在 property 頁修改屬性，或點擊浮動按鈕配置特定屬性。

2. 爲這個組件指定 key 值，而後點擊 浮動按鈕，拷貝對它的 "引用描述"。

3. 在 markdown 內容編輯器中粘帖 "引用描述" 文本便可。

通過這幾個步驟，直方圖就嵌入到 markdown 文本中了。

Markdown 在 Shadow Widget 中應用普遍，就像 markdown 能簡化文章寫做一下，它同樣簡化編程中的界面設計。其表達形式對機器可讀，同時，對開發人員也是易讀易理解的，對它作修改直接改文本，很方便。

一個複雜些的例子

好比下面組件，點擊左側列表中的項目，右側將展現相應頁的內容（注：下面是圖片，不能點擊看交互效果）。

它的實現原理大體是，用以下 MarkedDiv 定義 item A/B/C 三項內容：

<pre $=MarkedDiv key="mark">
<pre $=MarkedDiv title="item A">Page A
</pre>

<pre $=MarkedDiv title="item B">Page B
</pre>

<pre $=MarkedDiv title="item C">Page C
</pre>
</pre>

而後用 $for="item in duals('./mark').nodes" 循環語句，取這 3 個 element 的 props.title 值顯示到左側列表，用 NavPanel 與 GroundPanel 構造可選導航頁，各內容頁一樣用 $for="item in duals('./mark').nodes" 取得。

若是把這種界面作成樣板，用戶使用時，拖進來就建立一個組件，而後選中 key 爲 mark 的 MarkedDiv 構件，點擊 "edit markdown" 浮動按鈕，而後在彈出的 markdown 編輯器中修改文本。這樣，咱們能很方便的建立一樣式導航頁界面。

 

（非正經入門系列至此完結，本文是最後一篇）

---

本專欄歷史文章：

1. 介紹一項讓 React 能夠與 Vue 抗衡的技術

2. React 可視化開發工具 Shadow Widget 非正經入門（之一：React 三宗罪）

3. React 可視化開發工具 Shadow Widget 非正經入門（之二：分離界面設計）

4. React 可視化開發工具 Shadow Widget 非正經入門（之三：雙源屬性與數據驅動）

5. React 可視化開發工具 Shadow Widget 非正經入門（之四：flux、mvc、mvvm）

6. React 可視化開發工具 Shadow Widget 非正經入門（之五：指令式界面設計）