# icon-font-loader

- [README in English](README.md)

这是一款可以自动将 svg 转换成字体图标的 Webpack loader。

## 示例

在 CSS 中需要使用图标的地方用自定义属性`icon-font`引入 svg 文件：

``` css
.select:after {
    icon-font: url('../icons/arrow-down.svg');
    /* icon-font: url('../icons/arrow-down.svg') '\ff12'; */ /* 指定最终的 unicode */
    color: #666;
}
```

通过 icon-font-loader 将会转变为浏览器可识别的 CSS：

``` css
.select:after {
    font-family: 'icon-font';
    font-style: normal;
    font-weight: normal;
    ...
    content: '\f106';
    /* content: '\ff12'; */ /* 指定最终的 unicode */
    color: #666;
}
```

加载器会收集所有这样的引用，统一打包成 (eot,svg,ttf,woff) 字体文件，并在`<head>`中插入一个有`@font-face`的`<style>`标签或抛出一个这样的 CSS 文件。

``` css
@font-face {
    font-family: "icon-font";
    src: url("icon-font.eot?4063944d4c3fb8fa7bf4c19ad0f59965?#iefix") format("embedded-opentype"),
         url("icon-font.woff?4063944d4c3fb8fa7bf4c19ad0f59965") format("woff"),
         url("icon-font.ttf?4063944d4c3fb8fa7bf4c19ad0f59965") format("truetype"),
         url("icon-font.svg?4063944d4c3fb8fa7bf4c19ad0f59965#icon-font") format("svg");
}
```

当然，如果开启`dataURL`选项会转换为

``` css
@font-face {
	font-family: "icon-font";
	src:url("data:application/x-font-woff;base64,d09GRgABAAAAAAUkAAsAAAAACQgAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAABHU1VCAAABCAAAAHcAAAC4Ifsmu09TLzIAAAGAAAAAPQAAAFZWTEunY21hcAAAAcAAAADxAAACuqtTRqJnbHlmAAACtAAAAEIAAABwWoXqgmhlYBewAAA=") format("woff");
}
```

## 特性

与别的类似的字体图标加载器不同的是：

- 在 CSS 中使用。利用 CSS 的特性，可以很轻松地覆盖原图标：
    ``` css
    .select:after {
        icon-font: url('../icons/arrow-down.svg');
        color: #666;
    }

    .select.up:after {
        icon-font: url('../icons/arrow-up.svg');
    }
    ```
- 必须在`before`或`after`伪元素中使用，我们正是利用了它们的`content`属性，将字体图标视为某种字体下的特殊字符。
- 合并重复的图标。如果有相同的图标而它们的文件名或路径不同，我们会将它们合并起来，减少字体大小。

## 安装

``` shell
npm install --save-dev icon-font-loader
```

## 配置

除了在 CSS 中添加自定义属性，还需要在 Webpack 配置中添加一个 Plugin。

```javascript
const IconFontPlugin = require('icon-font-loader').Plugin;

module.exports = {
    ...
    module: {
        rules: [{ test: /\.css$/, use: ['style-loader', 'css-loader', 'icon-font-loader'] }],
    },
    plugins: [new IconFontPlugin()],
};
```

### Loader 参数

暂无。

### Plugin 参数

#### fontName

字体图标的字体名和文件名。

- Type: `string`
- Default: `'icon-font'`

#### filename

用于设置生成文件名的模板，类似于 Webpack 的 output.filename。模板支持以下占位符：

- `[ext]` 生成资源文件后缀
- `[name]` 字体名称
- `[fontName]` 字体名称，`[name]`的别名
- `[hash]` 生成文件中 svg 文件的 hash 值（默认使用16进制 md5 hash，所有文件使用 svg 的 hash，其他文件的 hash 有时会发生改变）
- `[<hashType>:hash:<digestType>:<length>]` 生成 hash 的样式
    - `hashType` hash 类型，比如：`sha1`, `md5`, `sha256`, `sha512`
    - `digestType` 数字进制：`hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`
    - `length` 字符长度


- Type: `string`
- Default: `'[name].[ext]?[hash]'`

#### output

字体和 CSS 等文件相对于 webpack 的 output 的相对路径。**必须是一个相对路径。**

- Type: `string`
- Default: `'./'`

#### publicPath

字体在 CSS url 中的路径，与 Webpack 的 publicPath 相同，此选项用于覆盖它。

- Type: `String`
- Default: `''`

#### localCSSTemplate

局部 CSS 虚拟属性转换后内容, 接受模板内容而不是模板文件的路径。

如果设置该选项值为空，则不会生成局部 CSS。

- Type: `string`
- Default: [global.css.hbs的内容](https://github.com/vusion/icon-font-loader/blob/master/src/global.css.hbs)

比如，该模板变量会生成下面 CSS 规则中的内容。

``` css
.icon-1::before, .icon-2::before .icon-3::before {
    font-family: '{{ fontName }}';
    font-style: normal;
    font-weight: normal;
    font-variant: normal;
    text-decoration: inherit;
    text-rendering: optimizeLegibility;
    text-transform: none;
    -moz-osx-font-smoothing: grayscale;
    -webkit-font-smoothing: antialiased;
    font-smoothing: antialiased;
}
```

#### localCSSSelector

局部 CSS 的选择器默认是当前文件所有图标选择器的合并。

如果设置该选项，默认的选择器会被设置的值代替。

- Type: `string`
- Default: `''`

举例说明，比如设置该选项为`'.my-icon'`, 局部 CSS 会生成成下面的代码:

``` css
.my-icon {
    font-family: '{{ fontName }}';
    font-style: normal;
    font-weight: normal;
    font-variant: normal;
    text-decoration: inherit;
    text-rendering: optimizeLegibility;
    text-transform: none;
    -moz-osx-font-smoothing: grayscale;
    -webkit-font-smoothing: antialiased;
    font-smoothing: antialiased;
}
```

#### property

CSS 的自定义属性名

- Type: `string`
- Default: `'icon-font'`

#### auto

是否在chunk中自动插入@font-face css 片段。如果不希望每一chunk都插入这段css，那么设置这个参数未false，我们将会生成额外的css文件供手动插入。

- Type: `boolean`
- Default: `true`

#### dataURL

如果设置为`true`，字体会转换成 data base64 嵌入到 CSS 中，而不是生成对应的字体文件。

在字体图标不多的情况下推荐使用，因为字体文件会产生额外的请求。

- Type: `boolean`
- Default: `false`

#### startCodepoint

- Type: `number`
- Default: `0xF101`

unicode 的字符起始点。

#### fontOptions

这个属性将直接传入[svgicons2svgfont](https://github.com/nfroidure/svgicons2svgfont)。

默认设置了`descent`字体基线选项，这样对于大部分图标来说，不用额外添加`vertical-align`样式。这是一个最佳实践。

- Type: `Object`
- Default:
  ``` js
  {
    fontHeight: 1000,
    descent: 140,
    centerHorizontally: true,
  }
  ```

#### entries

指定需要插入字体文件引入css的入口，如果没有指定或者是空数组，那么将会为所有的入口插入字体引入样式。

- Type: `Array`
- Default: `undefined`

## 修改日志

参见[Releases](https://github.com/vusion/icon-font-loader/releases)

## 贡献指南

参见[Contributing Guide](https://github.com/vusion/DOCUMENTATION/issues/4)

## 开源协议

参见[LICENSE](LICENSE)
