@oiij/naive-ui 0.0.75 → 0.0.77

package/dist/components/tooltip-button/index.d.ts

@@ -3,9 +3,12 @@ import { _default } from "./TooltipButton.vue.js";
 import { ButtonProps, TooltipProps } from "naive-ui";
 
 //#region src/components/tooltip-button/index.d.ts
+/**
+ * 提示按钮属性
+ */
 type TooltipButtonProps = {
-  tooltip?: string;
-  tooltipProps?: TooltipProps & ClassStyle;
+  /** 提示文本 */tooltip?: string; /** 提示框属性 */
+  tooltipProps?: TooltipProps & ClassStyle; /** 按钮属性 */
   buttonProps?: ButtonProps & ClassStyle;
 };
 //#endregion

package/dist/components/transition/index.d.ts

@@ -3,8 +3,11 @@ import { _default } from "./BaseTransition.vue.js";
 import { TransitionProps } from "vue";
 
 //#region src/components/transition/index.d.ts
+/**
+ * 过渡动画属性
+ */
 type TransitionProps$1 = {
-  name?: string;
+  /** 过渡名称 */name?: string; /** 过渡属性 */
   transitionProps?: TransitionProps & ClassStyle;
 };
 //#endregion

package/dist/components.d.ts

@@ -5,7 +5,7 @@ import { SearchInputProps } from "./components/search-input/index.js";
 import { _default as _default$2 } from "./components/data-table-plus/DataTablePlus.vue.js";
 import { ClassStyle, DataTablePlusEmits, DataTablePlusExpose, DataTablePlusFields, DataTablePlusInst, DataTablePlusProps } from "./components/data-table-plus/index.js";
 import { _default as _default$3 } from "./components/loading-provider/LoadingProvider.vue.js";
-import { LoadingProviderInst, LoadingProviderProps, loadingProviderInjectionKey } from "./components/loading-provider/index.js";
+import { LOADING_PROVIDER_INJECTION_KEY, LoadingProviderInst, LoadingProviderProps } from "./components/loading-provider/index.js";
 import { UseNaiveFormRules } from "./composables/use-naive-form.js";
 import { _default } from "./components/config-providers/ConfigProviders.vue.js";
 import { ConfigProvidersProps } from "./components/config-providers/index.js";
@@ -24,8 +24,6 @@ import { _default as _default$11 } from "./components/tooltip-button/TooltipButt
 import { TooltipButtonProps } from "./components/tooltip-button/index.js";
 import { _default as _default$12 } from "./components/transition/BaseTransition.vue.js";
 import { TransitionProps } from "./components/transition/index.js";
-import { _default as _default$13 } from "./components/type-writer/TypeWriter.vue.js";
-import { TypeWriterProps } from "./components/type-writer/index.js";
 import "./components/index.js";
 import { ComponentAttrs, ComponentEmit, ComponentExposed, ComponentProps, ComponentSlots } from "vue-component-type-helpers";
-export { ArrayAwareType, ClassStyle, ComponentAttrs, ComponentEmit, ComponentExposed, ComponentProps, ComponentSlots, ConfigProvidersProps, CopyButtonProps, DataTablePlusEmits, DataTablePlusExpose, DataTablePlusFields, DataTablePlusInst, DataTablePlusProps, LoadingProviderInst, LoadingProviderProps, _default as NConfigProviders, _default$1 as NCopyButton, _default$2 as NDataTablePlus, _default$3 as NLoadingProvider, _default$4 as NPresetForm, _default$5 as NPresetInput, _default$6 as NPresetPicker, _default$7 as NPresetSelect, _default$8 as NRemoteRequest, _default$9 as NSearchInput, _default$10 as NToggleInput, _default$11 as NTooltipButton, _default$12 as NTransition, _default$13 as NTypeWriter, OptionFormat, PresetFormExpose, PresetFormInst, PresetFormOptionItem, PresetFormOptions, PresetFormProps, PresetInputOptions, PresetInputProps, PresetInputType, PresetPickerEmits, PresetPickerExpose, PresetPickerInst, PresetPickerProps, PresetPickerValue, PresetSelectEmits, PresetSelectExpose, PresetSelectFields, PresetSelectInst, PresetSelectProps, PresetSelectValue, RemoteRequestEmits, RemoteRequestExpose, RemoteRequestFields, RemoteRequestInst, RemoteRequestProps, SearchInputProps, TooltipButtonProps, TransitionProps, TypeWriterProps, UseNaiveFormRules, loadingProviderInjectionKey };
+export { ArrayAwareType, ClassStyle, ComponentAttrs, ComponentEmit, ComponentExposed, ComponentProps, ComponentSlots, ConfigProvidersProps, CopyButtonProps, DataTablePlusEmits, DataTablePlusExpose, DataTablePlusFields, DataTablePlusInst, DataTablePlusProps, LOADING_PROVIDER_INJECTION_KEY, LoadingProviderInst, LoadingProviderProps, _default as NConfigProviders, _default$1 as NCopyButton, _default$2 as NDataTablePlus, _default$3 as NLoadingProvider, _default$4 as NPresetForm, _default$5 as NPresetInput, _default$6 as NPresetPicker, _default$7 as NPresetSelect, _default$8 as NRemoteRequest, _default$9 as NSearchInput, _default$10 as NToggleInput, _default$11 as NTooltipButton, _default$12 as NTransition, OptionFormat, PresetFormExpose, PresetFormInst, PresetFormOptionItem, PresetFormOptions, PresetFormProps, PresetInputOptions, PresetInputProps, PresetInputType, PresetPickerEmits, PresetPickerExpose, PresetPickerInst, PresetPickerProps, PresetPickerValue, PresetSelectEmits, PresetSelectExpose, PresetSelectFields, PresetSelectInst, PresetSelectProps, PresetSelectValue, RemoteRequestEmits, RemoteRequestExpose, RemoteRequestFields, RemoteRequestInst, RemoteRequestProps, SearchInputProps, TooltipButtonProps, TransitionProps, UseNaiveFormRules };

package/dist/components.js

@@ -1,6 +1,6 @@
 import BaseTransition_default from "./components/transition/BaseTransition.js";
 import LoadingProvider_default from "./components/loading-provider/LoadingProvider.js";
-import { loadingProviderInjectionKey } from "./components/loading-provider/index.js";
+import { LOADING_PROVIDER_INJECTION_KEY } from "./components/loading-provider/index.js";
 import ConfigProviders_default from "./components/config-providers/ConfigProviders.js";
 import CopyButton_default from "./components/copy-button/CopyButton.js";
 import SearchInput_default from "./components/search-input/SearchInput.js";
@@ -12,7 +12,6 @@ import PresetSelect_default from "./components/preset-select/PresetSelect.js";
 import RemoteRequest_default from "./components/remote-request/RemoteRequest.js";
 import ToggleInput_default from "./components/toggle-input/ToggleInput.js";
 import TooltipButton_default from "./components/tooltip-button/TooltipButton.js";
-import TypeWriter_default from "./components/type-writer/TypeWriter.js";
 import { ComponentAttrs, ComponentEmit, ComponentExposed, ComponentProps, ComponentSlots } from "vue-component-type-helpers";
 
-export { ComponentAttrs, ComponentEmit, ComponentExposed, ComponentProps, ComponentSlots, ConfigProviders_default as NConfigProviders, CopyButton_default as NCopyButton, DataTablePlus_default as NDataTablePlus, LoadingProvider_default as NLoadingProvider, PresetForm_default as NPresetForm, PresetInput_default as NPresetInput, PresetPicker_default as NPresetPicker, PresetSelect_default as NPresetSelect, RemoteRequest_default as NRemoteRequest, SearchInput_default as NSearchInput, ToggleInput_default as NToggleInput, TooltipButton_default as NTooltipButton, BaseTransition_default as NTransition, TypeWriter_default as NTypeWriter, loadingProviderInjectionKey };
+export { ComponentAttrs, ComponentEmit, ComponentExposed, ComponentProps, ComponentSlots, LOADING_PROVIDER_INJECTION_KEY, ConfigProviders_default as NConfigProviders, CopyButton_default as NCopyButton, DataTablePlus_default as NDataTablePlus, LoadingProvider_default as NLoadingProvider, PresetForm_default as NPresetForm, PresetInput_default as NPresetInput, PresetPicker_default as NPresetPicker, PresetSelect_default as NPresetSelect, RemoteRequest_default as NRemoteRequest, SearchInput_default as NSearchInput, ToggleInput_default as NToggleInput, TooltipButton_default as NTooltipButton, BaseTransition_default as NTransition };

package/dist/composables/_helper.d.ts

@@ -1,9 +1,12 @@
 //#region src/composables/_helper.d.ts
+/**
+ * 颜色配置类型，用于定义主题的基础颜色
+ */
 type Colors = {
-  primary?: string;
-  info?: string;
-  success?: string;
-  warning?: string;
+  /** 主色 */primary?: string; /** 信息色 */
+  info?: string; /** 成功色 */
+  success?: string; /** 警告色 */
+  warning?: string; /** 错误色 */
   error?: string;
 };
 //#endregion

package/dist/composables/_helper.js

@@ -1,12 +1,34 @@
 import { colord } from "colord";
 
 //#region src/composables/_helper.ts
+/**
+* 获取变亮的颜色
+* @param color - 原始颜色值
+* @returns 变亮后的颜色值，如果输入无效则返回 undefined
+* @example
+* ```ts
+* const darkColor = getDarkColor('#1890ff')
+* // 返回变亮后的颜色值
+* ```
+*/
 function getDarkColor(color) {
 	if (!color) return void 0;
 	const colorInst = colord(color);
 	if (!colorInst.isValid()) return void 0;
 	return colorInst.lighten(.1).toHex();
 }
+/**
+* 获取一组变亮的颜色
+* @param colors - 颜色配置对象
+* @returns 包含变亮后颜色的对象
+* @example
+* ```ts
+* const darkColors = getDarkColors({
+*   primary: '#1890ff',
+*   success: '#52c41a'
+* })
+* ```
+*/
 function getDarkColors(colors) {
 	return {
 		primary: getDarkColor(colors.primary),
@@ -16,6 +38,16 @@ function getDarkColors(colors) {
 		error: getDarkColor(colors.error)
 	};
 }
+/**
+* 获取状态颜色对象，包含基础颜色和交互状态颜色
+* @param color - 原始颜色值
+* @returns 状态颜色对象，如果输入无效则返回 undefined
+* @example
+* ```ts
+* const statusColor = getStatusColor('#1890ff')
+* // 返回 { color: '#1890ff', hover: '...', pressed: '...', suppl: '...' }
+* ```
+*/
 function getStatusColor(color) {
 	if (!color) return void 0;
 	const colorInst = colord(color);
@@ -27,6 +59,21 @@ function getStatusColor(color) {
 		suppl: colorInst.lighten(.1).toHex()
 	};
 }
+/**
+* 获取一组状态颜色
+* @param colors - 颜色配置对象
+* @returns 包含各状态颜色的对象
+* @example
+* ```ts
+* const colors = getColors({
+*   primary: '#1890ff',
+*   info: '#1890ff',
+*   success: '#52c41a',
+*   warning: '#faad14',
+*   error: '#f5222d'
+* })
+* ```
+*/
 function getColors(colors) {
 	const { primary, info, success, warning, error } = colors ?? {};
 	return {

package/dist/composables/index.d.ts

@@ -1,5 +1,5 @@
-import { UseAutoMenuReturn, useAutoMenu } from "./use-auto-menu.js";
 import { DataObject, DataRequestFields, UseDataRequestOptions, UseDataRequestPagination, UseDataRequestReturns, useDataRequest } from "./use-data-request.js";
 import { useLoading } from "./use-loading.js";
 import { UseNaiveFormClearRules, UseNaiveFormOptions, UseNaiveFormReturns, UseNaiveFormRules, useNaiveForm } from "./use-naive-form.js";
+import { UseNaiveMenuOptions, UseNaiveMenuReturn, useNaiveMenu } from "./use-naive-menu.js";
 import { UseNaiveThemeOptions, UseNaiveThemeReturns, useNaiveTheme } from "./use-naive-theme.js";

package/dist/composables/use-data-request.d.ts

@@ -1,5 +1,5 @@
-import * as vue4 from "vue";
 import * as _vueuse_core0 from "@vueuse/core";
+import * as vue0 from "vue";
 import { UseRequestOptions, UseRequestPlugin } from "vue-hooks-plus/es/useRequest/types";
 
 //#region src/composables/use-data-request.d.ts
@@ -46,14 +46,21 @@ type UseDataRequestPagination = {
  * @param api 请求 API 函数
  * @param options 配置选项
  * @returns 数据请求操作对象
+ * @example
+ * ```ts
+ * const { loading, data, list, pagination, run, refresh } = useDataRequest(api, {
+ *   defaultParams: { page: 1, pageSize: 10 },
+ *   fields: { page: 'page', pageSize: 'size', list: 'data', count: 'total' }
+ * })
+ * ```
  */
 declare function useDataRequest<P extends DataObject = DataObject, D extends DataObject = DataObject, R extends DataObject = DataObject>(api: (...args: P[]) => Promise<D>, options?: UseDataRequestOptions<P, D>): {
-  /** 加载状态 */loading: Readonly<vue4.Ref<boolean, boolean>>; /** 响应数据 */
-  data: Readonly<vue4.Ref<D | undefined, D | undefined>>; /** 错误信息 */
-  error: Readonly<vue4.Ref<Error | undefined, Error | undefined>>; /** 请求参数 */
-  params: Readonly<vue4.Ref<[] | P[], [] | P[]>>; /** 列表数据 */
-  list: vue4.ComputedRef<R[]>; /** 分页信息 */
-  pagination: vue4.Ref<{
+  loading: Readonly<vue0.Ref<boolean, boolean>>;
+  data: Readonly<vue0.Ref<D | undefined, D | undefined>>;
+  error: Readonly<vue0.Ref<Error | undefined, Error | undefined>>;
+  params: Readonly<vue0.Ref<P[] | [], P[] | []>>;
+  list: vue0.ComputedRef<R[]>;
+  pagination: vue0.Ref<{
     page: number;
     pageSize: number;
     itemCount: number;
@@ -61,19 +68,19 @@ declare function useDataRequest<P extends DataObject = DataObject, D extends Dat
     page: number;
     pageSize: number;
     itemCount: number;
-  }>; /** 运行请求 */
-  run: (...params: P[]) => void; /** 异步运行请求 */
-  runAsync: (...params: P[]) => Promise<D>; /** 刷新请求 */
-  refresh: () => void; /** 异步刷新请求 */
-  refreshAsync: () => Promise<D>; /** 取消请求 */
-  cancel: () => void; /** 修改响应数据 */
-  mutate: (data?: D | ((oldData?: D | undefined) => D | undefined) | undefined) => void; /** 设置请求参数 */
-  setParams: (_params: Partial<P>) => void; /** 设置参数并运行请求 */
-  runParams: (_params: Partial<P>) => void; /** 设置参数并异步运行请求 */
-  runParamsAsync: (_params: Partial<P>) => Promise<D>; /** 请求前事件 */
-  onBefore: _vueuse_core0.EventHookOn<[P[]]>; /** 请求成功事件 */
-  onSuccess: _vueuse_core0.EventHookOn<[D, P[]]>; /** 请求错误事件 */
-  onError: _vueuse_core0.EventHookOn<[Error, P[]]>; /** 请求完成事件 */
+  }>;
+  run: (...params: P[]) => void;
+  runAsync: (...params: P[]) => Promise<D>;
+  refresh: () => void;
+  refreshAsync: () => Promise<D>;
+  cancel: () => void;
+  mutate: (data?: D | ((oldData?: D | undefined) => D | undefined) | undefined) => void;
+  setParams: (_params: Partial<P>) => void;
+  runParams: (_params: Partial<P>) => void;
+  runParamsAsync: (_params: Partial<P>) => Promise<D>;
+  onBefore: _vueuse_core0.EventHookOn<[P[]]>;
+  onSuccess: _vueuse_core0.EventHookOn<[D, P[]]>;
+  onError: _vueuse_core0.EventHookOn<[Error, P[]]>;
   onFinally: _vueuse_core0.EventHookOn<[P[], D | undefined, Error | undefined]>;
 };
 /**

package/dist/composables/use-data-request.js

@@ -1,5 +1,5 @@
-import { computed, ref } from "vue";
 import { createEventHook } from "@vueuse/core";
+import { computed, ref } from "vue";
 import useRequest from "vue-hooks-plus/es/useRequest";
 
 //#region src/composables/use-data-request.ts
@@ -11,6 +11,13 @@ import useRequest from "vue-hooks-plus/es/useRequest";
 * @param api 请求 API 函数
 * @param options 配置选项
 * @returns 数据请求操作对象
+* @example
+* ```ts
+* const { loading, data, list, pagination, run, refresh } = useDataRequest(api, {
+*   defaultParams: { page: 1, pageSize: 10 },
+*   fields: { page: 'page', pageSize: 'size', list: 'data', count: 'total' }
+* })
+* ```
 */
 function useDataRequest(api, options) {
 	const { defaultParams, manual, fields, requestOptions, requestPlugins } = options ?? {};
@@ -70,15 +77,23 @@ function useDataRequest(api, options) {
 	const list = computed(() => data.value?.[_fields.list] ?? []);
 	/**
 	* 设置请求参数
-	* @param _params 要设置的参数
+	* @param _params - 要设置的参数
+	* @example
+	* ```ts
+	* setParams({ page: 2 })
+	* ```
 	*/
 	function setParams(_params) {
 		Object.assign(params.value?.[0], _params);
 	}
 	/**
 	* 设置参数并运行请求
-	* @param _params 要设置的参数
+	* @param _params - 要设置的参数
 	* @returns 请求结果
+	* @example
+	* ```ts
+	* runParams({ page: 2 })
+	* ```
 	*/
 	function runParams(_params) {
 		return run({
@@ -88,8 +103,12 @@ function useDataRequest(api, options) {
 	}
 	/**
 	* 设置参数并异步运行请求
-	* @param _params 要设置的参数
+	* @param _params - 要设置的参数
 	* @returns 请求结果 Promise
+	* @example
+	* ```ts
+	* await runParamsAsync({ page: 2 })
+	* ```
 	*/
 	function runParamsAsync(_params) {
 		return runAsync({

package/dist/composables/use-loading.d.ts

@@ -4,6 +4,12 @@ import { LoadingProviderInst } from "../components/loading-provider/index.js";
 /**
  * 用于获取 Naive UI 加载状态提供者的组合式 API
  * @returns 加载状态提供者实例
+ * @example
+ * ```ts
+ * const loading = useLoading()
+ * loading?.start()
+ * loading?.finish()
+ * ```
  */
 declare function useLoading(): LoadingProviderInst | undefined;
 //#endregion

package/dist/composables/use-loading.js

@@ -1,4 +1,4 @@
-import { loadingProviderInjectionKey } from "../components/loading-provider/index.js";
+import { LOADING_PROVIDER_INJECTION_KEY } from "../components/loading-provider/index.js";
 import { inject } from "vue";
 
 //#region src/composables/use-loading.ts
@@ -9,9 +9,15 @@ import { inject } from "vue";
 /**
 * 用于获取 Naive UI 加载状态提供者的组合式 API
 * @returns 加载状态提供者实例
+* @example
+* ```ts
+* const loading = useLoading()
+* loading?.start()
+* loading?.finish()
+* ```
 */
 function useLoading() {
-	return inject(loadingProviderInjectionKey);
+	return inject(LOADING_PROVIDER_INJECTION_KEY);
 }
 
 //#endregion

package/dist/composables/use-naive-form.d.ts

@@ -1,7 +1,7 @@
 import { DataObject } from "./use-data-request.js";
-import * as vue1 from "vue";
+import * as _vueuse_core3 from "@vueuse/core";
+import * as vue5 from "vue";
 import { MaybeRefOrGetter, Ref, TemplateRef } from "vue";
-import * as _vueuse_core0 from "@vueuse/core";
 import { FormInst, FormItemRule, FormRules } from "naive-ui";
 import { ValidateError } from "async-validator";
 
@@ -35,24 +35,32 @@ type UseNaiveFormOptions<T extends DataObject> = {
  * @param formInstRef 表单实例引用
  * @param options 配置选项
  * @returns 表单操作对象
+ * @example
+ * ```ts
+ * const formRef = ref<FormInst>()
+ * const { formValue, formRules, formProps, validate, reset, clear } = useNaiveForm(formRef, {
+ *   value: { name: '', age: 0 },
+ *   rules: { name: { required: true, message: '请输入姓名' } }
+ * })
+ * ```
  */
 declare function useNaiveForm<T extends DataObject = DataObject>(formInstRef: TemplateRef<FormInst>, options?: UseNaiveFormOptions<T>): {
-  /** 表单实例引用 */formInst: Readonly<vue1.ShallowRef<FormInst | null>>; /** 表单值引用 */
-  formValue: Ref<T, T>; /** 表单规则引用 */
-  formRules: Ref<Partial<Record<keyof T, FormRules | FormItemRule | FormItemRule[]>>, Partial<Record<keyof T, FormRules | FormItemRule | FormItemRule[]>>>; /** 表单属性，用于绑定到表单组件 */
+  formInst: Readonly<vue5.ShallowRef<FormInst | null>>;
+  formValue: Ref<T, T>;
+  formRules: Ref<Partial<Record<keyof T, FormRules | FormItemRule | FormItemRule[]>>, Partial<Record<keyof T, FormRules | FormItemRule | FormItemRule[]>>>;
   formProps: {
-    model: vue1.Reactive<T>;
-    rules: vue1.Reactive<Partial<Record<keyof T, FormRules | FormItemRule | FormItemRule[]>>>;
-  }; /** 设置表单值 */
-  setValue: (_value: Partial<T>) => void; /** 验证表单 */
+    model: vue5.Reactive<T>;
+    rules: vue5.Reactive<Partial<Record<keyof T, FormRules | FormItemRule | FormItemRule[]>>>;
+  };
+  setValue: (value: Partial<T>) => void;
   validate: () => Promise<{
     warnings?: ValidateError[][];
-  }>; /** 重置表单验证状态 */
-  resetValidation: () => void; /** 重置表单值到初始状态 */
-  resetForm: () => void; /** 重置表单验证状态和值 */
-  reset: () => void; /** 清空表单值 */
-  clear: () => void; /** 验证成功事件 */
-  onValidated: _vueuse_core0.EventHookOn<[T]>;
+  }>;
+  resetValidation: () => void;
+  resetForm: () => void;
+  reset: () => void;
+  clear: () => void;
+  onValidated: _vueuse_core3.EventHookOn<[T]>;
 };
 /**
  * useNaiveForm 返回类型

package/dist/composables/use-naive-form.js

@@ -1,29 +1,16 @@
-import { reactive, ref, toRaw, toValue, watchEffect } from "vue";
 import { createEventHook } from "@vueuse/core";
+import { reactive, ref, toRaw, toValue, watchEffect } from "vue";
 import { cloneDeep } from "es-toolkit/object";
+import { isPlainObject } from "es-toolkit/predicate";
 
 //#region src/composables/use-naive-form.ts
-/**
-* 检查值是否为对象类型
-* @param value 要检查的值
-* @returns 是否为对象类型
-*/
-function isObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/**
-* 清空对象值
-* @param obj 要清空的对象
-* @param rules 清空规则
-* @returns 清空后的对象
-*/
 function clearObjectValues(obj, rules) {
 	const { string: _string = "", number: _number = null, boolean: _boolean = false } = rules ?? {};
 	if (Array.isArray(obj)) {
 		obj.length = 0;
 		return obj;
 	}
-	if (typeof obj === "object" && obj !== null && !Array.isArray(obj)) {
+	if (isPlainObject(obj)) {
 		for (const key in obj) if (Object.prototype.hasOwnProperty.call(obj, key)) obj[key] = clearObjectValues(obj[key], rules);
 		return obj;
 	}
@@ -33,26 +20,19 @@ function clearObjectValues(obj, rules) {
 	return obj;
 }
 /**
-* 深度合并对象
-* @param target 目标对象
-* @param source 源对象
-* @returns 合并后的对象
-*/
-function deepMerge(target = {}, source = {}) {
-	for (const key in source) if (Object.prototype.hasOwnProperty.call(source, key)) {
-		const sourceValue = source[key];
-		const targetValue = target[key];
-		if (isObject(sourceValue) && isObject(targetValue)) deepMerge(targetValue, sourceValue);
-		else target[key] = sourceValue;
-	}
-	return target;
-}
-/**
 * 用于处理 Naive UI 表单的组合式 API
 * @template T 表单值类型
 * @param formInstRef 表单实例引用
 * @param options 配置选项
 * @returns 表单操作对象
+* @example
+* ```ts
+* const formRef = ref<FormInst>()
+* const { formValue, formRules, formProps, validate, reset, clear } = useNaiveForm(formRef, {
+*   value: { name: '', age: 0 },
+*   rules: { name: { required: true, message: '请输入姓名' } }
+* })
+* ```
 */
 function useNaiveForm(formInstRef, options) {
 	const { value, rules, clearRules } = options ?? {};
@@ -62,7 +42,9 @@ function useNaiveForm(formInstRef, options) {
 		formValueRef.value = toValue(value) ?? {};
 	});
 	const formRulesRef = ref(toValue(rules));
-	watchEffect(() => formRulesRef.value = toValue(rules) ?? {});
+	watchEffect(() => {
+		formRulesRef.value = toValue(rules) ?? {};
+	});
 	const formProps = {
 		model: reactive(formValueRef.value),
 		rules: reactive(formRulesRef.value)
@@ -70,19 +52,31 @@ function useNaiveForm(formInstRef, options) {
 	const onValidatedEvent = createEventHook();
 	/**
 	* 设置表单值
-	* @param _value 要设置的值
+	* @param value - 要设置的值
+	* @example
+	* ```ts
+	* setValue({ name: '张三' })
+	* ```
 	*/
-	function setValue(_value) {
-		Object.assign(formValueRef.value, _value);
+	function setValue(value) {
+		Object.assign(formValueRef.value, value);
 	}
 	/**
 	* 验证表单
-	* @returns 验证结果Promise
+	* @returns 验证结果 Promise
+	* @example
+	* ```ts
+	* try {
+	*   await validate()
+	* } catch (errors) {
+	*   console.log(errors)
+	* }
+	* ```
 	*/
 	function validate() {
+		if (!formInstRef.value) throw new Error("useNaiveForm: formInstRef is not found.");
 		return new Promise((resolve, reject) => {
-			if (!formInstRef.value) return reject(/* @__PURE__ */ new Error("useNaiveForm: formInstRef is not found."));
-			formInstRef.value.validate().then((res) => {
+			formInstRef.value?.validate().then((res) => {
 				onValidatedEvent.trigger(toRaw(toValue(formValueRef)));
 				return resolve(res);
 			}).catch(reject);
@@ -90,26 +84,41 @@ function useNaiveForm(formInstRef, options) {
 	}
 	/**
 	* 重置表单验证状态
+	* @example
+	* ```ts
+	* resetValidation()
+	* ```
 	*/
 	function resetValidation() {
 		formInstRef.value?.restoreValidation();
 	}
 	/**
 	* 清空表单值
+	* @example
+	* ```ts
+	* clear()
+	* ```
 	*/
 	function clear() {
 		clearObjectValues(formValueRef.value, clearRules);
 	}
 	/**
 	* 重置表单值到初始状态
+	* @example
+	* ```ts
+	* resetForm()
+	* ```
 	*/
 	function resetForm() {
 		clear();
-		const _cacheValue = cloneDeep(cacheValue);
-		deepMerge(formValueRef.value, _cacheValue);
+		Object.assign(formValueRef.value, cloneDeep(cacheValue));
 	}
 	/**
 	* 重置表单验证状态和值
+	* @example
+	* ```ts
+	* reset()
+	* ```
 	*/
 	function reset() {
 		resetValidation();

package/dist/composables/use-naive-menu.d.ts

@@ -0,0 +1,104 @@
+import * as vue8 from "vue";
+import { MaybeRefOrGetter, VNodeChild } from "vue";
+import { MenuOption } from "naive-ui";
+import { RouteRecordRaw } from "vue-router";
+
+//#region src/composables/use-naive-menu.d.ts
+/**
+ * 配置选项接口
+ * 用于定义 useNaiveMenu 组合函数的配置参数
+ */
+type UseNaiveMenuOptions = {
+  /**
+   * 隐藏条件，可以是函数或字符串
+   * - 如果是函数，返回 true 时路由将不显示在菜单中
+   * - 如果是字符串，则从 route.meta 中获取对应属性的值
+   * @default 'hidden'
+   */
+  hidden?: ((route: RouteRecordRaw) => boolean | string) | string;
+  /**
+   * 根路由判断，可以是函数或字符串
+   * - 如果是函数，返回 true 时路由将作为顶级菜单
+   * - 如果是字符串，则从 route.meta 中获取对应属性的值
+   * @default 'root'
+   */
+  root?: ((route: RouteRecordRaw) => boolean | string) | string;
+  /**
+   * 标签字段名，从 route.meta 中获取对应属性的值作为菜单标签
+   * @default 'title'
+   */
+  labelField?: string;
+  /**
+   * 键字段名，从 route 中获取对应属性的值作为菜单键
+   * @default 'name'
+   */
+  keyField?: string;
+  /**
+   * 图标字段名，从 route.meta 中获取对应属性的值作为菜单图标
+   * @default 'icon'
+   */
+  iconField?: string;
+  /**
+   * 图标渲染函数，用于自定义图标渲染
+   */
+  renderIcon?: (icon: string) => VNodeChild;
+  /**
+   * 父路由元信息字段名
+   * @default 'parent'
+   */
+  parentField?: string;
+  /**
+   * 父路由文件路径
+   * @default ''
+   */
+  parentFilePath?: string;
+  /**
+   * 父路由元信息生成函数
+   */
+  parent?: (route: RouteRecordRaw) => Record<string, unknown>;
+  /**
+   * 自定义菜单选项创建函数
+   */
+  createMenuOption?: (route: RouteRecordRaw) => MenuOption;
+};
+/**
+ * 自动菜单组合函数
+ * 将路由配置转换为菜单配置，并提供扁平化的菜单选项
+ * @param routes 路由配置数组，可以是响应式或普通数组
+ * @param options 配置选项
+ * @returns 包含菜单选项和扁平化菜单选项的对象
+ * @example
+ * ```ts
+ * // 基本使用
+ * const { menuOptions, flattenedMenuOptions } = useNaiveMenu(routes)
+ *
+ * // 带配置选项（使用函数）
+ * const { menuOptions, flattenedMenuOptions } = useNaiveMenu(routes, {
+ *   hidden: (route) => route.meta?.hidden,
+ *   root: (route) => route.meta?.root,
+ *   labelField: 'title',
+ *   keyField: 'name',
+ *   iconField: 'icon',
+ *   renderIcon: (icon) => h('i', { class: icon })
+ * })
+ *
+ * // 带配置选项（使用字符串）
+ * const { menuOptions, flattenedMenuOptions } = useNaiveMenu(routes, {
+ *   hidden: 'hidden',
+ *   root: 'root',
+ *   labelField: 'title',
+ *   keyField: 'name',
+ *   iconField: 'icon'
+ * })
+ * ```
+ */
+declare function useNaiveMenu(routes: MaybeRefOrGetter<RouteRecordRaw[]>, options?: UseNaiveMenuOptions): {
+  menuOptions: vue8.ComputedRef<MenuOption[]>;
+  flattenedMenuOptions: vue8.ComputedRef<MenuOption[]>;
+};
+/**
+ * useNaiveMenu 返回类型
+ */
+type UseNaiveMenuReturn = ReturnType<typeof useNaiveMenu>;
+//#endregion
+export { UseNaiveMenuOptions, UseNaiveMenuReturn, useNaiveMenu };