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 文本中嵌入特定界面，比如下面的直方统计图：

典型操作步骤如下：

在隐藏的胶片页（设计态仍可见）中，拖入直方图样板，创建一个组件，然后选中该组件，在 property 页修改属性，或点击浮动按钮配置特定属性。
为这个组件指定 key 值，然后点击浮动按钮，拷贝对它的 "引用描述"。
在 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 编辑器中修改文本。这样，我们能很方便的创建同样式导航页界面。

（非正经入门系列至此完结，本文是最后一篇）

本专栏历史文章：