# 通用库使用手册
## `base.js`
### `addStorageField`
```javascript
addStorageField(storage_id, selector, display_name, placeholder, filter = (x) => x)
```
将页面中元素与 `localStorage` 中的一个键值绑定。绑定的元素内容将与 `localStorage` 中对应的值同步，并为这些元素增加点击事件，引导用户改变该项的值。
- `storage_id: string` 必需，指定 `localStorage` 中存储的键值。
- `selector: string` 必需，指定要绑定的元素 CSS 选择器。元素将通过 `document.querySelectorAll(selector)` 方法获取。
- `display_name: string` 必需，显示在弹出提示框中的标题上（“修改 xxx：”）。
- `placeholder: string` 必需，`localStorage` 中的值未设定时的默认值。
- `filter: function`：可选，过滤器函数。接收 `localStorage` 中的值为参数，元素的 `innerHTML` 将设置为过滤器返回的内容。默认为 `(x) => x`。
`presetFilters` 提供了一些预设过滤器，如：`presetFilters.name`, `presetFilters.idcard(head = 2, tail = 2, mask = 18 - head - tail)`。
#### 示例
身份证号，只显示前三位和后三位：
```javascript
addStorageField("_idcard", "#idcard", "身份证号", "110101195306153019", presetFilters.idcard(3, 3))
```
### `initServiceWorker`
```javascript
initServiceWorker(project_name)
```
初始化 Service Worker，用于预加载内容以供离线使用。
- `project_name: string | Array`：必需，一个或多个项目名称，需与项目在 `src/` 中的路径名相同。例如 `"ykm"`，`["ykm", "skm", "trip-card"]`。
### `setDynamicTime`
```javascript
setDynamicTime(selector, start = 0, end = 19)
```
设置页面中动态更新的时间，指定元素的内容将定期与最新系统时间同步。格式为 `YYYY-MM-DD HH:mm:ss.SSSZ`，将通过提供的 `start` 及 `end` 截取此字符串。默认更新时间为 `1000ms`，可通过 `setUpdateInterval` 调整。
- `selector: string` 必需，指定要绑定的元素 CSS 选择器。元素将通过 `document.querySelectorAll(selector)` 方法获取。
- `start: number` 可选，字符串起始下标，默认为 0。
- `end: number` 可选，字符串截止下标，默认为 19。
### `setStaticTime`
```javascript
setStaticTime(selector, start = 0, end = 19, traceback_hours = 0, traceback_range = 0, filter = (x) => x)
```
设置页面中元素的内容为向前推算的静态时间。格式为 `YYYY-MM-DD HH:mm:ss.SSSZ`，将通过提供的 `start` 及 `end` 截取此字符串。
- `selector: string` 必需，指定要绑定的元素 CSS 选择器。元素将通过 `document.querySelectorAll(selector)` 方法获取。
- `start: number` 可选，字符串起始下标，默认为 0。
- `end: number` 可选，字符串截止下标，默认为 19。
- `traceback_hours: number` 可选，向前推算的小时数，默认为 0。
- `traceback_range: number` 可选，向前推算的随机波动范围小时数，默认为 0。
- `filter: function`：可选，过滤器函数。接收生成的字符串为参数，元素的 `innerHTML` 将设置为过滤器返回的内容。默认为 `(x) => x`。
最终生成的小时数范围为 `(now - traceback_hours - traceback_range / 2, now - traceback_hours + traceback_range / 2)`。
如果 HTML 标签上指定了 `data-traceback-time` 及 `data-traceback-range`，将依照标签属性的值设定这两项的值。
## `nav.css`
`nav.css` 提供了模拟小程序及应用内浏览器导航栏 UI 的样式，由 `nav.scss` 编译而来。引入 `nav.css` 后，还需在 `html` 文件中加入下面的 HTML。
### `navbar` —— 导航栏
`navbar--wechat`
微信小程序白色导航栏
```html
```
`navbar--wechat-alternative`
微信小程序透明背景或深色背景导航栏
```html
```
`navbar--wechat-browser`
微信应用内浏览器导航栏
```html
```
`navbar--alipay`
支付宝小程序白色导航栏
```html
```
`navbar--alipay-alternative`
支付宝小程序透明背景或深色背景导航栏
```html
```
### `capsule` —— 小程序右上角“胶囊”按钮
`capsule--wechat` 微信小程序右上角按钮：
```html
```
`capsule--alipay`
支付宝小程序右上角按钮
```html
```
`capsule--alternative`
透明背景或深色背景右上角按钮，可与 `capsule--wechat` 和 `capsule--alipay` 搭配。
```html
...
...
```