@fredwsw/frontend-rules 1.0.0

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

@@ -0,0 +1,104 @@
+---
+group: 媒体
+category: Components
+title: Album
+subtitle: 相册
+description: 图片相册组件，支持单图/多图展示、行数控制、预览大图与查看更多提示，可用对象数组扩展字段。
+demo:
+  cols: 2
+---
+
+## 何时使用 {#when-to-use}
+
+`uv-album` 提供类似相册的功能，用于展示一组图片，支持单图与多图布局、预览大图等，减少重复模板代码。
+
+> 完整示例下载地址：[uv-ui 插件市场](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+## 平台兼容性 {#platform}
+
+| App（vue） | App（nvue） | H5 | 小程序 | VUE2 | VUE3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | √ | √ | √ | √ | √ |
+
+**组件名：** `uv-album`
+
+## 代码演示 {#examples}
+
+### 基本使用 {#basic}
+
+通过 `urls` 属性设置相册图片地址。
+
+```vue
+<template>
+  <view>
+    <uv-album :urls="urls"></uv-album>
+  </view>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      urls: ['https://via.placeholder.com/400x200.png/3c9cff/fff']
+    }
+  }
+}
+</script>
+```
+
+### 多图模式 {#multiple}
+
+`urls` 传入多个地址时形成图片列表，通过 `multipleSize` 设置图片边长，通过 `space` 设置间距。
+
+```vue
+<template>
+  <view style="width: 400rpx;">
+    <uv-album :urls="urls" multipleSize="128rpx" space="8rpx"></uv-album>
+  </view>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      urls: [
+        'https://via.placeholder.com/100x200.png/3c9cff/fff',
+        'https://via.placeholder.com/200x200.png/3c9cff/fff',
+        'https://via.placeholder.com/300x200.png/3c9cff/fff',
+        'https://via.placeholder.com/280x200.png/3c9cff/fff',
+        'https://via.placeholder.com/240x200.png/3c9cff/fff',
+        'https://via.placeholder.com/180x200.png/3c9cff/fff',
+        'https://via.placeholder.com/140x200.png/3c9cff/fff',
+        'https://via.placeholder.com/150x200.png/3c9cff/fff',
+        'https://via.placeholder.com/90x200.png/3c9cff/fff',
+        'https://via.placeholder.com/220x200.png/3c9cff/fff'
+      ]
+    }
+  }
+}
+</script>
+```
+
+## API {#api}
+
+### Album Props {#props}
+
+| 参数 | 说明 | 类型 | 默认值 | 可选值 |
+| --- | --- | --- | --- | --- |
+| urls | 图片地址列表，支持 `Array<String>` 或 `Array<Object>` | Array | - | - |
+| keyName | 对象数组中图片地址字段名 | String | - | - |
+| singleSize | 单图时长边长度 | String \| Number | 180 | - |
+| multipleSize | 多图时图片边长（宽高） | String \| Number | 70 | - |
+| space | 多图时图片水平/垂直间距 | String \| Number | 6 | - |
+| singleMode | 单图时图片裁剪模式 | String | scaleToFill | - |
+| multipleMode | 多图时图片裁剪模式 | String | aspectFill | - |
+| maxCount | 最多展示图片数量，超出时最后一张显示剩余数量 | String \| Number | 9 | - |
+| previewFullImage | 是否可预览大图 | Boolean | true | true \| false |
+| rowCount | 每行展示图片数量（设置后 `singleSize`/`multipleSize` 失效） | String \| Number | 3 | - |
+| showMore | 超出 `maxCount` 时是否显示“查看更多”提示 | Boolean | true | true \| false |
+
+### Album Events {#events}
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| @albumWidth | 某些场景下需要文字与相册宽度一致时使用，该事件对外发送相册宽度 | width |

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

@@ -0,0 +1,71 @@
+---
+group: 基础
+category: Components
+title: Alert
+subtitle: 警告提示
+description: 用于展现需要关注的信息，支持多主题、描述文本、图标与可关闭能力。
+demo:
+  cols: 2
+---
+
+## 何时使用 {#when-to-use}
+
+当页面需要向用户显示警告/提示信息时使用。组件为非浮层的静态展现形式，始终展示，不会自动消失；可配置关闭按钮让用户手动关闭。
+
+> 完整示例下载地址：[uv-ui 插件市场](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+## 平台兼容性 {#platform}
+
+| App（vue） | App（nvue） | H5 | 小程序 | VUE2 | VUE3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | √ | √ | √ | √ | √ |
+
+**组件名：** `uv-alert`
+
+## 代码演示 {#examples}
+
+### 基本使用 {#basic}
+
+通过 `title` / `description` 设置标题与描述；`type` 设置主题（primary/success/error/warning/info）；`effect` 设置浅色/深色（light/dark）。
+
+```vue
+<uv-alert title="uv-ui" type="warning" description="uv-ui的目标是成为uni-app生态最优秀的UI框架"></uv-alert>
+```
+
+### 图标 {#icon}
+
+通过 `showIcon` 控制是否显示图标（当前版本为内置图标，随 type 变化，无法自定义）。
+
+```vue
+<uv-alert type="warning" :show-icon="true"></uv-alert>
+```
+
+### 可关闭 {#closable}
+
+通过 `closable` 显示关闭按钮，点击可关闭。
+
+```vue
+<uv-alert title="uv-ui" type="warning" description="uv-ui的目标是成为uni-app生态最优秀的UI框架" closable></uv-alert>
+```
+
+## API {#api}
+
+### Alert Props {#props}
+
+| 参数 | 说明 | 类型 | 默认值 | 可选值 |
+| --- | --- | --- | --- | --- |
+| title | 标题文字 | String | - | - |
+| type | 主题类型 | String | warning | warning \| success \| primary \| error \| info |
+| description | 辅助文字描述 | String | - | - |
+| closable | 是否可关闭（关闭按钮默认为叉号 icon） | Boolean | false | true \| false |
+| showIcon | 是否显示左侧图标 | Boolean | false | true \| false |
+| effect | 主题色调 | String | light | dark \| light |
+| center | 文字是否居中 | Boolean | false | true \| false |
+| fontSize | 字体大小（rpx 或 px） | String \| Number | 14 | - |
+| customStyle | 自定义外部样式 | Object | - | - |
+
+### Alert Events {#events}
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| @click | 点击组件触发 | - |

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

@@ -0,0 +1,149 @@
+---
+group: 数据
+category: Components
+title: Avatar
+subtitle: 头像
+description: 用于展示用户头像，支持图片/文字/图标、多种形状尺寸，以及头像组展示。
+demo:
+  cols: 2
+---
+
+## 何时使用 {#when-to-use}
+
+`uv-avatar` 常用于个人中心、评论列表等用户头像展示场景，支持图片头像、文字头像、图标头像，以及 `uv-avatar-group` 头像组。
+
+> 完整示例下载地址：[uv-ui 插件市场](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+## 平台兼容性 {#platform}
+
+| App（vue） | App（nvue） | H5 | 小程序 | VUE2 | VUE3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | √ | √ | √ | √ | √ |
+
+**组件名：** `uv-avatar`、`uv-avatar-group`
+
+## 代码演示 {#examples}
+
+### 基本使用 {#basic}
+
+通过 `src` 指定头像图片地址；若传递 `text`，`text` 优先级更高。
+
+注意：请传入 **绝对地址**，不要传相对地址（组件内相对路径不是相对于页面，容易出错）。
+
+```vue
+<template>
+  <view>
+    <uv-avatar src="https://via.placeholder.com/200x200.png/2878ff"></uv-avatar>
+    <uv-avatar text="李"></uv-avatar>
+  </view>
+</template>
+```
+
+### 头像形状 {#shape}
+
+`shape`：circle（圆形）/ square（圆角方形）。
+
+```vue
+<template>
+  <uv-avatar src="https://via.placeholder.com/200x200.png/2878ff" shape="square"></uv-avatar>
+</template>
+```
+
+### 图标头像 {#icon}
+
+设置 `icon` 指定头像图标（图标可参考 `uv-icon`）。
+
+```vue
+<template>
+  <view>
+    <uv-avatar icon="red-packet-fill" fontSize="22"></uv-avatar>
+    <uv-avatar icon="star-fill" fontSize="22"></uv-avatar>
+  </view>
+</template>
+```
+
+### 文字头像（自动背景色） {#random-bg}
+
+开启 `randomBgColor` 后头像可使用随机背景色。
+
+```vue
+<template>
+  <uv-avatar text="北" fontSize="18" randomBgColor></uv-avatar>
+</template>
+```
+
+### 头像组 {#group}
+
+通过 `uv-avatar-group` 展示头像组。
+
+```vue
+<template>
+  <uv-avatar-group :urls="urls" size="35" gap="0.4"></uv-avatar-group>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      urls: [
+        'https://cdn.uviewui.com/uview/album/1.jpg',
+        'https://cdn.uviewui.com/uview/album/2.jpg',
+        'https://cdn.uviewui.com/uview/album/3.jpg',
+        'https://cdn.uviewui.com/uview/album/4.jpg',
+        'https://cdn.uviewui.com/uview/album/7.jpg',
+        'https://cdn.uviewui.com/uview/album/6.jpg',
+        'https://cdn.uviewui.com/uview/album/5.jpg'
+      ]
+    }
+  }
+}
+</script>
+```
+
+## API {#api}
+
+### Avatar Props {#props}
+
+| 参数 | 说明 | 类型 | 默认值 | 可选值 |
+| --- | --- | --- | --- | --- |
+| src | 头像路径（加载失败显示默认头像；不能为相对路径） | String | - | - |
+| shape | 头像形状 | String | circle | circle \| square |
+| size | 头像尺寸（字符串或数值） | String \| Number | 40 | - |
+| mode | 图片裁剪类型（同 uni-app image 的 mode） | String | scaleToFill | - |
+| text | 文字头像（优先级高于 src） | String | - | - |
+| bg-color | 背景颜色（一般显示文字时用） | String | #c0c4cc | - |
+| color | 文字颜色 | String | #ffffff | - |
+| font-size | 文字大小 | String \| Number | 18 | - |
+| icon | 显示图标 | String | - | - |
+| mp-avatar | 显示小程序头像（百度/微信/QQ 小程序有效） | Boolean | false | true \| false |
+| random-bg-color | 是否使用随机背景色 | Boolean | false | true \| false |
+| default-url | 加载失败的默认头像 | String | - | - |
+| color-index | randomBgColor 为 true 时，取默认背景色数组索引（0-19） | String \| Number | - | - |
+| name | 组件标识符 | String | level | - |
+| customStyle | 自定义外部样式 | Object | - | - |
+
+### Avatar Events {#events}
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| @click | 头像被点击 | index：用户传递的标识符 |
+
+### AvatarGroup Props {#group-props}
+
+| 参数 | 说明 | 类型 | 默认值 | 可选值 |
+| --- | --- | --- | --- | --- |
+| urls | 头像图片组 | Array | [] | - |
+| maxCount | 最多展示头像数量 | String \| Number | 5 | - |
+| shape | 头像形状 | String | circle | circle \| square |
+| mode | 图片裁剪模式 | String | aspectFill | - |
+| showMore | 超出 maxCount 时是否显示查看更多提示 | Boolean | true | - |
+| size | 头像大小 | String \| Number | 40 | - |
+| keyName | 数组为对象时读取图片地址的 key | String | - | - |
+| gap | 头像遮挡比例（0.4 代表遮挡 40%） | String \| Number | 0.5 | - |
+| extraValue | 需额外显示的值（优先于 urls.length - maxCount） | String \| Number | - | - |
+
+### AvatarGroup Events {#group-events}
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| @showMore | 头像组更多点击 | - |

package/template/docs/uv-ui-docs/back-top-cn.md

@@ -0,0 +1,121 @@
+---
+group: 导航
+category: Components
+title: BackTop
+subtitle: 返回顶部
+description: 用于长页面中在滚动一定距离后显示返回顶部按钮，点击后快速回到页面顶部。
+demo:
+  cols: 2
+---
+
+## 何时使用 {#when-to-use}
+
+`uv-back-top` 适用于长页面，当用户向下滚动一定距离后显示返回顶部按钮，点击即可快速回到顶部。
+
+注意：组件本身无法感知页面滚动，需要在页面 `onPageScroll` 生命周期中获取 `scrollTop`，再通过 props 传给组件。
+
+> 完整示例下载地址：[uv-ui 插件市场](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+## 平台兼容性 {#platform}
+
+| App（vue） | App（nvue） | H5 | 小程序 | VUE2 | VUE3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | √ | √ | √ | √ | √ |
+
+**组件名：** `uv-back-top`
+
+## 代码演示 {#examples}
+
+### 基本使用 {#basic}
+
+在页面最外层元素设置 `ref="backTop"`，在 `onPageScroll` 中更新 `scrollTop`。
+
+```vue
+<template>
+  <view class="wrap" ref="backTop">
+    <text>滑动页面，返回顶部按钮将出现在右下角</text>
+    <uv-back-top :scroll-top="scrollTop"></uv-back-top>
+  </view>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      scrollTop: 0
+    }
+  },
+  onPageScroll(e) {
+    this.scrollTop = e.scrollTop
+    // #ifdef APP-NVUE
+    this.scrollTop = e.detail.scrollTop
+    // #endif
+  }
+}
+</script>
+
+<style lang="scss" scoped>
+.wrap {
+  height: 2000px;
+}
+</style>
+```
+
+### 改变出现时机 {#top}
+
+通过 `top` 设置滚动多远后显示返回顶部按钮。
+
+```vue
+<uv-back-top :scroll-top="scrollTop" top="600"></uv-back-top>
+```
+
+### 自定义图标与提示文字 {#icon-text}
+
+```vue
+<uv-back-top :scroll-top="scrollTop" icon="arrow-up" text="返回"></uv-back-top>
+```
+
+### 自定义样式 {#custom-style}
+
+通过 `iconStyle` 自定义图标样式，通过 `customStyle` 设置按钮背景/大小，通过 `mode` 控制形状（`circle/square`）。
+
+```vue
+<uv-back-top
+  :scroll-top="scrollTop"
+  icon="arrow-up"
+  text="返回"
+  :mode="mode"
+  :iconStyle="iconStyle"
+  :customStyle="customStyle"
+></uv-back-top>
+```
+
+## API {#api}
+
+### BackTop Props {#props}
+
+| 参数 | 说明 | 类型 | 默认值 | 可选值 |
+| --- | --- | --- | --- | --- |
+| mode | 按钮形状 | String | circle | circle \| square |
+| icon | 内置图标或图片路径 | String | arrow-upward | - |
+| text | 按钮文字提示 | String | - | - |
+| duration | 返回顶部过渡时间（ms） | String \| Number | 100 | - |
+| scrollTop | 页面滚动距离（`onPageScroll` 中获取） | String \| Number | 0 | - |
+| top | 滚动多远显示按钮（px/rpx） | String \| Number | 400 | - |
+| bottom | 按钮距屏幕底部距离（px/rpx） | String \| Number | 100 | - |
+| right | 按钮距屏幕右侧距离（px/rpx） | String \| Number | 20 | - |
+| z-index | 按钮层级 | String \| Number | 9 | - |
+| iconStyle | 图标样式（对象） | Object | - | - |
+| customStyle | 外层自定义样式 | Object | - | - |
+
+### BackTop Methods {#methods}
+
+| 方法名 | 说明 |
+| --- | --- |
+| backToTop | 在自定义内容时，可手动调用该方法返回顶部 |
+
+### BackTop Slots {#slots}
+
+| 名称 | 说明 |
+| --- | --- |
+| default | 自定义返回按钮的全部内容 |

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

@@ -0,0 +1,100 @@
+---
+group: 数据
+category: Components
+title: Badge
+subtitle: 徽标数（数字角标）
+description: 用于显示未读消息或数量提示，支持圆点/数字、最大值、不同数值展示策略与自定义样式。
+demo:
+  cols: 2
+---
+
+## 何时使用 {#when-to-use}
+
+`uv-badge` 一般用于显示未读消息或数量提示，可配合 `uv-tabs`、`uv-vtabs` 等组件使用，支持圆点与带数字两种形态。
+
+> 完整示例下载地址：[uv-ui 插件市场](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+## 平台兼容性 {#platform}
+
+| App（vue） | App（nvue） | H5 | 小程序 | VUE2 | VUE3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | √ | √ | √ | √ | √ |
+
+**组件名：** `uv-badge`
+
+## 代码演示 {#examples}
+
+### 基本使用 {#basic}
+
+- `value`：徽标内容
+- `type`：主题（primary / warning / error / success / info）
+- `max`：最大值，超出显示 `${max}+`
+
+```vue
+<template>
+  <view style="padding: 20px;">
+    <view class="box">
+      <uv-badge type="error" max="99" :value="100"></uv-badge>
+    </view>
+  </view>
+</template>
+
+<style lang="scss" scoped>
+.box {
+  width: 50px;
+  height: 50px;
+  background-color: #909193;
+}
+</style>
+```
+
+### 圆点徽标 {#dot}
+
+通过 `isDot` 显示小圆点（不展示数字）。
+
+```vue
+<uv-badge :isDot="true" type="success"></uv-badge>
+```
+
+### 数字展示方式 {#number-type}
+
+- `overflow`：超出 `max` 显示 `${max}+`
+- `ellipsis`：超出 `max` 直接显示 `...`
+- `limit`：以 1000 为阈值，超出显示 K/W，最多保留 2 位小数
+
+```vue
+<template>
+  <view style="padding: 20px;">
+    <view class="box">
+      <uv-badge numberType="overflow" type="error" max="99" :value="100"></uv-badge>
+    </view>
+    <view class="box">
+      <uv-badge numberType="ellipsis" type="error" max="99" :value="10000"></uv-badge>
+    </view>
+    <view class="box">
+      <uv-badge numberType="limit" type="error" max="99" :value="100"></uv-badge>
+    </view>
+  </view>
+</template>
+```
+
+## API {#api}
+
+### Badge Props {#props}
+
+| 参数 | 说明 | 类型 | 默认值 | 可选值 |
+| --- | --- | --- | --- | --- |
+| value | 展示数字；大于 max 显示 `${max}+`；为 0 且 show-zero 为 false 时隐藏 | String \| Number | - | - |
+| isDot | 不展示数字，仅显示小点 | Boolean | false | true \| false |
+| show | 组件是否显示 | Boolean | true | true \| false |
+| max | 最大值，超出显示 `${max}+` | String \| Number | 99 | - |
+| type | 主题类型 | String | error | error \| warning \| success \| primary \| info |
+| showZero | 数值为 0 时是否展示 | Boolean | false | true \| false |
+| bgColor | 背景色（优先级高于 type） | String | - | - |
+| color | 字体颜色 | String | #ffffff | - |
+| shape | 形状：circle（四角圆角）/ horn（左下直角） | String | circle | circle \| horn |
+| numberType | 数字展示方式 | String | overflow | overflow \| ellipsis \| limit |
+| inverted | 是否反转背景与字体颜色 | Boolean | false | true \| false |
+| absolute | 是否绝对定位（为 true 时 offset 生效） | Boolean | false | true \| false |
+| offset | 位置偏移 `[x, y]`（absolute 为 true 时有效） | Array | - | - |
+| customStyle | 自定义外部样式 | Object | - | - |