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}
如果有 SourceMap,它们也将包含在字符串结果中。
如果由于某种原因,你需要将 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")
]
}
}
]
}
查看此示例 working bootstrap example。
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; }
:主要信息: 标识符被导出
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 ```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**
```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。
例如 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 => 无 loader(默认); 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'
})
]
: []
}
Juho Vepsäläinen | Joshua Wiens | Kees Kluskens | Sean Larkin |
Michael Ciniawsky | Evilebot Tnawi | Joscha Feth |