feat: 组件props增加注释说明

组件props增加注释说明, 优化emits验证, 优化 props 定义

link #100

.markdownlint.json

@@ -9,4 +9,4 @@
   "MD036": false,
   "MD041": false,
   "MD050": false
-}
+}

docs/auto-imports.d.ts

@@ -61,7 +61,7 @@ declare global {
 // for type re-export
 declare global {
   // @ts-ignore
-  export type { Component, ComponentPublicInstance, ComputedRef, InjectionKey, PropType, Ref, VNode } from 'vue'
+  export type { Component, ComponentPublicInstance, ComputedRef, ExtractDefaultPropTypes, ExtractPropTypes, ExtractPublicPropTypes, InjectionKey, PropType, Ref, VNode, WritableComputedRef } from 'vue'
 }
 // for vue template auto import
 import { UnwrapRef } from 'vue'

docs/components/business/address.md

@@ -568,8 +568,8 @@
 | change | 自定义选择地址时，选择地区时触发 |  参考 `onChange` |
 | selected | 选择已有地址列表时触发 | 参考 `selected` |
 | close | 地址选择弹框关闭时触发 | 参考 `close` |
-| close-mask |点击遮罩层或点击右上角叉号关闭时触发 | {closeWay:'mask'/'cross'} |
-| switch-module | 点击‘选择其他地址’或自定义地址选择左上角返回按钮触发 | {type:'exist'/'custom'/'custom2'} |
+| close-mask |点击遮罩层或点击右上角叉号关闭时触发 | `{closeWay:'mask'/'cross'}` |
+| switch-module | 点击‘选择其他地址’或自定义地址选择左上角返回按钮触发 | `{type:'exist'/'custom'/'custom2'}` |
 
 ### change 回调参数
 

example/src/manifest.json

@@ -1 +1 @@
-{"name":"NutUi","appid":"__UNI__D989E4B","description":"","versionName":"1.0.0","versionCode":"100","transformPx":false,"app-plus":{"usingComponents":true,"nvueStyleCompiler":"uni-app","compilerVersion":3,"splashscreen":{"alwaysShowBeforeRender":true,"waiting":true,"autoclose":true,"delay":0},"modules":{},"distribute":{"android":{"permissions":[]},"ios":{"dSYMs":false},"sdkConfigs":{"ad":{}}},"darkmode":true},"quickapp":{},"mp-weixin":{"appid":"wxd4e6c25454525507","setting":{"urlCheck":false,"es6":true,"minified":true,"postcss":true},"usingComponents":true,"lazyCodeLoading":"requiredComponents","darkmode":true,"themeLocation":"theme.json"},"mp-alipay":{"usingComponents":true,"appid":"wxd4e6c25454525507","setting":{"urlCheck":false,"es6":true,"minified":true,"postcss":true},"lazyCodeLoading":"requiredComponents","darkmode":true,"themeLocation":"theme.json"},"mp-baidu":{"usingComponents":true},"mp-toutiao":{"usingComponents":true},"uniStatistics":{"enable":false},"vueVersion":"3","h5":{"darkmode":true,"themeLocation":"theme.json"}}
+{ "name": "NutUi", "appid": "__UNI__D989E4B", "description": "", "versionName": "1.0.0", "versionCode": "100", "transformPx": false, "app-plus": { "usingComponents": true, "nvueStyleCompiler": "uni-app", "compilerVersion": 3, "splashscreen": { "alwaysShowBeforeRender": true, "waiting": true, "autoclose": true, "delay": 0 }, "modules": {}, "distribute": { "android": { "permissions": [] }, "ios": { "dSYMs": false }, "sdkConfigs": { "ad": {} } }, "darkmode": true }, "quickapp": {}, "mp-weixin": { "appid": "wxd4e6c25454525507", "setting": { "urlCheck": false, "es6": true, "minified": true, "postcss": true }, "usingComponents": true, "lazyCodeLoading": "requiredComponents", "darkmode": true, "themeLocation": "theme.json" }, "mp-alipay": { "usingComponents": true, "appid": "wxd4e6c25454525507", "setting": { "urlCheck": false, "es6": true, "minified": true, "postcss": true }, "lazyCodeLoading": "requiredComponents", "darkmode": true, "themeLocation": "theme.json" }, "mp-baidu": { "usingComponents": true }, "mp-toutiao": { "usingComponents": true }, "uniStatistics": { "enable": false }, "vueVersion": "3", "h5": { "darkmode": true, "themeLocation": "theme.json" } }

example/src/pages/demo/business/address/index.vue

@@ -1,18 +1,13 @@
 <script lang="ts">
 import { defineComponent, reactive, ref, toRefs } from 'vue'
+import type { AddressExistRegionData, AddressRegionData, AddressType } from 'nutui-uniapp'
 
 /* eslint-disable no-console */
-
 interface CalBack {
   next?: string
-  value?: RegionData
+  value?: AddressRegionData
   custom: string
 }
-interface RegionData {
-  name: string
-  id: any
-  [key: string]: any
-}
 interface CalResult {
   type: string
   data: AddressResult
@@ -173,7 +168,7 @@ export default defineComponent({
         text.two = val.data.addressStr
       }
     }
-    const selected = (prevExistAdd: AddressList, nowExistAdd: RegionData, _arr: AddressList[]) => {
+    const selected = (prevExistAdd: AddressExistRegionData, nowExistAdd: AddressExistRegionData, _arr: AddressExistRegionData[]) => {
       console.log(prevExistAdd)
       console.log(nowExistAdd)
     }
@@ -207,14 +202,16 @@ export default defineComponent({
       }
     }
 
-    const switchModule = (val: CalResult) => {
+    const switchModule = (val: { type: AddressType }) => {
       if (val.type === 'custom')
         console.log('点击了“选择其他地址”按钮')
       else
         console.log('点击了自定义地址左上角的返回按钮')
     }
 
-    const closeMask = (val: CalResult) => {
+    const closeMask = (val: {
+      closeWay: 'self' | 'mask' | 'cross'
+    }) => {
       console.log('关闭弹层', val)
     }
 
@@ -262,7 +259,7 @@ export default defineComponent({
       :city="address.city"
       :country="address.country"
       :town="address.town"
-      @change="(cal: CalBack) => onChange(cal, 'normal')"
+      @change="(cal) => onChange(cal, 'normal')"
       @close="close1"
     />
 
@@ -362,7 +359,7 @@ export default defineComponent({
       :country="address.country"
       :town="address.town"
       :back-btn-icon="backBtnIcon"
-      @change="(cal: CalBack) => onChange(cal, 'other')"
+      @change="(cal) => onChange(cal, 'other')"
       @close="close4"
       @selected="selected"
       @switch-module="switchModule"

packages/nutui/components/_constants/event.ts

@@ -0,0 +1,18 @@
+export const UPDATE_MODEL_EVENT = 'update:modelValue'
+export const UPDATE_VISIBLE_EVENT = 'update:visible'
+export const CHANGE_EVENT = 'change'
+export const INPUT_EVENT = 'input'
+export const CLICK_EVENT = 'click'
+export const OPEN_EVENT = 'open'
+export const CLOSE_EVENT = 'close'
+export const OPENED_EVENT = 'opened'
+export const CLOSED_EVENT = 'closed'
+export const FOCUS_EVENT = 'focus'
+export const BLUR_EVENT = 'blur'
+export const CONFIRM_EVENT = 'confirm'
+export const SEARCH_EVENT = 'search'
+export const CLEAR_EVENT = 'clear'
+export const CANCEL_EVENT = 'cancel'
+export const CHOOSE_EVENT = 'choose'
+export const SELECT_EVENT = 'select'
+export const SELECTED_EVENT = 'selected'

packages/nutui/components/_constants/index.ts

@@ -1,3 +1,4 @@
 export * from './prefix'
 export * from './types'
 export * from './id'
+export * from './event'

packages/nutui/components/_utils/props.ts

@@ -28,6 +28,13 @@ export function makeArrayProp<T>(defaultVal: T[] = []) {
   }
 }
 
+export function makeObjectProp<T>(defaultVal: T) {
+  return {
+    type: Object as PropType<T>,
+    default: () => defaultVal,
+  }
+}
+
 export function makeNumberProp<T>(defaultVal: T) {
   return {
     type: Number,
@@ -52,10 +59,16 @@ export function makeStringProp<T>(defaultVal: T) {
 export type ClassType = string | object | Array<ClassType>
 
 export const commonProps = {
+  /**
+   * @description 自定义类名
+   */
   customClass: {
     type: [String, Object, Array] as PropType<ClassType>,
     default: '',
   },
+  /**
+   * @description 自定义样式
+   */
   customStyle: {
     type: [String, Object, Array] as PropType<StyleValue>,
     default: '',

packages/nutui/components/actionsheet/actionsheet.ts

@@ -1,6 +1,7 @@
-import type { ExtractPropTypes, PropType } from 'vue'
+import type { ExtractPropTypes } from 'vue'
 import { popupProps } from '../popup/popup'
-import { isBoolean } from '../_utils'
+import { isBoolean, isNumber, makeArrayProp, makeStringProp, truthProp } from '../_utils'
+import { CANCEL_EVENT, CHOOSE_EVENT, CLOSE_EVENT, UPDATE_VISIBLE_EVENT } from '../_constants'
 
 export interface ActionSheetOption {
   disable?: boolean
@@ -11,56 +12,51 @@ export interface ActionSheetOption {
 }
 export const actionsheetProps = {
   ...popupProps,
-  cancelTxt: {
-    type: String,
-    default: '',
-  },
-  optionTag: {
-    type: String as PropType<keyof ActionSheetOption>,
-    default: 'name',
-  },
-  optionSubTag: {
-    type: String as PropType<keyof ActionSheetOption>,
-    default: 'subname',
-  },
-  chooseTagValue: {
-    type: String,
-    default: '',
-  },
-  title: {
-    type: String,
-    default: '',
-  },
-  customColor: {
-    type: String,
-    default: '#ee0a24',
-  },
-  description: {
-    type: String,
-    default: '',
-  },
-  menuItems: {
-    type: Array as PropType<ActionSheetOption[]>,
-    default: () => [],
-  },
-  closeAbled: {
-    type: Boolean,
-    default: true,
-  },
+  /**
+   * @description 取消文案
+   */
+  cancelTxt: makeStringProp(''),
+  /**
+   * @description 设置列表项标题展示使用参数
+   */
+  optionTag: makeStringProp<keyof ActionSheetOption>('name'),
+  /**
+   * @description 设置列表项二级标题展示使用参数
+   */
+  optionSubTag: makeStringProp<keyof ActionSheetOption>('subname'),
+  /**
+   * @description 设置选中项的值，和 'option-tag' 的值对应
+   */
+  chooseTagValue: makeStringProp(''),
+  /**
+   * @description 设置列表项标题
+   */
+  title: makeStringProp(''),
+  /**
+   * @description 选中项颜色，当 choose-tag-value == option-tag 的值 生效
+   */
+  customColor: makeStringProp('#ee0a24'),
+  /**
+   * @description 设置列表项副标题/描述
+   */
+  description: makeStringProp(''),
+  /**
+   * @description 列表项
+   */
+  menuItems: makeArrayProp<ActionSheetOption>([]),
+  /**
+   * @description 遮罩层是否可关闭
+   */
+  closeAbled: truthProp,
 }
 
 export type ActionsheetProps = ExtractPropTypes<typeof actionsheetProps>
 
 export const actionsheetEmits = {
-  'close': () => true,
-  'update:visible': (val: boolean) => isBoolean(val),
-  'cancel': () => true,
-  'choose': (item: ActionSheetOption, index: any) => {
-    return {
-      item,
-      index,
-    }
-  },
+  [CLOSE_EVENT]: () => true,
+  [UPDATE_VISIBLE_EVENT]: (val: boolean) => isBoolean(val),
+  [CANCEL_EVENT]: () => true,
+  [CHOOSE_EVENT]: (item: ActionSheetOption, index: number) => item instanceof Object && isNumber(index),
 
 }
 

packages/nutui/components/actionsheet/actionsheet.vue

@@ -2,7 +2,7 @@
 import { computed, defineComponent, useSlots } from 'vue'
 import NutPopup from '../popup/popup.vue'
 import NutIcon from '../icon/icon.vue'
-import { PREFIX } from '../_constants'
+import { CANCEL_EVENT, CHOOSE_EVENT, CLOSE_EVENT, PREFIX, UPDATE_VISIBLE_EVENT } from '../_constants'
 import { type ActionSheetOption, actionsheetEmits, actionsheetProps } from './actionsheet'
 
 const props = defineProps(actionsheetProps)
@@ -21,21 +21,21 @@ function isHighlight(item: ActionSheetOption) {
 }
 
 function cancelActionSheet() {
-  emit('cancel')
-  emit('update:visible', false)
+  emit(CANCEL_EVENT)
+  emit(UPDATE_VISIBLE_EVENT, false)
 }
 
 function chooseItem(item: ActionSheetOption, index: any) {
   if (!item.disable && !item.loading) {
-    emit('choose', item, index)
-    emit('update:visible', false)
+    emit(CHOOSE_EVENT, item, index)
+    emit(UPDATE_VISIBLE_EVENT, false)
   }
 }
 
 function close() {
   if (props.closeAbled) {
-    emit('close')
-    emit('update:visible', false)
+    emit(CLOSE_EVENT)
+    emit(UPDATE_VISIBLE_EVENT, false)
   }
 }
 </script>