# @bevacqua/rome 中文文档

规范地址：https://npmcn.com/package/%40bevacqua/rome/

版本：3\.0\.4
npm 元数据更新时间：2022-04-04T18:37:16.473Z
中文译文更新时间：2026-11-08T00:35:08.826Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bevacqua/rome
原文对照：https://npmcn.com/package/%40bevacqua/rome/?lang=original
项目主页：https://github.com/bevacqua/rome
源码仓库：https://github.com/bevacqua/rome

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：966 kB，45 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：4 个
- 首次发布：2019-03-21T00:57:00.097Z
- 最新版本发布：2021-07-13T11:56:20.816Z
- 近 30 天下载量：3174（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 0 个）

## 中文简介

定制日期(和时间)取取取器. Opt -in UI,没有j查询!

## 安装

```sh
npm install @bevacqua/rome
```

也可以使用：`pnpm add @bevacqua/rome`、`yarn add @bevacqua/rome`、`bun add @bevacqua/rome`

## README

# 罗马

[![help me on gittip](http://gbindex.ssokolow.com/img/gittip-43x20.png)](https://www.gittip.com/bevacqua/) [![flattr.png](https://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=nzgb&url=https%3A%2F%2Fgithub.com%2Fbevacqua%2Frome)

> 自定义日期 _(和时间)_ 拣取者. Opt -in UI,没有j查询!

罗马不是一天之内建成的. 浏览器支持包括每个正常浏览器和 **IE7 + 数据**。 。 。 .

#### 迪莫! 迪莫! 迪莫! Demo!

你们可以 [看这里的现场演示](https://bevacqua.github.io/rome)。 。 。 .

[![screenshot.png](https://cloud.githubusercontent.com/assets/934293/3803583/387125ea-1c1c-11e4-974e-467984e4d1f0.png)](https://bevacqua.github.io/rome)

瓳, `rome` 实时同步输入,从不盗取焦点,其CSS完全可自定义!

罗马取决于 [`moment`](http://momentjs.com/)它不依赖于jQuery或其他奇怪的框架,虽然.

## 安装

从npm或鲍尔.

```shell
npm install --save @bevacqua/rome
```

```shell
bower install --save @bevacqua/rome
```

请注意,如果使用独立版本,API则在下方发布 `rome` 全球。 如果你使用 CJS,那么你必须 `require('@bevacqua/rome')`。 。 。 .

### 设置

你可以使用自己的分布 [`moment`](http://momentjs.com/),使用 `rome.standalone.js`。 。 。 .

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

你可以用捆绑的 `rome.js` 分配,随同 [`moment`](http://momentjs.com/) 进去.

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

如果你需要做任何有关国际化的事, [参考 `moment` 因为](http://momentjs.com/docs/#/i18n/)理想的情况是,在开始创建罗马日历组件之前进行这些修改.

## API 密码

API 在 `rome` 暴露出一些属性.

### `rome.find(elem)`

如果日历与所提供的日历相关 `elem`,然后返回日历,否则返回 `null`. DOM 元素只能有一个相关的日历.

### `rome(elem, options={})`

这种方法创建日历实例并将其关联到提供的 `elem`这种联系即使通过 `.destroy()`旋转 `rome` 举例来说,因为它可以 `.restore()`d 后来。 随后发出的呼吁 `rome(elem)` 将返回相关的日历,而不是创建新的日历 _(见 `rome.find(elem)`(中文(简体) )_将它视为 _"捕捉特征"_。 。 。 .

创建日历有很多选项 。 这些有合理的缺省,也容易调整。 备选方案如下:.

| 选项 | 说明 |
| --- | --- |
| `appendTo` | 附加日历的 DOM 元素 。 带 `'parent'` 作为母元素 |
| `autoClose` | 设定为 `true`中,日历在选择日期时自动关闭 (如果 `time: true` 财务报告和审定财务报表 `date: false`) (中文(简体) ). 价值为 `'time'` 只会在选定时间时自动关闭日历. |
| `autoHideOnBlur` | 瞄准输入字段以外的内容时隐藏日历 |
| `autoHideOnClick` | 单击退出时隐藏日历 |
| `date` | 日历显示天数并允许您在月份之间导航 |
| `dateValidator` | 验证指定日期被视为有效的功能 。 接收本地文件 `Date` 参数. |
| `dayFormat` | 用于显示日历上天数的格式字符串 |
| `initialValue` | 用于初始化日历的值 。 带 `string`, (中文(简体) ), `Date`,或 `moment` |
| `inputFormat` | 输入字段所使用的格式字符串以及结果 `rome` |
| `invalidate` | 在字段模糊时确保日期有效 |
| `strictParse` | 严格对比输入 `inputFormat`,并丢弃部分匹配 |
| `max` | 取消日期过去 `max`选择 `string`, (中文(简体) ), `Date`,或 `moment` |
| `min` | 否认日期前 `min`选择 `string`, (中文(简体) ), `Date`,或 `moment` |
| `monthFormat` | 日历用于显示月份及其年份的格式字符串 |
| `monthsInCalendar` | 日历中要计算多少个月 |
| `required` | 需要字段还是允许空值 ? |
| `styles` | 适用于日历中元素的 CSS 类 |
| `time` | 日历显示当前时间并允许您使用下拉方式更改 |
| `timeFormat` | 用于显示日历上时间的格式字符串 |
| `timeInterval` | 时间倒计时中每个选项之间的秒数 |
| `timeValidator` | 用于验证特定时间被视为有效的功能 。 接收本地文件 `Date` 参数. |
| `weekdayFormat` | 用于显示工作日的格式 。 带 `min` _(莫语)_, (中文(简体) ), `short` _(月语)_, (中文(简体) ), `long` _(星期一) (中文(简体) )_,或由您选择的七个字符串组成的数组. |
| `weekStart` | 日考虑周一. 范围:星期日 `0` - 礼拜六 `6` |

注意,对于输入字段,何时 `initialValue` 不提供初始值从 `elem.value` 换句话说 就内含历法而言, `new Date()` 如果没有提供,将用作默认.

#### 内嵌日历

如果在输入标记以外的元素中通过,则这种方法的行为略有不同. 区别在于 `appendTo` 成为所提供的 `elem`,而日历不会附加输入元素。 以下选项将被忽略 .

-   `autoHideOnBlur`,因为没有可以跟踪到 `blur` 事件
-   `invalidate`,因为没有输入字段可以与日历组件保持一致
-   `required`,因为您可以在输入字段中轻松做到
-   `styles.positioned`,因为日历将被视为内含

所有其他选择方案仍然适用,应该期待有相同的行为.

#### 默认选项

如果不设置选项,则使用默认值. 你们可以 [查找这里的默认值](https://github.com/bevacqua/rome/blob/master/src/defaults.js),或以下.

```json
{
  "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()
}
```

#### 罗马 API

当您创建日历时 `rome(elem)`你会得到一个 `cal` 倒计时。 这有几种API方法. 这些方法大多尽可能地返回日历实例,允许方法链.

##### `.show()`

显示日历 。 如果与输入相关,日历在输入字段下方获得绝对位置.

##### `.hide()`

隐藏日历 .

##### `.id`

自动生成的独特标识符 指定给这个罗马的例子.

##### `.container`

包含日历的 DOM 元素 .

##### `.associated`

分配给此日历实例的相关 DOM 元素 。 这是您用来创建日历的输入字段或父元素 .

##### `.getDate()`

返回本地日历中定义的当前日期 `Date` 对象。 若为 `required: false` 你会得到 `null` 当输入字段为空时.

##### `.getDateString(format?)`

使用提供的日历返回当前日期 `options.inputFormat` 格式字符串或选择的格式。 若为 `required: false` 你会得到 `null` 当输入字段为空时.

##### `.getMoment()`

返回副本 `moment` 以日历中当前日期为基础的对象。 若为 `required: false` 你会得到 `null` 当输入字段为空时.

##### `.destroy()`

从 DOM 及其所有相关的 DOM 事件听众中删除日历 。 唯一的响应性API方法变成 `.restore` 下文所述方法,API的其余部分成为无操作方法。 排放之后 `destroyed` 事件,所有事件听众都会从实例中删除.

##### `.destroyed`

回返 `true` 当历法被毁灭的时候 `false` 否则.

##### `.restore(options?)`

使用提供的选项(或默认选项)恢复日历。 相关的 DOM 元素不能被更改. API方法被恢复到原来的功能.

##### `.options(options?)`

如果提供了选项对象,它会破坏日历并用提供的选项初始化. 和打电话一样 `.restore(options)` 打电话后立即 `.destroy()`。 。 。 .

如果没有提供选项对象,则返回当前选项的副本.

##### `.options.reset()`

将选项重置到工厂默认值 。 和打电话一样 `.options({})` 在保留 `appendTo` 选项.

##### `.emitValues()`

表示以下列出的所有数据事件. 主要是内部使用, **应避免** 在消费地.

##### `.setValue(value)`

将当前日期设定为已提供 `value`,但只有在该值根据日历所定义的规则有效时。 带 `string`, (中文(简体) ), `Date`,或 `moment`. . 大部分在内部使用,它不会放出任何事件.

##### `.refresh()`

强制更新日历 。 这种方法将重新绘制月份并更新根据 `dateValidator` 财务报告和审定财务报表 `timeValidator`。 。 。 .

##### `.back()`

将日历显示返回一个月 。 等同点击后键 . 回返 `undefined`。 。 。 .

##### `.next()`

将日历显示提前一个月。 等同点击"next" 按钮 . 回返 `undefined`。 。 。 .

#### 活动

罗马日历还提供了一些您可以订阅的事件. 这些事件通过使用 [`contra`](https://github.com/bevacqua/contra)兹将这些事件列举如下.

| 活动 | 参数 | 说明 |
| --- | --- | --- |
| `ready` | `[options]` | 日历已经 `.restore`d. 国家 |
| `destroyed` | `[]` | 日历已经 `.destroy`编 |
| `data` | `[value]` | 该日期可能已经由日历更新. 价值 `.getDateString()` 提供 |
| `year` | `[year]` | 该年可能已经由日历更新. 价值 `moment.year()` 提供 |
| `month` | `[month]` | 该月可能已经由日历更新. 价值 `moment.month()` 提供 |
| `day` | `[day]` | 这一天可能已经由日历更新。 价值 `moment.date()` 提供 |
| `time` | `[time]` | 时间可能已经由日历更新. 提供了格式化的时间字符串 |
| `show` | `[]` | 日历已显示 |
| `hide` | `[]` | 日历已被隐藏 |
| `back` | `[month]` | 日历视图已移回一个月的值 `moment.month()` |
| `next` | `[month]` | 日历视图已移动一个月到数值 `moment.month()` |

#### 日期和时间验证器

请注意: `dateValidator` 财务报告和审定财务报表 `timeValidator` 两人都接受本地人 `Date` 对象作为参数。 预计这些方法将会回归 `undefined` 或者说 `true` 如果该日期被认为有效,以及 `false` 如果日期无效。 若为 `dateValidator` 返回时 `false`,验证过程将试图在理想日期附近找到一个有效日期.

若为 `dateValidator` 特定日期的通行证 `timeValidator` 将试图验证这一日期。 如果时间无效,将在有效时间内对当天进行探测. 此验证从预期时间开始, 并在 `timeInterval` 递增。 日终到来后,从正月初开始恢复验证,而不再跳至次日.

### `rome.val`

罗马提供了几家默认验证工厂 来方便你的生活.

这些方法需要 `moment`页:1 `Date`页:1 `string` 可解为 `moment` 使用 `inputFormat`或者一个DOM元素,罗马可以用来寻找另一个罗马的例子.

如果您以 DOM 元素通过, 校验器会查看相关的罗马实例, 并使用它的值进行校验 。 任何内嵌日历上首次执行验证符时 `'data'` 选中该日历的事件以刷新相关的日历.

对于用法示例 [参考演示](https://bevacqua.github.io/rome)。 。 。 .

#### `rome.val.afterEq(value)`

返回日期是否在所提供值之后。 比较使用 `>=`意思是它包含一切.

#### `rome.val.after(value)`

返回日期是否在所提供值之后。 比较使用 `>`意思是它是独家的.

#### `rome.val.beforeEq(value)`

返回提供值之前的日期。 比较使用 `<=`意思是它包含一切.

#### `rome.val.before(value)`

返回提供值之前的日期。 比较使用 `<`意思是它是独家的.

#### `rome.val.except(left, right)`

返回日期是否是除提供值以外的任何日期。 你可以提供各种各样的输入值. 记住 `Date`, (中文(简体) ), `string`, (中文(简体) ), `moment`,用于找到另一个日历的 DOM 元素都是有效的输入类型.

##### 提供 `left` 仅指 **"除了这个之外的任何日期"**

如果您使用 `rome.val.except('2014-08-09')`,则 `'2014-08-09'` 无效.

##### 提供 `left` 财务报告和审定财务报表 `right` 表示 **"任何没有在这个范围内的日期"**

如果您使用 `rome.val.except('2014-08-09', '2014-09-01')`,然后在 `'2014-08-09'` 财务报告和审定财务报表 `'2014-09-01'` 无效.

##### 若为 `left` 是数组, 数组中的每个元素都被当作上述简单例处理

在这种情况下, `right` 完全被忽视。 阵列中的每个项目按以下处理.

###### 如果项目是单一的,那么一个规则就建立在单一的日期上

使用 `rome.val.except(['2014-08-09', '2014-09-01'])` 意思是说 `'2014-08-09'` 财务报告和审定财务报表 `'2014-09-01'` 均为无效日期.

###### 如果项目为数组,则使用前两个项目来确定日期范围

使用 `rome.val.except([['2014-08-09', '2014-09-01']])` 意指任何之间 `'2014-08-09'` 财务报告和审定财务报表 `'2014-09-01'` 无效.

这两类条目可以任意方式合并. 每个条目将排除额外日期.

比如说, `[['2014-04-05', '2014-04-15'], ['2014-04-25', '2014-04-30'], '2014-05-05']` 指4月05至15日,4月25至30日,与5月05日一起均为无效日期.

#### `rome.val.only(left, right)`

行为相同 `rome.val.except`,但选定日期改为 **唯一有效日期**,而不是 **只有无效的日期**。 。 。 .

### `rome.moment`

显示 [`moment`](http://momentjs.com/) 罗马使用的例子。 改变 `moment` 例如,提及 `rome.use(moment)`。 。 。 .

### `rome.use(moment)`

设置实例 `moment` 由罗马使用.

## 发展

从安装任何依赖开始 .

```shell
npm install
```

然后运行Gulp `watch` 任务.

```shell
gulp watch
```

最后打开页面和您所做的任何更改只需要浏览器刷新即可.

```shell
open index.html
```

## 许可证

麻省理工学院

## 常见问题

### @bevacqua/rome 是什么？

定制日期\(和时间\)取取取器\. Opt -in UI,没有j查询\!

### 如何安装 @bevacqua/rome？

在项目目录运行 npm install @bevacqua/rome，或使用 pnpm add / yarn add / bun add。

### @bevacqua/rome 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bevacqua\_\_rome 是否存在。

### @bevacqua/rome 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bevacqua/rome 可以商用吗？

@bevacqua/rome 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bevacqua/rome 的下载量有多少？

根据 npm 官方下载统计，@bevacqua/rome 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,174 次，日均约 106 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bevacqua/rome 还在维护吗？

最新版本 3\.0\.4 发布于 2021/07/13（5 年前）；至今共发布 4 个版本，其中过去 12 个月发布了 0 个；首次发布于 2019/03/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。