README.md 4.92 KB
Newer Older
YazhouChen's avatar
YazhouChen committed
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
![download](https://img.shields.io/npm/dm/numerify.svg)
![version](https://img.shields.io/npm/v/numerify.svg)
![Travis](https://img.shields.io/travis/xiguaxigua/numerify.svg)
![npm bundle size (minified)](https://img.shields.io/bundlephobia/min/numerify.svg)
![language](https://img.shields.io/badge/language-javascript-yellow.svg)
![License](https://img.shields.io/badge/license-MIT-000000.svg)

[docs](http://daxigua.me/numerify/) | [demo](http://jsfiddle.net/vue_echarts/fywjmdvL/)

This is a formatted value tool that makes formatting easier and more
convenient to extend.

## Install

`npm i numerify -S`

## Start

### npm

```js
import numerify from 'numerify'
// commonjs package is 'numerify/lib/index.cjs.js'
console.log(numerify(1234, '0,0'))
```

### cdn

```html
<script src="https://unpkg.com/numerify/lib/index.umd.min.js"></script>
<script>
console.log(numerify(1234, '0,0'))
</script>
```

## Format List

| Number | Format | String |
| --: | --: | --: |
| 10000 | '0,0.0000' | 10,000.0000 |
| 10000.23 | '0,0' | 10,000 |
| 10000.23 | '+0,0' | +10,000 |
| -10000 | '0,0.0' | -10,000.0 |
| 10000.1234 | '0.000' | 10000.123 |
| 100.1234 | '00000' | 00100 |
| 1000.1234 | '000000,0' | 001,000 |
| 10 | '000.00' | 010.00 |
| 10000.1234 | '0[.]00000' | 10000.12340 |
| -10000 | '(0,0.0000)' | (10,000.0000) |
| -0.23 | '.00' | -.23 |
| -0.23 | '(.00)' | (.23) |
| 0.23 | '0.00000' | 0.23000 |
| 0.23 | '0.0[0000]' | 0.23 |
| 1230974 | '0.0a' | 1.2m |
| 1460 | '0 a' | 1 k |
| -104000 | '0a' | -104k |
| 1 | '0%' | 100% |
| 0.974878234 | '0.000%' | 97.488% |
| -0.43 | '0 %' | -43 % |
| 0.43 | '(0.000 %)' | 43.000 % |

## Methods

#### numerify(number, formatter, roundFunction)

- formatter default is `'0,0'`
- roundFunction default is `Math.round`

#### numerify.setOptions

this default options is:

```js
{
  zeroFormat: null,
  nullFormat: null,
  defaultFormat: '0,0',
  scalePercentBy100: true,
  abbrLabel: {
    th: 'k',
    mi: 'm',
    bi: 'b',
    tr: 't'
  }
}
```

in order to edit it, you can code such as

```js
numerify.setOptions({
  zeroFormat: 'N/A',
  nullFormat: 'N/A',
  defaultFormat: '0,0',
  scalePercentBy100: true,
  abbrLabel: {
    th: 'k',
    mi: 'm',
    bi: 'B',
    tr: 'T'
  }
})
numerify(0, '0.0') // N/A
```

#### numerify.reset

`numerify.setOptions` will change global settings and you can
use this function to reset options.

#### numerify.register

Adding your own custom formats is as easy as adding a locale.

```js
numerify.register('percentage', {
  regexp: /%/,
  format (value, format, roundingFunction) {
    const space = ~format.indexOf(' %') ? ' ' : ''
    let output

    if (numerify.options.scalePercentBy100) value = value * 100

    format = format.replace(/\s?%/, '')

    output = numerify._numberToFormat(value, format, roundingFunction)

    if (~output.indexOf(')')) {
      output = output.split('')
      output.splice(-1, 0, space + '%')
      output = output.join('')
    } else {
      output = output + space + '%'
    }

    return output
  }
})
```

#### numerify.unregister

remove formatter which has been registed.

```js
numerify.unregister('percentage')
```

#### numerify._numberToFormat

This is an internal function, used to format `()` , ` ,` , `+-` , `kmbt` , `.` and `[]`.

```js
numerify._numberToFormat(<value>, <format>, [roundingFunction])
```

## Plugins

plugins are packaged into `lib/plugins` folder, and you can use it such as:

```js
import numerifyBytes from 'numerify/lib/plugins/bytes.umd.js'
numerify.register('bytes', numerifyBytes)
```

plugins types and usage are as follows:

#### bps

| Number | Format | String |
| --: | --: | --: |
| 0 | '0 BPS' | 0 BPS |
| 0.0001 | '0 BPS' | 1 BPS |
| .0056 | '0 BPS' | 56 BPS |
| .25 | '0BPS' | 2500BPS |
| .000001 | '0.00 BPS' | 0.01 BPS |


#### bytes

| Number | Format | String |
| --: | --: | --: |
| 100 | '0b' | 100B |
| 1024 | '0b' | 1KB |
| 2048 | '0 ib' | 2 KiB |
| 3072 | '0.0 b' | 3.1 KB |
| 7884486213 | '0.00b' | 7.88GB |
| 3467479682787 | '0.000 ib' | 3.154 TiB |

#### currency

| Number | Format | String |
| --: | --: | --: |
| 1000.234 | '$0,0.00' | $1,000.23 |
| 1000.2 | '0,0[.]00 $' | 1,000.20 $ |
| 1001 | '$ 0,0[.]00' | $ 1,001 |
| -1000.234 | '($0,0)' | ($1,000) |
| -1000.234 | '$0.00' | -$1000.23 |
| 1230974 | '($ 0.00 a)' | $ 1.23 m |

#### exponential

| Number | Format | String |
| --: | --: | --: |
| 1123456789 | '0,0e+0' | 1e+9 |
| 12398734.202 | '0.00e+0' | 1.24e+7 |
| 0.000123987 | '0.000e+0' | 1.240e-4 |

#### ordinal

| Number | Format | String |
| --: | --: | --: |
| 1 | '0o' | 1st |
| 1 | '0 o' | 1 st |
| 100 | '0o' | 100th |

#### time

| Number | Format | String |
| --: | --: | --: |
| 25 | '00:00:00' | 0:00:25 |
| 238 | '00:00:00' | 0:03:58 |
| 63846 | '00:00:00' | 17:44:06 |

## Difference with numeral

The numeral is a very useful tool, and numerify draws on this thinking. The difference is that numerify focuses on the parts that format values without parsing values, is smaller (12k vs 3k), and performs better.

## License

MIT