@antsoo-lib/components 0.1.2 → 0.1.4

package/src/form/index.zh-CN.md

@@ -0,0 +1,253 @@
+---
+category: Components
+subtitle: 表单
+type: 数据录入
+cols: 1
+title: Form
+cover: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*-lcdS5Qm1bsAAAAAAAAAAAAADrJ8AQ/original
+coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*ylFATY6w-ygAAAAAAAAAAAAADrJ8AQ/original
+---
+
+高性能表单控件，自带数据域管理。包含数据录入、校验以及对应样式。
+
+## 何时使用
+
+- 用于创建一个实体或收集信息。
+- 需要对输入的数据类型进行校验时。
+
+## 表单
+
+我们为 `form` 提供了以下三种排列方式：
+
+- 水平排列：标签和表单控件水平排列；（默认）
+- 垂直排列：标签和表单控件上下垂直排列；
+- 行内排列：表单项水平行内排列。
+
+## 表单域
+
+表单一定会包含表单域，表单域可以是输入控件，标准表单域，标签，下拉菜单，文本域等。
+
+## API
+
+### Form
+
+| 参数                 | 说明                                                                                                                | 类型                                                                                 | 默认值       | 版本  |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------ | ----- |
+| colon                | 配置 Form.Item 的 colon 的默认值 (只有在属性 layout 为 horizontal 时有效)                                           | boolean                                                                              | true         |       |
+| disabled             | 设置表单组件禁用，仅对 antdv 组件有效                                                                               | boolean                                                                              | false        | 4.0   |
+| hideRequiredMark     | 隐藏所有表单项的必选标记                                                                                            | Boolean                                                                              | false        |       |
+| labelAlign           | label 标签的文本对齐方式                                                                                            | 'left' \| 'right'                                                                    | 'right'      |       |
+| labelCol             | label 标签布局，同 `<Col>` 组件，设置 `span` `offset` 值，如 `{span: 3, offset: 12}` 或 `sm: {span: 3, offset: 12}` | [object](/components/grid-cn/#col)                                                   |              |       |
+| labelWrap            | label 标签的文本换行方式                                                                                            | boolean                                                                              | false        | 3.0   |
+| layout               | 表单布局                                                                                                            | 'horizontal'\|'vertical'\|'inline'                                                   | 'horizontal' |       |
+| model                | 表单数据对象                                                                                                        | object                                                                               |              |       |
+| name                 | 表单名称，会作为表单字段 `id` 前缀使用                                                                              | string                                                                               | -            | 2.0.0 |
+| noStyle              | 为 `true` 时不带样式，作为纯字段控件使用                                                                            | boolean                                                                              | false        | 3.0   |
+| rules                | 表单验证规则                                                                                                        | object                                                                               |              |       |
+| scrollToFirstError   | 提交失败自动滚动到第一个错误字段                                                                                    | boolean \| [options](https://github.com/stipsan/scroll-into-view-if-needed/#options) | false        | 2.0.0 |
+| validateOnRuleChange | 是否在 rules 属性改变后立即触发一次验证                                                                             | boolean                                                                              | true         |       |
+| validateTrigger      | 统一设置字段校验规则                                                                                                | string \| string\[]                                                                  | `change`     | 2.0.0 |
+| wrapperCol           | 需要为输入控件设置布局样式时，使用该属性，用法同 labelCol                                                           | [object](/components/grid-cn/#col)                                                   |              |       |
+
+### 事件
+
+| 事件名称     | 说明                             | 回调参数                                     | 版本 |       |
+| ------------ | -------------------------------- | -------------------------------------------- | ---- | ----- |
+| finish       | 提交表单且数据验证成功后回调事件 | function(values)                             | -    | 2.0.0 |
+| finishFailed | 提交表单且数据验证失败后回调事件 | function({ values, errorFields, outOfDate }) | -    | 2.0.0 |
+| submit       | 数据验证成功后回调事件           | Function(e:Event)                            | ｜   |       |
+| validate     | 任一表单项被校验后触发           | Function(name, status, errorMsgs)            |      |       |
+
+### 方法
+
+| 方法名         | 说明                                                                                                     | 参数                                                                                                                                                                            | 版本 |
+| -------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
+| clearValidate  | 移除表单项的校验结果。传入待移除的表单项的 name 属性或者 name 组成的数组，如不传则移除整个表单的校验结果 | (nameList?: [NamePath](#namepath)\[]) => void                                                                                                                                   |      |
+| resetFields    | 对整个表单进行重置，将所有字段值重置为初始值并移除校验结果                                               | (nameList?: [NamePath](#namepath)\[]) => void                                                                                                                                   |      |
+| scrollToField  | 滚动到对应字段位置                                                                                       | (name: [NamePath](#namepath), options: \[[ScrollOptions](https://github.com/stipsan/scroll-into-view-if-needed/tree/ece40bd9143f48caf4b99503425ecb16b0ad8249#options)]) => void |      |
+| validate       | 触发表单验证, 同 validateFields                                                                          | (nameList?: [NamePath](#namepath)\[]) => Promise                                                                                                                                |      |
+| validateFields | 触发表单验证                                                                                             | (nameList?: [NamePath](#namepath)\[]) => Promise                                                                                                                                |      |
+
+#### NamePath
+
+`string | number | (string | number)[]`
+
+### Form.Item
+
+| 参数            | 说明                                                                                                                | 类型                               | 默认值   | 版本  |
+| --------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------- | ----- |
+| autoLink        | 是否自动关联表单域，对于大部分情况都可以使用自动关联，如果不满足自动关联的条件，可以手动关联，参见下方注意事项      | boolean                            | true     |       |
+| colon           | 配合 label 属性使用，表示是否显示 label 后面的冒号                                                                  | boolean                            | true     |       |
+| extra           | 额外的提示信息，和 help 类似，当需要错误信息和提示文案同时出现时，可以使用这个。                                    | string\|slot                       |          |       |
+| hasFeedback     | 配合 validateStatus 属性使用，展示校验状态图标，建议只配合 Input 组件使用                                           | boolean                            | false    |       |
+| help            | 提示信息，如不设置，则会根据校验规则自动生成                                                                        | string\|slot                       |          |       |
+| htmlFor         | 设置子元素 label `htmlFor` 属性                                                                                     | string                             |          |       |
+| label           | label 标签的文本                                                                                                    | string\|slot                       |          |       |
+| labelAlign      | 标签文本对齐方式                                                                                                    | 'left' \| 'right'                  | 'right'  |       |
+| labelCol        | label 标签布局，同 `<Col>` 组件，设置 `span` `offset` 值，如 `{span: 3, offset: 12}` 或 `sm: {span: 3, offset: 12}` | [object](/components/grid-cn/#col) |          |       |
+| name            | 表单域 model 字段，在使用 validate、resetFields 方法的情况下，该属性是必填的                                        | [NamePath](#namepath)              |          |       |
+| required        | 是否必填，如不设置，则会根据校验规则自动生成                                                                        | boolean                            | false    |       |
+| rules           | 表单验证规则                                                                                                        | object \| array                    |          |       |
+| tooltip         | 配置提示信息                                                                                                        | string \| slot                     |          | 4.0.4 |
+| validateFirst   | 当某一规则校验不通过时，是否停止剩下的规则的校验。                                                                  | boolean                            | false    | 2.0.0 |
+| validateStatus  | 校验状态，如不设置，则会根据校验规则自动生成，可选：'success' 'warning' 'error' 'validating'                        | string                             |          |       |
+| validateTrigger | 设置字段校验的时机                                                                                                  | string \| string\[]                | `change` | 2.0.0 |
+| wrapperCol      | 需要为输入控件设置布局样式时，使用该属性，用法同 labelCol                                                           | [object](/components/grid-cn/#col) |          |       |
+
+### 注意：
+
+#### 3.x
+
+自 3.0 版本以后，Form.Item 不再劫持子元素，而是通过 provider / inject 依赖注入的方式进行自动校验，这种方式可以提高组件性能，子元素也不会限制个数，同样子元素也可以是进一步封装的高级组件。你可以参考[自定义表单控件示例](#components-form-demo-customized-form-controls)
+
+但它同样会有一些缺点：
+
+1、自定义组件如果希望 Form.Item 进行校验展示，你需要 `const {id, onFieldChange, onFieldBlur} = useInjectFormItemContext()` 注入，并调用相应的方法。
+
+2、一个 Form.Item 只能收集一个表单项的数据，如果有多个表单项，会导致收集错乱，例如，
+
+```html
+<a-form-item>
+  <a-input name="a"></a-input>
+  <a-input name="b"></a-input>
+</a-form-item>
+```
+
+如上 Form.Item 并不知道需要收集 `name="a"` 还是 `name="b"`，你可以通过如下三种方式去解决此类问题：
+
+第一种，使用多个 `a-form-item`:
+
+```html
+<a-form-item>
+  <a-input name="a"></a-input>
+  <a-form-item><a-input name="b"></a-input></a-form-item>
+</a-form-item>
+```
+
+第二种，使用自定义组件包裹，并在自定义组件中调用 `useInjectFormItemContext`，相当于把多个表单项合并成了一个
+
+```html
+<script>
+  // 自定义组件
+  import { Form } from 'ant-design-vue'
+
+  export default {
+    setup() {
+      const formItemContext = Form.useInjectFormItemContext()
+    },
+  }
+</script>
+```
+
+```html
+<a-form-item>
+  <custom-com>
+    <a-input name="a"></a-input>
+    <a-input name="b"></a-input>
+  </custom-com>
+</a-form-item>
+```
+
+第三种，组件库提供了一个 `a-form-item-rest` 组件，它会阻止数据的收集，你可以将不需要收集校验的表单项放到这个组件中即可，它和第一种方式很类似，但它不会产生额外的 dom 节点。
+
+```html
+<a-form-item>
+  <a-input name="a"></a-input>
+  <a-form-item-rest><a-input name="b"></a-input></a-form-item-rest>
+</a-form-item>
+```
+
+#### 2.x
+
+Form.Item 会对唯一子元素进行劫持，并监听 `blur` 和 `change` 事件，来达到自动校验的目的，所以请确保表单域没有其它元素包裹。如果有多个子元素，将只会监听第一个子元素的变化。
+
+如果要监听的表单域不满足自动监听的条件，可以通过如下方式关联表单域：
+
+```html
+<a-form-item name="form.name" ref="name" :autoLink="false">
+  <a-input v-model:value="other" />
+  <span>hahha</span>
+  <div>
+    <a-input
+      v-model:value="form.name"
+      @blur="() => {$refs.name.onFieldBlur()}"
+      @change="() => {$refs.name.onFieldChange()}"
+    />
+  </div>
+</a-form-item>
+```
+
+### 校验规则
+
+| 参数       | 说明                                                                                            | 类型                                       | 默认值   |
+| ---------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------ | -------- |
+| enum       | 枚举类型                                                                                        | string                                     | -        |
+| len        | 字段长度                                                                                        | number                                     | -        |
+| max        | 最大长度                                                                                        | number                                     | -        |
+| message    | 校验文案                                                                                        | string                                     | -        |
+| min        | 最小长度                                                                                        | number                                     | -        |
+| pattern    | 正则表达式校验                                                                                  | RegExp                                     | -        |
+| required   | 是否必选                                                                                        | boolean                                    | `false`  |
+| transform  | 校验前转换字段值                                                                                | function(value) => transformedValue:any    | -        |
+| trigger    | 校验触发的时机                                                                                  | 'blur' \| 'change' \| `['change', 'blur']` | -        |
+| type       | 内建校验类型，[可选项](https://github.com/yiminghe/async-validator#type)                        | string                                     | 'string' |
+| validator  | 自定义校验（注意，[callback 必须被调用](https://github.com/ant-design/ant-design/issues/5155)） | function(rule, value, callback)            | -        |
+| whitespace | 必选时，空格是否会被视为错误                                                                    | boolean                                    | `false`  |
+
+更多高级用法可研究 [async-validator](https://github.com/yiminghe/async-validator)。
+
+### useForm (v2.2)
+
+`useForm` 是一个可以独立 Form 组件运行的方法，它使用 Vue 响应式机制进行数据的监听和校验，并将校验结果返回，你可以将校验结果绑定到任何组件上，`Form.Item` 也仅仅是将结果展示。
+
+2.2 以下版本需要需要 @ant-design-vue/use 库单独提供，不建议继续使用，你应该尽快升级到 2.2+ 版本
+
+```ts
+import { Form } from 'ant-design-vue'
+
+const useForm = Form.useForm
+
+useForm(modelRef, ruleRef, [options])
+```
+
+参数说明：
+
+```ts
+/*
+ `modelRef`, `ruleRef` 必须是响应式数据
+*/
+
+interface Props {
+  [key: string]: any
+}
+function useForm(
+  modelRef: Props | Ref<Props>,
+  rulesRef?: Props | Ref<Props>,
+  options?: {
+    immediate?: boolean
+    deep?: boolean
+    validateOnRuleChange?: boolean
+    debounce?: DebounceSettings
+  },
+): {
+  modelRef: Props | Ref<Props>
+  rulesRef: Props | Ref<Props>
+  initialModel: Props
+  validateInfos: validateInfos
+  resetFields: (newValues?: Props) => void
+  validate: <T = any>(names?: namesType, option?: validateOptions) => Promise<T>
+  validateField: (
+    name?: string,
+    value?: any,
+    rules?: [Record<string, unknown>],
+    option?: validateOptions,
+  ) => Promise<RuleError[]>
+  mergeValidateInfo: (items: ValidateInfo | ValidateInfo[]) => ValidateInfo
+  clearValidate: (names?: namesType) => void
+  onValidate?: (
+    name: string | number | string[] | number[],
+    status: boolean,
+    errorMsgs: string[] | null,
+  ) => void
+}
+```

package/src/form/interface.ts

@@ -0,0 +1,227 @@
+import type { VueNode } from '../_util/type'
+
+export type FormLabelAlign = 'left' | 'right'
+
+export type InternalNamePath = (string | number)[]
+export type NamePath = string | number | InternalNamePath
+
+export type StoreValue = any
+export interface Store {
+  [name: string]: StoreValue
+}
+
+export interface Meta {
+  touched: boolean
+  validating: boolean
+  errors: string[]
+  name: InternalNamePath
+}
+
+export interface InternalFieldData extends Meta {
+  value: StoreValue
+}
+
+/**
+ * Used by `setFields` config
+ */
+export interface FieldData extends Partial<Omit<InternalFieldData, 'name'>> {
+  name: NamePath
+}
+
+export type RuleType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'method'
+  | 'regexp'
+  | 'integer'
+  | 'float'
+  | 'object'
+  | 'enum'
+  | 'date'
+  | 'url'
+  | 'hex'
+  | 'email'
+
+type Validator = (
+  rule: RuleObject,
+  value: StoreValue,
+  callback: (error?: string) => void,
+) => Promise<void> | void
+
+export interface ValidatorRule {
+  warningOnly?: boolean
+  message?: string | VueNode
+  /** custom validate function (Note: callback must be called) */
+  validator: Validator
+}
+
+interface BaseRule {
+  warningOnly?: boolean
+  /** validate the value from a list of possible values */
+  enum?: StoreValue[]
+  /** validate the exact length of a field */
+  len?: number
+  /** validate the max length of a field */
+  max?: number
+  /** validation error message */
+  message?: string | VueNode
+  /** validate the min length of a field */
+  min?: number
+  /** validate from a regular expression */
+  pattern?: RegExp
+  /** indicates whether field is required */
+  required?: boolean
+  /** transform a value before validation */
+  transform?: (value: StoreValue) => StoreValue
+  /** built-in validation type, available options: https://github.com/yiminghe/async-validator#type */
+  type?: RuleType
+  /** treat required fields that only contain whitespace as errors */
+  whitespace?: boolean
+  /** Customize rule level `validateTrigger`. Must be subset of Field `validateTrigger` */
+  validateTrigger?: string | string[]
+  /** Check trigger timing */
+  trigger?: 'blur' | 'change' | Array<'change' | 'blur'>
+}
+
+type AggregationRule = BaseRule & Partial<ValidatorRule>
+
+interface ArrayRule extends Omit<AggregationRule, 'type'> {
+  type: 'array'
+  defaultField?: RuleObject
+}
+
+export type RuleObject = AggregationRule | ArrayRule
+
+export type Rule = RuleObject
+
+export interface ValidateErrorEntity<Values = any> {
+  values: Values
+  errorFields: { name: InternalNamePath; errors: string[] }[]
+  outOfDate: boolean
+}
+
+export interface FieldError {
+  name: InternalNamePath | string
+  errors: string[]
+}
+
+export interface RuleError {
+  errors: string[]
+  rule: RuleObject
+}
+
+export interface ValidateOptions {
+  triggerName?: string
+  validateMessages?: ValidateMessages
+}
+
+export type InternalValidateFields = (
+  nameList?: NamePath[],
+  options?: ValidateOptions,
+) => Promise<Store>
+export type ValidateFields = (nameList?: NamePath[]) => Promise<Store>
+
+// >>>>>> Info
+interface ValueUpdateInfo {
+  type: 'valueUpdate'
+  source: 'internal' | 'external'
+}
+
+interface ValidateFinishInfo {
+  type: 'validateFinish'
+}
+
+interface ResetInfo {
+  type: 'reset'
+}
+
+interface SetFieldInfo {
+  type: 'setField'
+  data: FieldData
+}
+
+interface DependenciesUpdateInfo {
+  type: 'dependenciesUpdate'
+  /**
+   * Contains all the related `InternalNamePath[]`.
+   * a <- b <- c : change `a`
+   * relatedFields=[a, b, c]
+   */
+  relatedFields: InternalNamePath[]
+}
+
+export type NotifyInfo =
+  | ValueUpdateInfo
+  | ValidateFinishInfo
+  | ResetInfo
+  | SetFieldInfo
+  | DependenciesUpdateInfo
+
+export type ValuedNotifyInfo = NotifyInfo & {
+  store: Store
+}
+
+export interface Callbacks<Values = any> {
+  onValuesChange?: (changedValues: any, values: Values) => void
+  onFieldsChange?: (changedFields: FieldData[], allFields: FieldData[]) => void
+  onFinish?: (values: Values) => void
+  onFinishFailed?: (errorInfo: ValidateErrorEntity<Values>) => void
+  onValidate?: (
+    name: string | number | string[] | number[],
+    status: boolean,
+    errors: string[] | null,
+  ) => void
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type EventArgs = any[]
+
+type ValidateMessage = string | (() => string)
+export interface ValidateMessages {
+  default?: ValidateMessage
+  required?: ValidateMessage
+  enum?: ValidateMessage
+  whitespace?: ValidateMessage
+  date?: {
+    format?: ValidateMessage
+    parse?: ValidateMessage
+    invalid?: ValidateMessage
+  }
+  types?: {
+    string?: ValidateMessage
+    method?: ValidateMessage
+    array?: ValidateMessage
+    object?: ValidateMessage
+    number?: ValidateMessage
+    date?: ValidateMessage
+    boolean?: ValidateMessage
+    integer?: ValidateMessage
+    float?: ValidateMessage
+    regexp?: ValidateMessage
+    email?: ValidateMessage
+    url?: ValidateMessage
+    hex?: ValidateMessage
+  }
+  string?: {
+    len?: ValidateMessage
+    min?: ValidateMessage
+    max?: ValidateMessage
+    range?: ValidateMessage
+  }
+  number?: {
+    len?: ValidateMessage
+    min?: ValidateMessage
+    max?: ValidateMessage
+    range?: ValidateMessage
+  }
+  array?: {
+    len?: ValidateMessage
+    min?: ValidateMessage
+    max?: ValidateMessage
+    range?: ValidateMessage
+  }
+  pattern?: {
+    mismatch?: ValidateMessage
+  }
+}

package/src/form/style/explain.ts

@@ -0,0 +1,56 @@
+import type { FormToken } from '.'
+import type { GenerateStyle } from '../../theme/internal'
+
+const genFormValidateMotionStyle: GenerateStyle<FormToken> = (token) => {
+  const { componentCls } = token
+
+  const helpCls = `${componentCls}-show-help`
+  const helpItemCls = `${componentCls}-show-help-item`
+
+  return {
+    [helpCls]: {
+      // Explain holder
+      transition: `opacity ${token.motionDurationSlow} ${token.motionEaseInOut}`,
+
+      '&-appear, &-enter': {
+        opacity: 0,
+
+        '&-active': {
+          opacity: 1,
+        },
+      },
+
+      '&-leave': {
+        opacity: 1,
+
+        '&-active': {
+          opacity: 0,
+        },
+      },
+
+      // Explain
+      [helpItemCls]: {
+        overflow: 'hidden',
+        transition: `height ${token.motionDurationSlow} ${token.motionEaseInOut},
+                     opacity ${token.motionDurationSlow} ${token.motionEaseInOut},
+                     transform ${token.motionDurationSlow} ${token.motionEaseInOut} !important`,
+
+        [`&${helpItemCls}-appear, &${helpItemCls}-enter`]: {
+          transform: `translateY(-5px)`,
+          opacity: 0,
+
+          [`&-active`]: {
+            transform: 'translateY(0)',
+            opacity: 1,
+          },
+        },
+
+        [`&${helpItemCls}-leave-active`]: {
+          transform: `translateY(-5px)`,
+        },
+      },
+    },
+  }
+}
+
+export default genFormValidateMotionStyle