├── .editorconfig ├── .gitignore ├── LICENSE ├── README.md ├── _config.yml ├── gulpfile.js ├── package.json ├── scaffolds ├── page.md └── post.md ├── scripts ├── helper.bstoc.js ├── helpers.js └── tags.js ├── source ├── _data │ ├── languages.yml │ ├── menu.yml │ ├── plugins.yml │ ├── sidebar.yml │ └── themes.yml ├── _posts │ ├── 2015-11-13-first-released.md │ └── 2015-11-15-beta-released.md ├── browserconfig.xml ├── docs │ ├── common.md │ ├── common │ │ └── markdown.md │ ├── contributing.md │ ├── css │ │ ├── code.md │ │ ├── jdc_fd_guide_css.md │ │ ├── note.md │ │ ├── query.md │ │ ├── reset.md │ │ ├── sass.md │ │ └── webkit.md │ ├── html │ │ ├── code.md │ │ ├── jdc_fd_web_final_2.md │ │ ├── note.md │ │ ├── template.md │ │ └── webapp.md │ ├── image │ │ ├── format.md │ │ ├── import.md │ │ ├── jdc_fd_guide_image.md │ │ ├── quality.md │ │ └── size.md │ ├── index.md │ ├── issues.md │ ├── js │ │ ├── code.md │ │ ├── language.md │ │ └── react.md │ └── name │ │ ├── classname.md │ │ ├── dir.md │ │ ├── htmlcss.md │ │ ├── image.md │ │ └── jdc_fd_guide_name.md ├── favicon.ico ├── index.jade ├── plugins │ └── index.md ├── robots.txt └── themes │ └── index.md ├── themes └── navy │ ├── languages │ ├── en.yml │ └── zh-cn.yml │ ├── layout │ ├── archive.swig │ ├── index.swig │ ├── layout.swig │ ├── page.swig │ ├── partial │ │ ├── after_footer.swig │ │ ├── baidu_analytics.swig │ │ ├── comment.swig │ │ ├── footer.swig │ │ ├── google_analytics.swig │ │ ├── head.swig │ │ ├── header.swig │ │ ├── mobile_nav.swig │ │ ├── plugin.swig │ │ ├── post.swig │ │ ├── share.swig │ │ ├── sidebar.swig │ │ └── theme.swig │ ├── plugins.swig │ └── post.swig │ └── source │ ├── assets │ └── bootstrap │ │ ├── css │ │ ├── bootstrap-theme.css │ │ ├── bootstrap-theme.css.map │ │ ├── bootstrap-theme.min.css │ │ ├── bootstrap.css │ │ ├── bootstrap.css.map │ │ └── bootstrap.min.css │ │ ├── fonts │ │ ├── glyphicons-halflings-regular.eot │ │ ├── glyphicons-halflings-regular.svg │ │ ├── glyphicons-halflings-regular.ttf │ │ ├── glyphicons-halflings-regular.woff │ │ └── glyphicons-halflings-regular.woff2 │ │ └── js │ │ ├── bootstrap.js │ │ ├── bootstrap.min.js │ │ └── npm.js │ ├── css │ ├── _partial │ │ ├── archive.styl │ │ ├── base.styl │ │ ├── font-awesome.css │ │ ├── fonts.css │ │ ├── footer.styl │ │ ├── header.styl │ │ ├── highlight.styl │ │ ├── index.styl │ │ ├── mobile_nav.styl │ │ ├── page.styl │ │ ├── plugins.styl │ │ ├── post.styl │ │ ├── sidebar.styl │ │ └── tables.styl │ ├── _variables.styl │ └── navy.styl │ ├── fonts │ ├── FontAwesome.otf │ ├── fontawesome-webfont.eot │ ├── fontawesome-webfont.svg │ ├── fontawesome-webfont.ttf │ ├── fontawesome-webfont.woff │ ├── fontawesome-webfont.woff2 │ └── lato │ │ └── v11 │ │ ├── 22JRxvfANxSmnAhzbFH8PgLUuEpTyoUstqEm5AMlJo4.woff2 │ │ ├── 8qcEw_nrk_5HEcCpYdJu8BTbgVql8nDJpwnrE27mub0.woff2 │ │ ├── IY9HZVvI1cMoAHxvl0w9LVKPGs1ZzpMvnHX-7fPOuAc.woff2 │ │ ├── MDadn8DQ_3oT6kvnUq_2r_esZW2xOQ-xsNqO47m55DA.woff2 │ │ ├── MgNNr5y1C_tIEuLEmicLmwLUuEpTyoUstqEm5AMlJo4.woff2 │ │ └── rZPI2gHXi8zxUjnybc2ZQFKPGs1ZzpMvnHX-7fPOuAc.woff2 │ ├── img │ ├── android-chrome-144x144.png │ ├── android-chrome-192x192.png │ ├── android-chrome-36x36.png │ ├── android-chrome-48x48.png │ ├── android-chrome-72x72.png │ ├── android-chrome-96x96.png │ ├── apple-touch-icon-114x114.png │ ├── apple-touch-icon-120x120.png │ ├── apple-touch-icon-144x144.png │ ├── apple-touch-icon-152x152.png │ ├── apple-touch-icon-180x180.png │ ├── apple-touch-icon-57x57.png │ ├── apple-touch-icon-60x60.png │ ├── apple-touch-icon-72x72.png │ ├── apple-touch-icon-76x76.png │ ├── apple-touch-icon-precomposed.png │ ├── apple-touch-icon.png │ ├── apple-touch-startup-image-1182x2208.png │ ├── apple-touch-startup-image-1242x2148.png │ ├── apple-touch-startup-image-1496x2048.png │ ├── apple-touch-startup-image-1536x2008.png │ ├── apple-touch-startup-image-320x460.png │ ├── apple-touch-startup-image-640x1096.png │ ├── apple-touch-startup-image-640x920.png │ ├── apple-touch-startup-image-748x1024.png │ ├── apple-touch-startup-image-750x1294.png │ ├── apple-touch-startup-image-768x1004.png │ ├── browserconfig.xml │ ├── coast-228x228.png │ ├── favicon-16x16.png │ ├── favicon-230x230.png │ ├── favicon-32x32.png │ ├── favicon-96x96.png │ ├── favicon.ico │ ├── firefox_app_128x128.png │ ├── firefox_app_512x512.png │ ├── firefox_app_60x60.png │ ├── logo.png │ ├── manifest.json │ ├── manifest.webapp │ ├── mstile-144x144.png │ ├── mstile-150x150.png │ ├── mstile-310x150.png │ ├── mstile-310x310.png │ ├── mstile-70x70.png │ ├── open-graph.png │ ├── twitter.png │ ├── yandex-browser-50x50.png │ └── yandex-browser-manifest.json │ └── js │ ├── hammer.js │ ├── jquery.js │ ├── lang_select.js │ ├── lunr.js │ ├── mobile_nav.js │ ├── plugins.js │ └── toc.js └── yarn.lock /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | charset = utf-8 5 | indent_style = space 6 | indent_size = 2 7 | end_of_line = lf 8 | insert_final_newline = true 9 | trim_trailing_whitespace = true 10 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | .deploy_git 3 | node_modules 4 | .gitignore 5 | db.json 6 | public 7 | 8 | 9 | db.json 10 | *.log 11 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 SUPER O2 MAN 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Front-End Coding Guidelines 2 | 3 | Installation Coding Guidelines For Front-End Developers. 4 | 5 | ## Getting started 6 | 7 | Install dependencies: 8 | 9 | ``` bash 10 | $ git clone https://github.com/o2team/guide.git 11 | $ cd guide 12 | $ npm install 13 | ``` 14 | 15 | Generate: 16 | 17 | ``` bash 18 | $ hexo g 19 | ``` 20 | 21 | Run server: 22 | 23 | ``` bash 24 | $ hexo s --watch 25 | ``` 26 | 27 | ## Deployment 28 | 29 | 1. Generate and optimize assets 30 | 31 | ```bash 32 | gulp 33 | ``` 34 | 35 | 2. Deploy to the gh-pages branch 36 | 37 | ```bash 38 | hexo d -g 39 | ``` 40 | 41 | ## License 42 | 43 | [CC BY 4.0](http://creativecommons.org/licenses/by/4.0/) 44 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | title: Aotu.io - 前端代码规范 2 | subtitle: "Front-End Coding Guidelines" 3 | description: "Best Coding Guidelines For Front-End Developer." 4 | author: 凹凸实验室 5 | language: zh-cn 6 | timezone: UTC 7 | url: http://guide.aotu.io/ 8 | root: / 9 | permalink: news/:year/:month/:day/:title/ 10 | archive_dir: news 11 | code_dir: downloads/code 12 | new_post_name: :year-:month-:day-:title.md # File name of new posts 13 | post_asset_folder: true 14 | highlight: 15 | enable: true 16 | line_number: false 17 | per_page: 0 18 | 19 | theme: navy 20 | deploy: 21 | type: git 22 | repo: git@github.com:o2team/guide.git 23 | branch: gh-pages 24 | 25 | disqus_shortname: 26 | google_analytics: UA-4910098-10 27 | baidu_analytics: bb4b770d7fdf4e05245cd1327199d813 28 | fb_admins: 100000247608790 29 | swiftype_key: nxhXzi1rDss_9_P_6zBa 30 | twitter: o2circle 31 | github: o2team/guide 32 | gh: 33 | user: o2team 34 | repo: guide 35 | -------------------------------------------------------------------------------- /gulpfile.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | var gulp = require('gulp'), 4 | $ = require('gulp-load-plugins')(), 5 | cssnano = require('cssnano'), 6 | yaml = require('js-yaml'), 7 | fs = require('fs'), 8 | cfg = yaml.safeLoad(fs.readFileSync('_config.yml')); 9 | 10 | require('shelljs/global'); 11 | 12 | var htmlMinifierOptions = { 13 | removeComments: true, 14 | collapseWhitespace: true, 15 | collapseBooleanAttributes: true, 16 | removeScriptTypeAttributes: true, 17 | removeStyleLinkTypeAttributes: true, 18 | removeOptionalTags: true, 19 | minifyJS: true, 20 | minifyCSS: true 21 | }; 22 | 23 | var dirs = { 24 | public: 'public', 25 | fonts: 'public/fonts', 26 | imgs: 'public/img', 27 | assetsDir:'public/assets' 28 | }; 29 | 30 | gulp.task('useref', ['hexo'], function(){ 31 | 32 | return gulp.src('public/**/*.html') 33 | .pipe($.useref({ 34 | searchPath:'public', 35 | transformPath: function(filePath) { 36 | return filePath.replace(dirs.public + cfg.root, dirs.public + '/'); 37 | } 38 | })) 39 | .pipe($.if('*.css', $.postcss([ 40 | cssnano() 41 | ]))) 42 | .pipe($.if('*.css', $.minifyCss())) 43 | .pipe($.if('*.js', $.uglify())) 44 | .pipe($.if('*.html', $.htmlMinifier(htmlMinifierOptions))) 45 | .pipe(gulp.dest('public')); 46 | }); 47 | 48 | gulp.task('rev:media', function(){ 49 | 50 | return gulp.src([dirs.fonts + '/**/*', dirs.imgs + '/**/*'], {base: dirs.public}) 51 | .pipe($.rev()) 52 | .pipe(gulp.dest(dirs.assetsDir)) 53 | .pipe($.rev.manifest('rev-media.json')) 54 | .pipe(gulp.dest(dirs.assetsDir)); 55 | 56 | }); 57 | 58 | gulp.task('rev:scripts', ['useref', 'rev:media'], function(){ 59 | var manifest = gulp.src(dirs.assetsDir + '/rev-media.json'); 60 | 61 | return gulp.src([dirs.public + '/css/dist*.css', dirs.public + '/js/dist*.js'], {base: dirs.public}) 62 | .pipe($.rev()) 63 | .pipe($.revReplace({ 64 | manifest: manifest 65 | })) 66 | .pipe(gulp.dest(dirs.assetsDir)) 67 | .pipe($.rev.manifest()) 68 | .pipe(gulp.dest(dirs.assetsDir)); 69 | 70 | }); 71 | 72 | gulp.task('img:min', ['rev:media'], function(){ 73 | 74 | var pngquant = require('imagemin-pngquant'); 75 | 76 | return gulp.src(dirs.assetsDir + '/img/**/*', {base: dirs.assetsDir}) 77 | .pipe($.imagemin({ 78 | progressive: true, 79 | svgoPlugins: [{removeViewBox:false}], 80 | use:[pngquant()] 81 | })) 82 | .pipe(gulp.dest(dirs.assetsDir)) 83 | }); 84 | 85 | gulp.task("rev:replace", ["rev:scripts"], function(){ 86 | var manifest = gulp.src([dirs.assetsDir + '/rev-*.json']); 87 | 88 | return gulp.src([ dirs.public + "/**/*.html"]) 89 | .pipe($.revReplace({ 90 | manifest: manifest, 91 | modifyReved:function(fileName){ 92 | if(fileName.indexOf('/dist') > -1){ 93 | //special files proccessed by gulp-useref 94 | fileName = cfg.root + 'assets/' + fileName; 95 | }else { 96 | fileName = 'assets/' + fileName; 97 | } 98 | return fileName; 99 | } 100 | })) 101 | .pipe(gulp.dest(dirs.public)); 102 | }); 103 | 104 | gulp.task('hexo', function(){ 105 | 106 | exec('hexo g'); 107 | 108 | }); 109 | 110 | gulp.task('img', ['img:min']); 111 | gulp.task('default', ['rev:replace', 'img']); 112 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "hexo-site", 3 | "version": "0.0.0", 4 | "private": true, 5 | "hexo": { 6 | "version": "3.9.0" 7 | }, 8 | "scripts": { 9 | "serve": "hexo s --watch", 10 | "build": "hexo generate && gulp" 11 | }, 12 | "dependencies": { 13 | "cheerio": "^0.19.0", 14 | "hexo": "^3.1.1", 15 | "hexo-deployer-git": "0.0.4", 16 | "hexo-generator-archive": "^0.1.3", 17 | "hexo-generator-feed": "^1.0.3", 18 | "hexo-generator-sitemap": "^1.0.1", 19 | "hexo-renderer-jade": "^0.1.0", 20 | "hexo-renderer-marked": "^0.2.5", 21 | "hexo-renderer-stylus": "^0.3.0", 22 | "hexo-server": "^0.1.2", 23 | "lodash": "^3.10.1", 24 | "lunr": "^0.6.0" 25 | }, 26 | "devDependencies": { 27 | "cssnano": "^3.3.1", 28 | "gulp": "^3.9.0", 29 | "gulp-favicons": "^2.1.3", 30 | "gulp-html-minifier": "^0.1.6", 31 | "gulp-if": "^2.0.0", 32 | "gulp-ignore": "^2.0.1", 33 | "gulp-image-resize": "^0.7.1", 34 | "gulp-imagemin": "^2.4.0", 35 | "gulp-load-plugins": "^1.1.0", 36 | "gulp-minify-css": "^1.2.1", 37 | "gulp-minify-html": "^1.0.4", 38 | "gulp-postcss": "^6.0.1", 39 | "gulp-rename": "^1.2.2", 40 | "gulp-rev": "^6.0.1", 41 | "gulp-rev-collector": "^1.0.2", 42 | "gulp-rev-replace": "^0.4.2", 43 | "gulp-uglify": "^1.5.1", 44 | "gulp-useref": "^3.0.0", 45 | "imagemin-pngquant": "^4.2.0", 46 | "js-yaml": "^3.4.3", 47 | "shelljs": "^0.5.3" 48 | }, 49 | "optionalDependencies": { 50 | "hexo-browsersync": "^0.1.0" 51 | } 52 | } -------------------------------------------------------------------------------- /scaffolds/page.md: -------------------------------------------------------------------------------- 1 | title: {{ title }} 2 | --- -------------------------------------------------------------------------------- /scaffolds/post.md: -------------------------------------------------------------------------------- 1 | title: {{ title }} 2 | --- -------------------------------------------------------------------------------- /scripts/helper.bstoc.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | var cheerio; 3 | 4 | function bsTOC(str, options) { 5 | options = options || {}; 6 | 7 | if (!cheerio) cheerio = require('cheerio'); 8 | 9 | var $ = cheerio.load(str); 10 | var headings = $('h1, h2, h3, h4, h5, h6'); 11 | 12 | if (!headings.length) return ''; 13 | 14 | var className = options.class || 'nav'; 15 | var listNumber = options.hasOwnProperty('list_number') ? options.list_number : true; 16 | var result = ''; 36 | } 37 | 38 | if (level > lastLevel) { 39 | result += ''; 67 | } 68 | 69 | return result; 70 | }; 71 | /** 72 | * boostrap scrollspy compatible toc 73 | */ 74 | hexo.extend.helper.register('bstoc', function(str, opts){ 75 | return bsTOC(str, opts); 76 | }); 77 | -------------------------------------------------------------------------------- /scripts/helpers.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | var pathFn = require('path'); 4 | var _ = require('lodash'); 5 | var url = require('url'); 6 | var cheerio = require('cheerio'); 7 | var lunr = require('lunr'); 8 | 9 | var localizedPath = ['docs', 'api']; 10 | 11 | function startsWith(str, start){ 12 | return str.substring(0, start.length) === start; 13 | } 14 | 15 | hexo.extend.helper.register('page_nav', function(){ 16 | var type = this.page.canonical_path.split('/')[0]; 17 | var sidebar = this.site.data.sidebar[type]; 18 | var path = this.path.substr(this.path.indexOf(type+'/') + (type+'/').length); 19 | var list = {}; 20 | var prefix = 'sidebar.' + type + '.'; 21 | 22 | for (var i in sidebar){ 23 | for (var j in sidebar[i]){ 24 | list[sidebar[i][j]] = j; 25 | } 26 | } 27 | 28 | var keys = Object.keys(list); 29 | var index = keys.indexOf(path); 30 | var result = ''; 31 | 32 | if (index > 0){ 33 | path = this.url_for_lang(type + '/' + keys[index-1]); 34 | result += '' + 35 | '' + this.__('page.prev') + ''; 36 | } 37 | 38 | if (index < keys.length - 1){ 39 | path = this.url_for_lang(type + '/' + keys[index+1]); 40 | result += '' + 41 | '' + this.__('page.next') + ''; 42 | } 43 | 44 | return result; 45 | }); 46 | 47 | hexo.extend.helper.register('doc_sidebar', function(className){ 48 | var type = this.page.canonical_path.split('/')[0]; 49 | var sidebar = this.site.data.sidebar[type]; 50 | var path = pathFn.basename(this.path); 51 | var result = ''; 52 | var self = this; 53 | var prefix = 'sidebar.' + type + '.'; 54 | var lang = this.page.lang; 55 | var isDefaultLang = lang === 'zh-cn'; 56 | var docRoot = this.url_for( isDefaultLang ? 'docs/' : lang + '/docs/' ); 57 | 58 | _.each(sidebar, function(menu, title){ 59 | result += '' + self.__(prefix + title) + ''; 60 | 61 | _.each(menu, function(link, text){ 62 | var itemClass = className + '-link'; 63 | link = docRoot + link; 64 | if (link.indexOf(path) > -1) itemClass += ' current'; 65 | 66 | result += '' + self.__(prefix + text) + ''; 67 | }) 68 | }); 69 | 70 | return result; 71 | }); 72 | 73 | hexo.extend.helper.register('header_menu', function(className){ 74 | var menu = this.site.data.menu; 75 | var result = ''; 76 | var self = this; 77 | var lang = this.page.lang; 78 | var isDefaultLang = lang === 'zh-cn'; 79 | 80 | _.each(menu, function(path, title){ 81 | if (!isDefaultLang && ~localizedPath.indexOf(title)) path = lang + '/' + path; 82 | 83 | result += '
  • '; 84 | result += '' + self.__('menu.' + title) + ''; 85 | result += '
    • '; 86 | }); 87 | 88 | return result; 89 | }); 90 | 91 | hexo.extend.helper.register('canonical_url', function(lang){ 92 | var path = this.page.canonical_path; 93 | if (lang && lang !== 'zh-cn') path = lang + '/' + path; 94 | 95 | return this.config.url + '/' + path; 96 | }); 97 | 98 | hexo.extend.helper.register('url_for_lang', function(path){ 99 | var lang = this.page.lang; 100 | var isDefaultLang = lang === 'zh-cn'; 101 | var url = path; 102 | 103 | if (!isDefaultLang && lang) url = lang + '/' + url; 104 | 105 | url = this.url_for(url); 106 | 107 | return url; 108 | }); 109 | 110 | hexo.extend.helper.register('raw_link', function(path){ 111 | return 'https://github.com/o2team/guide/edit/master/source/' + path; 112 | }); 113 | 114 | hexo.extend.helper.register('page_anchor', function(str){ 115 | var $ = cheerio.load(str, {decodeEntities: false}); 116 | var headings = $('h1, h2, h3, h4, h5, h6'); 117 | 118 | if (!headings.length) return str; 119 | 120 | headings.each(function(){ 121 | var id = $(this).attr('id'); 122 | 123 | $(this) 124 | .addClass('article-heading') 125 | .append(''); 126 | }); 127 | 128 | return $.html(); 129 | }); 130 | 131 | hexo.extend.helper.register('lunr_index', function(data){ 132 | var index = lunr(function(){ 133 | this.field('name', {boost: 10}); 134 | this.field('tags', {boost: 50}); 135 | this.field('description'); 136 | this.ref('id'); 137 | }); 138 | 139 | _.sortBy(data, 'name').forEach(function(item, i){ 140 | index.add(_.assign({id: i}, item)); 141 | }); 142 | 143 | return JSON.stringify(index.toJSON()); 144 | }); 145 | 146 | hexo.extend.helper.register('canonical_path_for_nav', function(){ 147 | var path = this.page.canonical_path; 148 | 149 | if (startsWith(path, 'docs/') || startsWith(path, 'api/')){ 150 | return path; 151 | } else { 152 | return ''; 153 | } 154 | }); 155 | 156 | hexo.extend.helper.register('lang_name', function(lang){ 157 | var data = this.site.data.languages[lang]; 158 | return data.name || data; 159 | }); 160 | 161 | hexo.extend.helper.register('disqus_lang', function(){ 162 | var lang = this.page.lang; 163 | var data = this.site.data.languages[lang]; 164 | 165 | return data.disqus_lang || lang; 166 | }); 167 | -------------------------------------------------------------------------------- /scripts/tags.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | hexo.extend.tag.register('note', function(args, content){ 4 | var className = args.shift(); 5 | var header = ''; 6 | var result = ''; 7 | 8 | if (args.length){ 9 | header += '' + args.join(' ') + ''; 10 | } 11 | 12 | result += '
    ' + header; 13 | result += hexo.render.renderSync({text: content, engine: 'markdown'}); 14 | result += '
    '; 15 | 16 | return result; 17 | }, true); -------------------------------------------------------------------------------- /source/_data/languages.yml: -------------------------------------------------------------------------------- 1 | zh-cn: 2 | name: 简体中文 3 | disqus_lang: zh 4 | en: English 5 | -------------------------------------------------------------------------------- /source/_data/menu.yml: -------------------------------------------------------------------------------- 1 | docs: docs/ 2 | news: news/ 3 | -------------------------------------------------------------------------------- /source/_data/sidebar.yml: -------------------------------------------------------------------------------- 1 | docs: 2 | getting_started: 3 | overview: index.html 4 | html: 5 | html_code: html/code.html 6 | html_note: html/note.html 7 | html_template: html/template.html 8 | html_webapp: html/webapp.html 9 | image: 10 | image_format: image/format.html 11 | image_size: image/size.html 12 | image_quality: image/quality.html 13 | image_import: image/import.html 14 | css: 15 | css_code: css/code.html 16 | css_note: css/note.html 17 | css_sass: css/sass.html 18 | css_reset: css/reset.html 19 | css_query: css/query.html 20 | css_webkit: css/webkit.html 21 | name: 22 | name_dir: name/dir.html 23 | name_image: name/image.html 24 | name_htmlcss: name/htmlcss.html 25 | name_class: name/classname.html 26 | js: 27 | js_language: js/language.html 28 | js_code: js/code.html 29 | js_react: js/react.html 30 | -------------------------------------------------------------------------------- /source/_data/themes.yml: -------------------------------------------------------------------------------- 1 | - name: landscape 2 | description: A brand new default theme for Hexo. 3 | link: https://github.com/hexojs/hexo-theme-landscape 4 | preview: http://hexo.io/hexo-theme-landscape 5 | tags: 6 | - official 7 | - responsive 8 | - widget 9 | - two_column 10 | - one_column 11 | - name: phase 12 | description: Feel the flow of time with Phase. 13 | link: https://github.com/hexojs/hexo-theme-phase 14 | preview: http://hexo.io/hexo-theme-phase 15 | tags: 16 | - official 17 | - one_column 18 | - name: light 19 | description: Default theme for Hexo. 20 | link: https://github.com/hexojs/hexo-theme-light 21 | preview: http://hexo.io/hexo-theme-light 22 | tags: 23 | - official 24 | - responsive 25 | - two_column 26 | - name: NexT 27 | description: NexT is an elegant theme for Hexo. 28 | link: https://github.com/iissnan/hexo-theme-next 29 | preview: http://notes.iissnan.com/ 30 | tags: 31 | - responsive 32 | - one_column 33 | - clean 34 | - white 35 | - name: Icarus 36 | description: 'The blog theme you may fall in love with, coming to Hexo.' 37 | link: https://github.com/ppoffice/hexo-theme-icarus 38 | preview: https://ppoffice.github.io/hexo-theme-icarus 39 | tags: 40 | - responsive 41 | - three_column 42 | - clean 43 | - flat 44 | - light 45 | - name: Hueman 46 | description: A redesign of Alx's wordpress theme Hueman, ported to Hexo. 47 | link: https://github.com/ppoffice/hexo-theme-hueman 48 | preview: https://ppoffice.github.io/hexo-theme-hueman 49 | tags: 50 | - responsive 51 | - two_column 52 | - wordpress 53 | - elegant 54 | - hueman 55 | - name: carbon 56 | description: Carbon is a simple theme using pjax for elegant loading. 57 | link: https://github.com/icylogic/carbon 58 | preview: https://blog.icylogic.net 59 | tags: 60 | - simple 61 | - white & black 62 | - pjax 63 | - name: hexadillax 64 | description: XadillaX built this theme with love and an otaku heart. 65 | link: https://github.com/XadillaX/hexadillax 66 | preview: https://xcoder.in/ 67 | tags: 68 | - bootstrap 69 | - simple 70 | - otaku 71 | - name: Jacman 72 | description: A fresh looking and responsive theme for Hexo. 73 | link: https://github.com/wuchong/jacman 74 | preview: http://wuchong.me/jacman 75 | tags: 76 | - responsive 77 | - two_column 78 | - blue 79 | - elegant 80 | - name: Wixo 81 | description: Turn your Hexo into a Wiki! 82 | link: https://github.com/wzpan/hexo-theme-wixo 83 | preview: http://wzpan.github.io/hexo-theme-wixo/ 84 | tags: 85 | - wiki 86 | - responsive 87 | - simple 88 | - tag_plugins 89 | - bootstrap 90 | - modal 91 | - name: Freemind 92 | description: Fully taking advantages of Bootstrap. 93 | link: https://github.com/wzpan/hexo-theme-freemind 94 | preview: http://wzpan.github.io/hexo-theme-freemind/ 95 | tags: 96 | - two_column 97 | - responsive 98 | - elegant 99 | - tag_plugins 100 | - bootstrap 101 | - name: Simplest 102 | description: Very simple, written with swig & scss. 103 | link: https://github.com/dnxbf321/hexo-theme-simplest 104 | preview: https://dnxbf321.github.io 105 | tags: 106 | - responsive 107 | - swig 108 | - scss 109 | - one_column 110 | - name: hexoThemeKacper 111 | description: Suitable for products blog 112 | link: https://github.com/jaywcjlove/hexoThemeKacper 113 | preview: http://JSlite.io 114 | tags: 115 | - bootstrap 116 | - tag_plugins 117 | - elegant 118 | - name: Tranquilpeak 119 | description: 'A gorgeous responsive theme for Hexo blog framework' 120 | link: https://github.com/LouisBarranqueiro/tranquilpeak-hexo-theme 121 | preview: http://louisbarranqueiro.github.io/tranquilpeak-hexo-theme 122 | tags: 123 | - responsive 124 | - gorgeous 125 | - sidebar 126 | - two_column 127 | - one_column 128 | - tag_plugins 129 | - name: Minos 130 | description: A simple and retro styled Hexo theme, concentrated more on your ideas. 131 | link: https://github.com/ppoffice/hexo-theme-minos 132 | preview: http://ppoffice.github.io/hexo-theme-minos 133 | tags: 134 | - responsive 135 | - one_column 136 | - simple 137 | - retro 138 | - white 139 | - name: Foundation 140 | description: A theme based on the Zurb Foundation 5 theme. 141 | link: https://github.com/chrisjlee/hexo-theme-zurb-foundation 142 | preview: http://chrisjlee.github.io/hexo-theme-zurb-foundation 143 | tags: 144 | - responsive 145 | - mobile_first 146 | - simple 147 | - white 148 | - name: simpleblock 149 | description: A simple theme inspired by Twenty Twelve. 150 | link: https://github.com/jysperm/hexo-theme-simpleblock 151 | preview: https://jysperm.me 152 | tags: 153 | - responsive 154 | - two_column 155 | - simple 156 | - light 157 | - name: yinwang 158 | description: Simplest View For Your Article Best. 159 | link: https://github.com/mickeyouyou/yinwang 160 | preview: http://www.fzb.me 161 | tags: 162 | - responsive 163 | - simple 164 | - chinese 165 | - name: zzoman2015 166 | description: Simplest Theme by ZZOMAN 167 | link: https://github.com/reumia/hexo-theme-zzoman2015 168 | preview: http://dev.zzoman.com 169 | tags: 170 | - simple 171 | - responsive 172 | - one_column 173 | - korean 174 | - name: Maupassant 175 | description: A simple Hexo template with great performance on different devices. 176 | link: https://github.com/tufu9441/maupassant-hexo 177 | preview: https://www.haomwei.com 178 | tags: 179 | - simple 180 | - responsive 181 | - two_column 182 | - white 183 | - jade 184 | - scss 185 | - name: ttstyle 186 | description: A three column theme for hexo.Responsive And SEO best. 187 | link: https://github.com/tangkunyin/hexo-theme-ttstyle 188 | preview: http://shuoit.net 189 | tags: 190 | - responsive 191 | - simple 192 | - seo 193 | - chinese 194 | - three_column 195 | - name: Jekyll 196 | description: A hexo theme inspire by jekyllrb.com. 197 | link: https://github.com/pinggod/hexo-theme-jekyll 198 | preview: http://pinggod.com 199 | tags: 200 | - 中文 201 | - jekyll 202 | - dark 203 | - name: Yelee 204 | description: Another simple and elegant Hexo theme by MOxFIVE 205 | link: https://github.com/MOxFIVE/hexo-theme-yelee 206 | preview: http://moxfive.xyz 207 | tags: 208 | - responsive 209 | - two_column 210 | - toc 211 | - elegant 212 | - simple 213 | - background_image 214 | -------------------------------------------------------------------------------- /source/_posts/2015-11-13-first-released.md: -------------------------------------------------------------------------------- 1 | title: V1.0.0 Preview (预览版) 2 | layout: post 3 | --- 4 | 5 | `MAC全栈开发环境搭建指南` 中文预览版发布。感谢各位开源贡献人员。 6 | 7 | ## 特性 8 | 9 | - **[HEXO](https://github.com/hexojs/hexo)**: 使用hexo作为指南的静态站点引擎。 10 | - 按照工作角色将指南分为通用、交互、视觉、前端开发、后台开发等几个部分。 11 | - 修复了hexo文档大纲的bug。 12 | -------------------------------------------------------------------------------- /source/_posts/2015-11-15-beta-released.md: -------------------------------------------------------------------------------- 1 | title: V1.0.0 Beta Released 2 | layout: post 3 | --- 4 | 5 | `MAC全栈开发环境搭建指南` 中英双语V1.0.0 Beta版本发布。感谢各位开源贡献人员。 6 | 7 | ## 特性 8 | 9 | - 中文双语版本 10 | 11 | 英文为简版，6级刚刚及格抱歉了~ 12 | 欢迎英文达人参与 `MAC全栈开发环境搭建指南` 的维护。 13 | 14 | - 修复了配置站点根目录为网站子目录时切换语言404的bug。 15 | - 去掉了retinajs的特性，现在srcset支持不错，没必要使用retinajs做响应式图片加载。 16 | -------------------------------------------------------------------------------- /source/browserconfig.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | #2f83cd 10 | 11 | 12 | 13 | -------------------------------------------------------------------------------- /source/docs/common.md: -------------------------------------------------------------------------------- 1 | title: 通用设置 2 | --- 3 | 如没有特别的标明`开发者适用`，通用设置部分内容适用于所有使用MAC工作的朋友。 4 | 5 | 6 | 7 | 8 | -------------------------------------------------------------------------------- /source/docs/contributing.md: -------------------------------------------------------------------------------- 1 | title: 贡献 2 | --- 3 | ## 完善 4 | 5 | [凹凸实验室](http://aotu.io) 的宗旨是 `面向开放 - Open Oriented`，所以十分欢迎大家一起参与完善我们的`全栈MAC装机指南`。本文档将帮助大家了解参与的具体过程。 6 | 7 | ### 开始之前 8 | 9 | 本指南使用[hexo](https://hexo.io)作为静态站点引擎，请先安装hexo的本地环境。 10 | 11 | ``` bash 12 | npm i -g hexo-cli 13 | ``` 14 | 15 | ### 如何做？ 16 | 17 | 1. Fork 源码[o2team/mac]. 18 | 2. 克隆Fork后的仓库至你的电脑，安装依赖包。 19 | 20 | {% code %} 21 | $ git clone https://github.com//mac.git 22 | $ cd mac 23 | $ npm install 24 | {% endcode %} 25 | 26 | 3. 创建一个特性分支. 27 | 28 | {% code %} 29 | $ git checkout -b new_feature 30 | {% endcode %} 31 | 32 | 4. 启动hexo服务，预览文档 33 | 34 | ``` bash 35 | hexo s -watch 36 | ``` 37 | 38 | 关于hexo更多的用法，请参考hexo官网。 39 | 40 | 5. 用你喜爱的编辑器在本地电脑进行文档的修改. 41 | 6. 提交分支: 42 | 43 | {% code %} 44 | $ git push origin new_feature 45 | {% endcode %} 46 | 47 | 7. 创建PR（pull request） 并描述具体的改动. 48 | 49 | 50 | ### 注意事项 51 | 52 | - 别修改 `package.json` 中的版本号. 53 | - 我们在收到PR时会第一时间审核并Merge你的改动，请确保改动的地方不存在排版等问题。 54 | 55 | 56 | ## 问题反馈 57 | 58 | 在使用`全栈MAC装机指南`过程中碰到任何问题，可以到 [GitHub](https://github.com/o2team/mac/issues) 上留言提问。 59 | 60 | [o2team/mac]: https://github.com/o2team/mac 61 | 62 | ## 贡献者 63 | 64 | 排名不分先后。 65 | 66 | - [mamboer](https://github.com/mamboer) 67 | - [cnt1992](https://github.com/cnt1992) 68 | -------------------------------------------------------------------------------- /source/docs/css/code.md: -------------------------------------------------------------------------------- 1 | title: 代码规范 2 | --- 3 | 4 | ## 编码规范 5 | 6 | CSS样式表是一个序列通用字符集，传输和存储过程中，这些字符必须由支持 US-ASCII（例如 UTF-8, ISO 8859-x, SHIFT JIS 等）字符编码方式编译 7 | 8 | ### 文档内嵌样式表编码 9 | 10 | > When a style sheet is embedded in another document, such as in the STYLE element or "style" attribute of HTML, the style sheet shares the character encoding of the whole document. 11 | 12 | 当样式出现在其它文档，如 HTML 的 STYLE 标签或标签属性 "style"，样式的编码由文档的决定。 13 | 14 | ### 文档外链样式表编码 15 | 16 | > When a style sheet resides in a separate file, user agents must observe the following priorities when determining a style sheet's character encoding (from highest priority to lowest): 17 | 18 | > 1. An HTTP "charset" parameter in a "Content-Type" field (or similar parameters in other protocols) 19 | > 2. BOM and/or @charset 20 | > 3. or other metadata from the linking mechanism (if any) 21 | > 4. charset of referring style sheet or document (if any) 22 | > 5. Assume UTF-8 23 | 24 | 文档外链样式表的编码可以由以下各项按照由高到低的优先级顺序决定： 25 | 26 | 1. HTTP “Content-Type” 字段参数 “charset”（或其它协议相似的参数） 27 | 2. BOM（byte-order mark）和（或）@charset 28 | 3. Link 中的元数据设置（如果有的话） 29 | 4. 引用样式表字符集或文档编码（如果有的话） 30 | 5. 假定为 UTF-8 编码 31 | 32 | ### 样式表编码 33 | 34 | > Authors using an @charset rule must place the rule at the very beginning of the style sheet, preceded by no characters. (If a byte order mark is appropriate for the encoding used, it may precede the @charset rule.) 35 | 36 | > @charset must be written literally, i.e., the 10 characters '@charset "' (lowercase, no backslash escapes), followed by the encoding name, followed by '";'. 37 | 38 | 39 | * @charset规则一定要在样式文件的第一行首个字符位置开始，否则的话就会有机会让 BOM 设置生效（如果有设置 BOM 的话）而优于 @charset 作为样式表的编码 40 | * `@charset "";` 一定要写上，并且用小写字母，不能出现转义符 41 | 42 | ### 团队约定 43 | 44 | * 样式文件必须写上 @charset 规则，并且一定要在样式文件的第一行首个字符位置开始写，编码名用 “UTF-8” 45 | * 字符 @charset ""; 都用小写字母，不能出现转义符，编码名允许大小混写 46 | * 考虑到在使用“UTF-8”编码情况下 BOM 对代码的污染和编码显示的问题，在可控范围下，坚决不使用 BOM。（更多关于 BOM 可参考 [BOM的介绍](https://zh.wikipedia.org/wiki/%E4%BD%8D%E5%85%83%E7%B5%84%E9%A0%86%E5%BA%8F%E8%A8%98%E8%99%9F) 和 [「带 BOM 的 UTF-8」和「无 BOM 的 UTF-8」有什么区别？](http://www.zhihu.com/question/20167122) ） 47 | 48 | *推荐：* 49 | 50 | ```css 51 | @charset "UTF-8"; 52 | 53 | .jdc{} 54 | ``` 55 | 56 | *不推荐：* 57 | 58 | ```css 59 | /** 60 | * @desc File Info 61 | * @author Author Name 62 | * @date 2015-10-10 63 | */ 64 | 65 | /* @charset规则不在文件首行首个字符开始 */ 66 | @charset "UTF-8"; 67 | 68 | .jdc{} 69 | ``` 70 | 71 | ```css 72 | @CHARSET "UTF-8"; 73 | /* @charset规则没有用小写 */ 74 | 75 | .jdc{} 76 | ``` 77 | 78 | ```css 79 | /* 无@charset规则 */ 80 | .jdc{} 81 | ``` 82 | 83 | 更多关于样式编码：[CSS style sheet representation](http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#charset) 84 | 85 | ## 代码风格 86 | 87 | ### 代码格式化 88 | 89 | 样式书写一般有两种：一种是紧凑格式 (Compact) 90 | 91 | ```css 92 | .jdc{ display: block;width: 50px;} 93 | ``` 94 | 95 | 一种是展开格式（Expanded） 96 | 97 | ```css 98 | .jdc{ 99 | display: block; 100 | width: 50px; 101 | } 102 | ``` 103 | 104 | **团队约定** 105 | 106 | 统一使用展开格式书写样式 107 | 108 | 109 | 110 | ### 代码大小写 111 | 112 | 样式选择器，属性名，属性值关键字全部使用小写字母书写，属性字符串允许使用大小写。 113 | 114 | ```css 115 | /* 推荐 */ 116 | .jdc{ 117 | display:block; 118 | } 119 | 120 | /* 不推荐 */ 121 | .JDC{ 122 | DISPLAY:BLOCK; 123 | } 124 | ``` 125 | 126 | ### 选择器 127 | 128 | * 尽量少用通用选择器 `*` 129 | * 不使用 ID 选择器 130 | * 不使用无具体语义定义的标签选择器 131 | 132 | ```css 133 | /* 推荐 */ 134 | .jdc {} 135 | .jdc li {} 136 | .jdc li p{} 137 | 138 | /* 不推荐 */ 139 | *{} 140 | #jdc {} 141 | .jdc div{} 142 | ``` 143 | 144 | ### 代码缩进 145 | 146 | 统一使用四个空格进行代码缩进，使得各编辑器表现一致（各编辑器有相关配置） 147 | 148 | ```css 149 | .jdc { 150 | width: 100%; 151 | height: 100%; 152 | } 153 | ``` 154 | 155 | ### 分号 156 | 157 | 每个属性声明末尾都要加分号； 158 | 159 | ```css 160 | .jdc { 161 | width: 100%; 162 | height: 100%; 163 | } 164 | ``` 165 | 166 | ### 代码易读性 167 | 168 | 左括号与类名之间一个空格，冒号与属性值之间一个空格 169 | 170 | *推荐：* 171 | 172 | ```css 173 | .jdc { 174 | width: 100%; 175 | } 176 | ``` 177 | 178 | *不推荐：* 179 | 180 | ```css 181 | .jdc{ 182 | width:100%; 183 | } 184 | ``` 185 | 186 | 187 | 逗号分隔的取值，逗号之后一个空格 188 | 189 | *推荐：* 190 | 191 | ```css 192 | .jdc { 193 | box-shadow: 1px 1px 1px #333, 2px 2px 2px #ccc; 194 | } 195 | ``` 196 | 197 | *不推荐：* 198 | 199 | ```css 200 | .jdc { 201 | box-shadow: 1px 1px 1px #333,2px 2px 2px #ccc; 202 | } 203 | ``` 204 | 205 | 为单个css选择器或新申明开启新行 206 | 207 | *推荐：* 208 | 209 | ```css 210 | .jdc, 211 | .jdc_logo, 212 | .jdc_hd { 213 | color: #ff0; 214 | } 215 | .nav{ 216 | color: #fff; 217 | } 218 | ``` 219 | 220 | *不推荐：* 221 | 222 | ``` css 223 | .jdc,jdc_logo,.jdc_hd { 224 | color: #ff0; 225 | }.nav{ 226 | color: #fff; 227 | } 228 | ``` 229 | 230 | 颜色值 `rgb()` `rgba()` `hsl()` `hsla()` `rect()` 中不需有空格，且取值不要带有不必要的 0 231 | 232 | *推荐：* 233 | 234 | ```css 235 | .jdc { 236 | color: rgba(255,255,255,.5); 237 | } 238 | ``` 239 | 240 | *不推荐：* 241 | 242 | ```css 243 | .jdc { 244 | color: rgba( 255, 255, 255, 0.5 ); 245 | } 246 | ``` 247 | 248 | 属性值十六进制数值能用简写的尽量用简写 249 | 250 | *推荐：* 251 | 252 | ```css 253 | .jdc { 254 | color: #fff; 255 | } 256 | ``` 257 | 258 | *不推荐：* 259 | 260 | ```css 261 | .jdc { 262 | color: #ffffff; 263 | } 264 | ``` 265 | 266 | 不要为 `0` 指明单位 267 | 268 | *推荐：* 269 | 270 | ```css 271 | .jdc { 272 | margin: 0 10px; 273 | } 274 | ``` 275 | 276 | *不推荐：* 277 | 278 | ```css 279 | .jdc { 280 | margin: 0px 10px; 281 | } 282 | ``` 283 | 284 | ### 属性值引号 285 | 286 | css属性值需要用到引号时，统一使用单引号 287 | 288 | ```css 289 | /* 推荐 */ 290 | .jdc { 291 | font-family: 'Hiragino Sans GB'; 292 | } 293 | 294 | /* 不推荐 */ 295 | .jdc { 296 | font-family: "Hiragino Sans GB"; 297 | } 298 | ``` 299 | 300 | ### 属性书写顺序 301 | 302 | 建议遵循以下顺序： 303 | 304 | 1. 布局定位属性：display / position / float / clear / visibility / overflow 305 | 2. 自身属性：width / height / margin / padding / border / background 306 | 3. 文本属性：color / font / text-decoration / text-align / vertical-align / white- space / break-word 307 | 4. 其他属性（CSS3）：content / cursor / border-radius / box-shadow / text-shadow / background:linear-gradient ... 308 | 309 | ```css 310 | .jdc { 311 | display: block; 312 | position: relative; 313 | float: left; 314 | width: 100px; 315 | height: 100px; 316 | margin: 0 10px; 317 | padding: 20px 0; 318 | font-family: Arial, 'Helvetica Neue', Helvetica, sans-serif; 319 | color: #333; 320 | background: rgba(0,0,0,.5); 321 | -webkit-border-radius: 10px; 322 | -moz-border-radius: 10px; 323 | -o-border-radius: 10px; 324 | -ms-border-radius: 10px; 325 | border-radius: 10px; 326 | } 327 | ``` 328 | 329 | 330 | [mozilla官方属性顺序推荐](https://www.mozilla.org/css/base/content.css) 331 | 332 | ### CSS3浏览器私有前缀写法 333 | 334 | CSS3 浏览器私有前缀在前，标准前缀在后 335 | 336 | ```css 337 | .jdc { 338 | -webkit-border-radius: 10px; 339 | -moz-border-radius: 10px; 340 | -o-border-radius: 10px; 341 | -ms-border-radius: 10px; 342 | border-radius: 10px; 343 | } 344 | ``` 345 | 更多关于浏览器私有前辍写法：[#Vendor-specific extensions](http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#vendor-keywords) 346 | -------------------------------------------------------------------------------- /source/docs/css/note.md: -------------------------------------------------------------------------------- 1 | title: 注释规范 2 | --- 3 | 4 | > Comments begin with the characters `/*` and end with the characters `*/`. They may occur anywhere outside other tokens, and their contents have no influence on the rendering. Comments may not be nested. 5 | 6 | * 注释以字符 `/*` 开始，以字符 `*/` 结束 7 | * 注释不能嵌套 8 | 9 | ```css 10 | /*Comment Text*/ 11 | ``` 12 | 13 | ### 团队约定 14 | 15 | #### 单行注释 16 | 17 | 注释内容第一个字符和最后一个字符都是一个空格字符，单独占一行，行与行之间相隔一行 18 | 19 | *推荐：* 20 | 21 | ``` css 22 | /* Comment Text */ 23 | .jdc{} 24 | 25 | /* Comment Text */ 26 | .jdc{} 27 | ``` 28 | 29 | *不推荐：* 30 | 31 | ```css 32 | /*Comment Text*/ 33 | .jdc{ 34 | display: block; 35 | } 36 | .jdc{ 37 | display: block;/*Comment Text*/ 38 | } 39 | ``` 40 | 41 | #### 模块注释 42 | 43 | 注释内容第一个字符和最后一个字符都是一个空格字符，`/*` 与 模块信息描述占一行，多个横线分隔符`-`与`*/`占一行，行与行之间相隔两行 44 | 45 | *推荐：* 46 | 47 | ```css 48 | /* Module A 49 | ---------------------------------------------------------------- */ 50 | .mod_a {} 51 | 52 | 53 | /* Module B 54 | ---------------------------------------------------------------- */ 55 | .mod_b {} 56 | ``` 57 | 58 | *不推荐：* 59 | 60 | ```css 61 | /* Module A ---------------------------------------------------- */ 62 | .mod_a {} 63 | /* Module B ---------------------------------------------------- */ 64 | .mod_b {} 65 | ``` 66 | 67 | #### 文件信息注释 68 | 69 | 在样式文件编码声明 `@charset` 语句下面注明页面名称、作者、创建日期等信息 70 | 71 | ```css 72 | @charset "UTF-8"; 73 | /** 74 | * @desc File Info 75 | * @author Author Name 76 | * @date 2015-10-10 77 | */ 78 | ``` 79 | 80 | 81 | 82 | 83 | 更多关于CSS注释：[#Comments](http://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#comments) 84 | 85 | 86 | 87 | -------------------------------------------------------------------------------- /source/docs/css/query.md: -------------------------------------------------------------------------------- 1 | title: 媒体查询 2 | --- 3 | 4 | 设备尺寸参考 ：[Mobile devices](http://mydevice.io/devices/) 5 | 6 | 媒体查询类型浏览器支持情况：[CSS3 Media Queries overview](http://cssmediaqueries.com/overview.html) 7 | 8 | ## 常用查询语句 9 | 10 | 判断设备横竖屏 11 | 12 | ```css 13 | /* 横屏 */ 14 | @media all and (orientation :landscape) { 15 | 16 | } 17 | 18 | /* 竖屏 */ 19 | @media all and (orientation :portrait) { 20 | 21 | } 22 | ``` 23 | 24 | 判断设备宽高 25 | 26 | ```css 27 | /* 设备宽度大于 320px 小于 640px */ 28 | @media all and (min-width:320px) and (max-width:640px) { 29 | 30 | } 31 | ``` 32 | 33 | 判断设备像素比 34 | 35 | ```css 36 | /* 设备像素比为 1 */ 37 | @media only screen and (-webkit-min-device-pixel-ratio: 1), only screen and (min-device-pixel-ratio: 1) { 38 | 39 | } 40 | 41 | /* 设备像素比为 1.5 */ 42 | @media only screen and (-webkit-min-device-pixel-ratio: 1.5), only screen and (min-device-pixel-ratio: 1.5) { 43 | 44 | } 45 | 46 | /* 设备像素比为 2 */ 47 | @media only screen and (-webkit-min-device-pixel-ratio: 2), only screen and (min-device-pixel-ratio: 2) { 48 | 49 | } 50 | ``` 51 | 52 | ## 常用设备设置 53 | 54 | ### iPhones 55 | 56 | ```css 57 | /* ----------- iPhone 4 and 4S ----------- */ 58 | 59 | /* Portrait and Landscape */ 60 | @media only screen 61 | and (min-device-width: 320px) 62 | and (max-device-width: 480px) 63 | and (-webkit-min-device-pixel-ratio: 2) { 64 | 65 | } 66 | 67 | /* Portrait */ 68 | @media only screen 69 | and (min-device-width: 320px) 70 | and (max-device-width: 480px) 71 | and (-webkit-min-device-pixel-ratio: 2) 72 | and (orientation: portrait) { 73 | } 74 | 75 | /* Landscape */ 76 | @media only screen 77 | and (min-device-width: 320px) 78 | and (max-device-width: 480px) 79 | and (-webkit-min-device-pixel-ratio: 2) 80 | and (orientation: landscape) { 81 | 82 | } 83 | 84 | /* ----------- iPhone 5 and 5S ----------- */ 85 | 86 | /* Portrait and Landscape */ 87 | @media only screen 88 | and (min-device-width: 320px) 89 | and (max-device-width: 568px) 90 | and (-webkit-min-device-pixel-ratio: 2) { 91 | 92 | } 93 | 94 | /* Portrait */ 95 | @media only screen 96 | and (min-device-width: 320px) 97 | and (max-device-width: 568px) 98 | and (-webkit-min-device-pixel-ratio: 2) 99 | and (orientation: portrait) { 100 | } 101 | 102 | /* Landscape */ 103 | @media only screen 104 | and (min-device-width: 320px) 105 | and (max-device-width: 568px) 106 | and (-webkit-min-device-pixel-ratio: 2) 107 | and (orientation: landscape) { 108 | 109 | } 110 | 111 | /* ----------- iPhone 6 ----------- */ 112 | 113 | /* Portrait and Landscape */ 114 | @media only screen 115 | and (min-device-width: 375px) 116 | and (max-device-width: 667px) 117 | and (-webkit-min-device-pixel-ratio: 2) { 118 | 119 | } 120 | 121 | /* Portrait */ 122 | @media only screen 123 | and (min-device-width: 375px) 124 | and (max-device-width: 667px) 125 | and (-webkit-min-device-pixel-ratio: 2) 126 | and (orientation: portrait) { 127 | 128 | } 129 | 130 | /* Landscape */ 131 | @media only screen 132 | and (min-device-width: 375px) 133 | and (max-device-width: 667px) 134 | and (-webkit-min-device-pixel-ratio: 2) 135 | and (orientation: landscape) { 136 | 137 | } 138 | 139 | /* ----------- iPhone 6+ ----------- */ 140 | 141 | /* Portrait and Landscape */ 142 | @media only screen 143 | and (min-device-width: 414px) 144 | and (max-device-width: 736px) 145 | and (-webkit-min-device-pixel-ratio: 3) { 146 | 147 | } 148 | 149 | /* Portrait */ 150 | @media only screen 151 | and (min-device-width: 414px) 152 | and (max-device-width: 736px) 153 | and (-webkit-min-device-pixel-ratio: 3) 154 | and (orientation: portrait) { 155 | 156 | } 157 | 158 | /* Landscape */ 159 | @media only screen 160 | and (min-device-width: 414px) 161 | and (max-device-width: 736px) 162 | and (-webkit-min-device-pixel-ratio: 3) 163 | and (orientation: landscape) { 164 | 165 | } 166 | ``` 167 | 168 | ### Galaxy Phones 169 | 170 | ```css 171 | /* ----------- Galaxy S3 ----------- */ 172 | 173 | /* Portrait and Landscape */ 174 | @media screen 175 | and (device-width: 320px) 176 | and (device-height: 640px) 177 | and (-webkit-device-pixel-ratio: 2) { 178 | 179 | } 180 | 181 | /* Portrait */ 182 | @media screen 183 | and (device-width: 320px) 184 | and (device-height: 640px) 185 | and (-webkit-device-pixel-ratio: 2) 186 | and (orientation: portrait) { 187 | 188 | } 189 | 190 | /* Landscape */ 191 | @media screen 192 | and (device-width: 320px) 193 | and (device-height: 640px) 194 | and (-webkit-device-pixel-ratio: 2) 195 | and (orientation: landscape) { 196 | 197 | } 198 | 199 | /* ----------- Galaxy S4 ----------- */ 200 | 201 | /* Portrait and Landscape */ 202 | @media screen 203 | and (device-width: 320px) 204 | and (device-height: 640px) 205 | and (-webkit-device-pixel-ratio: 3) { 206 | 207 | } 208 | 209 | /* Portrait */ 210 | @media screen 211 | and (device-width: 320px) 212 | and (device-height: 640px) 213 | and (-webkit-device-pixel-ratio: 3) 214 | and (orientation: portrait) { 215 | 216 | } 217 | 218 | /* Landscape */ 219 | @media screen 220 | and (device-width: 320px) 221 | and (device-height: 640px) 222 | and (-webkit-device-pixel-ratio: 3) 223 | and (orientation: landscape) { 224 | 225 | } 226 | 227 | /* ----------- Galaxy S5 ----------- */ 228 | 229 | /* Portrait and Landscape */ 230 | @media screen 231 | and (device-width: 360px) 232 | and (device-height: 640px) 233 | and (-webkit-device-pixel-ratio: 3) { 234 | 235 | } 236 | 237 | /* Portrait */ 238 | @media screen 239 | and (device-width: 360px) 240 | and (device-height: 640px) 241 | and (-webkit-device-pixel-ratio: 3) 242 | and (orientation: portrait) { 243 | 244 | } 245 | 246 | /* Landscape */ 247 | @media screen 248 | and (device-width: 360px) 249 | and (device-height: 640px) 250 | and (-webkit-device-pixel-ratio: 3) 251 | and (orientation: landscape) { 252 | 253 | } 254 | ``` 255 | 256 | ### HTC Phones 257 | 258 | ```css 259 | /* ----------- HTC One ----------- */ 260 | 261 | /* Portrait and Landscape */ 262 | @media screen 263 | and (device-width: 360px) 264 | and (device-height: 640px) 265 | and (-webkit-device-pixel-ratio: 3) { 266 | 267 | } 268 | 269 | /* Portrait */ 270 | @media screen 271 | and (device-width: 360px) 272 | and (device-height: 640px) 273 | and (-webkit-device-pixel-ratio: 3) 274 | and (orientation: portrait) { 275 | 276 | } 277 | 278 | /* Landscape */ 279 | @media screen 280 | and (device-width: 360px) 281 | and (device-height: 640px) 282 | and (-webkit-device-pixel-ratio: 3) 283 | and (orientation: landscape) { 284 | 285 | } 286 | ``` 287 | 288 | ### iPads 289 | 290 | ```css 291 | /* ----------- iPad mini ----------- */ 292 | 293 | /* Portrait and Landscape */ 294 | @media only screen 295 | and (min-device-width: 768px) 296 | and (max-device-width: 1024px) 297 | and (-webkit-min-device-pixel-ratio: 1) { 298 | 299 | } 300 | 301 | /* Portrait */ 302 | @media only screen 303 | and (min-device-width: 768px) 304 | and (max-device-width: 1024px) 305 | and (orientation: portrait) 306 | and (-webkit-min-device-pixel-ratio: 1) { 307 | 308 | } 309 | 310 | /* Landscape */ 311 | @media only screen 312 | and (min-device-width: 768px) 313 | and (max-device-width: 1024px) 314 | and (orientation: landscape) 315 | and (-webkit-min-device-pixel-ratio: 1) { 316 | 317 | } 318 | 319 | /* ----------- iPad 1 and 2 ----------- */ 320 | 321 | /* Portrait and Landscape */ 322 | @media only screen 323 | and (min-device-width: 768px) 324 | and (max-device-width: 1024px) 325 | and (-webkit-min-device-pixel-ratio: 1) { 326 | 327 | } 328 | 329 | /* Portrait */ 330 | @media only screen 331 | and (min-device-width: 768px) 332 | and (max-device-width: 1024px) 333 | and (orientation: portrait) 334 | and (-webkit-min-device-pixel-ratio: 1) { 335 | 336 | } 337 | 338 | /* Landscape */ 339 | @media only screen 340 | and (min-device-width: 768px) 341 | and (max-device-width: 1024px) 342 | and (orientation: landscape) 343 | and (-webkit-min-device-pixel-ratio: 1) { 344 | 345 | } 346 | 347 | /* ----------- iPad 3 and 4 ----------- */ 348 | 349 | /* Portrait and Landscape */ 350 | @media only screen 351 | and (min-device-width: 768px) 352 | and (max-device-width: 1024px) 353 | and (-webkit-min-device-pixel-ratio: 2) { 354 | 355 | } 356 | 357 | /* Portrait */ 358 | @media only screen 359 | and (min-device-width: 768px) 360 | and (max-device-width: 1024px) 361 | and (orientation: portrait) 362 | and (-webkit-min-device-pixel-ratio: 2) { 363 | 364 | } 365 | 366 | /* Landscape */ 367 | @media only screen 368 | and (min-device-width: 768px) 369 | and (max-device-width: 1024px) 370 | and (orientation: landscape) 371 | and (-webkit-min-device-pixel-ratio: 2) { 372 | 373 | } 374 | ``` 375 | 376 | 377 | -------------------------------------------------------------------------------- /source/docs/css/reset.md: -------------------------------------------------------------------------------- 1 | title: 重置样式 2 | --- 3 | 4 | ## 移动端 5 | 6 | ```css 7 | 8 | * { -webkit-tap-highlight-color: transparent; outline: 0; margin: 0; padding: 0; vertical-align: baseline; } 9 | body, h1, h2, h3, h4, h5, h6, hr, p, blockquote, dl, dt, dd, ul, ol, li, pre, form, fieldset, legend, button, input, textarea, th, td { margin: 0; padding: 0; vertical-align: baseline; } 10 | img { border: 0 none; vertical-align: top; } 11 | i, em { font-style: normal; } 12 | ol, ul { list-style: none; } 13 | input, select, button, h1, h2, h3, h4, h5, h6 { font-size: 100%; font-family: inherit; } 14 | table { border-collapse: collapse; border-spacing: 0; } 15 | a { text-decoration: none; color: #666; } 16 | body { margin: 0 auto; min-width: 320px; max-width: 640px; height: 100%; font-size: 14px; font-family: -apple-system,Helvetica,sans-serif; line-height: 1.5; color: #666; -webkit-text-size-adjust: 100% !important; text-size-adjust: 100% !important; } 17 | input[type="text"], textarea { -webkit-appearance: none; -moz-appearance: none; appearance: none; } 18 | 19 | ``` 20 | 21 | ## PC端 22 | 23 | ```css 24 | html, body, div, h1, h2, h3, h4, h5, h6, p, dl, dt, dd, ol, ul, li, fieldset, form, label, input, legend, table, caption, tbody, tfoot, thead, tr, th, td, textarea, article, aside, audio, canvas, figure, footer, header, mark, menu, nav, section, time, video { margin: 0; padding: 0; } 25 | h1, h2, h3, h4, h5, h6 { font-size: 100%; font-weight: normal } 26 | article, aside, dialog, figure, footer, header, hgroup, nav, section, blockquote { display: block; } 27 | ul, ol { list-style: none; } 28 | img { border: 0 none; vertical-align: top; } 29 | blockquote, q { quotes: none; } 30 | blockquote:before, blockquote:after, q:before, q:after { content: none; } 31 | table { border-collapse: collapse; border-spacing: 0; } 32 | strong, em, i { font-style: normal; font-weight: normal; } 33 | ins { text-decoration: underline; } 34 | del { text-decoration: line-through; } 35 | mark { background: none; } 36 | input::-ms-clear { display: none !important; } 37 | body { font: 12px/1.5 \5FAE\8F6F\96C5\9ED1, \5B8B\4F53, "Hiragino Sans GB", STHeiti, "WenQuanYi Micro Hei", "Droid Sans Fallback", SimSun, sans-serif; background: #fff; } 38 | a { text-decoration: none; color: #333; } 39 | a:hover { text-decoration: underline; } 40 | ``` 41 | -------------------------------------------------------------------------------- /source/docs/css/sass.md: -------------------------------------------------------------------------------- 1 | title: SASS规范 2 | --- 3 | 4 | ## 语法选用 5 | 6 | SASS有两种语法格式，一种是 SCSS (Sassy CSS)，另一种是缩进格式（Indented Syntax），有时称之为 Sass。 7 | 8 | ### SCSS 9 | 10 | SCSS语法基于 CSS 语法扩展，每一个有效的 CSS 文件都是一个有效的具有相同含义的 SCSS 文件，换种说法就是 SCSS 能识别大多数的 CSS hacks 写法和浏览器前缀写法以及早期的 IE 滤镜写法，这种格式以 .scss 作为扩展名。 11 | 12 | ### Sass 13 | 14 | Sass 使用 “缩进” 代替 “花括号” 表示属性属于某个选择器，用 “换行” 代替 “分号” 分隔属性，很多人认为这样做比 SCSS 更容易阅读，书写也更快速。缩进格式也可以使用 Sass 的全部功能，只是与 SCSS 相比个别地方采取了不同的表达方式，具体请查看 [the indented syntax reference](http://sass-lang.com/documentation/file.INDENTED_SYNTAX.html)。这种格式以 .sass 作为拓展名。 15 | 16 | 更详细的用法请阅读 SASS 官网文档：[DOCUMENTATION](http://sass-lang.com/documentation/file.SASS_REFERENCE.html) 17 | 18 | ### 团队约定 19 | 20 | 考虑到 SCSS 语法对 CSS 语法友好的兼容性和扩展性，我们在使用 SASS 编写样式的时候，统一使用 SCSS 语法 21 | 22 | ## 编码格式 23 | 24 | > When running on Ruby 1.9 and later, Sass is aware of the character encoding of documents. Sass follows the CSS spec to determine the encoding of a stylesheet, and falls back to the Ruby string encoding. This means that it first checks the Unicode byte order mark, then the @charset declaration, then the Ruby string encoding. If none of these are set, it will assume the document is in UTF-8. 25 | 26 | 当在 Ruby1.9或更新的版本运行的时候，SASS 能识辨文档的字符编码。SASS 遵循 CSS 规范去确定样式文件的编码，进而转回 Ruby 字符串编码。这意味着SASS编译的时候会首先检测 BOM，然后到 @charset 声明，再到 Ruby 字符串编码，如果以上都没有设置，SASS 会认为文档的编码为 UTF-8 27 | 28 | ### 团队约定 29 | 30 | 严格遵守上面 “CSS规范” 中的 [“编码规范”](code.html) 31 | 32 | 更多关于 SASS 编码：[SASS Encodings](http://sass-lang.com/documentation/file.SASS_REFERENCE.html) 33 | 34 | ## SASS注释规范 35 | 36 | SASS支持 CSS 标准的多行注释 `/* */`，同时也支持单行注释 `//`。 37 | 38 | * 多行注释在使用非 Compressed 模式进行编译后的输出文件中会保留下来，单行注释 `//` 侧会被移除 39 | * 多行注释和单行注释在 SASS 编译后输出的压缩 CSS 文件都会被移除 40 | * 当多行注释内容第一个字符是感叹号 “!” 的时候，即 `/*! */`，SASS 无论用哪一种编译方式编译注释都会保留 41 | * 注释内容可以加入 SASS 变量 42 | 43 | ### 团队约定 44 | 45 | SCSS 文件内 46 | 47 | * 全部遵循 CSS 注释规范 48 | * 不使用 `/*! */` 注释方式 49 | * 注释内不放 SASS 变量 50 | 51 | 标准的注释规范如下： 52 | 53 | ```css 54 | @charset "UTF-8"; 55 | 56 | /** 57 | * @desc File Info 58 | * @author liqinuo 59 | * @date 2015-10-10 60 | */ 61 | 62 | /* Module A 63 | ----------------------------------------------------------------*/ 64 | .mod_a {} 65 | 66 | /* module A logo */ 67 | .mod_a_logo {} 68 | 69 | /* module A nav */ 70 | .mod_a_nav {} 71 | 72 | 73 | /* Module B 74 | ----------------------------------------------------------------*/ 75 | .mod_b {} 76 | 77 | /* module B logo */ 78 | .mod_b_logo {} 79 | 80 | /* module B nav */ 81 | .mod_b_nav {} 82 | ``` 83 | 84 | ## 嵌套规范 85 | 86 | ### 选择器嵌套 87 | 88 | ```scss 89 | /* CSS */ 90 | .jdc {} 91 | body .jdc {} 92 | 93 | /* SCSS */ 94 | .jdc { 95 | body & {} 96 | } 97 | ``` 98 | 99 | ```scss 100 | /* CSS */ 101 | .jdc {} 102 | .jdc_cover {} 103 | .jdc_info {} 104 | .jdc_info_name {} 105 | 106 | /* SCSS */ 107 | .jdc { 108 | &_cover {} 109 | &_info { 110 | &_name {} 111 | } 112 | } 113 | ``` 114 | 115 | ### 属性嵌套 116 | 117 | ```scss 118 | /* CSS */ 119 | .jdc { 120 | background-color: red; 121 | background-repeat: no-repeat; 122 | background-image: url(/img/icon.png); 123 | background-position: 0 0; 124 | } 125 | 126 | /* SCSS */ 127 | .jdc { 128 | background: { 129 | color: red; 130 | repeat: no-repeat; 131 | image: url(/img/icon.png); 132 | position: 0 0; 133 | } 134 | } 135 | ``` 136 | 137 | ## 变量 138 | 139 | 可复用属性尽量抽离为页面变量，易于统一维护 140 | 141 | ```scss 142 | // CSS 143 | .jdc { 144 | color: red; 145 | border-color: red; 146 | } 147 | 148 | // SCSS 149 | $color: red; 150 | .jdc { 151 | color: $color; 152 | border-color: $color; 153 | } 154 | ``` 155 | 156 | ## 混合(mixin) 157 | 158 | 根据功能定义模块，然后在需要使用的地方通过 `@include` 调用，避免编码时重复输入代码段 159 | 160 | ```scss 161 | // CSS 162 | .jdc_1 { 163 | -webkit-border-radius: 5px; 164 | border-radius: 5px; 165 | } 166 | .jdc_2 { 167 | -webkit-border-radius: 10px; 168 | border-radius: 10px; 169 | } 170 | 171 | // SCSS 172 | @mixin radius($radius:5px) { 173 | -webkit-border-radius: $radius; 174 | border-radius: $radius; 175 | } 176 | .jdc_1 { 177 | @include radius; //参数使用默认值 178 | } 179 | .jdc_2 { 180 | @include radius(10px); 181 | } 182 | 183 | 184 | 185 | // CSS 186 | .jdc_1 { 187 | background: url(/img/icon.png) no-repeat -10px 0; 188 | } 189 | .jdc_2 { 190 | background: url(/img/icon.png) no-repeat -20px 0; 191 | } 192 | 193 | // SCSS 194 | @mixin icon($x:0, $y:0) { 195 | background: url(/img/icon.png) no-repeat $x, $y; 196 | } 197 | .jdc_1 { 198 | @include icon(-10px, 0); 199 | } 200 | .jdc_2 { 201 | @include icon(-20px, 0); 202 | } 203 | ``` 204 | 205 | 206 | ## 占位选择器 % 207 | 208 | 如果不调用则不会有任何多余的 css 文件，占位选择器以 `%` 标识定义，通过 `@extend` 调用 209 | 210 | ```scss 211 | //scss 212 | %borderbox { 213 | -webkit-box-sizing: border-box; 214 | box-sizing: border-box; 215 | } 216 | .jdc { 217 | @extend %borderbox; 218 | } 219 | ``` 220 | 221 | ## extend 继承 222 | 223 | ```scss 224 | // CSS 225 | .jdc_1 { 226 | font-size: 12px; 227 | color: red; 228 | } 229 | .jdc_2 { 230 | font-size: 12px; 231 | color: red; 232 | font-weight: bold; 233 | } 234 | 235 | // SCSS 236 | .jdc_1 { 237 | font-size: 12px; 238 | color: red; 239 | } 240 | .jdc_2 { 241 | @extend .jdc_1; 242 | font-weight: bold; 243 | } 244 | 245 | // 或者 246 | %font_red { 247 | font-size: 12px; 248 | color: red; 249 | } 250 | .jdc_1 { 251 | @extend %font_red; 252 | } 253 | .jdc_2 { 254 | @extend %font_red; 255 | font-weight: bold; 256 | } 257 | ``` 258 | 259 | 260 | ## for 循环 261 | 262 | ```scss 263 | // CSS 264 | .jdc_1 {background-position: 0 -20px;} 265 | .jdc_2 {background-position: 0 -40px;} 266 | .jdc_3 {background-position: 0 -60px;} 267 | 268 | // SCSS 269 | @for $i from 1 through 3 { 270 | .jdc_#{$i} { 271 | background-position: 0 (-20px) * $i; 272 | } 273 | } 274 | ``` 275 | 276 | 注意：`#{}` 是连接符，变量连接使用时需要依赖 277 | 278 | ## each 循环 279 | 280 | ```scss 281 | // CSS 282 | .jdc_list { 283 | background-image: url(/img/jdc_list.png); 284 | } 285 | .jdc_detail { 286 | background-image: url(/img/jdc_detail.png); 287 | } 288 | 289 | // SCSS 290 | @each $name in list, detail { 291 | .jdc_#{$name} { 292 | background-image: url(/img/jdc_#{$name}.png); 293 | } 294 | } 295 | 296 | 297 | // CSS 298 | .jdc_list { 299 | background-image: url(/img/jdc_list.png); 300 | background-color: red; 301 | } 302 | .jdc_detail { 303 | background-image: url(/img/jdc_detail.png); 304 | background-color: blue; 305 | } 306 | 307 | // SCSS 308 | @each $name, $color in (list, red), (detail, blue) { 309 | .jdc_#{$name} { 310 | background-image: url(/img/jdc_#{$name}.png); 311 | background-color: $color; 312 | } 313 | } 314 | ``` 315 | 316 | 317 | ## function 函数 318 | 319 | ```scss 320 | @function pxToRem($px) { 321 | @return $px / 10px * 1rem; 322 | } 323 | .jdc { 324 | font-size: pxToRem(12px); 325 | } 326 | ``` 327 | 328 | 329 | ## 运算规范 330 | 331 | 运算符之间空出一个空格 332 | 333 | ```scss 334 | .jdc { 335 | width: 100px - 50px; 336 | height: 30px / 5; 337 | } 338 | ``` 339 | 340 | 注意运算单位，单位同时参与运算，所以 10px 不等于 10，乘除运算时需要特别注意 341 | 342 | ```scss 343 | // 正确的运算格式 344 | .jdc { 345 | width: 100px - 50px; 346 | width: 100px + 50px; 347 | width: 100px * 2; 348 | width: 100px / 2; 349 | } 350 | ``` 351 | 352 | 353 | 354 | 355 | -------------------------------------------------------------------------------- /source/docs/css/webkit.md: -------------------------------------------------------------------------------- 1 | title: 移动端常用私有属性 2 | --- 3 | 4 | 目前两大主流移动平台为 `iOS` 和 `Android`，有不少带 `-webkit-` 前辍的 CSS 私有属性以及一些 iOS only 属性，当中好些属性在日常需求中经常应用到。 5 | 6 | `WebKit` CSS 属性中的一部分已经被包含在 CSS 规范草案中，并且可能成为最后的推荐标准，但目前仍然是试验性的属性，还有一些属性是不规范的属性，它们没有出现在跟踪规范中。 7 | ## -webkit-scrollbar 8 | 9 | `-webkit-scrollbar` 是-webkit-私有的伪元素，用于对拥有overflow属性的区域 **自定义滚动条的样式**。 10 | 11 | 譬如，为了隐藏滚动条，你可以这么做： 12 | ```css 13 | .scroll::-webkit-scrollbar { 14 | width: 0; 15 | height: 0; 16 | } 17 | ``` 18 | 除了对整个滚动条的控制外，Webkit还提供了控制对滚动条各组成部分的表现渲染的伪元素，甚至具体到滚动条的各种状态行为的伪类。 19 | 20 | ### 滚动条各块组成表现渲染的伪元素 21 | 一般而言，滚动条的主要组成部分包括： 22 | - 滚动按钮 — 滚动按钮的夹角则被称为滚动角(corner)。 23 | - 轨道 — 轨道(track)可以进一步分为轨枕(track pieces) 和滑块(thumb)。 24 | 25 | Webkit则根据滚动条各组成部分，提供了不同的伪元素来自定义样式。 26 | ``` 27 | ::-webkit-scrollbar { /* 1 */ } 28 | ::-webkit-scrollbar-button { /* 2 */ } 29 | ::-webkit-scrollbar-track { /* 3 */ } 30 | ::-webkit-scrollbar-track-piece { /* 4 */ } 31 | ::-webkit-scrollbar-thumb { /* 5 */ } 32 | ::-webkit-scrollbar-corner { /* 6 */ } 33 | ::-webkit-resizer { /* 7 */ } 34 | ``` 35 | 下图则是各伪元素对应的滚动条各部分： 36 | 37 | ![scrollbarparts.png](http://7xs2jo.com1.z0.glb.clouddn.com/215F9FF68F2CAE78957E1C112521A0A2.png) 38 | 39 | `::-webkit-scrollbar`：滚动条整体部分。可设置width、height、background、border等。 40 | 41 | `::-webkit-scrollbar-button`：滚动条两端的按钮。可以用display:none让其不显示，也可以添加背景图片，颜色改变显示效果。 42 | 43 | `::-webkit-scrollbar-track`：轨道。可以用display:none让其不显示，也可以添加背景图片，颜色改变显示效果。 44 | 45 | `::-webkit-scrollbar-track-piece`：轨枕，也就是除去滚动滑块的部分。 46 | 47 | `::-webkit-scrollbar-thumb`：滚动滑块，也就是滚动条里面可以拖动的那部分。 48 | 49 | `::-webkit-scrollbar-corner`：滚动按钮的夹角则被称为滚动角。 50 | 51 | `::-webkit-resizer`：用于定义右下角拖动块的样式。 52 | 53 | **需要注意的是**：若是水平滚动条，则width属性不起作用，height属性用来控制滚动条相应部分竖直方向高度；若是竖直滚动条，则height属性不起作用，width属性用来控制相应部分的宽度。 54 | 55 | ### 滚动条各块组成的伪元素 56 | 下面的伪类可以应用到上面的伪元素中。 57 | `:horizontal`：选择水平方向的滚动条。 58 | 59 | `:vertical`：选择垂直方向的滚动条。 60 | 61 | `:decrement`：适用于滚动按钮和轨枕。选择能够使得视窗位置递减状态(例如，垂直滚动条向上滚动，水平滚动条向左滚动。)的滚动按钮或轨枕。 62 | 63 | `:increment`：适用于滚动按钮和轨枕。选择能够使得视窗位置递增状态(例如，垂直滚动条向下滚动，水平滚动条向右滚动。)的滚动按钮或轨枕。 64 | 65 | `:start`：适用于滚动按钮和轨枕。选择位于滚动滑块前边的滚动按钮和轨枕。 66 | 67 | `:end`：适用于滚动按钮和轨枕。选择位于滚动滑块后边的滚动按钮和轨枕。 68 | 69 | `:double-button`：适用于滚动按钮和轨枕。选中紧挨着一对按钮的轨枕以及位于滚动条某一端的一对按钮中的其中一个滚动按钮。 70 | 71 | `:single-button`：适用于滚动按钮和轨枕。选中紧挨着仅一个按钮的轨枕以及位于滚动条某一端的仅它本身一个的滚动按钮。 72 | 73 | `:no-button`：适用于轨枕。选中轨道结束位置没有按钮的轨枕。 74 | 75 | `:corner-present`：适用于选中滚动角不存在的滚动条。 76 | 77 | `:window-inactive`：适用于所有滚动条，选中焦点不在该视窗的滚动区域。 78 | 79 | **另外，:enabled、:disabled、:hover、和:active等伪类同样在滚动条中适用。** 80 | 为了更好地理解，以下是几个伪元素组合伪类的应用例子： 81 | ```css 82 | ::-webkit-scrollbar-track-piece:start { 83 | /\*滚动条上半边或左半边\*/ 84 | } 85 | ::-webkit-scrollbar-thumb:window-inactive { 86 | /\*当焦点不在当前区域滑块的状态\*/ 87 | 88 | ::-webkit-scrollbar-button:horizontal:decrement:hover { 89 | /\*当鼠标在水平滚动条下面的按钮上的状态\*/ 90 | ``` 91 | 或者，读者可以去阅读[官方例子](http://trac.webkit.org/export/41842/trunk/LayoutTests/scrollbars/overflow-scrollbar-combinations.html) 92 | 93 | #### 参考资料： 94 | 95 | - [Webkit-Styling Scrollbars](https://webkit.org/blog/363/styling-scrollbars/) 96 | - [自定义浏览器滚动条的样式，打造属于你的滚动条风格](http://www.lyblog.net/detail/314.html) 97 | 98 | 99 | ## -webkit-touch-callout 100 | 101 | `-webkit-touch-callout` 是一个不规范的属性（[unsupported WebKit property](https://developer.apple.com/library/safari/documentation/AppleApplications/Reference/SafariCSSRef/Articles/StandardCSSProperties.html)），它没有出现在 CSS 规范草案中。 102 | 103 | 当你触摸并按住触摸目标时候，禁止或显示系统默认菜单。在iOS上，当你触摸并按住触摸的目标，比如一个链接，Safari浏览器将显示链接有关的系统默认菜单，这个属性可以让你禁用系统默认菜单。 104 | 105 | ### 属性值 106 | 107 | * `none`：系统默认菜单被禁用 108 | * `inherit`：系统默认菜单不被禁用 109 | 110 | ### 兼容性 111 | 112 | * iOS 2.0及更高版本的 Safari 浏览器可用 113 | * Android 尚不明确 114 | 115 | ## -webkit-tap-highlight-color 116 | 117 | `-webkit-tap-highlight-color` 是一个不规范的属性（[unsupported WebKit property](https://developer.apple.com/library/safari/documentation/AppleApplications/Reference/SafariCSSRef/Articles/StandardCSSProperties.html)），它没有出现在 CSS 规范草案中。 118 | 119 | 在 iOS Safari 上，当用户点击链接或具有 JavaScript 可点击脚本的元素，系统会为这些被点击元素加上一个默认的透明色值，该属性可以覆盖该透明值。 120 | 121 | ### 属性值 122 | 123 | <color>：颜色值 124 | 125 | ### 兼容性 126 | 127 | * iOS 1.1.1及更高版本的Safari浏览器可用 128 | * 大部分安卓手机 129 | 130 | ## -webkit-overflow-scrolling 131 | 132 | 定义在具 `overflow:scroll` 属性的元素内是否采用原生样式滚动行为 133 | 134 | ### 属性值 135 | 136 | * `auto`：默认值，单手滚动，滚动没有惯性效果 137 | * `touch`：原生样式滚动，应用此属性值会产生**层叠上下文**（会影响定位参照物的属性，类似 `opacity`、`masks`、`transforms`属性，影响到 `position` 的效果，甚至影响到 `position:fixed` 的定位参照物，） 138 | 139 | ### 兼容性 140 | 141 | * iOS 5.0 及更高版本 142 | * 大部分安卓机 143 | 144 | 145 | ## -webkit-line-clamp 146 | 147 | `-webkit-line-clamp` 是一个不规范的属性（[unsupported WebKit property](https://developer.apple.com/library/safari/documentation/AppleApplications/Reference/SafariCSSRef/Articles/StandardCSSProperties.html)），它没有出现在 CSS 规范草案中。 148 | 149 | 限制在一个块元素显示的文本的行数。 为了实现该效果，它需要组合其他外来的WebKit属性。 150 | 151 | 常见结合属性： 152 | 153 | * `display: -webkit-box`：**必须结合的属性**，将对象作为弹性伸缩盒子模型显示。 154 | * `-webkit-box-orient`：**必须结合的属性**，设置或检索伸缩盒对象的子元素的排列方式。 155 | * `text-overflow`：可以用来多行文本的情况下，用省略号“...”隐藏超出范围的文本。 156 | 157 | ### 属性值 158 | 159 | <number>：块元素显示的文本的行数 160 | 161 | ### 兼容性 162 | 163 | * iOS 164 | * Andriod 165 | 166 | ## -webkit-appearance 167 | 168 | `-webkit-appearance` 是一个不规范的属性（[unsupported WebKit property](https://developer.apple.com/library/safari/documentation/AppleApplications/Reference/SafariCSSRef/Articles/StandardCSSProperties.html)），它没有出现在 CSS 规范草案中。 169 | 170 | 改变按钮和其他控件的外观，使其类似于原生控件。 171 | 172 | ### 属性值 173 | 174 | * `none`：去除系统默认 appearance 的样式，常用于 iOS 下移除原生样式 175 | * `button`：渲染成 button 的风格 176 | * `checkbox`：渲染成 input checkbox 样式的复选框按钮 177 | * `radio `：渲染成 radio 的风格 178 | * ... 179 | 180 | 更多属性值参考 [mozilla：-webkit-appearance 属性](https://developer.mozilla.org/en-US/docs/Web/CSS/-moz-appearance) 181 | 182 | ### 兼容性 183 | 184 | * iOS 2.0及更高版本的Safari浏览器可用 185 | * Android 尚不明确 186 | 187 | ## -webkit-font-smoothing 188 | 189 | 字体平滑，该属性定义文本的平滑属性，但要**注意以下说明：** 190 | 191 | > 非标准属性，**不建议用于网页上**，这个属性不能保证所有用户都能看到相同效果，这会使网站的字体渲染造成不一致，而此属性的渲染行为日后也有可能会改变 192 | 193 | ### 属性值 194 | 195 | * `none`：去掉字体平滑效果，使字体带锯齿 196 | * `antialiased`：使字体在像素级别更平滑更轻细 197 | * `subpixel-antialiased`：在多数非 Retina 显示设备中字体将会更锐利。 198 | 199 | **注意：以上属性在 Retina 设备上会有明显的效果，在非 Retina 设备上看不出差异** 200 | 201 | ### 兼容性 202 | 203 | * 部分高清设备，如 Retina Mac 204 | 205 | 206 | ## -webkit-backface-visibility 207 | 208 | `backface-visibility` 在 [W3文档](http://www.w3.org/TR/css3-transforms/#backface-visibility-property) 有定义描述 209 | 210 | 定义转换元素的背面是否显示 211 | 212 | ### 属性值 213 | 214 | * `visible`：显示（默认值） 215 | * `hidden`：隐藏 216 | 217 | ### 兼容性 218 | 219 | * iOS 2.0 及更高版本的 Safari 浏览器可用 220 | * 大部分 Android 221 | 222 | ## -webkit-mask 223 | 224 | 定义多样的蒙板效果属性（缩写属性，类似 `margin`） 225 | 226 | ### 使用语法 227 | 228 | ``` 229 | [ || || || || || ]* 230 | where 231 | = [ | | left | center | right ] [ | | top | center | bottom ]? 232 | ``` 233 | 234 | 默认值： 235 | 236 | ```css 237 | -webkit-mask: none repeat scroll 0% 0% padding border add; 238 | ``` 239 | 240 | ### 属性值 241 | 242 | * <mask-image>：为元素设置蒙板图片，蒙板图片会根据图片的透明区域对元素可视部分进行裁剪 243 | * <uri>：图片链接作为蒙板图片 244 | * <gradient>：渐变函数 `-webkit-gradient` 作为蒙板图片 245 | * `none`：去掉蒙板图片 246 | 247 | * <mask-repeat>：定义蒙板图片是否平铺或平铺的方式 248 | * `repeat`：默认值，水平和垂直方向平铺 249 | * `repeat-x`：水平方向平铺 250 | * `repeat-y`：垂直方向平铺 251 | * `no-repeat`：不平铺 252 | 253 | * <mask-attachment>：如果 `-webkit-mask-image` 属性有设置，`attachment` 决定该图片是否相对视窗固定或随着其容器滚动 254 | * `scroll`：默认值，随容器滚动 255 | * `fixed`：相地视窗固定 256 | 257 | * <mask-position>：定义蒙板图片的初始位置，书写格式类似 `background-position`----`[， ]*` 258 | * <percentage> 259 | * <length> 260 | * `left` 261 | * `right` 262 | * `center` 263 | 264 | * <mask-origin>：定义蒙板图片定位相对起点，与 `webkit-mask-position` 属性相关。当 `-webkit-mask-attachment:fixed` 的时候，该属性不生效。 265 | * `padding`：默认值，蒙板定位相对边距 266 | * `border`：蒙板定位相对边框 267 | * `content`：蒙板定位相对元素盒子内容 268 | 269 | * <mask-clip>：如果 `-webkit-mask-image` 属性有设置，`-webkit-mask-clip` 将定义蒙板图片的裁剪区域 270 | * `border`：默认值，蒙板图片延伸到容器的边框 271 | * `padding`：蒙板图片延伸到容器的边距 272 | * `content`：蒙板图片裁剪到元素盒子内容范围 273 | * `text`：蒙板图片裁剪到元素文本范围 274 | 275 | * <mask-composite>：定义蒙板图片重合的裁剪显示方式 276 | * `add`：默认值，图片重合不裁剪 277 | * `subtract`：去掉层级低的图形以及图片重合部分图形，只留层级高非重合部分图形 278 | * `intersect`：只留重合部分图形 279 | * `exclude`：只去掉重合部分图形 280 | 281 | 有关属性更详细描述请参考： 282 | 283 | [w3 - css-masking](http://www.w3.org/TR/css-masking/) 284 | 285 | [MDN - -webkit-mask](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-mask) 286 | 287 | [携程 UED - -webkit-mask](http://ued.ctrip.com/webkitcss/) 288 | 289 | ### 兼容性 290 | 291 | * Safari 4.0 及更高版本 292 | * iOS 4.0 及更高版本 293 | * Android 2.1 及更高版本 294 | 295 | ## -webkit-user-select 296 | 297 | 定义用户是否能选中元素内容 298 | 299 | ### 属性值 300 | 301 | * `auto`：可选中元素内容 302 | * `none`：不能选中任何内容 303 | * `text`：可选中元素内的文本 304 | 305 | ### 兼容性 306 | 307 | * iOS 3.0 及更高版本的 Safari 308 | * 大部分安卓手机 309 | 310 | ## -webkit-user-modify 311 | 312 | 定义用户是否可编辑元素内容 313 | 314 | ### 属性值 315 | 316 | * `read-only`：只读 317 | * `read-write`：可读可写，粘贴内容会保留富文本格式（ Android 机不保留富文本格式 ） 318 | * `read-write-plaintext-only`：可读可写，粘贴内容所有富文本格式都会丢失 319 | 320 | **注意：使用这个属性的时候，请不要出现 `-webkit-user-select: none`，文本无法选中的情况下，在 Safari 该属性不生效，不过在 Chrome 依然生效** 321 | 322 | ### 兼容性 323 | 324 | * iOS 5.0 及更高版本 325 | * Safari 3.0 及更高版本 326 | * 大部分安卓手机 327 | 328 | ## -webkit-text-stroke 329 | 330 | 定义文本描边，可以设计描边的宽和颜色，一般与文本填充属性 `-webkit-text-fill-color` 共用。 331 | 332 | ### 属性值 333 | 334 | * <length>：长度单位 335 | * <color>：颜色值 336 | 337 | ### 兼容性 338 | 339 | * iOS 2.0 及更高版本 340 | * Safari 3.0 及更高版本 341 | * 安卓尚不明确 342 | 343 | ## -webkit-text-fill-color 344 | 345 | 定义文本填充，一般与文本描边属性 `-webkit-text-stroke` 共用。 346 | 347 | ### 属性值 348 | 349 | * <color>：颜色值 350 | * `currentcolor `：元素 `color` 属性值 351 | * `-webkit-activelink`：链接被点击时系统的默认颜色 352 | 353 | 更多属性值参考：[Safari CSS Reference -webkit-text-fill-color](https://developer.apple.com/library/safari/documentation/AppleApplications/Reference/SafariCSSRef/Articles/StandardCSSProperties.html) 354 | 355 | ### 兼容性 356 | 357 | * iOS 2.0 及更高版本 358 | * Safari 3.0 及更高版本 359 | * 安卓尚不明确 360 | 361 | ## -webkit-text-size-adjust 362 | 363 | 定义 iOS Safari 网页文本大小调整属性 364 | 365 | ### 属性值 366 | 367 | * <percentage>：百分比值，字体显示调整值 368 | * `auto`：字体自动调整 369 | * `none`：字体不能自动调整 370 | 371 | ### 兼容性 372 | 373 | * iOS 1.0 及更高版本 374 | * Safari on iOS only 375 | * 安卓尚不明确 376 | 377 | ## -webkit-marquee 378 | 379 | 定义滚动文本内容属性（缩写属性，类似`margin`）。 380 | 381 | ### 使用语法 382 | `-webkit-marquee: direction increment repetition style speed` 383 | 384 | ### 属性值 385 | 386 | * <direction>：滚动方向 387 | * `ahead`：从下到上滚动 388 | * `auto`：默认滚动方向 389 | * `backwards`：从右到左滚动 390 | * `down`：从上到下滚动 391 | * `forwards`：从左到右滚动 392 | * `left`：从右到左滚动 393 | * `reverse`：从上到下滚动 394 | * `right`：从左到右滚动 395 | * `up`：从下到上滚动 396 | * <increment>：每次移动的距离 397 | * [<percentage> | <length>] 398 | * `large`：距离常量 399 | * `medium`：距离常量 400 | * `small`：距离常量 401 | * <repetition>：文字滚动的重复次数 402 | * 非负整数 403 | * `infinite`：无限次 404 | * <style>：文字滚动的方式 405 | * `alternate`：重复滚动 406 | * `none`：停止滚动 407 | * `scroll`：在定义方向上滚动 408 | * `slide`：定义方向上滚动，内容显示完毕或者内容滚动到滚动区域另一端边框时候都会停止下来 409 | * <speed>：滚动或滑动的速度 410 | * 非负整数（毫秒单位）或带时间单位的非负整数 411 | * `fast` 412 | * `normal` 413 | * `slow` 414 | 415 | ### 兼容性 416 | 417 | * iOS 1.0 及更高版本 418 | * Safari 3.0 及更高版本 419 | * 大部分安卓手机 420 | 421 | ## -webkit-filter 422 | 423 | 滤镜属性可以让元素本身内容（文本、背景等）及其子元素加上滤镜效果 424 | 425 | ### 属性值 426 | 427 | * `blur()`：模糊，原始效果值为 `0px`，不接受负值 428 | 429 | * `brightness([ | ])`：亮度，原始效果值为 `1` 或 `100%`，不接受负值 430 | 431 | * `contrast([ | ])`：对比度，原始效果值为 `1` 或 `100%`，不接受负值 432 | 433 | * `drop-shadow( {2，4} ?)`：投影，原始效果值为所有长度值为 `0`，长度值至少2个，最多4个， 434 | 435 | * `grayscale([ | ] )`：灰度，原始效果值为 `0`，最大值为 `1` 或 `100%`，不接受负值 436 | 437 | * `hue-rotate( )`：相位，原始效果值为 `0deg` 438 | 439 | * `invert( [ | ])`：反相，原始效果值为 `0`，最大值为 `1` 或 `100%`，不接受负值 440 | 441 | * `opacity([ | ] )`：透明度，原始效果值为 `1`，最大值为 `1` 或 `100%`，不接受负值 442 | 443 | * `saturate([ | ])`：饱和度，原始效果值为 `1`，不接受负值 444 | 445 | * `sepia([ | ])`：乌贼墨，原始效果值为 `0`，最大值为 `1` 或 `100%`，不接受负值 446 | 447 | 关于 `-webkit-filter` 与 `-webkit-backdrop-filter` 的属性对比可以参考： 448 | 449 | [What's New in Safari 9.0 - backdrop-filter ](http://aotu.io/notes/2015/12/23/new-safari-9/) 450 | 451 | ### 兼容性 452 | 453 | * iOS 8.0 及更高版本 454 | * Safari 8.0 及更高版本 455 | * Android 4.4 及更高版本 456 | 457 | ## -webkit-backdrop-filter 458 | 459 | 背景滤镜属性可以让元素的背景或元素层级以下的元素加上滤镜效果 460 | 461 | ### 属性值 462 | 463 | * `blur()`：模糊，原始效果值为 `0px`，不接受负值 464 | 465 | * `brightness([ | ])`：亮度，原始效果值为 `1` 或 `100%`，不接受负值 466 | 467 | * `contrast([ | ])`：对比度，原始效果值为 `1` 或 `100%`，不接受负值 468 | 469 | * `drop-shadow( {2，3} ?)`：投影，原始效果值为所有长度值为 `0`，长度值至少2个，最多3个，**注意：不支持投影扩展值和混合投影** 470 | 471 | * `grayscale([ | ] )`：灰度，原始效果值为 `0`，最大值为 `1` 或 `100%`，不接受负值 472 | 473 | * `hue-rotate( )`：相位，原始效果值为 `0deg` 474 | 475 | * `invert( [ | ])`：反相，原始效果值为 `0`，最大值为 `1` 或 `100%`，不接受负值 476 | 477 | * `opacity([ | ] )`：透明度，原始效果值为 `1`，最大值为 `1` 或 `100%`，不接受负值 478 | 479 | * `saturate([ | ])`：饱和度，原始效果值为 `1`，不接受负值 480 | 481 | * `sepia([ | ])`：乌贼墨，原始效果值为 `0`，最大值为 `1` 或 `100%`，不接受负值 482 | 483 | 关于 `-webkit-filter` 与 `-webkit-backdrop-filter` 的属性对比可以参考： 484 | 485 | [What's New in Safari 9.0](http://aotu.io/notes/2015/12/23/new-safari-9/) 486 | 487 | ### 兼容性 488 | 489 | * iOS 9.0 及更高版本 490 | * Safari 9.0 及更高版本 491 | * 安卓尚未明确 492 | 493 | ## position:-webkit-sticky 494 | 495 | 可以使得元素在页面没有滚动的情况下表现得像relative，在滚动条滚到该元素区域的时候根据top值的设置使元素固定离顶部的距离，表现像 `position:fixed`，也就是常见的吸顶需求效果。 496 | 497 | ### 特性 498 | 499 | * 依赖父级元素滚动区域 500 | 501 | * 定位参考物始终是 viewport，`transform` 等可以改变 `position:fixed` 定位参考物的属性也没办法改变 `position:-webkit-sticky` 的定位参考物 502 | 503 | * `position:-webkit-sticky` 属性的元素固定区域只依赖其父元素的可滚动高度，如果其父元素高度小于元素本身的高度，fixed效果失效。 504 | 505 | ### 兼容性 506 | 507 | * iOS 6.1 及更高版本 508 | * iOS only 509 | 510 | 511 | ## -apple-system 512 | 513 | 苹果操作系统会从两种不同外观和大小的字体进行自动转换去调节系统新字体 “San Francisco”，可以通过 CSS 规则 514 | 515 | ```css 516 | font-family: -apple-system , sans-serif; 517 | ``` 518 | 519 | 让系统智能选择适配操作系统的字体，添加 `-apple-system` 可以使字体变得更圆润锐利。 520 | 521 | 关于 `-apple-system` 更详细的介绍可以参考： 522 | 523 | [What's New in Safari 9.0](http://aotu.io/notes/2015/12/23/new-safari-9/) 524 | 525 | ### 兼容性 526 | 527 | * iOS 9.0 及更高版本 528 | * Safari 9.0 及更高版本 529 | * iOS / OS X only 530 | 531 | ## 更多 WebKit CSS 属性 532 | 533 | 更多 `-webkit-` CSS 属性介绍请参考： 534 | 535 | * [MDN文档 - Webkit Extensions ](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Reference/Webkit_Extensions) 536 | * [携程 UED - webkitcss](http://ued.ctrip.com/webkitcss/) 537 | -------------------------------------------------------------------------------- /source/docs/html/code.md: -------------------------------------------------------------------------------- 1 | title: 代码规范 2 | --- 3 | 4 | ## DOCTYPE 声明 5 | 6 | 一个DOCTYPE必须包含以下部分，并严格按照顺序出现： 7 | 8 | > 1. A string that is an ASCII case-insensitive match for the string " 2. One or more space characters. 10 | > 3. A string that is an ASCII case-insensitive match for the string "html". 11 | > 4. Optionally, a DOCTYPE legacy string or an obsolete permitted DOCTYPE string (defined below). 12 | > 5. Zero or more space characters. 13 | > 6. A ">" (U+003E) character. 14 | 15 | 1. 一个ASCII字符串 " 28 | ``` 29 | 30 | ### 更多关于 DOCTYPE声明 31 | [#The DOCTYPE](http://www.w3.org/TR/2014/REC-html5-20141028/syntax.html#the-doctype) 32 | 33 | 34 | ## 页面语言LANG 35 | 36 | Lang属性的取值应该遵循互联网工程任务组--IETF（The Internet Engineering Task Force）制定的关于语言标签的文档 [BCP 47 - Tags for Identifying Languages](http://tools.ietf.org/html/bcp47) 37 | 38 | ### 团队约定 39 | 40 | 推荐使用属性值 `cmn-Hans-CN`（简体, 中国大陆），但是考虑浏览器和操作系统的兼容性，目前仍然使用 `zh-CN` 属性值 41 | ```html 42 | 43 | ``` 44 | 更多地区语言参考： 45 | 46 | zh-SG 中文 (简体, 新加坡) 对应 cmn-Hans-SG 普通话 (简体, 新加坡) 47 | zh-HK 中文 (繁体, 香港) 对应 cmn-Hant-HK 普通话 (繁体, 香港) 48 | zh-MO 中文 (繁体, 澳门) 对应 cmn-Hant-MO 普通话 (繁体, 澳门) 49 | zh-TW 中文 (繁体, 台湾) 对应 cmn-Hant-TW 普通话 (繁体, 台湾) 50 | 51 | 52 | #### 已废弃不推荐使用的 Languages Tags 53 | 54 | 以下写法已于 2009 年废弃，请勿使用（cmn、wuu、yue、gan 等已由 2005 年的 extlang 升级到 2009 年的 language）： 55 | 56 | zh-cmn, zh-cmn-Hans, zh-cmn-Hant, zh-wuu, zh-yue, zh-gan 57 | 58 | 以下写法已于 2009 年废弃，不推荐使用： 59 | 60 | zh-Hans, zh-Hans-CN, zh-Hans-SG, zh-Hans-HK, zh-Hans-MO, zh-Hans-TW, 61 | zh-Hant, zh-Hant-CN, zh-Hant-SG, zh-Hant-HK, zh-Hant-MO, zh-Hant-TW 62 | 63 | 更多已废弃 Languages Tags 参考 [IANA Language Subtag Registry](http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) 里面的 “Type: redundant“” 64 | 65 | #### 更多关于 Languages Tags ： 66 | 67 | [W3C Language tags in HTML and XML](http://www.w3.org/International/articles/language-tags/) 68 | 69 | 70 | [网页头部的声明应该是用 lang="zh" 还是 lang="zh-cn"？](http://www.zhihu.com/question/20797118?utm_source=weibo&utm_medium=weibo_share&utm_content=share_question&utm_campaign=share_sidebar) 71 | 72 | 73 | 74 | ## CHARSET 75 | 76 | > Because the character sets in ISO-8859 was limited in size, and not compatible in multilingual environments, the Unicode Consortium developed the Unicode Standard. 77 | > 78 | > The Unicode Standard covers (almost) all the characters, punctuations, and symbols in the world. 79 | > 80 | > Unicode enables processing, storage, and transport of text independent of platform and language. 81 | > 82 | > The default character encoding in HTML-5 is UTF-8. 83 | 84 | 因为 ISO-8859 中字符集大小是有限的，且在多语言环境中不兼容，所以 Unicode 联盟开发了 Unicode 标准。 85 | 86 | Unicode 标准覆盖了（几乎）所有的字符、标点符号和符号。 87 | 88 | Unicode 使文本的处理、存储和运输，独立于平台和语言。 89 | 90 | HTML-5 中默认的字符编码是 UTF-8 91 | 92 | 参阅 [HTML Unicode (UTF-8) Reference](http://www.w3schools.com/charsets/ref_html_utf8.asp) 93 | 94 | ### 团队约定 95 | 96 | 一般情况下统一使用 “UTF-8” 编码 97 | ```html 98 | 99 | ``` 100 | 101 | 由于历史原因，有些业务可能会使用 “GBK” 编码 102 | 103 | ```html 104 | 105 | ``` 106 | 107 | 请尽量统一写成标准的 “UTF-8”，不要写成 “utf-8” 或 “utf8” 或 “UTF8”。根据 [IETF对UTF-8的定义](http://www.ietf.org/rfc/rfc3629)，其编码标准的写法是 “UTF-8”；而 UTF8 或 utf8 的写法只是出现在某些编程系统中，如 .NET framework 的类 System.Text.Encoding 中的一个属性名就叫 UTF8。 108 | 109 | #### 更多关于 110 | 111 | UTF-8写法: [UTF8 or UTF-8?](http://stackoverflow.com/questions/809620/utf8-or-utf-8) 112 | 113 | GBK：[Application of IANA Charset Registration for GBK](http://www.ietf.org/assignments/charset-reg/GBK) 114 | 115 | Charset ：[character-encoding-declaration](http://www.w3.org/TR/html5/document-metadata.html#character-encoding-declaration) 116 | 117 | 118 | ## 元素及标签闭合 119 | 120 | HTML元素共有以下5种： 121 | 122 | * 空元素：area、base、br、col、command、embed、hr、img、input、keygen、link、meta、param、source、track、wbr 123 | * 原始文本元素：script、style 124 | * RCDATA元素：textarea、title 125 | * 外来元素：来自MathML命名空间和SVG命名空间的元素。 126 | * 常规元素：其他HTML允许的元素都称为常规元素。 127 | 128 | 元素标签的闭合应遵循以下原则： 129 | 130 | > Tags are used to delimit the start and end of elements in the markup. Raw text, escapable raw text, and normal elements have a start tag to indicate where they begin, and an end tag to indicate where they end. The start and end tags of certain normal elements can be omitted, as described below in the section on optional tags. Those that cannot be omitted must not be omitted. Void elements only have a start tag; end tags must not be specified for void elements. Foreign elements must either have a start tag and an end tag, or a start tag that is marked as self-closing, in which case they must not have an end tag. 131 | 132 | * 原始文本元素、RCDATA元素以及常规元素都有一个开始标签来表示开始，一个结束标签来表示结束。 133 | * [某些元素的开始和结束标签是可以省略的](http://www.w3.org/TR/html5/syntax.html#optional-tags)，如果规定标签不能被省略，那么就绝对不能省略它。 134 | * 空元素只有一个开始标签，且不能为空元素设置结束标签。 135 | * 外来元素可以有一个开始标签和配对的结束标签，或者只有一个自闭合的开始标签，且后者情况下该元素不能有结束标签。 136 | 137 | ### 团队约定 138 | 139 | 为了能让浏览器更好的解析代码以及能让代码具有更好的可读性，有如下约定： 140 | 141 | * 所有具有开始标签和结束标签的元素都要写上起止标签，某些允许省略开始标签或和束标签的元素亦都要写上。 142 | * 空元素标签都不加 “/” 字符 143 | 144 | 145 | *推荐：* 146 | 147 | ```html 148 |
    149 |

    我是h1标题

    150 |

    我是一段文字，我有始有终，浏览器能正确解析

    151 |
    152 | 153 |
    154 | ``` 155 | 156 | *不推荐：* 157 | 158 | ```html 159 |
    160 |

    我是h1标题

    161 |

    我是一段文字，我有始无终，浏览器亦能正确解析 162 |

    163 | 164 |
    165 | ``` 166 | 167 | 更多关于元素及标签关闭：[#Elements](http://www.w3.org/TR/html5/syntax.html#elements-0) 168 | 169 | ## 书写风格 170 | 171 | ### HTML代码大小写 172 | 173 | HTML标签名、类名、标签属性和大部分属性值统一用小写 174 | 175 | *推荐：* 176 | 177 | ```html 178 |
    179 | ``` 180 | 181 | *不推荐：* 182 | 183 | ```html 184 |
    185 | 186 |
    187 | ``` 188 | 189 | HTML文本、CDATA、JavaScript、meta标签某些属性等内容可大小写混合 190 | 191 | ```html 192 | 193 | 194 | 195 | 196 |

    I AM WHAT I AM

    197 | 198 | 199 | 203 | 204 | 205 | 208 | ``` 209 | 210 | ### 类型属性 211 | 212 | 不需要为 CSS、JS 指定类型属性，HTML5 中默认已包含 213 | 214 | *推荐：* 215 | 216 | ```html 217 | 218 | 219 | ``` 220 | 221 | *不推荐：* 222 | 223 | ```html 224 | 225 | 226 | ``` 227 | 228 | ### 元素属性 229 | 230 | * 元素属性值使用双引号语法 231 | * 元素属性值可以写上的都写上 232 | 233 | 234 | *推荐：* 235 | 236 | ```html 237 | 238 | 239 | 240 | ``` 241 | 242 | *不推荐：* 243 | 244 | ```html 245 | 246 | 247 | 248 | 249 | ``` 250 | 251 | 252 | 更多关于元素属性：[#Attributes](http://www.w3.org/TR/html5/syntax.html#attributes-0) 253 | 254 | ### 特殊字符引用 255 | 256 | > In certain cases described in other sections, text may be mixed with character references. These can be used to escape characters that couldn't otherwise legally be included in text. 257 | 258 | 文本可以和字符引用混合出现。这种方法可以用来转义在文本中不能合法出现的字符。 259 | 260 | 261 | 在 HTML 中不能使用小于号 “<” 和大于号 “>”特殊字符，浏览器会将它们作为标签解析，若要正确显示，在 HTML 源代码中使用字符实体 262 | 263 | *推荐：* 264 | 265 | ```html 266 | more>> 267 | ``` 268 | 269 | *不推荐：* 270 | 271 | ```html 272 | more>> 273 | ``` 274 | 更多关于符号引用：[#Character references](http://www.w3.org/TR/html5/syntax.html#character-references) 275 | 276 | ### 代码缩进 277 | 278 | 统一使用四个空格进行代码缩进，使得各编辑器表现一致（各编辑器有相关配置） 279 | 280 | ```html 281 |
    282 | 283 |
    284 | ``` 285 | 286 | ### 纯数字输入框 287 | 288 | 使用 `type="tel"` 而不是 `type="number"` 289 | 290 | ```html 291 | 292 | ``` 293 | ### 代码嵌套 294 | 295 | 元素嵌套规范，每个块状元素独立一行，内联元素可选 296 | 297 | *推荐：* 298 | 299 | ```html 300 |
    301 |

    302 |

    303 |
    304 |

    305 | ``` 306 | 307 | *不推荐：* 308 | 309 | ```html 310 |
    311 |

    312 |
    313 |

    314 | 315 | 316 |

    317 | ``` 318 | 段落元素与标题元素只能嵌套内联元素 319 | 320 | *推荐：* 321 | 322 | ```html 323 |

    324 |

    325 | ``` 326 | 327 | *不推荐：* 328 | 329 | ```html 330 |

    331 |

    332 | ``` -------------------------------------------------------------------------------- /source/docs/html/note.md: -------------------------------------------------------------------------------- 1 | title: 注释规范 2 | --- 3 | ## 遵循标准 4 | 5 | HTML注释规范写法应该遵循以下标准： 6 | 7 | > Comments must start with the four character sequence U+003C LESS-THAN SIGN, U+0021 EXCLAMATION MARK, U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS (<!--). Following this sequence, the comment may have text, with the additional restriction that the text must not start with a single ">" (U+003E) character, nor start with a U+002D HYPHEN-MINUS character (-) followed by a ">" (U+003E) character, nor contain two consecutive U+002D HYPHEN-MINUS characters (--), nor end with a U+002D HYPHEN-MINUS character (-). Finally, the comment must be ended by the three character sequence U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN (-->). 8 | 9 | * 必须以4个有序字符开始：编码为 U+003C LESS-THAN SIGN 的小于号, 编码为 U+0021 EXCLAMATION MARK 的感叹号, 编码为 U+002D HYPHEN-MINUS 横线, 编码为 U+002D HYPHEN-MINUS横线 ，即 “<!--” 10 | * 在此之后是注释内容，注释的内容有以下限制： 11 | * 不能以单个 ">" (U+003E) 字符开始 12 | * 不能以由 “-“（U+002D HYPHEN-MINUS）和 ”>” (U+003E) 组合的字符开始，即 “->” 13 | * 不能包含两个连续的 U+002D HYPHEN-MINUS 字符，即 “--” 14 | * 不能以一个 U+002D HYPHEN-MINUS 字符结束，即 “-” 15 | * 必须以3个有序字符结束：U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN，即 “-->” 16 | 17 | 标准写法： 18 | 19 | ```html 20 | 21 | ``` 22 | 23 | 错误的写法： 24 | 25 | ```html 26 | The Wrong Comment Text--> 27 | 28 | The Wrong Comment Text--> 29 | 30 | 31 | 32 | 33 | ``` 34 | 35 | 参考 www.w3.org [#Comments](http://www.w3.org/TR/2014/REC-html5-20141028/syntax.html#comments) 36 | 37 | 38 | ## 团队约定 39 | 40 | ### 单行注释 41 | 42 | 一般用于简单的描述，如某些状态描述、属性描述等 43 | 44 | 注释内容前后各一个空格字符，注释位于要注释代码的上面，单独占一行 45 | 46 | *推荐：* 47 | 48 | ```html 49 | 50 |
    ...
    51 | ``` 52 | 53 | *不推荐：* 54 | 55 | ```html 56 |
    ...
    57 | 58 |
    59 | ... 60 |
    61 | ``` 62 | 63 | ### 模块注释 64 | 65 | 一般用于描述模块的名称以及模块开始与结束的位置 66 | 67 | 注释内容前后各一个空格字符，`` 表示模块开始，`` 表示模块结束，模块与模块之间相隔一行 68 | 69 | *推荐写法：* 70 | 71 | ```html 72 | 73 |
    74 | ... 75 |
    76 | 77 | 78 | 79 |
    80 | ... 81 |
    82 | 83 | ``` 84 | 85 | *不推荐写法：* 86 | 87 | ```html 88 | 89 |
    90 | ... 91 |
    92 | 93 | 94 |
    95 | ... 96 |
    97 | 98 | ``` 99 | 100 | ### 嵌套模块注释 101 | 102 | 当模块注释内再出现模块注释的时候，为了突出主要模块，嵌套模块不再使用 103 | 104 | ```html 105 | 106 | 107 | ``` 108 | 109 | 而改用 110 | 111 | ```html 112 | 113 | ``` 114 | 115 | 注释写在模块结尾标签底部，单独一行。 116 | 117 | ```html 118 | 119 |
    120 | 121 |
    122 | ... 123 |
    124 | 125 | 126 |
    127 | ... 128 |
    129 | 130 | 131 |
    132 | 133 | ``` -------------------------------------------------------------------------------- /source/docs/html/template.md: -------------------------------------------------------------------------------- 1 | title: 文件模版 2 | --- 3 | 4 | HTML模版指的是团队使用的初始化HTML文件，里面会根据不同平台而采用不一样的设置，一般主要不同的设置就是 mata 标签的设置，以下是 PC 和移动端的 HTML 模版。 5 | 6 | ## HTML5标准模版 7 | 8 | ```html 9 | 10 | 11 | 12 | 13 | HTML5标准模版 14 | 15 | 16 | 17 | 18 | 19 | ``` 20 | 21 | ## 团队约定 22 | 23 | ### 移动端 24 | 25 | ```html 26 | 27 | 28 | 29 | 30 | 31 | 32 | 移动端HTML模版 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 | ### PC端 58 | 59 | ```html 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | PC端HTML模版 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | ``` -------------------------------------------------------------------------------- /source/docs/html/webapp.md: -------------------------------------------------------------------------------- 1 | title: WebApp Meta 2 | --- 3 | 4 | ## WebApp Meta 标签设置(iOS) 5 | 6 | > A web application is designed to look and behave in a way similar to a native application—for example, it is scaled to fit the entire screen on iOS. You can tailor your web application for Safari on iOS even further, by making it appear like a native application when the user adds it to the Home screen. You do this by using settings for iOS that are ignored by other platforms. 7 | 8 | WebApp目的在于使其界面和行为在某种程度上类似于原生APP应用。例如，WebApp 可以在 iOS 设备上通过缩放去适配设备屏幕。当用户将WebApp程序添加到主屏幕后，会使得它看上去像原生APP一样，以此，你可以进一步为 Safari 定制自己的 WebApp，而使用某些专为 iOS 平台设定的设置就可以做到。 9 | 10 | WebApp可以通过设置 meta 标签来改变页面的一些表现，有些 meta 设置在 Safari 应用或原生 App 的内嵌网页中都可以生效，而有些设置侧需要将应用添加到主屏幕的时候才会生效。 11 | 12 | 13 | ### Viewport Meta Tag 14 | 15 | #### 通用类设置 16 | ```html 17 | 19 | ``` 20 | * width -- viewport的宽度 21 | * height -- viewport的高度 22 | * initial-scale -- 初始的缩放比例 23 | * minimum-scale -- 允许用户缩放到的最小比例 24 | * maximum-scale -- 允许用户缩放到的最大比例 25 | * user-scalable -- 是否允许用户缩放 26 | 27 | #### Safari on iOS viewport 28 | 29 | > The width of the viewport in pixels. The default is 980. The range is from 200 to 10,000. 30 | > 31 | > The minimum-scale and maximum-scale properties also affect the behavior when changing orientations. The range of these property values is from >0 to 10.0. The default value for minimum-scale is 0.25 and maximum-scale is 5.0 32 | 33 | > user-scalable -- The default is yes. 34 | Setting user-scalable to no also prevents a webpage from scrolling when entering text in an input field. 35 | 36 | 37 | * 默认宽度是 980px，范围从 200px 到 10000px 38 | * initial-scale 缩放比例范围值是 从 >0 到 10 之间 39 | * minimum-scale 默认值是 0.25 40 | * maximum-scale 默认值是 5 41 | * user-scalable -- 默认值是 yes，设置 no 还可以在文本框输入文本的时候阻止页面滚动 42 | 43 | 44 | 更多关于 Safari on iOS viewport 的设置: 45 | 46 | [Configuring the Viewport](https://developer.apple.com/library/ios/documentation/AppleApplications/Reference/SafariWebContent/UsingtheViewport/UsingtheViewport.html#//apple_ref/doc/uid/TP40006509-SW19) 47 | [Safari HTML Reference](https://developer.apple.com/library/safari/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html) 48 | 49 | ### Apple-Specific Meta Tag Keys 50 | 51 | #### apple-mobile-web-app-capable 52 | 53 | 设置 WebApp 是否进入全屏模式，该设置需要添加到主屏幕才生效 54 | 55 | 56 | 57 | > If content is set to yes, the web application runs in full-screen mode;otherwise, it does not. The default behavior is to use Safari to display web content.You can determine whether a webpage is displayed in full-screen mode using the window.navigator.standalone read-only Boolean JavaScript property. 58 | 59 | * content设置 yes 进入全屏模式 60 | * 默认会启动 Safari 应用，使用 Safari 应用浏览 61 | * 通过检测 window.navigator.standalone 的 Boolean 值可以判断 web 应用是否处于全屏模式 62 | 63 | #### apple-mobile-web-app-status-bar-style 64 | 65 | 为 webapp 设置状态栏样式 66 | 67 | 68 | 69 | > This meta tag has no effect unless you first specify full-screen mode as described in apple-apple-mobile-web-app-capable. 70 | > 71 | If content is set to default, the status bar appears normal. If set to black, the status bar has a black background. If set to black-translucent, the status bar is black and translucent. If set to default or black, the web content is displayed below the status bar. If set to black-translucent, the web content is displayed on the entire screen, partially obscured by the status bar. The default value is default. 72 | 73 | * 此 meta 设置只在全屏模式生效 74 | * 默认值是 default 75 | * content="black"，状态栏背景黑色，网页内容在状态栏下面 76 | * content="black-translucent"，状态栏半透明，背景黑色，网页内容占满全屏 77 | 78 | *该设置在 iOS6 和 iOS7 表现还可以，但到了 iOS8 后会出现各种问题，而且在 iOS9 中并没有生效。参阅：[iOS 8: web app status bar position and resizing problems](http://stackoverflow.com/questions/25884806/ios-8-web-app-status-bar-position-and-resizing-problems)* 79 | 80 | #### format-detection 81 | 82 | 自动识别页面中有可能是电话格式的数字 83 | 84 | 85 | 86 | > By default, Safari on iOS detects any string formatted like a phone number and makes it a link that calls the number. Specifying telephone=no disables this feature. 87 | 88 | iOS中的 Safari 会默认识别与电话格式相似的数字并生成一个可以拉起电话应用并将该数字作为电话号码拨打的链接。定义 telephone=no 可以屏蔽该功能 89 | 90 | 更多 WebApp 设置参考 [Configuring Web Applications](https://developer.apple.com/library/ios/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html#//apple_ref/doc/uid/TP40002051-CH3-SW4) -------------------------------------------------------------------------------- /source/docs/image/format.md: -------------------------------------------------------------------------------- 1 | title: 图片格式 2 | --- 3 | 4 | ## 图片格式 5 | 6 | 常见的图片格式有 GIF、PNG8、PNG24、JPEG、WEBP，根据图片格式的特性和场景需要选取适合的图片格式。 7 | 8 | ### GIF 9 | 10 | > GIF图象是基于颜色列表的（存储的数据是该点的颜色对应于颜色列表的索引值），最多只支持8位（256色）。GIF文件内部分成许多存储块，用来存储多幅图象或者是决定图象表现行为的控制块，用以实现动画和交互式应用。GIF文件还通过LZW压缩算法压缩图象数据来减少图象尺寸 11 | 12 | #### 特性 13 | 14 | * 优秀的压缩算法使其在一定程度上保证图像质量的同时将体积变得很小。 15 | * 可插入多帧，从而实现动画效果。 16 | * 可设置透明色以产生对象浮现于背景之上的效果。 17 | * 由于采用了8位压缩，最多只能处理256种颜色，故不宜应用于真彩色图片。 18 | 19 | 更多关于GIF： 20 | 21 | [维基百科 - GIF](https://zh.wikipedia.org/wiki/GIF) 22 | 23 | [GIF文档](http://dev.gameres.com/Program/Visual/Other/GIFDoc.htm) 24 | 25 | ### PNG 26 | 27 | > PNG是20世纪90年代中期开始开发的图像文件存储格式，其目的是企图替代GIF和TIFF文件格式，同时增加一些GIF文件格式所不具备的特性。流式网络图形格式(Portable Network Graphic Format，PNG)名称来源于非官方的“PNG's Not GIF”，是一种位图文件(bitmap file)存储格式，读成“ping”。PNG用来存储灰度图像时，灰度图像的深度可多到16位，存储彩色图像时，彩色图像的深度可多到48位，并且还可存储多到16位的α通道数据。PNG使用从LZ77派生的无损数据压缩算法。 28 | 29 | #### 特性 30 | 31 | * 支持256色调色板技术，文件体积小。 32 | * 无损压缩 33 | * 最高支持48位真彩色图像以及16位灰度图像。 34 | * 支持Alpha通道的透明/半透明特性。 35 | * 支持图像亮度的Gamma校准信息。 36 | * 支持存储附加文本信息，以保留图像名称、作者、版权、创作时间、注释等信息。 37 | * 渐近显示和流式读写，适合在网络传输中快速显示预览效果后再展示全貌。 38 | * 使用CRC防止文件出错。 39 | * 最新的PNG标准允许在一个文件内存储多幅图像。 40 | 41 | 更多关于PNG： 42 | 43 | [PNG官方站 - PNG General Information](http://www.libpng.org/pub/png/) 44 | 45 | [PNG格式](http://dev.gameres.com/Program/Visual/Other/PNGFormat.htm) 46 | 47 | [维基百科 - PNG](https://zh.wikipedia.org/wiki/PNG) 48 | 49 | ### JPEG 50 | 51 | > JPEG是一种针对照片视频而广泛使用的一种有损压缩标准方法。这个名称代表Joint Photographic Experts Group（联合图像专家小组）。此团队创立于公元1986年，1992年发布了JPEG的标准而在1994年获得了ISO 10918-1的认定 52 | 53 | #### 特性 54 | 55 | * 适用于储存24位元全采影像 56 | * 采取的压缩方式通常为有损压缩 57 | * 不支持透明或动画 58 | * 压缩比越高影像耗损越大，失真越严重 59 | * 压缩比在10左右肉眼无法辨出压缩图与原图的差别 60 | 61 | 更多关于JPEG： 62 | 63 | [维基百科 - JPEG](https://zh.wikipedia.org/wiki/JPEG) 64 | 65 | ### WEBP 66 | 67 | > WebP，是一种同时提供了有损压缩与无损压缩的图片文件格式，派生自视频编码格式 VP8，是由Google在购买On2 Technologies后发展出来。WebP最初在2010年发布，2011年11月8日，Google开始让WebP支持无损压缩和透明色的功能，而在2012年8月16日的参考实做libwebp 0.2.0中正式支持 68 | 69 | #### 特性 70 | 71 | * 同时提供有损压缩和无损压缩两种图片文件格式 72 | * 文件体积小，无损压缩后，比 PNG 文件少了 45％ 的文件大小；有损压缩后，比 JPEG 文件少了 25% - 34% 文件大小 73 | * 浏览器兼容差，目前只支持客户端 Chrome 和 Opera 浏览器以及安卓原生浏览器(Andriod 4.0+)，[WebP兼容性](https://developers.google.com/speed/webp/faq#which_web_browsers_natively_support_webp) 74 | 75 | 更多关于WebP： 76 | 77 | [维基百科 - WEBP](https://zh.wikipedia.org/wiki/WebP) 78 | 79 | [WEBP探寻之路](http://isux.tencent.com/introduction-of-webp.html) 80 | 81 | 82 | 83 | ## 团队约定 84 | 85 | ### 内容图 86 | 87 | 内容图多以商品图等照片类图片形式存在，颜色较为丰富，文件体积较大 88 | 89 | * 优先考虑 JPEG 格式，条件允许的话优先考虑 WebP 格式 90 | * 尽量不使用PNG格式，PNG8 色位太低，PNG24 压缩率低，文件体积大 91 | 92 | ### 背景图 93 | 94 | 背景图多为图标等颜色比较简单、文件体积不大、起修饰作用的图片 95 | 96 | * PNG 与 GIF 格式，优先考虑使用 PNG 格式,PNG格式允许更多的颜色并提供更好的压缩率 97 | * 图像颜色比较简单的，如纯色块线条图标，优先考虑使用 PNG8 格式，避免不使用 JPEG 格式 98 | * 图像颜色丰富而且图片文件不太大的（40KB 以下）或有半透明效果的优先考虑 PNG24 格式 99 | * 图像颜色丰富而且文件比较大的（40KB - 200KB）优先考虑 JPEG 格式 100 | * 条件允许的，优先考虑 WebP 代替 PNG 和 JPEG 格式 -------------------------------------------------------------------------------- /source/docs/image/import.md: -------------------------------------------------------------------------------- 1 | title: 图片引入 2 | --- 3 | 4 | ## 图片引入 5 | 6 | 测试内容图应该写上表明图片尺寸的占位图，可以用线上占位图生成服务，如： 7 | 8 | ```html 9 | http://placeholder.qiniudn.com/300x200 10 | ``` 11 | 12 | ![image](http://placeholder.qiniudn.com/300x200) 13 | 14 | 15 | 16 | HTML 中图片引入不需添加 width、height 属性，alt 属性应该写上 17 | 18 | *推荐：* 19 | 20 | ```html 21 | 22 | ``` 23 | 24 | *不推荐：* 25 | 26 | ```html 27 | 28 | ``` 29 | 30 | CSS 中图片引入不需要引号 31 | 32 | ```css 33 | .jdc { 34 | background-image: url(icon.png); 35 | } 36 | ``` 37 | 38 | ### CSS Sprites VS Data URIs 39 | 40 | #### CSS Sprites特点 41 | 42 | * 减少请求数 43 | * 加速图片的显示 44 | * 维护更新成本大 45 | * 更多的内存消耗，特别是大体积或有过多空白的 Sprites 图 46 | * 图片渗漏，相邻的不需展示的图片有可能出现在展示元素中，特别是在高清设备移动设备上 47 | 48 | #### Data URIs（base64编码） 49 | 50 | * 减少请求数 51 | * 转换文件体积大，大约比原始的二进制大33% 52 | * IE6 / IE7 不支持 53 | * 图片显示相对较慢，需要更多的CPU消耗 54 | 55 | 56 | 57 | 更多关于 CSS Sprites 和 Data URIs 可以阅读： 58 | 59 | [《When to Base64 Encode Images (and When Not To)》](http://davidbcalhoun.com/2011/when-to-base64-encode-images-and-when-not-to/) 60 | 61 | [《Data URI 最佳实践》](http://madscript.com/html5/datauri-best-practice/) 62 | 63 | [《Data URI&MHTML: 用还是不用？》](http://www.99css.com/492/) 64 | 65 | [CSS Sprites vs. Data URIs: Which is Faster on Mobile?](http://www.mobify.com/blog/css-sprites-vs-data-uris-which-is-faster-on-mobile/) 66 | 67 | ## 团队约定 68 | 69 | ### CSS Sprites 使用建议 70 | 71 | * 适合使用频率高更新频率低的小图标 72 | * 尽量不留太多的空白 73 | * 体积较大的图片不合并 74 | * 确保要合并的小图坐标数值和合并后的 Sprites 图尺寸均为偶数 75 | 76 | 77 | ### Data URIs（base64编码）使用建议 78 | 79 | * 适合更新频率高的小图片，如某些具备自定义功能的标题icon等 80 | * 转换成 Base64 编码的图片应小于 2KB 81 | * 移动端不使用 Base64 编码 82 | * 要兼容 IE6/IE7 的不使用 83 | -------------------------------------------------------------------------------- /source/docs/image/jdc_fd_guide_image.md: -------------------------------------------------------------------------------- 1 | ## 图片规范 2 | 3 | ### 图片格式 4 | 5 | 常见的图片格式有 GIF、PNG8、PNG24、JPEG、WEBP，根据图片格式的特性和场景需要选取适合的图片格式 6 | 7 | 8 | #### GIF 9 | 10 | > GIF图象是基于颜色列表的（存储的数据是该点的颜色对应于颜色列表的索引值），最多只支持8位（256色）。GIF文件内部分成许多存储块，用来存储多幅图象或者是决定图象表现行为的控制块，用以实现动画和交互式应用。GIF文件还通过LZW压缩算法压缩图象数据来减少图象尺寸 11 | 12 | ##### 特性 13 | 14 | * 优秀的压缩算法使其在一定程度上保证图像质量的同时将体积变得很小。 15 | * 可插入多帧，从而实现动画效果。 16 | * 可设置透明色以产生对象浮现于背景之上的效果。 17 | * 由于采用了8位压缩，最多只能处理256种颜色，故不宜应用于真彩色图片。 18 | 19 | 更多关于GIF： 20 | 21 | [维基百科 - PNG](https://zh.wikipedia.org/wiki/GIF) 22 | 23 | [GIF文档](http://dev.gameres.com/Program/Visual/Other/GIFDoc.htm) 24 | 25 | #### PNG 26 | 27 | > PNG是20世纪90年代中期开始开发的图像文件存储格式，其目的是企图替代GIF和TIFF文件格式，同时增加一些GIF文件格式所不具备的特性。流式网络图形格式(Portable Network Graphic Format，PNG)名称来源于非官方的“PNG's Not GIF”，是一种位图文件(bitmap file)存储格式，读成“ping”。PNG用来存储灰度图像时，灰度图像的深度可多到16位，存储彩色图像时，彩色图像的深度可多到48位，并且还可存储多到16位的α通道数据。PNG使用从LZ77派生的无损数据压缩算法。 28 | 29 | ##### 特性 30 | 31 | * 支持256色调色板技术，文件体积小。 32 | * 无损压缩 33 | * 最高支持48位真彩色图像以及16位灰度图像。 34 | * 支持Alpha通道的透明/半透明特性。 35 | * 支持图像亮度的Gamma校准信息。 36 | * 支持存储附加文本信息，以保留图像名称、作者、版权、创作时间、注释等信息。 37 | * 渐近显示和流式读写，适合在网络传输中快速显示预览效果后再展示全貌。 38 | * 使用CRC防止文件出错。 39 | * 最新的PNG标准允许在一个文件内存储多幅图像。 40 | 41 | 更多关于PNG： 42 | 43 | [PNG官方站 - PNG General Information 44 | ](http://www.libpng.org/pub/png/) 45 | 46 | [PNG格式](http://dev.gameres.com/Program/Visual/Other/PNGFormat.htm) 47 | 48 | [维基百科 - PNG](https://zh.wikipedia.org/wiki/PNG) 49 | 50 | #### JPEG 51 | 52 | > JPEG是一种针对照片视频而广泛使用的一种有损压缩标准方法。这个名称代表Joint Photographic Experts Group（联合图像专家小组）。此团队创立于公元1986年，1992年发布了JPEG的标准而在1994年获得了ISO 10918-1的认定 53 | 54 | ##### 特性 55 | 56 | * 适用于储存24位元全采影像 57 | * 采取的压缩方式通常为有损压缩 58 | * 不支持透明或动画 59 | * 压缩比越高影像耗损越大，失真越严重 60 | * 压缩比在10左右肉眼无法辨出压缩图与原图的差别 61 | 62 | 更多关于JPEG： 63 | 64 | [维基百科 - JPEG](https://zh.wikipedia.org/wiki/JPEG) 65 | 66 | #### WEBP 67 | 68 | > WebP，是一种同时提供了有损压缩与无损压缩的图片文件格式，派生自视频编码格式 VP8，是由Google在购买On2 Technologies后发展出来。WebP最初在2010年发布，2011年11月8日，Google开始让WebP支持无损压缩和透明色的功能，而在2012年8月16日的参考实做libwebp 0.2.0中正式支持 69 | 70 | ##### 特性 71 | 72 | * 同时提供有损压缩和无损压缩两种图片文件格式 73 | * 文件体积小，无损压缩后，比 PNG 文件少了 45％ 的文件大小；有损压缩后，比 JPEG 文件少了 25% - 34% 文件大小 74 | * 浏览器兼容差，目前只支持客户端 Chrome 和 Opera 浏览器以及安卓原生浏览器(Andriod 4.0+)，[WebP兼容性](https://developers.google.com/speed/webp/faq#which_web_browsers_natively_support_webp) 75 | 76 | 更多关于WebB： 77 | 78 | [维基百科](https://zh.wikipedia.org/wiki/WebP) 79 | 80 | [WebP探寻之路](http://isux.tencent.com/introduction-of-webp.html) 81 | 82 | 83 | #### 团队约定 84 | 85 | ##### 内容图 86 | 87 | 内容图多以商品图等照片类图片形式存在，颜色较为丰富，文件体积较大 88 | 89 | * 优先考虑 JPEG 格式，条件允许的话优先考虑 WebP 格式 90 | * 尽量不使用PNG格式，PNG8 色位太低，PNG24 压缩率低，文件体积大 91 | 92 | ##### 背景图 93 | 94 | 背景图多为图标等颜色比较简单、文件体积不大、起修饰作用的图片 95 | 96 | * PNG 与 GIF 格式，优先考虑使用 PNG 格式,PNG格式允许更多的颜色并提供更好的压缩率 97 | * 图像颜色比较简单的，如纯色块线条图标，优先考虑使用 PNG8 格式，避免不使用 JPEG 格式 98 | * 图像颜色丰富而且图片文件不太大的（40KB 以下）或有半透明效果的优先考虑 PNG24 格式 99 | * 图像颜色丰富而且文件比较大的（40KB - 200KB）优先考虑 JPEG 格式 100 | * 条件允许的，优先考虑 WebP 代替 PNG 和 JPEG 格式 101 | 102 | ### 图片大小 103 | 104 | #### 全国网速现状 105 | 106 | ##### 固定网络 107 | 108 | 据文章 [《2015年Q3中国宽带速率状况报告》](http://www.199it.com/archives/399272.html)，2015第三季全国平均速度整体情况： 109 | 110 | ![image](http://labs.qiang.it/h5/guide/2015q3speed.jpg) 111 | 112 | 113 | 114 | 中国固定宽带互联网网络平均网络下载速率达到7.90 Mbit/s，用户进行网页浏览的平均首屏呈现时间为2.18s，平均视频下载速率为6.41Mbit/s 115 | 116 | ##### 移动网络 117 | 118 | 119 | 3G网络传输速率理论峰值在3.5Mbps，4G网络传输速率理论上可达到20Mbps，最高可以达到100Mbps。根据 `128KB/s=128×8(Kb/s)=1024Kb/s=1Mb/s` 的转换来算，3G网络的理论传输速率可达到450KB/s，4G网络的理论传输速率可达到 2.5MB/s ~ 12.5MB/s 120 | 121 | 受用户计算机性能、网络设备质量、资源使用情况、网络高峰期、网站服务能力、线路衰耗、信号衰减等多因素影响，3G和4G的实际平均传输速率约为： 122 | 123 | * 3G：最高值100KB/s，平均值40～50KB/s 124 | * 4G：最高值2.75MB/s，平均500～1000KB/s 125 | 126 | 127 | 128 | #### 3G/4G用户占比 129 | 130 | 131 | 2015年8月移动宽带（3G/4G）用户占比各省分布情况： 132 | 133 | ![image](http://labs.qiang.it/h5/guide/Img421935146.jpg) 134 | 135 | 据文章 [《工信部：2015年7月底中国4G用户累计超过2.5亿》](http://www.199it.com/archives/393838.html) 介绍： 136 | 137 | > 截至2015年7月底，中国4G用户累计超过2.5亿（全球LTE用户超过7.9亿，全球TD-LTE用户超过2.78亿），已建设4G基站超过153万个，其中完成TD-LTE基站建设超过100万个，多载波聚合等TD-LTE演进技术逐步商用，4G智能手机已经占到国内智能手机市场的82.7%。 138 | 139 | 140 | 141 | #### 团队约定 142 | 143 | 中国普通家庭的宽带基本能达到8Mbps，实际速率大约为500---900KB/s，全国3G/4G用户占有比超过了50%，为了保证图片能更好地加载展示给用户看，团队约定： 144 | 145 | **PC平台单张的图片的大小不应大于 200KB。** 146 | 147 | **移动平台单张的图片的大小不应大于 100KB。** 148 | 149 | *（图片的大小约定标准随全国网速的改变而改变）* 150 | 151 | 152 | ### 图片质量 153 | 154 | * 上线的图片都应该经过压缩处理，压缩后的图片不应该出现肉眼可感知的失真区域 155 | * 60质量的JPEG格式图片与质量大于60的相比，肉眼已看不出明显的区别，因此保存 JPEG 图的时候，质量一般控制在60，若保真度要求高的图片可适量提高到 80，图片大小控制在 200KB 以内 156 | 157 | ### 图片引入 158 | 159 | 测试内容图应该写上表明图片尺寸的占位图，可以用线上占位图生成服务，如： 160 | 161 | ``` 162 | http://placeholder.qiniudn.com/300x200 163 | ``` 164 | 165 | ![image](http://placeholder.qiniudn.com/300x200) 166 | 167 | 168 | 169 | HTML 中图片引入不需添加 width、height 属性，alt 属性应该写上 170 | 171 | *推荐：* 172 | 173 | ``` 174 | 175 | ``` 176 | 177 | *不推荐：* 178 | 179 | ``` 180 | 181 | ``` 182 | 183 | CSS 中图片引入不需要引号 184 | 185 | ``` 186 | .jdc { 187 | background-image: url(icon.png); 188 | } 189 | ``` 190 | 191 | ### CSS Sprites VS Data URIs 192 | 193 | #### CSS Sprites特点 194 | 195 | * 减少请求数 196 | * 加速图片的显示 197 | * 维护更新成本大 198 | * 更多的内存消耗，特别是大体积或有过多空白的 Sprites 图 199 | * 图片渗漏，相邻的不需展示的图片有可能出现在展示元素中，特别是在高清设备移动设备上 200 | 201 | #### Data URIs（base64编码） 202 | 203 | * 减少请求数 204 | * 转换文件体积大，大约比原始的二进制大33% 205 | * IE6 / IE7 不支持 206 | * 图片显示相对较慢，需要更多的CPU消耗 207 | 208 | 209 | 210 | 更多关于 CSS Sprites 和 Data URIs 可以阅读： 211 | 212 | [《When to Base64 Encode Images (and When Not To)》](http://davidbcalhoun.com/2011/when-to-base64-encode-images-and-when-not-to/) 213 | 214 | [《Data URI 最佳实践》](http://madscript.com/html5/datauri-best-practice/) 215 | 216 | [《Data URI&MHTML: 用还是不用？》](http://www.99css.com/492/) 217 | 218 | [CSS Sprites vs. Data URIs: Which is Faster on Mobile?](http://www.mobify.com/blog/css-sprites-vs-data-uris-which-is-faster-on-mobile/) 219 | 220 | #### 团队约定 221 | 222 | ##### CSS Sprites 使用建议 223 | 224 | * 适合使用频率高更新频率低的小图标 225 | * 尽量不留太多的空白 226 | * 体积较大的图片不合并 227 | * 确保要合并的小图坐标数值和合并后的 Sprites 图尺寸均为偶数 228 | 229 | 230 | ##### Data URIs（base64编码）使用建议 231 | 232 | * 合适更新频率高的小图片，如某些具备自定义功能的标题icon等 233 | * 转换成 Base64 编码的图片应小于 2KB 234 | * 移动端不使用 Base64 编码 235 | * 要兼容 IE6/IE7 的不使用 236 | 237 | 238 | 239 | 240 | 241 | 242 | 243 | 244 | 245 | 246 | 247 | 248 | 249 | 250 | -------------------------------------------------------------------------------- /source/docs/image/quality.md: -------------------------------------------------------------------------------- 1 | title: 图片质量 2 | --- 3 | 4 | * 上线的图片都应该经过压缩处理，压缩后的图片不应该出现肉眼可感知的失真区域 5 | * 60质量的JPEG格式图片与质量大于60的相比，肉眼已看不出明显的区别，因此保存 JPEG 图的时候，质量一般控制在60，若保真度要求高的图片可适量提高到 80，图片大小控制在 200KB 以内 -------------------------------------------------------------------------------- /source/docs/image/size.md: -------------------------------------------------------------------------------- 1 | title: 图片大小 2 | --- 3 | 4 | ## 图片大小 5 | 6 | ### 全国网速现状 7 | 8 | #### 固定网络 9 | 10 | 据文章 [《2015年Q3中国宽带速率状况报告》](http://www.199it.com/archives/399272.html)，2015第三季全国平均速度整体情况： 11 | 12 | ![image](http://labs.qiang.it/h5/guide/2015q3speed.jpg) 13 | 14 | 15 | 16 | 中国固定宽带互联网网络平均网络下载速率达到7.90 Mbit/s，用户进行网页浏览的平均首屏呈现时间为2.18s，平均视频下载速率为6.41Mbit/s 17 | 18 | #### 移动网络 19 | 20 | 21 | 3G网络传输速率理论峰值在3.5Mbps，4G网络传输速率理论上可达到20Mbps，最高可以达到100Mbps。根据 `128KB/s=128×8(Kb/s)=1024Kb/s=1Mb/s` 的转换来算，3G网络的理论传输速率可达到450KB/s，4G网络的理论传输速率可达到 2.5MB/s ~ 12.5MB/s 22 | 23 | 受用户计算机性能、网络设备质量、资源使用情况、网络高峰期、网站服务能力、线路衰耗、信号衰减等多因素影响，3G和4G的实际平均传输速率约为： 24 | 25 | * 3G：最高值100KB/s，平均值40～50KB/s 26 | * 4G：最高值2.75MB/s，平均500～1000KB/s 27 | 28 | 29 | 30 | ### 3G/4G用户占比 31 | 32 | 33 | 2015年8月移动宽带（3G/4G）用户占比各省分布情况： 34 | 35 | ![image](http://labs.qiang.it/h5/guide/Img421935146.jpg) 36 | 37 | 据文章 [《工信部：2015年7月底中国4G用户累计超过2.5亿》](http://www.199it.com/archives/393838.html) 介绍： 38 | 39 | > 截至2015年7月底，中国4G用户累计超过2.5亿（全球LTE用户超过7.9亿，全球TD-LTE用户超过2.78亿），已建设4G基站超过153万个，其中完成TD-LTE基站建设超过100万个，多载波聚合等TD-LTE演进技术逐步商用，4G智能手机已经占到国内智能手机市场的82.7%。 40 | 41 | 42 | ## 团队约定 43 | 44 | 中国普通家庭的宽带基本能达到8Mbps，实际速率大约为500---900KB/s，全国3G/4G用户占有比超过了50%，为了保证图片能更好地加载展示给用户看，团队约定： 45 | 46 | **PC平台单张的图片的大小不应大于 200KB。** 47 | 48 | **移动平台单张的图片的大小不应大于 100KB。** 49 | 50 | *（图片的大小约定标准随全国网速的改变而改变）* -------------------------------------------------------------------------------- /source/docs/index.md: -------------------------------------------------------------------------------- 1 | title: 概述 2 | --- 3 | 欢迎使用`前端代码规范`，使用过程中如碰到问题，请到[Github](https://github.com/o2team/guide/issues)进行提问。 4 | 5 | 6 | ## 关于 7 | 8 | `前端代码规范` 是由 [凹凸实验室](http://aotu.io) 整理的，基于 [W3C](http://www.w3.org/)、[苹果开发者](https://developer.apple.com/) 等官方文档，并结合团队日常业务需求以及团队在日常开发过程中总结提炼出的经验而制定。 9 | 10 | 旨在增强团队开发协作、提高代码质量和打造开发基石的编码规范， 11 | 12 | 以下规范是团队基本约定的内容，必须严格遵循。 13 | 14 | 15 | #### HTML规范 16 | 17 | 基于 [W3C](http://www.w3.org/)、[苹果开发者](https://developer.apple.com/) 等官方文档，并结合团队业务和开发过程中总结的规范约定，让页面HTML代码更具语义性。 18 | 19 | #### 图片规范 20 | 21 | 了解各种图片格式特性，根据特性制定图片规范，包括但不限于图片的质量约定、图片引入方式、图片合并处理等，旨在从图片层面优化页面性能。 22 | 23 | #### CSS规范 24 | 25 | 统一规范团队 CSS 代码书写风格和使用 CSS 预编译语言语法风格，提供常用媒体查询语句和浏览器私有属性引用，并从业务层面统一规范常用模块的引用。 26 | 27 | #### 命名规范 28 | 29 | 从 `目录`、`图片`、`HTML/CSS文件`、`ClassName` 的命名等层面约定规范团队的命名习惯，增强团队代码的可读性。 30 | 31 | #### JavaScript 规范 32 | 33 | 统一团队的 JS 语法风格和书写习惯，减少程序出错的概率，其中也包含了 ES6 的语法规范和最佳实践。 34 | 35 | #### React 规范 36 | 37 | 统一团队的类 React 应用的语法规范，规范类 React 应用书写。 38 | 39 | 40 | 41 | -------------------------------------------------------------------------------- /source/docs/issues.md: -------------------------------------------------------------------------------- 1 | title: 常见问题 2 | --- 3 | 4 | > 问：CSV文件打开乱码 5 | > 答：有时候程序导出来的csv文件在mac下用excel打开会乱码，此时可以用Numbers试试。 6 | 7 | > 问：把正在下载系统的mac放着充电，过了一天风扇很厉害强制关机，然后一直开不了 8 | > 答：估计是安装系统过程进入了休眠导致系统没有安装完，插入系统U盘一般可以解决。 9 | -------------------------------------------------------------------------------- /source/docs/js/code.md: -------------------------------------------------------------------------------- 1 | title: 代码规范 2 | --- 3 | 4 | ## 编码规范 5 | 6 | 统一团队的编码规范，有助于代码的维护。本章是传统意义上的 `Style Guideline`，目的是统一一些相对主观化的代码风格。 7 | 8 | ### 单行代码块 9 | 10 | 在单行代码块中使用空格 11 | 12 | *不推荐* 13 | 14 | ```js 15 | function foo () {return true} 16 | if (foo) {bar = 0} 17 | ``` 18 | 19 | *推荐* 20 | 21 | ```js 22 | function foo () { return true } 23 | if (foo) { bar = 0 } 24 | ``` 25 | 26 | ### 大括号风格 27 | 28 | 在编程过程中，大括号风格与缩进风格紧密联系，用来描述大括号相对代码块位置的方法有很多。在 JavaScript 中，主要有三种风格，如下： 29 | 30 | - **One True Brace Style** 31 | 32 | ```js 33 | if (foo) { 34 | bar() 35 | } else { 36 | baz() 37 | } 38 | ``` 39 | 40 | - **Stroustrup** 41 | 42 | ```js 43 | if (foo) { 44 | bar() 45 | } 46 | else { 47 | baz() 48 | } 49 | ``` 50 | 51 | - **Allman** 52 | 53 | ```js 54 | if (foo) 55 | { 56 | bar() 57 | } 58 | else 59 | { 60 | baz() 61 | } 62 | ``` 63 | 64 | 我们团队约定使用 `One True Brace Style` 风格 65 | 66 | ### 变量命名 67 | 68 | 当命名变量时，主流分为驼峰式命名（constiableName）和下划线命名（constiable_name）两大阵营。 69 | 70 | > 团队约定使用驼峰式命名 71 | 72 | ### 拖尾逗号 73 | 74 | 在 ECMAScript5 里面，对象字面量中的拖尾逗号是合法的，但在 IE8（非 IE8 文档模式）下，当出现拖尾逗号，则会抛出错误。 75 | 76 | 拖尾逗号的例子： 77 | 78 | ```js 79 | const foo = { 80 | name: 'foo', 81 | age: '22', 82 | } 83 | ``` 84 | 85 | 拖尾逗号的好处是，简化了对象和数组添加或删除元素，我们只需要修改新增的行即可，并不会增加差异化的代码行数。 86 | 87 | > 因为拖尾逗号有好也有不好，所以团队约定允许在最后一个元素或属性与闭括号 `]` 或 `}` 在不同行时，可以（但不要求）使用拖尾逗号。当在同一行时，禁止使用拖尾逗号。 88 | 89 | ### 逗号空格 90 | 91 | 逗号前后的空格可以提高代码的可读性，团队约定在逗号后面使用空格，逗号前面不加空格。 92 | 93 | *不推荐* 94 | 95 | ```js 96 | const foo = 1,bar = 2 97 | const foo = 1 , bar = 2 98 | const foo = 1 ,bar = 2 99 | ``` 100 | 101 | *推荐* 102 | 103 | ```js 104 | const foo = 1, bar = 2 105 | ``` 106 | 107 | ### 逗号风格 108 | 109 | 逗号分隔列表时，在 JavaScript 中主要有两种逗号风格： 110 | - 标准风格，逗号放置在当前行的末尾 111 | - 逗号前置风格，逗号放置在下一行的开始位置 112 | 113 | > 团队约定使用标准风格 114 | 115 | *不推荐* 116 | 117 | ```js 118 | const foo = 1 119 | , 120 | bar = 2 121 | 122 | const foo = 1 123 | , bar = 2 124 | 125 | const foo = ['name' 126 | , 'age'] 127 | ``` 128 | 129 | *推荐* 130 | 131 | ```js 132 | const foo = 1, 133 | bar = 2 134 | 135 | const foo = ['name', 136 | 'age'] 137 | ``` 138 | 139 | ### 计算属性的空格 140 | 141 | 团队约定在对象的计算属性内，禁止使用空格 142 | 143 | *不推荐* 144 | 145 | ```js 146 | obj['foo' ] 147 | obj[ 'foo'] 148 | obj[ 'foo' ] 149 | ``` 150 | 151 | *推荐* 152 | 153 | ```js 154 | obj['foo'] 155 | ``` 156 | 157 | ### 拖尾换行 158 | 159 | 在非空文件中，存在拖尾换行是一个常见的 `UNIX` 风格，它的好处是可以方便在串联和追加文件时不会打断 `Shell` 的提示。在日常的项目中，保留拖尾换行的好处是，可以减少版本控制时的代码冲突。 160 | 161 | *不推荐* 162 | 163 | ```js 164 | function func () { 165 | // do something 166 | } 167 | ``` 168 | 169 | *推荐* 170 | 171 | ```js 172 | function func () { 173 | // do something 174 | } 175 | // 此处是新的一行 176 | ``` 177 | 178 | > 可以通过 .editorconfig 添加 EOL 179 | 180 | ### 函数调用 181 | 182 | 为了避免语法错误，团队约定在函数调用时，禁止使用空格 183 | 184 | *不推荐* 185 | 186 | ```js 187 | fn () 188 | fn 189 | () 190 | ``` 191 | 192 | *推荐* 193 | 194 | ```js 195 | fn() 196 | ``` 197 | 198 | ### 缩进 199 | 200 | 代码保持一致的缩进，是作为工程师的职业素养。但缩进用两个空格，还是四个空格，是用 `Tab` 还是空格呢？这样的争论太多了，也得不出答案。本规范结合了市面上优秀的开源项目，姑且约定使用 `空格` 来缩进，而且缩进使用两个空格。 201 | 202 | 那是不是不能使用 `Tab` 进行缩进了？我们可以通过配置 `.editorconfig` ，将 `Tab` 自动转换为空格。 203 | 204 | ### 对象字面量的键值缩进 205 | 206 | 团队约定对象字面量的键和值之间不能存在空格，且要求对象字面量的冒号和值之间存在一个空格 207 | 208 | *不推荐* 209 | 210 | ```js 211 | const obj = { 'foo' : 'haha' } 212 | ``` 213 | 214 | *推荐* 215 | 216 | ```js 217 | const obj = { 'foo': 'haha' } 218 | ``` 219 | 220 | ### 构造函数首字母大写 221 | 222 | 在 JavaScript 中 `new` 操作符用来创建某个特定类型的对象的一个实例，该类型的对象是由一个构造函数表示的。由于构造函数只是常规函数，唯一区别是使用 `new` 来调用。所以我们团队约定构造函数的首字母要大小，以此来区分构造函数和普通函数。 223 | 224 | *不推荐* 225 | 226 | ```js 227 | const fooItem = new foo() 228 | ``` 229 | 230 | *推荐* 231 | 232 | ```js 233 | const fooItem = new Foo() 234 | ``` 235 | 236 | ### 构造函数的参数 237 | 238 | 在 JavaScript 中，通过 `new` 调用构造函数时，如果不带参数，可以省略后面的圆括号。但这样会造成与整体的代码风格不一致，所以团队约定使用圆括号 239 | 240 | *不推荐* 241 | 242 | ```js 243 | const person = new Person 244 | ``` 245 | 246 | *推荐* 247 | 248 | ```js 249 | const person = new Person() 250 | ``` 251 | 252 | ### 链式调用 253 | 254 | 链式调用如果放在同一行，往往会造成代码的可读性差，但有些时候，短的链式调用并不会影响美观。所以本规范约定一行最多只能有四个链式调用，超过就要求换行。 255 | 256 | ### 空行 257 | 258 | 空白行对于分离代码逻辑有帮助，但过多的空行会占据屏幕的空间，影响可读性。团队约定最大连续空行数为 2 259 | 260 | *不推荐* 261 | 262 | ```js 263 | const a = 1 264 | 265 | 266 | 267 | const b = 2 268 | ``` 269 | 270 | *推荐* 271 | 272 | ```js 273 | const a = 1 274 | 275 | 276 | const b = 2 277 | ``` 278 | 279 | ### 链式赋值 280 | 281 | 链式赋值容易造成代码的可读性差，所以团队约定禁止使用链式赋值 282 | 283 | *不推荐* 284 | 285 | ```js 286 | const a = b = c = 1 287 | ``` 288 | 289 | *推荐* 290 | 291 | ```js 292 | const a = 1 293 | const b = 1 294 | const c = 1 295 | ``` 296 | 297 | ### 变量声明 298 | 299 | JavaScript 允许在一个声明中，声明多个变量。团队约定在声明变量时，一个声明只能有一个变量 300 | 301 | *不推荐* 302 | 303 | ```js 304 | const a, b, c 305 | ``` 306 | 307 | *推荐* 308 | 309 | ```js 310 | const a 311 | const b 312 | const c 313 | ``` 314 | 315 | ### 分号 316 | 317 | JavaScript 在所有类 C 语言中是比较独特的，它不需要在每个语句的末尾有分号。在很多情况下，JavaScript 引擎可以确定一个分号应该在什么位置然后自动添加它。此特征被称为 自动分号插入 (ASI)，被认为是 JavaScript 中较为有争议的特征。 318 | 319 | 团队中对于是否应该使用分号，也有许多争论，本规范推荐不使用分号，因为我们认为好的工程师应该知道什么时候该加，什么时候不该加。 320 | 321 | 相关参考 ：[semi](http://eslint.org/docs/rules/semi) 322 | 323 | ### 代码块空格 324 | 325 | 一致性是任何风格指南的重要组成部分。虽然在哪里放置块的开括号纯属个人偏好，但在整个项目中应该保持一致。不一致的风格将会分散读者阅读代码的注意力。 326 | 327 | > 团队约定代码块前要添加空格 328 | 329 | *不推荐* 330 | 331 | ```js 332 | if (a){ 333 | b() 334 | } 335 | 336 | function a (){} 337 | ``` 338 | 339 | *推荐* 340 | 341 | ```js 342 | if (a) { 343 | b() 344 | } 345 | 346 | function a () {} 347 | ``` 348 | 349 | ### 函数声明的空格 350 | 351 | 当格式化一个函数，函数名或 function 关键字与左括号之间允许有空白。命名函数要求函数名和 function 关键字之间有空格，但是匿名函数要求不加空格。 352 | 353 | > 团队约定函数括号前要加空格 354 | 355 | *不推荐* 356 | 357 | ```js 358 | function func(x) { 359 | // ... 360 | } 361 | ``` 362 | 363 | *推荐* 364 | 365 | ```js 366 | function func (x) { 367 | // ... 368 | } 369 | ``` 370 | 371 | ### 操作符的空格 372 | 373 | 团队约定操作符前后都需要添加空格 374 | 375 | *不推荐* 376 | 377 | ```js 378 | const sum = 1+2 379 | ``` 380 | 381 | *推荐* 382 | 383 | ```js 384 | const sum = 1 + 2 385 | ``` 386 | 387 | ### BOM 388 | 389 | Unicode 字节顺序标记 (BOM) 用来指定代码单元是高字节序还是低字节序。也就是说，是高位在前还是低位在前。UTF-8 不需要 BOM 来表明字节顺序，因为单个字节并不影响字节顺序。 390 | 391 | 相信不少同学遇到过 BOM 的坑，这里不多说了，切记不要使用 windows 的记事本改代码！ 392 | -------------------------------------------------------------------------------- /source/docs/js/react.md: -------------------------------------------------------------------------------- 1 | title: React&JSX 书写规范 2 | --- 3 | 4 | ## React&JSX 书写规范 5 | 6 | > 本规范基本基于标准的 JavaScript 语法规范 7 | 8 | ### 基本规则 9 | 10 | - 每个文件只包含一个 React 类组件 11 | - 但是多个函数式组件可以放到一个文件中，eslint: [react/no-multi-comp](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-multi-comp.md#ignorestateless) 12 | - 一般使用 JSX 语法 13 | - 除非是在非 JSX 文件中初始化应用，否则不要使用 `React.createElement` 14 | 15 | ### 命名规范 16 | 17 | - 组件文件扩展名 18 | 19 | 如果使用 JavaScript，则文件扩展名为 `.js`；如果使用 `TypeScript`，则文件扩展名为 `.tsx` 20 | 21 | - 组件文件名 22 | 23 | 如果是组件文件，则使用 PascalCase，如 `MyComponent.js` 24 | 25 | 如果组件是一个目录，则组件主入口命名为 `index`，如 `index.js` 26 | 27 | - 引用命名 28 | 29 | React 组件使用 PascalCase，组件实例使用 CamelCase，eslint: [react/jsx-pascal-case](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-pascal-case.md) 30 | 31 | ```jsx 32 | // bad 33 | import reservationCard from './ReservationCard' 34 | 35 | // good 36 | import ReservationCard from './ReservationCard' 37 | 38 | // bad 39 | const ReservationItem = 40 | 41 | // good 42 | const reservationItem = 43 | ``` 44 | 45 | - 组件命名 46 | 47 | 使用文件名作为组件名字，例如, `ReservationCard.js` 应该包含名为 `ReservationCard` 的引用，然而对于文件夹中的根组件, 使用 `index.js` 作为文件名，使用文件夹的名字作为组件的名字 48 | 49 | ```jsx 50 | // bad 51 | import Footer from './Footer/Footer' 52 | 53 | // bad 54 | import Footer from './Footer/index' 55 | 56 | // good 57 | import Footer from './Footer' 58 | ``` 59 | 60 | - 组件属性名 61 | 62 | React DOM 使用小驼峰式命名法来定义属性的名称，而不使用 HTML 属性名称的命名约定，例如 63 | 64 | ```jsx 65 |
    66 | ``` 67 | 68 | ### Class Component VS Functional Component 69 | 70 | 只允许使用 `Class Component` 和 `Functional Component` 两种形态来书写组件，建议尽量使用函数式组件配合 Hooks 来进行开发 71 | 72 | ### 对齐 73 | 74 | 遵循以下JSX语法的对齐风格，eslint: [react/jsx-closing-bracket-location](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-closing-bracket-location.md) 75 | 76 | ```jsx 77 | // bad 78 | 80 | 81 | // good 82 | 86 | 87 | // if props fit in one line then keep it on the same line 88 | 89 | 90 | // children get indented normally 91 | 95 | 96 | 97 | 98 | // bad 99 | {showButton && 100 |