|
| 1 | +# Vue2 Time Picker |
| 2 | + |
| 3 | +A dropdown time picker (hour|minute|second) for **Vue 2.x**, with flexible time format support. |
| 4 | + |
| 5 | +> Looking for the Vue 1.x version? Please check the [vue-timepicker](https://github.com/phoenixwong/vue-timepicker) *(Vue 1.x supported)* |
| 6 | +
|
| 7 | +## Demo |
| 8 | + |
| 9 | +You can see the **Vue2 Timepicker** in action in the [Demo Page](https://phoenixwong.github.io/vue2-timepicker/) |
| 10 | + |
| 11 | +## Dependencies |
| 12 | + |
| 13 | +[Vue.js](http://vuejs.org/) v2.0+ |
| 14 | + |
| 15 | +## Get Started |
| 16 | + |
| 17 | +**Step 1:** Import VueTimepicker |
| 18 | + |
| 19 | +```javascript |
| 20 | +// import |
| 21 | +import VueTimepicker from 'vue2-timepicker' |
| 22 | + |
| 23 | +// Or, require |
| 24 | +var VueTimepicker = require('vue2-timepicker') |
| 25 | + |
| 26 | +``` |
| 27 | + |
| 28 | +**Step 2**: Include VueTimepicker in your component |
| 29 | + |
| 30 | +```javascript |
| 31 | +var yourComponent = new Vue({ |
| 32 | + components: { VueTimepicker }, |
| 33 | + ... |
| 34 | +}) |
| 35 | +``` |
| 36 | + |
| 37 | +**Step 3**: Then, you can introduce the `vue-timepicker` tag anywhere you like in your component's template |
| 38 | + |
| 39 | +```html |
| 40 | +<vue-timepicker></vue-timepicker> |
| 41 | +``` |
| 42 | + |
| 43 | +## Usage |
| 44 | + |
| 45 | +### Basic Usage |
| 46 | + |
| 47 | +```html |
| 48 | +<!-- Default to 24-Hour format HH:mm --> |
| 49 | +<vue-timepicker></vue-timepicker> |
| 50 | +``` |
| 51 | + |
| 52 | +### Customized Time Format |
| 53 | + |
| 54 | +```html |
| 55 | +<!-- Show seconds picker --> |
| 56 | +<vue-timepicker format="HH:mm:ss"></vue-timepicker> |
| 57 | + |
| 58 | +<!-- 12-hour format, with AM/PM picker --> |
| 59 | +<vue-timepicker format="hh:mm A"></vue-timepicker> |
| 60 | + |
| 61 | +<!-- 12-hour format, with seconds picker and am/pm picker --> |
| 62 | +<vue-timepicker format="hh:mm:ss a"></vue-timepicker> |
| 63 | +``` |
| 64 | + |
| 65 | +VueTimepicker will recognizes the following tokens in the format string |
| 66 | + |
| 67 | +Section | Token | Output |
| 68 | +---------- | ----- | --------------- |
| 69 | +**AM/PM** | A | AM PM |
| 70 | + | a | am pm |
| 71 | +**Hour** | H | 0 1 ... 22 23 |
| 72 | + | HH | 00 01 ... 22 23 |
| 73 | + | h | 1 2 ... 11 12 |
| 74 | + | hh | 01 02 ... 11 12 |
| 75 | + | k | 1 2 ... 23 24 |
| 76 | + | kk | 01 02 ... 23 24 |
| 77 | +**Minute** | m | 0 1 ... 58 59 |
| 78 | + | mm | 00 01 ... 58 59 |
| 79 | +**Second** | s | 0 1 ... 58 59 |
| 80 | + | ss | 00 01 ... 58 59 |
| 81 | + |
| 82 | +> If not set, `format` string will be default to "HH:mm" |
| 83 | +
|
| 84 | +### Customized Picker interval |
| 85 | + |
| 86 | +```html |
| 87 | +<!-- Show minute picker's value in the form of 0, 5, 10, ... 55, 60 --> |
| 88 | +<vue-timepicker :minute-interval="5"></vue-timepicker> |
| 89 | + |
| 90 | +<!-- Show second picker's value in the form of 0, 10, 20, ... 50, 60 --> |
| 91 | +<vue-timepicker :second-interval="10"></vue-timepicker> |
| 92 | + |
| 93 | +<!-- Bind interval config with your own data variable --> |
| 94 | +<vue-timepicker :minute-interval="yourMinuteInterval"></vue-timepicker> |
| 95 | +``` |
| 96 | + |
| 97 | +**Note:** Please do remember to add the `:` or `v-bind:` sign before the interval properties |
| 98 | + |
| 99 | +### Hide Clear Button |
| 100 | + |
| 101 | +```html |
| 102 | +<vue-timepicker hide-clear-button></vue-timepicker> |
| 103 | +``` |
| 104 | + |
| 105 | +### Bind Value with `v-model` |
| 106 | + |
| 107 | +```javascript |
| 108 | +// e.g. If you want to assign "10:05:00" as the initial value of vue-timepicker |
| 109 | +var yourComponent = new Vue({ |
| 110 | + components: { VueTimepicker }, |
| 111 | + data: function () { |
| 112 | + return { |
| 113 | + yourTimeValue: { |
| 114 | + HH: "10", |
| 115 | + mm: "05", |
| 116 | + ss: "00" |
| 117 | + }, |
| 118 | + ... |
| 119 | + } |
| 120 | + }, |
| 121 | + ... |
| 122 | +}) |
| 123 | +``` |
| 124 | + |
| 125 | +```html |
| 126 | +<!-- HTML --> |
| 127 | +<vue-timepicker v-model="yourTimeValue" format="HH:mm:ss"></vue-timepicker> |
| 128 | +``` |
| 129 | + |
| 130 | +### Get Time Picker's Current Value |
| 131 | + |
| 132 | +**Method 1:** Read value from `v-model` |
| 133 | + |
| 134 | +```html |
| 135 | +<!-- In the last section, we've set the initial value (yourTimeValue) to "10:05:00" --> |
| 136 | +<vue-timepicker v-model="yourTimeValue" format="HH:mm:ss"></vue-timepicker> |
| 137 | +``` |
| 138 | + |
| 139 | +```javascript |
| 140 | +// Then, open the dropdown picker and pick a new time. |
| 141 | +// Like setting to "14:30:15" for example |
| 142 | +// Check the value after that |
| 143 | +console.log(this.yourTimeValue) |
| 144 | +// outputs -> {HH: "14", mm: "30", ss: "15"} |
| 145 | +``` |
| 146 | + |
| 147 | +**Method 2:** Add `@change` event handler |
| 148 | + |
| 149 | +```html |
| 150 | +<!-- A: No argument --> |
| 151 | +<vue-timepicker :time-value.sync="yourTimeValue" @change="changeHandler"></vue-timepicker> |
| 152 | + |
| 153 | +<!-- B: Custom arguments --> |
| 154 | +<vue-timepicker :time-value.sync="yourTimeValue" @change="otherChangeHandler($event, 'foo', 'bar')"></vue-timepicker> |
| 155 | +``` |
| 156 | + |
| 157 | +```javascript |
| 158 | +// A: No argument |
| 159 | +changeHandler (eventData) { |
| 160 | + console.log(eventData) |
| 161 | + // -> {data: {HH:..., mm:... }} |
| 162 | +} |
| 163 | + |
| 164 | +// B: Custom arguments |
| 165 | +otherChangeHandler (eventData, yourArg1, yourArg2) { |
| 166 | + console.log(eventData) |
| 167 | + // -> {data: {HH:..., mm:... }} |
| 168 | + console.log(yourArg1) |
| 169 | + // -> 'foo' |
| 170 | + console.log(yourArg2) |
| 171 | + // -> 'bar' |
| 172 | +} |
| 173 | +``` |
| 174 | + |
| 175 | +Unlike `v-model`, which only returns the defined time tokens you provided in the binding variable, the `change` event will return **all** supported formats. |
| 176 | + |
| 177 | +In the example above, when picker is set to "14:30:15" in HH:mm:ss format, `change` event will return the following data: |
| 178 | + |
| 179 | +```javascript |
| 180 | +// `@change` event data |
| 181 | +{ |
| 182 | + HH: "14", |
| 183 | + H: "14", |
| 184 | + hh: "14", |
| 185 | + a: "am", |
| 186 | + A: "AM", |
| 187 | + h: "14", |
| 188 | + kk: "14", |
| 189 | + k: "14", |
| 190 | + m: "30", |
| 191 | + mm: "30", |
| 192 | + s: "15", |
| 193 | + ss: "15" |
| 194 | +} |
| 195 | +``` |
| 196 | + |
| 197 | +Whereas the `v-model` will only return the data with defined tokens |
| 198 | + |
| 199 | +```javascript |
| 200 | +// Previously defined variable (`yourTimeValue` in this case) as {HH:..., mm:..., ss:...} |
| 201 | +// Hence, the `v-model` returns: |
| 202 | +{ |
| 203 | + HH: "14", |
| 204 | + mm: "30", |
| 205 | + ss: "15" |
| 206 | +} |
| 207 | +``` |
| 208 | + |
| 209 | +## Props API |
| 210 | + |
| 211 | +Prop | Type | Required | Default Value |
| 212 | +--------------------- | --------- | -------- | ------------- |
| 213 | +**v-model** | _Object_ | no | _undefined_ |
| 214 | +**format** | _String_ | no | "HH:mm" |
| 215 | +**minute-interval** | _Number_ | no | _undefined_ |
| 216 | +**second-interval** | _Number_ | no | _undefined_ |
| 217 | +**hide-clear-button** | _Boolean_ | no | false |
| 218 | + |
| 219 | +## Contribution |
| 220 | + |
| 221 | +Please feel free to fork and help developing. |
| 222 | + |
| 223 | +```bash |
| 224 | +# install dependencies |
| 225 | +npm install |
| 226 | + |
| 227 | +# serve with hot reload at localhost:8080 |
| 228 | +npm run dev |
| 229 | +``` |
| 230 | + |
| 231 | +For detailed explanation on how things work, checkout the [webpack guide](http://vuejs-templates.github.io/webpack/) and [docs for vue-loader](http://vuejs.github.io/vue-loader). |
| 232 | + |
| 233 | +## License |
| 234 | + |
| 235 | +[MIT](http://opensource.org/licenses/MIT) |
0 commit comments