Add some docs ...

2025-01-18 06:03:38 +08:00 · 2016-01-07 17:00:42 +08:00 · 2016-01-07 17:00:42 +08:00 · e87b4649a4
commit e87b4649a4
parent 00df19d3e3
5 changed files with 397 additions and 46 deletions
--- a/docs/pattern/form.md
+++ b/docs/pattern/form.md
@ -5,4 +5,115 @@

 ---

-占位。
+作为获取用户输入的重要交互方式，表单也承担将问题和答案进行配对的角色。
+
+设计者进行表单设计时，应当注意这几点：
+
+1. 确保用户了解要提供什么信息，以及为什么要提供这些信息。
+
+  为初级用户／偶尔访问的用户提供白话作为『标签』；为领域专家提供专业术语作为『标签』。当需要用户提供敏感信息时，通过『输入提示』来说明系统为什么要这么做，eg：需要获取身份证号码、手机号码时。
+
+2. 让用户能在上下文中获取信息，帮助他完成输入。
+
+  使用『良好的默认值』、『结构化的格式』、『输入提示』、『输入提醒』等方式，避免让用户在空白中完成输入。
+
+3. 对错误敏感，并尽可能宽容。
+
+  通过不同的『校验』规则和形式进行反馈，避免用户在点击提交后才刚刚开始『校验』，让用户提前纠正错误；依据『容错格式』，允许用户以多种格式和语法输入，eg：用户在电话号码输入框中多输入了一个空格，系统存储时可以主动删掉空格，但是不需要告诉用户这是一个错误。
+
+4. 不要提出不必要的问题。
+
+## 内容
+
+<img class="preview-img" align="right" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+通常表单会有四个部分组成。
+
+1. 标签。
+2. 输入框。
+3. 动作。
+4. 校验反馈。
+
+> 注：`*` 表明该项为必填项。
+
+## 交互
+
+### 填空
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+在一种描述性的上下文中出现输入项，可以帮助用户理解当前的状况，以及需要提供什么数据。
+
+### 组合输入框
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+当两个输入框关联性很强时，可以前后拼接，减少页面空间。
+
+### 对齐方式
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+在页面设计表单时，按钮组必须和输入框左对齐。
+
+### 禁用主按钮
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png" good>
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png" bad>
+
+当输入框非常少时（一般少于 3 个），如果用户没有在必填项中输入内容，可禁用『提交』等主按钮；当输入框非常多时（超过 5 项以上），不建议禁用主按钮。
+
+### 结构化的格式
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+用户对输入的内容很熟悉，且系统不希望接受任何偏离期望的格式。
+
+### 输入提示 & 输入提醒
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+输入提示：不希望在标签上放置太多文字进行解释，同时只有标签又会引起误解。
+
+输入提醒：提醒用户该控件的目的或所需格式，由于在用户输入后提醒就会消失，所以适用在用户对内容比较熟悉时。
+
+### 密码加强计
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+提供关于密码强度和有效性的及时反馈，适用在注册页面时的密码输入框。
+
+### 校验
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+
+通过不同的“校验”规则和形式进行反馈，避免用户在点击提交后才刚刚开始“校验”，让用户提前纠正错误。
+
+### 字数校验框
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+用于统计当前输入长度，以及是否超过系统阈值。
+
+### 容错格式
+
+待补充。
+
+### 自动完成
+
+待补充。
+
+### 列表构造器
+
+待补充。
+
+### 良好的默认值
+
+待补充。
--- a/docs/pattern/list.md
+++ b/docs/pattern/list.md
@ -5,4 +5,113 @@

 ---

-占位。
+
+列表是非常常见的界面元素，有多种使用场景：
+
+- 获取概览
+- 逐项浏览
+- 查找特定列表项
+- 排序与过滤
+- 重新安排、添加、删除或重新分类列表项
+
+## 交互
+
+### 显示详情信息
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+气泡显示：用户鼠标点击／悬停某个链接或内容时，在悬浮层上显示该条列表项少量的详情信息。
+
+<br />
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+列表嵌入：用户可以不用打开新页面或者打开弹框，只要通过点击，就可以直接在上下文中查看该列表项的详情信息。
+
+<br />
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+弹出层显示：用户通过点击，在弹出框中查看该列表项的详情信息，但是当前列表项的上下文关系会被打断。
+
+<br />
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+双面板选择器：用户通过点击，在列表的一侧（一般为右侧）查看该列表项大量的详情信息。
+
+<br />
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+单窗口深入：用户通过点击，在当前页查看大量的详情信息。此模式打破了整个列表项的上下文关系，适用在详情信息之间完全无关，或者屏幕空间实在狭小（eg：移动应用），又或者列表和内容可能非常多的应用场景中。
+
+### 显示更多文本
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+宽行：使某些列表项可以扩展为多行文本行来显示足够的文本内容。
+
+<br />
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+对等网格：以网格或者矩阵的方式排列内容元素，其中每个元素都有相仿的视觉重量。
+
+### 显示图片
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+走马灯：以一维的形式来显示图片，可用户主动触发或者系统自动播放。
+
+<br />
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+缩略图网格：以二维的形式来展现图片/Icon，具有强烈的视觉效果，可以吸引用户注意。
+
+### 显示长列表
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+分页器：以分段的形式加载列表，将是否需要加载其他项的选择权交给用户。
+
+<br />
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+无限加载：当用户加载到第一段内容的最下方，通过监听滚轮事件或者用户点击按钮，继续加载下一段内容。
+
+### 显示分类或者层级的列表
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+两层结构。
+
+<br />
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+多层结构。
+
+<br />
+
+## 案例
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+功能可有批操作，升序降序，分页，单条操作。
+
+<br />
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+列表各项的合并、详情展开。
+
+<br />
+
+<img class="preview-img" width="50%" align="right" alt="图片的描述语句" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+卡片网格。
--- a/docs/pattern/navigation.md
+++ b/docs/pattern/navigation.md
@ -5,14 +5,66 @@

 ---

-占位。
+在广义上，任何告知用户他在哪里，他能去什么地方以及如何到达那里的方式，都可以称之为导航。而我们将中后台常见的导航方式进行提炼和封装，帮助设计者快速构建清晰和流畅的系统。当设计者使用导航或者自定义一些导航结构时，请注意：

-<img class="preview-img" align="right" src="https://os.alipayobjects.com/rmsportal/mFRzGiKZvfHJvRC.png">
+1. 尽可能提供标示、上下文线索以及网站地图，避免用户迷路；
+2. 保持导航样式和行为一致或者减少导航数量，降低用户学习成本；
+3. 尽可能减少页面间的跳转（eg：一个常见任务需要多个页面跳转时，请减少至一至两次），让用户移动距离保持简短。

-占位。
+## 常见导航

-占位。
+<img class="preview-img" align="right" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">

-占位。
+我们将常见的导航模式分为：侧栏导航和顶部导航，两者各有优缺点，设计者可以根据各自的业务需求进行选择。

-占位。
+## 侧栏导航
+
+<img class="preview-img" align="right" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+导航的结构由以下几部分组成。
+
+
+1. 产品 Logo 和名称。
+2. 业务类目。
+3. 登陆工具。
+4. 面包屑（可选）。
+
+> 注：
+> 1. 尽可能不使用面包屑，尤其是当前页面的导航能清晰的告诉用户他在哪里时；
+> 2. 面包屑可以分为这几类：
+>    - 路径型：路径型面包屑是一个动态显示用户到达页面经过的途径。
+>    - 位置型：位置型面包屑是固定的，显示了页面在网站结构中的位置。
+>    - 属性型：属性型面包屑给出的当前页面的分类信息。
+
+<img class="preview-img" align="right" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+<img class="preview-img" align="right" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+<img class="preview-img" align="right" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+我们定义了不同类目层级所对应的导航样式。
+
+
+## 顶部导航
+
+<img class="preview-img" align="right" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+<img class="preview-img" align="right" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+结构如右图所示：
+
+1. 产品 Logo 和名称。
+2. 业务类目。
+3. 登陆工具。
+4. 面包屑（可选）。
+
+<br>
+
+<img class="preview-img" align="right" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+<img class="preview-img" align="right" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+<img class="preview-img" align="right" src="https://os.alipayobjects.com/rmsportal/OeChYAOTenMzJmG.png">
+
+
+不同类目层级。
--- a/scripts/demo.js
+++ b/scripts/demo.js
@ -149,7 +149,8 @@ var Modal = antd.Modal;
 var PriviewImg = React.createClass({
  getInitialState() {
    return {
-      visible: false
+      visible: false,
+      boxLength: 1,
    };
  },
  showImageModal() {
@ -163,21 +164,40 @@ var PriviewImg = React.createClass({
    });
  },
  render() {
+    const width = (100.0 / this.props.boxLength) + '%';
+    const goodCls = this.props.good ? 'good' : '';
+    const badCls = this.props.bad ? 'bad' : '';
    return (
-      <span className="preview-image-wrapper">
-        <img src={this.props.src} onClick={this.showImageModal} alt={this.props.alt} />
+      <div className="preview-image-box" style={{ width: width }}>
+        <div className={`preview-image-wrapper ${goodCls} ${badCls}`}>
+          <img src={this.props.src} onClick={this.showImageModal} alt="Sample Picture" />
+        </div>
+        <div className="preview-image-description">{this.props.alt}</div>
        <Modal className="image-modal" width="960" visible={this.state.visible} onCancel={this.handleCancel} footer="" title="">
-          <img src={this.props.src} alt={this.props.alt} />
+          <img src={this.props.src} />
+          <div className="preview-image-description">{this.props.alt}</div>
        </Modal>
-      </span>
+      </div>
    );
  }
 });

 InstantClickChangeFns.push(function() {
-  Array.slice(document.querySelectorAll('.preview-img')).forEach(function(img) {
-    img.parentNode.className = 'preview-image';
-    ReactDOM.render(<PriviewImg src={img.src} />, img.parentNode);
+  const previewImageBoxes = $('.preview-img').parent();
+  previewImageBoxes.each(function(i, box) {
+    box = $(box);
+    const priviewImgs = [];
+    const boxLength = box.find('.preview-img').length;
+    box.find('.preview-img').each(function(i, img) {
+      console.log(img.hasAttribute('good'));
+      priviewImgs.push(
+        <PriviewImg boxLength={boxLength} key={i} src={img.src}
+          alt={img.alt} good={!!img.hasAttribute('good')} bad={!!img.hasAttribute('bad')} />
+      );
+    });
+    const mountNode = $('<div class="preview-image-boxes"></div>');
+    box.replaceWith(mountNode);
+    ReactDOM.render(<span>{priviewImgs}</span>, mountNode[0]);
  });
 });

--- a/site/static/style.css
+++ b/site/static/style.css
@ -386,6 +386,7 @@ footer ul li > a {
  padding-bottom: 50px;
  float: left;
  border-right: 1px solid #e9e9e9;
+  margin-right: -1px;
 }

 .aside-container > ul > li {
@ -411,7 +412,7 @@ footer ul li > a {
  z-index: 1;
  position: relative;
  background: #fff;
-  right: 1px;
+  border-right: 1px solid #e9e9e9;
 }

 .aside-container li h4:after {
@ -426,6 +427,7 @@ footer ul li > a {
  transition: all 0.3s ease;
 }

+
 .aside-container li[open=open] h4:after {
  -webkit-transform: scale(0.6) rotate(180deg);
  transform: scale(0.6) rotate(180deg);
@ -494,22 +496,14 @@ footer ul li > a {
  padding: 0 40px 120px;
  background: #fff;
  min-height: 500px;
-}
-
-.main-container-center {
-  margin: 0 auto;
-  padding: 30px 80px 120px;
-  border-left: 1px solid #e9e9e9;
-  border-right: 1px solid #e9e9e9;
-  width: 90%;
-  height: 100%;
+  overflow: hidden;
 }

 .markdown {
  color: #666;
  font-size: 14px;
  line-height: 1.8;
-  width: 90%;
+  width: 80%;
 }

 .highlight {
@ -536,6 +530,7 @@ footer ul li > a {
  color: #404040;
  margin: 1.6em 0 0.6em 0;
  font-weight: 500;
+  clear: both;
 }

 .markdown h1 { font-size: 28px; }
@ -546,11 +541,10 @@ footer ul li > a {
 .markdown h6 { font-size: 12px; }

 .markdown hr {
-  border-radius: 10px;
-  height: 3px;
+  height: 1px;
  border: 0;
-  background: #eee;
-  margin: 20px 0;
+  background: #e9e9e9;
+  margin: 16px 0;
 }

 .markdown p,
@ -558,10 +552,11 @@ footer ul li > a {
  margin: 1em 0;
 }

-.markdown > ul li {
+.markdown > ul li,
+.markdown blockquote ul > li {
  list-style: circle;
-  margin-left: 20px;
-  padding-left: 8px;
+  margin-left: 1em;
+  padding-left: 0.4em;
 }

 .markdown > ul li p,
@ -569,10 +564,11 @@ footer ul li > a {
  margin: 0.6em 0;
 }

-.markdown > ol li {
+.markdown > ol li,
+.markdown blockquote ol > li {
  list-style: decimal;
-  margin-left: 20px;
-  padding-left: 8px;
+  margin-left: 1em;
+  padding-left: 0.4em;
 }

 .markdown code {
@ -627,6 +623,11 @@ footer ul li > a {
  color: #999;
  border-left: 4px solid #e9e9e9;
  padding-left: 0.8em;
+  margin: 1em 0;
+  overflow: hidden;
+}
+
+.markdown blockquote p {
  margin: 0;
 }

@ -646,6 +647,11 @@ footer ul li > a {
  display: inline-block;
 }

+.markdown > br,
+.markdown > p > br {
+  clear: both;
+}
+
 #api ~ ul > li > p > strong ~ code {
  background: #fff;
  color: #CC7300;
@ -709,18 +715,18 @@ footer ul li > a {
 }

 .toc li > ul {
-  text-indent: 10px;
+  text-indent: 8px;
 }

 .toc a {
-  padding-left: 10px;
+  padding-left: 8px;
  border-left: 2px solid #eee;
  display: block;
  transition: all 0.3s ease;
  white-space: nowrap;
  text-overflow: ellipsis;
  overflow: hidden;
-  max-width: 100px;
+  max-width: 90px;
  line-height: 20px;
  color: #999;
 }
@ -818,7 +824,7 @@ footer ul li > a {
 }

 .code-boxes-col-1-1 {
-  width: 90%;
+  width: 80%;
 }

 .code-boxes-col-2-1 {
@ -1070,6 +1076,10 @@ a.entry-link:hover .anticon-smile {
    width: 100%;
  }

+  .toc {
+    display: none;
+  }
+
  .nav-phone-icon {
    display: block;
    width: 49px;
@ -1246,23 +1256,72 @@ a.entry-link:hover .anticon-smile {
  font-size: 12px;
 }

-p.preview-image {
+.preview-image-boxes {
  float: right;
-  margin: 0;
-  margin-right: -10%;
+  margin: 0 -14% 30px 60px;
+  width: 600px;
+  overflow: hidden;
+}
+
+.preview-image-box {
+  width: 100%;
+  float: left;
+  padding: 0 8px;
+}
+
+.preview-image-box:first-child {
+  margin-left: -8px;
+}
+
+.preview-image-box:last-child {
+  margin-right: -8px;
 }

 .preview-image-wrapper {
-  width: 600px;
  background: #F2F2F2;
  padding: 24px;
  display: inline-block;
  text-align: center;
+  width: 100%;
+  position: relative;
 }

-.preview-image img {
+.preview-image-wrapper.good:after {
+  content: '';
+  width: 100%;
+  height: 3px;
+  background: #2db7f5;
+  display: block;
+  position: absolute;
+  bottom: 0;
+  left: 0;
+}
+
+.preview-image-wrapper.bad:after {
+  content: '';
+  width: 100%;
+  height: 3px;
+  background: #f50;
+  display: block;
+  position: absolute;
+  bottom: 0;
+  left: 0;
+}
+
+.preview-image-description {
+  font-size: 12px;
+  margin-top: 8px;
+  color: #999;
+}
+
+.preview-image-box img {
  cursor: pointer;
  max-width: 100%;
+  transition: box-shadow 0.3s ease;
+}
+
+.preview-image-box img:hover {
+  box-shadow: 2px 2px 5px rgba(0, 0, 0, 0.3);
 }

 .image-modal {