From c1da418a353a4a29a716ce9f24f6c48c5fcc14ca Mon Sep 17 00:00:00 2001 From: tuchg Date: Tue, 16 Aug 2022 20:00:44 +0800 Subject: [PATCH] docs: add some missing documents --- packages/cdk/forms/docs/Api.zh.md | 383 +++++++++++++++++++++++++++++- packages/pro/tree/docs/Api.zh.md | 1 + 2 files changed, 382 insertions(+), 2 deletions(-) diff --git a/packages/cdk/forms/docs/Api.zh.md b/packages/cdk/forms/docs/Api.zh.md index 59d372b19..3f6c4aca3 100644 --- a/packages/cdk/forms/docs/Api.zh.md +++ b/packages/cdk/forms/docs/Api.zh.md @@ -159,9 +159,388 @@ export interface FormAccessor { * 将控件设置为 blurred 状态 */ markAsBlurred: () => void - /** + /** * 设置控件的值 + * + * @param value 新的值 + * @param options + * * `dirty`: 是否让控件变成 `dirty` 状态, 默认值为 `true`. + * * `blur`: 是否让控件变成 `blurred` 状态, 默认值为 `false`. */ - setValue: (value: T) => void + setValue: (value: T, options: { dirty?: boolean; blur?: boolean }) => void +} +``` + +特别需要注意的是: `FormAccessor` 中的 `setValue` 的第二个参数中的 `dirty` 默认为 `true`, 与 `AbstractControl` 的 `setValue` 不一致。 + +### AbstractControl + +```ts +export abstract class AbstractControl { + /** + * control 的唯一 id + */ + readonly uid: number; + /** + * 子控件的集合 + */ + readonly controls: ComputedRef; + /** + * 控件的 ref 值 + */ + readonly valueRef: ComputedRef; + /** + * 控件的验证状态，有三种可能的验证状态值: + * * **valid**: 此控件已通过所有验证 + * * **invalid**: 此控件至少有一个验证失败 + * * **validating**: 此控件正在执行验证 + */ + readonly status: ComputedRef; + /** + * 包含验证失败所产生的任何错误的对象，如果没有错误则为 `undefined` + */ + readonly errors: ComputedRef; + /** + * 此控件是否验证通过 + */ + readonly valid: ComputedRef; + /** + * 此控件是否验证失败 + */ + readonly invalid: ComputedRef; + /** + * 此控件是否正在验证中 + */ + readonly validating: ComputedRef; + /** + * 此控件是否被禁用 + */ + readonly disabled: ComputedRef; + /** + * 此控件是否已经触发 blur 事件 + */ + readonly blurred: ComputedRef; + /** + * 此控件是否尚未触发 blur 事件 + */ + readonly unblurred: ComputedRef; + /** + * 如果用户在 UI 中更改了控件的值，则该控件是 `dirty` + */ + readonly dirty: ComputedRef; + /** + * 如果用户在 UI 中尚未更改控件的值，则该控件是 `pristine` + */ + readonly pristine: ComputedRef; + /** + * 此控件的父级控制器, 如果不存在则为 `undefined` + */ + get parent(): AbstractControl | undefined; + /** + * 此控件的顶层控制器,, 如果不存上层控制器在则为自身 + */ + get root(): AbstractControl; + /** + * 此控件触发验证的时机 + * 可选值: `'change'` | `'blur'` | `'submit'` + * 默认值: `'change'` + */ + get trigger(): 'change' | 'blur' | 'submit'; + /** + * 此控件的名称，通常用于验证提示信息 + */ + name?: string; + /** + * 此控件的示例，通常用于验证提示信息 + */ + example?: string; + constructor( + controls?: GroupControls | AbstractControl>[], + validatorOrOptions?: ValidatorFn | ValidatorFn[] | ValidatorOptions, + asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[], initValue?: T + ); + /** + * 设置控件的新值。 + * + * @param value 新值 + * @param options + * * `dirty`: 是否将其标记为 `dirty`, 默认为 `false` + * * `blur`: 是否将其标记为 `blurred`, 默认为 `false` + */ + abstract setValue(value: T | Partial | Partial>[], options?: { + dirty?: boolean; + blur?: boolean; + }): void; + /** + * 控件的聚合值。 + * + * @param options + * * `skipDisabled`: 是否忽略禁用控件的值，默认为 `false` + */ + abstract getValue(options?: { + skipDisabled?: boolean; + }): T; + /** + * 重置控件，将其标记为 `unblurred` 和 `pristine`, 并将值设置为初始化的值 + */ + reset(): void; + /** + * 手动运行验证 + */ + validate(): Promise; + /** + * 禁用此控制器 + */ + disable(): void; + /** + * 启用此控制器 + */ + enable(): void; + /** + * 将控件标记为 `blurred` + */ + markAsBlurred(): void; + /** + * 将控件标记为 `unblurred`. + */ + markAsUnblurred(): void; + /** + * 将控件标记为 `dirty`. + */ + markAsDirty(): void; + /** + * 将控件标记为 `pristine`. + */ + markAsPristine(): void; + /** + * 为控件设置新的同步验证器，它将覆盖现有的同步验证器 + * + * 如果你想清除所有同步验证器，你可以传入 `undefined` + */ + setValidators(newValidators?: ValidatorFn | ValidatorFn[]): void; + /** + * 为控件设置新的异步验证器，它将覆盖现有的异步验证器 + * + * 如果你想清除所有异步验证器，你可以传入 `undefined` + */ + setAsyncValidators(newAsyncValidators?: AsyncValidatorFn | AsyncValidatorFn[]): void; + /** + * 向此控件添加一个或多个同步验证器，但不影响其他验证器 + * + * 当您在运行时添加或删除验证器时，您必须调用 `validate()` 以使新的验证生效 + */ + addValidators(validators: ValidatorFn | ValidatorFn[]): void; + /** + * 向此控件添加一个或多个异步验证器，但不影响其他验证器 + * + * 当您在运行时添加或删除验证器时，您必须调用 `validate()` 以使新的验证生效 + */ + addAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void; + /** + * 从此控件中删除同步验证器，但不影响其他验证器 + * 通过函数引用比较验证器, 必须传递对完全相同的函数引用 + * 如果没有找到提供的验证器，它将被忽略 + * + * 当您在运行时添加或删除验证器时，您必须调用 `validate()` 以使新的验证生效 + */ + removeValidators(validators: ValidatorFn | ValidatorFn[]): void; + /** + * 从此控件中删除异步验证器，但不影响其他验证器 + * 通过函数引用比较验证器, 必须传递对完全相同的函数引用 + * 如果没有找到提供的验证器，它将被忽略 + * + * 当您在运行时添加或删除验证器时，您必须调用 `validate()` 以使新的验证生效 + */ + removeAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void; + /** + * 清空同步验证器 + * + * 当您在运行时添加或删除验证器时，您必须调用 `validate()` 以使新的验证生效 + * + */ + clearValidators(): void; + /** + * 清空异步验证器 + * + * 当您在运行时添加或删除验证器时，您必须调用 `validate()` 以使新的验证生效 + * + */ + clearAsyncValidators(): void; + /** + * 检查此控件上是否有同步验证器函数 + * 所提供的验证器必须是对所提供的完全相同函数的引用 + * + */ + hasValidator(validator: ValidatorFn): boolean; + /** + * 检查此控件上是否有异步验证器函数 + * 所提供的验证器必须是对所提供的完全相同函数的引用 + * + */ + hasAsyncValidator(validator: AsyncValidatorFn): boolean; + /** + * 获取给定控件名称或路径的子控件 + * + * @param path 子控件的路径，可以是字符串或者数字，也可以是由 `.` 分割的字符串，还可以是一个数组 + */ + get>(path: K): AbstractControl | undefined; + get(path: K): AbstractControl; + get(path: ControlPathType): AbstractControl | undefined; + /** + * 手动设置表单控件上的错误 + */ + setErrors(errors?: ValidateErrors): void; + /** + * 获取给定路径的控件的错误数据 + * + * @param errorCode 要检查的错误代码，例如：`required`, `email` + * @param path 子控件的路径, 不传则为当前控件 + */ + getError(errorCode: string, path?: ControlPathType): ValidateError | undefined; + /** + * 给定路径的控件是否存在错误 + * + * @param errorCode 要检查的错误代码，例如：`required`, `email` + * @param path 子控件的路径, 不传则为当前控件 + */ + hasError(errorCode: string, path?: ControlPathType): boolean; + /** + * 设置控件的父类 + */ + setParent(parent: AbstractControl): void; + /** + * 监听此控件的值的变化 + * + * @param cb 值改变时的回调 + * @param options 监听参数 + */ + watchValue(cb: WatchCallback, options?: WatchOptions): WatchStopHandle; + /** + * 监听此控件的验证状态的变化 + * + * @param cb 状态改变时的回调 + * @param options 监听参数 + */ + watchStatus(cb: WatchCallback, options?: WatchOptions): WatchStopHandle; +} +``` + +### FormControl + +```ts +export class FormControl extends AbstractControl { + readonly controls: ComputedRef; + constructor( + _initValue?: T | undefined, + validatorOrOptions?: ValidatorFn | ValidatorFn[] | ValidatorOptions, + asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] + ); + setValue(value: T, options?: { + dirty?: boolean; + blur?: boolean; + }): void; + getValue(): T; +} +``` + +### FormGroup + +```ts +export class FormGroup extends AbstractControl { + readonly controls: ComputedRef>; + constructor( + /** + * 子控件的集合，它的键就是子控件注册时的 `key` + */ + controls: GroupControls, + validatorOrOptions?: ValidatorFn | ValidatorFn[] | ValidatorOptions, + asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] + ); + setValue(value: Partial, options?: { + dirty?: boolean; + blur?: boolean; + }): void; + getValue(options?: { + skipDisabled?: boolean; + }): T; + /** + * 向此控件组添加子控件 + * + * @param key 被添加控件的键 + * @param control 被添加的控件 + */ + addControl>(key: K, control: AbstractControl): void; + /** + * 从此控件组中删除子控件 + * + * @param key 被删除控件的键 + */ + removeControl>(key: K): void; + /** + * 替换现有的控件 + * + * @param key 替换控件的键 + * @param control 替换的控件 + */ + setControl(key: K, control: AbstractControl): void; +} +``` + +### FormArray + +```ts +export class FormArray extends AbstractControl { + readonly controls: ComputedRef[]>; + /** + * 子控件数组的长度 + */ + readonly length: ComputedRef; + constructor( + /** + * 子控件的数组，每个子控件都有一个被注册的 `index` + */ + controls: AbstractControl[], + validatorOrOptions?: ValidatorFn | ValidatorFn[] | ValidatorOptions, + asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] + ); + setValue(value: T extends object ? Partial[] : T[], options?: { + dirty?: boolean; + blur?: boolean; + }): void; + getValue(options?: { + skipDisabled?: boolean; + }): T[]; + /** + * 通过的 `index` 获取子控件 + * + * @param index 子控件的下标 + */ + at(index: number): AbstractControl | undefined; + /** + * 在数组末尾插入一个新的子控件 + * + * @param control 添加的子控件 + */ + push(control: AbstractControl): void; + /** + * 在数组中给定的 `index` 处插入一个新的子控件 + * + * @param index 插入控件的下标 + * @param control 插入的子控件 + */ + insert(index: number, control: AbstractControl): void; + /** + * 删除数组中给定 `index` 处的子控件。 + * + * @param index 删除控件的下标 + */ + removeAt(index: number): void; + /** + * 替换数组中给定 `index` 处现有的子控件 + * + * @param index 替换控件的下标 + * @param control 替换的控件 + */ + setControl(index: number, control: AbstractControl): void; } ``` diff --git a/packages/pro/tree/docs/Api.zh.md b/packages/pro/tree/docs/Api.zh.md index 4fa8c9867..3460e829d 100644 --- a/packages/pro/tree/docs/Api.zh.md +++ b/packages/pro/tree/docs/Api.zh.md @@ -13,6 +13,7 @@ | `v-model:collapsed` | 树是否收缩 | `boolean` | - | - | 不设置时没有收缩展开功能 | | `v-model:searchValue` | 用于搜索的值 | `string` | - | - | - | | `checkable` | 是否显示选择框 | `boolean` | `false` | - | - | +| `checkOnClick` | 是否允许点击节点进行勾选 | `boolean` | `false` | - | 仅在`checkable`为`true`时生效 | | `childrenKey` | 替代[TreeNode](#TreeNode)中的`children`字段 | `string` | `children` | - | - | | `cascaderStrategy` | 勾选策略 | `'all' \| 'parent' \| 'child'` | `'all'` | - | 设置勾选策略来指定显示的勾选节点，`all` 表示显示全部选中节点；`parent` 表示只显示父节点（当父节点下所有子节点都选中时）；`child` 表示只显示子节点，仅当`cascade`为`true`时，`parent`和`child`才生效 | | `clearIcon` | 设置搜索框清除图标 | `string \| #clearIcon` | `'close-circle'` | ✅ | - |