@fredwsw/frontend-rules 1.0.0

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

@@ -0,0 +1,220 @@
+---
+group: 表单
+category: Components
+title: Form
+subtitle: 表单
+description: 用于表单场景，可配置 Input、Select 等，支持表单验证。
+demo:
+  cols: 2
+---
+
+## 何时使用 {#when-to-use}
+
+`uv-form` 一般用于表单验证、输入绑定、下拉选择等场景。每个表单域由 `uv-form-item` 组成，可放置 `uv-input`、`uv-textarea`、`uv-checkbox`、`uv-radio`、`uv-switch` 等。
+
+> 完整示例下载地址：[uv-ui 插件市场](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+## 平台兼容性 {#platform}
+
+| App（vue） | App（nvue） | H5 | 小程序 | VUE2 | VUE3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | √ | √ | √ | √ | √ |
+
+**组件名：** `uv-form`
+
+## 注意事项 {#notice}
+
+- 组件上的 `ref` 建议不要和组件重名，否则 vue3 的 setup 语法糖可能报错
+- 使用 `v-if` 控制 `uv-form-item` 显示/隐藏时，建议加 `key`，否则 type="password" 可能失效
+- app-nvue 下 input 设置 disabled 或 readonly 时，节点事件可能无效，可用 view 遮罩解决
+
+## 代码演示 {#examples}
+
+### 基本使用 {#basic}
+
+通过 `model` 绑定数据，`rules` 设置校验规则，`ref` 调用 `validate`、`resetFields` 等方法。
+
+```vue
+<template>
+  <view>
+    <uv-form labelPosition="left" :model="model1" :rules="rules" ref="form">
+      <uv-form-item label="姓名" prop="userInfo.name" borderBottom>
+        <uv-input v-model="model1.userInfo.name" border="none"></uv-input>
+      </uv-form-item>
+      <uv-form-item label="性别" prop="userInfo.sex" borderBottom @click="showSexSelect">
+        <uv-input
+          v-model="model1.userInfo.sex"
+          disabled
+          disabledColor="#ffffff"
+          placeholder="请选择性别"
+          border="none"
+        ></uv-input>
+        <template v-slot:right>
+          <uv-icon name="arrow-right"></uv-icon>
+        </template>
+      </uv-form-item>
+      <uv-button type="primary" text="提交" customStyle="margin-top: 10px" @click="submit"></uv-button>
+      <uv-button type="error" text="重置" customStyle="margin-top: 10px" @click="reset"></uv-button>
+    </uv-form>
+    <uv-action-sheet ref="sexSelect" :actions="actions" title="请选择性别" @select="sexSelect"></uv-action-sheet>
+  </view>
+</template>
+<script>
+export default {
+  data() {
+    return {
+      model1: {
+        userInfo: { name: 'uv-ui', sex: '' }
+      },
+      actions: [{ name: '男' }, { name: '女' }, { name: '保密' }],
+      rules: {
+        'userInfo.name': {
+          type: 'string',
+          required: true,
+          message: '请填写姓名',
+          trigger: ['blur', 'change']
+        },
+        'userInfo.sex': {
+          type: 'string',
+          max: 1,
+          required: true,
+          message: '请选择男或女',
+          trigger: ['blur', 'change']
+        }
+      }
+    }
+  },
+  methods: {
+    submit() {
+      this.$refs.form.validate().then(res => {
+        uni.showToast({ icon: 'success', title: '校验通过' })
+      }).catch(errors => {
+        uni.showToast({ icon: 'error', title: '校验失败' })
+      })
+    },
+    reset() {
+      this.$refs.form.resetFields()
+      this.$refs.form.clearValidate()
+    },
+    showSexSelect() {
+      this.$refs.sexSelect.open()
+      uni.hideKeyboard()
+    },
+    sexSelect(e) {
+      this.model1.userInfo.sex = e.name
+      this.$refs.form.validateField('userInfo.sex', err => {})
+    }
+  }
+}
+</script>
+```
+
+### 自定义校验规则 {#validator}
+
+使用 `validator` 自定义同步校验，`asyncValidator` 异步校验。某些平台不支持 props 传函数，需在 `onReady` 中调用 `this.$refs.form.setRules(this.rules)`。
+
+```vue
+<template>
+  <view>
+    <uv-form :model="form" :rules="rules" ref="form">
+      <uv-form-item label="电话" prop="mobile">
+        <uv-input v-model="form.mobile" placeholder="请输入电话" />
+      </uv-form-item>
+    </uv-form>
+    <uv-button @click="submit">提交</uv-button>
+  </view>
+</template>
+<script>
+export default {
+  data() {
+    return {
+      form: { mobile: '' },
+      rules: {
+        mobile: [
+          { required: true, message: '此为必填字段', trigger: ['blur', 'change'] },
+          {
+            validator: (rule, value) => uni.$uv.test.mobile(value),
+            message: '电话号码格式错误',
+            trigger: ['blur']
+          }
+        ]
+      }
+    }
+  },
+  onReady() {
+    this.$refs.form.setRules(this.rules)
+  },
+  methods: {
+    submit() {
+      this.$refs.form.validate().then(res => {
+        uni.showToast({ icon: 'success', title: '校验通过' })
+      }).catch(() => {
+        uni.showToast({ icon: 'error', title: '校验失败' })
+      })
+    }
+  }
+}
+</script>
+```
+
+### 错误提示方式 {#error-type}
+
+通过 `errorType` 设置：`message`（文字）、`none`（不提示）、`border-bottom`（底线下划线变红）、`toast`（toast 提示）。
+
+```vue
+<uv-form :error-type="errorType">...</uv-form>
+```
+
+## API {#api}
+
+### Form Props {#props}
+
+| 参数 | 说明 | 类型 | 默认值 | 可选值 |
+| --- | --- | --- | --- | --- |
+| model | 表单数据对象 | Object | - | - |
+| rules | 校验规则，含自定义方法时需用 setRules | Object \| Function \| Array | - | - |
+| errorType | 错误提示方式 | String | message | message \| toast \| border-bottom \| none |
+| borderBottom | 是否显示表单域下划线 | Boolean | true | - |
+| labelPosition | 提示文字位置 | String | left | top \| left |
+| labelWidth | 提示文字宽度 px/rpx | String \| Number | 45 | - |
+| labelAlign | label 对齐 | String | left | left \| center \| right |
+| labelStyle | label 样式 | Object | - | - |
+
+### Form Methods {#methods}
+
+通过 ref 调用。
+
+| 名称 | 说明 | 参数 |
+| --- | --- | --- |
+| validate | 整表校验 | - |
+| setRules | 设置 rules（含自定义函数时必用） | Function(rules) |
+| validateField | 部分字段校验 | Function(value, Function(errorsRes)) |
+| resetFields | 重置为初始值并移除校验结果 | - |
+| clearValidate | 清空校验结果 | Function(props) |
+
+### FormItem Props {#formitem-props}
+
+| 参数 | 说明 | 类型 | 默认值 | 可选值 |
+| --- | --- | --- | --- | --- |
+| label | 左侧提示文字 | String | - | - |
+| prop | model 中的属性名 | String | - | - |
+| borderBottom | 是否显示下边框 | String \| Boolean | true | true \| false |
+| labelWidth | 覆盖 form 的 labelWidth | String \| Number | - | - |
+| labelPosition | label 位置 | String | - | left \| top |
+| leftIcon | 左侧图标 | String | - | - |
+| leftIconStyle | 左侧图标样式 | String \| Object | - | - |
+| required | 是否显示 * 号（仅展示，校验用 rules） | Boolean | false | true \| false |
+| customStyle | 自定义样式 | Object | - | - |
+
+### FormItem Slots {#formitem-slots}
+
+| 名称 | 说明 |
+| --- | --- |
+| default | form-item 内容 |
+| right | 右侧自定义内容 |
+
+### FormItem Events {#formitem-events}
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| @click | 点击触发 | - |

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

@@ -0,0 +1,63 @@
+---
+group: 布局
+category: Components
+title: Gap
+subtitle: 间隔槽
+description: 用于内容块之间的留白分隔区域，通常为一块背景色矩形，用于统一页面分段间距。
+demo:
+  cols: 2
+---
+
+## 何时使用 {#when-to-use}
+
+`uv-gap` 用于 **内容块之间的留白分隔**，例如：
+
+- 列表区块之间的灰色间隔
+- 页面模块之间的视觉分割
+
+通过统一使用 `uv-gap` 可以保持页面风格一致，减少重复写样式的工作量。
+
+> 完整示例下载地址：[uv-ui 插件市场](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+## 平台兼容性 {#platform}
+
+| App（vue） | App（nvue） | H5 | 小程序 | VUE2 | VUE3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | √ | √ | √ | √ | √ |
+
+**组件名：** `uv-gap`
+
+## 代码演示 {#examples}
+
+### 基本使用 {#basic}
+
+直接引入即可，通过 `height` 与 `bgColor` 控制间隔块高度与背景色。
+
+```vue
+<uv-gap height="80" bgColor="#bbb"></uv-gap>
+```
+
+### 与上下内容的距离 {#margin}
+
+通过 `marginTop`、`marginBottom` 单独控制与前后元素的间距。
+
+```vue
+<uv-gap
+  height="40"
+  bgColor="#f5f5f5"
+  :marginTop="20"
+  :marginBottom="20"
+></uv-gap>
+```
+
+## API {#api}
+
+### Gap Props {#props}
+
+| 参数 | 说明 | 类型 | 默认值 | 可选值 |
+| --- | --- | --- | --- | --- |
+| bgColor | 背景颜色 | String | transparent（背景透明） | - |
+| height | 间隔槽高度（px/rpx） | String \| Number | 20 | - |
+| marginTop | 与前一个元素的距离（px/rpx） | String \| Number | 0 | - |
+| marginBottom | 与后一个元素的距离（px/rpx） | String \| Number | 0 | - |
+

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

@@ -0,0 +1,187 @@
+---
+group: 布局
+category: Components
+title: Grid
+subtitle: 宫格布局
+description: 多宫格布局组件，支持自定义列数、边框、对齐方式和点击事件，可扩展为左右滑动宫格。
+demo:
+  cols: 2
+---
+
+## 何时使用 {#when-to-use}
+
+`uv-grid` 一般用于同时展示多个同类项目的场景，如功能入口菜单、分类宫格等。  
+支持为宫格项配合 `uv-badge`、`uv-icon` 等组件展示图标与徽标，也可结合 `swiper` 实现左右滑动的宫格页。
+
+> 完整示例下载地址：[uv-ui 插件市场](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+## 平台兼容性 {#platform}
+
+| App（vue） | App（nvue） | H5 | 小程序 | VUE2 | VUE3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | √ | √ | √（仅支持微信小程序） | √ | √ |
+
+**组件名：** `uv-grid`、`uv-grid-item`
+
+## 代码演示 {#examples}
+
+### 基本使用 {#basic}
+
+外层使用 `uv-grid` 包裹，通过 `col` 设置列数，内部用 `uv-grid-item` 的 slot 定义内容；`border=false` 关闭宫格边框。
+
+```vue
+<template>
+  <view>
+    <uv-grid :border="false">
+      <uv-grid-item v-for="(item, index) in baseList" :key="index">
+        <uv-icon :customStyle="{ paddingTop: 20 + 'rpx' }" :name="item.name" :size="22"></uv-icon>
+        <text class="grid-text">{{ item.title }}</text>
+      </uv-grid-item>
+    </uv-grid>
+  </view>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      baseList: [
+        { name: 'photo', title: '李白' },
+        { name: 'lock', title: '韩信' },
+        { name: 'star', title: '刘备' }
+      ]
+    }
+  }
+}
+</script>
+
+<style lang="scss">
+.grid-text {
+  font-size: 14px;
+  color: #909399;
+}
+</style>
+```
+
+### 自定义列数与点击事件 {#col-click}
+
+```vue
+<template>
+  <view>
+    <uv-grid :col="4" @click="click">
+      <uv-grid-item v-for="(item, index) in baseList" :key="index">
+        <uv-icon :customStyle="{ paddingTop: 20 + 'rpx' }" :name="item.name" :size="22"></uv-icon>
+        <text class="grid-text">{{ item.title }}</text>
+      </uv-grid-item>
+    </uv-grid>
+  </view>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      baseList: [
+        { name: 'photo', title: '李白' },
+        { name: 'lock', title: '韩信' },
+        { name: 'star', title: '刘备' },
+        { name: 'star', title: '元芳' }
+      ]
+    }
+  },
+  methods: {
+    click(name) {
+      uni.showToast({
+        icon: 'none',
+        title: `点击了第${name}个`
+      })
+    }
+  }
+}
+</script>
+```
+
+### 实现宫格左右滑动 {#swiper}
+
+结合 uni `swiper` 可以实现宫格左右滑动；请指定 `swiper` 高度，否则不会被内容撑开。
+
+```vue
+<template>
+  <view>
+    <swiper :indicator-dots="true" class="swiper">
+      <swiper-item>
+        <uv-grid :border="true" align="center">
+          <uv-grid-item
+            v-for="(item, index) in swiperList"
+            :key="index"
+            :index="index"
+            :customStyle="{ width: 220 + 'rpx', height: 220 + 'rpx' }"
+          >
+            <uv-icon :customStyle="{ paddingTop: 20 + 'rpx' }" :name="item" :size="22"></uv-icon>
+            <text class="grid-text">{{ '宫格' + (index + 1) }}</text>
+          </uv-grid-item>
+        </uv-grid>
+      </swiper-item>
+      <!-- 省略第二、三页示例，整体结构一致，仅 index 偏移不同 -->
+    </swiper>
+  </view>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      swiperList: ['integral', 'kefuv-ermai', 'coupon', 'gift', 'scan', 'pause-circle', 'volume-off', 'email', 'list']
+    }
+  }
+}
+</script>
+
+<style lang="scss">
+.swiper {
+  height: 720rpx;
+}
+.grid-text {
+  font-size: 14px;
+  color: #909399;
+  padding: 10rpx 0 20rpx 0;
+  /* #ifndef APP-PLUS */
+  box-sizing: border-box;
+  /* #endif */
+}
+</style>
+```
+
+## API {#api}
+
+### Grid Props {#props}
+
+| 参数 | 说明 | 类型 | 默认值 | 可选值 |
+| --- | --- | --- | --- | --- |
+| col | 宫格列数 | String \| Number | 3 | - |
+| border | 是否显示宫格边框 | Boolean | true | true \| false |
+| align | 宫格对齐方式（控制只有一两个宫格时的对齐场景） | String | left | left \| center \| right |
+| customStyle | 自定义外部样式 | Object | - | - |
+
+### GridItem Props {#item-props}
+
+| 参数 | 说明 | 类型 | 默认值 | 可选值 |
+| --- | --- | --- | --- | --- |
+| name | 宫格标识名 | String \| Number | - | - |
+| bgColor | 宫格背景颜色 | String | transparent | - |
+
+### Grid Events {#events}
+
+> 需在 `uv-grid` 上监听。
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| @click | 点击宫格触发 | name |
+
+### GridItem Events {#item-events}
+
+> 需在 `uv-grid-item` 上监听。
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| @click | 点击宫格触发 | name |