@fredwsw/frontend-rules 1.0.0

package/template/docs/uv-ui-docs/button-cn.md

@@ -0,0 +1,181 @@
+---
+group: 基础
+category: Components
+title: Button
+subtitle: 按钮
+description: 基于 uni-app button 二次封装，扩展更多主题色与尺寸能力。
+cover: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*BD2JSKm8I-kAAAAAAAAAAAAADrJ8AQ/original
+coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*r29rQ51bNdwAAAAAAAAAAAAADrJ8AQ/original
+demo:
+  cols: 2
+---
+
+## 何时使用 {#when-to-use}
+
+按钮用于触发一个操作（提交、确认、取消、跳转等）。`uv-button` 基于 uni-app 的 `button` 组件二次封装，主要扩展点：
+
+- `type`：提供更多主题色
+- `size`：提供更多尺寸选项
+
+> 完整示例下载地址：[uv-ui 插件市场](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+## 平台兼容性 {#platform}
+
+| App（vue） | App（nvue） | H5 | 小程序 | VUE2 | VUE3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | √ | √ | √ | √ | √ |
+
+**组件名：** `uv-button`
+
+## 注意事项 {#notice}
+
+- 本组件扩展了更多能力，部分属性与官方 `button` 完全一致。更详细开放能力说明参考 uni-app 文档：[uni-app button 组件](https://uniapp.dcloud.net.cn/component/button.html)
+- 受微信小程序限制，微信小程序中设置了 `form-type` 的 `uv-button` **无法触发** `form` 组件的 `@submit`（H5 和 App 正常）
+- 如需给 `uv-button` 设置宽度，建议外层包一层 `view` 控制宽度，或使用 `customStyle`
+- 微信小程序下直接写 class/内联样式可能受编译结构影响，推荐用 `customStyle`（对象，驼峰命名）传入
+
+## 代码演示 {#examples}
+
+### 基本使用 {#basic}
+
+文字建议通过 `text` 传入。
+
+```vue
+<uv-button text="月落"></uv-button>
+```
+
+### 多种形态 {#variants}
+
+- `type`：default / primary / success / info / warning / error
+- `plain`：镂空
+- `hairline`：细边
+- `disabled`：禁用
+- `loading` + `loadingText`：加载态
+- `icon`：图标按钮（配合 uv-icon）
+- `shape`：square / circle
+- `color`：支持 `linear-gradient(...)` 渐变
+- `size`：normal / large / mini（以及组件扩展的更多值）
+
+```vue
+<template>
+  <view style="padding: 20px;">
+    <uv-button type="primary" text="确定"></uv-button>
+    <uv-button type="primary" :plain="true" text="镂空"></uv-button>
+    <uv-button type="primary" :plain="true" :hairline="true" text="细边"></uv-button>
+    <uv-button type="primary" :disabled="disabled" text="禁用"></uv-button>
+    <uv-button type="primary" loading loadingText="加载中"></uv-button>
+    <uv-button type="primary" icon="map" text="图标按钮"></uv-button>
+    <uv-button type="primary" shape="circle" text="按钮形状"></uv-button>
+    <uv-button text="渐变色按钮" color="linear-gradient(to right, rgb(66, 83, 216), rgb(213, 51, 186))"></uv-button>
+    <uv-button type="primary" size="small" text="大小尺寸"></uv-button>
+  </view>
+</template>
+<script>
+export default {
+  data() {
+    return { disabled: true }
+  }
+}
+</script>
+```
+
+### 使用 customStyle 定义外部样式 {#custom-style}
+
+非微信小程序平台根元素就是原生 `button`，样式改动相对容易；微信小程序因编译结构导致样式传递可能不稳定，推荐使用 `customStyle`（对象、驼峰命名）传入。
+
+注意：nvue 中圆角等部分样式需要使用连字符写法（示例已包含）。
+
+```vue
+<template>
+  <view>
+    <uv-button :custom-style="customStyle" color="#fff" text="雪月夜"></uv-button>
+  </view>
+</template>
+<script>
+export default {
+  computed: {
+    customStyle() {
+      return {
+        height: '80rpx',
+        background: '#3c9cff',
+        color: '#fff',
+        borderRadius: '40rpx',
+        'border-top-right-radius': '40rpx',
+        'border-bottom-left-radius': '40rpx',
+        'border-bottom-right-radius': '40rpx'
+      }
+    }
+  }
+}
+</script>
+```
+
+## API {#api}
+
+### Button Props {#props}
+
+| 属性名 | 类型 | 默认值 | 说明 | 可选值 |
+| --- | --- | --- | --- | --- |
+| hairline | Boolean | true | 是否显示细边框 | true \| false |
+| type | String | info | 按钮样式类型 | info \| primary \| error \| warning \| success |
+| size | String | normal | 按钮大小 | normal \| large \| mini |
+| shape | String | square | 外观形状 | square \| circle |
+| plain | Boolean | false | 是否镂空 | true \| false |
+| disabled | Boolean | false | 是否禁用 | true \| false |
+| loading | Boolean | false | 是否显示 loading 图标 | true \| false |
+| loadingText | String | - | 加载中文字 | - |
+| loadingMode | String | spinner | loading 图标类型 | 参考 LoadingIcon 模式 |
+| loadingSize | String \| Number | 15 | loading 图标大小 | - |
+| openType | String | - | 开放能力（同 uni-app button） | - |
+| formType | String | - | 用于 form 的 submit/reset（同 uni-app button） | - |
+| appParameter | String | - | open-type=launchApp 时向 App 传参（微信/QQ） | - |
+| hoverStopPropagation | Boolean | true | 是否阻止祖先节点出现点击态（微信） | true \| false |
+| lang | String | en | 返回用户信息语言 | zh_CN \| zh_TW \| en |
+| sessionFrom | String | - | 会话来源（openType=contact） | - |
+| sendMessageTitle | String | - | 会话消息卡片标题（openType=contact） | - |
+| sendMessagePath | String | - | 会话消息卡片跳转路径（openType=contact） | - |
+| sendMessageImg | String | - | 会话消息卡片图片（openType=contact） | - |
+| showMessageCard | String | - | 是否显示会话消息卡片（openType=contact） | - |
+| dataName | String | - | 小程序 data-xxx 额外参数，通过 `target.dataset.name` 取 | - |
+| throttleTime | String \| Number | 0 | 节流时间（ms） | - |
+| hoverStartTime | String \| Number | 0 | 按住多久出现点击态（ms） | - |
+| hoverStayTime | String \| Number | 200 | 松开后点击态保留（ms） | - |
+| text | String \| Number | - | 按钮文字（建议优先用 text，便于统一样式；nvue 下 slot 不易控样式） | - |
+| icon | String | - | 按钮图标 | - |
+| iconSize | String \| Number | - | 按钮图标大小（1.0.9） | - |
+| iconColor | String | - | 图标颜色：plain=true 时与边框一致，否则默认白色（info 主题为黑色） | - |
+| color | String | - | 按钮颜色，支持 `linear-gradient` | - |
+| customTextStyle | Object \| String | - | 自定义文字样式（避免 customStyle 覆盖不到） | - |
+| customStyle | Object \| String | - | 自定义外部样式（推荐对象驼峰命名） | - |
+
+### Button Events {#events}
+
+说明：在 H5、App 可以直接监听 `tap` 等同 click，但部分 HBuilder X 版本微信小程序对组件 `@tap` 可能无效，建议统一使用组件内部 `@click`。
+
+| 事件名 | 说明 | 回调参数 | 平台差异说明 |
+| --- | --- | --- | --- |
+| @click | 按钮点击（请勿使用 @tap，微信小程序可能无效） | 点击事件对象及参数 | - |
+| @getphonenumber | 获取用户手机号（open-type=getPhoneNumber） | - | 微信/支付宝/百度/抖音/快手/京东 |
+| @getuserinfo | 获取用户信息（open-type=getUserInfo） | - | 微信/QQ/百度/快手/京东 |
+| @error | 开放能力错误回调（open-type=launchApp） | - | 微信/QQ/快手/京东 |
+| @opensetting | 从小程序打开 App 成功（open-type=launchApp） | - | 微信/QQ/百度/快手/京东 |
+| @launchapp | 打开 App 成功（open-type=launchApp） | - | 微信/QQ/快手/京东 |
+| @contact | 客服消息回调（open-type=contact） | - | 微信/QQ/百度/快手 |
+| @chooseavatar | 获取用户头像（open-type=chooseAvatar） | - | 微信小程序 |
+| @agreeprivacyauthorization | 同意隐私协议（open-type=agreePrivacyAuthorization） | - | 微信小程序 2.33.0 |
+| @addgroupapp | 添加群应用（open-type=addGroupApp） | - | QQ 小程序 |
+| @chooseaddress | 选择收货地址（open-type=chooseAddress） | - | 百度小程序 |
+| @chooseinvoicetitle | 选择发票抬头（open-type=chooseInvoiceTitle） | - | 百度小程序 |
+| @subscribe | 订阅消息授权（open-type=subscribe） | - | 百度小程序 |
+| @login | 登录回调（open-type=login） | - | 百度小程序 |
+| @im | 跳转 IM 成功回调（open-type=im） | - | 抖音小程序 2.68.0+ |
+
+关于 `open-type` 的设置与回调详情，参考 uni-app 官方 button 文档。
+
+### Button Slots {#slots}
+
+| 名称 | 说明 |
+| --- | --- |
+| default | 默认插槽（按钮文本）；建议统一使用 `text` 参数以保证样式一致 |
+| suffix | 后置插槽，方便在按钮文字后追加图标等内容 |
+

package/template/docs/uv-ui-docs/calendar-cn.md

@@ -0,0 +1,179 @@
+---
+group: 表单
+category: Components
+title: Calendar
+subtitle: 日历
+description: 用于单选日期、多选日期、范围选择等，包裹在底部弹起容器中。
+demo:
+  cols: 2
+---
+
+## 何时使用 {#when-to-use}
+
+`uv-calendar` 用于专业的日期选择场景，如入住离店等。与 Picker 的日期模式有重合，但本组件支持范围选择，Picker 可配置时分秒等，按需选择。
+
+> 完整示例下载地址：[uv-ui 插件市场](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+## 平台兼容性 {#platform}
+
+| App（vue） | App（nvue） | H5 | 小程序 | VUE2 | VUE3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | √ | √ | √ | √ | √ |
+
+**组件名：** `uv-calendar`
+
+## 代码演示 {#examples}
+
+### 基本使用 {#basic}
+
+通过 ref 调用 `open()` 和 `close()` 控制打开/关闭，通过 `mode` 指定单选/多选/范围。
+
+```vue
+<template>
+  <view>
+    <uv-calendar ref="calendar" @confirm="confirm"></uv-calendar>
+    <button @click="open">打开</button>
+  </view>
+</template>
+<script>
+export default {
+  methods: {
+    open() {
+      this.$refs.calendar.open()
+    },
+    confirm(e) {
+      console.log('日历选择：', e)
+    }
+  }
+}
+</script>
+```
+
+### 单个日期 {#single}
+
+`mode="single"`，返回数组如 `["2021-07-01"]`。
+
+```vue
+<uv-calendar ref="calendar" mode="single" @confirm="confirm"></uv-calendar>
+```
+
+### 多个日期 {#multiple}
+
+`mode="multiple"`，返回数组如 `["2021-07-27", "2021-07-29", "2021-07-30"]`。
+
+```vue
+<uv-calendar ref="calendar" mode="multiple" @confirm="confirm"></uv-calendar>
+```
+
+### 日期范围 {#range}
+
+`mode="range"`，返回范围内所有日期数组，如入住离店。
+
+```vue
+<uv-calendar ref="calendar" mode="range" @confirm="confirm"></uv-calendar>
+```
+
+### 自定义主题色 {#color}
+
+```vue
+<uv-calendar ref="calendar" mode="range" color="#f56c6c" @confirm="confirm"></uv-calendar>
+```
+
+### 自定义文案 {#formatter}
+
+通过 `setFormatter` 设置日期文案（bottomInfo、disabled 等）。在 `onReady` 中调用。
+
+```vue
+<template>
+  <uv-calendar
+    ref="calendar"
+    mode="range"
+    startText="住店"
+    endText="离店"
+    confirmDisabledText="请选择离店日期"
+  ></uv-calendar>
+</template>
+<script>
+export default {
+  onReady() {
+    this.$refs.calendar.setFormatter(this.formatter)
+  },
+  methods: {
+    formatter(day) {
+      const d = new Date()
+      const month = d.getMonth() + 1
+      const date = d.getDate()
+      if (day.month == month && day.day == date + 3) {
+        day.bottomInfo = '打8折'
+        day.dot = true
+        day.disabled = true
+      }
+      return day
+    }
+  }
+}
+</script>
+```
+
+### 日期最大范围 {#max-date}
+
+```vue
+<uv-calendar ref="calendar" :maxDate="maxDate" @confirm="confirm"></uv-calendar>
+```
+
+### 显示农历 {#lunar}
+
+```vue
+<uv-calendar ref="calendar" showLunar @confirm="confirm"></uv-calendar>
+```
+
+### 默认日期 {#default-date}
+
+```vue
+<uv-calendar ref="calendar" mode="multiple" :defaultDate="defaultDateMultiple" @confirm="confirm"></uv-calendar>
+```
+
+## API {#api}
+
+### Calendar Props {#props}
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| title | 标题 | String | 日期选择 |
+| showTitle | 是否显示标题 | Boolean | true |
+| showSubtitle | 是否显示副标题 | Boolean | true |
+| mode | 日期类型 | String | single |
+| startText | range 时第一个日期底部文案 | String | 开始 |
+| endText | range 时最后一个日期底部文案 | String | 结束 |
+| color | 主题色 | String | #3c9cff |
+| minDate | 最小可选日期 | Number \| String | 0 |
+| maxDate | 最大可选日期 | Number \| String | 0 |
+| defaultDate | 默认选中日期 | Array \| String \| Date | null |
+| maxCount | multiple 时最多可选数量 | Number \| String | - |
+| rowHeight | 日期行高 | Number \| String | 56 |
+| showLunar | 是否显示农历 | Boolean | false |
+| showMark | 是否显示月份背景色 | Boolean | true |
+| confirmText | 确定按钮文字 | String | 确定 |
+| confirmDisabledText | 禁用时确定按钮文字 | String | 确定 |
+| closeOnClickOverlay | 点击遮罩是否关闭 | Boolean | false |
+| closeOnClickConfirm | 点击确认是否关闭 | Boolean | true |
+| readonly | 只读 | Boolean | false |
+| maxRange | range 时最多可选天数 | Number \| String | - |
+| round | 圆角 | String \| Number | 0 |
+| monthNum | 最大展示月份数 | String \| Number | 3 |
+
+### Calendar Methods {#methods}
+
+| 方法名 | 说明 |
+| --- | --- |
+| open | 弹出日历 |
+| close | 关闭日历 |
+| setFormatter | 日期格式化函数 |
+
+### Calendar Events {#events}
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| @confirm | 日期选择完成后 | 选择日期相关参数 |
+| @close | 日历关闭时 | - |
+| @change | 点击日期时 | { day, selected } |

package/template/docs/uv-ui-docs/calendars-cn.md

@@ -0,0 +1,264 @@
+---
+group: 表单
+category: Components
+title: Calendars
+subtitle: 新版日历（推荐）
+description: 查看日期、选择单个/多个或任意范围日期，支持打点、自定义文案与主题。
+cover: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*BD2JSKm8I-kAAAAAAAAAAAAADrJ8AQ/original
+coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*r29rQ51bNdwAAAAAAAAAAAAADrJ8AQ/original
+demo:
+  cols: 2
+---
+
+## 何时使用 {#when-to-use}
+
+新版日历组件 uv-calendars 用于解决老版本 uv-calendar 的性能问题，特别是日期选择范围受限、体验不佳等缺点。
+
+- 查看日期、选择单个、多个或任意范围日期
+- 打点、自定义文案、自定义主题
+- 插入页面或弹窗展示
+
+**常用场景：** 酒店日期预订、火车/机票选择、上下班打卡等。
+
+> 完整示例下载地址：[uv-ui 插件市场](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+## 平台兼容性 {#platform}
+
+| App（vue） | App（nvue） | H5 | 小程序 | VUE2 | VUE3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | √ | √ | √ | √ | √ |
+
+**组件名：** `uv-calendars`
+
+## 注意事项 {#notice}
+
+- 农历转换使用 `@1900-2100区间内的公历、农历互转` 方案
+- `date` 属性需传入 **String**，如 `2023-08-03`，不要传 `new Date()`
+- 通过 `insert` 区分事件：弹窗模式用 `@confirm`，插入模式用 `@change`
+- 弹窗模式下无法阻止后面元素滚动，需在弹窗打开后手动禁止滚动穿透（可参考 uv-popup 等组件）
+
+## 代码演示 {#examples}
+
+### 基本使用 {#basic}
+
+通过 ref 调用 `open()` 打开日历（弹窗模式）。
+
+```vue
+<template>
+  <view>
+    <uv-calendars ref="calendars" @confirm="confirm" />
+    <button @click="open">打开日历</button>
+  </view>
+</template>
+<script>
+export default {
+  methods: {
+    open() {
+      this.$refs.calendars.open()
+    },
+    confirm(e) {
+      console.log(e)
+    }
+  }
+}
+</script>
+```
+
+### 插入模式 {#insert}
+
+设置 `insert` 为 `true`，日历直接嵌入页面，不通过弹窗展示。此时使用 `@change` 而非 `@confirm`。
+
+```vue
+<template>
+  <view>
+    <uv-calendars insert @change="change" />
+  </view>
+</template>
+<script>
+export default {
+  methods: {
+    change(e) {
+      console.log(e)
+    }
+  }
+}
+</script>
+```
+
+### 多日期模式 {#multiple}
+
+设置 `mode="multiple"`。默认值可通过 `date` 设置，如 `['2023-08-26','2023-08-27','2023-08-28']`。
+
+```vue
+<template>
+  <view>
+    <uv-calendars ref="calendars" mode="multiple" @confirm="confirm" />
+    <button @click="open">打开日历</button>
+  </view>
+</template>
+<script>
+export default {
+  methods: {
+    open() {
+      this.$refs.calendars.open()
+    },
+    confirm(e) {
+      console.log(e)
+    }
+  }
+}
+</script>
+```
+
+### 日期范围模式 {#range}
+
+设置 `mode="range"`。默认值可通过 `date` 设置，如 `['2023-08-26','2023-08-29']`。
+
+```vue
+<template>
+  <view>
+    <uv-calendars ref="calendars" mode="range" @confirm="confirm" />
+    <button @click="open">打开日历</button>
+  </view>
+</template>
+<script>
+export default {
+  methods: {
+    open() {
+      this.$refs.calendars.open()
+    },
+    confirm(e) {
+      console.log(e)
+    }
+  }
+}
+</script>
+```
+
+### 自定义主题颜色 {#color}
+
+通过 `color` 设置主题色，建议使用 16 进制，如 `#ff0000`。
+
+```vue
+<template>
+  <view>
+    <uv-calendars
+      ref="calendars"
+      mode="range"
+      color="#ff0000"
+      :date="['2023-08-08','2023-08-27']"
+      @confirm="confirm"
+    />
+    <button @click="open">打开日历</button>
+  </view>
+</template>
+<script>
+export default {
+  methods: {
+    open() {
+      this.$refs.calendars.open()
+    },
+    confirm(e) {
+      console.log(e)
+    }
+  }
+}
+</script>
+```
+
+### 自定义文案（打点） {#selected}
+
+通过 `selected` 配置打点，格式为对象数组，详见 Selected Options。
+
+```vue
+<template>
+  <view>
+    <uv-calendars
+      ref="calendars"
+      mode="range"
+      title="选择日期"
+      start-text="住店"
+      end-text="离店"
+      :selected="selected"
+      @confirm="confirm"
+    />
+    <button @click="open">打开日历</button>
+  </view>
+</template>
+<script>
+export default {
+  data() {
+    const d = new Date()
+    const year = d.getFullYear()
+    let month = d.getMonth() + 1
+    month = month < 10 ? `0${month}` : month
+    return {
+      selected: [
+        { date: `${year}-${month}-02`, info: '签到', badge: true, infoColor: '#ff0000' },
+        { date: `${year}-${month}-06`, info: '余10', infoColor: '#19be6b', topinfo: '￥100', topinfoColor: '#19be6b' }
+      ]
+    }
+  },
+  methods: {
+    open() {
+      this.$refs.calendars.open()
+    },
+    confirm(e) {
+      console.log(e)
+    }
+  }
+}
+</script>
+```
+
+## API {#api}
+
+### Calendars Props {#props}
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| date | String \| Array | 今天 | 默认选中日期。单日期为字符串如 `2023-08-26`；multiple/range 为数组如 `['2023-08-26','2023-08-29']` |
+| lunar | Boolean | false | 是否显示农历 |
+| mode | String | - | 日期类型：不填（单日期）、`multiple`（多日期）、`range`（范围） |
+| insert | Boolean | false | 是否插入模式，`true` 插入页面，`false` 弹窗模式 |
+| clearDate | Boolean | true | 弹窗模式是否清空上次选择 |
+| selected | Array | - | 打点配置，格式 `[{date, info, disable, ...}]`，见 Selected Options |
+| startDate | String | - | 可选范围开始日期，如 `2023-01-01`，之前日期禁用 |
+| endDate | String | - | 可选范围结束日期，如 `2023-02-01`，之后日期禁用 |
+| showMonth | Boolean | true | 是否显示月份背景 |
+| round | String \| Number | 8px | 弹窗模式圆角 |
+| color | String | #3c9cff | 主题色，建议 16 进制 |
+| confirmColor | String | #3c9cff | 确认按钮颜色 |
+| cancelColor | String | #909193 | 取消按钮颜色 |
+| closeOnClickOverlay | Boolean | true | 点击遮罩是否关闭 |
+| startText | String | 开始 | range 模式下首日底部文案 |
+| endText | String | 结束 | range 模式下末日底部文案 |
+| allowSameDay | Boolean | false | range 模式下是否允许起止同一天 (1.0.11) |
+| readonly | Boolean | false | 只读，禁止选择 (1.0.15) |
+
+### Selected Options（selected 数组项） {#selected-options}
+
+| 属性名 | 说明 |
+| --- | --- |
+| date | 日期，格式 `YYYY-mm-dd` |
+| info | 底部文案 |
+| infoColor | 底部文案颜色 |
+| topinfo | 头部文案 |
+| topinfoColor | 头部文案颜色 |
+| badge | 是否显示右上角红点 |
+| disable | 是否禁止点击 |
+
+### Calendars Methods {#methods}
+
+| 方法名 | 说明 |
+| --- | --- |
+| open | `insert` 为 false 时，调用此方法弹出日历 |
+
+### Calendars Events {#events}
+
+| 事件名 | 说明 | 返回 |
+| --- | --- | --- |
+| @confirm | 点击确定时触发 | 日期参数：fulldate（单）、multiple（多）、range（范围） |
+| @close | 关闭日历时触发 | - |
+| @change | 点击日期时触发 | 同上；insert 为 true 时生效 |
+| @monthSwitch | 选择年月确认时触发 | `{ year, month }` |