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 非正经入门（之五：指令式界面设计）