css-loader
安装
npm install --save-dev css-loader
用法
css-loader 解释(interpret) @import 和 url() ,会 import/require() 后再解析(resolve)它们。
引用资源的合适 loader 是 file-loader和 url-loader,你应该在配置中指定(查看如下设置)。
file.js
import css from 'file.css';
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: [ 'style-loader', 'css-loader' ]
}
]
}
}
你也可以直接将 css-loader 的结果作为字符串使用,例如 Angular 的组件样式。
webpack.config.js
{
test: /\.css$/,
use: [
'to-string-loader',
'css-loader'
]
}
或者
const css = require('./test.css').toString();
console.log(css); // {String}
如果有 SourceMaps,它们也将包含在结果字符串中。
如果由于某种原因,你需要将 CSS 提取为纯粹的字符串资源(即不包含在 JS 模块中),则可能需要查看 extract-loader。 例如,当你需要将 CSS 作为字符串进行后处理时,这很有用。
webpack.config.js
{
test: /\.css$/,
use: [
'handlebars-loader', // handlebars loader expects raw resource string
'extract-loader',
'css-loader'
]
}
选项
名称
类型
默认值
描述
root
{String}
/
解析 URL 的路径,以 / 开头的 URL 不会被转译
url
{Boolean}
true
启用/禁用 url() 处理
alias
{Object}
{}
创建别名更容易导入一些模块
import
{Boolean}
true
启用/禁用 @import 处理
modules
{Boolean}
false
启用/禁用 CSS 模块
minimize
{Boolean|Object}
false
启用/禁用 压缩
sourceMap
{Boolean}
false
启用/禁用 Sourcemap
camelCase
{Boolean|String}
false
以驼峰化式命名导出类名
importLoaders
{Number}
0
在 css-loader 前应用的 loader 的数量
localIdentName
{String}
hash:base64
配置生成的标识符(ident)
root
对于以 / 开头的 URL,默认行为是不转译它们。
url(/image.png) => url(/image.png)
如果设置了 root 查询参数,那么此查询参数将被添加到 URL 前面,然后再进行转译。
webpack.config.js
{
loader: 'css-loader',
options: { root: '.' }
}
url(/image.png) => require('./image.png')
不建议使用'相对根路径'的 url。你应该只将其用于旧版 CSS 文件。
url
要禁用 css-loader 解析 url(),将选项设置为 false。
与现有的 css 文件兼容(如果不是在 CSS 模块模式下)。
url(image.png) => require('./image.png')
url(~module/image.png) => require('module/image.png')
alias
用别名重写你的 URL,在难以改变输入文件的url 路径时,这会很有帮助,例如,当你使用另一个包(package)(如 bootstrap, ratchet, font-awesome 等)中一些 css/sass 文件。
css-loader 的别名,遵循与webpack 的 resolve.alias 相同的语法,你可以在resolve 文档 查看细节
file.scss
@charset "UTF-8";
@import "bootstrap";
webpack.config.js
{
test: /\.scss$/,
use: [
{
loader: "style-loader"
},
{
loader: "css-loader",
options: {
alias: {
"../fonts/bootstrap": "bootstrap-sass/assets/fonts/bootstrap"
}
}
},
{
loader: "sass-loader",
options: {
includePaths: [
path.resolve("./node_modules/bootstrap-sass/assets/stylesheets")
]
}
}
]
}
看看这个工作引导示例。
import
要禁用 css-loader 解析 @import,将选项设置为false
@import url('https://fonts.googleapis.com/css?family=Roboto');
⚠️谨慎使用,因为这将禁用解析所有 @import,包括 css 模块 composes: xxx from 'path/to/file.css' 功能。
modules
查询参数 modules 会启用 CSS 模块规范。
默认情况下,这将启用局部作用域 CSS。(你可以使用 :global(...) 或 :global 关闭选择器 and/or 规则。
Scope
默认情况下,CSS 将所有的类名暴露到全局的选择器作用域中。样式可以在局部作用域中,避免全局作用域的样式。
语法 :local(.className) 可以被用来在局部作用域中声明 className。局部的作用域标识符会以模块形式暴露出去。
使用 :local(无括号)可以为此选择器启用局部模式。:global(.className) 可以用来声明一个明确的全局选择器。使用:global(无括号)可以将此选择器切换至全局模式。
loader 会用唯一的标识符(identifier)来替换局部选择器。所选择的唯一标识符以模块形式暴露出去。
:local(.className) { background: red; }
:local .className { color: green; }
:local(.className .subClass) { color: green; }
:local .className .subClass :global(.global-class-name) { color: blue; }
._23_aKvs-b8bW2Vg3fwHozO { background: red; }
._23_aKvs-b8bW2Vg3fwHozO { color: green; }
._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 { color: green; }
._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 .global-class-name { color: blue; }
:information_source:标识符被导出
exports.locals = {
className: '_23_aKvs-b8bW2Vg3fwHozO',
subClass: '_13LGdX8RMStbBE9w-t0gZ1'
}
建议局部选择器使用驼峰式。它们在导入 JS 模块中更容易使用。
url() 中的 URL 在块作用域 (:local .abc) 规则中的表现,如同请求模块。
file.png => ./file.png
~module/file.png => module/file.png
你可以使用 :local(#someId),但不推荐这种用法。推荐使用 class 代替 id。 你可以使用 localIdentName 查询参数(默认 [hash:base64])来配置生成的 ident。
webpack.config.js
{
test: /\.css$/,
use: [
{
loader: 'css-loader',
options: {
modules: true,
localIdentName: '[path][name]__[local]--[hash:base64:5]'
}
}
]
}
你还可以通过自定义 getLocalIdent 函数来指定绝对路径,以根据不同的模式(schema)生成类名。这需要 webpack >= 2.2.1(options 对象支持传入函数)。
webpack.config.js
{
loader: 'css-loader',
options: {
modules: true,
localIdentName: '[path][name]__[local]--[hash:base64:5]',
getLocalIdent: (context, localIdentName, localName, options) => {
return 'whatever_random_class_name'
}
}
}
重要信息:对于使用 extract-text-webpack-plugin 预渲染,你应该在预渲染 bundle 中 使用 css-loader/locals 而不是 style-loader!css-loader 。它不会嵌入 CSS,但只导出标识符映射(identifier map)。
Composing
当声明一个局部类名时,你可以与另一个局部类名组合为一个局部类。
:local(.className) {
background: red;
color: yellow;
}
:local(.subClass) {
composes: className;
background: blue;
}
这不会导致 CSS 本身发生任何变化,但会导出多个类名。
exports.locals = {
className: '_23_aKvs-b8bW2Vg3fwHozO',
subClass: '_13LGdX8RMStbBE9w-t0gZ1 _23_aKvs-b8bW2Vg3fwHozO'
}
._23_aKvs-b8bW2Vg3fwHozO {
background: red;
color: yellow;
}
._13LGdX8RMStbBE9w-t0gZ1 {
background: blue;
}
Importing
从另一个模块导入本地类名。
:local(.continueButton) {
composes: button from 'library/button.css';
background: red;
}
:local(.nameEdit) {
composes: edit highlight from './edit.css';
background: red;
}
要从多个模块导入,请使用多个composes:规则。
:local(.className) {
composes: edit hightlight from './edit.css';
composes: button from 'module/button.css';
composes: classFromThisModule;
background: red;
}
minimize
默认情况下,如果模块系统指定,css-loader 将压缩 css。
在某些情况下,压缩对于 css 来说是破坏性的,所以如果需要设置,可以向基于 cssnano 的 minifier(cssnano-based minifier) 提供自己的选项。更多可用信息请查看 cssnano 文档。
还可以使用 minimize 查询参数,来禁用或强制压缩。
webpack.config.js
{
loader: 'css-loader',
options: {
minimize: true || {/* CSSNano Options */}
}
}
sourceMap
设置 sourceMap 选项查询参数来引入 source map。
I. e extract-text-webpack-plugin 可以处理它们。
默认情况下不启用它们,因为它们会导致运行时的额外开销,并增加了 bundle 大小 (JS source map 不会)。此外,相对路径是错误的,你需要使用包含服务器 URL 的绝对公用路径。
webpack.config.js
{
loader: 'css-loader',
options: {
sourceMap: true
}
}
camelCase
默认情况下,导出 JSON 键值对形式的类名。如果想要驼峰化( camelize )类名(有助于在 JS 中使用),通过设置 css-loader 的查询参数 camelCase 即可实现。
名称
类型
描述
true
{Boolean}
类名将被驼峰化
'dashes'
{String}
只有类名中的破折号将被驼峰化
'only'
{String}
在 0.27.1 中加入。类名将被驼峰化,初始类名将从局部移除
'dashesOnly'
{String}
在 0.27.1 中加入。类名中的破折号将被驼峰化,初始类名将从局部移除
file.css
.class-name {}
file.js
import { className } from 'file.css';
webpack.config.js
{
loader: 'css-loader',
options: {
camelCase: true
}
}
importLoaders
查询参数 importLoaders,用于配置「css-loader 作用于 @import 的资源之前」有多少个 loader。
webpack.config.js
{
test: /\.css$/,
use: [
'style-loader',
{
loader: 'css-loader',
options: {
importLoaders: 1 // 0 => no loaders (default); 1 => postcss-loader; 2 => postcss-loader, sass-loader
}
},
'postcss-loader',
'sass-loader'
]
}
在模块系统(即 webpack)支持原始 loader 匹配后,此功能可能在将来会发生变化。
例子
资产
以下 webpack.config.js 可以加载 CSS 文件,将小体积 PNG/JPG/GIF/SVG 图像转为像字体那样的 Data URL 嵌入,并复制较大的文件到输出目录。
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: [ 'style-loader', 'css-loader' ]
},
{
test: /\.(png|jpg|gif|svg|eot|ttf|woff|woff2)$/,
loader: 'url-loader',
options: {
limit: 10000
}
}
]
}
}
提取
对于生产环境构建,建议从 bundle 中提取 CSS,以便之后可以并行加载 CSS/JS 资源。可以通过使用 extract-text-webpack-plugin 来实现,在生产环境模式运行中提取 CSS。
webpack.config.js
const env = process.env.NODE_ENV
const ExtractTextPlugin = require('extract-text-webpack-plugin')
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: env === 'production'
? ExtractTextPlugin.extract({
fallback: 'style-loader',
use: [ 'css-loader' ]
})
: [ 'style-loader', 'css-loader' ]
},
]
},
plugins: env === 'production'
? [
new ExtractTextPlugin({
filename: '[name].css'
})
]
: []
}