Laravel 文档阅读: JavaScript & CSS 脚手架代码

翻译、衍生自:https://laravel.com/docs/5.5/frontend

简介

Laravel 没有非要让你用哪个 Javascript 库或者哪个 CSS 预处理器,但还是热心地开箱提供了 Bootstrap 和 Vue 脚手架代码,这对大多数项目来说都是非常有帮助的。默认,Laravel 使用 NPM 安装这些前端包。

Laravel 中的 JavaScript 和 CSS 脚手架代码是用 Laravel Mix 编译的。Laravel Mix 是构建在 Webpack 上的一个前端代码构建工具,它隐藏了 Webpack 底层的复杂配置,暴露出极易上手的 API,让你轻松编译前端代码不是梦。

CSS

Laravel Mix 支持 SASS 和 Less 这两个 CSS 预处理器的编译功能。 CSS 预处理器只是对 CSS 的扩展,是一套语法规则,并不是一门新的编程语言,引入它是为了让样式表结构更加清晰和更好维护。

本篇文档里只是简单涉及了 CSS 编译,更加详细地编译 SASS 或者 Less 文件的内容需要参考 Laravel Mix 文档。

JavaScript

Laravel 没有要求开发者使用哪个 JavaScript 框架或者 JavaScript 库来构建项目。事实上,你可以完全不用 JavaScript 库或框架。但是,作为可能是全世界最好用的 PHP 框架,默认,Laravel 还是热心的在项目里提供了 Vue.js 脚手架代码。Vue 在使用组件和有表现力的 API 构建现代的 JavaScript 应用上非常厉害。

与 CSS 一样,我们也可以使用 Laravel Mix 将 Vue 的多个组件轻松地编译成一个可供浏览器使用的 JavaScript 脚本文件。

移除前端脚手架代码

如果不想用 Laravel 提供的前端脚手架代码,使用 Artisan 命令 preset none 即可移除。

php artisan preset none

这条命令会移除所有的 Bootstrap 和 Vue 脚手架代码,保留一个空白的 SASS 文件和一些常用的 JavaScript 工具库(包括 lodash、jquery、axios,在 resources/assets/js/bootstrap.js 中定义引入的)。

写 CSS

Laravel 项目根目录下的 package.json 文件默认包含了 bootstrap-sass 文件。

"devDependencies": {
    "axios": "^0.16.2",
    "bootstrap-sass": "^3.3.7",
    "cross-env": "^5.0.1",
    "jquery": "^3.1.1",
    "laravel-mix": "^1.0",
    "lodash": "^4.17.4",
    "vue": "^2.1.10"
}

这能帮助开发者用 Bootstrap 框架快速开发一个前端页面原型。如果你不想用 Bootstrap,直接 php artisan preset none 去掉就是了,没什么大不了的。不过,这给直接用 Bootstrap 框架开发项目的人带来不少福音。

在编译 CSS 之前,确保项目使用 NPM,已安装好前端依赖包。

npm install 

依赖安装好后,就可以用 Laravel Mix 把 SASS 文件编译成纯 CSS 文件.。我们可以用 npm run dev 编译咱们的前端文件,这条命令是按照项目根目录下 webpack.mix.js 配置文件中指定的规则编译前端文件的。编译好的 CSS 文件一般就放在 public/css 这个目录下面:

 npm run dev

webpack.mix.js 文件中,其实已经预设好了编译规则。

const { mix } = require('laravel-mix');

/*
 |--------------------------------------------------------------------------
 | Mix Asset Management
 |--------------------------------------------------------------------------
 |
 | Mix provides a clean, fluent API for defining some Webpack build steps
 | for your Laravel application. By default, we are compiling the Sass
 | file for the application as well as bundling up all the JS files.
 |
 */

mix.js('resources/assets/js/app.js', 'public/js')
   .sass('resources/assets/sass/app.scss', 'public/css');

瞧(咱们先不看 JS 那段), Laravel Mix 要把 resources/assets/sass/app.scss 编译到 public/css 这里去了,编译好的文件名是 app.css

你也可以看 app.scss 文件里的内容:

// Fonts
@import url(https://fonts.googleapis.com/css?family=Raleway:300,400,600);

// Variables
@import "variables";

// Bootstrap
@import "node_modules/bootstrap-sass/assets/stylesheets/bootstrap";

就是引入字体,引入咱自定义的变量(会覆盖下面的 Bootstrap SASS 文件里的默认变量),还有 Bootstrap 框架的 SASS 源码。这些东西最后都编译到了 app.css 这个文件里。当然这些规则你可以修改的,看你实际的需要了。

另外,webpack.mix.js 文件里的规则也完全可以自定义不使用 SASS,而用 Less,这会在 Laravel Mix 文档里讲到的。

写 JavaScript

所有引入项目的 JavaScript 依赖在根目录下的 package.json 文件里定义。 package.jsoncomposer.json 类似,但是前者是引入 JavaScript 依赖,后者是引入 PHP 依赖。使用 NPM 来安装项目的 JavaScript 依赖:

npm install

默认,package.json 定义了少量依赖,包括 vueaxios,帮助开发者快速开发 JavaScript 程序。你可以按照需要,在 package.json 增加或者删除所需的依赖。

依赖安装好后,就可以使用 npm run dev 命令编译脚本了。Webpack 是用于现代 JavaScript 应用程序的模块绑定器。执行 npm run dev 命令事时,Webpack 会按照 webpack.mix.js 文件里的设定规则进行脚本编译和打包。

npm dev

默认,Laravel webpack.mix.js 中的设定规则会编译 resources/assets/sass/app.scssresources/assets/js/app.js 文件,前者已经说过,这里不再赘述,我们看 app.js

/**
 * First we will load all of this project's JavaScript dependencies which
 * includes Vue and other libraries. It is a great starting point when
 * building robust, powerful web applications using Vue and Laravel.
 */

require('./bootstrap');

window.Vue = require('vue');

/**
 * Next, we will create a fresh Vue application instance and attach it to
 * the page. Then, you may begin adding components to this application
 * or customize the JavaScript scaffolding to fit your unique needs.
 */

Vue.component('example', require('./components/Example.vue'));

const app = new Vue({
    el: '#app'
});

app.js 中注册了 Vue 组件,当然,你也可以应用其他什么的框架在你的项目里,只要你愿意。编译好的 JavaScript 文件就放在 public/js 目录下。

注意,在 app.js 文件会加载 resources/assets/js/bootstrap.js 文件里的内容。我们来看看 bootstrap.js 这个文件:

window._ = require('lodash');

/**
 * We'll load jQuery and the Bootstrap jQuery plugin which provides support
 * for JavaScript based Bootstrap features such as modals and tabs. This
 * code may be modified to fit the specific needs of your application.
 */

try {
    window.$ = window.jQuery = require('jquery');

    require('bootstrap-sass');
} catch (e) {}

/**
 * We'll load the axios HTTP library which allows us to easily issue requests
 * to our Laravel back-end. This library automatically handles sending the
 * CSRF token as a header based on the value of the "XSRF" token cookie.
 */

window.axios = require('axios');

window.axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';

/**
 * Next we will register the CSRF Token as a common header with Axios so that
 * all outgoing HTTP requests automatically have it attached. This is just
 * a simple convenience so we don't have to attach every token manually.
 */

let token = document.head.querySelector('meta[name="csrf-token"]');

if (token) {
    window.axios.defaults.headers.common['X-CSRF-TOKEN'] = token.content;
} else {
    console.error('CSRF token not found: https://laravel.com/docs/csrf#csrf-x-csrf-token');
}

/**
 * Echo exposes an expressive API for subscribing to channels and listening
 * for events that are broadcast by Laravel. Echo and event broadcasting
 * allows your team to easily build robust real-time web applications.
 */

// import Echo from 'laravel-echo'

// window.Pusher = require('pusher-js');

// window.Echo = new Echo({
//     broadcaster: 'pusher',
//     key: 'your-pusher-key'
// });

内容看起来很多,但是,去掉注释,单看代码就非常清晰了:在页面窗口对象(window)上注册我们的 JavaScript 依赖库,包括 lodash、jquery(引入这个,是为了能用 bootstrap 提供的一些组件功能,例如模型和切换条)、axios(并配置了 X-Requested-With 请求头,说明自己是 Ajax 请求,不是传统的 HTTP 请求,还有 X-CSRF-TOKEN 防攻击令牌),就这么点内容。

日后,一些额外新增的 JavaScript 依赖都是在这个 bootstrap.js 文件里注册、配置的

写 Vue 组件

默认,Laravel 在 resources/assets/js/components 这个目录里,提供了一个 Vue 组件的范例 Example.vue。以 .vue 为后缀名的文件是单文件形式的 Vue 组件文件的后缀名,在这个文件里包含 HTML 模板代码,JavaScript 代码甚至是为组件单独定义的 CSS 样式!下面请看 Example.vue 文件的内容:

<template>
    <div class="container">
        <div class="row">
            <div class="col-md-8 col-md-offset-2">
                <div class="panel panel-default">
                    <div class="panel-heading">Example Component</div>

                    <div class="panel-body">
                        I'm an example component!
                    </div>
                </div>
            </div>
        </div>
    </div>
</template>

<script>
    export default {
        mounted() {
            console.log('Component mounted.')
        }
    }
</script>

注意,这里使用了 Bootstrap 的布局样式,没有自定义自己的 CSS 样式。 Bootstrap 的布局样式之所以会生效,是因为在 resources/assets/sass/app.scss 文件里引入了 bootstrap-sass 库,因而最终编译好的 app.css 文件里就有 Bootstrap CSS 样式了。

注册一个 Vue 组件是在 app.js 文件里完成的:

Vue.component('example', require('./components/Example.vue'));

要使用这个组件也非常容易。例如,在执行 make:auth Artisan 命令后得到的认证系统里,你可以直接把咱们的组件放在 home.blade.php Blade 模板文件中,像这样:

@extends('layouts.app')

@section('content')
    <example></example>
@endsection

记住了,每当你修改了一个 Vue 组件的代码,就要重新执行 npm run dev 命令编译它才行。或者,使用更加方便的 npm run watch 命令,在你每次修改完一个 Vue 组件的代码后,组件内容会自动重新编译,这很大程度上解决了每次都要重新执行 npm run dev 命令的烦恼。

如果不会 Vue 的话,看它 文档 就 OK 了,文档写得非常好和容易懂。

使用 React

如果更喜欢用 React 来构建 JavaScript 应用程序的话在 Laravel 也很容易做到!使用 Artisan 命令 preset react 即可:

php artisan preset react

这条命令会把默认的 Vue脚手架代码,替换成 React 的,还包括一个 React 的范例页面哦。