forked from baixing/puerh
-
Notifications
You must be signed in to change notification settings - Fork 0
/
getting-start.html
314 lines (291 loc) · 17.2 KB
/
getting-start.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
<!DOCTYPE html>
<html class="getting-start">
<head>
<meta charset="utf-8" />
<title>Getting Start > Puerh - 百姓网 UI 库</title>
<link rel="stylesheet" href="stylesheets/base.css" />
<link rel="stylesheet" href="style.css" />
<!--[if lt IE 9]>
<script type="text/javascript">
// html5shiv MIT @rem remysharp.com/html5-enabling-script
// iepp v1.6.2 MIT @jon_neal iecss.com/print-protector
/*@cc_on(function(a,b){function r(a){var b=-1;while(++b<f)a.createElement(e[b])}if(!(!window.attachEvent||!b.createStyleSheet||!function(){var a=document.createElement("div");a.innerHTML="<elem></elem>";return a.childNodes.length!==1}())){a.iepp=a.iepp||{};var c=a.iepp,d=c.html5elements||"abbr|article|aside|audio|canvas|datalist|details|figcaption|figure|footer|header|hgroup|mark|meter|nav|output|progress|section|summary|time|video",e=d.split("|"),f=e.length,g=new RegExp("(^|\\s)("+d+")","gi"),h=new RegExp("<(/*)("+d+")","gi"),i=/^\s*[\{\}]\s*$/,j=new RegExp("(^|[^\\n]*?\\s)("+d+")([^\\n]*)({[\\n\\w\\W]*?})","gi"),k=b.createDocumentFragment(),l=b.documentElement,m=l.firstChild,n=b.createElement("body"),o=b.createElement("style"),p=/print|all/,q;c.getCSS=function(a,b){if(a+""===undefined)return"";var d=-1,e=a.length,f,g=[];while(++d<e){f=a[d];if(f.disabled)continue;b=f.media||b,p.test(b)&&g.push(c.getCSS(f.imports,b),f.cssText),b="all"}return g.join("")},c.parseCSS=function(a){var b=[],c;while((c=j.exec(a))!=null)b.push(((i.exec(c[1])?"\n":c[1])+c[2]+c[3]).replace(g,"$1.iepp_$2")+c[4]);return b.join("\n")},c.writeHTML=function(){var a=-1;q=q||b.body;while(++a<f){var c=b.getElementsByTagName(e[a]),d=c.length,g=-1;while(++g<d)c[g].className.indexOf("iepp_")<0&&(c[g].className+=" iepp_"+e[a])}k.appendChild(q),l.appendChild(n),n.className=q.className,n.id=q.id,n.innerHTML=q.innerHTML.replace(h,"<$1font")},c._beforePrint=function(){o.styleSheet.cssText=c.parseCSS(c.getCSS(b.styleSheets,"all")),c.writeHTML()},c.restoreHTML=function(){n.innerHTML="",l.removeChild(n),l.appendChild(q)},c._afterPrint=function(){c.restoreHTML(),o.styleSheet.cssText=""},r(b),r(k);if(c.disablePP)return;m.insertBefore(o,m.firstChild),o.media="print",o.className="iepp-printshim",a.attachEvent("onbeforeprint",c._beforePrint),a.attachEvent("onafterprint",c._afterPrint)}})(this,document)@*/
</script>
<![endif]-->
</head>
<body class="javascript" style="_border:100px solid;">
<div class="container clearfix">
<div id="header" class="grid grid-20">
<div class="grid grid-4 first">
<h1 id="logo">Puerh</h1>
<strong id="tagline">百姓网 UI 库</strong>
</div>
<div class="grid grid-11 navi">
<a href="./index.html" id="index">HOME</a>
<a href="./css.html" id="css">CSS</a>
<a href="./javascript.html" id="javascript">JavaScript</a>
<a href="./getting-start.html" id="getting-start">Getting Start</a>
</div>
<div class="grid grid-5 last navi">Feedback：
<a href="http://arch.baixing.com/Puerh/faq.html">FAQ</a>
<a href="mailto:[email protected]">@登甲</a>
<a href="mailto:[email protected]">@小鱼</a>
</div>
</div> <!-- #header -->
<div id="document" class="grid grid-20 typo">
<p>
Puerh 是百姓网 UI 库的简称。名字源自于在想为框架命名时办公桌上的一包普尔茶，因此取名“普尔（Puerh）”，希望所构建的百姓网 UI 简洁但像普尔茶一样有韵味。这个文档将介绍如何使用 Puerh 来构建 Web 界面。
</p>
<h2>一、CSS 组件</h2>
<p>所有组件均通过兼容测试、使用统一的命名注释规范。包括栅格系统、排版样式和组件样式。所有组件样式包含于 <code>base.css</code> 中。</p>
<blockquote>组件兼容要求：Mac/Win 系统下的 IE6+ / Google Chrome / Firefox / Safari</blockquote>
<h3>1、命名规范</h3>
<p>使用嵌套式命名法（暂且这样称呼吧）。组件是一个整体，理应包含于一个容器中；为了便于重用，在 CSS 中我们配合 class 选择器来做模块；另外为了使命名更长度和语义上更易懂。做如下约定：</p>
<ul>
<li><b>HTML class 属性：</b>使用小写字母作为 class 名，使用嵌套式命名。
<p>统一命名规范，让属性值与 HTML 属性一致，均使用小写。所谓的嵌套式命名，即以父级元素的名字作为子元素的命名前缀。比如 <code>.tab</code> 组件名的子模块，应该是 <code>.tab-模块名</code>，而模块的下一级则是 <code>.tab-模块名-子模块名</code>。每一级都以上一级名称加上“-”作为前缀使用。</p>
</li>
<li><b>组件：</b>使用单个单词
<p>尽量使用一个单词命名，比如 <code>.list</code>、<code>.flow</code>、<code>.filter</code> 等，不要使用像 <code>headerMeta</code>、<code>header-meta</code>这样的写法，一来命名太长，二来不符合嵌套规范。</p>
</li>
<li><b>模块</b> = 组件名 + 模块名
<p>假设我们需要写一个 Tab 组件，Tab 是一个整体，包含在 <code>.tab</code> 这个 class 中，有触发点 <code>.tab-trigger</code> 和内容区 <code>.tab-content</code>。触发点中有不同的点，内容区中有不同的内容模块。使用嵌套式的命名方法，有这样的结构：</p>
<pre class="prettyprint">
<div class="<b>tab</b>"> --- 组件名
<ul class="<b>tab-trigger</b>"> --- 模块名
<li class="tab-trigger-item">item 1</li>
<li class="<b>tab-trigger-item</b>">item 2</li> --- 子模块
<li class="tab-trigger-item">item 3</li>
</ul>
<div class="<b>tab-content</b>"> --- 模块名
<div class="tab-content-item">content 1</div>
<div class="<b>tab-content-item</b>">content 2</div> --- 子模块
<div class="tab-content-item">content 3</div>
</div>
</div> <!-- .tab --></pre>
<li><b>扩展</b> = 组件名 + 扩展名
<p>假设我们有一个竖排的 Tab 组件，除了把 Tab 的触发点从上面移到左边，外观上并没有其他变化。这时复用模块将可以减少重复的代码并且只作局部调整省去重复劳动。可以给组件增加一个扩展名。如：</p>
<pre class="prettyprint">
<div class="tab <b>tab-vertical</b>"> --- 组件名 + 扩展名
<ul class="tab-trigger">
...
</ul>
<div class="tab-content">
...
</div>
</div> <!-- .tab .tab-vertical--></pre>
</li>
<li><b>状态</b> = 模块名 + 状态名
<p>仍以 Tab 为例。触发点是有状态的。激活状态的标签通常和其他标签显示不同的样式，非激活状态的内容更是明显，一般都是隐藏的。因此我们需要给模块一个状态。会有这样的代码：</p>
<pre class="prettyprint">
<div class="tab">
<ul class="tab-trigger">
<li class="tab-trigger-item <b>tab-trigger-item-active</b>">item 1</li> --- 状态名
<li class="tab-trigger-item">item 2</li>
<li class="tab-trigger-item">item 3</li>
</ul>
<div class="tab-content">
<div class="tab-content-item <b>tab-content-item-active</b>">content 1</div> --- 状态名
<div class="tab-content-item">content 2</div>
<div class="tab-content-item">content 3</div>
</div>
</div> <!-- .tab --></pre>
<p>另外，值得一提的是，模块和组件一样，都可以有扩展名，命名方法同扩展命名。</p>
</li>
</ul>
<h4>命名中的注意点：</h4>
<ul>
<li>同组件不嵌套，即 .tab > .tab 的方式是不被允许的，可以是 .tab1 > .tab2 的方式</li>
<li>组件层级嵌套最好不要超过4级，1-2-3-4，如果大于4级，则考虑是否将一个组件分拆成多个</li>
<li>icon 使用统一的命名方式</li>
</ul>
<h4>Icons 的命名方式：</h4>
<p>所有小图标均使用 <code>.icon</code> 命名。使用 CSS Sprites 方式合并图片，用 <code>.icon .icon-扩展</code> 来设定图片的背景位置。具体可以参考 Icons 组件的实现。</p>
<h3>2、注释规范</h3>
<p>注释旨在指明团队协作中的创作、个性者和代码作用。在 CSS 中，无论块组还是单行注释，均使用 <code>/* 注释 */</code>。由于中文注释可能导致代码失效，但中文作为团队最有效的沟通文字，最好的使用方法是，保证在 <code>/*</code> 和 <code>*/</code> 之间的中文前后都有空格，以保证 CSS 不会失效。</p>
<p>在组件中，主要使用的两种注释如下：</p>
<pre class="prettyprint">
/* form 表单 --- 简单描述
* author: [email protected] --- 作者
* require: button --- 依赖（可选）
*/
.form{
font-family:serif\0/; /* solution:win7 ie8 line-height bug */ --- 行内注释
}
… </pre>
<h3>3、栅格系统</h3>
<p>Puerh 使用 980px 宽、20 栏（每栏 <code>30px</code>）、10px 间隙的栅格系统。内容区域为 980px，撑开宽度为 1000px。所有栅格必须包含到 <code>.container</code> 内。使用 <code>.grid</code> 模块，扩展名 <code>.grid-N</code> N 代表 1~20 中的任意整数。</p>具体的使用如下：
<pre class="prettyprint">
// 包含于 <b>.container</b> 中
<div class="container">
<div class="grid grid-20">...</div>
</div>
// 嵌套使用：需要用于 <b>.first/.last</b> 类
<div class="container">
<div class="grid grid-20">
<div class="grid grid-5 <b>first</b>">…</div> --- 第一个容器
<div class="grid grid-5">…</div> --- 中间可以多个
<div class="grid grid-10 <b>last</b>">…</div> --- 最后一个容器
</div>
</div></pre>
<h3>4、排版类：TYPO.CSS</h3>
<p>在 Puerh 中使用开源的 TYPO.CSS 作为排版样式。这个库不同于一般的 CSS Reset，在提供 Reset 的同时，提供适合中文并且最大化兼容种系统的排版方法。在需要排版的地方使用 <code>.typo</code> 作为父容器的类，或在单独需要使用的时候，使用 <code>.typo-TAGNAME</code> 的方式单独使用。具体使用方式参考：</p>
<pre class="prettyprint">
// 在 <b>.typo</b> 内使用标签，将对应相应语义显示
<div class="typo">
<h3>Title</h3>
<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit.</p>
<ul>
<li>item 1</li>
<li>item 2</li>
</ul>
...
</div>
// 在没有 .typo 的情况下使用 <b>.typo-TAGNAME</b>
<h3 class="typo-h3">Title</h3>
<ul class="typo-ul">
<li>item 1</li>
<li>item 2</li>
</ul></pre>
<h3>5、小工具</h3>
<ul>
<li><b>CLEARFIX</b>: 清理浮动，在浮动元素的父节点添加
<pre class="prettyprint">
<ul class="<b>clearfix</b>">
<li class="float-item">…</li>
<li class="float-item">…</li>
...
</ul> </pre>
</li>
<li><b>DIAMOND</b>: 创建一个菱形
<pre class="prettyprint">
// 效果请看 Tips 和 Flow 组件的实现
<div class="<b>diamond</b>">
…
</div> </pre>
</li>
<li><b>CLOSE</b>: 关闭按钮
<pre class="prettyprint">
<div class="<b>close</b>" data-dismiss="alert">×</div> </pre>
</li>
</ul>
<h3>6、兼容：CSS Hack</h3>
<p>兼容是 CSS 中最大的难点。各种 hack 可以帮助你快速解决问题，但不一定是解决问题的真正方法。所以，hack 应该尽量避免使用。很多时候都是写法决定 bug，在有时间允许的情况下，请多进行测试以找到最佳方式。</p>
<pre class="prettyprint">
.all-IE{property:value\9;}
:root .IE-9{property:value\0/;}
.gte-IE-8{property:value\0;}
.lte-IE-7{*property:value;}
.IE-7{+property:value;}
.IE-6{_property:value;}
.not-IE{property//:value;}
@-moz-document url-prefix() { .firefox{property:value;} }
@media all and (-webkit-min-device-pixel-ratio:0) { .webkit{property:value;} }
@media all and (-webkit-min-device-pixel-ratio:10000),not all and (-webkit-min-device-pixel-ratio:0) { .opera{property:value;} }
@media screen and (max-device-width: 480px) { .iphone-or-mobile-s-webkit{property:value;} }</pre>
<p>目前在网站中会自动添加 body class，显示方式如下：<code>浏览器</code> <code>版本号</code> <code>系统名</code></p>
<pre class="prettyprint">
// 在 Body 中加 class
<body class='firefox firefox-12 mac'>
// 目前支持的 class name
浏览器：.firefox / .chrome / .safari / .ie / .opera / .maxthon / .netscape
版本号：浏览器版本号取整：比如 firefox 12.03 会显示 firefox-12
系统名：.mac / .win / .vista / .win7 / .ubuntu / .linux
// 标记与使用：
文件：Browser.php (/lib/)
调用：Browser::detect()</pre>
<p><b>注意：</b>别用轻易使用hack，IE下很多兼容性问题都是 <a href="http://haslayout.net/">has Layout</a> 引起的。试着给元素加上:</p>
<pre class="prettyprint">
display: inline-blockheight: (除 auto外任何值)
width: (除 auto外任何值)
float: (left或 right)
position: absolutewriting-mode: tb-rlzoom: (除 normal外任意值) </pre>
<h3>7、IE私有特性</h3>
<ul>
<li><b>expression</b>：无论什么时候，都不要使用它，用 Javascript 吧。更优雅，更灵活。</li>
<li><b>filter</b>:
<ul>
<li>应该尽量避免使用 AlphaImageLoader</li>
<li>可以适当在投影/发光/渐变/去色方面上使用</li>
</ul>
</li>
<li><b>IE bug</b>
<p>常见BUG，详见：http://sofish.de/1400</p>
</li>
</ul>
<h3>8、关于模块化</h3>
<p>有两点需要注意的，一是，注意代码重用的模块化；一是，注意 HTML 结构的模块化，而不是分块。</p>
<ul>
<li>
<p><strong>我们是这样重用的</strong>：</p>
<pre class="prettyprint">
<div id="<strong>module-1</strong>" class="module">
<h3>TITLE</h3>
<p class="module-item">
some text
</p>
</div>
<div id="<strong>module-2</strong>" class="module">
< h3>TITLE</h3>
<p class="module-item">
some text
</p>
</div></pre>
<pre class="prettyprint">
/* module, reuse style in module scrope*/
.module{}
.module-status{}
.module-item{}
.module-status .module-1-item{}
/* customize */
<strong>#module-1</strong> .module-item{}
<strong>#module-2</strong> .module-item{}</pre>
</li>
<li>
<p><strong>HTML 的模块化</strong>：我们应该这样写（他们的视觉是一体的，代码也应该是一体的）：</p>
<pre class="prettyprint">
<div id="<strong>module-1</strong>" class="module">
<h3>TITLE</h3>
<p class="module-item">
some text
</p>
</div> <!-- #module .module --></pre>
<p>而不是这样写：</p>
<pre class="prettyprint">
<h3>TITLE</h3>
<!-- 第一块 -->
<div id="<strong>module-1</strong>" class="module>
<p class="module-item">
some text
</p>
</div> <!-- 第二块 --></pre>
</li>
</ul>
<b>注意：</b>在样式的安全使用用，尽量把样式定义在相应的容器中，而不是作为全局使用
<pre class="prettyprint">
// 全局样式：除非非常通用，是不允许新建全局样式的，如果你要建，请先问一下小鱼，不然可能随时被干掉（^^）
.red{color:red!imporant;}
// 作用域：限定在一定的容器中
// 像 .hover 这样的选择器是非常普通的，如何使用？
// 这样两个容器的 .hover 就不相互影响了，记得限定作用域
.module-1 .hover{ ... }
.module-2 .hover{ ... }
</pre>
<h2>二、JavaScript 组件</h2>
<p>目前 Puerh 的大部分组件都使用 Twitter Bootstrap 库的自定义 Javascript 插件。删除了其中网站不常用的 Carousel 等组件，修改 Tips、Modals 等插件以适合百姓网需求，增加 Validator 和 Linkage 组件。</p>
<p>具体使用方法参见：<a href="./javascript.html">JavaScript 组件»</a></p>
<h2>三、反馈</h2>
<p>Puerh 将会一直在使用、一直测试完善。在使用过程中遇到问题，请优先查阅 <a href="http://arch.baixing.com/Puerh/faq.html">FAQ</a>。在此基础中，如若有任何问题、建议、批评，或者要请吃饭的，外观设计中的找 <a href="mailto:[email protected]">@登甲</a>，在使用和代码上的问题请找 <a href="mailto:[email protected]">@小鱼</a>。</p>
</div> <!-- #document -->
<div id="footer" class="grid grid-20">
<small>版权所有: 客齐集网络信息技术服务（上海）有限公司</small>
</div>
</div> <!-- .container -->
<script type="text/javascript" src="./javascripts/jquery-1.7.1.min.js"></script>
<script type="text/javascript" src="./javascripts/plugins.js"></script>
<script type="text/javascript" src="instant.js"></script>
<script type="text/javascript">
window.addEventListener && window.addEventListener('load', function(){prettyPrint()}, false);
</script>
</body>
</html>