Puerh 是Chinamysee UI 库的简称。名字源自于在想为框架命名时办公桌上的一包普尔茶,因此取名“普尔(Puerh)”,希望所构建的互联网 UI 简洁但像普尔茶一样有韵味。这个文档将介绍如何使用 Puerh 来构建 Web 界面。

一、CSS 组件

所有组件均通过兼容测试、使用统一的命名注释规范。包括栅格系统、排版样式和组件样式。所有组件样式包含于 base.css 中。

组件兼容要求:Mac/Win 系统下的 IE6+ / Google Chrome / Firefox / Safari

1、命名规范

使用嵌套式命名法(暂且这样称呼吧)。组件是一个整体,理应包含于一个容器中;为了便于重用,在 CSS 中我们配合 class 选择器来做模块;另外为了使命名更长度和语义上更易懂。做如下约定:

命名中的注意点:

Icons 的命名方式:

所有小图标均使用 .icon 命名。使用 CSS Sprites 方式合并图片,用 .icon .icon-扩展 来设定图片的背景位置。具体可以参考 Icons 组件的实现。

2、注释规范

注释旨在指明团队协作中的创作、个性者和代码作用。在 CSS 中,无论块组还是单行注释,均使用 /* 注释 */。由于中文注释可能导致代码失效,但中文作为团队最有效的沟通文字,最好的使用方法是,保证在 /**/ 之间的中文前后都有空格,以保证 CSS 不会失效。

在组件中,主要使用的两种注释如下:

/* form 表单								--- 简单描述
 * author: sofish@163.com						--- 作者
 * require: button							--- 依赖(可选)
 */
.form{
    font-family:serif\0/; /* solution:win7 ie8 line-height bug */	--- 行内注释
}
…		

3、栅格系统

Puerh 使用 980px 宽、20 栏(每栏 30px)、10px 间隙的栅格系统。内容区域为 980px,撑开宽度为 1000px。所有栅格必须包含到 .container 内。使用 .grid 模块,扩展名 .grid-N N 代表 1~20 中的任意整数。

具体的使用如下:
// 包含于 .container 中
<div class="container">
	<div class="grid grid-20">...</div>
</div>

// 嵌套使用:需要用于 .first/.last 类
<div class="container">
	<div class="grid grid-20">
		<div class="grid grid-5 first">…</div>	--- 第一个容器
		<div class="grid grid-5">…</div>	--- 中间可以多个
		<div class="grid grid-10 last">…</div>	--- 最后一个容器
	</div>
</div>

4、排版类:TYPO.CSS

在 Puerh 中使用开源的 TYPO.CSS 作为排版样式。这个库不同于一般的 CSS Reset,在提供 Reset 的同时,提供适合中文并且最大化兼容种系统的排版方法。在需要排版的地方使用 .typo 作为父容器的类,或在单独需要使用的时候,使用 .typo-TAGNAME 的方式单独使用。具体使用方式参考:

// 在 .typo 内使用标签,将对应相应语义显示
<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 的情况下使用 .typo-TAGNAME
<h3 class="typo-h3">Title</h3>
<ul class="typo-ul">
	<li>item 1</li>
	<li>item 2</li>
</ul>

5、小工具

6、兼容:CSS Hack

兼容是 CSS 中最大的难点。各种 hack 可以帮助你快速解决问题,但不一定是解决问题的真正方法。所以,hack 应该尽量避免使用。很多时候都是写法决定 bug,在有时间允许的情况下,请多进行测试以找到最佳方式。

.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;} }

目前在网站中会自动添加 body class,显示方式如下:浏览器 版本号 系统名

// 在 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()

注意:别用轻易使用hack,IE下很多兼容性问题都是 has Layout 引起的。试着给元素加上:

display: inline-blockheight: (除 auto外任何值)
width: (除 auto外任何值)
float: (left或 right)
position: absolutewriting-mode: tb-rlzoom: (除 normal外任意值) 

7、IE私有特性

8、关于模块化

有两点需要注意的,一是,注意代码重用的模块化;一是,注意 HTML 结构的模块化,而不是分块。

注意:在样式的安全使用用,尽量把样式定义在相应的容器中,而不是作为全局使用
// 全局样式:除非非常通用,是不允许新建全局样式的,如果你要建,请先问一下小鱼,不然可能随时被干掉(^^)
.red{color:red!imporant;}

// 作用域:限定在一定的容器中
// 像 .hover 这样的选择器是非常普通的,如何使用?
// 这样两个容器的 .hover 就不相互影响了,记得限定作用域
.module-1 .hover{ ... }
.module-2 .hover{ ... }
 		

二、JavaScript 组件

目前 Puerh 的大部分组件都使用 Twitter Bootstrap 库的自定义 Javascript 插件。删除了其中网站不常用的 Carousel 等组件,修改 Tips、Modals 等插件以适合互联网需求,增加 Validator 和 Linkage 组件。

具体使用方法参见:JavaScript 组件»

三、反馈

Puerh 将会一直在使用、一直测试完善。在使用过程中遇到问题,请优先查阅 FAQ。在此基础中,如若有任何问题、建议、批评,或者要请吃饭的,外观设计中和代码使用上的问题请找 @Chinamysee