tg-map-vue3 3.0.8 → 3.1.0

package/dist/src/utils/vue-utils.d.ts

@@ -1,5 +1,5 @@
-import type { Component, ComponentOptions, ComponentPublicInstance, Prop, PropType, RendererElement, RendererNode, Slots, VNode, WritableComputedOptions } from 'vue';
-import type { AbstractConstructor, KeysMatching, StringEnumLike, Thing } from './mapped-types';
+import { type Component, type ComponentOptions, type ComponentPublicInstance, type Prop, type PropType, type RendererElement, type RendererNode, type Slots, type VNode, type WritableComputedOptions } from 'vue';
+import type { AbstractConstructor, KeysMatching, StringEnumLike, StringEnumValue, Thing } from './mapped-types';
 /** 组件选项中的hook名 */
 export type VueHookName = ExcludeSubtype<KeysMatching<OmitStartsWith<RemoveIndex<ComponentOptions>, '_'>, {
     (): void;
@@ -39,18 +39,18 @@ type NotNullProp<T = any, D = T> = {
     default: D | (() => D);
 });
 export declare function stringEnumProp<E extends StringEnumLike>(enumObject: E, defaultValue: E[keyof E]): {
-    type: PropType<E[keyof E]>;
+    type: PropType<StringEnumValue<E>>;
     default: E[keyof E];
 };
 export declare function stringEnumProp<E extends StringEnumLike>(enumObject: E): {
-    type: PropType<E[keyof E]>;
+    type: PropType<StringEnumValue<E>>;
 };
-export declare function stringEnumPropFromArray<T extends string>(enums: T[], defaultValue: T): {
-    type: PropType<T>;
+export declare function stringUnionPropFromValues<T extends string>(values: readonly T[], defaultValue: T): {
+    type: PropType<T[][number]>;
     default: T;
 };
-export declare function stringEnumPropFromArray<T extends string>(enums: T[]): {
-    type: PropType<T>;
+export declare function stringUnionPropFromValues<T extends string>(values: readonly T[]): {
+    type: PropType<T[][number]>;
 };
 export declare function requiredProp<T>(type: PropType<T>): {
     type: PropType<T>;
@@ -110,20 +110,69 @@ export declare function findByComponentType<T extends Component & AbstractConstr
  */
 export declare function extractVNodeFromSlotsByComponent<Props>(slots: Slots, component: ComponentOptions<Props>): VNode<RendererNode, RendererElement, Props> | undefined;
 /**
- * Vue3中 class/style/未声明的事件/未声明的属性 都会集合到{@link SetupContext.attrs}中
- * 默认情况下({@link ComponentOptions.inheritAttrs}为true), 将被透传给组件的根节点
+ * Vue3中 class/style/未声明的事件/未声明的属性 都会集合到`this.$attrs`中
+ * 默认情况下(`inheritAttrs`为true), 将被透传给组件的根节点
+ *
+ * 而Vue2, `this.$attrs`值包含 未声明的属性, 所有事件放到了`this.$listeners`中
  *
- * 而Vue2, 默认只会透传 未声明的属性, 事件通过`$listeners`暴露
+ * 这里模仿Vue2的行为, 从{@link attrs}中拆分出未声明的事件, 方便将他们透传给地图的对象
+ * 同时若传入{@link props}, 也会从它里面拆分出 声明的事件类型的属性
  *
- * 这里模仿Vue2的行为, 拆分出未声明的事件, 方便将他们透传给地图的对象
+ * ## 如何给事件添加类型信息
  *
- * @see https://cn.vuejs.org/guide/components/attrs.html#disabling-attribute-inheritance
- * @see https://v3-migration.vuejs.org/zh/breaking-changes/listeners-removed.html
+ * - 声明在`emits`中的事件, 会给emit方法添加类型信息, 但没办法在运行时判断是否有被设置
+ * - 声明在`props`中的事件, 不会.................. , 但可以通过读取`this.$props`判断是否被设置
+ *
+ * 所有我们最终选择用{@link EventProps}在`props`中声明事件, 同时用{@link EventEmits}在`emits`上声明事件的类型,
+ * 达到既有类型信息, 又能判断是否存在的效果, 写法如下:
+ * ```
+ * {
+ *   props: {...} satisfies EventProps<TgMapEmits>,
+ *   emits: undefined as any as EventEmits<TgMapEmits>,
+ * }
+ * ```
+ *
+ * ## 参考
+ * - https://cn.vuejs.org/guide/components/attrs.html#disabling-attribute-inheritance
+ * - https://v3-migration.vuejs.org/zh/breaking-changes/listeners-removed.html
+ * - https://eslint.vuejs.org/rules/require-explicit-emits.html#options
  */
-export declare function splitAttrs(attrs: Record<string, unknown>): {
+export declare function splitAttrs(attrs: Record<string, unknown>, props?: Record<string, unknown>): {
+    /** class/style/未声明的属性 等 */
+    binds: Record<string, unknown>;
+    /** 未声明的事件 */
+    listeners: Record<string, unknown>;
+    /** 声明在`props`中的事件 */
+    listenerProps: Record<string, unknown>;
+};
+/** 响应式的{@link splitAttrs} */
+export declare function useSplittedAttrs(attrs: Record<string, unknown>, props?: Record<string, unknown>): import("vue").ComputedRef<{
+    /** class/style/未声明的属性 等 */
     binds: Record<string, unknown>;
+    /** 未声明的事件 */
     listeners: Record<string, unknown>;
+    /** 声明在`props`中的事件 */
+    listenerProps: Record<string, unknown>;
+}>;
+export type EventCallback<E = any> = (event: E) => void;
+/**
+ * 事件类型的属性
+ * @see splitAttrs
+ * */
+export type EventProps<Emits> = Emits extends string ? {
+    [K in Emits as `on${Capitalize<K>}`]: Prop<Function>;
+} : {
+    [K in keyof Emits as K extends string ? `on${Capitalize<K>}` : never]: Prop<EventCallback<Emits[K]>>;
+};
+/**
+ * 用来声明事件的类型信息
+ * @see splitAttrs
+ *  */
+export type EventEmits<T> = {
+    [K in keyof T]: (event: T[K]) => boolean;
 };
+/** 给事件类型的属性标注类型 */
+export declare function eventProp<E = any>(): Prop<EventCallback<E>>;
 export declare const eventLogMethods: {
     /**
      * @event 一般来说传{@link Tg.Event}对象, 但传其他对象也不会报错