--- url: 'https://wot-design-uni.cn/component/action-sheet.md' --- # ActionSheet 动作面板 从底部弹出的动作菜单面板。 ## 基本用法 通过 `v-model` 设置显示隐藏。 `actions` 类型为 `Array`，数组内部对象结构如下： | 参数 | 类型 | 说明 | 最低版本 | | ------- | ------ | -------- | -------- | | name | string | 选项名称 | - | | subname | string | 描述信息 | - | | color | string | 颜色 | - | ```html 弹出菜单 ``` ```typescript const show = ref(false) const actions = ref([ { name: '选项1' }, { name: '选项2' }, { name: '选项3', subname: '描述信息' } ]) function showActions() { show.value = true } function close() { show.value = false } const toast = useToast() function select({ item, index }) { toast.show(`当前选中项: ${item.title}, 下标: ${index}`) } ``` ## 选项状态 可以设置 颜色、禁用、加载 等状态。 ```html 弹出菜单 ``` ```typescript const show = ref(false) const actions = ref([ { name: '颜色', color: '#0083ff' }, { name: '禁用', disabled: true }, { loading: true } ]) function showActions() { show.value = true } function close() { show.value = false } ``` ## 取消按钮 设置 `cancel-text` 取消按钮文案，展示取消按钮。 ```html ``` ## 自定义单行面板 自定义单行面板时，`panels` 类型为一维数组， 数组内部对象结构如下： | 参数 | 类型 | 说明 | 最低版本 | | ------- | ------ | -------- | -------- | | iconUrl | string | 图片地址 | - | | title | string | 标题 | - | ```html 弹出菜单 ``` ```typescript const show = ref(false) const panels = ref([ { iconUrl: '//img12.360buyimg.com/imagetools/jfs/t1/122016/33/6657/1362/5f0692a1E8708d245/e47299e5945a6956.png', title: '微信好友' } ]) function showActions() { show.value = true } function close() { show.value = false } const toast = useToast() function select({ item, index }) { toast.show(`当前选中项: ${item.title}, 下标: ${index}`) } ``` ### 多行展示 自定义多行面板时， `panels` 类型为多维数组， 每个数组内部对象结构如下： | 参数 | 类型 | 说明 | 最低版本 | | ------- | ------ | -------- | -------- | | iconUrl | string | 图片地址 | - | | title | string | 标题 | - | ```html 弹出菜单 ``` ```typescript const show = ref(false) const panels = ref([ [ { iconUrl: '//img12.360buyimg.com/imagetools/jfs/t1/122016/33/6657/1362/5f0692a1E8708d245/e47299e5945a6956.png', title: '微信好友' } ], [ { iconUrl: '//img12.360buyimg.com/imagetools/jfs/t1/122016/33/6657/1362/5f0692a1E8708d245/e47299e5945a6956.png', title: '微信好友' } ] ]) function showActions() { show.value = true } function close() { show.value = false } const toast = useToast() function select({ item, index }) { toast.show(`当前选中项: ${item.title}, 下标: ${index}`) } ``` ## 标题 设置 `title` 展示标题。 ```html 内容 ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ---------------------- | ----------------------------------------------------------------------------- | ------- | ------ | ------- | -------- | | v-model | 设置菜单显示隐藏 | boolean | - | - | - | | actions | 菜单选项 | array | - | \[] | - | | panels | 自定义面板项,可以为字符串数组，也可以为对象数组，如果为二维数组，则为多行展示 | array | - | \[] | - | | title | 标题 | string | - | - | - | | cancel-text | 取消按钮文案 | string | - | - | - | | close-on-click-action | 点击选项后是否关闭菜单 | boolean | - | true | - | | close-on-click-modal | 点击遮罩是否关闭 | boolean | - | true | - | | duration | 动画持续时间 | number | - | 200(ms) | - | | z-index | 菜单层级 | number | - | 10 | - | | lazy-render | 弹层内容懒渲染，触发展示时才渲染内容 | boolean | - | true | - | | safe-area-inset-bottom | 弹出面板是否设置底部安全距离（iphone X 类型的机型） | boolean | - | true | - | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | ---------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | select | 点击选项时触发 | 菜单选项或自定义面板一维数组 （item: 选项对象, index: 选项下标），自定义面板二维数组（item: 选项对象, rowIndex: 选项行下标, colIndex 选项列下标） | - | | open | 弹出层打开时触发 | - | - | | opened | 弹出层打开动画结束时触发 | - | - | | close | 弹出层关闭时触发 | - | - | | closed | 弹出层关闭动画结束时触发 | - | - | | click-modal | 点击遮罩时触发 | - | - | | cancel | 点击取消按钮时触发 | - | - | ## Action 数据结构 | 键名 | 说明 | 类型 | 最低版本 | | -------- | ---------- | ------- | -------- | | name | 选项名称 | string | - | | subname | 描述信息 | string | - | | color | 颜色 | string | - | | disabled | 禁用 | boolean | - | | loading | 加载中状态 | boolean | - | ## Panel 数据结构 | 键名 | 说明 | 类型 | 最低版本 | | ------- | -------- | ------ | -------- | | iconUrl | 图片地址 | string | - | | title | 标题内容 | string | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------------- | --------------- | -------- | | custom-class | 根节点样式 | - | | custom-header-class | header 头部样式 | - | --- --- url: 'https://wot-design-uni.cn/component/backtop.md' --- # Backtop 回到顶部 用于返回页面顶部的操作按钮。 ## 基本用法 由于返回顶部需要实时监听滚动条位置，但是在uniapp的组件中不能获取页面的滚动信息， 所以只能在页面的`onPageScroll`生命周期中获取滚动条位置，再通过`Props`传递给组件。 ```html ``` ```typescript const scrollTop = ref(0) onPageScroll((e) => { scrollTop.value = e.scrollTop }) ``` ## 自定义图标 ```html TOP ``` ## 自定义样式 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | --------- | -------------------------------- | ------ | ------ | ------ | -------- | | scrollTop | 页面滚动距离 | number | - | - | - | | top | 距离顶部多少距离时显示，单位`px` | number | - | 300 | - | | duration | 返回顶部滚动时间，单位`ms` | number | - | 100 | - | | zIndex | 组件z-index属性 | number | - | 10 | - | | iconStyle | 自定义`icon`样式 | string | - | - | - | | shape | 按钮形状 | string | square | circle | - | | bottom | 距离屏幕顶部的距离，单位`px` | number | - | 100 | - | | right | 距离屏幕右边距离，单位`px` | number | - | 20 | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | | custom-style | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/badge.md' --- # Badge 徽标 出现在按钮、图标旁的数字或状态标记。 ## 基础用法 展示新消息数量。 定义`modelValue`属性，它接受`Number`或者`String`。 ```html 评论 评论 ``` ## 修改背景色 设置 `type` 属性，也可以自定义背景色 `bg-color`，也可以通过`custom-class`定义组件样式。 ```html 回复 评论 回复 评论 回复 ``` ```scss :deep(.badge) { margin: 0 30px 20px 0; display: inline-block; } ``` ## 最大值 可自定义最大值。 由`max`属性定义，它接受一个`Number`，需要注意的是，只有当`modelValue`为`Number`时，它才会生效。 ```html 评论 回复 ``` ## 展示 0 值 可使用`show-zero`属性，自定义是否展示 `0` 值。需要注意的是，`is-dot` 属性优先级高于 `show-zero` 属性，`is-dot`为`true`时将始终显示红点。 ```html 评论 回复 ``` ## 自定义内容 可以显示数字以外的文本内容。 定义`modelValue`为`String`类型是时可以用于显示自定义文本。 ```html 评论 回复 ``` ## 点状标注 以红点的形式标注需要关注的内容。 除了数字外，设置`is-dot`属性，它接受一个`Boolean`。 ```html 数据查询 ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|---------| | v-model | 显示值 | string / number | - | - | - | - | | max | 最大值，超过最大值会显示 '{max}+'，要求 value 是 Number 类型 | number | - | - | - | | top | 为正时，角标向下偏移对应的像素 | number | - | - | - | | right | 为正时，角标向左偏移对应的像素 | number | - | - | - | | is-dot | 红色点状标注 | boolean | - | false | - | | hidden | 隐藏 badge | boolean | - | false | - | | type | 类型 | string | primary / success / warning / danger / info | - | - | | bg-color | 背景色 | string | 各种颜色的css写法 | - | - | | show-zero | 是否显示0 | boolean | - | false | 0.1.62 | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/button.md' --- # Button 按钮 按钮用于触发一个操作，如提交表单或打开链接。 ## 基本用法 基本按钮。 ```html 主要按钮 成功按钮 信息按钮 警告按钮 危险按钮 ``` ## 禁用 设置 `disabled` 属性。 ```html 默认按钮 ``` ## 幽灵按钮 设置 `plain` 属性。 ```html 主要按钮 ``` ## 细边框幽灵按钮 设置 `hairline` 属性。 ```html 主要按钮 ``` ## 按钮大小 设置 `size` ，支持 'small'、'medium'、'large'，默认为 'medium'。 ```html 小号按钮 中号按钮 大号按钮 ``` ## 加载中按钮 设置 `loading` 属性，让按钮处于加载中状态。加载中的按钮是禁止点击的。 ```html 加载中 ``` ## 文字按钮 将 `type` 设置为 `text`。文字按钮不支持其他颜色。 ```html 文字按钮 ``` ## 图标按钮 将 `type` 设置为 `icon`，同时设置 `icon` 属性，icon 为图标的类名，可以直接使用 `Icon 图标` 章节中的图标类名。 ```html ``` ## 带图标的按钮 设置 `icon` 属性，不需要设置 `type` 为 `icon`，即可以直接使用带图标的按钮。 ```html ``` 结合`classPrefix`可以使用自定义图标，参见 [Icon 自定义图标](/component/icon#自定义图标)。 ```html 可回收 ``` ## 块状按钮 设置 `block` 属性。 ```html 主要按钮 ``` ## 自定义样式 通过 `custom-class` 和 `custom-style` 属性可以自定义按钮的样式，这里我们使用`custom-class`给按钮添加一个 `Material Design 3` 风格的`box-shadow`。 ```html 主要按钮 成功按钮 信息按钮 警告按钮 危险按钮 ``` ```scss .page-class { :deep() { .custom-shadow { box-shadow: 0 3px 1px -2px rgb(0 0 0 / 20%), 0 2px 2px 0 rgb(0 0 0 / 14%), 0 1px 5px 0 rgb(0 0 0 / 12%); } } } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------- | ------------ | -------- | | type | 按钮类型 | string | primary / success / info / warning / error / text / icon | primary | - | | round | 圆角按钮 | boolean | - | true | - | | plain | 幽灵按钮 | boolean | - | false | - | | hairline | 是否细边框 | boolean | - | false | - | | loading | 加载中按钮 | boolean | - | false | - | | block | 块状按钮 | boolean | - | false | - | | size | 按钮尺寸 | string | small / medium / large | medium | - | | disabled | 禁用按钮 | boolean | - | false | - | | icon | 图标类名 | string | - | - | - | | loading-color | 加载图标颜色 | string | - | - | - | | open-type | 微信开放能力 | string | - | - | - | | hover-stop-propagation | 指定是否阻止本节点的祖先节点出现点击态 | boolean | - | false | - | | lang | 指定返回用户信息的语言，zh\_CN 简体中文，zh\_TW 繁体中文，en 英文 | string | zh\_CN / zh\_TW | en | - | | session-from | 会话来源，open-type="contact"时有效 | string | - | - | - | | session-message-title | 会话内消息卡片标题，open-type="contact"时有效 | string | - | 当前标题 | - | | session-message-path | 会话内消息卡片点击跳转小程序路径，open-type="contact"时有效 | string | - | 当前分享路径 | - | | send-message-img | 会话内消息卡片图片，open-type="contact"时有效 | string | - | 截图 | - | | app-parameter | 打开 APP 时，向 APP 传递的参数，open-type=launchApp 时有效 | string | - | - | - | | show-message-card | 是否显示会话内消息卡片，设置此参数为 true，用户进入客服会话会在右下角显示"可能要发送的小程序"提示，用户点击后可以快速发送小程序消息，open-type="contact"时有效 | boolean | - | false | - | | classPrefix | 类名前缀，用于使用自定义图标，参见[icon](/component/icon#自定义图标) | string | - | 'wd-icon' | 0.1.27 | | button-id | 按钮的唯一标识，可用于设置隐私同意授权按钮的 id | string | - | - | 1.3.6 | | scope | 支付宝小程序使用，当 open-type 为 getAuthorize 时有效。 | ButtonScope | `phoneNumber` / `userInfo` | - | 1.3.14 | ### ButtonOpenType 开放能力 | 属性 | 说明 | | ------------------------- | ------------------------------------------------------------------------------------------ | | feedback | 打开“意见反馈”页面，用户可提交反馈内容并上传日志。 | | share | 触发用户转发 | | getUserInfo | 获取用户信息，可以从@getuserinfo 回调中获取到用户信息 | | contact | 打开客服会话，如果用户在会话中点击消息卡片后返回应用，可以从 @contact 回调中获得具体信息 | | getPhoneNumber | 获取用户手机号，可以从@getphonenumber 回调中获取到用户信息 | | launchApp | 小程序中打开 APP，可以通过 app-parameter 属性设定向 APP 传的参数 | | openSetting | 打开授权设置页 | | chooseAvatar | 获取用户头像，可以从@chooseavatar 回调中获取到头像信息 | | getAuthorize | 支持小程序授权，支付宝小程序配合`scope`使用，可以实现`getPhoneNumber`和`getUserInfo`功能。 | | lifestyle | 关注生活号，支付宝小程序 | | contactShare | 分享到通讯录好友，支付宝小程序 | | agreePrivacyAuthorization | 用户同意隐私协议按钮。可通过 @agreeprivacyauthorization 监听用户同意隐私协议事件。 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------------- | ------------------------------------------------------------ | -------- | -------- | | click | 点击事件 | `event` | - | | getuserinfo | 获取用户信息 | `detail` | - | | contact | 客服消息回调，open-type="contact"时有效 | `detail` | - | | getphonenumber | 获取用户手机号回调，open-type=getPhoneNumber 时有效 | `detail` | - | | error | 当使用开放能力时，发生错误的回调，open-type=launchApp 时有效 | `detail` | - | | launchapp | 打开 APP 成功的回调，open-type=launchApp 时有效 | `detail` | - | | opensetting | 在打开授权设置页后回调，open-type=openSetting 时有效 | `detail` | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/calendar.md' --- # Calendar 日历选择器 提供日历单选、多选、范围选择、周维度、月维度等功能。 ## 基本使用 `type` 默认为 `date` 类型，设置 `v-model` 绑定值（13 位时间戳格式），监听 `@confirm` 事件获取选中值。`min-date` 最小日期默认为当前日期往前推 6 个月，`max-date` 最大日期默认为当前日期往后推 6 个月，日历的日期只展示最小日期到最大日期之间的日期。label 可以不传。可以通过 `label-width` 设置标题宽度，默认为 '33%'。 > `min-date`和`max-date`这两个值尽量不要设置过大，避免大量数据的计算和传递导致页面性能低下。 ```html ``` ```typescript const value = ref(Date.now()) function handleConfirm({ value }) { console.log(value) } ``` ## 日期多选 设置 `type` 为 `dates` 类型，此时 `value` 为数组。 ```html ``` ```typescript const value = ref([]) function handleConfirm({ value }) { console.log(value) } ``` ## 周类型选择 设置 `type` 为 `week` 类型，如果 `value` 有初始值，建议将周起始日 `first-day-of-week` 设置为 1（周一），避免选中样式和回显匹配不上。 ```html ``` ```typescript const value = ref(Date.now()) function handleConfirm({ value }) { console.log(value) } ``` ## 月类型选择 设置 `type` 为 `month` 类型，此时 `value` 有值时其值为月的第一天。 ```html ``` ```typescript const value = ref(Date.now()) function handleConfirm({ value }) { console.log(value) } ``` ## 范围选择 `type` 支持 `daterange`（日期范围选择）、`weekrange`（周范围选择）、`monthrange`（月范围选择） 类型，此时 `value` 为数组格式。 ```html ``` ```typescript const value = ref([]) function handleConfirm({ value }) { console.log(value) } ``` ## 日期时间类型 设置 `type` 为 `datetime` 类型，可以选择到时分秒，设置 `type` 为 `datetimerange` 为范围选择。 ```html ``` ```typescript const value = ref('') function handleConfirm({ value }) { console.log(value) } ``` 可以设置 `hide-second`，使时间只展示到分钟级别；设置 `time-filter` 属性，可以自定义过滤 时分秒 选项，该属性接收 { type: string, values: array } 参数，返回一个新的数组，type 值为 'hour'、'minute' 或 'second'，values 为 picker 数据列表。 ```html ``` ```typescript const value = ref('') function timeFilter({ type, values }) { if (type === 'minute') { // 只展示 0,10,20,30,40,50 分钟选项 return values.filter((item) => { return item % 10 === 0 }) } return values } function handleConfirm({ value }) { console.log(value) } ``` ## 日周月切换 设置 `show-type-switch` 属性，展示 日周月 切换功能，支持在日周月类型 `date、week、month` 之间进行来回切换，可以通过 `type` 属性设置初始类型。如果 `type` 为 range 类型如 `daterange`，则日历可以在 `daterange、weekrange、monthrang` 之间进行来回切换。 ```html ``` ## 快捷操作 设置 `show-confirm` 属性为 `false`，不展示确定按钮，只对 `date、daterange、week、weekrange、month、monthrange` 类型有效。 ```html ``` ## 范围选择允许选中同一日期 设置 `allow-same-day` 属性，范围选择允许用户选择同一天、同一周、同一个月。 ```html ``` ## 格式化日期 设置 `formatter` 参数，其值为函数类型，接收一个 `object` 参数，返回一个对象，对象的属性保持跟入参的属性一致，其属性如下： | 属性 | 类型 | 说明 | 最低版本 | | ---------- | --------------- | ------------------------------------------- | -------- | | type | CalendarDayType | 可选值见[CalendarDayType](#calendardaytype) | - | | date | timestamp | 13 位的时间戳 | - | | text | string | 日期文本内容 | - | | topInfo | string | 上方提示信息 | - | | bottomInfo | string | 下方提示信息 | - | | disabled | boolean | 是否禁用 | - | ### CalendarDayType | 类型 | 说明 | 最低版本 | | ----------------- | ------------------------------------ | ---------------- | | selected | 单日期选中 | - | | start | 范围开始日期 | - | | end | 范围结束日期 | - | | middle | 范围开始与结束之间的日期 | - | | same | 范围开始与结束日期同一天 | - | | current | 当前日期 | - | | multiple-middle | 多日期范围选择，开始与结束之间的日期 | 1.5.0 | | multiple-selected | 多日期范围选择，选中的日期 | 1.5.0 | ```html ``` ```typescript const value = ref([]) function handleConfirm({ value }) { console.log(value) } const formatter = (day) => { const date = new Date(day.date) const now = new Date() const year = date.getFullYear() const month = date.getMonth() const da = date.getDate() const nowYear = now.getFullYear() const nowMonth = now.getMonth() const nowDa = now.getDate() if (year === nowYear && month === nowMonth && da === nowDa) { day.topInfo = '今天' } if (month === 5 && da === 18) { day.topInfo = '618大促' } if (month === 10 && da === 11) { day.topInfo = '京东双11' } if (day.type === 'start') { day.bottomInfo = '开始' } if (day.type === 'end') { day.bottomInfo = '结束' } if (day.type === 'same') { day.bottomInfo = '开始/结束' } return day } ``` ## 快捷选项 设置 `shortcuts` 属性，配置快捷选项列表，传入 `on-shortcuts-click` 属性，`on-shortcuts-click` 是个函数，接收 { item, index } 参数，item 为当前选项，index 为当前选项的下标。当快捷选项被点击时，会调用 `on-shortcuts-click`，接收到日历新的选中值。`text` 为选项的必传字段，其他字段根据自己需要自行传入。 ```html ``` ```typescript const shortcuts = ref[]>([ { text: '近7天', id: 7 }, { text: '近15天', id: 15 }, { text: '近30天', id: 30 } ]) const value = ref('') const onShortcutsClick = ({ item }) => { const dayDiff = item.id const endDate = Date.now() - 24 * 60 * 60 * 1000 const startDate = endDate - dayDiff * 24 * 60 * 60 * 1000 return [startDate, endDate] } function handleConfirm({ value }) { console.log(value) } ``` ## 自定义展示 设置 `display-format` 属性可以自定义表单回显，`inner-display-format` 属性自定义范围选择类型的面板内部回显。 `display-format` 为函数，接收 `value`（当前值，type 为范围类型时为时间戳数组，其他类型为 number）、`type`（当前日历类型） 两个参数。 `inner-display-format` 为函数，会调用两次，接收 `value`（开始日期或结束日期，类型为 number）、`rangeType`（'start' - 开始日期, 'end' - 结束日期）、`type`（当前日历类型）三个参数。 ```html ``` ```typescript import { dayjs } from '@/uni_modules/wot-design-uni' const value = ref('') const displayFormat = (value) => { return dayjs(value[0]).format('YY年MM月DD日') + ' - ' + dayjs(value[1]).format('YY年MM月DD日') } const innerDisplayFormat = (value, rangeType) => { if (!value) { return rangeType === 'start' ? '活动开始时间' : '活动结束时间' } return dayjs(value).format('YY年MM月DD日') } function handleConfirm({ value }) { console.log(value) } ``` ## 确定前校验 设置 `before-confirm` 函数，在用户点击`确定`按钮时，会执行 `before-confirm` 函数，并传入 `value` 和 `resolve` 参数，可以对 `value` 进行校验，并通过 `resolve` 函数告知组件是否确定通过，`resolve` 接受 1 个 boolean 值，`resolve(true)` 表示选项通过，`resolve(false)` 表示选项不通过，不通过时不会关闭弹窗。 ```html ``` ```typescript import { useToast } from '@/uni_modules/wot-design-uni' const toast = useToast() const value = ref('') const beforeConfirm = ({ value, resolve }) => { if (value > Date.now()) { toast.error('该日期暂无数据') resolve(false) } else { resolve(true) } } function handleConfirm({ value }) { console.log(value) } ``` ## 最大范围限制 设置 `max-range` 属性，设置范围选择的最大限制。 ```html ``` ## 设置周起始日 设置 `first-day-of-week` 属性，默认为 0，即周日，设置为 1 则为周一，依此类推。 ## 自定义选择器 如果默认的 cell 类型的展示格式不满足需求，可以通过默认插槽进行自定义选择器样式。 ```html 当前选中日期：{{ formatValue }} 选择日期 ``` ```typescript const value = ref('') const formatValue = ref('') function handleConfirm({ value }) { formatValue.value = new Date(value).toString() } ``` ## 使用组件实例方法 通过 ref 可以获取到 Calendar 实例并调用实例方法，通过 `with-cell` 可以屏蔽组件内部的 cell 选择器。 ```html 打开日历 ``` ```typescript import { ref } from 'vue' import type { CalendarInstance } from '@/uni_modules/wot-design-uni/components/wd-calendar/types' const calendar = ref() const value = ref(Date.now()) function openCalendar() { calendar.value?.open() } function closeCalendar() { calendar.value?.close() } function handleConfirm({ value }) { console.log(value) } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------- | --------------------- | ---------------- | | v-model | 选中值，为 13 位时间戳或时间戳数组 | null / number / array | - | - | - | | type | 日期类型 | string | date / dates / datetime / week / month / daterange / datetimerange / weekrange / monthrange | date | - | | min-date | 最小日期，为 13 位时间戳 | number | - | 当前日期往前推 6 个月 | - | | max-date | 最大日期，为 13 位时间戳 | number | - | 当前日期往后推 6 个月 | - | | first-day-of-week | 周起始天 | number | - | 0 | - | | formatter | 日期格式化函数 | function | - | - | - | | max-range | type 为范围选择时有效，最大日期范围 | number | - | - | - | | range-prompt | type 为范围选择时有效，选择超出最大日期范围时的错误提示文案 | string | - | 选择天数不能超过 x 天 | - | | allow-same-day | type 为范围选择时有效，是否允许选择同一天 | boolean | - | false | - | | default-time | 选中日期所使用的当日内具体时刻 | string / array | - | 00:00:00 | - | | time-filter | type 为 'datetime' 或 'datetimerange' 时有效，用于过滤时间选择器的数据 | function | - | - | - | | hide-second | type 为 'datetime' 或 'datetimerange' 时有效，是否不展示秒修改 | boolean | - | false | - | | show-confirm | 是否显示确定按钮 | boolean | - | true | - | | show-type-switch | 是否显示类型切换功能 | boolean | - | false | - | | shortcuts | 快捷选项，为对象数组，其中对象的 `text` 必传 | array | - | - | - | | title | 弹出层标题 | string | - | 选择日期 | - | | label | 选择器左侧文案 | string | - | - | - | | placeholder | 选择器占位符 | string | - | 请选择 | - | | disabled | 禁用 | boolean | - | false | - | | readonly | 只读 | boolean | - | false | - | | display-format | 自定义展示文案的格式化函数，返回一个字符串 | function | - | - | - | | inner-display-format | 自定义范围选择类型的面板内部回显，返回一个字符串 | function | - | - | - | | size | 设置选择器大小 | string | large | - | - | | label-width | 设置左侧标题宽度 | string | - | 33% | - | | error | 是否为错误状态，错误状态时右侧内容为红色 | boolean | - | false | - | | required | 必填样式 | boolean | - | false | - | | center | 是否垂直居中 | boolean | - | false | - | | ellipsis | 是否超出隐藏 | boolean | - | false | - | | align-right | 选择器的值靠右展示 | boolean | - | false | - | | before-confirm | 确定前校验函数，接收 { value, resolve } 参数，通过 resolve 继续执行，resolve 接收 1 个 boolean 参数 | function | - | - | - | | use-default-slot | 使用默认插槽时设置该选项，已废弃直接使用默认插槽即可。 | boolean | - | false | - | | use-label-slot | 使用 label 插槽时设置该选项，已废弃直接使用 label 插槽即可。 | boolean | - | false | - | | close-on-click-modal | 点击遮罩是否关闭 | boolean | - | true | - | | z-index | 弹窗层级 | number | - | 15 | - | | safe-area-inset-bottom | 弹出面板是否设置底部安全距离（iphone X 类型的机型） | boolean | - | true | - | | prop | 表单域 `model` 字段名，在使用表单校验功能的情况下，该属性是必填的 | string | - | - | - | | rules | 表单验证规则，结合`wd-form`组件使用 | `FormItemRule []` | - | `[]` | - | | immediate-change | type 为 'datetime' 或 'datetimerange' 时有，是否在手指松开时立即触发 picker-view 的 change 事件。若不开启则会在滚动动画结束后触发 change 事件，1.2.25 版本起提供，仅微信小程序和支付宝小程序支持。 | boolean | - | false | 1.2.25 | | with-cell | 是否使用内置 cell 选择器 | boolean | - | true | 1.5.0 | ### FormItemRule 数据结构 | 键名 | 说明 | 类型 | | --------- | ------------------------------------------------------- | ------------------------------------- | | required | 是否为必选字段 | `boolean` | | message | 错误提示文案 | `string` | | validator | 通过函数进行校验，可以返回一个 `Promise` 来进行异步校验 | `(value, rule) => boolean \| Promise` | | pattern | 通过正则表达式进行校验，正则无法匹配表示校验不通过 | `RegExp` | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ------------------------------------ | ------------------------ | -------- | | confirm | 绑定值变化时触发 | `{ value, type }` | - | | change | 点击面板日期时触发 | `{ value }` | - | | cancel | 点击关闭按钮或者蒙层时触发 | - | - | | open | 日历打开时触发 | - | - | ## Methods | 方法名称 | 说明 | 参数 | 最低版本 | | -------- | -------- | ---- | -------- | | open | 打开面板 | - | - | | close | 关闭面板 | - | - | ## Slots | name | 说明 | 最低版本 | | ------- | ---------- | -------- | | default | 自定义展示 | - | | label | 左侧插槽 | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------------ | -------------------- | -------- | | custom-class | 根节点样式 | - | | custom-label-class | label 外部自定义样式 | - | | custom-value-class | value 外部自定义样式 | - | --- --- url: 'https://wot-design-uni.cn/component/calendar-view.md' --- # CalendarView 日历面板组件 提供日历单选、多选、范围选择、周维度、月维度等功能。可以根据实际业务场景基于该组件进行封装高度定制化组件。 ## 基本使用 `type` 默认为 `date` 类型，设置 `v-model` 绑定值（13 位时间戳格式），也可以监听 `@change` 事件获取选中值。`min-date` 最小日期默认为当前日期往前推 6 个月，`max-date` 最大日期默认为当前日期往后推 6 个月，日历面板的日期只展示最小日期到最大日期之间的日期。 > `min-date`和`max-date`这两个值尽量不要设置过大，避免大量数据的计算和传递导致页面性能低下。 ```html ``` ```typescript const value = ref(Date.now()) function handleChange({ value }) { console.log(value) } ``` ## 日期多选 设置 `type` 为 `dates` 类型，此时 `value` 为数组。 ```html ``` ```typescript const value = ref([]) function handleChange({ value }) { console.log(value) } ``` ## 周类型选择 设置 `type` 为 `week` 类型，如果 `value` 有初始值，建议将周起始日 `first-day-of-week` 设置为 1（周一），避免选中样式和回显匹配不上。 ```html ``` ```typescript const value = ref(Date.now()) function handleChange({ value }) { console.log(value) } ``` ## 月类型选择 设置 `type` 为 `month` 类型，此时 `value` 有值时其值为月的第一天。 ```html ``` ```typescript const value = ref(Date.now()) function handleChange({ value }) { console.log(value) } ``` ## 范围选择 `type` 支持 `daterange`（日期范围选择）、`weekrange`（周范围选择）、`monthrange`（月范围选择） 类型，此时 `value` 为数组格式。 ```html ``` ```typescript const value = ref([]) function handleChange({ value }) { console.log(value) } ``` ## 日期时间类型 设置 `type` 为 `datetime` 类型，可以选择到时分秒，设置 `type` 为 `datetimerange` 为范围选择。 ```html ``` ```typescript const value = ref('') function handleChange({ value }) { console.log(value) } ``` 可以设置 `hide-second`，使时间只展示到分钟级别；设置 `time-filter` 属性，可以自定义过滤 时分秒 选项，该属性接收 { type: string, values: array } 参数，返回一个新的数组，type 值为 'hour'、'minute' 或 'second'，values 为 picker 数据列表。 ```html ``` ```typescript const value = ref('') const timeFilter = ({ type, values }) => { if (type === 'minute') { // 只展示 0,10,20,30,40,50 分钟选项 return values.filter((item) => { return item % 10 === 0 }) } return values } function handleChange({ value }) { console.log(value) } ``` ## 范围选择允许选中同一日期 设置 `allow-same-day` 属性，范围选择允许用户选择同一天、同一周、同一个月。 ```html ``` ## 格式化日期 设置 `formatter` 参数，其值为函数类型，接收一个 `object` 参数，返回一个对象，对象的属性保持跟入参的属性一致，其属性如下： | 属性 | 类型 | 说明 | 最低版本 | | ---------- | --------------- | ------------------------------------------- | -------- | | type | CalendarDayType | 可选值见[CalendarDayType](#calendardaytype) | - | | date | timestamp | 13 位的时间戳 | - | | text | string | 日期文本内容 | - | | topInfo | string | 上方提示信息 | - | | bottomInfo | string | 下方提示信息 | - | | disabled | boolean | 是否禁用 | - | ### CalendarDayType | 类型 | 说明 | | ----------------- | ------------------------------------ | | selected | 单日期选中 | | start | 范围开始日期 | | end | 范围结束日期 | | middle | 范围开始与结束之间的日期 | | same | 范围开始与结束日期同一天 | | current | 当前日期 | | multiple-middle | 多日期范围选择，开始与结束之间的日期 | | multiple-selected | 多日期范围选择，选中的日期 | ```html ``` ```typescript const value = ref([]) const formatter = (day) => { const date = new Date(day.date) const now = new Date() const year = date.getFullYear() const month = date.getMonth() const da = date.getDate() const nowYear = now.getFullYear() const nowMonth = now.getMonth() const nowDa = now.getDate() if (year === nowYear && month === nowMonth && da === nowDa) { day.topInfo = '今天' } if (month === 5 && da === 18) { day.topInfo = '618大促' } if (month === 10 && da === 11) { day.topInfo = '京东双11' } if (day.type === 'start') { day.bottomInfo = '开始' } if (day.type === 'end') { day.bottomInfo = '结束' } if (day.type === 'same') { day.bottomInfo = '开始/结束' } return day } function handleChange({ value }) { console.log(value) } ``` ## 最大范围限制 设置 `max-range` 属性，设置范围选择的最大限制。 ```html ``` ## 展示面板标题 `show-panel-title` 默认为 `true`，会自动计算标题并进行展示，可以选择不进行展示。 ```html ``` ## 设置周起始日 设置 `first-day-of-week` 属性，默认为 0，即周日，设置为 1 则为周一，依此类推。 ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------- | --------------------- | -------- | | v-model | 选中值，为 13 位时间戳或时间戳数组 | null / number / array | - | - | - | | type | 日期类型 | string | date / dates / datetime / week / month / daterange / datetimerange / weekrange / monthrange | date | - | | min-date | 最小日期，为 13 位时间戳 | number | - | 当前日期往前推 6 个月 | - | | max-date | 最大日期，为 13 位时间戳 | number | - | 当前日期往后推 6 个月 | - | | first-day-of-week | 周起始天 | number | - | 0 | - | | formatter | 日期格式化函数 | function | - | - | - | | max-range | type 为范围选择时有效，最大日期范围 | number | - | - | - | | range-prompt | type 为范围选择时有效，选择超出最大日期范围时的错误提示文案 | string | - | 选择天数不能超过 x 天 | - | | allow-same-day | type 为范围选择时有效，是否允许选择同一天 | boolean | - | false | - | | show-panel-title | 是否展示面板标题，自动计算当前滚动的日期月份 | boolean | - | true | - | | default-time | 选中日期所使用的当日内具体时刻 | string / array | - | 00:00:00 | - | | panel-height | 可滚动面板的高度 | number | - | 378 | - | | time-filter | type 为 'datetime' 或 'datetimerange' 时有效，用于过滤时间选择器的数据 | function | - | - | - | | hide-second | type 为 'datetime' 或 'datetimerange' 时有效，是否不展示秒修改 | boolean | - | false | - | | immediate-change | type 为 'datetime' 或 'datetimerange' 时有，是否在手指松开时立即触发 picker-view 的 change 事件。若不开启则会在滚动动画结束后触发 change 事件，1.2.25 版本起提供，仅微信小程序和支付宝小程序支持。 | boolean | - | false | 1.2.25 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ---------------- | ----------- | -------- | | change | 绑定值变化时触发 | `{ value }` | - | ## Methods | 方法名称 | 说明 | 参数 | 最低版本 | | -------------- | ------------------------------------------------------------------------------------------------------------ | ---- | -------- | | scrollIntoView | 使当前日期或者选中日期滚动到可视区域，并监听滚动，在面板从 隐藏状态（如 display: none） 切换为展示状态时调用 | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/card.md' --- # Card 卡片 用于展示商品的图片、价格等信息。 ## 基本使用 通过 `title` 属性设置标题，默认插槽传入内容。 支持设置 `title` 插槽和 `footer` 插槽。 ```html 一般的，检举内容由承办的党的委员会或纪律检查委员会将处理意见或复议、复查结论同申诉人见面，听取其意见。复议、复查的结论和决定，应交给申诉人一份。 ``` ## 矩形卡片 将`type` 设置为 `rectangle` 。 ```html joy 智催评营销 高级版-快速吸粉 | 周期一年 ``` ```scss .content, .title { display: flex; flex-direction: row; justify-content: flex-start; align-items: center; } .content { justify-content: flex-start; } .title { justify-content: space-between; } .title-tip { color: rgba(0, 0, 0, 0.25); font-size: 12px; } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ----- | -------- | ------ | --------- | ------ | -------- | | title | 卡片标题 | string | - | - | - | | type | 卡片类型 | string | rectangle | - | - | ## Slot | name | 说明 | 最低版本 | | ------- | ------------ | -------- | | default | 卡片内容 | - | | title | 卡片标题 | - | | footer | 底部操作内容 | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | -------------------- | ---------------- | -------- | | custom-class | 根节点自定义样式 | - | | custom-title-class | 标题自定义样式 | - | | custom-content-class | 内容自定义样式 | - | | custom-footer-class | 底部自定义样式 | - | --- --- url: 'https://wot-design-uni.cn/component/cell.md' --- # Cell 单元格 单元格为列表中的单个展示项。 ## 基本用法 `Cell` 可以单独使用，也可以和 `CellGroup` 组合使用。 ```html ``` ## 图标设置 设置 `icon` 属性，值可以为 Icon 章节中的图标名，也可以通过 icon 的 slot 自定义图标位置。 > 自定义图标，如果有多个 cell，需保证所有图标的宽度是一致的且垂直居中。使用 icon 属性且为 Icon 章节的字体图标，则宽度会自动一致且垂直居中；cell 图标的大小是宽 16px，高 16px，large 尺寸图标宽度 18px，高度 18px，距离右侧文字距离 15px。如果使用插槽，可以通过`custom-icon-class`进行设置。 ```html ``` ```scss .cell-icon { display: block; box-sizing: border-box; width: 16px; height: 16px; margin-right: 4px; background: url('https://img10.360buyimg.com/jmadvertisement/jfs/t1/71075/7/3762/1820/5d1f26d1E0d600b9e/a264c901943080ac.png') no-repeat; background-size: cover; } ``` ## 分组标题 可以在 `cell-group` 上设置 `title` 和 `value` 属性。 ```html ``` ## 单元格大小 通过设置 `size` 修改单元格大小，将 `size` 设置为 'large' 时左侧标题字号为 16px。 ```html ``` ## 展示边框线 在 `wd-cell-group` 上设置 `border` 属性，会给每个 cell 加上边框，最后一个 cell 则不展示边框，其他具有 `cell` 类型的表单组件也支持边框展示，如 input、picker。 ```html ``` ## 点击反馈 通过设置 `clickable` 开启点击反馈，之后可以监听`click`事件。 ```html ``` ```typescript import { useToast } from '@/uni_modules/wot-design-uni' const toast = useToast() function showToast() { toast.show('点击') } ``` ## 页面跳转 通过设置 `is-link` 属性显示导航箭头和点击态，设置 `to` 属性，指定跳转地址，可以设置 replace 替换掉历史堆栈中的当前页面。 `is-link`会默认开启`clickable`。 ```html ``` 可以只设置 `is-link` 用于展示右箭头和点击态。 ```html ``` ## 垂直居中 通过设置 `center` 设置内容垂直居中对齐，默认顶部居中。 ```html ``` ## 表单属性 - 必填 设置 `required` 属性。 ```html ``` ```typescript const rate = ref(0) function handleRateChange({ value }) { console.log(value) } ``` ## 表单属性 - 上下结构 设置 `vertical` 属性。 ```html ``` ```typescript const slider = ref('') function handleSliderChange({ value }) { console.log(value) } ``` ## 设置左侧宽度 设置 `title-width` 属性，label 内容超出则会 ... 隐藏，如果有个性化需求，使用插槽实现。 ```html ``` ## 自定义内容 `cell` 提供了 `icon`、`title`、`label`和默认 value 的插槽。 ```html 按钮 订购 ``` ```typescript const switchValue = ref('') function handleSwitchChange({ value }) { console.log(value) } ``` ```scss .cell-icon { display: block; box-sizing: border-box; padding: 4px 0; width: 16px; height: 24px; margin-right: 4px; background: url('https://img10.360buyimg.com/jmadvertisement/jfs/t1/71075/7/3762/1820/5d1f26d1E0d600b9e/a264c901943080ac.png') no-repeat; background-size: cover; } :deep(.custom-value) { position: absolute; top: 50%; right: 0; transform: translate(0, -50%); white-space: nowrap; } .custom-text { color: #f0883a; } .end-time { display: inline-block; margin-left: 8px; border: 1px solid #faa21e; padding: 0 4px; font-size: 10px; color: #faa21e; } ``` ## CellGroup Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | -------- | -------------- | ------- | ------ | ------ | -------- | | title | 分组标题 | string | - | - | - | | value | 分组右侧内容 | string | - | - | - | | border | 是否展示边框线 | boolean | - | - | - | | use-slot | 分组启用插槽 | boolean | - | false | - | ## Cell Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ----------- | ------------------------------ | ------- | ------ | ------ | -------- | | title | 标题 | string | - | - | - | | value | 右侧内容 | string | - | - | - | | icon | 图标类名 | string | - | - | - | | label | 描述信息 | string | - | - | - | | is-link | 是否为跳转链接 | boolean | - | false | - | | to | 跳转地址 | string | - | - | - | | clickable | 点击反馈，开启 is-link 时，默认开启此选项 | boolean | - | false | - | | replace | 跳转时是否替换栈顶页面 | boolean | - | false | - | | size | 设置单元格大小 | string | large | - | - | | title-width | 设置左侧标题宽度 | string | - | - | - | | center | 是否垂直居中，默认顶部居中 | boolean | - | false | - | | required | 表单属性，必填 | boolean | - | false | - | | vertical | 表单属性，上下结构 | boolean | - | false | - | | prop | 表单域 `model` 字段名，在使用表单校验功能的情况下，该属性是必填的 | string | - | - | - | | rules | 表单验证规则，结合`wd-form`组件使用 | `FormItemRule []` | - | `[]` | - | | border | 是否展示边框线，优先级高于`cell-group`的`border` | boolean | - | - | - | ### FormItemRule 数据结构 | 键名 | 说明 | 类型 | | --- | --- | --- | | required | 是否为必选字段 | `boolean` | | message | 错误提示文案 | `string` | | validator | 通过函数进行校验，可以返回一个 `Promise` 来进行异步校验 | `(value, rule) => boolean \| Promise` | | pattern | 通过正则表达式进行校验，正则无法匹配表示校验不通过 | `RegExp` | ## Cell Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ------------------------------------------------ | ---- | -------- | | click | 当 clickable 或 is-link 为 true 时点击单元格触发 | - | - | ## CellGroup Slot > CellGroup 必须首先开启`use-slot`,插槽才生效。使用插槽时请通过外部自定义样式类来控制样式。 | name | 说明 | 最低版本 | | ----- | ------------ | -------- | | title | 分组标题 | - | | value | 分组右侧内容 | - | ## Cell Slot | name | 说明 | 最低版本 | | ------- | ----------------------------------------- | -------- | | title | 标题 | - | | default | 右侧内容，使用时不需要设置 `#default` | - | | icon | 图标 | - | | label | 描述信息 | - | ## CellGroup 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | ## Cell 外部样式类 | 类名 | 说明 | 最低版本 | | ------------------ | ------------------------------ | -------- | | custom-class | 根节点样式 | - | | custom-icon-class | icon 外部自定义样式 | - | | custom-label-class | label 外部自定义样式 | - | | custom-value-class | value 外部自定义样式 | - | | custom-title-class | title 外部自定义样式 | - | --- --- url: 'https://wot-design-uni.cn/component/checkbox.md' --- # Checkbox 复选框 复选框用于在一组备选项中进行多选。 ## 基本用法 通过 `v-model` 绑定复选框的勾选状态，单独使用时值为 `boolean` 类型。 ```html 单选框1 ``` ```typescript const value = ref(true) function handleChange({ value }) { console.log(value) } ``` ## 修改图标形状 修改 `shape` 属性，可选值为 'circle'、'square'、'button'，默认为 'circle'。 ```html 沃特 沃特 ``` ## 修改选中的颜色 设置 `checked-color` 属性。 ```html 沃特 ``` ```typescript const value = ref(true) ``` ## 修改选中和非选中的值 设置 `true-value` 和 `false-value` 修改选中值和非选中值。如果不设置，`change`事件的参数 默认为 `true` 和 `false` 切换。 ```html 复选框 ``` ## 复选框组 通过 `v-model` 绑定复选框的勾选状态。 ```html 沃特 商家后台 ``` ```typescript const value = ref([]) ``` 设置 `cell` 属性，开启表单模式复选框组。 ```html 沃特 商家后台 ``` 开启表单模式时，如果同时设置 `shape` 为 `button` 自动开启表单复选按钮组模式。 ```html 选项一 选项二 选项三 选项四 选项五 选项六 选项七 ``` ```typescript const value = ref(['jingmai']) const value1 = ref(['jingmai']) const value2 = ref(['1']) ``` ## 同行展示 设置 `inline` 属性，使复选框在同一行展示。 ```html 沃特 商家后台 ``` ```typescript const value = ref(['jingmai']) ``` ## 禁用 可以在 `checkbox-group` 上面设置 `disabled`，禁用所有复选框，也可以在单个复选框上面设置 `disabled` 属性，禁用某个复选框。 ```html 沃特 商家后台 ``` ```typescript const value = ref(['jingmai']) ``` ## 设置选中数量的上限和下限 `min` 属性设置最小选中的数量，`max` 属性设置最大选中的数量。如果要默认设置某个选项固定被选中，则给该复选框设置 disabled，且 `value` 中有该选项的值。 ```html 京东 沃特 商家后台 营销中心 ``` ```typescript const value = ref(['jd']) ``` ## 尺寸 设置 `size` 属性，可选 `large`。 ```html 沃特 商家后台 ``` ## 结合 Cell 使用 通过 `Checkbox` 实例上的 `toggle` 方法触发选中状态切换。 ```html ``` ```ts import { ref } from 'vue' const value = ref([]) const checkBox1 = ref() const checkBox2 = ref() const checkBox3 = ref() function handleCheck1() { checkBox1.value && checkBox1.value.toggle() } function handleCheck2() { checkBox2.value && checkBox2.value.toggle() } function handleCheck3() { checkBox3.value && checkBox3.value.toggle() } function noop() {} ``` ## Checkbox Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------- | -------------------------------------------------------------------- | ------------------------- | ------------------------ | ------- | -------- | | v-model | 单选框选中时的值 | string / number / boolean | - | - | - | | shape | 单选框形状 | string | circle / square / button | circle | - | | checked-color | 选中的颜色 | string | - | #4D80F0 | - | | disabled | 禁用 | boolean | - | false | - | | max-width | 文字位置最大宽度 | string | - | - | - | | true-value | 选中值，在 checkbox-group 中使用无效，需同 false-value 一块使用 | string / number | - | true | - | | false-value | 非选中时的值，在 checkbox-group 中使用无效，需同 true-value 一块使用 | string /number | - | false | - | | size | 设置大小 | string | large | - | - | ## CheckboxGroup Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------- | -------------------------------------- | ------- | ------------------------ | ------- | -------- | | v-model | 绑定值 | Array | - | - | - | | shape | 单选框形状 | string | circle / square / button | circle | - | | cell | 表单模式 | boolean | - | false | - | | checked-color | 选中的颜色 | string | - | #4D80F0 | - | | disabled | 禁用 | boolean | - | false | - | | min | 最小选中的数量 | number | - | 0 | - | | max | 最大选中的数量，0 为无限数量，默认为 0 | number | - | 0 | - | | inline | 同行展示 | boolean | - | false | - | | size | 设置大小 | string | large | - | - | ## Checkbox Methods | 方法名称 | 说明 | 参数 | 最低版本 | | -------- | ------------------------------------- | ---- | -------- | | toggle | 切换当前选中状态,同时触发 change 事件 | - | 1.2.16 | ## Checkbox Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | -------------------------------------------------------------------- | ----------- | -------- | | change | 绑定值变化时触发，当为复选框组时参数为 boolean，表示该复选框是否选中 | `{ value }` | - | ## CheckboxGroup Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ---------------- | ----------- | -------- | | change | 绑定值变化时触发 | `{ value }` | - | ## Checkbox 外部样式类 | 类名 | 说明 | 最低版本 | | ------------------ | ---------------- | -------- | | custom-class | 根节点样式 | - | | custom-label-class | 文字结点样式 | - | | custom-shape-class | 单选图标结点样式 | - | ## CheckboxGroup 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/circle.md' --- # Circle 环形进度条 0.1.19 圆环形的进度条组件，支持进度渐变动画。 ## 基础用法 通过`v-model`表示进度条的当前进度，`text`属性控制进度条中间文字内容。 ```html ``` ```ts const current = ref(10) ``` ## 宽度控制 通过`strokeWidth`属性来控制进度条宽度，默认`10px`。 ```html ``` ## 颜色定制 通过`color`属性控制进度条颜色，默认`#1C64FD`，通过`layerColor`属性控制进度条轨道颜色，默认`#EBEEF5`。 ```html ``` ## 渐变色 `color`属性支持传入对象格式来定义渐变色。 ```html ``` ```ts const gradientColor = { '0%': '#ffd01e', '100%': '#ee0a24' } ``` ## 进度条展开方向 通过`clockwise`属性控制进度条展开方向，`clockwise`为`false`时，进度会从逆时针方向开始。 ```html ``` ## 大小定制 通过`size`属性控制进度条圆环直径，默认`100px`。 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ----------------- | ---------------------------- | --------------------------- | ------------------------------------------ | --------------- | -------- | | `v-model` / `modelValue` | 当前进度 | number | - | `0` | 0.1.19 | | `customClass` | 自定义class | string | - | - | 0.1.19 | | `customStyle` | 自定义style | string | - | - | 0.1.19 | | `size` | 圆环直径，默认单位为 px | number | - | `100` | 0.1.19 | | `color` | 进度条颜色 | string / Record\ | - | `#4d80f0` | 0.1.19 | | `layerColor` | 轨道颜色 | string | - | `#EBEEF5` | 0.1.19 | | `fill` | 填充颜色 | string | - | `#ffffff` | 0.1.19 | | `speed` | 动画速度（单位为 rate/s） | number | - | `50` | 0.1.19 | | `text` | 文字 | string | - | - | 0.1.19 | | `strokeWidth` | 进度条宽度，单位px | number | - | `10` | 0.1.19 | | `strokeLinecap` | 进度条端点的形状 | string | `butt` / `round` / `square` | `round` | 0.1.19 | | `clockwise` | 是否顺时针增加 | boolean | - | `true` | 0.1.19 | ## Circle 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/collapse.md' --- # Collapse 折叠面板 将一组内容放置在多个折叠面板中，点击面板的标题可以展开或收缩其内容。 ## 基本使用 `v-model` 为绑定值，可以为 array 类型（普通折叠）、 string 类型（手风琴）和 boolean 类型（收起展开查看更多）。CollapseItem 的 `name` 为必填, `title` 选填且可通过 `slot` 自定义。`name` 用于标识该折叠栏。 ```typescript const value = ref(['item1']) ``` ```html 这是一条简单的示例文字。 这是一条简单的示例文字。 这是一条简单的示例文字。 ``` ```css .header { display: flex; align-items: center; justify-content: space-between; } ``` ## 手风琴 设置 `accordion` 属性。 ```html 这是一条简单的示例文字。 这是一条简单的示例文字。 这是一条简单的示例文字。 ``` ## 禁用 给 CollapseItem 设置 `disabled` 属性，禁用某个折叠栏。 ```html 这是一条简单的示例文字。 这是一条简单的示例文字。 这是一条简单的示例文字。 ``` ## 异步更新 通过给`wd-collapse-item`组件传入 `beforeExpend` 函数可以在打开面板前进行校验和处理，返回 true 表示允许打开，返回 false 表示禁止打开。支持返回 Promise 进行例如调用接口获取面板数据的操作。 ```html {{ item.body }} ``` ```ts import { useToast } from '@/uni_modules/wot-design-uni' const toast = useToast() const value = ref(['item1']) const itemList = ref[]>([ { title: '标签1', name: 'item1', body: '如订单处于暂停状态，进入“我的订单”页面，找到要取消的订单，点击“取消订单”按钮；选择订单取消原因后，点击“下一步”提交申请即可。' }, { title: '标签1', name: 'item2', body: '一般情况下，买家只能向商户申请退款，商户确认可以退款后，可以通过接口或者商户平台向微信支付发起退款申请。' }, { title: '标签1', name: 'item3', body: '将收到的有质量问题的商品照片或者订单截图上传到微信公众账号（微信关注联华华商公众号），我们的工作人员会尽快帮您处理。' }, { title: '标签1', name: 'item4', body: '七天无理由退换货制度，所有商品在不影响二次销售的情况下7天内（以快递单签收为准）均接受客户退换货。' }, { title: '标签1', name: 'item5', body: 'Q1:优惠券使用详情？详情页面【我的】-【我的优惠】-【优惠券规则说明】。' } ]) /** * 折叠面板展开前回调方法 * @param e */ function beforeExpend(name) { const index = itemList.value.findIndex((item) => { return item.name === name }) if (index > -1) { itemList.value[index].body = 'Q1:七天无理由退换货制度，所有商品在不影响二次销售的情况下7天内（以快递单签收为准）均接受客户退换货。七天无理由退换货制度，所有商品在不影响二次销售的情况下7天内（以快递单签收为准）均接受客户退换货。七天无理由退换货制度，所有商品在不影响二次销售的情况下7天内（以快递单签收为准）均接受客户退换货。七天无理由退换货制度，所有商品在不影响二次销售的情况下7天内（以快递单签收为准）均接受客户退换货。七天无理由退换货制度，所有商品在不影响二次销售的情况下7天内（以快递单签收为准）均接受客户退换货。七天无理由退换货制度，所有商品在不影响二次销售的情况下7天内（以快递单签收为准）均接受客户退换货。' } return new Promise((reslove, reject) => { toast.loading('加载中') setTimeout(() => { toast.close() reslove(true) }, 500) }) } ``` ## 查看更多 Collapse 可以单独使用，通过设置 `viewmore` 属性，将其转化为查看更多的折叠类型，同时可以设置 `line-num` 修改收起时的显示行数。这时候的 `value` 为 boolean 类型。 ```html 这是一条简单的示例文字。这是一条简单的示例文字。这是一条简单的示例文字。这是一条简单的示例文字。这是一条简单的示例文字。这是一条简单的示例文字。这是一条简单的示例文字。这是一条简单的示例文字。 ``` ## 查看更多-使用插槽 Collapse 查看更多的模式下，可以使用插槽定义自己想要的折叠处样式，使用 `use-more-slot` 设置插槽开启。并且可以使用外部样式类 `custom-more-slot-class` 为自定义插槽设置样式。 ```scss :deep(.more-slot) { color: red; } ``` ```html 具名插槽：这是一条简单的示例文字。这是一条简单的示例文字。这是一条简单的示例文字。这是一条简单的示例文字。这是一条简单的示例文字。这是一条简单的示例文字。这是一条简单的示例文字。这是一条简单的示例文字。 ``` ## 嵌套使用 `collapse`可以嵌套使用，同时由于`collapse-item`的内容容器存在默认的`padding`，所以嵌套的`collapse`需要设置`custom-body-style`或者`custom-body-class`来覆盖默认样式。 ***以下为示例，也可以自行调整样式。*** :::tip 注意 `custom-body-style`和`custom-body-class`在`1.4.0`及以上版本支持。 ::: ```html {{ item.body }} ``` ```css .collapse { :deep() { .no-border { &::after { display: none; } } } } ``` ```ts const collapseRoot = ref(['0']) const collapseList = ref>([['item1'], ['item2'], ['item3'], ['item4'], ['item5']]) ``` ## CollapseItem Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------- | ----------------------------------------------------------- | -------- | ------ | ------ | -------- | | name | 折叠栏的标识符 | string | - | - | - | | title | 折叠栏的标题, 支持同名 slot 自定义内容 | string | - | '' | - | | disabled | 禁用折叠栏 | boolean | - | false | - | | before-expend | 打开前的回调函数，返回 false 可以阻止打开，支持返回 Promise | Function | - | - | - | ### `before-expend` 执行时会传递以下回调参数： | 参数名 | 说明 | 类型 | | ------ | ---------- | -------- | | name | 唯一标识符 | `String` | ## Collapse Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ----------- | ------------------------------------ | ------------------------ | ------ | ------ | -------- | | value | 绑定值 | string / array / boolean | - | - | - | | accordion | 手风琴 | boolean | - | false | - | | viewmore | 查看更多的折叠面板 | boolean | - | false | - | | useMoreSlot | 查看更多的自定义插槽使用标志 | boolean | - | false | - | | line-num | 查看更多的折叠面板，收起时的显示行数 | number | - | 2 | - | ## Collapse Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ---------------- | ----------- | -------- | | change | 绑定值变化时触发 | `{ value }` | - | ## Methods | 方法名 | 说明 | 参数 | 最低版本 | | --------- | -------------------------------------------------------------------------------- | ------------------------------------ | -------- | | toggleAll | 切换所有面板展开状态，传 `true` 为全部展开，`false` 为全部收起，不传参为全部切换 | `options?: CollapseToggleAllOptions` | 0.2.6 | ### CollapseToggleAllOptions 参数说明 | 参数名 | 说明 | 类型 | 默认值 | | ------------ | ----------------------------------- | ------- | ------ | | expanded | 是否展开，true 为展开，false 为收起 | boolean | - | | skipDisabled | 是否跳过禁用项 | boolean | false | ### toggleAll 方法示例 ```html ... ``` ```ts import { ref } from 'vue' import type { CollapseInstance } from '@/uni_modules/wot-design-uni/components/wd-collapse/types' const collapseRef = ref() // 全部切换 collapseRef.value?.toggleAll() // 全部展开 collapseRef.value?.toggleAll(true) // 全部收起 collapseRef.value?.toggleAll(false) // 全部全部切换，并跳过禁用项 collapseRef.value?.toggleAll({ skipDisabled: true }) // 全部选中，并跳过禁用项 collapseRef.value?.toggleAll({ expanded: true, skipDisabled: true }) ``` ## Collapse Slot | name | 说明 | 最低版本 | | ----- | ---------------------------------------------------- | -------- | | title | 标题，便于开发者自定义标题（非 viewmore 使用） | 1.2.27 | | more | 查看更多，便于开发者自定义查看更多类型的展开收起样式 | - | ## CollapseItem 外部样式类 | 类名 | 说明 | 最低版本 | | ----------------- | ------------------------------ | ---------------- | | custom-class | collapseItem 根节点样式 | - | | custom-body-style | 自定义折叠面板内容容器的样式 | 1.4.0 | | custom-body-class | 自定义折叠面板内容容器的样式类 | 1.4.0 | ## Collapse 外部样式类 | 类名 | 说明 | 最低版本 | | ---------------------- | ---------------------------------- | -------- | | custom-class | collapse 根节点样式 | - | | custom-more-slot-class | 查看更多模式下的插槽外部自定义样式 | - | --- --- url: 'https://wot-design-uni.cn/component/col-picker.md' --- # ColPicker 多列选择器 使用多列选择器来做级联，交互效果较好，多列选择器支持无限级选择。 ::: tip 提示 多列选择器常用于选择省市区，我们使用 Vant 提供的中国省市区数据作为数据源，你可以安装 [@vant/area-data](https://github.com/youzan/vant/tree/main/packages/vant-area-data) npm 包来引入： ```bash # 通过 npm npm i @vant/area-data # 通过 yarn yarn add @vant/area-data # 通过 pnpm pnpm add @vant/area-data # 通过 Bun bun add @vant/area-data ``` ::: ***为了方便开发者使用`@vant/area-data`进行开发调试，我们封装了`useColPickerData`，你可以直接使用`useColPickerData`来获取数据源。*** ::: details 基于@vant/area-data 包装的`useColPickerData` ```typescript // 可以将此代码放置于项目src/hooks/useColPickerData.ts中 import { useCascaderAreaData } from '@vant/area-data' export type CascaderOption = { text: string value: string children?: CascaderOption[] } /** * 使用'@vant/area-data'作为数据源，构造ColPicker组件的数据 * @returns */ export function useColPickerData() { // '@vant/area-data' 数据源 const colPickerData: CascaderOption[] = useCascaderAreaData() // 根据code查找子节点，不传code则返回所有节点 function findChildrenByCode(data: CascaderOption[], code?: string): CascaderOption[] | null { if (!code) { return data } for (const item of data) { if (item.value === code) { return item.children || null } if (item.children) { const childrenResult = findChildrenByCode(item.children, code) if (childrenResult) { return childrenResult } } } return null } return { colPickerData, findChildrenByCode } } ``` ::: ## 基本用法 `label` 设置左侧文本内容； `columns` 设置数据源，为二维数组，每一列为一个一维数组，每个选项包含 `value`(选项值) 和 `label`(选项名称)。 `v-model` 设置选中项的值，数据类型为数组； 也可以监听 `change` 事件，获取选中值，`event` 是个对象，包含 `value`(选中值数组)、`selectedItems`（选中项对象数组）两个属性。 传入 `column-change` 属性，其类型为 `function`，接收参数 options: object；options 的结构如下： | 参数 | 类型 | 说明 | 最低版本 | | ------------ | -------- | ---------------------------------------------------------------------- | -------- | | selectedItem | object | 当前列的选中项，数据结构跟 columns 中选项的数据结构一致 | - | | index | number | 当前列下标 | - | | rowIndex | number | 当前列选中项下标 | - | | resolve | function | 接收下一列的选项数组 | - | | finish | function | 结束 picker 选择，若无法正常关闭如数据获取失败，则执行 `finish(false)` | - | ```html ``` ```typescript // useColPickerData可以参考本章节顶部的介绍 // 导入路径根据自己实际情况调整，万不可一贴了之 import { useColPickerData } from '@/hooks/useColPickerData' const { colPickerData, findChildrenByCode } = useColPickerData() const value = ref([]) const area = ref([ colPickerData.map((item) => { return { value: item.value, label: item.text } }) ]) const columnChange = ({ selectedItem, resolve, finish }) => { const areaData = findChildrenByCode(colPickerData, selectedItem.value) if (areaData && areaData.length) { resolve( areaData.map((item) => { return { value: item.value, label: item.text } }) ) } else { finish() } } function handleConfirm({ value }) { console.log(value) } ``` ## 异步加载 一般 column-change 是个异步获取数据的操作，触发 column-change 组件会有默认 loading，数据响应后关闭 loading。 异步请求数据失败，则调用 `finish(false)`。 ```html ``` ```typescript // useColPickerData可以参考本章节顶部的介绍 // 导入路径根据自己实际情况调整，万不可一贴了之 import { useColPickerData } from '@/hooks/useColPickerData' const { colPickerData, findChildrenByCode } = useColPickerData() const value = ref([]) const area = ref([ colPickerData.map((item) => { return { value: item.value, label: item.text } }) ]) const columnChange = ({ selectedItem, resolve, finish }) => { // 模拟异步请求 setTimeout(() => { // 模拟请求失败 if (Math.random() > 0.7) { finish(false) toast.error.error('数据请求失败，请重试') return } // 这里为什么用selectedItem.value作为code呢？是因为area构造的时候就是将标识放到了value字段上，同理你也可以改为其他字段，只要和area的字段对应即可 const areaData = findChildrenByCode(colPickerData, selectedItem.value) if (areaData && areaData.length) { resolve( areaData.map((item) => { return { value: item.value, label: item.text } }) ) } else { // 没有下一项时，执行完成 finish() } }, 300) } function handleConfirm({ value }) { console.log(value) } ``` ## 初始选项 初始选项有两种方式： 1）设置初始选项时，`columns` 的数组长度应与 `value` 的数组长度一致，`value` 每一列的值必须对应可以在 `columns` 中找到。 ```html ``` ```typescript // useColPickerData可以参考本章节顶部的介绍 // 导入路径根据自己实际情况调整，万不可一贴了之 import { useColPickerData } from '@/hooks/useColPickerData' const { colPickerData, findChildrenByCode } = useColPickerData() const value = ref(['150000', '150100', '150121']) const area = ref([ colPickerData.map((item) => { return { value: item.value, label: item.text } }), findChildrenByCode(colPickerData, '150000')!.map((item) => { return { value: item.value, label: item.text } }), findChildrenByCode(colPickerData, '150100')!.map((item) => { return { value: item.value, label: item.text } }) ]) const columnChange = ({ selectedItem, resolve, finish }) => { const areaData = findChildrenByCode(colPickerData, selectedItem.value) if (areaData && areaData.length) { resolve( areaData.map((item) => { return { value: item.value, label: item.text } }) ) } else { finish() } } function handleConfirm({ value }) { console.log(value) } ``` 2）设置 `auto-complete` 属性，当 `columns` 数组长度为 0 时，会自动触发 `columnChange` 函数来补齐数据。设置了该属性后，因为数据需要动态补全，因此 传递出来的参数 selectedItem 只有 value 字段，没有 label 字段。 ```html ``` ```typescript // useColPickerData可以参考本章节顶部的介绍 // 导入路径根据自己实际情况调整，万不可一贴了之 import { useColPickerData } from '@/hooks/useColPickerData' const { colPickerData, findChildrenByCode } = useColPickerData() import { useToast } from '@/uni_modules/wot-design-uni' const toast = useToast() const value = ref([]) const area = ref([]) onMounted(async () => { toast.loading('数据加载中') // 模拟异步请求 await sleep() toast.close() value.value = ['150000', '150100', '150121'] }) const columnChange: ColPickerColumnChange = async ({ selectedItem, resolve, finish }) => { // 模拟异步请求 await sleep(0.3) const areaData = findChildrenByCode(colPickerData, selectedItem.value) if (areaData && areaData.length) { resolve( areaData.map((item) => { return { value: item.value, label: item.text } }) ) } else { finish() } } function sleep(second: number = 1) { return new Promise((resolve) => { setTimeout(() => { resolve(true) }, 1000 * second) }) } ``` ## 禁用 设置 `disabled` 属性。 ```html ``` ## 只读 设置 `readonly` 属性。 ```html ``` ## 禁用选项 `columns` 每个选项支持 `disabled` 属性。 ```html ``` ```typescript // useColPickerData可以参考本章节顶部的介绍 // 导入路径根据自己实际情况调整，万不可一贴了之 import { useColPickerData } from '@/hooks/useColPickerData' const { colPickerData, findChildrenByCode } = useColPickerData() const value = ref([]) const area = ref([ colPickerData.map((item) => { return { value: item.value, label: item.text, disabled: item.value === '140000' } }) ]) const columnChange = ({ selectedItem, resolve, finish }) => { const areaData = findChildrenByCode(colPickerData, selectedItem.value) if (areaData && areaData.length) { resolve( areaData.map((item) => { return { value: item.value, label: item.text } }) ) } else { finish() } } ``` ## 选项提示信息 `columns` 每个选项支持 `tip` 属性。 ```html ``` ```typescript // useColPickerData可以参考本章节顶部的介绍 // 导入路径根据自己实际情况调整，万不可一贴了之 import { useColPickerData } from '@/hooks/useColPickerData' const { colPickerData, findChildrenByCode } = useColPickerData() const value = ref([]) const area = ref([ colPickerData.map((item) => { return { value: item.value, label: item.text, disabled: item.value === '140000', tip: item.value === '140000' ? '该地区无货，暂时无法选择' : item.value === '150000' ? '该地区配送时间可能较长' : '' } }) ]) const columnChange = ({ selectedItem, resolve, finish }) => { const areaData = findChildrenByCode(colPickerData, selectedItem.value) if (areaData && areaData.length) { resolve( areaData.map((item) => { return { value: item.value, label: item.text } }) ) } else { finish() } } ``` ## 展示格式化 设置 `display-format` 属性，其类型为 `function`，接收当前选中项（数组，数组成员的格式同 columns 数组成员的格式），返回要展示的字符串。 ```html ``` ```typescript // useColPickerData可以参考本章节顶部的介绍 // 导入路径根据自己实际情况调整，万不可一贴了之 import { useColPickerData } from '@/hooks/useColPickerData' const { colPickerData, findChildrenByCode } = useColPickerData() const value = ref(['130000', '130200', '130204']) const area = ref([ colPickerData.map((item) => { return { value: item.value, label: item.text } }), findChildrenByCode(colPickerData, '130000')!.map((item) => { return { value: item.value, label: item.text } }), findChildrenByCode(colPickerData, '130200')!.map((item) => { return { value: item.value, label: item.text } }) ]) const columnChange = ({ selectedItem, resolve, finish }) => { const areaData = findChildrenByCode(colPickerData, selectedItem.value) if (areaData && areaData.length) { resolve( areaData.map((item) => { return { value: item.value, label: item.text } }) ) } else { finish() } } // 格式化方法 const displayFormat = (selectedItems: Record[]) => { return selectedItems[selectedItems.length - 2].label + '-' + selectedItems[selectedItems.length - 1].label } ``` ## 设置标题 设置 `title` 属性，修改弹出层的标题。 ```html ``` ## 确定前校验 设置 `before-confirm` 函数，在用户点击`确定`按钮时，会执行 `before-confirm` 函数，并传入 `value`、`selectedItems`(选中项数组，数据结构同 columns 每一列的选项) 和 `resolve` 参数，可以对 `value` 进行校验，并通过 `resolve` 函数告知组件是否确定通过，`resolve` 接受 1 个 boolean 值，`resolve(true)` 表示选项通过，`resolve(false)` 表示选项不通过，不通过时不会关闭弹窗。 ```html ``` ```typescript // useColPickerData可以参考本章节顶部的介绍 // 导入路径根据自己实际情况调整，万不可一贴了之 import { useColPickerData } from '@/hooks/useColPickerData' const { colPickerData, findChildrenByCode } = useColPickerData() const value = ref([]) const area = ref([ colPickerData.map((item) => { return { value: item.value, label: item.text } }) ]) const columnChange = ({ selectedItem, resolve, finish }) => { const areaData = findChildrenByCode(colPickerData, selectedItem.value) if (areaData && areaData.length) { resolve( areaData.map((item) => { return { value: item.value, label: item.text } }) ) } else { finish() } } const beforeConfirm = (value: (string | number)[], selectedItems: Record[], resolve: (isPass: boolean) => void) => { if (parseInt(String(value[2])) > 120000) { toast.error('该地区库存不足') resolve(false) } else { resolve(true) } } function handleConfirm({ selectedItems }: any) { displayValue.value = selectedItems .map((item: any) => { return item.label }) .join('') } ``` ## 错误状态 设置 `error` 属性，选择器的值显示为红色。 ```html ``` ## 必填样式 设置 `required` 属性，展示必填样式。 ```html ``` ## 选择器大小 通过设置 `size` 修改选择器大小，将 `size` 设置为 'large' 时字号为 16px。 ```html ``` ## 值靠右展示 设置 `align-right` 属性，选择器的值靠右展示。 ```html ``` ## 自定义选择器 如果默认的 cell 类型的展示格式不满足需求，可以通过默认插槽进行自定义选择器样式。在标签上添加 use-default-slot 属性并设置为 true。 ```html 当前选中项: {{ displayValue }} 选择地址 ``` ```typescript // useColPickerData可以参考本章节顶部的介绍 // 导入路径根据自己实际情况调整，万不可一贴了之 import { useColPickerData } from '@/hooks/useColPickerData' const { colPickerData, findChildrenByCode } = useColPickerData() const value = ref([]) const displayValue = ref('') const area = ref([ colPickerData.map((item) => { return { value: item.value, label: item.text } }) ]) const columnChange = ({ selectedItem, resolve, finish }) => { const areaData = findChildrenByCode(colPickerData, selectedItem.value) if (areaData && areaData.length) { resolve( areaData.map((item) => { return { value: item.value, label: item.text } }) ) } else { finish() } } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ------ | ------- | -------- | | v-model | 选中项 | array | - | - | - | | columns | 选择器数据，二维数组 | array | - | - | - | | value-key | 选项对象中，value 对应的 key | string | - | value | - | | label-key | 选项对象中，展示的文本对应的 key | string | - | label | - | | tip-key | 选项对象中，提示文案对应的 key | string | - | tip | - | | title | 弹出层标题 | string | - | - | - | | label | 选择器左侧文案 | string | - | - | - | | placeholder | 选择器占位符 | string | - | 请选择 | - | | disabled | 禁用 | boolean | - | false | - | | readonly | 只读 | boolean | - | false | - | | display-format | 自定义展示文案的格式化函数，返回一个字符串 | function | - | - | - | | column-change | 接收当前列的选中项 item、当前列下标、当前列选中项下标下一列数据处理函数 resolve、结束选择 finish | function | - | - | - | | size | 设置选择器大小 | string | large | - | - | | label-width | 设置左侧标题宽度 | string | - | 33% | - | | error | 是否为错误状态，错误状态时右侧内容为红色 | boolean | - | false | - | | required | 必填样式 | boolean | - | false | - | | align-right | 选择器的值靠右展示 | boolean | - | false | - | | before-confirm | 确定前校验函数，接收 (value, resolve) 参数，通过 resolve 继续执行 picker，resolve 接收 1 个 boolean 参数 | function | - | - | - | | loading-color | loading 图标的颜色 | string | - | #4D80F0 | - | | use-default-slot | 使用默认插槽时设置该选项 | boolean | - | false | - | | use-label-slot | 使用 label 插槽时设置该选项 | boolean | - | false | - | | close-on-click-modal | 点击遮罩是否关闭 | boolean | - | true | - | | auto-complete | 自动触发 column-change 事件来补全数据，当 columns 为空数组或者 columns 数组长度小于 value 数组长度时，会自动触发 column-change | - | false | - | | z-index | 弹窗层级 | number | - | 15 | - | | safe-area-inset-bottom | 弹出面板是否设置底部安全距离（iphone X 类型的机型） | boolean | - | true | - | | ellipsis | 是否超出隐藏 | boolean | - | false | - | | prop | 表单域 `model` 字段名，在使用表单校验功能的情况下，该属性是必填的 | string | - | - | - | | rules | 表单验证规则，结合`wd-form`组件使用 | `FormItemRule []` | - | `[]` | - | | lineWidth | 底部条宽度，单位像素 | number | - | - | 1.3.7 | | lineHeight | 底部条高度，单位像素 | number | - | - | 1.3.7 | ### FormItemRule 数据结构 | 键名 | 说明 | 类型 | | --------- | ------------------------------------------------------- | ------------------------------------- | | required | 是否为必选字段 | `boolean` | | message | 错误提示文案 | `string` | | validator | 通过函数进行校验，可以返回一个 `Promise` 来进行异步校验 | `(value, rule) => boolean \| Promise` | | pattern | 通过正则表达式进行校验，正则无法匹配表示校验不通过 | `RegExp` | ## 选项数据结构 | 键名 | 说明 | 类型 | 是否必填 | 最低版本 | | -------- | -------- | ------- | -------- | -------- | | value | 选项值 | string | 是 | - | | label | 选项名 | string | 是 | - | | tip | 选项提示 | string | 否 | - | | disabled | 禁用选项 | boolean | 否 | - | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | -------------------------- | ------------------------------------------------ | -------- | | confirm | 最后一列选项选中时触发 | `{ value(选项值数组), selectedItems(选项数组) }` | - | | close | 点击关闭按钮或者蒙层时触发 | - | - | ## Methods | 方法名称 | 说明 | 参数 | 最低版本 | | -------- | ---------------- | ---- | -------- | | open | 打开 picker 弹框 | - | | close | 关闭 picker 弹框 | - | ## Slots | name | 说明 | 最低版本 | | ------- | ---------- | -------- | | default | 自定义展示 | - | | label | 左侧插槽 | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------------ | -------------------- | -------- | | custom-class | 根节点样式 | - | | custom-label-class | label 外部自定义样式 | - | | custom-value-class | value 外部自定义样式 | - | --- --- url: 'https://wot-design-uni.cn/component/config-provider.md' --- # ConfigProvider 全局配置 用于全局配置 `Wot` 组件，提供深色模式、主题定制等能力。 ## 深色模式 将 ConfigProvider 组件的 `theme` 属性设置为 `dark`，可以开启深色模式。 深色模式会全局生效，使页面上的所有 `Wot` 组件变为深色风格。 ```vue ... ``` :::tip 值得注意的是，开启 `Wot` 的深色模式只会影响 `Wot` 组件的 `UI`，并不会影响全局的文字颜色或背景颜色，你可以参考以下 `CSS` 来设置一些全局样式： ::: ```css .wot-theme-dark body { color: #f5f5f5; background-color: black; } ``` ## 动态切换 通过动态设置 `theme` 属性，可以在浅色风格和深色风格之间进行切换。 ```vue ... ``` ```ts export default { setup() { const theme = ref('light') setTimeout(() => { theme.value = 'dark' }, 1000) return { theme } } } ``` ## 定制主题 `Wot` 组件通过丰富的 [CSS 变量](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties) 来组织样式，通过覆盖这些 `CSS` 变量，可以实现定制主题、动态切换主题等效果。 ### 示例 这些变量的默认值被定义在 `page` 节点上，如果要转 `H5`，默认值被定义在 `:root` 节点上 ```css :root, page { --wot-color-success: red; --wot-color-warning: yellow; } ``` ### 通过 CSS 覆盖 你可以直接在代码中覆盖这些 `CSS` 变量，`Button` 组件的样式会随之发生改变： ```css /* 添加这段样式后，默认 Button 底色会变成绿色 */ :root, page { --wot-button-normal-bg: green; } ``` ### 通过 ConfigProvider 覆盖 `ConfigProvider` 组件提供了覆盖 `CSS` 变量的能力，你需要在根节点包裹一个 `ConfigProvider` 组件，并通过 `theme-vars` 属性来配置一些主题变量 ```html
提交
``` ```ts import { ref, reactive } from 'vue' export default { setup() { // themeVars 内的值会被转换成对应 CSS 变量 // 比如 buttonPrimaryBg 会转换成 `--wot-button-primary-bg-color` const themeVars = reactive({ buttonPrimaryBgColor: '#07c160', buttonPrimaryColor: '#07c160' }) return { themeVars } } } ``` ### 在 TypeScript 中使用 在 TypeScript 中定义 `themeVars` 时，建议使用 **wot-design-uni** 提供的 **ConfigProviderThemeVars** 类型，可以提供完善的类型提示： ```ts import type { ConfigProviderThemeVars } from 'wot-design-uni'; const themeVars: ConfigProviderThemeVars = { colorTheme: 'red' } ``` :::tip 注意：ConfigProvider 仅影响它的子组件的样式，不影响全局 root 节点。 ::: ## 全局共享 > 需要配合虚拟根组件([uni-ku-root](https://github.com/uni-ku/root)) 来做全局共享 ### 安装 ::: code-group ```bash [npm] npm i -D @uni-ku/root ``` ```bash [yarn] yarn add -D @uni-ku/root ``` ```bash [pnpm] pnpm add -D @uni-ku/root ``` ::: ### 引入 * CLI项目: 直接编辑 根目录下的 vite.config.(js|ts) * HBuilderX项目: 需要在根目录下 创建 vite.config.(js|ts) ```ts // vite.config.(js|ts) import { defineConfig } from 'vite' import UniKuRoot from '@uni-ku/root' import Uni from '@dcloudio/vite-plugin-uni' export default defineConfig({ plugins: [ // ...plugins UniKuRoot(), Uni() ] }) ``` :::tip 若存在改变 pages.json 的插件，需要将 UniKuRoot 放置其后 ::: ### 使用 1. 创建根组件并处理全局配置组件 * CLI项目: 在 **src** 目录下创建下 App.ku.vue * HBuilderX项目: 在 **根** 目录下创建 App.ku.vue :::tip 在 App.ku.vue 中标签 `` 代表指定视图存放位置 ::: ```vue ``` 2. 编写控制主题组合式函数 ```ts // src/composables/useTheme.ts import type { ConfigProviderThemeVars } from 'wot-design-uni' import { ref } from 'vue' const theme = ref<'light' | 'dark'>() const themeVars = ref() export function useTheme(vars?: ConfigProviderThemeVars) { vars && (themeVars.value = vars) function toggleTheme(mode?: 'light' | 'dark') { theme.value = mode || (theme.value === 'light' ? 'dark' : 'light') } return { theme, themeVars, toggleTheme, } } ``` 3. 在任意视图文件中使用切换主题模式 ```vue ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ---------- | ------------------------------------------------ | ------ | -------------- | ------ | -------- | | theme | 主题风格，设置为 `dark` 来开启深色模式，全局生效 | string | `dark`/`light` | - | - | | theme-vars | 自定义主题变量 | `ConfigProviderThemeVars` | - | - | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | ---------------- | | custom-class | 根节点样式 | 1.3.9 | | custom-style | 根节点样式 | 1.3.9 | --- --- url: 'https://wot-design-uni.cn/component/count-down.md' --- # CountDown 倒计时0.1.58 用于实时展示倒计时数值，支持毫秒精度。 ## 基础用法 `time` 属性表示倒计时总时长，单位为毫秒。 ```html ``` ```ts const time = ref(30 * 60 * 60 * 1000) ``` ## 自定义格式 `format` 属性表示倒计时格式，支持自定义。 ```html ``` ```ts const format = ref('DD 天 HH 时 mm 分 ss 秒') const time = ref(30 * 60 * 60 * 1000) ``` ## 毫秒级渲染 `millisecond` 属性表示是否开启毫秒级渲染，默认关闭。 ```html ``` ```ts const time = ref(30 * 60 * 60 * 1000) ``` ## 自定义样式 通过插槽自定义倒计时的样式，`timeData` 对象格式见下方表格。 ```html ``` ```ts const time = ref(30 * 60 * 60 * 1000) ``` ```css .custom-count-down { display: inline-block; width: 22px; color: #fff; font-size: 12px; text-align: center; background-color: #f0883a; border-radius: 2px; } .custom-count-down-colon { display: inline-block; margin: 0 4px; color: #f0883a; } ``` ## 手动控制 通过 `start` 方法开始倒计时，通过 `pause` 方法暂停倒计时，通过 `reset` 方法重置倒计时。 ```html ``` ```ts const { show: showToast } = useToast() const countDown = ref(null) const start = () => { countDown.value.start() } const pause = () => { countDown.value.pause() } const reset = () => { countDown.value.reset() } const onFinish = () => showToast('倒计时结束') ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ----------- | -------------------- | ------- | ------ | ---------- | -------- | | time | 倒计时时长，单位毫秒 | Number | — | 0 | 0.1.58 | | millisecond | 是否开启毫秒级渲染 | Boolean | — | false | 0.1.58 | | auto-start | 是否自动开始倒计时 | Boolean | — | true | 0.1.58 | | format | 倒计时格式化字符串 | String | — | `HH:mm:ss` | 0.1.58 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ---------------- | --------------------- | -------- | | finish | 倒计时结束时触发 | — | 0.1.58 | | change | 倒计时变化时触发 | current: TimeData | 0.1.58 | ## Methods | 方法名 | 说明 | 参数 | 最低版本 | | -------- | ---------------- | --------------------- | -------- | | start | 开始倒计时 | — | 0.1.58 | | pause | 暂停倒计时 | — | 0.1.58 | | reset | 重置倒计时，若 `auto-start` 为 `true`，重设后会自动开始倒计时 | — | 0.1.58 | ## Slots | 名称 | 说明 | 最低版本 | | ---- | -------- | -------- | | — | 默认插槽 | 0.1.58 | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | ### format 格式 | 格式 | 说明 | | ---- | ------------ | | DD | 天数 | | HH | 小时 | | mm | 分钟 | | ss | 秒数 | | S | 毫秒（1 位） | | SS | 毫秒（2 位） | | SSS | 毫秒（3 位） | ### timeData 对象 | 属性 | 说明 | 类型 | 默认值 | | ------------ | ---- | ------ | ------ | | days | 天 | number | - | | hours | 小时 | number | - | | minutes | 分钟 | number | - | | seconds | 秒 | number | - | | milliseconds | 毫秒 | number | - | --- --- url: 'https://wot-design-uni.cn/component/count-to.md' --- # CountTo 数字滚动1.3.8 数字滚动组件。 ## 基本用法 设置 `endVal` 属性，表示最终值。 设置 `startVal` 属性，表示起始值。 设置 `duration` 属性，表示从起始值到结束值数字变动的时间。 设置 `autoplay` 属性，表示是否自动播放。 设置 `decimals` 属性，表示保留的小数位数。 设置 `decimal` 属性，表示小数点符号。 设置 `prefix` 属性，表示数字前缀。 设置 `suffix` 属性，表示数字后缀。 设置 `fontSize` 属性，表示字体大小。 设置 `color` 属性，表示文本颜色。 ```vue ``` ## 设置主题 通过type参数设置文本主题，我们提供了五类属性：primary error success warning default-默认。 ```html ``` ## 手动控制 通过 `start` 方法开始倒计时，通过 `pause` 方法暂停倒计时，通过 `reset` 方法重置倒计时。 ```html ``` ```ts import type { CountToInstance } from '@/uni_modules/wot-design-uni/components/wd-count-to/types' const countTo = ref() const start = () => { countTo.value!.start() } const pause = () => { countTo.value!.pause() } const reset = () => { countTo.value!.reset() } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | --------- | ------------------------------ | ------- | ------------------------------------------- | ------- | -------- | | fontSize | 字体大小 | number | 16 | default | 1.3.8 | | color | 文本颜色 | string | - | '' | 1.3.8 | | type | 主题类型 | string | 'primary' / 'error' / 'warning' / 'success' | default | 1.3.9 | | startVal | 起始值 | number | - | 0 | 1.3.8 | | endVal | 最终值 | number | - | 2024 | 1.3.8 | | duration | 从起始值到结束值数字变动的时间 | number | - | 3000 | 1.3.8 | | autoplay | 是否自动播放 | boolean | - | true | 1.3.8 | | decimals | 保留的小数位数 | number | (需大于等于 0) | 0 | 1.3.8 | | decimal | 小数点符号 | string | - | '.' | 1.3.8 | | separator | 三位三位的隔开效果 | string | - | ',' | 1.3.8 | | prefix | 前缀 | string | - | - | 1.3.8 | | suffix | 后缀 | string | - | - | 1.3.8 | | useEasing | 是否具有连贯性 | boolean | - | true | 1.3.8 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | -------------------- | ---- | -------- | | finish | 动画完成时触发 | — | 1.3.8 | | mounted | 组件加载完成时时触发 | - | 1.3.8 | ## Methods | 方法名 | 说明 | 参数 | 最低版本 | | ------ | ----------------------------------------------------------- | ---- | -------- | | start | 开始动画 | — | 1.3.8 | | pause | 暂停动画 | — | 1.3.8 | | reset | 重置动画，若 `auto-start` 为 `true`，重设后会自动开始倒计时 | — | 1.3.8 | ## Slots | 名称 | 说明 | 最低版本 | | ------- | -------- | -------- | | default | 默认插槽 | 1.3.8 | | prefix | 前缀插槽 | 1.3.8 | | suffix | 后缀插槽 | 1.3.8 | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | 1.3.8 | | custom-style | 根节点样式 | 1.3.8 | --- --- url: 'https://wot-design-uni.cn/component/curtain.md' --- # Curtain 幕帘 一般用于公告类的图片弹窗。 ## 基本用法 通过 `v-model` 属性设置显示隐藏，必填项。 `src` 为幕帘图片地址（只支持在线地址），值为 `string` 类型，必填项。 `to` 为幕帘点击访问链接，值为 `string` 类型，非必填项。 ```html 展示幕帘 ``` ```typescript const value = ref(false) const img = ref('https://img20.360buyimg.com/da/jfs/t1/141592/25/8861/261559/5f68d8c1E33ed78ab/698ad655bfcfbaed.png') const link = ref('/pages/index/index') function handleClick() { value.value = true } ``` ## 设置幕帘图片宽高 设置 `width`，默认高度为图片原始比例与传入`width`计算所得, 必填项。 ```html 展示幕帘 ``` ```typescript const value = ref(false) const img = ref('https://img20.360buyimg.com/da/jfs/t1/141592/25/8861/261559/5f68d8c1E33ed78ab/698ad655bfcfbaed.png') const link = ref('/pages/index/index') function handleClick() { value.value = true } ``` ## 修改关闭按钮位置 设置 `close-position`，默认为 'inset'，可选值 'top', 'bottom', 'top-left', 'top-right', 'bottom-left', 'bottom-right'。 ```html 展示幕帘 ``` ```typescript const value = ref(false) const img = ref('https://img20.360buyimg.com/da/jfs/t1/141592/25/8861/261559/5f68d8c1E33ed78ab/698ad655bfcfbaed.png') const link = ref('/pages/index/index') function handleClick() { value.value = true } ``` ## 设置遮罩点击可关闭幕帘 设置 `close-on-click-modal` 属性，值为`boolean` 类型，非必填项。 ```html 展示幕帘 ``` ```typescript const value = ref(false) const img = ref('https://img20.360buyimg.com/da/jfs/t1/141592/25/8861/261559/5f68d8c1E33ed78ab/698ad655bfcfbaed.png') const link = ref('/pages/index/index') function handleClick() { value.value = true } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |----------------------|----------------------------------------------------|---------|--------------------------------------------------------------------------|--------|----------| | value | 绑定值，展示/关闭幕帘（已废弃，请使用 modelValue） | boolean | - | - | - | | modelValue | 绑定值，展示/关闭幕帘 | boolean | - | - | 1.7.0 | | src | 幕帘图片地址，必须使用网络地址 | string | - | - | - | | width | 幕帘图片宽度，默认单位 px | number | - | - | - | | to | 幕帘图片点击链接 | string | - | - | - | | close-position | 关闭按钮位置 | string | inset / top / bottom / top-left / top-right / bottom-left / bottom-right | inset | - | | close-on-click-modal | 点击遮罩是否关闭 | boolean | - | false | - | | hide-when-close | 是否当关闭时将弹出层隐藏（display: none） | boolean | - | true | - | | z-index | 设置层级 | number | - | 10 | 1.4.0 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | ----------- | ------------------------------------------------------------------------------ | ---- | -------- | | click | 点击幕帘时触发 | - | - | | close | 弹出层关闭时触发 | - | - | | click-modal | 点击遮罩时触发 | - | - | | beforeenter | 进入前触发 | - | - | | enter | 进入时触发 | - | - | | afterenter | 进入后触发 | - | - | | beforeleave | 离开前触发 | - | - | | leave | 离开时触发 | - | - | | afterleave | 离开后触发 | - | - | | load | 图片加载完成事件 | - | - | | error | 图片加载失败事件，若图片加载失败，则不会展示幕帘组件，即使设置 `value` 为 true | - | - | ## Slots | name | 说明 | 最低版本 | | ----- | ------------ | ---------------- | | close | 关闭按钮插槽 | 1.5.0 | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------------ | -------------- | ---------------- | | custom-class | 根节点样式 | - | | custom-close-class | 关闭按钮样式类 | 1.5.0 | | custom-close-style | 关闭按钮样式 | 1.5.0 | --- --- url: 'https://wot-design-uni.cn/component/datetime-picker.md' --- # DatetimePicker 日期时间选择器 为 DatetimePickerView 组件的封装，在其内部构建好日期时间选项。 ## 基本用法 `v-model` 设置绑定值，默认为 `datetime` 类型，展示年月日时分，绑定值为 `时间戳` 类型，如果为 `time` 类型，绑定值为字符串。label 可以不传。可以通过 `label-width` 设置标题宽度，默认为 `33%`。 ```html ``` ```typescript const value = ref(Date.now()) function handleConfirm({ value }) { console.log(new Date(value)) } ``` ## 设置默认值 `default-value` 设置默认日期，打开面板时面板自动选到默认日期。 ```html ``` ```typescript const value = ref('') const defaultValue = ref(Date.now()) function handleConfirm({ value }) { console.log(new Date(value)) } ``` ## date 类型 `date` 类型只展示年月日。 ```html ``` ```typescript const value = ref(Date.now()) ``` ## year-month 类型 `year-month` 类型只展示年月。 ```html ``` ```typescript const value = ref(Date.now()) ``` ## year 类型 `year` 类型只展示年。 ```html ``` ```typescript const value = ref(Date.now()) ``` ## time 类型 `time` 类型只展示时分，绑定值为 `HH:mm` 格式。 ```html ``` ```typescript const value4 = ref('09:20') ``` ## 修改展示格式 给 `display-format` 属性传入一个函数，接收所有选中项数组，返回展示的文本内容。 ```html ``` ```typescript const value = ref(Date.now()) const displayFormat = (items) => { return `${items[0].label}年${items[1].label}月${items[2].label}日 ${items[3].label}:${items[4].label}` } ``` ## 修改弹出层内部格式 给 `formatter` 属性传入一个函数，接收 `type` 和 `value` 值，返回展示的文本内容。`type` 有 `year`、`month`、`date`、`hour`、`minute` 类型，`value` 为 `number` 类型。 使用自定义`formatter`会关闭内置的默认`display-format`函数。 ```html ``` ```typescript const value = ref(Date.now()) const formatter = (type, value) => { switch (type) { case 'year': return value + '年' case 'month': return value + '月' case 'date': return value + '日' case 'hour': return value + '时' case 'minute': return value + '分' default: return value } } ``` ## 过滤选项 给 `filter` 属性传入一个函数，接收 `type` 和 `values` 值，返回列的选项列表。`type` 有 `year`、`month`、`date`、`hour`、`minute` 类型，`values` 为 number数组。 ```html ``` ```typescript const value = ref(Date.now()) const filter = (type, values) => { if (type === 'minute') { return values.filter((value) => value % 5 === 0) } return values } ``` ## 选择器大小 通过设置 `size` 修改选择器大小，将 `size` 设置为 'large' 时字号为 16px。 ```html ``` ## 必填属性 设置 `required` 属性开启表单必填。 ```html ``` ## 错误状态 设置 `error` 属性，选择器的值显示为红色。 ```html ``` ## 值靠右展示 设置 `align-right` 属性，选择器的值靠右展示。 ```html ``` ## 确定前校验 设置 `before-confirm` 函数，在用户点击`确定`按钮时，会执行 `before-confirm` 函数，并传入 `value`(time 类型为字符串，其他为时间戳，当picker为区间选择时，`value`为数组) 、 `resolve` 和 `picker` 参数，可以对 `value` 进行校验，并通过 `resolve` 函数告知组件是否确定通过，`resolve` 接受1个 boolean 值，`resolve(true)` 表示选项通过，`resolve(false)` 表示选项不通过，不通过时不会关闭 `picker`弹窗。可以通过 `picker` 参数直接设置 `loading` 等属性。 ```html ``` ```typescript const value = ref('') const toast = useToast() const beforeConfirm = (value, resolve, picker) => { picker.setLoading(true) setTimeout(() => { picker.setLoading(false) if (value > Date.now()) { resolve(false) toast.error('不能选择大于今天的日期') } else { resolve(true) } }, 2000) } function handleConfirm({ value }) { console.log(new Date(value)) } ``` ## 唤起项插槽 设置默认插槽修改唤起picker组件的形式。 ```html 插槽唤起 ``` ## 时间范围选择 当 `v-model` 为 `Array` 类型, 时间范围选择开启。 ```html ``` ```typescript const value = ref(['', Date.now()]) function handleConfirm({ value }) { console.log(new Date(value)) } ``` ## 范围选择tab标签展示格式 给 `display-format-tab-label` 属性传入一个函数，接收所有选中项数组，返回展示的文本内容。 ```html ``` ```typescript const value = ref(['', Date.now()]) function handleConfirm({ value }) { console.log(new Date(value)) } const displayFormatTabLabel = (items) => { return `${items[0].label}年${items[1].label}月${items[2].label}日 ${items[3].label}:${items[4].label}` } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|---------| | v-model | 选中项，当 type 为 time 时，类型为字符串；当 type 为 Array 时，类型为范围选择；否则为 `timestamp` | `string` / `timestamp` / `array` | - | - | | default-value | 默认日期，类型保持与 value 一致，打开面板时面板自动选到默认日期 | `string` / `timestamp` / `array` | - | - | - | | type | 选择器类型 | string | date / year-month / time / year | datetime | - | | loading | 加载中 | boolean | - | false | - | | loading-color | 加载的颜色，只能使用十六进制的色值写法，且不能使用缩写 | string | - | #4D80F0 | - | | columns-height | picker内部滚筒高 | number | - | 231 | - | | title | 弹出层标题 | string | - | - | - | | cancel-button-text | 取消按钮文案 | string | - | 取消 | - | | confirm-button-text | 确认按钮文案 | string | - | 完成 | - | | label | 选择器左侧文案，label可以不传 | string | - | - | - | | placeholder | 选择器占位符 | string | - | 请选择 | - | | disabled | 禁用 | boolean | - | false | - | | readonly | 只读 | boolean | - | false | - | | display-format | 自定义展示文案的格式化函数，返回一个字符串 | function | - | - | - | | formatter | 自定义弹出层选项文案的格式化函数，返回一个字符串 | function | - | - | - | | filter | 自定义过滤选项的函数，返回列的选项数组 | function | - | - | - | | display-format-tab-label | 在区域选择模式下，自定义展示tab标签文案的格式化函数，返回一个字符串 | function | - | - | - | | minDate | 最小日期，13 位的时间戳 | `timestamp` | - | 当前日期 - 10年 | - | | maxDate | 最大日期，13 位的时间戳 | `timestamp` | - | 当前日期 + 10年 | - | | minHour | 最小小时，time类型时生效 | number | - | 0 | - | | maxHour | 最大小时，time类型时生效 | number | - | 23 | - | | minMinute | 最小分钟，time类型时生效 | number | - | 0 | - | | maxMinute | 最大分钟，time类型时生效 | number | - | 59 | - | | required | 表单属性，必填 | boolean | - | false | - | | size | 设置选择器大小 | string | large | - | - | | label-width | 设置左侧标题宽度 | string | - | 33% | - | | error | 是否为错误状态，错误状态时右侧内容为红色 | boolean | - | false | - | | align-right | 选择器的值靠右展示 | boolean | - | false | - | | use-label-slot | label 使用插槽，已废弃，直接使用label插槽即可 | boolean | - | false | - | | use-default-slot | 使用默认插槽，已废弃，直接使用默认插槽即可 | boolean | - | false | - | | before-confirm | 确定前校验函数，接收 (value, resolve, picker) 参数，通过 resolve 继续执行 picker，resolve 接收1个boolean参数 | function | - | - | - | | close-on-click-modal | 点击遮罩是否关闭 | boolean | - | true | - | | z-index | 弹窗层级 | number | - | 15 | - | | safe-area-inset-bottom | 弹出面板是否设置底部安全距离（iphone X 类型的机型） | boolean | - | true | - | | ellipsis | 是否超出隐藏 | boolean | - | false | - | | prop | 表单域 `model` 字段名，在使用表单校验功能的情况下，该属性是必填的 | string | - | - | - | | rules | 表单验证规则，结合`wd-form`组件使用 | `FormItemRule []` | - | `[]` | - | | immediate-change | 是否在手指松开时立即触发picker-view的 change 事件。若不开启则会在滚动动画结束后触发 change 事件，1.2.25版本起提供，仅微信小程序和支付宝小程序支持。 | boolean | - | false | 1.2.25 | ### FormItemRule 数据结构 | 键名 | 说明 | 类型 | | --- | --- | --- | | required | 是否为必选字段 | `boolean` | | message | 错误提示文案 | `string` | | validator | 通过函数进行校验，可以返回一个 `Promise` 来进行异步校验 | `(value, rule) => boolean \| Promise` | | pattern | 通过正则表达式进行校验，正则无法匹配表示校验不通过 | `RegExp` | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | |--------|------|-----|---------| | confirm | 点击右侧按钮触发 | `{ value }`, value 为当前选中日期的时间戳，'time' 类型则为字符串 | - | | cancel | 点击左侧按钮触发 | - | - | | toggle | 在区域选择模式下，tab标签切换时触发 | 切换到当前picker选中的值 | - | ## Methods | 方法名称 | 说明 | 参数 | 最低版本 | |--------|------|-----|---------| | open | 打开picker弹框 | - | | close | 关闭picker弹框 | - | ## Slot | name | 说明 | 最低版本 | |------|-----|---------| | default | 使用默认插槽 | - | | label | 左侧标题插槽 | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-view-class | pickerView 外部自定义样式 | - | | custom-cell-class | pickerView cell 外部自定义样式 | 1.3.8 | | custom-label-class | label 外部自定义样式 | - | | custom-value-class | value 外部自定义样式 | - | --- --- url: 'https://wot-design-uni.cn/component/datetime-picker-view.md' --- # DatetimePickerView 日期时间选择器视图 为 Picker 组件的封装，在其内部构建好日期时间选项。 ## 基本用法 `v-model` 设置绑定值，默认为 `datetime` 类型，展示年月日时分，绑定值为 `时间戳` 类型，如果为 `time` 类型，绑定值为字符串。 ```html ``` ```typescript import { useToast } from '@/uni_modules/wot-design-uni' const toast = useToast() const value = ref(Date.now()) function onChange1({ value }) { toast.show('选择了' + new Date(value)) } ``` ## date 类型 `date` 类型只展示年月日。 ```html ``` ```typescript const value = ref(Date.now()) ``` ## year-month 类型 `year-month` 类型只展示年月。 ```html ``` ```typescript const value = ref(Date.now()) ``` ## year 类型 `year` 类型只展示年月。 ```html ``` ```typescript const value = ref(Date.now()) ``` ## time 类型 `time` 类型只展示时分，绑定值为 `HH:mm` 格式。 ```html ``` ```typescript const value4 = ref('11:12') ``` ## 修改内部格式 给 `formatter` 属性传入一个函数，接收 `type` 和 `value` 值，返回展示的文本内容。`type` 有 `year`、`month`、`date`、`hour`、`minute` 类型，`value` 为 `number` 类型。 使用自定义`formatter`会关闭内置的默认`display-format`函数。 ```html ``` ```typescript const value = ref(Date.now()) const formatter = (type, value) => { switch (type) { case 'year': return value + '年' case 'month': return value + '月' case 'date': return value + '日' case 'hour': return value + '时' case 'minute': return value + '分' default: return value } } ``` ## 过滤选项 给 `filter` 属性传入一个函数，接收 `type` 和 `values` 值，返回列的选项列表。`type` 有 `year`、`month`、`date`、`hour`、`minute` 类型，`values` 为 number数组。 ```html ``` ```typescript const value = ref(Date.now()) const filter = (type, values) => { if (type === 'minute') { return values.filter((value) => value % 5 === 0) } return values } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|---------| | v-model | 选中项，当 type 为 time 时，类型为字符串，否则为 `timestamp` | `string` / `timestamp` | - | - | | type | 选择器类型 | string | date / year-month / time / year | datetime | - | | loading | 加载中 | boolean | - | false | - | | loading-color | 加载的颜色，只能使用十六进制的色值写法，且不能使用缩写 | string | - | #4D80F0 | - | | columns-height | picker内部滚筒高 | number | - | 231 | - | | formatter | 自定义弹出层选项文案的格式化函数，返回一个字符串 | function | - | - | - | | filter | 自定义过滤选项的函数，返回列的选项数组 | function | - | - | - | | minDate | 最小日期，13 位的时间戳 | `timestamp` | - | 当前日期 - 10年 | - | | maxDate | 最大日期，13 位的时间戳 | `timestamp` | - | 当前日期 + 10年 | - | | minHour | 最小小时，time类型时生效 | number | - | 0 | - | | maxHour | 最大小时，time类型时生效 | number | - | 23 | - | | minMinute | 最小分钟，time类型时生效 | number | - | 0 | - | | maxMinute | 最大分钟，time类型时生效 | number | - | 59 | - | | immediate-change | 是否在手指松开时立即触发picker-view的 change 事件。若不开启则会在滚动动画结束后触发 change 事件，1.2.25版本起提供，仅微信小程序和支付宝小程序支持。 | boolean | - | false | 1.2.25 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | |--------|------|-----|---------| | change | 切换选项时触发 | 选中的值 `{ value }`，value 为当前选中日期的时间戳，'time' 类型则为字符串 | - | | pickstart | 当滚动选择开始时候触发事件 | - | - | - | | pickend | 当滚动选择结束时候触发事件 | - | - | - | --- --- url: 'https://wot-design-uni.cn/component/divider.md' --- # Divider 分割线 用于将内容分隔为多个区域。 :::danger 请注意 `hairline`、`dashed`、`content-position`、`vertical`属性为 1.5.0 版本新增支持，在此之前仅支持默认插槽显示文本和自定义`color`。 ::: ## 基本使用 默认渲染一条水平分割线。 ```html ``` ## 展示文本 使用默认插槽在分割线中间插入内容。 ```html 展示文本 ``` ## 自定义渲染内容 使用默认插槽在分割线中间插入自定义内容。 ```html ``` ## 内容位置 通过 `content-position` 指定内容所在位置。 ```html 中间 左侧 右侧 ``` ## 虚线 添加 `dashed` 属性使分割线渲染为虚线。 ```html 虚线分割 ``` ## 自定义颜色 设置 `color` 属性。 ```html 自定义颜色 ``` ## 垂直分割线 添加 `vertical` 属性使分割线渲染为垂直分割线。 ```html 文本 文本 文本 文本 文本 ``` ```css .content { padding: 12rpx 15px; } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ---------------- | ------------------------------ | ------- | ----------------------- | -------- | ---------------- | | color | 自定义颜色，支持所有颜色的写法 | string | - | - | - | | hairline | 是否显示边框 | boolean | - | true | 1.5.0 | | dashed | 是否显示为虚线 | boolean | - | false | 1.5.0 | | content-position | 内容位置 | string | `left`/`center`/`right` | `center` | 1.5.0 | | vertical | 是否显示为垂直分割线 | boolean | - | false | 1.5.0 | ## Slot | name | 说明 | 最低版本 | | ------- | ---- | -------- | | default | 内容，仅在 `vertical` 为 `false` 时生效 | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/drop-menu.md' --- # DropMenu 下拉菜单 向下或向上弹出的菜单列表。 ## 基础用法 基础用法需要绑定 `v-model` 值以及 `options` 属性。 `options` 属性是一个一维对象数组，数组项的数据结构为：label（选项文本），value（选项值），tip（选项说明）。 因为`uni-app`组件无法监听点击自己以外的地方，为了在点击页面其他地方时，可以自动关闭 `dropmenu` ，建议使用组件库的 `useQueue` hook（会关闭所有 dropmenu、popover、toast、swipeAction、fab），在页面的根元素上监听点击事件的冒泡。 :::warning 如果存在用户手动点击 `dropmenu` 以外某个地方如按钮弹出 `dropmenu` 的场景，则需要在点击的元素（在这里上按钮）加上 @click 阻止事件冒泡到根元素上，避免触发 `closeOutside` 把要手动打开的 `dropmenu` 关闭了。 ::: ```html ``` ```typescript import { useQueue } from '@/uni_modules/wot-design-uni' const { closeOutside } = useQueue() const value1 = ref(0) const value2 = ref(0) const option1 = ref[]>([ { label: '全部商品', value: 0 }, { label: '新款商品', value: 1 }, { label: '活动商品', value: 2 } ]) const option2 = ref[]>([ { label: '综合', value: 0 }, { label: '销量', value: 1 }, { label: '上架时间', value: 2 } ]) function handleChange1({ value }) { console.log(value) } function handleChange2({ value }) { console.log(value) } ``` ## 自定义菜单内容 通过插槽 `default` 可以自定义 `DropMenuItem` 的内容，此时需要使用实例上的 `close` 方法手动控制菜单的关闭。 可以通过 `title` 设置菜单标题。 > 这时候不要传入 options 和 value ```html 主要按钮 ``` ```typescript const dropMenu = ref() const slider = ref() // slider 1.2.25支持 const value = ref(0) const sliderValue = ref(30) const option = ref[]>([ { label: '全部商品', value: 0 }, { label: '新款商品', value: 1 }, { label: '活动商品', value: 2 } ]) function handleChange({ value }) { console.log(value) } function confirm() { dropMenu.value.close() } function handleOpened() { slider.value?.initSlider() } ``` ## 自定义菜单选项 自己通过 flex 布局做自定义筛选展示。 ```html ``` ## 自定义菜单图标1.3.7 可以通过 `icon` 设置菜单右侧图标，等同于 `` 的 `name` 属性。通过 `icon-size` 设置图标尺寸，等同于 `` 的 `size` 属性。 ```html ``` ## 异步打开/关闭1.3.7 设置 `before-toggle` 函数，在下拉菜单打开或者关闭前执行特定的逻辑，实现状态变更前校验、异步打开/关闭的目的，`before-toggle`接收 { status: 当前操作类型：true 打开下拉菜单，false 关闭下拉菜单, resolve }，可以对操作进行校验，并通过 resolve 函数告知组件是否确定通过，resolve 接受 1 个 boolean 值，resolve(true) 表示选项通过，resolve(false) 表示选项不通过，不通过时不会执行关闭或展开操作。 :::warning 提示 `before-toggle` 函数无法阻止其他`drop-menu`或其他`drop-menu-item`的展开/关闭操作，仅限当前`drop-menu-item`的展开/关闭操作。 ::: ```html ``` ```typescript import { useMessage } from '@/uni_modules/wot-design-uni' const messageBox = useMessage() const value = ref(0) const option = ref[]>([ { label: '全部商品', value: 0 }, { label: '新款商品', value: 1 }, { label: '活动商品', value: 2 } ]) // 通过对话框确认是否打开/关闭下拉菜单 const handleBeforeToggle: DropMenuItemBeforeToggle = ({ status, resolve }) => { messageBox .confirm({ title: `异步${status ? '打开' : '关闭'}`, msg: `确定要${status ? '打开' : '关闭'}下拉菜单吗？` }) .then(() => { resolve(true) }) .catch(() => { resolve(false) }) } ``` ## 向上展开 将 `direction` 属性值设置为 `up`，菜单即可向上展开 ```html ``` ## 禁用菜单 ```html ``` ## DropMenu Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | -------------------- | ------------------------------------ | ------- | --------- | ------ | -------- | | direction | 菜单展开方向，可选值为`up` 或 `down` | string | up / down | down | - | | modal | 是否展示蒙层 | boolean | - | true | - | | close-on-click-modal | 是否点击蒙层时关闭 | boolean | - | true | - | | duration | 菜单展开收起动画时间，单位 ms | number | - | 200 | - | ## DropMenuItem Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------- | ---------------------------------------------------------------------- | ----------------------------- | ------ | ---------- | -------- | | v-model | 当前选中项对应选中的 value | string / number | - | - | - | | disabled | 禁用菜单 | boolean | - | false | - | | options | 列表数据，对应数据结构 `[{text: '标题', value: '0', tip: '提示文字'}]` | array | - | - | - | | icon-name | 选中的图标名称(可选名称在 wd-icon 组件中) | string | - | check | - | | title | 菜单标题 | string | - | - | - | | icon | 菜单图标 | string | - | arrow-down | - | | icon-size | 菜单图标尺寸 | string | - | 14px | \_ | | before-toggle | 下拉菜单打开或者关闭前触发，`reslove(true)`时继续执行打开或关闭操作 | function({ status, resolve }) | - | - | 1.3.7 | | value-key | 选项对象中，value 对应的 key | string | - | value | - | | label-key | 选项对象中，展示的文本对应的 key | string | - | label | - | | tip-key | 选项对象中，选项说明对应的 key | string | - | tip | - | ## DropdownItem Events | 方法名 | 说明 | 参数 | 最低版本 | | ------ | ---------------- | ----------------------------------------------------------------------------- | -------- | | change | 绑定值变化时触发 | event.detail = { value, selectedItem }, value 为选中值，selectedItem 为选中项 | - | | close | 关闭菜单 | - | - | | open | 展开菜单 | - | - | | closed | 菜单完全关闭 | - | - | | opened | 菜单展开完成 | - | - | ## DropdownItem Methods 通过设置 `ref` 可以获取到 DropdownItem 实例并调用实例方法 | 方法名 | 说明 | 参数 | 返回值 | 最低版本 | | ------ | -------- | ---- | ------ | -------- | | close | 关闭菜单 | - | - | - | | open | 展开菜单 | - | - | - | ## DropMenu Slot | name | 说明 | 最低版本 | | ------- | -------- | -------- | | default | 菜单内容 | - | ## DropMenuItem Slot | name | 说明 | 最低版本 | | ------- | ------------------ | -------- | | default | 菜单自定义内部内容 | - | ## DropMenu 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ------------------- | -------- | | custom-class | DropMenu 根节点样式 | - | ## DropMenuItem 外部样式类 | 类名 | 说明 | 最低版本 | | ------------------ | --------------------------- | ---------------- | | custom-class | DropMenuItem 根节点样式 | - | | custom-title | DropMenuItem 左侧文字样式 | - | | custom-icon | DropMenuItem 右侧 icon 样式 | - | | custom-popup-class | 自定义下拉菜单 popup 样式类 | 1.5.0 | | custom-popup-style | 自定义下拉菜单 popup 样式 | 1.5.0 | --- --- url: 'https://wot-design-uni.cn/component/fab.md' --- # Fab 悬浮按钮 悬浮动作按钮组件，按下可显示一组动作按钮。 :::warning 因为`uni-app`组件无法监听点击自己以外的地方，为了在点击页面其他地方时，可以自动关闭 `fab` ，建议使用组件库的 `useQueue` hook（会关闭所有 dropmenu、popover、toast、swipeAction、fab），在页面的根元素上监听点击事件的冒泡。 如果存在用户手动点击 `fab` 以外某个地方如按钮滑出 `fab` 的场景，则需要在点击的元素（在这里是按钮）加上 `click.stop=""` 阻止事件冒泡到根元素上，避免触发 `closeOutside`把要手动打开的 `fab` 关闭了。 ::: ## 基本用法 通过`type`设置悬浮按钮触发器的类型，`position`设置悬浮按钮触发器的位置，`direction`设置动作按钮的打开方向，`disabled`设置悬浮按钮是否禁用。 ```html ``` ```ts import { useToast } from '@/uni_modules/wot-design-uni' const { show: showToast } = useToast() const type = ref<'primary' | 'success' | 'info' | 'warning' | 'error' | 'default'>('primary') const position = ref<'left-top' | 'right-top' | 'left-bottom' | 'right-bottom' | 'left-center' | 'right-center' | 'top-center' | 'bottom-center'>('left-bottom') const direction = ref<'top' | 'right' | 'bottom' | 'left'>('top') const disabled = ref(false) ``` ```scss :deep(.custom-button) { min-width: auto !important; box-sizing: border-box; width: 32px !important; height: 32px !important; border-radius: 16px !important; margin: 8rpx; } :deep(.custom-radio) { height: 32px !important; line-height: 32px !important; } ``` ## 动作菜单展开/收起 通过`v-model:active`控制动作按钮菜单的展开/收起 ```html ``` ```ts const active = ref(false) ``` ## 可拖动按钮 ```html ``` :::warning 开启拖动后`direction`属性将失效，会根据拖动后的位置自动计算弹出方向。拖动完成后按钮将会自动吸边。 ::: ## 自定义触发器 通过`trigger`插槽自定义触发器，`expandable`控制点击触发器是否展开/收起动作按钮菜单。 ```html ``` ```ts const handleClick = () => { console.log('点击了') } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | -------------- | ----------------------------------------------------- | ------------ |-------------------------------------------------------------------------------------------------------------------------------------------| ---------------------------------------------- | ---------------- | | v-model:active | 是否激活 | boolean | - | false | 0.1.57 | | type | 类型 | FabType | 'primary' | 'success' | 'info' | 'warning' | 'error' | 'default' | 'primary' | 0.1.57 | | position | 悬浮按钮位置 | FabPosition | 'left-top' | 'right-top' | 'left-bottom' | 'right-bottom' | left-center | right-center | top-center | bottom-center | 'right-bottom' | 0.1.57 | | draggable | 按钮能否拖动 | boolean | | false | 1.2.19 | | direction | 悬浮按钮菜单弹出方向 | FabDirection | 'top' | 'right' | 'bottom' | 'left' | 'top' | 0.1.57 | | disabled | 是否禁用 | boolean | - | false | 0.1.57 | | inactiveIcon | 悬浮按钮未展开时的图标 | string | - | 'add' | 0.1.57 | | activeIcon | 悬浮按钮展开时的图标 | string | - | 'close' | 0.1.57 | | zIndex | 自定义悬浮按钮层级 | number | - | 99 | 0.1.57 | | gap | 自定义悬浮按钮与可视区域边缘的间距 | FabGap | - | { top: 16, left: 16, right: 16, bottom: 16 } | 1.2.26 | | customStyle | 自定义样式 | string | - | '' | 0.1.57 | | expandable | 用于控制点击时是否展开菜单，设置为 false 时触发 click | boolean | - | true | 1.3.11 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | -------------------------------------------- | ---- | ---------------- | | click | expandable 设置为 false 时，点击悬浮按钮触发 | — | 1.3.11 | ## Slot | name | 说明 | 最低版本 | | ------- | -------------------------------------------------------------- | ---------------- | | trigger | 触发器插槽，用于自定义点击按钮，使用此插槽时组件不会抛出 click | 1.3.11 | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ------------ | -------- | | custom-class | 自定义样式类 | 0.1.57 | --- --- url: 'https://wot-design-uni.cn/component/floating-panel.md' --- # FloatingPanel 浮动面板 浮动在页面底部的面板，用户可以通过上下拖动秒板来浏览内容，从而在不离开当前视图的情况下访问更多信息，常用于地图导航。 ## 基本用法 FloatingPanel 的初始高度会取 `anchors[0]` 的值，也就是 `100px`，用户可以拖动来展开面板，使高度达到 `60%` 的屏幕高度。 ```html ``` ```js const data = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z'] ``` ## 自定义锚点 你可以通过 `anchors` 属性来设置 FloatingPanel 的锚点位置，并通过 `v-model:height` 来控制当前面板的显示高度。 比如，使面板的高度在 `100px`、`40%` 屏幕高度和 `70%` 屏幕高度三个位置停靠： ```html 自定义锚点 {{ anchors }} - {{ height.toFixed(0) }} ``` ```js const height = ref(0) const windowHeight = ref(0) const anchors = ref([]) const handleHeightChange = ({ height }: { height: number }) => { console.log(height) } onLoad(() => { windowHeight.value = uni.getSystemInfoSync().windowHeight anchors.value = [100, Math.round(0.4 * windowHeight.value), Math.round(0.7 * windowHeight.value)] height.value = anchors.value[1] }) ``` ```css .inner-content { padding: 1rem; text-align: center; font-size: 16px; font-weight: bold; } ``` ## 仅头部拖拽 默认情况下，FloatingPanel 的头部区域和内容区域都可以被拖拽，你可以通过 `contentDraggable` 属性来禁用内容区域的拖拽。 ```html 内容区不可以拖拽 ``` ```css .inner-content { padding: 1rem; text-align: center; font-size: 16px; font-weight: bold; } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------------- | ------------------------------------------- | -------- | ------ | --------------------------- | ---------------- | | v-model:height | 当前面板的显示高度 | number | - | `0` | 1.3.12 | | anchors | 设置自定义锚点, 单位 `px` | number\[] | - | `[100, windowHeight * 0.6]` | 1.3.12 | | duration | 动画时长，单位`ms`，设置为 `0` 可以禁用动画 | number | - | `300` | 1.3.12 | | contentDraggable | 允许拖拽内容容器 | boolean | - | `true` | 1.3.12 | | safeAreaInsetBottom | 是否开启底部安全区适配 | boolean | - | `false` | 1.3.12 | | showScrollbar | 是否开启滚动条 | boolean | - | `true` | 1.3.12 | ## Slots | 名称 | 说明 | 最低版本 | | ---- | -------- | ---------------- | | — | 默认插槽 | 1.3.12 | ## Events | 方法名 | 说明 | 参数 | 最低版本 | | ------------ | -------------------------------- | -------------------- | ---------------- | | heightChange | 面板显示高度改变且结束拖动后触发 | `{ height: number }` | 1.3.12 | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ------------ | ---------------- | | custom-class | 根节点样式类 | 1.3.12 | | custom-style | 根节点样式 | 1.3.12 | --- --- url: 'https://wot-design-uni.cn/component/form.md' --- # Form 表单 用于数据录入、校验，支持输入框、单选框、复选框、文件上传等类型，常见的 form 表单为`单元格`形式的展示，即左侧为表单的标题描述，右侧为表单的输入。 其中，`Input 输入框`、`Textarea 输入框`、`Picker 选择器`、 `Calendar 日历选择器`、 `ColPicker 多列选择器`、`SelectPicker 单复选选择器`、`Cell 单元格` 和 `DatetimePicker 日期时间选择器`具有`单元格`的展示形式，同时也支持 `prop` 和 `rules` 属性，我们称之为`表单项组件`，而 `InputNumber 计数器` 、 `Switch 开关` 和 `Upload 上传` 等组件则需要使用 `Cell 单元格` 进行包裹使用。 结合 `wd-form` 组件，可以实现对以上组件的规则校验。 > 对于表单组件，建议对 wd-cell-group 开启 border 属性，这样每条 cell 就会有边框线隔离开，这样表单的划分比较清晰。 ## 基础用法 在表单中，使用 `model` 指定表单数据对象，每个 `表单项组件` 代表一个表单项，使用 `prop` 指定表单项字段 ，使用 `rules` 属性定义校验规则。 ::: details 查看基础用法示例 ::: code-group ```html [vue] 提交 ``` ```typescript [typescript] ``` ```css [css] .footer { padding: 12px; } ``` ::: ## 校验错误提示方式 1. `message`：默认为输入框下方用文字进行提示 2. `toast`：以"toast"提示的方式弹出错误信息，每次只弹出最前面的那个表单域的错误信息 3. `none`：不会进行任何提示 ::: details 错误提示方式 ::: code-group ```html [vue] 提交 ``` ```typescript [typescript] ``` ::: ## 校验规则 本章节演示四种自定义校验及提示规则：`正则校验`、`函数校验`、`函数返回错误提示`和`异步函数校验`。 ::: details 查看校验规则示例 ::: code-group ```html [vue] 提交 ``` ```typescript [typescript] ``` ```css [css] .footer { padding: 12px; } ``` ::: ## 动态表单 表单项动态增减。 ::: details 查看动态表单示例 ::: code-group ```html [vue] 添加 删除 重置 提交 ``` ```typescript [typescript] ``` ```css [css] .footer { text-align: left; :deep(.wd-button) { &:not(:last-child) { margin-right: 12px; } } } ``` ::: ## 指定字段校验 `validate` 方法可以传入一个 `prop` 参数，指定校验的字段，可以实现在表单组件的`blur`、`change`等事件触发时对该字段的校验。`prop` 参数也可以是一个字段数组，指定多个字段进行校验。 ::: details 查看指定字段校验示例 ::: code-group ```html [vue] 提交 校验用户名和密码 ``` ```typescript [typescript] ``` ```css [css] .footer { padding: 12px; } ``` ::: ## 不对隐藏组件做校验 1.6.0 在表单中，如果某个组件使用 `v-if` 隐藏，则不会对该组件进行校验。 ## 复杂表单 结合`Input 输入框`、`Textarea 输入框`、`Picker 选择器`、 `Calendar 日历选择器`、 `ColPicker 多列选择器`、`SelectPicker 单复选选择器`、`Cell 单元格` 和 `DatetimePicker 日期时间选择器`实现一个复杂表单。 ::: details 查看复杂表单示例 ::: code-group ```html [vue] 满 减 已阅读并同意 《巴拉巴拉吧啦协议》 提交 ``` ```typescript [typescript] ``` ```css [css] .inline-txt { display: inline-block; font-size: 14px; margin: 0 8px; color: rgba(0, 0, 0, 0.45); vertical-align: middle; } :deep(.group) { margin-top: 12px; } .tip { margin: 10px 15px 21px; color: #999; font-size: 12px; } .footer { padding: 0 25px 21px; } :deep(.label-class) { color: #999 !important; font-size: 12px !important; } ``` ::: ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------- | ----------------------------------------------------------------------------------- | --------------------- | ------ | --------- | ---------------- | | model | 表单数据对象 | `Record` | - | - | 0.2.0 | | rules | 表单验证规则 | `FormRules` | - | - | 0.2.0 | | resetOnChange | 表单数据变化时是否重置表单提示信息（设置为 false 时需要开发者单独对变更项进行校验） | `boolean` | - | `true` | 0.2.16 | | errorType | 校验错误提示方式 | `toast/message/none` | - | `message` | 1.3.8 | ### FormItemRule 数据结构 | 键名 | 说明 | 类型 | | --------- | ------------------------------------------------------- | ------------------------------------- | | required | 是否为必选字段 | `boolean` | | message | 错误提示文案 | `string` | | validator | 通过函数进行校验，可以返回一个 `Promise` 来进行异步校验 | `(value, rule) => boolean \| Promise` | | pattern | 通过正则表达式进行校验，正则无法匹配表示校验不通过 | `RegExp` | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ------------------------------------------------------------------------------ | --------------- | -------- | | validate | 验证表单，支持传入一个 prop 来验证单个表单项，不传入 prop 时，会验证所有表单项，1.6.0 版本起支持传入数组 | `prop?: string\|string[]` | 0.2.0 | | reset | 重置校验结果 | - | 0.2.0 | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | 0.2.0 | --- --- url: 'https://wot-design-uni.cn/component/gap.md' --- # Gap 间隔槽 一般用于页面布局时代替margin或者padding;或者充当（底部）占位元素。 ## 基本使用 通过 `height` 属性设置标题 `background` 属性设置背景色。 ```html ``` ## 自定义背景色 ```html ``` ## 自定义高度 ```html ``` ## 底部安全区 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----------------|---------|---------|------------|-------------| -------- | | height | 高度 | `string`/`number` | - | 15 | - | | bgColor | 背景颜色 | string | | transparent | - | | safeAreaBottom | 开启底部安全区 | boolean | true/false | false | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | -------------------- | ---------------- | -------- | | custom-class | 自定义样式 | - | --- --- url: 'https://wot-design-uni.cn/component/grid.md' --- # Grid 宫格 宫格可以在水平方向上把页面分隔成等宽度的区块，用于展示内容或进行页面导航。 ## 基础用法 基础用法需要绑定 `icon` 值以及 `text` 属性。默认显示一行。 `icon` 为 `wd-icon` 标签中的 `name` 属性。 ```html ``` ## 自定义列数 `column` 可以用来自定义宫格列数。未定义 `column` 属性时，默认显示为一行，定义该属性后，组件内部根据 `column` 属性自行划分行数。 ```html ``` ## 自定义背景颜色 `bg-color` 可以用来自定义宫格背景颜色。 ```html ``` ## 开启边框 `border` 可以用来开启边框线展示。 ```html ``` ## 内容插槽 通过默认插槽可以自定义 `GridItem` 的内容。 使用默认插槽过程中, 开启 `GridItem` 上的属性 `use-slot`。 ```html ``` ```scss .img { width: 100%; height: 90px; } ``` ## 单个插槽 通过插槽 `icon` 可以插入 `GridItem` 中的图标位。通过 `use-icon-slot` 开启图标插槽。 通过插槽 `text` 可以插入 `GridItem` 中的文字位。通过 `use-text-slot` 开启文字插槽。 注意: 1. 使用单个插槽或者自定义样式时，需要用户使用 `custom-class` 控制 每一个 `GridItem` 的高度，保证每一个 `GridItem` 的高度相同且符合用户预期。 2. 使用 icon 插槽时，如果插槽大小超过`icon-size`设置的值时，需要调整`icon-size`属性使其大小等于插槽尺寸。 ```html ``` ```scss .slot-img { height: 36px; width: 36px; border-radius: 4px; } .text { color: #ffb300; margin-top: 8px; } ``` ## 自定义样式 通过设置 `custom-class` 可以自定义 `GridItem` 的样式。 可以在 `custom-class` 样式属性中设定 `GridItem` 的宽、高度等属性。 注意: * 设定宽高这类可能会影响布局的属性时，请将 `custom-class` 作用到当前 `Grid` 下的所有 `GridItem` 以确保所有 `GridItem` 样式相同。 * **如果想改变 `GridItem` 高度, 不要直接设置 `Grid` 的高度, 修改单独的** `GridItem`。 * **如果想改变 `icon` 大小设置 `icon-size` 属性, `custom-icon` 不能改变当前 icon 宽高。** ```html ``` ```scss :deep(.custom-item) { height: 80px !important; color: #e2231a; padding-left: 20px; text-align: left !important; } ``` ## 正方形格子 通过 `square` 属性开启正方形格属性。此时显示每一个 `GridItem` 都为正方形。 注意: 使用 `square` 不要自定义 `GridItem` 的高度样式。 ```html ``` ## 设定格间隙 通过 `gutter` 属性设置格子之间的距离。 ```html ``` ## 页面导航 通过 `clickable` 属性开启可点击状态, 可以绑定 `click` 事件。 通过 `link-type` 属性设置页面跳转方式。 通过 `url` 属性设置跳转链接, 通过 `url` 属性设置 URL 跳转链接。 ```html ``` ## 提示信息 设置 `is-dot` 属性后，会在图标右上角展示一个小红点。 设置 `type` | `max` | `value` , 使用方式同组件 `wd-badge` 中的同名属性。 ```html ``` ## Grid Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ----------- | ------------------------------ | ------- | ------ | ---------------------------- | ---------------- | | column | 列数 | number | - | - | - | | border | 是否显示边框 | boolean | - | false | - | | gutter | 格子之间的间距，默认单位为`px` | number | - | - | - | | square | 是否将格子固定为正方形 | boolean | - | false | - | | clickable | 是否开启格子点击反馈 | boolean | - | false | - | | bg-color | 背景颜色设置 | string | - | #ffffff | - | | hover-class | 指定grid-item按下去的样式类 | string | - | wd-grid-item\_\_content--hover | 1.9.0 | ## GridItem Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------- | ------ | -------- | | text | 文字 value | string | - | - | - | | icon | 图标名称，可选值见 `wd-icon` 组件 | string | - | - | - | | is-dot | 是否显示图标右上角小红点 | boolean | - | false | - | | type | 图标右上角显示的 `badge` 类型 | string | primary / success / warning / danger / info | - | - | | value | 图标右上角 `badge` 显示值 | string, number | - | - | - | | max | 图标右上角 `badge` 最大值，超过最大值会显示 '{max}+'，要求 value 是 Number 类型 | number | - | - | - | | url | 点击后跳转的链接地址 | string | - | - | - | | link-type | 页面跳转方式, 参考[微信小程序路由文档](https://developers.weixin.qq.com/miniprogram/dev/framework/app-service/route.html) | string | navigateTo / switchTab / reLaunch | - | - | | use-slot | 是否开启 `GridItem` 内容插槽 | boolean | - | false | - | | use-icon-slot | 是否开启 `GridItem` icon 插槽 | boolean | - | false | - | | use-text-slot | 是否开启 `GridItem` text 内容插槽 | boolean | - | false | - | | icon-size | 图标大小 | string | - | 26px | - | | badge-props | 自定义徽标的属性，传入的对象会被透传给 [Badge 组件的 props](/component/badge#attributes) | BadgeProps | - | - | 0.1.50 | ## GridItem Events | 方法名 | 说明 | 参数 | 返回值 | 最低版本 | | --------- | -------------- | ----- | ------ | -------- | | itemclick | 点击(跳转)事件 | event | - | - | ## Grid Slot | name | 说明 | 最低版本 | | ------- | -------- | -------- | | default | 宫格内容 | - | ## GridItem Slot | name | 说明 | 最低版本 | | ------- | ------------------------------ | -------- | | default | 宫格中每一格的默认显示全部内容 | - | | icon | 宫格中图标位内容 | - | | text | 宫格中文本位内容 | - | ## Grid 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | --------------- | -------- | | custom-class | Grid 根节点样式 | - | ## GridItem 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ----------------------- | -------- | | custom-class | GridItem 根节点样式 | - | | custom-text | GridItem 下方文字样式 | - | | custom-icon | GridItem 上方 icon 样式 | - | --- --- url: 'https://wot-design-uni.cn/component/icon.md' --- # Icon 图标 0.1.27 更新 基于字体的图标集。 ## 基本用法 通过 `name` 属性设置使用哪个图标。 ```html ``` ## 图标颜色 设置 `color` 属性。 ```html ``` ## 图标大小 设置 `size` 属性。 ```html ``` ## 自定义图标 如果需要在现有 Icon 的基础上使用更多图标，可以引入第三方 iconfont 对应的字体文件和 CSS 文件，之后就可以在 Icon 组件中直接使用。 ```css /* 路径 src/iconfont/index.css */ @font-face { font-family: "fish"; src: url('//at.alicdn.com/t/c/font_4626013_vwpx4thmin.woff2?t=1721314121733') format('woff2'), url('//at.alicdn.com/t/c/font_4626013_vwpx4thmin.woff?t=1721314121733') format('woff'), url('//at.alicdn.com/t/c/font_4626013_vwpx4thmin.ttf?t=1721314121733') format('truetype'); } .fish { font-family: "fish" !important; font-size: 16px; font-style: normal; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; } .fish-kehuishouwu:before { content: "\e627"; } ``` ```html ``` ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|---------| | name | 使用的图标名字，可以使用链接图片 | string | - | - | - | | color | 图标的颜色 | string | - | inherit | - | | size | 图标的字体大小 | string | - | inherit | - | | classPrefix | 类名前缀，用于使用自定义图标 | string | - | 'wd-icon' | 0.1.27 | | custom-style | 根节点样式 | string | - | - | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/img.md' --- # Img 图片 增强版的 img 标签，提供多种图片填充模式，支持图片懒加载、加载完成、加载失败。 ## 基本用法 基础用法与原生 image 标签一致，可以设置 `src` 、 `width` 、`height` 等原生属性。 原生属性，参考[uni-app image 官方文档](https://uniapp.dcloud.net.cn/component/image.html#image)。 此处需要注意的是 src 属性： 使用 `相对路径`，需要注意 `src` 需要以组件存放位置相对图片位置为相对路径。 使用 `文件导入` ，需要注意的是微信小程序 image 标签路径接受二进制数据以及 base64 编码。单独使用 import 图片路径无法访问。 ```html ``` ```typescript // import { joy } from '../images/joy' const joy = 'data:image/jpeg;base64,...' // 图片文件base64 ``` ## 插槽 使用`loading` `error`插槽设置在图片加载时、加载失败后的展示内容 ```vue ``` ## 填充模式 通过 `mode` 属性可以设置图片填充模式，可选值见下方表格。 mode 为小程序原生属性，参考[微信小程序 image 官方文档](https://developers.weixin.qq.com/miniprogram/dev/component/image.html)。 ```html ``` ## 圆形设置 通过 `round` 属性可以设置以圆形展示。 ```html ``` ## 可预览 通过设置`enable-preview`属性可以支持点击预览，底层调用 uni.previewImage 来实现预览效果 ```html ``` 也可以传入 `preview-src` 属性来预览另外的图片 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ---------------------- | -------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------- | | src | 图片链接 | string | - | - | - | | width | 宽度，默认单位为 px | number / string | - | - | - | | height | 高度，默认单位为 px | number / string | - | - | - | | mode | 填充模式 | ImageMode | 'top left' / 'top right' / 'bottom left' / 'bottom right' / 'right' / 'left' / 'center' / 'bottom' / 'top' / 'heightFix' / 'widthFix' / 'aspectFill' / 'aspectFit' / 'scaleToFill' | 'scaleToFill' | - | | round | 是否显示为圆形 | boolean | - | false | - | | radius | 圆角大小，默认单位为 px | number / string | - | - | - | | enable-preview | 是否支持点击预览 | boolean | - | false | 1.2.11 | | show-menu-by-longpress | 开启长按图片显示识别小程序码菜单，仅微信小程序支持 | boolean | - | false | 1.3.11 | | preview-src | 预览图片链接 | string | - | - | 1.8.0 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | -------------------- | --------------------------- | -------- | | click | 点击事件 | (event: MouseEvent) => void | - | | load | 当图片载入完毕时触发 | `{height, width}` | - | | error | 当错误发生时触发 | `{errMsg}` | - | ## Slots | 名称 | 说明 | 最低版本 | | ------- | ------------------ | -------- | | loading | 图片加载时展示 | 1.2.21 | | error | 图片加载失败后展示 | 1.2.21 | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | -------------------- | -------- | | custom-class | 根节点样式 | - | | custom-image | image 外部自定义样式 | - | --- --- url: 'https://wot-design-uni.cn/component/img-cropper.md' --- # ImgCropper 图片裁剪 图片剪裁组件，用于图片裁剪，支持拖拽、缩放、旋转等操作。 ## 基本用法 图片裁剪组件需要绑定 `v-model` 来控制组件的显示与隐藏，通过属性 `img-src` 控制展示的图片资源。进入组件后，可以对图片进行拖拽、双指缩放、旋转等操作，监听 `confirm` 事件获取裁剪结果。 > *注意：建议在新页面中使用图片裁剪组件，保持 `show` 为 true，完成裁剪后返回上一页。* ```html 点击上传头像 ``` ```typescript const src = ref('') const imgSrc = ref('') const show = ref(false) function upload() { uni.chooseImage({ count: 1, success: (res) => { const tempFilePaths = res.tempFilePaths[0] src.value = tempFilePaths show.value = true } }) } function handleConfirm(event) { const { tempFilePath } = event imgSrc.value = tempFilePath } function imgLoaderror(res) { console.log('加载失败', res) } function imgLoaded(res) { console.log('加载成功', res) } function handleCancel(event) { console.log('取消', event) } ``` ## 自定义裁剪比例 通过 `aspect-ratio` 属性可以设置裁剪框的宽高比，格式为 `width:height`。 ### 3:2 适合拍照 ```html ``` ### 16:9 影视比例 ```html ``` ### 16:10 这么阔 很有型 16:10 的显示比例非常适合展示风景照片或者电影海报等宽屏内容。 ```html ``` ## 裁剪后上传 结合 `useUpload` 可以实现裁剪完成后自动上传图片的功能。 ```html ``` ```typescript import { ref } from 'vue' import { useUpload, useToast } from '@/uni_modules/wot-design-uni' import { type UploadFileItem } from '@/uni_modules/wot-design-uni/components/wd-upload/types' const { startUpload, UPLOAD_STATUS } = useUpload() const { show: showToast } = useToast() const show = ref(false) const src = ref('') const imgSrc = ref('') async function handleConfirmUpload(event) { const { tempFilePath } = event // 构建上传文件对象 const file: UploadFileItem = { url: tempFilePath, status: UPLOAD_STATUS.PENDING, percent: 0, uid: new Date().getTime() } try { // 开始上传 await startUpload(file, { action: 'https://your-upload-url', onSuccess() { imgSrc.value = tempFilePath showToast({ msg: '上传成功' }) }, onError() { showToast({ msg: '上传失败' }) }, onProgress(res) { console.log('上传进度:', res.progress) } }) } catch (error) { console.error('上传失败:', error) } } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值| 最低版本 | |-----|------|-----|-------|-------|--------| | v-model | 打开图片裁剪组件 | boolean | - | false | - | | img-src | 图片资源链接 | string | - | - | - | | img-width | 截屏预览图片的初始宽度; `1、设置宽度不设置高度，按照宽度等比缩放；2、如果都不设置，预览时图片大小会根据裁剪框大小进行等比缩放，进行锁边处理；`; string 类型只支持 % 单位，number 类型时单位为 px | number / string | - | - | - | | img-height | 截屏预览图片的初始高度; `1、设置高度不设置宽度，按照高度等比缩放；2、如果都不设置，预览时图片大小会根据裁剪框大小进行等比缩放，进行锁边处理；`; string 类型只支持 % 单位，number 类型时单位为 px | number / string | - | - | - | | disabled-rotate | 禁止图片旋转 | boolean | - | false | - | | export-scale | 设置导出图片尺寸 | number | - | 2 | - | | max-scale | 最大缩放倍数 | number | - | 3 | - | | cancel-button-text | 取消按钮文案 | string | - | 取消 | - | | confirm-button-text | 确认按钮文案 | string | - | 完成 | - | | quality | 生成的图片质量 [wx.canvasToTempFilePath属性介绍](https://developers.weixin.qq.com/miniprogram/dev/api/canvas/wx.canvasToTempFilePath.html#%E5%8F%82%E6%95%B0) | number | 0/1 | 1 | - | | file-type | 目标文件的类型，[wx.canvasToTempFilePath属性介绍](https://developers.weixin.qq.com/miniprogram/dev/api/canvas/wx.canvasToTempFilePath.html#%E5%8F%82%E6%95%B0) | string | - | png | - | | aspect-ratio | 裁剪框宽高比，格式为 width:height | string | - | 1:1 | 1.9.0 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | |---------|-----|-----|---------| | confirm | 完成截图时触发 | `{tempFilePath, width, height}` 分别为生成文件的临时路径 (本地路径)、生成图片宽、生成图片高| - | | cancel | 当取消截图时触发 | - | - | | imgloaderror | 当图片加载错误时触发 | `{err} `| - | | imgloaded | 当图片加载完成时触发 | `{res}` | - | ## Methods 对外暴露函数 | 事件名称 | 说明 | 参数 | 最低版本 | |--------|------|-----|---------| | setRoate | 设置图片旋转角度 | deg (设置的旋转角度)| - | | resetImg | 重置图片的角度、缩放、位置 | - | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/index-bar.md' --- # IndexBar 索引栏 1.2.21 用于列表的索引分类显示和快速定位。 ## 基本用法 使用一个固定高度的元素包裹`wd-index-bar`组件,组件的宽高会和包裹元素相同。 将`wd-index-anchor`作为子组件使用,会根据 anchor 组件的`index`属性生成锚点以及侧边栏。 ```vue ``` ## 更新列表数据 列表数据如果需要更新，可以参考此示例 ::: details 查看更新列表数据示例 ::: code-group ```html [vue] ``` ```typescript [typescript] ``` ```css [css] .wraper { height: calc(100vh - var(--window-top)); height: calc(100vh - var(--window-top) - constant(safe-area-inset-bottom)); height: calc(100vh - var(--window-top) - env(safe-area-inset-bottom)); } ``` ::: ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------ | ------------ | ------- | ------ | ------ | -------- | | sticky | 索引是否吸顶 | boolean | - | false | - | ## IndexAnchor Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ----- | -------- | ---------------- | ------ | ------ | -------- | | index | 索引字符 | string / number | - | - | - | ## IndexAnchor Slots | name | 说明 | 参数 | 最低版本 | | ------- | ---------- | ---- | -------- | | default | 自定义内容 | - | - | ## IndexAnchor 外部样式类 | 类名 | 说明 | 最低版本 | | ----------- | ------------ | -------- | | customStyle | 自定义样式 | - | | customClass | 自定义样式类 | - | --- --- url: 'https://wot-design-uni.cn/component/input.md' --- # Input 输入框 用户可以在文本框里输入内容。 ::: tip 提示 `0.2.0`版本已将 `Input` 组件的 `textarea 文本域`功能迁移至 [Textarea](/component/textarea)组件，所有API保持一致。 ::: ## 基本用法 可以通过 `v-model` 双向绑定输入框的值，通过 `placeholder` 设置占位提示文字。 ```typescript const value = ref('') function handleChange(event) { console.log(event) } ``` ```html ``` ## 禁用 设置 `disabled` 属性。 ```html ``` ## 只读 设置 `readonly` 属性。 ```html ``` ## 清空按钮 设置 `clearable` 属性。 ```html ``` ## 有值且聚焦时展示清空按钮 设置 `clear-trigger` 属性，可以控制是否聚焦时才展示清空按钮。 :::warning 注意 支付宝小程序暂不支持 `clear-trigger` 属性，且某种情况下清空按钮无法点击，原因参考此[issue](https://github.com/ant-design/ant-design-mini/issues/1255)（希望可以早点解决，所以直接给蚂蚁的组件库提了个issue）。 ::: ```html ``` ## 点击清除按钮时不自动聚焦 设置`focus-when-clear` 属性，可以控制点击清除按钮时是否自动聚焦。 ```html ``` ## 密码输入框 设置 `show-password` 属性。 ```html ``` ## 前后icon 设置前置icon `prefix-icon`，设置后置icon `suffix-icon`，icon 为 [icon](/component/icon) 章节中的图标，如果没有你需要的图标，则使用 `prefix`、`suffix` 插槽进行自定义插入。 ```html ``` ## 限制字数输入 设置 `maxlength` 属性，如果要显示字数限制，设置 `show-word-limit` 属性。 ```html ``` ## 设置label标题 设置 `label` 标题，可以和 `cell-group` 组合使用，形成 `cell` 展示类型。可以通过 `label-width` 设置标题宽度，默认为 '33%'。 ```html ``` ## 必填样式 设置了 `label` 的情况下，设置 `required` 属性，展示必填样式。 ```html ``` ## 输入框大小 通过设置 `size` 修改输入框大小，将 `size` 设置为 'large' 时字号为 16px。 ```html ``` ## 错误状态 设置 `error` 属性，输入框的值显示为红色。 ```html ``` ## 垂直居中 当设置 `label` 标题时，默认为顶部居中，设置 `center` 属性可以使标题和输入框垂直居中。 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------- | -------------------------------------- | -------- | | type | 类型 | string | text / number / digit / idcard / safe-password / nickname / tel | text | - | | v-model | 绑定值 | string / number | - | - | - | | placeholder | 占位文本 | string | - | 请输入... | - | | clearable | 显示清空按钮 | boolean | - | false | - | | maxlength | 原生属性，最大长度 | number | - | 支付宝小程序无默认值，其余平台默认为-1 | - | | showPassword | 显示为密码框 | boolean | - | false | - | | disabled | 原生属性，禁用 | boolean | - | false | - | | readonly | 只读 | boolean | - | false | - | | prefixIcon | 前置图标，icon组件中的图标类名 | string | - | - | - | | suffixIcon | 后置图标，icon组件中的图标类名 | string | - | - | - | | showWordLimit | 显示字数限制，需要同时设置 maxlength | boolean | - | false | - | | confirm-type | 设置键盘右下角按钮的文字，仅在type='text'时生效 | string | done / go / next / search / send | done | - | | confirm-hold | 点击键盘右下角按钮时是否保持键盘不收起 | Boolean | - | false | - | | always-embed | 微信小程序原生属性，强制 input 处于同层状态，默认 focus 时 input 会切到非同层状态 (仅在 iOS 下生效) | Boolean | - | false | - | | placeholderStyle | 原生属性，指定 placeholder 的样式，目前仅支持color,font-size和font-weight | string | - | - | - | | placeholderClass | 原生属性，指定 placeholder 的样式类 | string | - | - | - | | focus | 原生属性，获取焦点 | boolean | - | false | - | | cursorSpacing | 原生属性，指定光标与键盘的距离。取 input 距离底部的距离和cursor-spacing指定的距离的最小值作为光标与键盘的距离 | number | - | 0 | - | | cursor | 原生属性，指定focus时的光标位置 | number | - | -1 | - | | selectionStart | 原生属性，光标起始位置，自动聚集时有效，需与selection-end搭配使用 | number | - | -1 | - | | selectionEnd | 原生属性，光标结束位置，自动聚集时有效，需与selection-start搭配使用 | number | - | -1 | - | | adjustPosition | 原生属性，键盘弹起时，是否自动上推页面 | boolean | - | true | - | | label | 设置左侧标题 | string | - | - | - | | size | 设置输入框大小 | string | - | - | - | | error | 设置输入框错误状态，错误状态时为红色 | boolean | - | false | - | | center | 当有label属性时，设置标题和输入框垂直居中，默认为顶部居中 | boolean | - | false | - | | label-width | 设置左侧标题宽度 | string | - | 33% | - | | required | cell 类型下必填样式 | boolean | - | false | - | | no-border | 非 cell 类型下是否隐藏下划线 | boolean | - | false | - | | prop | 表单域 `model` 字段名，在使用表单校验功能的情况下，该属性是必填的 | string | - | - | - | | rules | 表单验证规则，结合`wd-form`组件使用 | `FormItemRule []` | - | `[]` | - | | clearTrigger | 显示清除图标的时机，always 表示输入框不为空时展示，focus 表示输入框聚焦且不为空时展示 | `InputClearTrigger` | `focus` / `always` | `always` | 1.3.7 | | focusWhenClear | 是否在点击清除按钮时聚焦输入框 | boolean | - | true | 1.3.7 | | ignoreCompositionEvent | 是否忽略组件内对文本合成系统事件的处理。为 false 时将触发 compositionstart、compositionend、compositionupdate 事件，且在文本合成期间会触发 input 事件。 | boolean | - | true | 1.3.11 | | inputmode | 提供用户在编辑元素或其内容时可能输入的数据类型的提示。 | InputMode | - | text | 1.5.0 | ### InputMode 可选值 > 新增于 uni-app 3.6.16+ inputmode是html规范后期更新的内容。各家小程序还未支持此属性。 在符合条件的高版本webview里，uni-app的web和app-vue平台中可使用本属性，参见[inputmode](https://uniapp.dcloud.net.cn/component/input.html#inputmode)。 | 值 | 说明 | | ------- | -------------------------------------------------------------------------------------------------------------------- | | none | 无虚拟键盘。在应用程序或者站点需要实现自己的键盘输入控件时很有用。 | | text | 使用用户本地区域设置的标准文本输入键盘。 | | decimal | 小数输入键盘，包含数字和分隔符（通常是“ . ”或者“ , ”），设备可能也可能不显示减号键。 | | numeric | 数字输入键盘，所需要的就是 0 到 9 的数字，设备可能也可能不显示减号键。 | | tel | 电话输入键盘，包含 0 到 9 的数字、星号（\*）和井号（#）键。表单输入里面的电话输入通常应该使用 。 | | search | 为搜索输入优化的虚拟键盘，比如，返回键可能被重新标记为“搜索”，也可能还有其他的优化。 | | email | 为邮件地址输入优化的虚拟键盘，通常包含"@"符号和其他优化。表单里面的邮件地址输入应该使用 。 | | url | 为网址输入优化的虚拟键盘，比如，“/”键会更加明显、历史记录访问等。表单里面的网址输入通常应该使用 。 | ## FormItemRule | 键名 | 说明 | 类型 | | --------- | ------------------------------------------------------- | ------------------------------------- | | required | 是否为必选字段 | `boolean` | | message | 错误提示文案 | `string` | | validator | 通过函数进行校验，可以返回一个 `Promise` 来进行异步校验 | `(value, rule) => boolean \| Promise` | | pattern | 通过正则表达式进行校验，正则无法匹配表示校验不通过 | `RegExp` | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------------------- | -------------------------------- | -------------------------------------- | -------- | | input | 监听输入框input事件 | `{value, cursor, keyCode}` | - | | focus | 监听输入框focus事件 | `{ value, height }`, height 为键盘高度 | - | | blur | 监听输入框blur事件 | `{ value }` | - | | clear | 监听输入框清空按钮事件 | - | - | | confirm | 点击完成时， 触发 confirm 事件 | `{ value }` | - | | keyboardheightchange | 键盘高度发生变化的时候触发此事件 | `{ height, duration }` | - | | clickprefixicon | 点击前置图标时触发 | - | - | | clicksuffixicon | 点击后置图标时触发 | - | - | ## Slot | name | 说明 | 最低版本 | | ------ | ------------ | -------- | | label | 左侧标题插槽 | - | | prefix | 前置插槽 | - | | suffix | 后置插槽 | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------------ | -------------------- | -------- | | custom-class | 根节点样式 | - | | custom-input-class | input 外部自定义样式 | - | | custom-label-class | label 外部自定义样式 | - | --- --- url: 'https://wot-design-uni.cn/component/input-number.md' --- # InputNumber 计数器 由增加按钮、减少按钮和输入框组成，用于在一定范围内输入、调整数字。 ## 基本用法 通过 `v-model` 绑定输入值，可以通过 `change` 事件监听到输入值的变化。 ```html ``` ```typescript const value = ref(1) function handleChange({ value }) { console.log(value) } ``` ## 设置步长 设置 `step` 步长，即每次value变化的绝对值。 ```html ``` ## 设置最小最大值 设置 `min` 最小值，`max` 最大值。`min` 默认为1。 ```html ``` ## 禁用 设置 `disabled` 属性。 ```html ``` ## 禁用输入框 设置 `disable-input` 属性。 ```html ``` ## 无输入框 设置 `without-input` ，不展示输入框。 ```html ``` ## 设置小数精度 设置 `precision` 属性，默认为0。 ```html ``` ## 严格步数倍数 设置 `step-strictly` 属性，强制输入框输入内容为 `step` 的倍数（当用户输入完成后触发change时，会更正输入框内容）。 ```html ``` ## 修改输入框宽度 设置 `input-width` 设置宽度，该值接受1个字符串，可以是表示尺寸的任何单位。 ```html ``` ## 允许空值，设置 placeholder 设置 `allow-null` 属性允许空值，设置 `placeholder` 提示填写。 ```html ``` ```typescript const value = ref('') function handleChange({ value }) { console.log(value) } ``` ## 异步变更 通过 `before-change` 可以在输入值变化前进行校验和拦截。 ```html ``` ```typescript import { ref } from 'vue' import { useToast } from '@/uni_modules/wot-design-uni' import type { InputNumberBeforeChange } from '@/uni_modules/wot-design-uni/components/wd-input-number/types' const { loading, close } = useToast() const value = ref(1) const beforeChange: InputNumberBeforeChange = (value) => { loading({ msg: `正在更新到${value}...` }) return new Promise((resolve) => { setTimeout(() => { close() resolve(true) }, 500) }) } ``` ## 长按加减 设置 `long-press` 属性，允许长按加减。 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|--------| | v-model | 绑定值 | number / string | - | - | - | | min | 最小值 | number | - | 1 | - | | max | 最大值 | number | - | Infinity | - | | step | 步数 | number | - | 1 | - | | step-strictly | 严格值为步数的倍数 | boolean | - | false | - | | precision | 小数精度 | number | - | 0 | - | | disabled | 禁用 | boolean | - | false | - | | without-input | 不显示输入框 | boolean | - | false | - | | input-width | 输入框宽度 | string | - | 36px | - | | allow-null | 是否允许输入的值为空，设置为 `true` 后允许传入空字符串 | boolean | - | false | - | | placeholder | 占位文本 | string | - | - | - | | disable-input | 禁用输入框 | boolean | - | false | 0.2.14 | | disable-plus | 禁用增加按钮 | boolean | - | false | 0.2.14 | | disable-minus | 禁用减少按钮 | boolean | - | false | 0.2.14 | | adjustPosition | 原生属性，键盘弹起时，是否自动上推页面 | boolean | - | true | 1.3.11 | | before-change | 输入框值改变前触发，返回 false 会阻止输入框值改变，支持返回 `Promise` | `(value: number \| string) => boolean \| Promise` | - | - | 1.6.0 | | long-press | 是否允许长按进行加减 | boolean | - | false | 1.8.0 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | |---------|-----|-----|---------| | change | 值修改事件 | ` { value }` | - | | focus | 输入框获取焦点事件 | ` { value, height }` | - | | blur | 输入框失去焦点事件 | ` { value }` | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/keyboard.md' --- # Keyboard 虚拟键盘 1.3.10 虚拟数字键盘，用于输入数字、密码、身份证或车牌号等场景。 ## 基本用法 可以通过 `v-model:visible` 控制键盘是否展示。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 带右侧栏的键盘 将 `mode` 属性设置为 `custom` 来展示键盘的右侧栏，常用于输入金额的场景。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 身份证键盘 通过 `extra-key` 属性可以设置左下角按键内容，比如需要输入身份证号时，可以将 `extra-key` 设置为 `X`。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 车牌号键盘 将 `mode` 属性设置为 `car` 来展示车牌号键盘，常用于输入车牌号的场景。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 带标题的键盘 通过 `title` 属性可以设置键盘标题。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 使用 slot 自定义标题 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 多个额外按键 当 `mode` 为 `custom` 时，支持以数组的形式配置两个 `extra-key`。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 随机数字键盘 通过 `random-key-order` 属性可以随机排序数字键盘，常用于安全等级较高的场景。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 双向绑定 可以通过 `v-model` 绑定键盘当前输入值，并通过 `maxlength` 属性来限制输入长度。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) const value1 = ref('') function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 展示蒙层遮罩 `hideOnClickOutside`控制键盘弹窗是否有遮罩，通过`modal`控制遮罩是否为透明。 ::: tip 提示 当前`modal`仅控制遮罩是否为透明，`hideOnClickOutside`控制弹窗是否有遮罩，当存在遮罩时，点击遮罩就可以关闭键盘，但是键盘展开时必须点击遮罩关闭当前键盘后才可以再点击别的按钮。也可以关闭`hideOnClickOutside`，手动控制键盘是否展示来实现点击外部时收起键盘，这样更灵活。 ::: ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) const value1 = ref('') function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------------- | ------------------------ | --------------------- | -------------------------- | ---------- | ---------------- | | v-model:visible | 是否展开 | `boolean` | - | `false` | 1.3.10 | | v-model | 绑定的值 | `string` | - | - | 1.3.10 | | title | 标题 | `string` | - | - | 1.3.10 | | mode | 键盘模式 | `string` | `default`, `car`, `custom` | `default` | 1.3.10 | | zIndex | 层级 | `number` | - | `100` | 1.3.10 | | maxlength | 最大长度 | `number` | - | `Infinity` | 1.3.10 | | showDeleteKey | 是否显示删除键 | `boolean` | - | `true` | 1.3.10 | | randomKeyOrder | 是否随机键盘按键顺序 | `boolean` | - | `false` | 1.3.10 | | closeText | 确认按钮文本 | `string` | - | - | 1.3.10 | | deleteText | 删除按钮文本 | `string` | - | - | 1.3.10 | | closeButtonLoading | 关闭按钮是否显示加载状态 | `boolean` | - | `false` | 1.3.10 | | modal | 是否显示蒙层遮罩 | `boolean` | - | `false` | 1.3.10 | | hideOnClickOutside | 是否在点击外部时收起键盘 | `boolean` | - | `true` | 1.3.10 | | lockScroll | 是否锁定滚动 | `boolean` | - | `true` | 1.3.10 | | safeAreaInsetBottom | 是否在底部安全区域内 | `boolean` | - | `true` | 1.3.10 | | extraKey | 额外按键 | `string` / `string[]` | - | - | 1.3.10 | ## Slot | name | 说明 | 类型 | 最低版本 | | ----- | ---- | ---- | -------- | | title | 标题 | - | 1.2.12 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ------------------------------ | ----------- | -------- | | input | 点击按键时触发 | key: string | - | | delete | 点击删除键时触发 | - | - | | close | 点击关闭按钮或非键盘区域时触发 | - | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ------------ | -------- | | custom-class | 根节点样式类 | 1.3.10 | | custom-style | 根节点样式 | 1.3.10 | --- --- url: 'https://wot-design-uni.cn/component/layout.md' --- # Layout 布局 用于快速进行布局。 ## 基本用法 `Layout` 组件提供了 `24列` 栅格，通过在 `wd-col` 上设置 `span` 属性，通过计算当前内容所占百分比进行分栏。 注意: 分栏布局仅提供布局，即元素宽度，内部样式用户可根据需要通过 `custom-class` 或 `修改内部标签` 来自行定义样式。 ```html span: 24 span: 12 span: 12 span: 8 span: 8 span: 8 span: 6 span: 6 span: 6 span: 6 ``` ```scss .bg-dark1, .bg-dark, .bg-light{ border-radius: 4px; min-height: 30px; text-align: center; line-height: 30px; font-size: 12px; margin-bottom: 10px; color: rgba(0, 0, 0, 0.45); } .bg-dark1 { background: #99a9bf; color: #fff; } .bg-dark { background: #d3dce6; } .bg-light { background: #e5e9f2; } ``` ## 分栏偏移 `offset` 属性可以设置分栏的偏移量，计算方式以及偏移大小与 `span` 相同。 ```html span: 4 span: 8 offset: 4 span: 8 offset: 4 span: 8 offset: 4 ``` ## 分栏间隔 通过 `gutter` 属性可以设置列元素之间的间距，默认间距为 0 ```html span: 8 span: 8 span: 8 ``` ## Row Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|--------| | gutter | 列元素之间的间距（单位为px） | number | - | 0 | - | ## Col Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|---------| | span | 列元素宽度 | number | - | 24 | - | | offset | 列元素偏移距离 | number | - | 0 | - | ## Row 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | Row 根节点样式 | - | ## Col 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | Col 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/loading.md' --- # Loading 加载指示器 加载动画，用于表示加载中的过渡状态。 ## 基本用法 基本用法，适用于按钮加载状态和页面轻提示。 ```html ``` ## 修改指示器类型 通过 `type` 修改指示器的类型，可选值为 'outline'，适用于通用模块加载。 ```html ``` ## 修改颜色 通过 `color` 属性修改指示器的颜色。比如修改为白色，同时设置背景为黑色。 :::warning 小程序中没有 svg 标签，所以是先通过js生成svg标签，再转换成 base64，因此设置指示器颜色必须为16进制色值，且不接受色值缩写。 ::: ```html ``` ```scss :deep(.loading-black) { background: rgba(0, 0, 0, 0.7); padding: 10px; border-radius: 4px; } ``` ## 修改指示器大小 通过 `size` 属性设置指示器的大小，默认为大小 '32px'，属性支持 `number`/`string` 类型。 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|---------| | type | 加载指示器类型 | string | outline | ring | - | | color | 设置加载指示器颜色 | string | - | #4D80F0 | - | | size | 设置加载指示器大小 | number / string | - | 32px | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/loadmore.md' --- # loadmore 加载更多 用于在列表底部展示加载状态。 ## 基本用法 在需要进行加载的列表的底部引入该组件即可。当滑动到列表底部时，通过设置`state`展示不同的文案。 ```html ``` ```scss :deep(.loadmore) { background-color: #f4f4f4; margin: 20px 0; } ``` ## 自定义文案 通过设置`loading-text`、`finished-text`、`error-text`配合`state`展示不同状态时的文案 ```html ``` ## 点击继续加载 当 state 为 error 时，点击文案，组件会触发`loadmore`事件 ```html ``` ## 应用实现 配合`onReachBottom`事件实现滚动到底部加载更多 ```html 这是一条测试{{ index + 1 }} ``` ```typescript import { onLoad, onReachBottom } from '@dcloudio/uni-app' const state = ref('loading') const num = ref(0) const max = ref(60) onReachBottom(() => { if (num.value === 45) { state.value = 'error' } else if (num.value < max.value) { loadmore() } else if (num.value === max.value) { state.value = 'finished' } }) onLoad(() => { loadmore() }) function loadmore() { setTimeout(() => { num.value = num.value + 15 state.value = 'loading' }, 200) } ``` ```scss .list-item { position: relative; display: flex; padding: 10px 15px; background: #fff; color: #464646; } .list-item:after { position: absolute; display: block; content: ''; height: 1px; left: 0; width: 100%; bottom: 0; background: #eee; transform: scaleY(0.5); } image { display: block; width: 120px; height: 78px; margin-right: 15px; } .right { -webkit-box-flex: 1; -ms-flex: 1; flex: 1; } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------- | -------------------- | ------ | ---------------------- | ------------------ | -------- | | state | 加载状态 | string | loading/finished/error | - | - | | loading-text | 加载提示文案 | string | - | 加载中... | - | | finished-text | 全部加载完的提示文案 | string | - | 没有更多了 | - | | error-text | 加载失败的提示文案 | string | - | 加载失败，点击重试 | - | | loading-props | loading加载组件属性| `Partial` | - | - | 1.3.14 | #### LoadingProps 参见[LoadingProps](/component/loading.html#attributes) ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | --------------------------------------------------- | ---- | -------- | | reload | state 为 error 加载错误时，点击文案触发 reload 事件 | - | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/message-box.md' --- # MessageBox 弹框 弹出对话框，常用于消息提示、消息确认等，支持函数调用。 ## Alert 弹框 alert 弹框只有确定按钮，用于强提醒。 ```html alert ``` ```typescript import { useMessage } from '@/uni_modules/wot-design-uni' const message = useMessage() function alert() { message.alert('操作成功') } ``` 显示标题的 alert 弹框。 ```html alert ``` ```typescript import { useMessage } from '@/uni_modules/wot-design-uni' const message = useMessage() function alert() { message.alert({ msg: '提示文案', title: '标题' }) } ``` 如果内容文案过长，弹框高度不再增加，而是展示滚动条。 ```html alert ``` ```typescript import { useMessage } from '@/uni_modules/wot-design-uni' const message = useMessage() function alert() { message.alert({ msg: '以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文字是示意以上文', title: '标题' }) } ``` ## Confirm 弹框 用于提示用户操作。 ```html confirm ``` ```typescript import { useMessage } from '@/uni_modules/wot-design-uni' const message = useMessage() function confirm() { message .confirm({ msg: '提示文案', title: '标题' }) .then(() => { console.log('点击了确定按钮') }) .catch(() => { console.log('点击了取消按钮') }) } ``` ## Prompt 弹框 prompt 会展示一个输入框，并可以进行输入校验。 ```html prompt ``` ```typescript import { useMessage } from '@/uni_modules/wot-design-uni' const message = useMessage() function prompt() { message .prompt({ title: '请输入邮箱', inputValue: value1.value, inputPattern: /.+@.+\..+/i }) .then((resp) => { console.log(resp) }) .catch((error) => { console.log(error) }) } ``` ## 插槽 如果提供的弹框内容不满足需求，可以使用插槽自定义弹框内容。可以通过指定唯一标识`selector`的方式，在一个页面中使用多个`MessageBox`,`useMessage(selector)`会返回一个指定了`selector`的组件实例。 ```html custom ``` ```typescript import { useMessage } from '@/uni_modules/wot-design-uni' const rate = ref(1) const message = useMessage('wd-message-box-slot') function withSlot() { message .confirm({ title: '评分' }) .then(() => { message.alert(`你的评分为：${rate.value}分`) }) .catch((error) => { console.log(error) }) } ``` ```scss :deep(.custom-rate-class) { display: block; height: 22px; } ``` ## 确认前置处理 设置 `beforeConfirm` 函数，在用户选择图片点击确认后，会执行 `beforeConfirm` 函数，接收 { resolve }，开发者可以在确认前进行处理，并通过 `resolve` 函数告知组件是否确定通过，`resolve` 接受 1 个 `boolean` 值，`resolve(true)` 表示选项通过，`resolve(false)` 表示选项不通过，不通过时不会完成确认操作。 ```html beforeConfirm ``` ```typescript import { useMessage, useToast } from '@/uni_modules/wot-design-uni' const message = useMessage() const toast = useToast() function beforeConfirm() { message .confirm({ msg: '是否删除', title: '提示', beforeConfirm: ({ resolve }) => { toast.loading('删除中...') setTimeout(() => { toast.close() resolve(true) toast.success('删除成功') }, 2000) } }) .then(() => {}) .catch((error) => { console.log(error) }) } ``` ## 自定义操作按钮1.5.0 可以通过按钮属性 `cancel-button-props` 和 `confirm-button-props` 自定义操作按钮的样式，具体参考 [Button Attributes](/component/button.html#attributes)。 ```html 自定义按钮 ``` ```typescript function withButtonProps() { message .confirm({ msg: '自定义按钮样式', title: '提示', cancelButtonProps: { type: 'error', customClass: 'custom-shadow' }, confirmButtonProps: { type: 'success', customClass: 'custom-shadow' } }) .then(() => {}) .catch((error) => { console.log(error) }) } ``` ```css :deep() { .wd-message-box { .custom-shadow { box-shadow: 0 3px 1px -2px rgb(0 0 0 / 20%), 0 2px 2px 0 rgb(0 0 0 / 14%), 0 1px 5px 0 rgb(0 0 0 / 12%); } } } ``` *** 弹框在点击确定和取消按钮时，会返回一个 promise 对象，用 then 接收“确定”按钮事件，用 catch 接收“取消”按钮事件。传入的 action 值为:'confirm'、'cancel'、'modal'。 `MessageBox.show(msg)`在调用时直接传入字符串，`MessageBox.show(options)` 在调用时，需传入 options 参数。alert、confirm 和 prompt 都支持快捷调用： ```typescript MessageBox.show(msg) MessageBox.show(options) MessageBox.alert(options) MessageBox.confirm(options) MessageBox.prompt(options) ``` ## Options | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | -------------------- | ------------------------------------------------------------------------------- | --------------- | ------------------------ | ---------------- | ---------------- | | title | 标题 | string | - | - | - | | msg | 消息文案 | string | - | - | - | | type | 弹框类型 | string | alert / confirm / prompt | alert | - | | closeOnClickModal | 是否支持点击蒙层进行关闭，点击蒙层回调传入的 action 为'modal' | boolean | - | true | - | | inputType | 当 type 为 prompt 时，输入框类型 | string | - | text | - | | inputValue | 当 type 为 prompt 时，输入框初始值 | string / number | - | - | - | | inputPlaceholder | 当 type 为 prompt 时，输入框 placeholder | string | - | 请输入内容 | - | | inputPattern | 当 type 为 prompt 时，输入框正则校验，点击确定按钮时进行校验 | regex | - | - | - | | inputValidate | 当 type 为 prompt 时，输入框校验函数，点击确定按钮时进行校验 | function | - | - | - | | inputError | 当 type 为 prompt 时，输入框检验不通过时的错误提示文案 | string | - | 输入的数据不合法 | - | | confirmButtonText | 确定按钮文案 | string | - | 确定 | - | | cancelButtonText | 取消按钮文案 | string | - | 取消 | - | | zIndex | 弹窗层级 | number | - | 99 | - | | lazyRender | 弹层内容懒渲染，触发展示时才渲染内容 | boolean | - | true | - | | cancel-button-props | 取消按钮的属性，具体参考 [Button Attributes](/component/button.html#attributes) | object | - | - | 1.5.0 | | confirm-button-props | 确定按钮的属性，具体参考 [Button Attributes](/component/button.html#attributes) | object | - | - | 1.5.0 | ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------- | -------- | ------- | ------ | ------ | -------- | | selector | 指定唯一标识 | string | - | - | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/navbar.md' --- # Navbar 导航栏 为页面提供导航功能，常用于页面顶部。 ::: tip 常见问题 **右图标被小程序胶囊挡住？** 在小程序平台开启自定义顶部导航时，右上角会固定显示胶囊，所以此时右侧插槽及选项是不建议使用。 **如何设置为背景透明？** 通过 `custom-style` 设置组件 `background-color` 为 `transparent`。 ```html ``` **组件会被 `video` 覆盖？** `video`为原生组件，层级较高，目前无法遮盖，需要具体平台具体分析。 ::: ## 基础用法 通过 `title` 属性设置导航栏标题。 ```html ``` ## 返回上级 在导航栏实现返回上级功能。 ```html ``` ```ts function handleClickLeft() { uni.navigateBack() } ``` ## 右侧按钮 在导航栏右侧添加可点击的按钮。 ```html ``` ```ts import { useToast } from '@/uni_modules/wot-design-uni' const { show: showToast } = useToast() function handleClickRight() { showToast('按钮') } ``` ## 使用插槽 可以通过 `left` 和 `right` 插槽自定义导航栏两侧的内容。 ```html ``` ## 固定在顶部 通过 `fixed` 可以设置导航条固定在页面顶部，通过设置 `placeholder` 可以在顶部生成占位空间，通过设置 `safeAreaInsetTop` 可以开启顶部安全区的适配。 ```html ``` ## 禁用按钮 通过 `left-disabled` 或 `right-disabled` 属性来禁用两侧的按钮。按钮被禁用时透明度降低，且无法点击。 ```html ``` ## 胶囊样式 通过 `capsule` 插槽和 `navbar-capsule` 组件定制返回胶囊。 ```html ``` ```ts function handleBack() { uni.navigateBack({}) } function handleBackHome() { uni.reLaunch({ url: '/pages/index/Index' }) } ``` ## 带搜索栏 通过 `title` 插槽，自定义标题。 ```html ``` ```scss .search-box { display: flex; height: 100%; align-items: center; --wot-search-padding: 0; --wot-search-side-padding: 0; :deep() { .wd-search { background: transparent; } } } ``` ## Navbar Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------- | -------- | ------- | ------ | ------ | -------- | | title | 卡片标题 | string | - | '' | 0.1.33 | | leftText | 左侧文案 | string | - | '' | 0.1.33 | | rightText | 右侧文案 | string | - | '' | 0.1.33 | | leftArrow | 显示左侧箭头 | boolean | true, false | false | 0.1.33 | | bordered | 显示下边框 | boolean | true, false | true | 0.1.33 | | fixed | 固定到顶部 | boolean | true, false | false | 0.1.33 | | placeholder | 固定在顶部时，在标签位置生成一个等高的占位元素 | boolean | true, false | false | 0.1.33 | | zIndex | 导航栏 z-index | number | - | 1 | 0.1.33 | | safeAreaInsetTop | 开启顶部安全区适配 | boolean | true, false | false | 0.1.33 | | leftDisabled | 禁用左侧按钮，禁用时透明度降低，且无法点击 | boolean | true, false | false | 0.1.33 | | rightDisabled | 禁用右侧按钮，禁用时透明度降低，且无法点击 | boolean | true, false | false | 0.1.33 | ## Navbar Events | 事件名称 | 说明 | 参数 | 最低版本 | | ------------ | ----------------------------- | ---------------------------------------------- | --------- | | click-left | 点击左侧按钮时触发 | - | 0.1.33 | | click-right | 点击右侧按钮时触发 | - | 0.1.33 | ## NavbarCapsule Events | 事件名称 | 说明 | 参数 | 最低版本 | | ------------ | ----------------------------- | ---------------------------------------------- | --------- | | back | 点击返回按钮时触发 | - | 0.1.33 | | back-home | 点击返回首页按钮时触发 | - | 0.1.33 | ## Navbar Slot | 名称 | 说明 | 最低版本 | | ------- | -------- | -------- | | capsule | 自定义胶囊（当存在胶囊时，left不生效） | 0.1.33 | | left | 左侧内容 | 0.1.33 | | title | 标题内容 | 0.1.33 | | right | 右侧内容 | 0.1.33 | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式类 | 0.1.33 | | custom-style | 根节点样式 | 0.1.33 | --- --- url: 'https://wot-design-uni.cn/component/notice-bar.md' --- # NoticeBar 通知栏 通知栏组件，用于在页面顶部展示通知提醒。 ## 基本用法 设置 `text` 文本内容和 `prefix` 左侧图标。 ```html ``` ## 类型修改 设置 `type` 可修改通知类型，通知类型共有三种 `info`|`warning`|`danger`，默认值为`warning`。 ```html ``` ```scss :deep(.space) { margin-bottom: 10px; } ``` ## 插槽演示 ```html 通知被禁或时段内消息屏蔽可能造成消… ``` ```scss :deep(.prefix) { font-size: 18px; padding-right: 4px; width: 18px; height: 18px; } ``` ## 多行展示 设置 `wrapable` 属性为 `true` 且同时禁止滚动 `scrollable` 即可开启多行展示。 ```html ``` ## 可关闭的 设置 `closable` 属性，使通知栏可以关闭。 ```html ``` ## 自定义颜色 设置 `color` 修改文字和图标颜色，设置 `background-color` 修改背景颜色。 ```html ``` ## 多文本轮播 将一个`string[]`传递给`text`属性，即可开启多文本轮播，并且会在展示下一条文本时触发`next`事件，该事件接收一个`number`参数，代表的是当前展示的文本数组索引 ```html ``` ```javascript import { ref } from 'vue' const textArray = ref([ '欢迎使用wot design uni', '该组件库基于uniapp ->Vue3, ts构建', '项目地址：https://github.com/Moonofweisheng/wot-design-uni', '我们的目标是打造最强uniapp组件库', '诚挚邀请大家共同建设', '这是一条消息提示信息，这是一条消息提示信息，这是一条消息提示信息，这是一条消息提示信息，这是一条消息提示信息' ]) const onNext = (index: number) => { console.log('展示下一条，index: ', index) console.log('文本是：' + textArray.value[index]) } ``` ## 垂直滚动 1. `direction`传递`vertical`即可开启垂直滚动，目前仅支持一个方向的垂直滚动 2. `text`为数组时才会进行滚动 ```html ``` ## 重置播放动画 1.3.13 通过`ref`获取组件实例，调用`reset`方法即可重置播放动画。当你遇到`NoticeBar`的播放动画异常的情况时，可以调用`reset`方法重置动画。 例如：在`APP-VUE`端，`Tabbar`页面使用`NoticeBar`时，从其它界面返回到`NoticeBar`页面，会偶发`NoticeBar`动画异常，此时可以调用`reset`方法重置动画。 参考issues：[#358](https://github.com/Moonofweisheng/wot-design-uni/issues/358)、[#650](https://github.com/Moonofweisheng/wot-design-uni/issues/650) ```html 重置播放动画 ``` ```ts // uni_modules import { type NoticeBarInstance } from '@/uni_modules/wot-design-uni/components/wd-notice-bar/types' // npm // import { type NoticeBarInstance } from 'wot-design-uni/components/wd-notice-bar/types' const notice = ref() const textArray = ref([ '欢迎使用wot design uni', '该组件库基于uniapp ->Vue3, ts构建', '项目地址：https://github.com/Moonofweisheng/wot-design-uni', '我们的目标是打造最强uniapp组件库', '诚挚邀请大家共同建设', '这是一条消息提示信息，这是一条消息提示信息，这是一条消息提示信息，这是一条消息提示信息，这是一条消息提示信息' ]) function handleReset() { notice.value?.reset() } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ---------------- | -------------------------------------- | -------------------------- | ----------------------- | ------------ | -------- | | text | 设置通知栏文案 | `string` `string[]` | - | - | - | | type | 设置通知栏类型 | `string` | info / warning / danger | warning | - | | prefix | 设置左侧图标，使用 icon 章节中的图标名 | `string` | - | - | - | | scrollable | 是否可以滚动 | `boolean` | - | true | - | | delay | 滚动动画初始延时，单位 秒(s) | `number` | - | 1 | - | | speed | 滚动速度，单位 px/s | `number` | - | 50 | - | | closable | 是否可以关闭 | `boolean` | - | false | - | | wrapable | 是否换行展示 | `boolean` | - | false | - | | color | 文字、图标颜色 | `string` | - | - | - | | background-color | 背景颜色 | `string` | - | - | - | | direction | 滚动方向 | `NoticeBarScrollDirection` | `horizontal` `vertical` | `horizontal` | - | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ---------------- | ------------------------------------------------------------------------------ | -------- | | close | 关闭按钮点击时 | - | - | | next | 下一次滚动前触发 | index: `number` | - | | click | 点击时触发 | `{ text: string, index: number }`，其中`text`为当前文本，`index`为当前文本索引 | 1.2.16 | ## Methods | 方法名称 | 说明 | 参数 | 最低版本 | |---------|-----|-----|---------| | reset | 用于重置播放动画| - | 1.3.13 | ## Slot | name | 说明 | 类型 | 最低版本 | | ------- | ------------ | ---- | -------- | | prefix | 前置图标 | - | - | | suffix | 后置插槽 | - | - | | default | 通知文本内容 | - | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/notify.md' --- # Notify 消息通知 通知类组件，用于在页面顶部展示通知信息。 ## 基本用法 需要在页面中引入该组件，作为挂载点。 ```html ``` ```ts import { useNotify } from '@/uni_modules/wot-design-uni' const { showNotify, closeNotify } = useNotify() // 3 秒后自动关闭 showNotify('通知内容') // 主动关闭 closeNotify() ``` ## 通知类型 支持 `primary`、`success`、`warning`、`danger` 四种通知类型，默认为 `danger`。 ```ts // 主要通知 showNotify({ type: 'primary', message: '通知内容' }) // 成功通知 showNotify({ type: 'success', message: '通知内容' }) // 危险通知 showNotify({ type: 'danger', message: '通知内容' }) // 警告通知 showNotify({ type: 'warning', message: '通知内容' }) ``` ## 自定义通知 ```ts showNotify({ message: '自定义颜色', color: '#ad0000', background: '#ffe1e1' }) showNotify({ message: '自定义位置', position: 'bottom' }) showNotify({ message: '自定义时长', duration: 1000 }) ``` ## 使用 Notify 组件 如果需要在 Notify 内嵌入组件或其他自定义内容，可以直接使用 Notify 组件，并使用默认插槽进行定制。 ```html 使用 Notify 组件调用 成功通知 ``` ```ts import { ref, onMounted } from 'vue' let timer: ReturnType export default { setup() { const visible = ref(false) const safeHeight = ref(0) const showNotify = () => { visible.value = true if (timer) clearTimeout(timer) timer = setTimeout(() => { visible.value = false }, 3000) } onMounted(() => { // #ifdef H5 safeHeight.value = 44 // #endif }) return { visible, showNotify, safeHeight } } } ``` ## 进阶`demo` ```vue // App.vue ``` ```vue // /components/layout/layout.vue ``` ```vue // /pages/user.vue ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------ | ----------------------------------------------------------------| ------- | ------------------------- | ------------ | -------- | | type | 类型 | NotifyType | `primary` `success` `warning` `danger` | `danger` | - | | message | 展示文案，支持通过`\n`换行 | string | - | - | - | | duration | 展示时长(ms)，值为 0 时，notify 不会消失 | number | - | `3000` | - | | zIndex | 层级 | number | - | `99` | - | | position | 弹出位置 | NotifyPosition | `top` `bottom` | `top` | - | | color | 字体颜色 | string | - | - | - | | background | 背景颜色 | string | - | - | - | | safeHeight | 顶部安全高度 | number / string | - | - | - | | selector | 指定唯一标识 | number | - | - | - | ## Events | 事件名 | 说明 | 参数 | 最低版本 | | -------- | ----------------------------------------- | ------- | -------- | | click | 点击时的回调函数 | (event: MouseEvent) => void | - | | closed | 关闭时的回调函数 | () => void | - | | opened | 展示后的回调函数 | () => void | - | ## Methods | 方法名称 | 说明 | 参数 | 最低版本 | | -------- | ----------------------------------------- | ------- | -------- | | showNotify | 展示提示 | `NotifyOptions` / `string` | - | | closeNotify | 关闭提示 | - | - | | setNotifyDefaultOptions | 修改默认配置，影响所有的 `showNotify` 调用 | `NotifyOptions` | - | | resetNotifyDefaultOptions | 重置默认配置，影响所有的 `showNotify` 调用 | - | - | ## Options 调用 `showNotify`、 `setNotifyDefaultOptions` 等方法时，支持传入以下选项： | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------ | ----------------------------------------------------------------| ------- | ------------------------- | ------------ | -------- | | type | 类型 | NotifyType | `primary` `success` `warning` `danger` | `danger` | - | | message | 展示文案，支持通过`\n`换行 | string | - | - | - | | duration | 展示时长(ms)，值为 0 时，notify 不会消失 | number | - | `3000` | - | | zIndex | 层级 | number | - | `99` | - | | position | 弹出位置 | NotifyPosition | `top` `bottom` | `top` | - | | color | 字体颜色 | string | - | - | - | | background | 背景颜色 | string | - | - | - | | safeHeight | 顶部安全高度 | number / string | - | - | - | | onClick | 点击时的回调函数 | (event: MouseEvent) => void | - | - | - | | onClosed | 关闭时的回调函数 | () => void | - | - | - | | onOpened | 展示后的回调函数 | () => void | - | - | - | --- --- url: 'https://wot-design-uni.cn/component/number-keyboard.md' --- # NumberKeyboard 数字键盘 虚拟数字键盘，用于输入数字、密码或身份证等场景。 ## 基本用法 可以通过 `v-model:visible` 控制键盘是否展示。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 带右侧栏的键盘 将 `mode` 属性设置为 `custom` 来展示键盘的右侧栏，常用于输入金额的场景。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 身份证键盘 通过 `extra-key` 属性可以设置左下角按键内容，比如需要输入身份证号时，可以将 `extra-key` 设置为 `X`。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 带标题的键盘 通过 `title` 属性可以设置键盘标题。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 使用 slot 自定义标题 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 多个额外按键 当 `mode` 为 `custom` 时，支持以数组的形式配置两个 `extra-key`。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 随机数字键盘 通过 `random-key-order` 属性可以随机排序数字键盘，常用于安全等级较高的场景。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 双向绑定 可以通过 `v-model` 绑定键盘当前输入值，并通过 `maxlength` 属性来限制输入长度。 ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) const value1 = ref('') function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## 展示蒙层遮罩 `hideOnClickOutside`控制键盘弹窗是否有遮罩，通过`modal`控制遮罩是否为透明。 ::: tip 提示 当前`modal`仅控制遮罩是否为透明，`hideOnClickOutside`控制弹窗是否有遮罩，当存在遮罩时，点击遮罩就可以关闭键盘，但是键盘展开时必须点击遮罩关闭当前键盘后才可以再点击别的按钮。也可以关闭`hideOnClickOutside`，手动控制键盘是否展示来实现点击外部时收起键盘，这样更灵活。 ::: ```html ``` ```ts const { show: showToast } = useToast() const visible = ref(false) const value1 = ref('') function showKeyBoard() { visible.value = true } const onInput = (value) => showToast(`${value}`) const onDelete = () => showToast('删除') ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------------- | ------------------------ | --------------------- | ------------------- | ---------- | -------- | | v-model:visible | 是否展开 | `boolean` | - | `false` | 0.1.65 | | v-model | 绑定的值 | `string` | - | - | 0.1.65 | | title | 标题 | `string` | - | - | 0.1.65 | | mode | 键盘模式 | `string` | `default`, `custom` | `default` | 0.1.65 | | zIndex | 层级 | `number` | - | `100` | 0.1.65 | | maxlength | 最大长度 | `number` | - | `Infinity` | 0.1.65 | | showDeleteKey | 是否显示删除键 | `boolean` | - | `true` | 0.1.65 | | randomKeyOrder | 是否随机键盘按键顺序 | `boolean` | - | `false` | 0.1.65 | | closeText | 确认按钮文本 | `string` | - | - | 0.1.65 | | deleteText | 删除按钮文本 | `string` | - | - | 0.1.65 | | closeButtonLoading | 关闭按钮是否显示加载状态 | `boolean` | - | `false` | 0.1.65 | | modal | 是否显示蒙层遮罩 | `boolean` | - | `false` | 0.1.65 | | hideOnClickOutside | 是否在点击外部时收起键盘 | `boolean` | - | `true` | 0.1.65 | | lockScroll | 是否锁定滚动 | `boolean` | - | `true` | 0.1.65 | | safeAreaInsetBottom | 是否在底部安全区域内 | `boolean` | - | `true` | 0.1.65 | | extraKey | 额外按键 | `string` / `string[]` | - | - | 0.1.65 | ## Slot | name | 说明 | 类型 | 最低版本 | | ----- | ---- | ---- | -------- | | title | 标题 | - | 1.2.12 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ------------------------------ | ----------- | -------- | | input | 点击按键时触发 | key: string | - | | delete | 点击删除键时触发 | - | - | | close | 点击关闭按钮或非键盘区域时触发 | - | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ------------ | -------- | | custom-class | 根节点样式类 | 0.1.65 | | custom-style | 根节点样式 | 0.1.65 | --- --- url: 'https://wot-design-uni.cn/component/overlay.md' --- # Overlay 遮罩层 0.1.30 创建一个遮罩层，用于强调特定的页面元素，并阻止用户进行其他操作。 ## 基础用法 使用 `show` 控制遮罩层的显示/隐藏。 ```html 显示遮罩层 ``` ## 嵌入内容 通过 `type` 修改指示器的类型，可选值为 'outline'，适用于通用模块加载。 ```html 嵌入内容 ``` ```scss .wrapper { display: flex; align-items: center; justify-content: center; height: 100%; } .block { width: 120px; height: 120px; background-color: #fff; } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ----------- | ------------------ | ----------------- | ------ | ------ | -------- | | show | 是否展示遮罩层 | `boolean` | true | false | - | | duration | 动画时长，单位毫秒 | `string / number` | - | 300 | - | | lockScroll | 是否锁定滚动 | `boolean` | false | true | - | | zIndex | 层级 | `number` | - | 10 | - | | customStyle | 自定义样式 | `string` | - | - | - | --- --- url: 'https://wot-design-uni.cn/component/pagination.md' --- # Pagination 分页 当数据量过多时，使用分页分解数据。 ## 基本用法 通过 `v-model` 来绑定当前页码，`total`设置总条数，`page-size`设置一页展示条数，默认为10条，总页数通过`total`和`page-size`自动计算。 ```html ``` ```typescript const value = ref(1) function handleChange({ value }) { console.log(value) } ``` ## Icon图标 设置 `show-icon` 属性，将分页导航展示为Icon图标。 ```html ``` ## 文字提示 设置 `show-message` 属性，展示文字提示。 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|--------| | v-model | 绑定值 | number | - | - | - | | prev-text | 上一页按钮文字 | string | - | 上一页 | - | | next-text | 下一页按钮文字 | string | - | 下一页 | - | | total-page | 总页数，如果有total，则优先使用total计算页数 | number | - | `根据页数计算` | - | | page-size | 分页大小 | number | - | 10 | - | | total | 总数据个数 | number | - | - | - | | show-icon | 是否展示分页Icon | boolean | - | false | - | | show-message | 是否展示文字提示 | boolean | - | false | - | | hide-if-one-page | 总页数只有一页时是否隐藏 | boolean | - | true | - | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | |---------|-----|------|--------| | change | 值修改事件 | `{ value }`,value为当前值 | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/password-input.md' --- # PasswordInput 密码输入框 0.2.0 带网格的输入框组件，可以用于输入密码、短信验证码等场景，通常与[数字键盘](./number-keyboard.md)组件配合使用。 ## 基础用法 搭配数字键盘组件来实现密码输入功能。 ```html ``` ```typescript import { ref } from 'vue' const value = ref('123') const showKeyboard = ref(true) ``` ### 自定义长度 通过`length`属性来设置密码长度。 ```html ``` ### 格子间距 通过`gutter`属性来设置格子之间的间距。 ```html ``` ### 明文展示 将`mask`设置为`false`可以明文展示输入的内容，适用于短信验证码等场景。 ```html ``` ### 提示信息 通过`info`属性设置提示信息，通过`error-info`属性设置错误提示，例如当输入六位时提示密码错误。 ```html ``` ```typescript import { ref, watch } from 'vue' const value = ref('123') const errorInfo = ref('') const showKeyboard = ref(true) watch(value, (newVal) => { if (newVal.length === 6 && newVal !== '123456') { errorInfo.value = '密码错误' } else { errorInfo.value = '' } }) ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ---------- | ------------------------------------------------ | ---------------- | ------ | ------ | -------- | | v-model | 密码值 | string | - | - | - | | info | 输入框下方文字提示 | string | - | - | - | | error-info | 输入框下方错误提示 | string | - | - | - | | length | 密码最大长度 | number | - | 6 | - | | gutter | 输入框格子之间的间距，如 20px 2em，默认单位为 px | number / string | - | 0 | - | | mask | 是否隐藏密码内容 | boolean | - | true | - | | focused | 是否已聚焦，聚焦时会显示光标 | boolean | - | false | - | ## Events | 事件名 | 说明 | 参数 | 最低版本 | | ------ | ---------------- | ----------- | -------- | | focus | 输入框聚焦时触发 | `event:Event` | - | --- --- url: 'https://wot-design-uni.cn/component/picker.md' --- # Picker 选择器 Picker 组件为 popup 和 pickerView 的组合。 ## 基本用法 `columns` 设置选项数据源，选项可以为字符串，也可以为对象，如果为对象则默认取 `label` 属性为选项内容进行渲染。`label` 设置左侧文本内容，`v-model` 设置选中项的值。label 可以不传。可以通过 `label-width` 设置标题宽度，默认为 '33%'，监听 `confirm` 事件，获取选中值，传出一个 event 对象，event `event = { value, selectedItems }`，value 为绑定值，selectedItems 为选中选项的对象。 ```html ``` ```typescript const columns = ref(['选项1', '选项2', '选项3', '选项4', '选项5', '选项6', '选项7']) const value = ref('选项1') function handleConfirm({ value }) { value.value = value } ``` 当 `columns` 选项为对象时，其数据结构为： | 参数 | 类型 | 说明 | 最低版本 | | -------- | ------------------------- | -------------------------------------------------------- | -------- | | value | string / number / boolean | 选项值，如果 value 属性不存在，则使用 label 作为选项的值 | - | | label | string | 选项文本内容 | - | | disabled | boolean | 选项是否禁用 | - | ## 禁用 设置 `disabled` 属性。 ```html ``` ```typescript const value = ref('选项3') const columns = ref(['选项1', '选项2', '选项3', '选项4', '选项5', '选项6', '选项7']) ``` ## 只读 设置 `readonly` 属性。 ```html ``` ## 清空按钮 设置 `clearable` 属性。 ```html ``` ## 文案标题 设置 `title` 属性。 ```html ``` ## 加载中 设置 `loading` 属性。 ```html ``` ## 多列 `columns` 属性设置为二维数组，`value` 为数组。 ```html ``` ```typescript const value = ref(['中南大学', '软件工程']) const columns = ref([ ['中山大学', '中南大学', '华南理工大学'], ['计算机科学与技术', '软件工程', '通信工程', '法学', '经济学'] ]) ``` ## 多级联动 传入 `column-change` 属性，其类型为 `function`，接收 pickerView 实例、选中项、当前修改列的下标、resolve 作为入参，根据选中项和列下标进行判断，通过 pickerView 实例暴露出来的 `setColumnData` 方法修改其他列的数据源，当修改完成后需要执行 `resolve()` 告知组件修改完成以继续执行，如果 `column-change` 包含异步操作，也可以使组件按照异步顺序进行执行。 > 每次修改完后都需要调用 resolve() 通知组件。 ```html ``` ```typescript const district = { '0': [{ label: '北京', value: '110000' }, { label: '广东省', value: '440000' }], '110000': [{ label: '北京', value: '110100' }], '440000': [{ label: '广州市', value: '440100' }, { label: '韶关市', value: '440200' }, { label: '深圳市', value: '440300' }, { label: '珠海市', value: '440400' }, { label: '汕头市', value: '440500' }], '110100': [{ label: '东城区', value: '110101' }, { label: '西城区', value: '110102' }, { label: '朝阳区', value: '110105' }, { label: '丰台区', value: '110106' }, { label: '石景山区', value: '110107' }], '440100': [{ label: '荔湾区', value: '440103' }, { label: '越秀区', value: '440104' }, { label: '海珠区', value: '440105'}], '440200': [{ label: '武江区', value: '440203'}], '440300': [{ label: '罗湖区', value: '440303' }, { label: '福田区', value: '440304' }], '440400': [{ label: '香洲区', value: '440402' }, { label: '斗门区', value: '440403' }, { label: '金湾区', value: '440404' }], '440500': [{ label: '龙湖区', value: '440507' }, { label: '金平区', value: '440511' }] } const value = ref(['110000', '110100', '110102']) const columns = ref([district[0], district[district[0][0].value], district[district[district[0][0].value][0].value]]) const onChangeDistrict = (pickerView, value, columnIndex, resolve) => { const item = value[columnIndex] if (columnIndex === 0) { pickerView.setColumnData(1, district[item.value]) pickerView.setColumnData(2, district[district[item.value][0].value]) } else if (columnIndex === 1) { pickerView.setColumnData(2, district[item.value]) } resolve() } const displayFormat = (items) => { return items .map((item) => { return item.label }) .join('-') } ``` ## 选择器大小 通过设置 `size` 修改选择器大小，将 `size` 设置为 'large' 时字号为 16px。 ```html ``` ## 必填属性 设置 `required` 属性，展示必填样式。 ```html ``` ## 错误状态 设置 `error` 属性，选择器的值显示为红色。 ```html ``` ## 值靠右展示 设置 `align-right` 属性，选择器的值靠右展示。 ```html ``` ## 确定前校验 设置 `before-confirm` 函数，在用户点击`确定`按钮时，会执行 `before-confirm` 函数，并传入 `value` 、 `resolve` 和 `picker` 参数，可以对 `value` 进行校验，并通过 `resolve` 函数告知组件是否确定通过，`resolve` 接受1个 boolean 值，`resolve(true)` 表示选项通过，`resolve(false)` 表示选项不通过，不通过时不会关闭 `picker`弹窗。可以通过 `picker` 参数直接设置 `loading`、`columns` 等属性。 ```html ``` ```typescript import { useToast } from '@/uni_modules/wot-design-uni' const toast = useToast() const beforeConfirm = (value, resolve, picker) => { picker.setLoading(true) setTimeout(() => { picker.setLoading(false) if (['选项2', '选项3'].indexOf(value) > -1) { resolve(false) toast.error('选项校验不通过，请重新选择') } else { resolve(true) } }, 2000) } const columns = ref(['选项1', '选项2', '选项3', '选项4', '选项5', '选项6', '选项7']) const value = ref('') const beforeConfirm = (value, resolve, picker) => { picker.setLoading(true) setTimeout(() => { picker.setLoading(false) if (['选项2', '选项3'].indexOf(value) > -1) { resolve(false) toast.error('选项校验不通过，请重新选择') } else { resolve(true) } }, 2000) } function handleConfirm({ value }) { value.value = value } ``` ## 唤起项插槽 开启 `use-default-slot` ，设置默认插槽修改唤起picker组件的形式。 ```html 插槽唤起 ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------ | ------- | ---------------- | | v-model | 选中项，如果为多列选择器，则其类型应为数组 | string / number / boolean / array | - | - | - | | columns | 选择器数据，可以为字符串数组，也可以为对象数组，如果为二维数组，则为多列选择器 | array | - | - | - | | loading | 加载中 | boolean | - | false | - | | loading-color | 加载的颜色，只能使用十六进制的色值写法，且不能使用缩写 | string | - | #4D80F0 | - | | columns-height | picker内部滚筒高 | number | - | 231 | - | | value-key | 选项对象中，value对应的 key | string | - | value | - | | label-key | 选项对象中，展示的文本对应的 key | string | - | label | - | | title | 弹出层标题 | string | - | - | - | | cancel-button-text | 取消按钮文案 | string | - | 取消 | - | | confirm-button-text | 确认按钮文案 | string | - | 完成 | - | | label | 选择器左侧文案 | string | - | - | - | | placeholder | 选择器占位符 | string | - | 请选择 | - | | disabled | 禁用 | boolean | - | false | - | | readonly | 只读 | boolean | - | false | - | | display-format | 自定义展示文案的格式化函数，返回一个字符串 | function | - | - | - | | column-change | 接收 pickerView 实例、选中项、当前修改列的下标、resolve 作为入参，根据选中项和列下标进行判断，通过 pickerView 实例暴露出来的 `setColumnData` 方法修改其他列的数据源。 | function | - | - | - | | size | 设置选择器大小 | string | large | - | - | | label-width | 设置左侧标题宽度 | string | - | 33% | - | | error | 是否为错误状态，错误状态时右侧内容为红色 | boolean | - | false | - | | required | 表单属性，必填 | boolean | - | false | - | | align-right | 选择器的值靠右展示 | boolean | - | false | - | | use-label-slot | label 使用插槽 | boolean | - | false | - | | use-default-slot | 使用默认插槽 | boolean | - | false | - | | before-confirm | 确定前校验函数，接收 (value, resolve, picker) 参数，通过 resolve 继续执行 picker，resolve 接收1个boolean参数 | function | - | - | - | | close-on-click-modal | 点击遮罩是否关闭 | boolean | - | true | - | | z-index | 弹窗层级 | number | - | 15 | - | | safe-area-inset-bottom | 弹出面板是否设置底部安全距离（iphone X 类型的机型） | boolean | - | true | - | | ellipsis | 是否超出隐藏 | boolean | - | false | - | | prop | 表单域 `model` 字段名，在使用表单校验功能的情况下，该属性是必填的 | string | - | - | - | | rules | 表单验证规则，结合`wd-form`组件使用 | `FormItemRule []` | - | `[]` | - | | immediate-change | 是否在手指松开时立即触发picker-view的 change 事件。若不开启则会在滚动动画结束后触发 change 事件，1.2.25版本起提供，仅微信小程序和支付宝小程序支持。 | boolean | - | false | 1.2.25 | | clearable | 显示清空按钮 | boolean | - | false | 1.3.13 | ### FormItemRule 数据结构 | 键名 | 说明 | 类型 | | --------- | ------------------------------------------------------- | ------------------------------------- | | required | 是否为必选字段 | `boolean` | | message | 错误提示文案 | `string` | | validator | 通过函数进行校验，可以返回一个 `Promise` 来进行异步校验 | `(value, rule) => boolean \| Promise` | | pattern | 通过正则表达式进行校验，正则无法匹配表示校验不通过 | `RegExp` | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ---------------------- | ----------------------------------------------------------------------------------------------------------- | -------- | | confirm | 点击右侧按钮触发 | { value, selectedItems }， value 为选中值(多列则为数组)，selectedItems为选中项(多列则为数组) | - | | cancel | 点击左侧按钮触发 | - | - | | open | 打开选择器弹出层时触发 | - | - | | clear | 点击清空按钮时触发 | - | 1.3.13 | ## Methods | 方法名称 | 说明 | 参数 | 最低版本 | | -------- | -------------- | ---- | -------- | | open | 打开picker弹框 | - | - | | close | 关闭picker弹框 | - | - | ## Slot | name | 说明 | 最低版本 | | ------- | ------------ | -------- | | default | 使用默认插槽 | - | | label | 左侧标题插槽 | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------------ | ------------------------- | -------- | | custom-class | 根节点样式 | - | | custom-view-class | pickerView 外部自定义样式 | - | | custom-label-class | label 外部自定义样式 | - | | custom-value-class | value 外部自定义样式 | - | --- --- url: 'https://wot-design-uni.cn/component/picker-view.md' --- # PickerView 选择器视图 选择器视图，用于从一组数据中选择单个或多个值。 ## 基本用法 单列选择器，给 `columns` 传入一个数值数组，设置 `v-model` 绑定值。选项可以为字符串，也可以为对象，如果为对象则默认取选项 `label` 属性为选项内容进行渲染，`v-model` 获取的值为选项 `value` 属性的值，如果选项 `value` 属性不存在，则取选项 `label` 的值。 ```html ``` ```typescript import { useToast } from '@/uni_modules/wot-design-uni' const toast = useToast() const columns = ref(['选项1', '选项2', '选项3', '选项4', '选项5', '选项6', '选项7']) const value3 = ref('') function onChange({picker, value, index}) { toast.show(`当前选中项: ${value}, 下标: ${index}`) } ``` 当 `columns` 选项为对象时，其数据结构为： | 参数 | 类型 | 说明 | 最低版本 | |-----|-----|------|---------| | value | string / number / boolean | 选项值，如果 value 属性不存在，则使用 label 作为选项的值 | - | | label | string | 选项文本内容 | - | | disabled | boolean | 选项是否禁用 | - | ## 禁用选项 选项可以为对象，设置 `disabled` 属性。 ```html ``` ```typescript const columns = ref(['选项1', '选项2', '选项3', '选项4', '选项5', '选项6', '选项7']) const value = ref('选项3') ``` ## 加载中 设置 `loading` 属性。 ```html ``` ## 多列 `columns` 属性设置为二维数组，`value` 为数组。 ```html ``` ```typescript const value = ref(['中南大学', '软件工程']) const columns = ref([ ['中山大学', '中南大学', '华南理工大学'], ['计算机科学与技术', '软件工程', '通信工程', '法学', '经济学'] ]) ``` ## 多级联动 传入 `column-change` 属性，其类型为 `function`，接收 pickerView 实例、选中项、当前修改列的下标、resolve 作为入参，根据选中项和列下标进行判断，通过 pickerView 实例暴露出来的 `setColumnData` 方法修改其他列的数据源，当修改完成后需要执行 `resolve()` 告知组件修改完成以继续执行，如果 `column-change` 包含异步操作，也可以使组件按照异步顺序进行执行。 ```html ``` ```typescript const district = { '0': [{ label: '北京', value: '110000' }, { label: '广东省', value: '440000' }], '110000': [{ label: '北京', value: '110100' }], '440000': [{ label: '广州市', value: '440100' }, { label: '韶关市', value: '440200' }, { label: '深圳市', value: '440300' }, { label: '珠海市', value: '440400' }, { label: '汕头市', value: '440500' }], '110100': [{ label: '东城区', value: '110101' }, { label: '西城区', value: '110102' }, { label: '朝阳区', value: '110105' }, { label: '丰台区', value: '110106' }, { label: '石景山区', value: '110107' }], '440100': [{ label: '荔湾区', value: '440103' }, { label: '越秀区', value: '440104' }, { label: '海珠区', value: '440105'}], '440200': [{ label: '武江区', value: '440203'}], '440300': [{ label: '罗湖区', value: '440303' }, { label: '福田区', value: '440304' }], '440400': [{ label: '香洲区', value: '440402' }, { label: '斗门区', value: '440403' }, { label: '金湾区', value: '440404' }], '440500': [{ label: '龙湖区', value: '440507' }, { label: '金平区', value: '440511' }] } const value = ref(['110000', '110100', '110102']) const columns = ref([district[0], district[district[0][0].value], district[district[district[0][0].value][0].value]]) const onChangeDistrict = (pickerView, value, columnIndex, resolve) => { const item = value[columnIndex] if (columnIndex === 0) { pickerView.setColumnData(1, district[item.value]) pickerView.setColumnData(2, district[district[item.value][0].value]) } else if (columnIndex === 1) { pickerView.setColumnData(2, district[item.value]) } resolve() } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|---------| | v-model | 选中项，如果为多列选择器，则其类型应为数组 | string / number / boolean / array | - | - | - | | columns | 选择器数据，可以为字符串数组，也可以为对象数组，如果为二维数组，则为多列选择器 | array | - | - | - | | loading | 加载中 | boolean | - | false | - | | loading-color | 加载的颜色，只能使用十六进制的色值写法，且不能使用缩写 | string | - | #4D80F0 | - | | columns-height | picker内部滚筒高 | number | - | 231 | - | | value-key | 选项对象中，value对应的 key | string | - | value | - | | label-key | 选项对象中，展示的文本对应的 key | string | - | label | - | | column-change | 接收 pickerView 实例、选中项、当前修改列的下标、resolve 作为入参，根据选中项和列下标进行判断，通过 pickerView 实例暴露出来的 `setColumnData` 方法修改其他列的数据源。 | function | - | - | - | | immediate-change | 是否在手指松开时立即触发picker-view的 change 事件。若不开启则会在滚动动画结束后触发 change 事件，1.2.25版本起提供，仅微信小程序和支付宝小程序支持。 | boolean | - | false | 1.2.25 | ## Methods | 方法名称 | 说明 | 参数 | 最低版本 | |---------|-----|-----|---------| | getLabels | 获取所有列选中项的文本，返回值为一个数组 | - | | getColumnIndex | 获取某一列的选中项下标 | columnIndex | - | | getColumnData | 获取某一列的选项 | columnIndex | - | | setColumnData | 设置某一列的选项 | columnIndex, values | - | | resetColumns | 重置列数据为指定列数据 | columns（类型与props中columns相同） | 1.3.9 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | |--------|------|------|--------| | change | 选项值修改时触发 | event = { value, picker, index }, 单列: picker实例, 选中项值, 选中项下标; 多列: picker实例, 所有列选中项值, 当前列的下标 | - | | pickstart | 当滚动选择开始时候触发事件 | - | - | | pickend | 当滚动选择结束时候触发事件 | - | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/popover.md' --- # Popover 气泡 常用于展示提示信息。 ## 基本用法 Popover 的属性与 [Tooltip](/component/tooltip.html) 很类似，因此对于重复属性，请参考 [Tooltip](/component/tooltip.html) 的文档，在此文档中不做详尽解释。 因为`uni-app`组件无法监听点击自己以外的地方，为了在点击页面其他地方时，可以自动关闭 `popover` ，建议使用组件库的 `useQueue` hook（会关闭所有 dropmenu、popover、toast、swipeAction、fab），在页面的根元素上监听点击事件的冒泡。 :::warning 如果存在用户手动点击 `popover` 以外某个地方如按钮弹出 `popover` 的场景，则需要在点击的元素（在这里上按钮）加上 click 阻止事件冒泡到根元素上，避免触发 `closeOutside` 把要手动打开的 `popover` 关闭了。 ::: ```html 点击展示 ``` ```typescript import { useQueue } from '@/uni_modules/wot-design-uni' const { closeOutside } = useQueue() function handleChange({ show }) { console.log(show) } ``` ## 模式 mode 使用 `mode` 属性控制当前文字提示的展示模式。`mode` 可选参数为 `normal` / `menu`： * **normal**（普通文字模式）: * 当 `mode` 处于默认状态，`content` 属性传入要显示的 `String` 字符串。 * **menu**（列表模式）: * 文字提示框会展示成列表形式，此时 `content` 属性传入 `Array` 类型，数组内对象数据结构如下方列表所示。 * 绑定事件 `menuclick`，在选择结束后，执行操作，列表关闭。 列表模式下 `content` 数组内对象的数据结构： | 键名 | 说明 | 类型 | 是否必填 | 最低版本 | | ------------------------------------- | ------ | ------ | -------- | -------- | | content | 选项名 | string | 是 | - | | iconClass（不设置该属性时只展示标题） | 选项值 | string | 否 | - | **注意：iconClass 属性值为组件库内部的 icon 图标名。** ```html 列表 ``` ```typescript import { useToast } from '@/uni_modules/wot-design-uni' const toast = useToast() const menu = ref>>([ { iconClass: 'read', content: '全部标记已读' }, { iconClass: 'delete', content: '清空最近会话' }, { iconClass: 'detection', content: '消息订阅设置' }, { iconClass: 'subscribe', content: '消息异常检测' } ]) function link(e) { toast.show('选择了' + e.item.content) } ``` ## 嵌套信息 开启属性 `use-content-slot`，使用插槽 `content`， 可以在 Popover 中嵌套多种类型信息。 :::warning 注意 目前使用`content`插槽时，组件内部无法正确获取气泡的宽高，此时设置偏移的`placement`无法生效，例如`bottom-end`。 ::: ```html 点击展示 ``` ```scss .pop-content { /* 必填 开始 */ position: relative; z-index: 500; border-radius: 4px; /* 必填 结束 */ background: #fff; color: #8268de; font-weight: bolder; padding: 10px; width: 150px; } ``` ## Popover Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------- | ------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | | v-model | 手动状态是否可见 | boolean | - | false | - | | content | 显示的内容，也可以通过 `slot#content` 传入 | string/array（当模式为菜单模式时，content 属性格式为 Array） | - | - | - | | mode | 当前显示的模式，决定内容的展现形式 | string | normal（普通模式）/ menu（菜单模式） | normal | - | | placement | popover 的出现位置 | string | top / top-start / top-end / bottom / bottom-start / bottom-end / left / left-start / left-end / right / right-start / right-end | bottom | - | | visible-arrow | 是否显示 popover 箭头 | boolean | - | true | - | | disabled | popover 是否可用 | boolean | - | false | - | | offset | 出现位置的偏移量 | number | - | 0 | - | ## Slot | name | 说明 | 最低版本 | | ------- | ------------------------ | -------- | | content | 多行内容或用户自定义样式 | - | ## Events | 事件名称 | 说明 | 回调参数 | 最低版本 | | -------------- | --------------------------- | ----------------- | -------- | | open | 显示时触发 | - | - | | close | 隐藏时触发 | - | - | | change | pop 显隐值变化时触发 | - | - | | menuclick | menu 模式下点击某一选项触发 | `{ item, index }` | - | ## Methods | 方法名称 | 说明 | 参数 | 最低版本 | | -------- | ---------------- | ---- | -------- | | open | 打开文字提示弹框 | - | - | | close | 关闭文字提示弹框 | - | - | ## Popover 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ------------ | -------- | | custom-class | 根节点样式 | - | | custom-arrow | 尖角样式 | - | | custom-pop | 文字提示样式 | - | --- --- url: 'https://wot-design-uni.cn/component/popup.md' --- # Popup 弹出层 弹出层组件，用于展示弹窗、信息提示等内容。 ## 基本用法 `v-model` 为绑定值，表示是否展示弹出层。 ```html 弹弹弹 ``` ```css .custom-txt { color: black; width: 400rpx; height: 400rpx; display: flex; justify-content: center; align-items: center; font-size: 40rpx; border-radius: 32rpx; } ``` ## 弹出位置 设置 `position`，默认为 'center'，可选值 'top', 'right', 'bottom', 'left'。 ```html ``` ## 关闭按钮 设置 `closable` 属性。 ```html ``` ## 禁用遮罩点击 通过设置 `close-on-click-modal` 属性为 `false`，你可以禁用用户点击遮罩层时关闭弹出层的功能。 ```html ``` ## 禁用遮罩 通过设置 `modal` 属性为 `false`，你可以禁用遮罩层，使用户可以与底层内容进行交互。 ```html ``` ## 开启底部安全区 通过设置 `safe-area-inset-bottom` 属性为 `true`，你可以确保弹出层在底部显示时不会被底部安全区域遮挡。 ```html ``` ## 禁止滚动穿透 使用组件时，会发现内容部分滚动到底时，继续划动会导致底层页面的滚动，这就是滚动穿透。 目前，组件可以通过 `lock-scroll` 属性处理部分滚动穿透问题。 但由于小程序和APP平台自身原因，弹窗内容区域仍会出现滚动穿透。 不过，我们为开发者提供了一个推荐方案以完整解决滚动穿透： 可以使用 [page-meta](https://uniapp.dcloud.net.cn/component/page-meta#page-meta) 组件动态修改 `page-meta` 的 `overflow` 属性。 ```html ``` :::tip 提示 h5 滚动穿透不需要处理，组件已默认开启 `lock-scroll`。 ::: ### H5平台 ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|-----|------|-------|-------|---------| | v-model | 弹出层是否显示 | boolean | - | - | - | | position | 弹出位置 | string | center / top / right / bottom / left | center | - | | closable | 关闭按钮 | boolean | - | false | - | | close-on-click-modal | 点击遮罩是否关闭 | boolean | - | true | - | | duration | 动画持续时间 | number / boolean | - | 300(ms) | - | | z-index | 设置层级 | number | - | 10 | - | | custom-style | 自定义弹出层样式 | string | - | - | - | | modal | 是否显示遮罩 | boolean | - | true | - | | modal-style | 自定义modal蒙层样式 | string | - | - | - | | hide-when-close | 是否当关闭时将弹出层隐藏（display: none) | boolean | - | true | - | | lazy-render | 弹层内容懒渲染，触发展示时才渲染内容 | boolean | - | true | - | | safe-area-inset-bottom | 弹出面板是否设置底部安全距离（iphone X 类型的机型） | boolean | - | false | - | | transition | 动画类型，参见 wd-transition 组件的name | string | fade / fade-up / fade-down / fade-left / fade-right / slide-up / slide-down / slide-left / slide-right / zoom-in | - | - | | lockScroll | 是否锁定背景滚动 | boolean | - | true | 0.1.30 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | |---------|-----|-----|---------| | close | 弹出层关闭时触发 | - | - | | click-modal | 点击遮罩时触发 | - | - | | before-enter | 进入前触发 | - | - | | enter | 进入时触发 | - | - | | after-enter | 进入后触发 | - | - | | before-leave | 离开前触发 | - | - | | leave | 离开时触发 | - | - | | after-leave | 离开后触发| - | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/progress.md' --- # Progress 进度条 用于展示操作的当前进度。 ## 基本用法 设置百分比 `percentage`。 ```html ``` ## 隐藏进度文字 设置 `hide-text` 隐藏进度文字。 ```html ``` ## 设置状态 设置 `status`，告知用户当前状态和预期。 ```html ``` ## 修改颜色 设置 `color` 修改进度条颜色。 ```html ``` `color` 也可以设置为数组或者函数。数组如果只传入颜色，则自动计算每个颜色的进度边界。函数需要返回一个颜色值。 ```html ``` 数组也可以设置为以下格式： ```html ``` ```typescript import type { ProgressColor } from '@/uni_modules/wot-design-uni/components/wd-progress/types' const colorObject = ref([ { color: 'yellow', percentage: 30 }, { color: 'red', percentage: 60 }, { color: 'blue', percentage: 80 }, { color: 'black', percentage: 90 } ]) const percentage = ref(100) ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ---------- | --------------------- | --------------------------------------- | ---------------- | ------ | -------- | | percentage | 进度数值，最大值 100 | `number` | - | 0 | - | | hide-text | 隐藏进度文字 | `boolean` | - | false | - | | color | 进度条颜色 | `string / ProgressColor[] / string[]` | - | - | - | | status | 进度条状态 | `string` | success / danger / warning | - | - | | duration | 进度增加 1%所需毫秒数 | `number` | - | 30 | - | ### ProgressColor | 字段 | 说明 | 说明 | 最低版本 | | ---------- | ------ | ------ | -------- | | color | string | 颜色 | - | | percentage | number | 百分比 | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/radio.md' --- # Radio 单选框 单选框，用于在一组备选项中进行单选。 ## 基本用法 `v-model` 为绑定值，即选中的 `wd-radio` 的 `value` 值。 ```html 单选框1 单选框2 当前选中的值为:{{value}} ``` ```typescript const value = ref(1) ``` ## 修改图标形状 修改 `shape` 属性，可选值为 'dot'、'button'、'check'，默认为 'check'。 ```html 沃特 商家后台 ``` ```typescript const value = ref(1) function change(e) { console.log(e) } ``` ```html 沃特 商家后台 ``` ```typescript const value = ref(1) function change(e) { console.log(e) } ``` ## 表单模式 设置 `cell` 属性，开启表单模式单选框组。 开启表单模式时，如果同时设置 `shape` 为 `button` 开启表单模式单选按钮组模式。 ```html 选项一 选项二 选项三 选项四 选项五 选项六 选项七 ``` ```ts const value = ref(1) ``` ## 同行展示 设置 `inline` 属性，使单选框在同一行展示。 ```html 单选框1 单选框2 ``` ```ts const value = ref(1) ``` ## 修改选中的颜色 设置 `checked-color` 属性。 ```html 沃特 商家后台 ``` ```ts const value = ref(1) ``` ## 禁用 可以在 `radio-group` 上面设置 `disabled`，禁用所有单选框，也可以在单个单选框上面设置 `disabled` 属性，禁用某个单选框。 ```html 沃特 商家后台 ``` ```ts const value = ref(1) ``` ## 尺寸 设置 `size` 属性，可选 `large`。 ```html 沃特 商家后台 ``` ## Props优先级 radio设置的props优先级比radioGroup上设置的props优先级更高 ```html 商家后台 沃特 商家智能 ``` ## RadioGroup Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | -------------- | --------------------------- | ------------------------- | -------------------- | ------- | ---------------- | | v-model | 会自动选中value对应的单选框 | string / number / boolean | - | - | - | | shape | 单选框形状 | string | dot / button / check | check | - | | size | 设置大小 | string | large | - | - | | checked-color | 选中的颜色 | string | - | #4D80F0 | - | | disabled | 禁用 | boolean | - | false | - | | max-width | 文字位置最大宽度 | string | - | - | - | | inline | 同行展示 | boolean | - | false | - | | cell | 表单模式 | boolean | - | false | - | | icon-placement | 勾选图标对齐方式 | string | left / right/ auto | auto | 1.5.0 | ## RadioGroup Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ---------------- | ----------- | -------- | | change | 绑定值变化时触发 | `{ value }` | - | ## Radio Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------- | --------------------------------------------- | ------------------------- | -------------------- | ------- | -------- | | value | 单选框选中时的值。会自动匹配radioGroup的value | string / number / boolean | - | - | - | | shape | 单选框形状 | string | dot / button / check | check | - | | checked-color | 选中的颜色 | string | - | #4D80F0 | - | | disabled | 禁用 | boolean | - | false | - | --- --- url: 'https://wot-design-uni.cn/component/rate.md' --- # Rate 评分 用于快速的评价操作，或对评价进行展示。 ## 基本用法 设置`v-model`分数，设置`num`总分数，默认为5分。 ```html ``` ```typescript const value = ref(1) function changeValue({ value }) { console.log(value) } ``` ## 只读 设置 `readonly` 属性。 ```html ``` ## 禁用 设置 `disabled` 属性和`disabled-color` ```html ``` ## 修改颜色 可以通过 `color` 属性修改未选中的颜色，`active-color` 修改选中的颜色。 ```html ``` ## 修改icon 可以通过 `icon` 属性修改未选中的图标，`active-icon` 修改选中的图标。 ```html ``` ## 修改大小、间隔 可以通过 `size` 属性修改图标的大小，`space` 修改图标之间的间隔。 ```html ``` ## 允许半选 设置 `allowHalf` 属性。 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|-----|------|-------|-------|--------| | v-model | 当前分数 | number | - | - | - | | num | 评分最大值 | number | - | 5 | - | | readonly | 是否只读 | boolean | - | false | - | | size | 图标大小 | string | - | 16px | - | | space | 图标间距 | string | - | 4px | - | | color | 未选中的图标颜色 | string | - | #E8E8E8 | - | | active-color | 选中的图标颜色(支持传颜色数组，共有 2 个元素，为 2 个分段所对应的颜色) | string/array | - | linear-gradient(180deg, rgba(255,238,0,1) 0%,rgba(250,176,21,1) 100%) | - | | icon | 未选中的图标类名 | string | - | wd-icon-star-on | - | | active-icon | 选中的图标类名 | string | - | wd-icon-star-on | - | | disabled | 是否禁用 | boolean | - | false | - | | disabled-color | 禁用的图标颜色 | string | - | linear-gradient(315deg, rgba(177,177,177,1) 0%,rgba(199,199,199,1) 100%) | - | | allow-half | 是否允许半选 | boolean | - | false | 1.7.0 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | |---------|-----|-----|---------| | change | 点击icon，修改分值事件 | `{ value }` | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/resize.md' --- # Resize 监听元素尺寸变化 当组件包裹的文档流尺寸发生变化时，触发 `size` 事件。一般用于监听 dom 内容更新时导致的 dom 尺寸位置的变化，重新获取 dom 尺寸和位置，进行内容展示的计算操作。 ## 基本用法 > 不要给此组件增加任何外部样式 ```html ``` ```typescript const width = ref('') const height = ref('') onReady(() => { setTimeout(() => { width.value = '100px' height.value = '100px' }, 1500) }) function handleResize(detail: Record) { const { height, width, top, right, bottom, left } = detail console.log(height, width, top, right, bottom, left) } ``` ## Events | 事件名称 | 说明 | 参数 | 最低版本 | |--------|------|-----|---------| | resize | 尺寸发生变化时触发 | `{width: number, height: number, top: number, right: number, bottom: number, left: number}` | - | --- --- url: 'https://wot-design-uni.cn/component/search.md' --- # Search 搜索框 搜索框组件，支持输入框聚焦、失焦、输入、搜索、取消、清空事件。 ## 基本用法 `v-model`设置输入框绑定值、`focus`绑定聚焦事件、`change` 绑定输入事件，`blur`绑定失焦事件，`search` 绑定搜索事件，`cancel` 绑定取消事件，`clear` 绑定清空事件。 ```html ``` ```typescript const value = ref('') function focus() { console.log('聚焦') } function blur() { console.log('失焦') } function search() { console.log('搜索') } function clear() { console.log('重置') } function cancel() { console.log('取消') } function change({ value }) { console.log('输入', value) } ``` ## 浅色主题 设置 `light` 属性，将组件背景色和输入框背景色反转。 ```html ``` ## 输入框提示文案靠左 设置 `placeholder-left` 属性。 ```html ``` ## 隐藏取消按钮 设置 `hide-cancel` 属性。 ```html ``` ## 禁用 设置 `disabled` 属性。 ```html ``` 可以和 `hide-cancel` 结合使用，用于在本页只展示搜索框，当点击搜索框时，将页面路由切换进搜索页，在搜索页中再使用搜索功能。 ```html ``` ## 自定义左侧插槽 通过使用 `prefix` 插槽自定义搜索框左侧内容。 ```html ``` ```typescript const searchType = ref('全部') const value = ref('') const menu = ref([ { content: '全部' }, { content: '订单号' }, { content: '退款单号' } ]) function changeSearchType({ item, index }) { searchType.value = item.content } ``` ```scss .search-type { position: relative; height: 30px; line-height: 30px; padding: 0 8px 0 16px; } .search-type::after { position: absolute; content: ''; width: 1px; right: 0; top: 5px; bottom: 5px; background: rgba(0, 0, 0, 0.25); } .search-type { :deep(.icon-arrow) { display: inline-block; font-size: 20px; vertical-align: middle; } } ``` ## 自定义文案 通过设置 `placeholder` 修改输入框提示文案，`cancel-txt` 修改取消按钮文案。 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------------- | ----------------------------------------------------------------------------------------- | --------------- | ------ | ------ | -------- | | placeholder | 搜索框占位文本 | string | - | 搜索 | - | | placeholder-left | placeholder 居左边 | boolean | - | false | - | | cancel-txt | 搜索框右侧文本 | string | - | 取消 | - | | light | 搜索框亮色（白色） | boolean | - | false | - | | hide-cancel | 是否隐藏右侧文本 | boolean | - | false | - | | disabled | 是否禁用搜索框 | boolean | - | false | - | | maxlength | 原生属性，设置最大长度。-1 表示无限制 | string / number | - | -1 | - | | v-model | 输入框内容，双向绑定 | string | - | - | - | | ~~use-suffix-slot~~ | ~~是否使用输入框右侧插槽~~**（已废弃，将在下一个 minor 版本被移除，直接使用插槽即可）** | boolean | - | false | - | | focus | 是否自动聚焦 | boolean | - | false | 0.1.63 | | focusWhenClear | 是否在点击清除按钮时聚焦输入框 | boolean | - | false | 0.1.63 | | placeholderStyle | 原生属性，指定 placeholder 的样式，目前仅支持color,font-size和font-weight | string | - | - | 1.6.0 | | placeholderClass | 原生属性，指定 placeholder 的样式类 | string | - | - | 1.6.0 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | -------------------------- | ----------- | -------- | | focus | 输入框聚焦事件 | `{ value }` | - | | blur | 监听输入框失焦事件 | `{ value }` | - | | search | 监听输入框搜索事件 | `{ value }` | - | | clear | 监听输入框清空按钮事件 | - | - | | cancel | 监听输入框右侧文本点击事件 | `{ value }` | - | | change | 监听输入框内容变化事件 | `{ value }` | - | ## Slots | name | 说明 | 最低版本 | | ------ | -------------------- | -------- | | prefix | 输入框左侧自定义内容 | - | | suffix | 输入框右侧自定义内容 | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | | custom-input-class | input 外部自定义样式 | 1.6.0 | --- --- url: 'https://wot-design-uni.cn/component/segmented.md' --- # Segmented 分段器 0.1.23 分段器用于展示多个选项并允许用户选择其中单个选项。 ## 何时使用 * 用于展示多个选项并允许用户选择其中单个选项； * 当切换选中选项时，关联区域的内容会发生变化。 ## 基本用法 通过 `options` 属性设置选项列表，通过 `v-model:value` 绑定当前选中项。 ```vue ``` ```ts const list = ref(['评论', '点赞', '贡献', '打赏']) const current = ref('点赞') ``` ## 大型分段器 通过设置 `size` 属性为 `"large"`，创建一个大型分段器。 ```html ``` ## 小型分段器 通过设置 `size` 属性为 `"small"`，创建一个小型分段器。 ```html ``` ## 带振动效果的分段器 通过设置 `vibrate-short` 属性为 `true`，使手机在切换选项时产生短暂振动。 ```html ``` ## 禁用分段器 通过设置 `disabled` 属性为 `true`，禁用分段器。 ```html ``` ## 自定义渲染分段器标签 使用插槽 `label` 可以自定义渲染分段器的标签内容。 ```html ``` ```ts const list = ref([ { value: '李雷', disabled: false, payload: { avatar: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/redpanda.jpg' } }, { value: '韩梅梅', disabled: false, payload: { avatar: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/capybara.jpg' } } ]) ``` ```scss .section { width: 100%; padding: 0 24rpx; box-sizing: border-box; &-slot { padding: 4px; } } ``` ## 在弹出框中使用 微信小程序端，在弹出框中使用本组件时，需要调用 `updateActiveStyle` 方法更新分段器样式，参见[常见问题](/guide/common-problems.html#%E4%B8%BA%E4%BB%80%E4%B9%88%E5%9C%A8%E5%BE%AE%E4%BF%A1%E5%B0%8F%E7%A8%8B%E5%BA%8F%E4%B8%8A%E4%BD%BF%E7%94%A8popup%E3%80%81actionsheet%E3%80%81dropdownitem%E7%AD%89%E5%BC%B9%E5%87%BA%E6%A1%86%E7%BB%84%E4%BB%B6%E5%8C%85%E8%A3%B9slider%E3%80%81tabs%E7%AD%89%E7%BB%84%E4%BB%B6%E6%97%B6-slider%E3%80%81tabs%E8%A1%A8%E7%8E%B0%E5%BC%82%E5%B8%B8)。 ```html 打开弹窗 在弹出框中使用 ``` ```ts const list = ref(['评论', '点赞', '贡献', '打赏']) const current = ref('点赞') const segmentedRef = ref() // 获取分段器实例 const showPopup = ref(false) // 控制popup显示 /** * 点击按钮打开popup */ function handleClick() { showPopup.value = true } /** * popup打开后更新分段器样式 */ function handlePopupShow() { segmentedRef.value?.updateActiveStyle() } ``` ```css .title { display: flex; font-size: 32rpx; align-items: center; justify-content: center; padding: 24rpx 0; } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------------- | ------------------ | ------------------------------------------- | ------------------------------ | -------- | -------- | | value/v-model:value | 当前选中的值 | string / number | - | - | 0.1.23 | | disabled | 是否禁用分段器 | boolean | true / false | `false` | 0.1.23 | | size | 控件尺寸 | string | `large` / `middle` / `small` | `middle` | 0.1.23 | | options | 数据集合 | `string[] / number[] / SegmentedOption[]` | - | \[] | 0.1.23 | | vibrateShort | 切换选项时是否振动 | boolean | true / false | `false` | 0.1.23 | ### SegmentedOption | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | -------- | -------- | ---------------- | ------------- | ------ | -------- | | value | 选中值 | string / number | - | - | 0.1.23 | | disabled | 是否禁用 | boolean | true / false | - | 0.1.23 | | payload | 更多数据 | any | - | - | 0.1.23 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | -------------- | ----------------- | -------- | | change | 选项切换时触发 | `SegmentedOption` | 0.1.23 | | click | 选项点击时触发 | `SegmentedOption` | 1.2.20 | ## Methods 对外暴露函数 | 事件名称 | 说明 | 参数 | 最低版本 | | ----------------- | --------------------------------------------------------- | ------------------------------ | -------- | | updateActiveStyle | 更新滑块偏移量，参数`animation`用于是否开启动画，默认开启 | `(animation: boolean) => void` | - | ## Slots | name | 说明 | 参数 | 最低版本 | | ----- | ------------ | ----------------------------- | -------- | | label | 选项标签内容 | `{ option: SegmentedOption }` | 0.1.23 | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ----------- | ------------ | -------- | | customStyle | 自定义样式 | 0.1.23 | | customClass | 自定义样式类 | 0.1.23 | --- --- url: 'https://wot-design-uni.cn/component/select-picker.md' --- # SelectPicker 单复选选择器 0.1.34 更新 用于从一组选项中进行单选或多选。 ## 基本用法 `label` 设置左侧文本内容； `columns` 设置数据源，一维数组，每个选项包含 `value`(选项值) 和 `label`(选项名称)； `v-model` 设置选中项的值，数据类型为 `Array` | `String` `Number` 或 `Boolean`； ```html ``` ```typescript const columns = ref>([ { value: '101', label: '男装' }, { value: '102', label: '奢侈品' }, { value: '103', label: '女装' } ]) const value = ref(['101']) function handleChange({ value }) { toast.show('选择了' + value) } ``` ## 类型切换 `type` 默认值为 `checkbox`， 为默认值时，value 值类型为 `Array` 类型 设置 `type` 值为 `radio` ，开启单选类型，value 值类型为 `String` `Number` 或 `Boolean`。 ```html ``` ```typescript const columns = ref>([ { value: '101', label: '男装' }, { value: '102', label: '奢侈品' }, { value: '103', label: '女装' } ]) const value = ref(['101']) ``` ## 禁用 设置 `disabled` 属性。 ```html ``` ## 只读 设置 `readonly` 属性。 ```html ``` ## 清空 设置 `clearable` 属性 ```html ``` ## 禁用选项 `columns` 每个选项支持 `disabled` 属性。 ```html ``` ```typescript const columns = ref>([ { value: '101', label: '男装', disabled: true }, { value: '102', label: '奢侈品' }, { value: '103', label: '女装' } ]) const value = ref(['101']) ``` ## 展示格式化 设置 `display-format` 属性，其类型为 `function`，接收当前选中项（当类型`checkbox`时 参数是 数组类型，类型为`radio` 时参数是 `String` `Number` 或 `Boolean` 类型）, 当前的选项数组 `columns`，返回要展示的字符串。 ```html ``` ```typescript const columns = ref>([ { value: '101', label: '男装', disabled: true }, { value: '102', label: '奢侈品' }, { value: '103', label: '女装' } ]) const value = ref(['101']) const displayFormat = (items, columns) => { let showValue = '' columns.forEach((column) => { items.forEach((item, index) => { if (column.value === item) { showValue += `${item}: ${column.label} ${index + 1 < items.length ? '--' : ''} ` } }) }) return showValue } ``` ## 确定前校验 设置 `before-confirm` 函数，在用户点击`确定`按钮时，会执行 `before-confirm` 函数，并传入`value`(选中项 也就是当前选择的值） 和 `resolve` 参数，可以对 `value` 进行校验，并通过 `resolve` 函数告知组件是否确定通过，`resolve` 接受 1 个 boolean 值，`resolve(true)` 表示选项通过，`resolve(false)` 表示选项不通过，不通过时不会关闭弹窗。 ```html ``` ```typescript const columns = ref>([ { value: '101', label: '男装' }, { value: '102', label: '奢侈品' }, { value: '103', label: '女装' } ]) const value = ref(['101']) const beforeConfirm = (value, resolve) => { if (value.length > 0) { toast.error('暂时无法选择商品') resolve(false) } else { resolve(true) } } ``` ## 设置标题 设置 `title` 属性，修改弹出层的标题。 ```html ``` ## 错误状态 设置 `error` 属性，选择器的值显示为红色。 ```html ``` ## 必填样式 设置 `required` 属性，展示必填样式。 ```html ``` ## 选择器大小 通过设置 `size` 修改选择器大小，将 `size` 设置为 'large' 时字号为 16px。 ```html ``` ## 值靠右展示 设置 `align-right` 属性，选择器的值靠右展示。 ```html ``` ## 可搜索 设置 `filterable` 属性支持本地搜索，设置 `filter-placeholder` 属性设置搜索框的占位符。 ```html ``` ## 自动完成 `radio`类型，设置 `show-confirm` 属性支持控制确认按钮的显示，设置为`false`可自动完成。 ```html ``` ## 自定义选择器 如果默认的 cell 类型的展示格式不满足需求，可以通过默认插槽进行自定义选择器样式。 ```html 当前选中项：{{customShow}} 默认唤起项 ``` ```typescript const value = ref(['102']) const columns = ref>([ { value: '101', label: '男装' }, { value: '102', label: '奢侈品' }, { value: '103', label: '女装' }, { value: '104', label: '鞋靴' }, { value: '105', label: '内衣配饰' }, { value: '106', label: '箱包' }, { value: '107', label: '美妆护肤' }, { value: '108', label: '个性清洁' }, { value: '109', label: '钟表珠宝' }, { value: '110', label: '手机' }, { value: '111', label: '数码' }, { value: '112', label: '电脑办公' } ]) function handleConfirm({ value, selectedItems }) { console.log(value) customShow.value = selectedItems .map((item) => { return item.label }) .join(', ') } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ---------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------- | ---------------- | -------- | ---------------- | | v-model | 选中项，`type`类型为`checkbox`时，类型为 array；`type`为`radio` 时 ，类型为 number / boolean / string | array / number / boolean / string | - | - | - | | columns | 选择器数据，一维数组 | array | - | - | - | | type | 单复选选择器类型 | string | checkbox / radio | checkbox | - | | value-key | 选项对象中，value 对应的 key | string | - | value | - | | label-key | 选项对象中，展示的文本对应的 key | string | - | label | - | | title | 弹出层标题 | string | - | - | - | | label | 选择器左侧文案 | string | - | - | - | | placeholder | 选择器占位符 | string | - | 请选择 | - | | disabled | 禁用 | boolean | - | false | - | | loading | 加载中 | boolean | - | false | - | | loading-color | 加载的颜色，只能使用十六进制的色值写法，且不能使用缩写 | String | - | #4D80F0 | - | | readonly | 只读 | boolean | - | false | - | | display-format | 自定义展示文案的格式化函数，返回一个字符串 | function | - | - | - | | confirm-button-text | 确认按钮文案 | string | - | 确认 | - | | size | 设置选择器大小 | string | large | - | - | | label-width | 设置左侧标题宽度 | string | - | 33% | - | | error | 是否为错误状态，错误状态时右侧内容为红色 | boolean | - | false | - | | required | 必填样式 | boolean | - | false | - | | align-right | 选择器的值靠右展示 | boolean | - | false | - | | before-confirm | 确定前校验函数，接收 (value, resolve) 参数，通过 resolve 继续执行 picker，resolve 接收 1 个 boolean 参数 | function | - | - | - | | select-size | 设置 picker 内部的选项组尺寸大小 （单/复选框） | string | large | - | - | | min | 最小选中的数量（仅在复选框类型下生效，`type`类型为`checkbox`） | number | - | 0 | - | | max | 最大选中的数量，0 为无限数量，默认为 0（仅在复选框类型下生效，`type`类型为`checkbox`） | number | - | 0 | - | | checked-color | 选中的颜色（单/复选框） | string | - | #4D80F0 | - | | use-default-slot | 使用默认插槽时设置该选项 | boolean | - | false | - | | use-label-slot | 使用 label 插槽时设置该选项 | boolean | - | false | - | | close-on-click-modal | 点击遮罩是否关闭 | boolean | - | true | - | | z-index | 弹窗层级 | number | - | 15 | - | | safe-area-inset-bottom | 弹出面板是否设置底部安全距离（iphone X 类型的机型） | boolean | - | true | - | | filterable | 可搜索（目前只支持本地搜索） | boolean | - | false | - | | filter-placeholder | 搜索框占位符 | string | - | 搜索 | - | | ellipsis | 是否超出隐藏 | boolean | - | false | - | | scroll-into-view | 重新打开是否滚动到选中项 | boolean | - | true | 0.1.34 | | show-confirm | 是否显示确认按钮（仅`radio`类型生效） | boolean | | true | 1.2.8 | | prop | 表单域 `model` 字段名，在使用表单校验功能的情况下，该属性是必填的 | string | - | - | - | | rules | 表单验证规则，结合`wd-form`组件使用 | `FormItemRule []` | - | `[]` | - | | clearable | 显示清空按钮 | boolean | - | false | 1.3.13 | ### FormItemRule 数据结构 | 键名 | 说明 | 类型 | | --------- | ------------------------------------------------------- | ------------------------------------- | | required | 是否为必选字段 | `boolean` | | message | 错误提示文案 | `string` | | validator | 通过函数进行校验，可以返回一个 `Promise` 来进行异步校验 | `(value, rule) => boolean \| Promise` | | pattern | 通过正则表达式进行校验，正则无法匹配表示校验不通过 | `RegExp` | ## 选项数据结构 | 键名 | 说明 | 类型 | 是否必填 | 最低版本 | | -------- | -------- | ------- | -------- | -------- | | value | 选项值 | string | 是 | - | | label | 选项名 | string | 是 | - | | disabled | 禁用选项 | boolean | 否 | - | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | -------------------------- | ---------------------------------------------------------------------------------------------------------- | -------- | | confirm | 点击确认时触发 | event.detail = { value, selectedItems }, checkbox 类型时 value 和 selectedItems 为数组，radio 类型为非数组 | - | | change | picker 内选项更改时触发 | `{ value }`, checkbox 类型时 value 为数组，radio 类型为非数组 | - | | cancel | 点击关闭按钮或者蒙层时触发 | - | - | | close | 弹窗关闭时触发 | - | 1.2.29 | | open | 弹窗打开时触发 | - | 1.2.29 | | clear | 点击清空按钮时触发 | - | 1.3.13 | ## Methods | 方法名称 | 说明 | 参数 | 最低版本 | | -------- | -------- | ---- | -------- | | open | 打开弹窗 | - | - | | close | 关闭弹窗 | - | - | ## Slots | 插槽名称 | 说明 | 最低版本 | | -------- | ---------- | -------- | | default | 自定义展示 | - | | label | 左侧插槽 | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | -------------------- | ------------------------ | -------- | | custom-class | 根节点样式 | - | | custom-label-class | label 外部自定义样式 | - | | custom-value-class | value 外部自定义样式 | - | | custom-content-class | 弹出层内容区域自定义样式 | - | --- --- url: 'https://wot-design-uni.cn/component/sidebar.md' --- # Sidebar 侧边导航 0.1.49 垂直展示的导航栏，用于在不同的内容区域之间进行切换。 ## 基础用法 通过 `v-model` 绑定当前选中项的索引。 ```html ``` ```typescript const active = ref(0) ``` ## 徽标提示 设置 `is-dot` 属性后，会在右上角展示一个小红点；设置 `badge` 属性后，会在右上角展示相应的徽标。 ```html ``` ## 禁用选项 通过 `disabled` 属性禁用选项。 ```html ``` ## 监听切换事件 设置 `change` 方法来监听切换导航项时的事件。 ```html ``` ```typescript import { useToast } from '@/uni_modules/wot-design-uni' const toast = useToast() const active = ref(1) function handleChange({ value, label }) { toast.show(`当前标签名 ${label}`) } ``` ## 异步切换 通过 `before-change` 属性可以在切换标签前执行特定的逻辑。它接收 `{ value, resolve }` 参数，通过 `resolve` `继续执行，resolve` 接收 1 个 boolean 参数 ```html ``` ```typescript import { useToast } from '@/uni_modules/wot-design-uni' import type { SidebarBeforeChange } from '@/uni_modules/wot-design-uni/components/wd-sidebar/types' import { ref } from 'vue' const { loading: showLoading, close: closeLoading } = useToast() const toast = useToast() const active = ref(1) const beforeChange: SidebarBeforeChange = ({ value, resolve }) => { showLoading('切换中') setTimeout(() => { closeLoading() resolve(true) }, 2000) } ``` ## 锚点用法示例 sidebar 组件的锚点用法可以帮助用户在长页面上快速导航到特定的部分。 ::: details 查看锚点用法示例 ::: code-group ```html [vue] ``` ```typescript [typescript] ``` ```css [css] .wraper { display: flex; height: calc(100vh - var(--window-top)); height: calc(100vh - var(--window-top) - constant(safe-area-inset-bottom)); height: calc(100vh - var(--window-top) - env(safe-area-inset-bottom)); } .content { flex: 1; background: #fff; } ``` ::: ## 切换页面用法示例 sidebar 组件在每次切换激活项时，跳转到指定的页面，且无法通过滚动导航到下一个 sidebar 项。 ::: details 查看切换页面用法示例 ::: code-group ```html [vue] ``` ```typescript [typescript] ``` ```css [css] .wraper { display: flex; height: calc(100vh - var(--window-top)); height: calc(100vh - var(--window-top) - constant(safe-area-inset-bottom)); height: calc(100vh - var(--window-top) - env(safe-area-inset-bottom)); overflow: hidden; } .content { flex: 1; background: #fff; transition: transform 0.3s ease; } .category { box-sizing: border-box; height: 100%; } ``` ::: ## 自定义图标用法示例 设置`sidebar-item`的`icon`属性，自定义图标。 ::: details 自定义图标用法示例 ::: code-group ```html [vue] ``` ```typescript [typescript] ``` ```css [css] .wraper { display: flex; height: calc(100vh - var(--window-top)); height: calc(100vh - var(--window-top) - constant(safe-area-inset-bottom)); height: calc(100vh - var(--window-top) - env(safe-area-inset-bottom)); } .content { flex: 1; background: #fff; } ``` ::: ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------ | ------ | ---------------- | | modelValue / v-model | 当前导航项的索引 | string / number | - | 0 | 0.1.49 | | before-change | 切换导航项前钩子，可以在切换标签前执行特定的逻辑，接收 { value, resolve } 参数，通过 resolve 继续执行，resolve 接收 1 个 boolean 参数 | function | - | - | 1.4.0 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | -------------- | ------------------------------------------ | -------- | | change | 选项切换时触发 | `(value: number \| string, label: string)` | 0.1.49 | ## Slots | name | 说明 | 参数 | 最低版本 | | ------- | ---------- | ---- | -------- | | default | 自定义展示 | - | 0.1.49 | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ----------- | ------------ | -------- | | customStyle | 自定义样式 | 0.1.49 | | customClass | 自定义样式类 | 0.1.49 | ## SidebarItem Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ----------- | ---------------------------------------------------------------------------------------- | -------------------------- | ------ | ------ | -------- | | label | 当前选项标题 | string | - | - | 0.1.49 | | value | 当前选项的值，唯一标识 | `number / string` | - | - | 0.1.49 | | icon | 图标 | string | - | - | 0.1.49 | | badge | 徽标属性，徽标显示值 | `number / string / null` | - | - | 0.1.49 | | isDot | 徽标属性，是否点状徽标 | boolean | - | false | 0.1.49 | | max | 徽标属性，徽标最大值 | number | - | 99 | 0.1.49 | | disabled | 是否禁用 | boolean | - | false | 0.1.49 | | badge-props | 自定义徽标的属性，传入的对象会被透传给 [Badge 组件的 props](/component/badge#attributes) | BadgeProps | - | - | 0.1.50 | ## SidebarItem Slots | name | 说明 | 参数 | 最低版本 | | ---- | ---------- | ---- | -------- | | icon | 自定义图标 | - | 0.1.49 | ## SidebarItem 外部样式类 | 类名 | 说明 | 最低版本 | | ----------- | ------------ | -------- | | customStyle | 自定义样式 | 0.1.49 | | customClass | 自定义样式类 | 0.1.49 | --- --- url: 'https://wot-design-uni.cn/component/signature.md' --- # Signature 签名 1.6.0 用于签名场景，基于 Canvas 实现的签名组件。提供了基础签名、历史记录、笔锋效果等功能。 :::tip 提醒 如果遇到导出图片不清晰，可以将 `exportScale` 设置为 `2` 以上。 ::: ## 基础用法 基础的电子签名功能。签名完成后会使用预览组件显示签名图片。 ```html ``` ```typescript const img = ref>({}) function confirm(result: SignatureResult) { if (result.success) { uni.previewImage({ urls: [result.tempFilePath] }) } } function clear() { img.value = {} } ``` ## 历史记录 通过 `enable-history` 开启历史记录功能，可以进行撤销和恢复操作。 ```html ``` ## 笔锋模式 通过 `pressure` 开启笔锋模式，模拟真实书写效果。笔锋模式下笔画粗细会随书写速度变化。 ### 基础笔锋效果 ```html ``` :::tip 使用建议 1. 笔锋模式推荐参数范围： * min-width: 1-2 * max-width: 4-6 * min-speed: 1-2 2. max-width 和 min-width 的差值建议保持在 3-5 之间 3. min-speed 值越小，压感越灵敏，建议根据实际书写习惯调整 4. 对于签名场景，建议将画布高度设置在 300-400 之间 ::: ### 自定义笔锋参数 可以通过以下属性精确控制笔锋效果： * `min-width`: 最小笔画宽度，快速书写时的线条粗细 * `max-width`: 最大笔画宽度，慢速书写时的线条粗细 * `min-speed`: 速度阈值，用于调整压感灵敏度 ```html 快速书写产生细线条，慢速书写产生粗线条 ``` ### 笔锋模式 + 历史记录 笔锋模式可以与历史记录功能结合使用，支持对带有笔锋效果的线条进行撤销和恢复操作。 ```html 结合历史记录，支持笔锋效果的撤销与恢复 ``` ## 自定义功能 ### 自定义按钮 通过 `footer` 插槽自定义底部按钮。 ```html ``` ```typescript const disabled = ref(true) function changeDisabled() { disabled.value = false } ``` ### 自定义画笔 可以自定义画笔的颜色和宽度。 ```html ``` ### 弹窗中使用 结合 `wd-popup` 组件在弹窗中使用签名板。建议使用 `after-enter` 事件调用签名板的 `init` 方法以确保正确初始化。 ```html 打开签名板 ``` ```typescript import { ref } from 'vue' import type { SignatureInstance, SignatureResult } from '@/uni_modules/wot-design-uni/components/wd-signature/types' const show = ref(false) const img = ref>({}) const signatureRef = ref() function handleConfirm(result: SignatureResult) { show.value = false if (result.success) { uni.previewImage({ urls: [result.tempFilePath] }) } } ``` ```scss .popup-footer { margin-top: 16px; display: flex; justify-content: flex-end; gap: 12px; } ``` :::tip 提示 弹窗中使用签名板时，建议： 1. 开启 `closable` 显示关闭按钮 2. 设置 `safe-area-inset-bottom` 以适配底部安全区 3. 使用 `custom-style` 调整弹窗内边距，为关闭按钮留出空间 4. 在弹窗的 `after-enter` 事件中调用签名板的 `init` 方法，确保正确初始化 ::: ### 横屏签名页面 可以通过配置页面的 `pageOrientation` 来实现横屏签名页面。 ```json // pages.json { "pages": [ { "path": "pages/signature-landscape/Index", "style": { "navigationBarTitleText": "横屏签名", "pageOrientation": "landscape" } } ] } ``` ```html ``` :::tip 提示 横屏签名页面的建议： 1. 使用 `pageOrientation: "landscape"` 强制横屏显示 2. 动态计算画布尺寸以适配不同设备 3. 注意横屏时 windowWidth 和 windowHeight 的对调 4. 建议开启笔锋模式提供更好的签名体验 ::: ### 横屏签名 支持以下两种横屏签名实现方案： #### 1. 通用横屏方案 (推荐) 通过自定义布局和按钮旋转实现横屏效果，适用于所有平台。 ```html ``` ```ts import { pause } from '@/uni_modules/wot-design-uni/components/common/util' const height = ref(0) const width = ref(0) const inited = ref(false) onMounted(() => { const { windowWidth, windowHeight } = uni.getSystemInfoSync() width.value = windowWidth - 48 height.value = windowHeight - 48 pause(100).then(() => { inited.value = true }) }) ``` ```scss .landscape-signature { height: 100vh; // #ifdef H5 height: calc(100vh - 44px); // #endif background: #fff; position: relative; padding: 24px 0; padding-left: 48px; box-sizing: border-box; .custom-actions { position: fixed; left: 0; top: 50%; width: 48px; transform: translateY(-50%) rotate(90deg); transform-origin: center; z-index: 10; .button-group { display: flex; flex-direction: row; gap: 12px; white-space: nowrap; width: max-content; transform: translateX(-50%); } } } ``` :::tip 实现说明 通用横屏方案特点： 1. 使用 fixed 布局配合旋转实现左侧垂直按钮栏 2. 通过 footer 插槽自定义操作按钮 3. 使用 transform 实现按钮的旋转效果 4. 适用于所有平台,实现方式一致 5. 建议使用 inited 变量配合延迟加载避免画布初始化问题 ::: #### 2. 原生横屏方案 (仅微信小程序) 微信小程序提供了原生的横屏支持，使用时需要注意区分平台: ```json { "path": "pages/signature/landscape", "style": { "navigationBarTitleText": "横屏签名", // #ifdef MP-WEIXIN "pageOrientation": "landscape" // #endif } } ``` ```html ``` ```ts import { pause } from '@/uni_modules/wot-design-uni/components/common/util' const height = ref(0) const width = ref(0) const inited = ref(false) onMounted(() => { const { windowWidth, windowHeight } = uni.getSystemInfoSync() width.value = windowWidth height.value = windowHeight - 60 // 预留底部按钮空间 pause(100).then(() => { inited.value = true }) }) ``` ```scss .landscape-signature { height: 100vh; background: #fff; position: relative; box-sizing: border-box; // #ifdef MP-WEIXIN padding: 0; display: flex; flex-direction: column; .weixin-actions { padding: 12px; background-color: #f8f8f8; .button-group { display: flex; justify-content: center; gap: 12px; } } // #endif } ``` :::warning 注意事项 1. `pageOrientation` 配置仅在微信小程序端生效 2. 使用条件编译区分不同平台的布局结构 3. 微信小程序页面会自动旋转，按钮布局不需要特殊处理 4. 预留底部按钮空间时需要考虑横屏布局 5. 其他平台请使用通用横屏方案 ::: ## Attributes | 参数 | 说明 | 类型 | 默认值 | 最低版本 | |------|------|------|--------|----------| | pen-color | 签名笔颜色 | string | #000000 | - | | line-width | 签名笔宽度 | number | 3 | - | | height | 画布的高度 | number | 200 | - | | width | 画布的宽度 | number | 300 | - | | clear-text | 清空按钮的文本 | string | - | - | | confirm-text | 确认按钮的文本 | string | - | - | | file-type | 导出图片类型 | string | png | - | | quality | 导出图片质量(0-1) | number | 1 | - | | export-scale | 导出图片的缩放比例 | number | 1 | - | | disabled | 是否禁用签名板 | boolean | false | - | | background-color | 画板的背景色 | string | - | - | | disable-scroll | 是否禁用画布滚动 | boolean | true | - | | enable-history | 是否开启历史记录 | boolean | false | 1.8.0 | | step | 历史记录步长 | number | 1 | 1.8.0 | | pressure | 是否启用笔锋模式 | boolean | false | 1.8.0 | | min-width | 笔锋模式最小宽度 | number | 2 | 1.8.0 | | max-width | 笔锋模式最大宽度 | number | 6 | 1.8.0 | | min-speed | 笔锋模式速度阈值 | number | 1.5 | 1.8.0 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | |---------|------|------|----------| | start | 开始签名时触发 | event: TouchEvent | - | | end | 结束签名时触发 | event: TouchEvent | - | | signing | 签名过程中触发 | event: TouchEvent | - | | confirm | 确认签名时触发 | result: SignatureResult | - | | clear | 清空签名时触发 | - | - | ## Methods | 方法名 | 说明 | 参数 | 最低版本 | |--------|------|------|----------| | init | 初始化签名板 | forceUpdate?: boolean | - | | confirm | 确认签名 | - | - | | clear | 清空签名 | - | - | | restore | 恢复上一步 | - | - | | revoke | 撤销上一步 | - | - | ## Slots | 名称 | 说明 | 参数 | 最低版本 | |------|------|------|----------| | footer | 自定义底部按钮 | `{ clear, confirm, restore, revoke, currentStep, historyList }` | - | --- --- url: 'https://wot-design-uni.cn/component/skeleton.md' --- # Skeleton 骨架屏 用于等待加载内容所展示的占位图形组合，有动态效果加载效果，减少用户等待焦虑。 ## 骨架图风格 支持 `avatar`、`image`、`text`、`paragraph` 四种类型。 ```html // 头像骨架屏 // 图片骨架屏 // 文本骨架屏 // 段落骨架屏 ``` ## 宫格骨架屏 ```html ``` ```ts const grid = [ [ { width: '48px', height: '48px' }, { width: '48px', height: '48px' }, { width: '48px', height: '48px' }, { width: '48px', height: '48px' }, { width: '48px', height: '48px' } ], [ { width: '48px', height: '16px' }, { width: '48px', height: '16px' }, { width: '48px', height: '16px' }, { width: '48px', height: '16px' }, { width: '48px', height: '16px' } ] ] ``` ## 单元格骨架屏 ```html ``` ## 图片组合骨架屏 ```html ``` ```ts const imageGroup = [ { height: '171px' }, 1, { width: '107px' }, [{ width: '93px' }, { width: '32px', marginLeft: '41px' }] ] ``` ## 加载动画 支持 `gradient`、`flashed` ```html ``` ## 插槽内容 可以通过插槽写入展示的内容，当请求结束，将loading设置为false，此时会隐藏骨架组件，同时展示插槽内容。 ```html ``` ```js const showContent = ref(true) ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ----------------------------------- | ------ | -------- | | theme | 骨架图风格 | SkeletonTheme | `text` `avatar` `paragraph` `image` | - | - | | rowCol | 用于设置行列数量、宽度高度、间距等【示例一】`[1, 1, 2]` 表示输出三行骨架图，第一行一列，第二行一列，第三行两列。 【示例二】`[1, 1, { width: '100px' }]` 表示自定义第三行的宽度为 `100px`。 【示例三】`[1, 2, [{ width, height }, { width, height, marginLeft }]]` 表示第三行有两列，且自定义宽度、高度和间距 | SkeletonRowCol | - | - | - | | loading | 是否为加载状态，如果是则显示骨架图，如果不是则显示加载完成的内容 | boolean | - | true | - | | animation | 动画效果 | SkeletonAnimation | `gradient` `flashed` | - | - | ## Slots | name | 说明 | 最低版本 | | ------- | --------------------- | ---------------- | | default | loading结束后展示内容 | 1.2.21 | --- --- url: 'https://wot-design-uni.cn/component/slider.md' --- # Slider 滑块 支持单向滑块和双向滑块。 ## 基本用法 `v-model` 为绑定值。如果为 number 类型则显示一个滑块，如果为 array 类型则显示两个滑块。 ```html ``` ```typescript const value = ref(30) ``` ## 双滑块 双滑块模式下 `value` 为 `二元数组` 类型。 ```html ``` ```typescript const value = ref([10, 30]) ``` ## 最大值最小值 设置 `min` 最小值，`min` 最大值。 ```html ``` ## 隐藏文案 设置 `hide-label` 隐藏滑块当前值。 ```html ``` 设置 `hide-min-max` 隐藏最大最小值。 ```html ``` ## 禁用 设置 `disabled` 属性。 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|---------------------------|-----|-------|-------|-------| | v-model | 滑块值，如果为array，则为双向滑块 | number / array | - | - | - | | hide-min-max | 是否显示左右的最大最小值 | boolean | - | false | - | | hide-label | 是否显示当前滑块值 | boolean | - | false | - | | disabled | 是否禁用 | boolean | - | false | - | | max | 最大值 | number | - | 100 | - | | min | 最小值，允许负数`(1.2.19)` | number | - | 0 | - | | step | 步进值 | number | - | 1 | `1.2.19` | | active-color | 进度条激活背景颜色 | string | - | linear-gradient(315deg, rgba(81,124,240,1) 0%,rgba(118,158,245,1) 100%) | - | | inactive-color | 进度条未激活背景颜色 | string | - | #e5e5e5 | - | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | |---------|-----|-----|---------| | dragstart | 开始移动时触发 | `{ value }` | - | | dragmove | 移动滑块时触发 | `{ value }` | - | | dragend | 移动结束时触发 | `{ value }` | - | ## Methods 对外暴露函数 | 事件名称 | 说明 | 参数 | 最低版本 | |--------|------|-----|---------| | initSlider | 初始化slider宽度数据 | - | 1.2.25 | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | | custom-min-class | 最小值自定义样式 | - | | custom-max-class | 最大值自定义样式 | - | --- --- url: 'https://wot-design-uni.cn/component/sort-button.md' --- # SortButton 排序按钮 用于展示排序按钮，支持升序、降序、重置三种状态。 ## 基本用法 使用`v-model` 绑定组件展示状态，其值为：`-1、0、1`，分别代表：降序、未选中状态、升序。 `title` 为展示文案，按钮默认处于未选中状态。 ```html ``` ```typescript const value = ref(0) function handleChange({ value }) { console.log(value) } ``` ## 按钮重置 双箭头状态下(默认状态)通过设置 `allow-reset` 允许重置按钮为未选中状态 ```html ``` ## 优先切换为降序 通过设置 `desc-first` 优先切换为降序，默认为升序。 ```html ``` ## 取消展示下划线 当只有一个排序按钮时，应该不展示下划线，设置 `line` 属性为 `false`。 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|--------| | v-model | 选中的箭头方向：1 升序，0 重置状态，-1 降序。 | number | -1,0,1 | 0或-1 | - | | title | 排序按钮展示的文案。 | string | - | - | - | | allow-reset | 展示双箭头时，允许手动重置按钮。 | boolean | - | false | - | | desc-first | 优先切换为降序，不开启则默认优先切换为升序 | boolean | - | false | - | | line | 展示下划线，当只有一个排序按钮时，应该不展示下划线 | boolean | - | true | - | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | |---------|-----|-----|---------| | change | 监听排序修改 | `{ value }` | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/status-tip.md' --- # StatusTip 缺省提示 一般用于兜底占位展示。 ::: warning 注意 本组件使用图片均为外链，***不保证稳定性***，推荐将图片下载到开发者的服务器后通过自定义图片`URL`或者自定义`url-prefix`使用。1.3.11版本开始支持自定义图片地址前缀`url-prefix`。 下载地址： 1. Github 仓库： 2. npm 地址： * npm： * 淘宝镜像： ::: ## 基本用法 设置 `image` 修改展示缺省图片类型，默认为 `network`，可选值 `search`, `network`, `content`, `collect`, `comment`, `halo`, `message`。可设置 `tip` 来控制展示提示文案。 ```html ``` ## 自定义大小 通过 `image-size` 属性图片的大小。 ```html ``` ## 自定义图片 需要自定义图片时，可以在 `image` 属性中传入任意图片 URL。 ```html ``` ## 自定义图片内容 使用插槽 `image` 可以自定义图片内容。 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ---------- | -------------------------------------------------- | ----------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------- | ---------------- | | image | 缺省图片类型，支持传入图片 URL | string | search / network / content / collect / comment / halo / message | network | - | | image-size | 图片大小，默认单位为 `px` | `string`/`number`/`ImageSize` | - | - | - | | tip | 提示文案 | string | - | - | - | | image-mode | 预览图片的 mode 属性 | `ImageMode` | - | aspectFit | 1.2.12 | | url-prefix | 图片路径前缀，指向图片所在目录，用于拼接图片 URL。 | string | - | https://registry.npmmirror.com/wot-design-uni-assets/\*/files/ | 1.3.11 | ### ImageSize | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------ | ------------------------- | ---------------- | ------ | ------ | -------- | | height | 图片高度，默认单位为 `px` | string / number | - | - | 1.2.12 | | width | 图片宽度，默认单位为 `px` | string / number | - | - | 1.2.12 | ## Slot | name | 说明 | 最低版本 | | ------- | ------------------------ | -------- | | image | 图片内容 | 1.3.12 | --- --- url: 'https://wot-design-uni.cn/component/steps.md' --- # Steps 步骤条 用于引导用户按照流程完成任务或向用户展示当前状态。 :::tip 破坏性更新提醒 `1.2.10`版本`step`组件废弃了`title-slot`、`icon-slot`和`description-slot`等三个控制插槽使用的字段，新增支持直接使用`title`、`icon`和`description`插槽，同时废弃了`default`插槽。 ::: ## 基本用法 `active` 为步骤进度，为 number 类型，步骤的下标。 ```html ``` ```ts const active = ref(0) function nextStep() { active.value = active.value + 1 } ``` ## 水平居中 设置 `align-center` 水平居中，只对横向步骤条有效。 ```html ``` ## 设置标题和描述信息 可以通过 `title` 和 `description` 设置步骤的标题和描述信息。如果不设置标题，则会使用默认的文案。 ```html 下一步 ``` ```ts const active = ref(0) function nextStep() { active.value = active.value + 1 } ``` ## 修改图标 可以通过 `icon` 属性设置步骤的图标，传入图标的名称，也可以通过 `icon` 的 slot 插槽自定义图标，使用插槽需要设置 `icon-slot` 为 `true`。 ```html ``` ## 竖向步骤条 设置 `vertical` 属性。 ```html ``` ## 点状步骤 设置 `dot` 属性。 ```html ``` ## 修改状态 设置 `status`，支持 'finished'（完成）、'process'（进行中）、'error'（失败） 三种状态。 ```html ``` ## Steps Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|--------| | active | 步骤进度 | number | - | 0 | - | | vertical | 垂直方向 | boolean | - | false | - | | dot | 点状步骤条 | dot | - | false | - | | space | 步骤条间距，默认为自动计算 | string | - | - | - | | align-center | 是否水平居中，只对横向步骤条有效 | boolean | - | false | - | ## Step Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|--------| | title | 标题，如果没有则为默认文案。当只有标题而没有描述时，标题的字号会小2号 | string | - | - | - | | title-slot | 使用 title 插槽时需要设置该属性，已废弃，直接使用title插槽即可 | boolean | - | false | - | | description | 描述 | string | - | - | - | | description-slot | 使用 description 插槽时需要设置该属性，已废弃，直接使用description插槽即可 | boolean | - | false | - | | icon | 图标 | string | - | - | - | | icon-slot | 使用 icon 插槽时需要设置该属性，已废弃，直接使用icon插槽即可 | boolean | - | false | - | | status | 步骤状态 | string | finished / process / error | - | - | ## Step Slot | name | 说明 | 最低版本 | |------|-----|---------| | icon | 图标 | 1.2.10 | | title | 标题 | 1.2.10 | | description | 描述 | 1.2.10 | ## Steps 外部样式类 | 类名 | 说明 | 最低版本 | |-----|-----|---------| | custom-class | 根节点样式 | - | ## Step 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/sticky.md' --- # Sticky 粘性布局 粘性布局组件，用于在页面滚动时将元素固定在指定位置。 ## 基本用法 将需要吸顶的内容包裹在 `wd-sticky` 组件内即可。 > 注意：被包裹的元素在样式中使用百分比单位 `width:xx%;height:xx%;` 无效，建议使用 `vh`、`vw`。 ```html 基础用法 ``` ## 动态插入 `wd-sticky` 支持包裹动态生成的内容。 > 注意包裹动态生成的内容时，内容的宽高不小于 `1px` ```html 点击插入 动态插入 ``` ```typescript const show = ref(false) function display() { show.value = true } onShow(() => { setTimeout(display, 5000) }) ``` ```scss page{ height: 200vh; } ``` ## 吸顶距离 通过 `offset-top` 属性可以设置组件在吸顶时与顶部的距离。 ::: tip 提醒 由于在`H5`端导航栏为普通元素，所以吸顶距离会自动在`offset-top`的基础上增加`44px`，当开发者在`H5`端使用自定义导航栏时`offset-top`就需要先减去`44`。例如期望吸顶距离为20px，那么`offset-top = 20 - 44 = -24` ::: ```html 吸顶距离 ``` ## 指定容器 将 `wd-sticky` 组件包裹在自定义容器内，之后再使用 `wd-sticky-box` 包裹自定义容器。 > 注意：被包裹的自定义容器在样式中使用百分比单位 `width:xx%;height:xx%;` 无效，建议使用 `vh`、`vw`。 ```html 指定容器 ``` ```scss .container{ height: 150px;width: 100vw; } ``` ## Sticky Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|--------| | z-index | 堆叠顺序 | number | - | 1 | - | | offset-top | 吸顶距离 | number | - | 0 | - | ## Sticky 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | ## Sticky Box 外部样式类 | 类名 | 说明 | 最低版本 | |-----|------|--------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/swipe-action.md' --- # SwipeAction 滑动操作 常用于单元格左右滑删除等手势操作。 :::warning 滑动操作组件对页面的功能隐藏较深，用户难以发现，建议使用其他交互方式来实现操作功能，比如列表项有个按钮，点击按钮弹出 ActionSheet。 如果坚持要使用滑动操作组件，建议在用户进入页面时加上操作提示以提示用户列表项可以左右滑动。 ::: ## 基本用法 `wd-swipe-action`分为三部分：`自定义左按钮内容`、`自定义内容`、`自定义右按钮内容`。自定义按钮内容需要设置`slot`开启，自定义内容为默认插槽，无需手动开启。 因为`uni-app`组件无法监听点击自己以外的地方，为了在点击页面其他地方时，可以自动关闭 `swipeAction` ，建议使用组件库的 `useQueue` hook（会关闭所有 dropmenu、popover、toast、swipeAction、fab），在页面的根元素上监听点击事件的冒泡。 :::warning 如果存在用户手动点击 `swipeAction` 以外某个地方如按钮滑出 `swipeAction` 的场景，则需要在点击的元素（在这里上按钮）加上 @click 阻止事件冒泡到根元素上，避免触发 `closeOutside`把要手动打开的 `swipeAction` 关闭了。 ::: ```html ``` ```typescript import { useToast, useQueue } from '@/uni_modules/wot-design-uni' const { closeOutside } = useQueue() const toast = useToast() function handleAction(action: string) { toast.show(`点击了${action}`) } ``` ```scss .action { height: 100%; } .button { display: inline-block; padding: 0 11px; height: 100%; color: white; line-height: 42px; } ``` ## 左右滑动 > `wd-swipe-action`组件提供`left`/`right`两个滑动按钮，通过设置插槽`left`和`right`开启 ```html ``` ## 切换按钮 > 可以通过设置`v-model`来控制开启关闭滑动按钮，可选值为:`left`、`close`、`right`分别表示："打开左滑动按钮"、"关闭滑动按钮""打开右滑动按钮" ```html 打开左边 关闭所有 打开右边 ``` ```typescript const value = ref('close') function changeState(position: string) { value.value = position } ``` ## 按钮关闭前的钩子函数 > 通过`before-close`属性传入一个函数，注意传入的变量必须定义在`data`在。回调函数会在滑动按钮关闭前执行。 钩子函数接收两个参数:`reason`、`position`。 `reason`表示滑动按钮关闭的原因，值为:`click`、`swipe`、`value`，分别代表:点击关闭按钮、滑动关闭按钮、通过控制`value`关闭按钮; `position`代表被关闭的操作按钮，值为：`left`、`right`。当`reason`为`click`时，表示点击`position`位置关闭滑动按钮，值为：`left`、`right`、`inside`。 ```html 打开左边 关闭所有 打开右边 ``` ```typescript import { useToast } from '@/uni_modules/wot-design-uni' const toast = useToast() const value = ref('close') function changeState(position: string) { value.value = position } const beforeClose = (reason, position) => { if (reason === 'click') { toast.show(`${reason} ${position}导致滑动按钮关闭`) } else { toast.show(`${reason}导致${position}滑动按钮关闭`) } } ``` ## 点击事件 > `click`事件只会在关闭滑动按钮时触发。 回调函数的参数表示点击的位置，其中`left`、`right`表示点击了左右滑动按钮，`inside`表示点击了容器内按钮以外的地方。 ```html ``` ```typescript import { useToast } from '@/uni_modules/wot-design-uni' const toast = useToast() function handleClick({ value }) { toast.show(`点击${value}关闭操作按钮`) } ``` ## 禁用滑动按钮 > 设置`disabled`属性禁用滑动 ```html ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------ | ------------------------ | -------- | -------------------- | ------ | -------- | | v-model | 滑动按钮的状态 | string | left / close / right | close | - | | disabled | 是否禁用滑动操作 | boolean | - | false | - | | before-close | 关闭滑动按钮前的钩子函数 | function | - | - | - | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ----------------------------------------------------- | ----------------------------------------------------- | -------- | | click | 当滑动按钮打开时，点击整个滑动操作容器触发 click 事件 | event={value}, value 可能为 'left'、'inside'、'right' | - | ## Slot | name | 说明 | 最低版本 | | ------- | ------------ | -------- | | left | 自定义左按钮 | - | | default | 自定义内容 | - | | right | 自定义右按钮 | - | ## Cell 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/swiper.md' --- # Swiper 轮播 用于创建轮播，它支持水平和垂直方向的滑动，可以自定义样式和指示器位置，支持视频和图片资源的轮播，支持设置轮播标题和自定义标题样式。 :::danger 请注意 嵌入视频仅在`h5`、`微信小程序`和`钉钉小程序`支持，其余端不支持，请了解后使用。 ::: ## 基础用法 通过设置 `autoplay` 属性控制轮播图是否自动播放，设置 `v-model:current` 属性初始化轮播图展示的滑块，监听滑块 `click` 来处理点击事件，而每一页轮播结束后，会触发 `change` 事件。 ```html ``` ```ts const current = ref(0) const swiperList = ref([ 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/redpanda.jpg', 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/capybara.jpg', 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/panda.jpg', 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/moon.jpg', 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/meng.jpg' ]) function handleClick(e) { console.log(e) } function onChange(e) { console.log(e) } ``` ## 点条状指示器 ```html ``` ## 数字指示器 ```html ``` ## 视频轮播1.3.13 :::danger 请注意 嵌入视频仅在`h5`、`微信小程序`和`钉钉小程序`支持，其余端不支持，请了解后使用。 ::: ```html ``` ```ts const videoList = ref([ 'https://unpkg.com/wot-design-uni-assets@1.0.3/VID_115503.mp4', 'https://unpkg.com/wot-design-uni-assets@1.0.3/VID_150752.mp4', 'https://unpkg.com/wot-design-uni-assets@1.0.3/VID_155516.mp4', 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/moon.jpg' ]) ``` ## 手动播放视频 ```html ``` ```ts const videoList = ref([ 'https://unpkg.com/wot-design-uni-assets/VID_115503.mp4', 'https://unpkg.com/wot-design-uni-assets/VID_150752.mp4', 'https://unpkg.com/wot-design-uni-assets/VID_155516.mp4' ]) ``` ## 播放视频时停止轮播 ```html ``` ```ts const videoList = ref([ 'https://unpkg.com/wot-design-uni-assets/VID_115503.mp4', 'https://unpkg.com/wot-design-uni-assets/VID_150752.mp4', 'https://unpkg.com/wot-design-uni-assets/VID_155516.mp4' ]) ``` ## 手动切换 ```html ``` ## 卡片样式 设置 `previousMargin` 和 `nextMargin` 实现卡片轮播的样式。 ```html ``` ```scss .card-swiper { --wot-swiper-radius: 0; --wot-swiper-item-padding: 0 24rpx; --wot-swiper-nav-dot-color: #e7e7e7; --wot-swiper-nav-dot-active-color: #4d80f0; padding-bottom: 24rpx; :deep(.custom-indicator-class) { bottom: -16px; } :deep(.custom-image) { border-radius: 12rpx; } :deep(.custom-image-prev) { height: 168px !important; } } ``` ## 同时展示 2 个滑块 设置 `display-multiple-items` 属性，控制同时展示的滑块数量。 ```html ``` ```scss .card-swiper { --wot-swiper-radius: 0; --wot-swiper-item-padding: 0 24rpx; --wot-swiper-nav-dot-color: #e7e7e7; --wot-swiper-nav-dot-active-color: #4d80f0; padding-bottom: 24rpx; :deep(.custom-indicator-class) { bottom: -16px; } :deep(.custom-image) { border-radius: 12rpx; } :deep(.custom-image-prev) { height: 168px !important; } } ``` ## 垂直方向 `direction` 设置为 `vertical` 后滑块会纵向排列。 ```html ``` ## 自定义指示器 通过 `indicator` 插槽可以自定义指示器的样式。 ```html ``` ```scss .custom-indicator { padding: 0 12rpx; height: 48rpx; line-height: 48rpx; border-radius: 45%; background: rgba(0, 0, 0, 0.6); color: #ffffff; font-size: 24rpx; } ``` ## 指定valueKey和textKey 通过`value-key` 属性指定 `list` 中每个对象图片地址字段，默认为 `value`。 通过`text-key` 属性指定 `list` 中每个对象标题字段，默认为 `text`。 :::tip 提示 当前`swiper`提供的标题样式为顶部靠右，如需自定义样式，请使用外部样式类`customTextClass`或者自定义样式`customTextStyle`，使用`text-key`时请确认你的组件库版本是否包含此功能。 ::: ```html ``` ```ts const current = ref(0) const customSwiperList = ref([ { url: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/redpanda.jpg', title: '小熊猫！' }, { url: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/capybara.jpg', title: '卡！皮！巴！拉！' }, { url: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/panda.jpg', title: '大熊猫！' }, { url: 'https://registry.npmmirror.com/wot-design-uni-assets/*/files/moon.jpg', title: '诗画中国！' } ]) ``` ```scss :deep(.customTextClass) { position: absolute; top: 24rpx; right: 24rpx; color: #ffffff; font-size: 24rpx; text-shadow: 0 0 8rpx #000000; } ``` ## 属性控制切换 ```html prev next ``` ```javascript const current = ref (0) const isLoop = ref(false) ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------------------- | ------------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------ | ---------------- | | autoplay | 是否自动播放 | `boolean` | - | true | 0.1.22 | | v-model:current | 控制当前轮播在哪一项（下标） | `number` | - | 0 | 0.1.22 | | direction | 轮播滑动方向 | `DirectionType` | `horizontal, vertical` | horizontal | 0.1.22 | | displayMultipleItems | 同时显示的滑块数量 | `number` | - | 1 | 0.1.22 | | duration | 滑动动画时长 | `number` | - | 300 | 0.1.22 | | easingFunction | 切换缓动动画类型（微信小程序、快手小程序、京东小程序） | `EasingType` | - | default | 0.1.22 | | height | 轮播的高度 | `string / number` | - | 192 | 0.1.22 | | interval | 轮播间隔时间 | `number` | - | 5000 | 0.1.22 | | list | 图片列表 | `string[] / SwiperList[]` | - | - | 0.1.22 | | loop | 是否循环播放 | `boolean` | - | true | 0.1.22 | | nextMargin | 后边距 | `string / number` | - | 0 | 0.1.22 | | indicatorPosition | 指示器展示位置 | `IndicatorPositionType` | `left, top-left, top, top-right, bottom-left, bottom, bottom-right, right` | bottom | 0.1.22 | | previousMargin | 前边距 | `string / number` | - | 0 | 0.1.22 | | snapToEdge | 边距是否应用到第一个、最后一个元素 | `boolean` | - | false | 0.1.22 | | indicator | 指示器全部配置 | `SwiperIndicatorProps / boolean` | - | true | 0.1.22 | | imageMode | 图片裁剪、缩放的模式 | `string` | 参考官方文档[mode](https://uniapp.dcloud.net.cn/component/image.html#mode-%E6%9C%89%E6%95%88%E5%80%BC) | `aspectFill` | 0.1.55 | | autoplayVideo | 视频是否自动播放，默认自动播放 | `boolean` | - | true | 1.3.13 | | stopPreviousVideo  | 切换轮播项时是否停止上一个视频的播放，默认切换时停止播放上一个视频 | `boolean` | - | true | 1.3.13 | | stopAutoplayWhenVideoPlay | 视频播放时是否停止自动轮播 | `boolean` | - | false | 1.3.13 | | customStyle | 外部自定义样式 | `string` | - | '' | 0.1.22 | | value-key | 选项对象中，value 对应的 key | `string` | - | `value` | 1.3.7 | | text-key | 选项对象中，标题 text 对应的 key | `string` | - | `text` | 1.3.13 | | adjust-height | 自动以指定滑块的高度为整个容器的高度。当 vertical 为 true 时，默认不调整，仅支付宝小程序支持。| `string` | `'first' / 'current' / 'highest' / 'none'` | `highest` | 1.3.13 | | adjust-vertical-height | vertical 为 true 时强制使 adjust-height 生效。仅支付宝小程序支持。 | `boolean` | - | `false` | 1.3.13 | ｜ muted | 视频是否静音播放 | `boolean` | - | `true` | 1.6.0 | | videoLoop | 视频是否循环播放 | `boolean` | - | `true` | 1.6.0 | ### DirectionType 轮播滑动方向，可选值为 `'horizontal'` 和 `'vertical'`。 ### EasingType 切换缓动动画类型，可选值为 `'default'`、`'linear'`、`'easeInCubic'`、`'easeOutCubic'` 和 `'easeInOutCubic'`。 ### IndicatorPositionType 页码信息展示位置，可选值为 `'left'`、`'top-left'`、`'top'`、`'top-right'`、`'bottom-left'`、`'bottom'`、`'bottom-right'` 和 `'right'`。 ### SwiperList 轮播图项的列表配置，包括 图片或视频地址`value`、视频封面`poster` 、文件资源的类型`type`等属性，支持扩展属性。指定`type`后组件将不在内部判断文件类型，以`type`为准。 | name | 说明 | 最低版本 | | --------- | ------------ | -------- | | value | 图片或视频地址 |- | | poster | 视频封面 |- | | type | 用于指定文件资源的类型，可选值`image`、`video` | 1.4.0 | ### SwiperIndicatorProps | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------------- | -------------------------- | --------------------- | -------------------------------------------------------------------------- | ---------- | -------- | | current | 当前轮播在哪一项（下标） | Number | - | 0 | 0.1.22 | | direction | 轮播滑动方向 | DirectionType | `horizontal, vertical` | horizontal | 0.1.22 | | min-show-num | 小于这个数字不会显示导航器 | Number | - | 2 | 0.1.22 | | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------------- | -------------------------- | --------------------- | -------------------------------------------------------------------------- | ---------- | -------- | | current | 当前轮播在哪一项（下标） | Number | - | 0 | 0.1.22 | | direction | 轮播滑动方向 | DirectionType | `horizontal, vertical` | horizontal | 0.1.22 | | min-show-num | 小于这个数字不会显示导航器 | Number | - | 2 | 0.1.22 | | pagination-position | 页码信息展示位置 | IndicatorPositionType | `left, top-left, top, top-right, bottom-left, bottom, bottom-right, right` | bottom | 0.1.22 | | show-controls | 是否显示控制按钮 | Boolean | - | false | 0.1.22 | | total | 总共的项数 | Number | - | 0 | 0.1.22 | | type | 导航器类型 | SwiperIndicatorType | `dots, dots-bar, fraction ` | dots | 0.1.22 | | autoplay | 是否自动播放 | boolean | - | true | 0.1.22 | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | ---------------- | ----------------------------------------------------------- | -------- | | click | 点击轮播项时触发 | `(index: number, item: SwiperList \| string)` | 0.1.22 | | change | 轮播切换时触发 | `(current: number, source: 'autoplay' \| 'touch' \| 'nav') ` | 0.1.22 | ## Slot | name | 说明 | 参数 | 最低版本 | | --------- | ------------ | ------------------------------------ | -------- | | indicator | 自定义指示器 | `{ current: number, total: number }` | 0.1.22 | ## 外部样式类 | 类名 | 说明 | 最低版本 | | -------------------- | -------------------- | -------- | | customClass | 外部自定义类名 | 0.1.22 | | customIndicatorClass | 自定义指示器类名 | 0.1.22 | | customImageClass | 自定义图片类名，1.3版本将废弃，请使用`customItemClass`代替 | 0.1.22 | | customPrevImageClass | 自定义上一个图片类名，1.3版本将废弃，请使用`customPrevClass`代替 | 0.1.22 | | customNextImageClass | 自定义下一个图片类名，1.3版本将废弃，请使用`customNextClass`代替 | 0.1.22 | | customItemClass | 自定义子项类名 | 1.3.13 | | customPrevClass | 自定义上一个子项类名 | 1.3.13 | | customNextClass | 自定义下一个子项类名 | 1.3.13 | | customTextClass | 自定义文字标题类名 | 1.3.13 | | customTextStyle | 自定义文字标题样式 | 1.3.13 | --- --- url: 'https://wot-design-uni.cn/component/switch.md' --- # Switch 开关 用来打开或关闭选项。 ## 基本用法 `v-model` 为绑定值，默认为 boolean 类型。 ```html ``` ```typescript const checked = ref(true) ``` ## 修改值 通过 `active-value` 属性修改开关打开时的值，`inactive-value` 属性修改开关关闭时的值。 ```html ``` ## 修改颜色 通过 `active-color` 属性修改开关打开时的颜色，`inactive-color` 属性修改开关关闭时的颜色。 ```html ``` ## 自定义大小 设置 `size` 修改开关大小。 ```html ``` ## 禁用 设置 `disabled` 属性。 ## 修改前钩子 设置 `before-change` 属性，修改前钩子，接收 { value, resolve } 参数，`resolve(true)` 表示修改通过，`resolve(false)` 表示不修改。 ```html ``` ```typescript import { useMessage } from '@/uni_modules/wot-design-uni' const message = useMessage() const beforeChange = ({ value, resolve }) => { message .confirm('是否切换开关') .then(() => { resolve(true) }) .catch(() => { resolve(false) }) } ``` ## Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | |-----|------|-----|-------|-------|---------| | v-model | 绑定值 | boolean / string / number | - | - | - | | disabled | 禁用 | boolean | - | false | - | | active-value | 打开时的值 | boolean / string / number | - | true | - | | inactive-value | 关闭时的值 | boolean / string / number | - | false | - | | active-color | 打开时的背景色 | string | - | #4D80F0 | - | | inactive-color | 关闭时的背景色，默认为白色，所以有灰色边框，如果设置了该值，则会自动去除灰色边框 | string | - | #fff | - | | size | 开关大小，可以为任何单位的字符串尺寸 | string/number | - | 28px | - | | before-change | 修改前钩子 | function | - | - | - | ## Events | 事件名称 | 说明 | 参数 | 最低版本 | |--------|------|-----|---------| | change | 值修改事件 | `{ value }` | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | |-----|-----|---------| | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/tabs.md' --- # Tab 标签页 标签页组件，用于在不同的内容区域之间进行切换。 ## 基本用法 `v-model` 为绑定值，可以为 number 类型（选中的 tab 的下标）和 string 类型（标签名）。 :::tip 提示 当`v-model`为`number`类型时，`wd-tab`可以不必设置`name`。同时如果 value 超出了 tab 数量，会用 0 自动兜底。 ::: ```html 内容{{ item}} ``` ```typescript const tab = ref(0) ``` ```scss .content { line-height: 120px; text-align: center; } ``` ## name 匹配 为`wd-tab`设置`name`作为唯一标识。 ```html 内容{{ item }} ``` ```typescript const tabs = ref(['这', '是', '一', '个', '例子']) const tab = ref('例子') ``` ```scss .content { line-height: 120px; text-align: center; } ``` ## 使用徽标1.4.0 使用`bage-props`设置徽标属性，可以参考[Badge 组件的 props](/component/badge#attributes)。 ```html {{ item.title }}徽标 ``` ```typescript const tabWithBadge = ref(0) const tabsWithBadge = ref([ { title: '普通数值', badgeProps: { modelValue: 10, right: '-8px' } }, { title: '最大值', badgeProps: { modelValue: 100, max: 99, right: '-8px' } }, { title: '点状', badgeProps: { isDot: true, right: '-8px', showZero: true } } ]) ``` ## 自动调整底部条宽度 设置 `auto-line-width` 属性，自动调整底部条宽度为文本内容宽度。 ```html 内容{{ tab }} ``` ```typescript const tabs = ref(['Wot', 'Design', 'Uni']) const tab = ref('Design') ``` ## 粘性布局 设置 `sticky` 属性，使用粘性布局。可以设置 `offset-top` 属性，当距离窗口顶部多少像素时，固定标签头。在`H5`端使用自定义导航栏时需要参考[sticky 的吸顶距离](/component/sticky.html#吸顶距离)进行配置。 ```html 内容{{ item}} ``` ## 禁用 Tab 在 `wd-tab` 上设置 `disabled` 属性，禁用某个页签。 ```html 内容{{ item }} ``` ## 点击事件 监听页签的点击事件. ```html 内容{{ item }} ``` ## 手势滑动 设置 `swipeable` 属性，支持手势滑动。 ```html 内容{{ item }} ``` ## 切换动画 设置 `animated` 属性，开启切换标签内容时的过渡动画。 ```html 内容{{ item }} ``` ## 左对齐超出即可滚动 1.4.0 `slidable`设置为`always`时，所有的标签会向左侧收缩对齐，超出即可滑动。 ```html 内容{{ item }} ``` *** 标签页在标签数大于等于 6 个时，可以滑动；当标签数大于等于 10 个时，将会显示导航地图，便于快速定位到某个标签。可以通过设置 `slidable-num` 修改可滑动的数量阈值；设置 `map-num` 修改显示导航地图的阈值。`slidable`设置为`always`时，所有的标签会向左侧收缩对齐，超出即可滑动。 ## 在弹出框中使用 微信小程序端，在弹出框中使用本组件时，需要调用 `updateLineStyle` 方法更新激活项样式，参见[常见问题](/guide/common-problems.html#%E4%B8%BA%E4%BB%80%E4%B9%88%E5%9C%A8%E5%BE%AE%E4%BF%A1%E5%B0%8F%E7%A8%8B%E5%BA%8F%E4%B8%8A%E4%BD%BF%E7%94%A8popup%E3%80%81actionsheet%E3%80%81dropdownitem%E7%AD%89%E5%BC%B9%E5%87%BA%E6%A1%86%E7%BB%84%E4%BB%B6%E5%8C%85%E8%A3%B9slider%E3%80%81tabs%E7%AD%89%E7%BB%84%E4%BB%B6%E6%97%B6-slider%E3%80%81tabs%E8%A1%A8%E7%8E%B0%E5%BC%82%E5%B8%B8)。 ```html 打开弹窗 在弹出框中使用 内容{{ tab }} ``` ```ts const tab = ref(3) const tabs = ref(['这', '是', '一', '个', '例子']) const showPopup = ref(false) // 控制popup显示 const tabsRef = ref() // 获取分段器实例 /** * 点击按钮打开popup */ function handleOpenClick() { showPopup.value = true } /** * popup打开后更新分段器样式 */ function handlePopupShow() { tabsRef.value?.updateLineStyle(false) } ``` ```css .title { display: flex; font-size: 32rpx; align-items: center; justify-content: center; padding: 24rpx 0; } ``` ## Tabs Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | ------------- | ---------------------------------------------------------------------------------------- | --------------- | -------- | ------ | -------- | | v-model | 绑定值 | string / number | - | - | - | | slidable-num | 可滑动的标签数阈值，`slidable`设置为`auto`时生效 | number | - | 6 | - | | map-num | 显示导航地图的标签数阈值 | number | - | 10 | - | | map-title | 导航地图标题 | string | - | - | 1.4.0 | | sticky | 粘性布局 | boolean | - | false | - | | offset-top | 粘性布局时距离窗口顶部距离 | number | - | 0 | - | | swipeable | 开启手势滑动 | boolean | - | false | - | | autoLineWidth | 底部条宽度跟随文字，指定`lineWidth`时此选项不生效 | boolean | - | false | 1.4.0 | | lineWidth | 底部条宽度，单位像素 | number | - | 19 | - | | lineHeight | 底部条高度，单位像素 | number | - | 3 | - | | color | 文字颜色 | string | - | - | - | | inactiveColor | 非活动标签文字颜色 | string | - | - | - | | animated | 是否开启切换标签内容时的转场动画 | boolean | - | false | - | | duration | 切换动画过渡时间，单位毫秒 | number | - | 300 | - | | slidable | 是否开启滚动导航 | TabsSlidable | `always` | `auto` | 1.4.0 | | badge-props | 自定义徽标的属性，传入的对象会被透传给 [Badge 组件的 props](/component/badge#attributes) | BadgeProps | - | - | 1.4.0 | ## Tab Attributes | 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 | | -------- | ------------------------------------------------------- | ------- | ------ | ------ | -------- | | name | 标签页名称 | string | - | - | - | | title | 标题 | string | - | - | - | | disabled | 禁用 | boolean | - | false | - | | lazy | 延迟渲染，默认开启，开启`animated`后此选项始终为`false` | boolean | - | true | 1.4.0 | ## Tabs Events | 事件名称 | 说明 | 参数 | 最低版本 | | -------- | -------------------- | --------------------------------------------------------------- | -------- | | change | 绑定值变化时触发 | event = { index, name },index 为 tab 下标，name 为 tab 绑定的值 | - | | click | 点击标题时触发 | event = { index, name },index 为 tab 下标，name 为 tab 绑定的值 | - | | disabled | 点击禁用的标题时触发 | event = { index, name },index 为 tab 下标，name 为 tab 绑定的值 | - | ## Methods 对外暴露函数 | 事件名称 | 说明 | 参数 | 最低版本 | | --------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------- | | setActive | 设置激活项，参数分别为：`value` 激活值，`init` 是否已初始化 ，`setScroll` 是否设置 scroll-view 滚动 | `(value: number \| string, init: boolean, setScroll: boolean) => void` | - | | scrollIntoView | 使选中项滚动到可视区域 | - | - | | updateLineStyle | 更新激活项边框线样式，参数`animation`用于是否开启动画，默认开启 | `(animation: boolean) => void` | - | ## 外部样式类 | 类名 | 说明 | 最低版本 | | ------------ | ---------- | -------- | | custom-class | 根节点样式 | - | --- --- url: 'https://wot-design-uni.cn/component/tabbar.md' --- # Tabbar 标签栏 底部导航栏，用于在不同页面之间进行切换。 ## 基础用法 `v-model` 为绑定值，表示选中标签的索引值或者名称。 ```html ``` ```typescript import { ref } from 'vue' const tabbar = ref(1) ``` ## 通过名称匹配 通过设置 `name` 属性，可以通过名称匹配选中标签。 ```html ``` ```typescript import { ref } from 'vue' const tabbar = ref('home') ``` ## 徽标提示 通过设置 `value` 属性，可以显示徽标提示，而设置 is-dot 属性后，会在图标右上角展示一个小红点。 ```html ``` ```typescript import { ref } from 'vue' const tabbar = ref(1) ``` ## 悬浮标签栏 通过设置 `shape` 属性为 `round`，可以将标签栏设置为悬浮样式。 ```html ``` ```typescript import { ref } from 'vue' const tabbar = ref(1) ``` ## 自定义图标 通过使用 `