Puerh,百姓网 UI 库。旨在建立稳定、简洁、兼容的前端框架。兼容 Mac/Windows 下的 IE6+ / Firefox / Google Chrome 浏览器。 Puerh 的目标是构建一套适合百姓网的前端解决方案。从模块区分上,她包含: Typography、 Grid、 Font Icon(Baicons)、 UI组件 和 JS 组件
第一次使用 Puerh?请看 Getting Start → 如在使用上遇到任何问题,请通过 Github Issues 给我们 提意见 →
Puerh 是百姓网 UI 库的简称。名字源自于在想为框架命名时办公桌上的一包普尔茶,因此取名“普尔(Puerh)”,希望所构建的百姓网 UI 简洁但像普尔茶一样有韵味。这个文档将介绍如何使用 Puerh 来构建 Web 界面。
所有组件均通过兼容测试、使用统一的命名注释规范。包括栅格系统、排版样式和组件样式。所有组件样式包含于 puerh.css
中。
组件兼容要求:Mac/Win 系统下的 IE6+ / Google Chrome / Firefox / Safari
使用嵌套式命名法(暂且这样称呼吧)。组件是一个整体,理应包含于一个容器中;为了便于重用,在 CSS 中我们配合 class 选择器来做模块;另外为了使命名更长度和语义上更易懂。做如下约定:
统一命名规范,让属性值与 HTML 属性一致,均使用小写。所谓的嵌套式命名,即以父级元素的名字作为子元素的命名前缀。比如 .tab
组件名的子模块,应该是 .tab-模块名
,而模块的下一级则是 .tab-模块名-子模块名
。每一级都以上一级名称加上“-”作为前缀使用。
尽量使用一个单词命名,比如 .list
、.flow
、.filter
等,不要使用像headerMeta
、header-meta
这样的写法,一来命名太长,二来不符合嵌套规范。
假设我们需要写一个 Tab 组件,Tab 是一个整体,包含在 .tab
这个 class 中,有触发点 .tab-trigger
和内容区 .tab-content
。触发点中有不同的点,内容区中有不同的内容模块。使用嵌套式的命名方法,有这样的结构:
<div class="tab"> --- 组件名 <ul class="tab-trigger"> --- 模块名 <li class="tab-trigger-item">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">content 1</div> <div class="tab-content-item">content 2</div> --- 子模块 <div class="tab-content-item">content 3</div> </div> </div> <!-- .tab -->
假设我们有一个竖排的 Tab 组件,除了把 Tab 的触发点从上面移到左边,外观上并没有其他变化。这时复用模块将可以减少重复的代码并且只作局部调整省去重复劳动。可以给组件增加一个扩展名。如:
<div class="tatab-vertical"> --- 组件名 + 扩展名 <ul class="tab-trigger"> ... </ul> <div class="tab-content"> ... </div> </div> <!-- .tab .tab-vertical-->
仍以 Tab 为例。触发点是有状态的。激活状态的标签通常和其他标签显示不同的样式,非激活状态的内容更是明显,一般都是隐藏的。因此我们需要给模块一个状态。会有这样的代码:
<div class="tab"> <ul class="tab-trigger"> <li class="tab-trigger-item tab-trigger-item-active">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 tab-content-item-active">content 1</div> --- 状态名 <div class="tab-content-item">content 2</div> <div class="tab-content-item">content 3</div> </div> </div> <!-- .tab -->
另外,值得一提的是,模块和组件一样,都可以有扩展名,命名方法同扩展命名。
所有小图标均使用 .icon
命名。使用 CSS Sprites 方式合并图片,用.icon .icon-扩展
来设定图片的背景位置。具体可以参考 Icons 组件的实现。
注释旨在指明团队协作中的创作、个性者和代码作用。在 CSS 中,无论块组还是单行注释,均使用 /* 注释 */
。由于中文注释可能导致代码失效,但中文作为团队最有效的沟通文字,最好的使用方法是,保证在/*
和*/
之间的中文前后都有空格,以保证 CSS 不会失效。
在组件中,主要使用的两种注释如下:
/* form 表单 --- 简单描述 * author: sofish@163.com --- 作者 * require: button --- 依赖(可选) */ .form{ font-family:serif\0/; /* solution:win7 ie8 line-height bug */ --- 行内注释 } …
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> // 嵌套使用:需要用于 b .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>
在 Puerh 中使用开源的 TYPO.CSS 作为排版样式。这个库不同于一般的 CSS Reset,在提供 Reset 的同时,提供适合中文并且最大化兼容种系统的排版方法。在需要排版的地方使用 .typo
作为父容器的类,或在单独需要使用的时候,使用.typo-TAGNAME
的方式单独使用。具体使用方式参考:
// 在 b .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 的情况下使用 b .typo-TAGNAME <h3 class="typo-h3">Title</h3> <ul class="typo-ul"> <li>item 1</li> <li>item 2</li> </ul>
<ul class="clearfix"> <li class="float-item">…</li> <li class="float-item">…</li> .. </ul>
<div class="close" data-dismiss="alert">×</div>
兼容是 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-block height: (除 auto外任何值) width: (除 auto外任何值) float: (left或 right) position: absolute writing-mode: tb-rl zoom: (除 normal外任意值)
常见BUG,详见:http://sofish.de/1400
有两点需要注意的,一是,注意代码重用的模块化;一是,注意 HTML 结构的模块化,而不是分块。
<div id="strong module-1" class="module"> <h3>TITLE</h3> <p class="module-item"> some text </p> </div> <div id="strong module-2" class="module"> <h3>TITLE</h3> <p class="module-item"> some text </p> </div>
/* module, reuse style in module scrope*/ .module{} .module-status{} .module-item{} .module-status .module-1-item{} /* customize */#module-1 .module-item{}#module-2 .module-item{}
<div id="strong module-1" class="module"> <h3>TITLE</h3> <p class="module-item"> some text </p> </div> <!-- #module .module -->
而不是这样写:
<h3>TITLE</h3> <!-- 第一块 --> <div id="strong module-1" class="module> <p class="module-item"> some text </p> </div> <!-- 第二块 -->
注意:在样式的安全使用用,尽量把样式定义在相应的容器中,而不是作为全局使用
// 全局样式:除非非常通用,是不允许新建全局样式的,如果你要建,请先问一下小鱼,不然可能随时被干掉(^^) .red{color:red!imporant;} // 作用域:限定在一定的容器中 // 像 .hover 这样的选择器是非常普通的,如何使用? // 这样两个容器的 .hover 就不相互影响了,记得限定作用域 .module-1 .hover{ ... } .module-2 .hover{ ... }
目前 Puerh 的大部分组件都使用 Twitter Bootstrap 库的自定义 Javascript 插件。删除了其中网站不常用的 Carousel 等组件,修改 Tips、Modals 等插件以适合百姓网需求,增加 Validator 和 Linkage 组件。
具体使用方法参见:JavaScript 组件»
Puerh 将会一直在使用、一直测试完善。在使用过程中遇到问题,如若有任何问题、建议、批评,或者要请吃饭的,外观设计中的找……暂时没有,在使用和代码上的问题请找 @Amio。