wechat h5 boilerplate
v0.3.6
"Make H5 production as easy as PPT production!"
Wechat-H5-Boilerplate (hereinafter referred to as WHB) is an H5 dynamic template, specially optimized for WeChat and suitable for quickly building a full-screen scrolling H5 promotional page.
For example, it only takes one line of code to animate a piece of text:
<p class="animated" data-ani-name="slideInRight" data-ani-duration="1s" data-ani-delay="0.3s">I'm a coder!</p>
Use your mobile phone to visit the address below or scan the QR code below
https://panteng.github.io/wechat-h5-boilerplate/
/app
/dist --> 项目文件的分发版本，所有的文件均由Gulp任务生成，请勿手动修改
/audios --> 从app/src/audios复制而来
/fonts --> 从app/src/fonts和在config/vendors.js中指定的第三方字体复制而来
/images --> 由app/src/images下的图片经Imagemin压缩优化生成
/javascripts --> 由app/src/javascripts下的文件经Browserify打包生成
/stylesheets --> 由app/src/scss下的文件编译生成
index.html --> 由app/src/index.html经Gulp-inject插入bundle.(min.).css和bundle.(min.).js后生成
/src --> 项目的源码，所有文件都可编辑
/audios --> 存放音频、视频文件
/fonts --> 存放字体文件
/images --> 存放图片文件
/javascripts --> JS源文件，经Browserify打包后生成app/dist/javascripts/bundle.js
/scss --> SCSS文件，经过编译后生成app/dist/stylesheets/bundle.css
index.html --> 页面HTML，经过Gulp-inject处理后生成app/dist/index.html
/config
vendors.js --> 第三方CSS、JS、Fonts列表，详见vendors.js说明
.gitignore
gulpfile.js --> Gulp任务
package.json
Clone this project locally
Run in console:
git clone --depth=1 https://github.com/panteng/wechat-h5-boilerplate.git <your-project-name>
cd <your-project-name>
Or you can download the WHB source code compressed package directly from the Release page.
Install third-party packages
WHB uses NPM to manage third-party packages
Run in console:
npm install
Note 1: Due to the poor network environment in China, downloading packages on NPM is very slow. It is recommended to use Taobao NPM mirror CNPM. For the installation method of CNPM, please refer to the official website instructions. CNPM v4.2.0 has a bug on Windows systems (refer to #97). Windows users should not use this version. Although the official said it has been fixed, I still get an error when I use CNPM on Windows to install packages that require node-gyp compilation. I also don't recommend using CNPM v3.4.1 because its built-in NPM version is too old. It is recommended to install npm install --registry=https://registry.npm.taobao.org -d directly using the mirror warehouse. (-d is added to display detailed information during the installation process. I personally often use this method to determine whether the installation process is stuck due to network or other problems).
Note 2: Some third-party packages required by WHB depend on node-gyp. Before installing these packages, please confirm that node-gyp has been correctly installed on your machine. Please refer to the node-gyp official documentation for installation. Windows users may have some trouble as installing node-gyp on Windows is a pain.
Note 3: Windows users, please do not place WHB in a directory that is too deep in the path. Because Windows only supports paths with a length of less than 255 characters, if you place this project in a directory with a deep path, it is very likely that node-gyp will fail to compile.
Note 4: Windows users, if you have correctly installed node-gyp, but still get an error when running npm install -d , and the error message is "EPERM, operation not permitted", please try npm install -d --force .
Start development
Run on console:
gulp dev
After a moment, the browser window will automatically open and point to the address localhost:3000 . When you modify any file under app/src, the browser page will automatically refresh.
Execute gulp prod task
Run in console:
gulp prod
This task will generate two new files bundle.min.css and bundle.min.js in the app/dist folder, and delete the original bundle.css and bundle.js.
When publishing, you only need to upload the files in the app/dist folder to the server, no other files are required. The CSS, JS and image files in app/dist are compressed and optimized.
loading animation
H5 pages usually contain a lot of pictures and background music, so a good-looking loading animation is necessary.
You can write some CSS3 animations yourself, insert the animation-related HTML code into <div class="loading-overlay"></div> in app/src/index.html, and integrate the relevant CSS3 Animation code into in app/src/scss.
If you want to save trouble, the website loading.io can help you generate ready-made loading animations (if you can't open it, please go through the wall). It is recommended to generate an animated image file in SVG format, change the file to loading.svg and replace the file with the same name under app/src/images/.
Also share some excellent CSS3 loading animation libraries:
Page switching effect
Page switching currently only supports the four types that come with Swiper: slide, fade, flip and coverflow (cube does not support it because it does not meet this scenario). See the section on effects in the Swiper documentation for details.
WHB is not yet able to specify different switching methods for different pages. I will consider adding this feature and more cool switching methods in subsequent versions.
Animation of elements (pictures, text) within the page
Adding animation to pictures and text in WHB is very easy.
For example, there is a paragraph of text on the first page that needs to be displayed in animation. The code is as follows:
<div class="swiper-slide slide-1">
<p class="animated" data-ani-name="slideInRight" data-ani-duration="1s" data-ani-delay="0.3s">I'm a coder!</p>
</div>
Just add the class name animated to this text and specify the three attributes data-ani-name (animation name), data-ani-duration (animation execution time), and data-ani-delay (animation delay time). .
WHB's animation is provided by Animate.css. The supported animation names can be viewed on the Animate.css official website.
Font icon
There are only two icons in the font icon file that comes with WHB, namely the music symbol in the upper right corner and the upstroke prompt symbol at the bottom of the screen. If you need more icons, it is recommended to use Icomoon.io for customization, select the icons you need (you can also design and upload them yourself), and package them into font files.
The reason why it is not recommended to use general font packages such as Font-Awesome is that there are many icons in Font-Awesome, so the font file will be relatively large, and most of the icons are not used. Larger font files can slow down the loading of web pages on user devices.
Image optimization
WHB comes with the function of lossy compression of images under app/src/images, but I still recommend that you perform necessary manual optimization on the images before throwing them into the app/src/images folder, such as Adjust to appropriate size, integrate some small pictures into sprites, etc.
Share some useful image optimization and processing websites:
background music
It is recommended that the file format of background music is mp3 and the size should not exceed 1MB. You can use professional audio editing software such as Adobe Audition to intercept and compress background music.
If not necessary, please do not set background music to disturb users.
Mobile terminal debugging
First, run the gulp dev task and find the following paragraph in the console output:
[BS] Access URLs:
----------------------------------------
Local: http://localhost:3000
External: http://192.168.187.101:3000
----------------------------------------
UI: http://localhost:3001
UI External: http://192.168.187.101:3001
----------------------------------------
Then, make sure your mobile device (mobile phone, tablet, etc.) and computer are in the same LAN (the simplest way is to connect the computer, mobile phone and tablet to the same WIFI; or the computer is connected to the router with a network cable, and the mobile phone and tablet are connected to the same WIFI. WIFI issued by the router).
Finally, open the browser on your mobile device and access the URL corresponding to External in the third line above (note that your URL may be different from what I wrote above, please refer to the External URL displayed in your own console).
Now as long as you modify the file under app/src, all mobile devices and computers that access this URL will automatically refresh the browser page. Operations you perform on one device are also synced to the other devices in real time (such as swiping up on a page with your finger).
Responsive design
It is recommended to use rem instead of px to set the size, margin and font size of elements.
In WHB, the px value corresponding to 1rem will change with the device screen size.
On devices with screen width less than 400px, 1rem = 16px;
On devices with a screen width greater than 400px and less than 600px, 1rem = 22px;
On devices with screen width greater than 600px, 1rem = 32px;
See the code about Media Query in app/src/scss/base/_base.scss.
config/vendors.js description
The vendors.js file is used to register third-party CSS, JS and Fonts information. All third-party files registered in vendors.js will be added to the project in some form. For example: If vendors.js now looks like this:
module.exports = {
stylesheets: [
'node_modules/normalize.css/normalize.css',
'node_modules/swiper/dist/css/swiper.css',
'node_modules/animate.css/animate.css',
'node_modules/font-awesome/css/font-awesome.css'
],
javascripts: [
'node_modules/jquery/dist/jquery.js'，
'node_modules/swiper/dist/js/swiper.jquery.js'
],
fonts: [
'node_modules/font-awesome/fonts/*'
]
};
All css files in the stylesheets of vendors.js will be added to the bundle.css finally generated by the project;
All js files in the javascripts of vendors.js will be added to the bundle.js finally generated by the project;
All files in the fonts of vendors.js will be copied to the app/dist/fonts folder.
Remember that files registered in vendors.js will be added to bundle.css and bundle.js first, so you don’t need to worry about the styles in SCSS you wrote being overwritten or finding that an object from a third-party library is not found in main.js. defined situation. The files registered in vendors.js will be added to bundle.css and bundle.js in order of registration, so you have to ensure that the registration order is correct. For example, jquery.js must be registered before swiper.jquery.js, because swiper.jquery .js is dependent on jquery.js.
Note 1: The file path is relative to gulpfile.js, not vendors.js.
Note 2: If you don’t like to import third-party JS files in this way, and want to use CommonJS’s require writing method to import them, that’s also possible. For example, introduce jQuery in app/src/javascripts/main.js in this way:
var $ = require('jquery');
Gulp tasks
During the development process, if you find that you have modified or replaced the images, audio, fonts and other files under the app/src file, but the page in the browser has not changed accordingly, please try to run gulp dev again in the console gulp dev tasks.
MIT
