rome

2018-06-13 admin

rome是什么

什么是rome,Customizable date (and time) picker. Opt-in UI, no jQuery!

rome介绍、rome使用

help me on gittipflattr.png

Customizable date (and time) picker. Opt-in UI, no jQuery!

Rome wasn’t built in a day. Browser support includes every sane browser and IE7+.

Demo!

You can see a live demo here.

screenshot.png

Oh, rome synchronizes in real-time with inputs, never steals focus, and its CSS is entirely customizable!

<sub>Rome depends on moment. It doesn’t depend on jQuery or other weird frameworks, though.</sub>

Install

From npm or Bower.

bower install --save rome

Note that if you’re using the standalone version, the API is published under the rome global. If you’re using CJS, then you’ll have to require('rome').

Setup

You can use your own distribution of moment, using rome.standalone.js.

<script src='moment.js'></script>
<script src='rome.standalone.js'></script>

You could just use the bundled rome.js distribution, which comes with moment in it.

<script src='rome.js'></script>

If you need to do anything regarding internationalization, refer to moment for that. Ideally, make those changes before starting to create Rome calendar components.

API

The API in rome exposes a few properties.

rome.find(elem)

If a calendar is associated to the provided elem, then that calendar is returned, otherwise returns null. DOM elements can only have one associated calendar.

rome(elem, options={})

This method creates a calendar instance and associates it to the provided elem. This association can’t be undone even by .destroy()ing the rome instance, because it can be .restore()d later. Subsequent calls to rome(elem) will return the associated calendar, instead of creating a new one <sub>(see rome.find(elem))</sub>. Think of this as a “caching feature”.

Creating a calendar has a ton of options. These have reasonable defaults that are easy to adjust, too. The options are listed below.

Option Description
appendTo DOM element where the calendar will be appended to. Takes 'parent' as the parent element
autoClose When set to true, the calendar is auto-closed when picking a day _(or a time if time: true and date: false). A value of 'time' will only auto-close the calendar when a time is picked.
autoHideOnBlur Hides the calendar when focusing something other than the input field
autoHideOnClick Hides the calendar when clicking away
date The calendar shows days and allows you to navigate between months
dateValidator Function to validate that a given date is considered valid. Receives a native Date parameter.
dayFormat Format string used to display days on the calendar
initialValue Value used to initialize calendar. Takes string, Date, or moment
inputFormat Format string used for the input field as well as the results of rome
invalidate Ensures the date is valid when the field is blurred
strictParse Compares input strictly against inputFormat, and partial matches are discarded
max Disallow dates past max. Takes string, Date, or moment
min Disallow dates before min. Takes string, Date, or moment
monthFormat Format string used by the calendar to display months and their year
monthsInCalendar How many months get rendered in the calendar
required Is the field required or do you allow empty values?
styles CSS classes applied to elements on the calendar
time The calendar shows the current time and allows you to change it using a dropdown
timeFormat Format string used to display the time on the calendar
timeInterval Seconds between each option in the time dropdown
timeValidator Function to validate that a given time is considered valid. Receives a native Date parameter.
weekdayFormat Format used to display weekdays. Takes min (Mo), short (Mon), long (Monday), or an array with seven strings of your choosing.
weekStart Day considered the first of the week. Range: Sunday 0 - Saturday 6

Note that in the case of input fields, when initialValue isn’t provided the initial value is inferred from elem.value instead. In the case of inline calendars, new Date() will be used as a default if none is provided.

Inlining the Calendar

If you pass in an element other than an input tag, then this method behaves slightly differently. The difference is that appendTo becomes the provided elem, and the calendar won’t attach itself to an input element. The options listed below will be ignored.

  • autoHideOnBlur, because there is no input field that can be tracked for blur events
  • invalidate, because there is no input field to keep consistent with the calendar component
  • required, because you can easily do that on an input field
  • styles.positioned, because the calendar will be considered inlined

All of the other options still apply, and identical behavior should be expected.

Default Options

If you don’t set an option, the default will be used. You can look up the defaults here, or below.

{
  "appendTo": document.body,
  "autoClose": true,
  "autoHideOnBlur": true,
  "autoHideOnClick": true,
  "date": true,
  "dateValidator": Function.prototype,
  "dayFormat": "DD",
  "initialValue": null,
  "inputFormat": "YYYY-MM-DD HH:mm",
  "invalidate": true,
  "max": null,
  "min": null,
  "monthFormat": "MMMM YYYY",
  "monthsInCalendar": 1,
  "required": false,
  "strictParse": false,
  "styles": {
    "back": "rd-back",
    "container": "rd-container",
    "date": "rd-date",
    "dayBody": "rd-days-body",
    "dayBodyElem": "rd-day-body",
    "dayConcealed": "rd-day-concealed",
    "dayDisabled": "rd-day-disabled",
    "dayHead": "rd-days-head",
    "dayHeadElem": "rd-day-head",
    "dayRow": "rd-days-row",
    "dayTable": "rd-days",
    "month": "rd-month",
    "next": "rd-next",
    "positioned": "rd-container-attachment",
    "selectedDay": "rd-day-selected",
    "selectedTime": "rd-time-selected",
    "time": "rd-time",
    "timeList": "rd-time-list",
    "timeOption": "rd-time-option"
  },
  "time": true,
  "timeFormat": "HH:mm",
  "timeInterval": 1800,
  "timeValidator": Function.prototype,
  "weekdayFormat": "min",
  "weekStart": moment().weekday(0).day()
}

Rome API

When you create a calendar with rome(elem), you’ll get a cal instance back. This has a few API methods. Most of these methods return the calendar instance whenever possible, allowing for method chaining.

.show()

Shows the calendar. If associated with an input, the calendar gets absolutely position right below the input field.

.hide()

Hides the calendar.

.id

Auto-generated unique identifier assigned to this instance of Rome.

.container

The DOM element that contains the calendar.

.associated

The associated DOM element assigned to this calendar instance. This is the input field or parent element that you used to create the calendar.

.getDate()

Returns the current date, as defined by the calendar, in a native Date object. If required: false you’ll get null when the input field is empty.

.getDateString(format?)

Returns the current date, as defined by the calendar, using the provided options.inputFormat format string or a format of your choosing. If required: false you’ll get null when the input field is empty.

.getMoment()

Returns a copy of the moment object underlying the current date in the calendar. If required: false you’ll get null when the input field is empty.

.destroy()

Removes the calendar from the DOM and all of its associated DOM event listeners. The only responsive API method becomes the .restore method described below, the rest of the API becomes no-op methods. After emitting the destroyed event, all event listeners are removed from the instance.

.destroyed

Returns true when the calendar is in a destroyed state and false otherwise.

.restore(options?)

Restores the calendar, using the provided options (or the default options). The associated DOM element can’t be changed. The API methods are restored to their original functionality.

.options(options?)

If an options object is provided, it destroys the calendar and initializes it with the provided options. Effectively the same as calling .restore(options) immediately after calling .destroy().

If no options object is provided, a copy of the current options is returned.

.options.reset()

Resets the options to the factory defaults. Effectively the same as calling .options({}) while preserving the appendTo option.

.emitValues()

Emits all of the data events listed below. Mostly used internally, should be avoided in consumer-land.

.setValue(value)

Sets the current date to the provided value, but only if that value is valid according to the rules defined by the calendar. Takes string, Date, or moment. Mostly used internally, and it doesn’t emit any events.

.refresh()

Forces a refresh of the calendar. This method will redraw the month and update the dates that can be selected in accordance with dateValidator and timeValidator.

.back()

Steps the calendar display back by one month. Equivalent to clicking the ‘back’ button. Returns undefined.

.next()

Steps the calendar display forward by one month. Equivalent to clicking the ‘next’ button. Returns undefined.

Events

Rome calendars also provide a few events you can subscribe to. These events are published through an event emitter created using contra. These events are listed below.

Event Arguments Description
ready [options] The calendar has been .restored
destroyed [] The calendar has been .destroyed
data [value] The date may have been updated by the calendar. Value of .getDateString() is provided
year [year] The year may have been updated by the calendar. Value of moment.year() is provided
month [month] The month may have been updated by the calendar. Value of moment.month() is provided
day [day] The day may have been updated by the calendar. Value of moment.date() is provided
time [time] The time may have been updated by the calendar. Formatted time string is provided
show [] The calendar has been displayed
hide [] The calendar has been hidden
back [month] The calendar view has been moved back a month to the value moment.month()
next [month] The calendar view has been moved forward a month to the value moment.month()

Date and Time Validator

Please note that dateValidator and timeValidator both receive a native Date object as a parameter. These methods are expected to return undefined or true if the date is deemed valid, and false in case the date is invalid. If dateValidator returns false, the validation process will try to find a valid date near the desired date.

If dateValidator passes for a given date, the timeValidator will attempt to validate that date as well. If the time is invalid, the day will be probed for a valid time. This validation starts at the desired time, and grows in timeInterval increments. When the end of the day is reached, validation resumes at the start of the day instead of leaping to the next day.

rome.val

There are a few default validator factories provided by Rome to make your life easier.

These methods take a moment, a Date, a string that can be parsed into a moment using inputFormat, or a DOM element that Rome could use to look up another Rome instance.

If you passed in a DOM element, the validator will look up the associated Rome instance and validate using its value. The first time the validator is executed on any inline calendar, the 'data' event for that calendar will be hooked to refresh the related calendar.

For usage examples you can refer to the demos.

rome.val.afterEq(value)

Returns whether the date is after the provided value. The comparison uses >=, meaning it’s inclusive.

rome.val.after(value)

Returns whether the date is after the provided value. The comparison uses >, meaning it’s exclusive.

rome.val.beforeEq(value)

Returns whether the date is before the provided value. The comparison uses <=, meaning it’s inclusive.

rome.val.before(value)

Returns whether the date is before the provided value. The comparison uses <, meaning it’s exclusive.

rome.val.except(left, right)

Returns whether the date is any date except the provided value. You can provide a wide variety of input values. Keep in mind Date, string, moment, and the DOM element used to find another calendar are all valid input types.

Providing left only means “any date except this one”

If you use rome.val.except('2014-08-09'), then '2014-08-09' is invalid.

Providing left and right means “any date that’s not in this range”

If you use rome.val.except('2014-08-09', '2014-09-01'), then anything between '2014-08-09' and '2014-09-01' is invalid.

If left is an array, each element in the array is treated as the simple case described above

In this case, right is completely ignored. Every item in the array is treated as follows.

If the item is single, then a rule is built on that single date

Using rome.val.except(['2014-08-09', '2014-09-01']) means that '2014-08-09' and '2014-09-01' are both invalid dates.

If the item is an array, the first two items are used to determine a date range

Using rome.val.except([['2014-08-09', '2014-09-01']]) means anything between '2014-08-09' and '2014-09-01' is invalid.

These two types of entries can be combined in any way you like. Each entry will exclude additional dates.

For instance, [['2014-04-05', '2014-04-15'], ['2014-04-25', '2014-04-30'], '2014-05-05'] means that April 05 to 15, and April 25 to 30, along with May 05 are all invalid dates.

rome.val.only(left, right)

Identical behavior to rome.val.except, except for the fact that the selected dates become the only valid dates, rather than the only invalid dates.

rome.moment

Exposes the moment instance used by Rome. To change the moment instance, refer to rome.use(moment).

rome.use(moment)

Sets the instance of moment used by Rome.

Development

Start by installing any dependencies.

Then run the Gulp watch task.

Lastly open the page and any changes you make just need a browser refresh.

License

MIT

本站文章除注明转载外,均为本站原创或编译。欢迎任何形式的转载,但请务必注明出处。

转载请注明:文章转载自 JavaScript中文网 [https://www.javascriptcn.com]

本文地址:https://www.javascriptcn.com/read-33972.html

文章标题:rome

相关文章
Chrome扩展-获取DOM内容
brandonhilkert提出了一个问题:Chrome Extension - Get DOM content,或许与您遇到的问题类似。 回答者piperchestergkalpak给出了该问题的处理方式: The terms “back...
2018-03-23
了解Chrome扩展程序开发
首先,我尝试来用简单几句话描述一下Chrome扩展程序: Chrome扩展主要用于对浏览器功能的增强,它强调与浏览器相结合。比如Chrome扩展可以在浏览器的工具栏和地址栏中显示图标,它可以更改用户当前浏览的网页中的内容,也可以更改浏览...
2018-01-10
chrome 浏览器表情包斗图插件, code review 社区撕逼必备~
嗯,写个 chrome 斗图用的浏览器插件。 便于在 github、gitlab code review,与各个技术社区评论发表情包斗图用,可快速搜索生成表情包链接所需的表情链接。 github 地址 chrome 应用商店地址 最早想写...
2017-12-28
爬虫新姿势 - 使用Chrome Devtools写一个小说爬虫
目前,绝大部分的爬虫教程都是基于Python和Node.js。其实,只要有Chrome浏览器,使用Chrome F12打开的的Devtools就能随时随地轻轻松松写一个爬虫,完全不用装其它语言环境。今天就介绍一下只使用Chrome Devt...
2018-03-06
chrome扩展应用开发快速科普
概述 本文通过对chrome插件的各个部分进行快速的介绍,从而让大家了解插件各个部分的关系,并且知道如何将其进行组装成一个完整的chrome插件。 由于chrome官方文档中对于如何从零开发一个chrome扩展应用没有一套完整的流程,同时官...
2018-04-09
解决@vue/cli 创建项目是安装chromedriver时失败的问题
最近在使用新版vue的命令行工具创建项目时,安装chromedriver老是失败,导致后面的步骤也没有进行。网上搜索了一下,全是使用 npm install chromedriver --chromedriver_cdnurl=http:&...
2018-02-14
记一次解决谷歌浏览器Google Chrome Helper占用过高cpu问题
阅读原文 有时候发现mac风扇响的厉害,于是我检查了mac系统的活动监视器,发现Google Chrome Helper占用99%的CPU。 通常来说Chrome如果占用过高的内存,这并不是什么问题,毕竟Chrome的性能以及易用性是建立在...
2018-06-05
访问V8 JavaScript中的行号(Chrome和js)
james_womack提出了一个问题:Accessing line number in V8 JavaScript (Chrome &amp; Node.js),或许与您遇到的问题类似。 回答者james_womack给出了该问题的处理方...
2018-04-03
[译文]Chrome63中开发者面板(Devtools)新增功能
欢迎回来!Chrome 63中提供给DevTools的新功能包括: 支持了多客户端的远程调试功能 工作区(workspace)2.0 四个新的审计(audits)功能 使用自定义的数据模拟推送通知功能(push notif...
2018-01-12
Angular2 RxJS getting &apos;Observable_1.Observable.fromEvent is not a function&apos; error
Michael Oryl提出了一个问题:Angular2 RxJS getting ‘Observable_1.Observable.fromEvent is not a function’ error,或许与您遇到的问题类似。 回答者Co...
2018-04-10
回到顶部