aaac7fed
 liuqimichale
add
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
|
# postcss-url
[](https://travis-ci.org/postcss/postcss-url)
[](https://ci.appveyor.com/project/MoOx/postcss-url)
[](https://david-dm.org/postcss/postcss-url)
[](https://david-dm.org/postcss/postcss-url?type=dev)
> [PostCSS](https://github.com/postcss/postcss) plugin to rebase, inline or copy on url().
## Installation
```console
$ npm install postcss-url
```
## Basic example - rebase
```js
// dependencies
const fs = require("fs")
const postcss = require("postcss")
const url = require("postcss-url")
// css to be processed
const css = fs.readFileSync("input.css", "utf8")
// process css
const output = postcss()
.use(url({
url: "rebase"
}))
.process(css, {
from: "src/stylesheet/index.css",
to: "dist/index.css"
})
```
before:
```css
.element {
background: url('images/sprite.png');
}
```
after:
```css
.element {
/* rebasing path by new destination */
background: url('../src/stylesheet/images/sprite.png');
}
```
## Inline
```js
// postcss-url options
const options = {
url: 'inline'
};
postcss()
.use(url(options))
.process(css, {
from: "src/stylesheet/index.css",
to: "dist/index.css"
})
```
before:
```css
.element {
background: url('/images/sprite.png');
filter: url('/images/circle.svg');
}
```
after:
```css
.element {
/* inlined png as base64 */
background: url('data:image/png;base64,R0lGODlhAQABAJH/AP///wAAAP///wAAACH/C0FET0JFOklSMS4');
/* inlined svg as encodeURIComponent */
filter: url('data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%2F%3E');
}
```
## Copy
```js
// postcss-url options
const options = {
url: 'copy',
// base path to search assets from
basePath: path.resolve('node_modules/bootstrap'),
// dir to copy assets
assetsPath: 'img',
// using hash names for assets (generates from asset content)
useHash: true
};
postcss()
.use(url(options))
.process(css, {
from: "src/stylesheet/index.css",
to: "dist/index.css"
})
```
before:
```css
.element {
background: url('/images/sprite.png');
}
```
after:
```css
.element {
/* copy 'sprite.png' from 'node_modules/bootstrap/images/' to 'dist/img/' */
/* and rename it by hash function */
background: url('img/a2ds3kfu.png');
}
```
### Muiltiple options
process first matched option by default.
```multi: true``` in `custom` will processing with other options
```js
const options = [
{ filter: '**/assets/copy/*.png', url: 'copy', assetsPath: 'img', useHash: true },
{ filter: '**/assets/inline/*.svg', url: 'inline' },
{ filter: '**/assets/**/*.gif', url: 'rebase' },
// using custom function to build url
{ filter: 'cdn/**/*', url: (asset) => `https://cdn.url/${asset.url}` }
];
postcss().use(url(options))
```
Checkout [tests](test) for examples.
### Options combinations
* `rebase` - _default_
* `assetsPath` - directory to copy assets (relative to `to` or absolute)
* `inline`
* `basePath` - path or array of paths to search assets (relative to `from`, or absolute)
* `encodeType` - `base64`, `encodeURI`, `encodeURIComponent`
* `includeUriFragment` - include the fragment identifer at the end of the URI
* `maxSize` - file size in kbytes
* `fallback` - `copy`, `rebase` or custom function for files > `maxSize`
* `ignoreFragmentWarning` - do not warn when an SVG URL with a fragment is inlined
* `optimizeSvgEncode` - reduce size of inlined svg (IE9+, Android 3+)
* `copy`
* `basePath` - path or array of paths to search assets (relative to `from`, or absolute)
* `assetsPath` - directory to copy assets (relative to `to` or absolute)
* `useHash` - use filehash(xxhash) for naming
* `hashOptions` - options for hash function
* `custom {Function}`
* `multi` - processing with other options
### Options list
#### `url`
##### `rebase` - _(default)_
Allow you to fix `url()` according to postcss `to` and/or `from` options (rebase to `to` first if available, otherwise `from` or `process.cwd()`).
##### `inline`
Allow you to inline assets using base64 encoding. Can use postcss `from` option to find ressources.
##### `copy`
Allow you to copy and rebase assets according to postcss `to`, `assetsPath` and `from` options (`assetsPath` is relative to the option `to`).
##### `url: {Function}`
Custom transform function. Takes following arguments:
* `asset`
* `url` - original url
* `pathname` - url pathname (url without search or hash)
* `absolutePath` - absolute path to asset
* `relativePath` - current relative path to asset
* `search` - _search_ from `url`, ex. `?query=1` from `./image.png?query=1`
* `hash` - _hash_ from `url`, ex. `#spriteLink` from `../asset.svg#spriteLink`
* `dir`
* `from` - postcss option from
* `to` - postcss option to
* `file` - decl file path
* `options` - postcss-url matched options
* `decl` - related postcss declaration object
* `warn` - wrapped function `result.warn` for current `decl`
* `result` – postcss result object
And should return the transformed url.
You can use this option to adjust urls for CDN.
#### `maxSize`
Specify the maximum file size to inline (in kbytes)
#### `ignoreFragmentWarning`
_(default: `false`)_
Do not warn when an SVG URL with a fragment is inlined.
PostCSS-URL does not support partial inlining. The entire SVG file will be inlined. By default a warning will be issued when this occurs.
**NOTE:** Only files less than the maximum size will be inlined.
#### `filter`
A regular expression e.g. `/\.svg$/`, a [minimatch string](https://github.com/isaacs/minimatch) e.g. `'**/*.svg'` or a custom filter function to determine wether a file should be inlined.
#### `fallback`
The url fallback method to use if max size is exceeded or url contains a hash.
Custom transform functions are supported.
#### `includeUriFragment`
_(default: `false`)_
Specifies whether the URL's fragment identifer value, if present, will be added
to the inlined data URI.
#### `basePath`
Specify the base path or list of base paths where to search images from
#### `assetsPath`
_(default: `false`)_
If you specify an `assetsPath`, the assets files will be copied in that
destination
#### `useHash`
_(default: `false`)_
If set to `true` the copy method is going to rename the path of the files by a hash name
#### `hashOptions`
##### `method`
_(default: `xxhash32`)_
Hash method `xxhash32|xxhash64` or custom function (accept file buffer)
##### `shrink`
_(default: `8`)_
Result hash shrink count
##### `append`
_(default: `false`)_
Prepend the original filename in resulting filename
---
## Contributing
Work on a branch, install dev-dependencies, respect coding style & run tests before submitting a bug fix or a feature.
```console
$ git clone https://github.com/postcss/postcss-url.git
$ git checkout -b patch-1
$ npm install
$ npm test
```
## [Changelog](CHANGELOG.md)
## [License](LICENSE)
|
