本系列博文从 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 编辑器中修改文本。这样,我们能很方便的创建同样式导航页界面。
(非正经入门系列至此完结,本文是最后一篇)
本专栏历史文章: