昆仑组装应用引擎 API 开发文档

🔸 useGetAppInstance

获取当前应用实例底层元信息对象。

function useGetAppInstance(): App

参数

无

返回值

返回 App 实例对象

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useGetAppInstance } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useGetAppInstance } = __kl

const app = useGetAppInstance()
console.log(app)
// 输出: App 实例对象

🔸 useGetAppSchema

获取当前应用 Schema 响应式元数据。

function useGetAppSchema(): AppSchemaType | null

参数

无

返回值

返回一个 AppSchemaType 类型的 Schema 数据对象 或 null

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useGetAppSchema } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useGetAppSchema } = __kl

const appSchema = useGetAppSchema()
console.log(appSchema)
// 输出: App 数据对象或 null

🔸 useEventBus

引擎内置的应用程序事件总线。

function useEventBus(): typeof eventBus

::: info 💡 引擎内置事件总线 Event-bus，它的核心原理是基于发布/订阅模式，提供简单的 API，使得开发者可以在应用程序中轻松地创建和管理事件。 :::

参数

无

返回值

返回一个事件总线实例对象

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useEventBus } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useEventBus } = __kl

const eventbus = useEventBus()

// 监听指定事件
eventbus.on('myEvent', (e) => {
    console.log('接收到的参数', e)
    //...
})

// 监听所有事件
eventbus.on('*', (type, e) => {
    console.log('接收到的参数', type, e)
    //...
})

// 发送指定事件
eventbus.emit('myEvent', '传参')

// 销毁指定事件
eventbus.off('myEvent')

// 销毁所有事件
eventbus.all.clear()

🔸 useGetAppCompTree

获取应用当前页面的组件树。

function useGetAppCompTree(): CompNodeType[] | undefined

参数

无

返回值

返回应用当前页面的组件树或 undefined

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useGetAppCompTree } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useGetAppCompTree } = __kl

const appCompTree = useGetAppCompTree()
console.log(appCompTree)
// 输出: App 组件树数组或 undefined

🔸 useGetCompTreeByPath

根据给定的路由 path 获取页面的组件树。

function useGetCompTreeByPath(path: string): CompNodeType[]

参数

| 名称 | 类型 | 默认值 | 描述 | | ---- | -------- | --- | --------- | | path | string | — | 路由 path，如：/xxx |

返回值

返回指定页面路径的组件树数组或一个空数组

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useGetCompTreeByPath } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useGetCompTreeByPath } = __kl

const compTree = useGetCompTreeByPath('/xxx')
console.log(compTree)
// 输出: 组件树数组或空数组

🔸 useGetAppRouter

获取当前应用的路由实例对象。

function useGetAppRouter(): AppRouterType

参数

无

返回值

返回路由实例对象或 undefined

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useGetAppRouter } from '@klweb/compose-app-engine' 

// 在组装编排模式中调用
const { useGetAppRouter } = __kl

const router = useGetAppRouter()

// 跳转路由或其他操作
router.push({
    path: '/other-page',
    query: {
        a: 1,
        b: 2
    }
})

🔸 useGetAppRoute

获取应用当前路由信息对象。

function useGetAppRoute(): AppRouteType

参数

无

返回值

返回当前路由信息对象或 undefined

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useGetAppRoute } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useGetAppRoute } = __kl

const { path, query } = useGetAppRoute()
console.log(path, query)
// 输出: 路径和路由参数

🔸 useGetGlobalProperties

获取当前应用的全局属性对象。

function useGetGlobalProperties(): GlobalPropertiesType

参数

无

返回值

返回当前应用全局属性对象

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useGetGlobalProperties } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useGetGlobalProperties } = __kl

const globalProperties = useGetGlobalProperties()
console.log(globalProperties)
// 输出: 全局属性对象

🔸 useRegGlobalProperties

注册一个应用全局属性对象，在其它组件实例内可直接调用。

function useRegGlobalProperties<T>(key: string, target: T): void

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | ---| | key | string | — | 要注册的属性键名 | | target | T | — | 被注册绑定对象, 接受一个泛型类型为 T 的参数 |

返回值

无返回值

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { 
    useRegGlobalProperties,
    useGetGlobalProperties,
    useGetCurrentInstance,
    useGetCompRef
} from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { 
    useRegGlobalProperties, 
    useGetGlobalProperties,
    useGetCurrentInstance,
    useGetCompRef 
} = __kl

// 1、首先声明一个可执行函数
const myFunction = () => {
    console.log('hello world!')
}

// 2、注册该函数为全局属性
useRegGlobalProperties('$myFunction', myFunction)

// 3、当前或其它组件实例内调用
const { $myFunction } = useGetGlobalProperties(); 
$myFunction()

// 或
const { proxy } = useGetCurrentInstance();  // 仅在组件生命周期钩子函数内生效
proxy.$myFunction()

// 或
const compRef = await useGetCompRef('c_3u4523d');
compRef.$myFunction()

// 输出: hello world!

🔸 useRef

接受一个内部值，返回一个响应式的、可更改的 ref 对象，此对象只有一个指向其内部值的属性 .value。

function useRef(): typeof ref

参数

无

返回值

返回一个 ref 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useRef } from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useRef } = __kl

const ref = useRef();
const count = ref(0)

🔸 useReactive

返回一个对象的响应式代理。

function useReactive(): typeof reactive

参数

无

返回值

返回一个 reactive 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useReactive } from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useReactive } = __kl

const reactive = useReactive();
const obj = reactive({ count: 0 })
obj.count++

🔸 useComputed

计算属性，接受一个 getter 函数，返回一个只读的响应式 ref 对象。

function useComputed(): typeof computed

::: info 💡 该 ref 通过 .value 暴露 getter 函数的返回值，它也可以接受一个带有 get 和 set 函数的对象来创建一个可写的 ref 对象。了解更多 :::

参数

无

返回值

返回一个 computed 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useRef, useComputed } from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useRef, useComputed } = __kl

const ref = useRef();
const computed = useComputed();

// 创建一个只读的计算属性 ref
const count = ref(1)
const plusOne = computed(() => count.value + 1)
console.log(plusOne.value) // 2

// 创建一个可写的计算属性 ref
const count = ref(1)
const plusOne = computed({
  get: () => count.value + 1,
  set: (val) => {
    count.value = val - 1
  }
})

plusOne.value = 1
console.log(count.value) // 0

🔸 useWatch

侦听一个或多个响应式数据源，并在数据源变化时调用所给的回调函数。

function useWatch(): typeof watch

::: info 💡 watch() 默认是懒侦听的，即仅在侦听源发生变化时才执行回调函数。了解更多 :::

参数

无

返回值

返回一个 watch 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useRef, useWatch } from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useRef, useWatch } = __kl

const ref = useRef();
const watch = useWatch();

// 侦听一个 ref
const count = ref(0)
watch(count, (count, prevCount) => {
    // ...
})

🔸 useToRefs

将一个响应式对象转换为一个普通对象，这个普通对象的每个属性都是指向源对象相应属性的 ref。

function useToRefs(): typeof toRefs

::: info 💡 每个单独的 ref 都是使用 toRef() 创建的。了解更多 :::

参数

无

返回值

返回一个 toRefs 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useReactive, useToRefs } from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useReactive, useToRefs } = __kl

const reactive = useReactive();
const toRefs = useToRefs();

const state = reactive({
  foo: 1,
  bar: 2
})

const { foo, bar } = toRefs(state)

🔸 useToValue

将值、refs 或 getters 规范化为值。

function useToValue(): typeof toValue

::: info 💡 这与 unref() 类似，不同的是此函数也会规范化 getter 函数。如果参数是一个 getter，它将会被调用并且返回它的返回值。了解更多 :::

参数

无

返回值

返回一个 toValue 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useRef, useToValue } from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useRef, useToValue } = __kl

const ref = useRef();
const toValue = useToValue();

toValue(1)  // 1
toValue(ref(1)) // 1
toValue(() => 1) // 1

🔸 useToRaw

根据一个 Vue 创建的代理返回其原始对象。

function useToRaw(): typeof toRaw

::: info 💡 toRaw() 可以返回由 reactive()、readonly()、shallowReactive() 或者 shallowReadonly() 创建的代理对应的原始对象。了解更多 :::

参数

无

返回值

返回一个 toRaw 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useReactive, useToRaw } from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useReactive, useToRaw } = __kl

const reactive = useReactive();
const toRaw = useToRaw();

const foo = {};
const reactiveFoo = reactive(foo);
console.log(toRaw(reactiveFoo) === foo) // true

🔸 useShallowRef

ref() 的浅层作用形式。

function useShallowRef(): typeof shallowRef

::: info 💡 shallowRef() 常常用于对大型数据结构的性能优化或是与外部的状态管理系统集成。了解更多 :::

参数

无

返回值

返回一个 shallowRef 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useShallowRef } from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useShallowRef } = __kl

const shallowRef = useShallowRef();
const state = shallowRef({ count: 1 });

// 不会触发更改
state.value.count = 2;

// 会触发更改
state.value = { count: 2 }

🔸 useShallowReactive

reactive() 的浅层作用形式。

function useShallowReactive(): typeof shallowReactive

::: info 💡 和 reactive() 不同，这里没有深层级的转换：一个浅层响应式对象里只有根级别的属性是响应式的。了解更多 :::

参数

无

返回值

返回一个 shallowReactive 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useShallowReactive } from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useShallowReactive } = __kl

const shallowReactive = useShallowReactive();
const state = shallowReactive({
  foo: 1,
  nested: {
    bar: 2
  }
})；

// 更改状态自身的属性是响应式的
state.foo++；

// 但下层嵌套对象不会被转为响应式
isReactive(state.nested)； // false

// 不是响应式的
state.nested.bar++

🔸 useMarkRaw

将一个对象标记为不可被转为代理，返回该对象本身。

function useMarkRaw(): typeof markRaw

参数

无

返回值

返回一个 markRaw 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useReactive, useMarkRaw } from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useReactive, useMarkRaw } = __kl

const reactive = useReactive();
const markRaw = useMarkRaw();
const foo = markRaw({});
console.log(isReactive(reactive(foo))); // false

// 也适用于嵌套在其他响应性对象
const bar = reactive({ foo });
console.log(isReactive(bar.foo)) // false

🔸 useOnMounted

注册一个回调函数，在组件挂载完成后执行。

function useOnMounted(): typeof onMounted

参数

无

返回值

返回一个 onMounted 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useOnMounted} from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useOnMounted } = __kl

const onMounted = useOnMounted();
onMounted(() => {
    //...
})

🔸 useOnUnmounted

注册一个回调函数，在组件实例被卸载之后调用。

function useOnUnmounted(): typeof onUnmounted

参数

无

返回值

返回一个 onUnmounted 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useOnUnmounted} from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useOnUnmounted } = __kl

const onUnmounted = useOnUnmounted();
onUnmounted(() => {
    //...
})

🔸 useNextTick

等待下一次 DOM 更新刷新的工具方法。

function useNextTick(): typeof nextTick

::: info 💡 nextTick() 可以在状态改变后立即使用，以等待 DOM 更新完成。 :::

参数

无

返回值

返回一个 nextTick 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useNextTick } from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useNextTick } = __kl

const nextTick = useNextTick();
nextTick(() => {
    //...
})

// 或
await nextTick();
//...

🔸 useOnUpdated

注册一个回调函数，在组件因为响应式状态变更而更新其 DOM 树之后调用。

function useOnUpdated(): typeof onUpdated

参数

无

返回值

返回一个 onUpdated 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useOnUpdated} from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useOnUpdated } = __kl

const onUpdated = useOnUpdated();
onUpdated(() => {
    //...
})

🔸 useGetCurrentInstance

获取当前组件内部实例。

function useGetCurrentInstance(): CurrentInstanceType

::: warning ⚠️ 使用 useGetCurrentInstance 函数仅在组件生命周期钩子函数内生效。 :::

参数

无

返回值

返回当前组件内部实例，包含： instance、app、globalProperties、proxy

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useGetCurrentInstance } from '@klweb/compose-app-engine'

// 在组装编排模式中调用
const { useGetCurrentInstance } = __kl

const { 
    instance, 
    app, 
    globalProperties, 
    proxy 
} = useGetCurrentInstance()
console.log(instance, app, globalProperties, proxy)
// 输出: instance: 完整的内部实例；app: App 实例；globalProperties: App 全局属性；proxy: 组件 proxy 实例对象

🔸 useGetCompRef

根据给定的组件 ID 获取组件实例。

function useGetCompRef(compId: string, delay: number = 0): Promise<CompInstanceType>

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | compId | string | — | 目标组件 ID | | delay | number | 0 | 延迟时间，默认：0 毫秒，由于组件树渲染的遍历机制，如目标组件未渲染完成，则无法获取到实例，可传入 300 毫秒或更大的毫秒数延迟获取 |

返回值

返回一个 CompInstanceType 类型的组件实例的 Promise

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useGetCompRef } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useGetCompRef } = __kl

const compRef = await useGetCompRef('c_3u4523d')
console.log(compRef)

// 或
useGetCompRef('c_3u4523d').then(compRef => {
    console.log(compRef)
})

// 输出: 目标组件实例对象

🔸 useGetCompRefProps

根据给定的组件 ID 获取组件实例响应属性（props）对象。

async function useGetCompRefProps(compId: string, delay: number = 0): Promise<CompRefPropsType | void>

::: warning ⚠️ 通过 useGetCompRefProps 函数获取到的组件属性对象（props）是响应式的，但修改 props 属性值仅是组件实例内部响应，并不会同步更新其对应的 schema 元数据，如需更新组件元数据可用 useGetCompNode 函数获取组件元数据进行更新。 :::

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | compId | string | — | 目标组件 ID | | delay | number | 0 | 延迟时间，默认：0 毫秒，由于组件树渲染的遍历机制，如目标组件未渲染完成，则无法获取到实例，可传入 300 毫秒或更大的毫秒数延迟获取 |

返回值

返回一个 CompRefPropsType 类型的组件实例属性对象的 Promise

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useGetCompRefProps } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useGetCompRefProps } = __kl

const props = await useGetCompRefProps('c_3u4523d')
props.name = '更新 name'

// 或
useGetCompRefProps('c_3u4523d').then(props => {
    props.name = '更新 name'
})

🔸 useGetCompNode

根据给定的组件 ID 获取组件节点元数据响应对象。

function useGetCompNode(compId: string): CompNodeType | null

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | compId | string | — | 目标组件 ID |

返回值

返回一个 CompNodeType 类型的组件元数据或 null

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useGetCompNode } from '@klweb/compose-app-engine' 

// 在组装编排模式中调用
const { useGetCompNode } = __kl

const compNode = useGetCompNode('c_3u4523d')
console.log(compNode)
// 输出：组件元数据对象

🔸 useRemoveCompNode

根据给定的组件 ID 从组件树 compTree 中删除组件节点元数据，并返回该组件节点元数据对象。

function useRemoveCompNode(compId: string): CompNodeType | null

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | compId | string | — | 目标组件 ID |

返回值

返回一个 CompNodeType 类型的组件元数据或 null

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useRemoveCompNode } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useRemoveCompNode } = __kl

const compNode = useRemoveCompNode('c_3u4523d')
console.log(compNode)
// 输出：组件元数据对象

🔸 useReloadCompNode

根据给的组件 ID 重新渲染单文件组件实例。

function useReloadCompNode(compId: string): void

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | compId | string | — | 目标组件 ID |

返回值

无返回值

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useReloadCompNode } from '@klweb/compose-app-engine' 

// 在组装编排模式中调用
const { useReloadCompNode } = __kl

useReloadCompNode('c_3u4523d')

🔸 useUnrenderCompNode

禁止渲染给定的组件 ID 的组件实例。

function useUnrenderCompNode(compId: string): void

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | compId | string | — | 目标组件 ID |

返回值

无返回值

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useUnrenderCompNode } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useUnrenderCompNode } = __kl

useUnrenderCompNode('c_3u4523d')

🔸 useResolveAsyncCompLoader

根据给定的组件名称解析模块对应的异步 loader。

function useResolveAsyncCompLoader(compName: string): AsyncComponentLoader | null

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | compName | string | — | 组件名称 |

返回值

返回一个组件模块异步 loader，如：() => import('/src/components/index.mjs')

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useResolveAsyncCompLoader } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useResolveAsyncCompLoader } = __kl
const loader = useResolveAsyncCompLoader('KlGis')

🔸 useDefineComponent

定义一个局部组件。

function useDefineComponent(component: ComponentOptions): DefineComponent

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | component | ComponentOptions | — | 组件选项对象 |

返回值

返回该组件选项对象本身

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useDefineComponent, useCreateVnode } from '@klweb/compose-app-engine' 

// 在组装编排模式中调用
const { useDefineComponent, useCreateVnode } = __kl

const MyComponent = useDefineComponent({
    name: 'my-component',
    setup() {
        const h = useCreateVnode();
        const msg = 'Hello World';
        // 渲染函数或 JSX/TSX（注：组装编排模式中不支持 JSX/TSX）
        return () => h('div', msg)
    }   
})

🔸 useDefineAsyncComponent

定义一个异步组件，它在运行时是懒加载的。

function useDefineAsyncComponent(source: AsyncComponentLoader | AsyncComponentOptions): Component

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | source | AsyncComponentLoader | AsyncComponentOptions | — | 接受一个异步加载函数（如：() => import('/src/components/index.mjs')），或是对加载行为进行更具体定制的一个选项对象 |

类型

type AsyncComponentLoader = () => Promise<Component>

interface AsyncComponentOptions {
  loader: AsyncComponentLoader
  loadingComponent?: Component
  errorComponent?: Component
  delay?: number
  timeout?: number
  suspensible?: boolean
  onError?: (
    error: Error,
    retry: () => void,
    fail: () => void,
    attempts: number
  ) => any
}

返回值

返回一个 Component 类型的单文件组件（SFC）

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useDefineAsyncComponent } from '@klweb/compose-app-engine' 

// 在组装编排模式中调用
const { useDefineAsyncComponent } = __kl

const MyComponent = useDefineAsyncComponent(() => import('/src/components/index.mjs'))

// 或
const MyComponent = useDefineAsyncComponent({
    loader: () => import('/src/components/index.mjs'),
    // ...
})

🔸 useRegGlobalComponent

注册应用全局性组件。

function useRegGlobalComponent(compName: string, source: Component | AsyncComponentLoader): void

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | compName | string | — | 组件名称 | | source | Component | AsyncComponentLoader | — | 接受一个 Component 类型的组件或一个异步组件 loader（如：() => import('/src/components/index.mjs')） |

返回值

无返回值

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useRegGlobalComponent } from '@klweb/compose-app-engine'  
import MyComponent from 'xxxx'

// 在组装编排模式中调用
const { useRegGlobalComponent } = __kl

useRegGlobalComponent('my-component', MyComponent)

// 或

useRegGlobalComponent('my-component', () => import('/src/components/index.mjs'))

🔸 useResolveComponent

根据给定的名称解析已全局注册的组件。

function useResolveComponent(compName: string): Component | string

::: warning ⚠️ 使用 useResolveComponent 函数必须在 setup() 或渲染函数内调用。 :::

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | compName | string | — | 组件名称 |

返回值

返回一个 Component 类型的单文件组件（SFC），如未解析到则返回组件名字符串

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useResolveComponent, useGetAppInstance } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useResolveComponent, useGetAppInstance } = __kl

// 解析全局组件
const MyComponent = useResolveComponent('my-component')

// 或
const app = useGetAppInstance();
const MyComponent = app.component('my-component')

console.log(MyComponent)
// 输出: 一个组件或组件名字符串

🔸 useRegGlobalDirective

注册应用全局性指令。

function useRegGlobalDirective(name: string, directive: Directive): void

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | name | string | — | 指令名称 | | directive | Directive | — | 接受一个 Directive 类型的指令定义 |

返回值

无返回值

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useRegGlobalDirective } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useRegGlobalDirective } = __kl

// 注册（对象形式的指令）
useRegGlobalDirective('my-directive', {
    /* 自定义指令钩子 */
})

// 注册（函数形式的指令）
useRegGlobalDirective('my-directive', () => {
    /* ... */
})

🔸 useResolveDirective

根据给定的名称解析已全局注册的指令。

function useResolveDirective(name: string): Directive | undefined

::: warning ⚠️ 使用 useResolveDirective 函数必须在 setup() 或渲染函数内调用。 :::

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | name | string | — | 指令名称 |

返回值

返回一个 Directive 类型的指令，如未解析到则返回 undefined

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useResolveDirective, useGetAppInstance } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useResolveDirective, useGetAppInstance } = __kl

// 解析全局指令
const MyDirective = useResolveDirective('my-directive')

// 或
const app = useGetAppInstance();
const MyDirective = app.directive('my-directive')

console.log(MyDirective)
// 输出: 一个指令或 undefined

🔸 useCreateVnode

创建一个 vnode 虚拟节点的渲染函数。

function useCreateVnode(): typeof h

::: info 💡 在开发 JSX / TSX 组件模式中，可通过 useCreateVnode 函数创建一个 vnode 虚拟节点渲染视图，其语法与 Vue 提供的 h 渲染函数一致。了解更多 :::

参数

无参数

返回值

返回一个 h 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useCreateVnode } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useCreateVnode } = __kl

export default defineComponent({
    setup() {
        const h = useCreateVnode();
        return () => (
            <>
                { 
                    h('div', Array.from({ length: 20 }).map(() => {
                        return h('p', 'hi')
                    })) 
                }
                
                { h('div', { class: 'bar', innerHTML: 'hello' }) }
            </>
        )
    }
})

🔸 useRender

用于编程式地创建组件虚拟 DOM 树的函数。

function useRender(): typeof render

::: info 💡 render 函数是字符串模板的一种替代，可以使你利用 JavaScript 的丰富表达力来完全编程式地声明组件最终的渲染输出。 :::

参数

无参数

返回值

返回一个 render 函数

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useCreateVnode, useRender } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useCreateVnode, useRender } = __kl

const h = useCreateVnode();
const render = useRender();
const vnode = h('div', { class: 'bar', innerHTML: 'hello' });
render(vnode, document.body)

🔸 useResolveVnode

引擎内置的动态加载/渲染单文件组件（SFC）函数。

function useResolveVnode(component: Component | string, props?: ObjectType, slots?: ObjectType): VNode | null

::: info 💡 在开发 JSX / TSX 组件模式中，通过 useResolveVnode 函数可将一个组件解析为一个 vnode 动态渲染，其语法与 Vue 提供的 h 渲染函数一致。了解更多 :::

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | component | Component | string | — | 接受一个 Component 类型的单文件组件（SFC）或一个组件模块名字符串（如全局注册组件，则传入该组件的注册名） | | props | ObjectType | — | 定义组件内属性 | | slots | ObjectType | — | 定义组件内插槽 |

返回值

返回一个 vnode 或 null

示例

import { myComponent } from 'xxxx' 

// 在组件开发模式中调用使用 `import` 导入函数
import { useResolveVnode } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useCreateVnode } = __kl

export default defineComponent({
    setup() {

        return () => (
            <>
                // 渲染一个 `Component` 类型的单文件组件（SFC）
                { 
                    useResolveVnode(myComponent, {
                            // props
                            id: 'c_3u4523d',
                            // event
                            onClick: (evt) => { }
                        },
                        {
                            // slots
                            default: () => { }
                        }
                    ) 
                }
                
                 // 渲染一个全局注册的单文件组件（SFC），则传入注册的组件名
                 
                { 
                    useResolveVnode('myComponent', {
                            // props
                            id: 'c_3u4523d',
                            // event
                            onClick: (evt) => { }
                        },
                        {
                            // slots
                            default: () => { }
                        }
                    ) 
                }                 
            </>
        )
    }
})

🔸 useRegCompEvents

注册组件生命周期钩子函数内的执行事件或鼠标事件。

function useRegCompEvents(): void

::: warning ⚠️ useRegCompEvents 函数仅限用于开发组件模式中，在 setup() 内执行自动完成组件实例的事件注册。 :::

参数

无

返回值

无返回值

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useRegCompEvents } from '@klweb/compose-app-engine'  

export default defineComponent({
    setup() {
        // 在 setup 内执行自动完成注册事件
        useRegCompEvents()
        //...
    }
})

🔸 useRequest

引擎内置的通用 HTTP 请求库。

function useRequest(): AxiosInstance

::: warning ⚠️ useRequest 和 useDataSourceRequest 的区别：两者都是基于 Axios 封装，useRequest 函数可在开发组件模式和组装编排模式中调用，useDataSourceRequest 函数仅限在开发组件模式中接入数据源调用。了解 Axios :::

参数

无参数

类型

interface AxiosInstance extends Axios {
  <T = any, R = AxiosResponse<T>, D = any>(config: AxiosRequestConfig<D>): Promise<R>;
  <T = any, R = AxiosResponse<T>, D = any>(url: string, config?: AxiosRequestConfig<D>): Promise<R>;

  defaults: Omit<AxiosDefaults, 'headers'> & {
    headers: HeadersDefaults & {
      [key: string]: AxiosHeaderValue
    }
  }
}

返回值

返回一个 Axios 实例

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { useRequest } from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { useRequest } = __kl

const axios = useRequest();

// GET 请求
axios.get('/api/xxx', {
    params: { id: 1 }
}).then(res => {
    console.log(res)
})

// POST 请求
axios.post('/api/xxx', { id: 1 }).then(res => {
    console.log(res)
})

🔸 useDataSourceRequest

引擎内置的组件数据源请求库。

function useDataSourceRequest(dsConfig: CompDataSourceType, customParams?: Record<string, any>): Promise<any>

::: warning ⚠️ 基于 Promise 的 HTTP 网络请求库，useDataSourceRequest 函数仅限在开发组件模式中接入数据源调用。 :::

参数

| 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | dsConfig | CompDataSourceType | — | 数据源配置项 | | customParams | Record<string, any> | — | 自定义请求参数 |

类型

type protocolType = 'http' | 'https' | 'ws'
type MethodType = 'get' | 'GET' | 'delete' | 'DELETE' | 'head' | 'HEAD' | 'options' | 'OPTIONS' | 'post' | 'POST' | 'put' | 'PUT' | 'patch' | 'PATCH' | 'purge' | 'PURGE' | 'link' | 'LINK' | 'unlink' | 'UNLINK'
type ContentType =  'application/json' | 'multipart/form-data' | 'application/x-www-form-urlencoded' | 'application/octet-stream' | 'text/plain' | 'text/html' | 'text/xml'
type ResponseType = 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream'

interface DataFilterType {
    enabled: boolean,
    value: string | null
}

interface CompDataSourceType {
    dsName?: string,
    type?: 'static' | 'dynamic',
    data?: string | null
    id?: string | null,
    protocol?: protocolType | null,
    hostPort?: string | null,
    url?: string | null,
    abUrl?: boolean,
    method?: MethodType | null,
    params?: string | null,
    headers?: string | null,
    contentType?: ContentType | null,
    timeout?: number | null,
    serializeParams?: boolean | null,
    dataFilter?: DataFilterType | null,
    responseType?: ResponseType | null
}

返回值

返回一个任何值的 Promise

示例

// 在组件开发模式中调用使用 `import` 导入函数
import type { PropType } from 'vue'
import { useDataSourceRequest, type CompDataSourceType } from '@klweb/compose-app-engine'  

export default defineComponent({
    props: {
        dataSource: {
            type: Array as PropType<CompDataSourceType[]>,
            default: () => ([
                {
                    dsName: '表格列表数据源',
                    type: 'static',
                    data: "{\r\n \"code\": \"0\",\r\n \"data\": [],\r\n \"msg\": \"请求成功\"\r\n}"
                }
            ]) 
        }         
    },
    setup() {
        // 声明一个数据接口函数
        const getTableData = async () => {
            // 选择关联的数据源
            const tableDs = props.dataSource[0];
            if (!tableDs) return;
            // 请求数据
            const res = await useDataSourceRequest(tableDs, {
                currentPage: 1,
                limit: 20
            })
            console.log(res)
        }
        
        getTableData()
    }
})

🔸 useDialog

引擎内置的一个用于创建和管理对话框（Dialog）的类。

class useDialog implements DefineAttrsType {}

::: info 💡 useDialog 类函数提供了显示和关闭对话框的方法，并支持服务式对话框功能（推荐），可满足更多的定制性场景。 :::

构造函数（Constructor）

• 参数

  | 名称 | 类型 | 默认值 | 描述 | | --- | --- | --- | ---| | attributes | DefineAttrsType | — | 定义对话框的属性项，配置参数详见 Element-Plus 官方文档 |

• 类型

  type DefineAttrsType = {
      /**
       * 是否显示 Dialog
       * @default false
      */
      modelValue?: boolean;
    
      /**
       * Dialog 对话框的标题，也可通过具名 `slot` 传入
       * @default 'Dialog Title'
      */    
      title?: string;
    
      /**
       * 对话框的宽度
       * @default '600px'
      */     
      width?: string | number;
    
      /**
       * 对话框内容插槽组件。当使用 `service` 方式时，如 `contentModule` 为一个 `defineAsyncComponent` 定义的异步组件，则需要结合 `targetFlag` 声明该组件名。
       * @default —
      */     
      contentModule?: Component;
    
      /**
       * 对话框内容插槽组件绑定属性对象
       * @default —
      */     
      contentAttrs?: Record<string, any>;
    
      /**
       * 对话框扩展插槽 `header`、`title`、`footer`（此属性只对 `service` 方式有效）
       * @default —
      */     
      slots?: Slots;
    
      /**
       * 对话框是否支持鼠标拖拽调节大小
       * @default false
      */     
      isResize?: boolean;
    
      /**
       * 对话框附加标识，主要区分不同业务 `Dialog`，显示或关闭 `Dialog` 返回 `targetFlag` 的值
       * @default —
      */      
      targetFlag?: string | number;
    
      /**
       * 对话框互斥标识，仅互斥其它带有相同标识的 `Dialog`
       * @default —
      */   
      mutexFlag?: string;
    
      /**
       * 是否显示 Dialog Header
       * @default true
      */   
      showHeader?: boolean;    
    
      /**
       * 是否需要遮罩层
       * @default true
      */     
      modal?: boolean;
    
      /**
       * 遮罩层鼠标事件是否生效
       * @default true
      */     
      modalEvent?: boolean;
    
      /**
       * 遮罩的自定义类名
       * @default —
      */     
      modalClass?: string;   
    
      /**
       * 对话框内容组件是否强制更新（此属性对 `service` 方式无效）
       * @default undefined
      */      
      forceUpdateKey?: string | number;
    
      /**
       * 是否为全屏 Dialog
       * @default false
      */    
      fullscreen?: boolean;
    
      /**
       * Dialog CSS 中的 `margin-top` 值
       * @default '15vh''
      */    
      top?: string;
    
      /**
       * Dialog 自身是否插入至 `body` 元素上。嵌套的 Dialog 必须指定该属性并赋值为 `true`（此属性对 `service` 方式无效）
       * @default true
      */    
      appendToBody?: boolean;
    
      /**
       * 是否在 Dialog 出现时将 `body` 滚动锁定
       * @default true
      */     
      lockScroll?: boolean;
    
      /**
       * Dialog 打开的延时时间，单位毫秒
       * @default 0
      */     
      openDelay?: number;
    
      /**
       * Dialog 关闭的延时时间，单位毫秒
       * @default 0
      */     
      closeDelay?: number;
    
      /**
       * 是否可以通过点击 `modal` 关闭 Dialog (当 `modalEvent` 为 `false` 时无效)
       * @default true
      */  
      closeOnClickModal?: boolean;
    
      /**
       * 是否可以通过按下 `ESC` 关闭 Dialog
       * @default true
      */      
      closeOnPressEscape?: boolean;
    
      /**
       * 是否显示关闭按钮
       * @default true
      */      
      showClose?: boolean;
    
      /**
       * 为 Dialog 启用可拖拽功能
       * @default true
      */      
      draggable?: boolean;
    
      /**
       * 允许拖拽 Dialog 超出可视窗口区域界线（此属性只对 `service` 方式有效）
       * @default true
      */      
      isDragOut?: boolean; 
        
      /**
       * 允许拖拽 Dialog 超出可视窗口区域界线最低限制值（此属性只对 `service` 方式且 `isDragOut` 为 `true` 时有效）
       * @default 20
      */      
      dragOutLimitValue?: number;    
    
      /**
       * 是否让 Dialog 的 `header` 和 `footer` 部分居中排列
       * @default false
      */      
      center?: boolean;
    
      /**
       * 是否水平垂直对齐对话框
       * @default false
      */      
      alignCenter?: boolean;
    
      /**
       * 当关闭 Dialog 时，销毁其中的元素
       * @default true
      */      
      destroyOnClose?: boolean;
    
      /**
       * 自定义关闭图标
       * @default `Close`
      */      
      closeIcon?: string | Component;
    
       /**
       * Dialog 的自定义类名
       * @default —
      */     
      class?: string;
    
       /**
       * Dialog 的自定义内联样式
       * @default —
      */     
      style?: string | Record<string, any> | any[];
    
      /**
       * 和原生的 CSS 的 `z-index` 相同，改变 `z` 轴的顺序
       * @default —
      */ 
      zIndex?: number;
    
      /**
       * header 的 `aria-level` 属性
       * @default '2'
      */ 
      headerAriaLevel?: string
  }

方法（Methods）

• service 🌈

  useDialog.service(attributes?: DefineAttrsType, callback?: Callback): Promise<ServiceReturnType>

  • 描述：创建一个服务式对话框，支持更多扩展功能
  • 参数：
    • attributes?: DefineAttrsType - 更新对话框属性
    • callback?: Callback - 回调函数，在对话框显示后被调用
  • 返回值：
    • Promise<ServiceReturnType> - 返回当前对话框的属性代理对象
  • 示例：

  // 在组件开发模式中调用使用 `import` 导入函数
  import { useDialog } from '@klweb/compose-app-engine'  
    
  // 在组装编排模式中调用
  const { useDialog } = __kl
    
  const __useDialog = new useDialog({
      // 可定义对话框实例的默认通用属性
       width: 600,
       isResize: true
  });
   
  // 服务式弹窗
  __useDialog.service({
      title: '弹窗标题',
      contentModule: '组件模块',
      contentAttrs: '绑定属性对象'
  }, cb => { 
      // 显示/关闭弹窗回调
  })

• show

  useDialog.show(attributes?: DefineAttrsType, callback?: Callback): void

  • 描述：显示对话框。
  • 参数：
    • attributes?: DefineAttrsType - 更新对话框属性
    • callback?: Callback - 回调函数，在对话框显示后被调用
  • 示例：

  <template>
  <el-dialog v-bind="dialogAttrs">
      <component :is="contentModule" v-bind="contentAttrs" @closeDialog="closeDialog($event)" />
  </el-dialog>
  </template>
  
  <script setup lang="ts">
  import { ElDialog } from 'element-plus'
  import { useDialog } from '@klweb/compose-app-engine'
    
  const __useDialog = new useDialog();
  const { dialogAttrs, contentModule, contentAttrs } = __useDialog;
    
  // 打开弹窗
  __useDialog.show({
      title: '弹窗标题',
      contentModule: '组件模块',
      contentAttrs: '绑定属性对象'
  }, cb => { 
      // Callback 
  })
    
  // 关闭弹窗回调
  const closeDialog = (e) => {
      __useDialog.close(cb => {
          // ...
      })
  }
  </script>

• close

  useDialog.close(callback?: Callback): void

  • 描述：关闭对话框。
  • 参数：
    • callback?: Callback - 回调函数，在对话框关闭后被调用

🔸 useElMessage

全局 ElMessage 消息提示，常用于主动操作后的反馈提示。

function useElMessage(): ElMessageType

参数

配置参数详见 Element-Plus 官方文档

返回值

返回一个 ElMessage 实例

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { 
    useElMessage, 
    useGetCurrentInstance,
    useGetCompRef
} from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { 
    useElMessage, 
    useGetCurrentInstance,
    useGetCompRef
} = __kl

const ElMessage = useElMessage()

ElMessage({
    message: '提示文本',
    type: 'success'
})

// 或

ElMessage.success('提示文本')

// 或
const { proxy } = useGetCurrentInstance();  // 仅在组件生命周期钩子函数内生效
proxy.$message.success('提示文本')

// 或
const compRef = await useGetCompRef('c_3u4523d');
compRef.$message.success('提示文本')

🔸 useElLoading

全局 ElLoading 数据加载状态动效。

function useElLoading(): ElLoadingType

参数

配置参数详见 Element-Plus 官方文档

返回值

返回一个 ElLoading 实例

示例

// 在组件开发模式中调用使用 `import` 导入函数
import { 
    useElLoading, 
    useGetCurrentInstance,
    useGetCompRef
} from '@klweb/compose-app-engine'  

// 在组装编排模式中调用
const { 
    useElLoading, 
    useGetCurrentInstance,
    useGetCompRef
} = __kl

const ElLoading = useElLoading()
const loadingInstance = ElLoading({
    text: '正在加载...'
})

// 关闭 loading
setTimeout(() => {
    loadingInstance.close()
})

// 或
const { proxy } = useGetCurrentInstance();  // 仅在组件生命周期钩子函数内生效
const loadingInstance = proxy.$loading({
    text: '正在加载...'
});
loadingInstance.close()

// 或
const compRef = await useGetCompRef('c_3u4523d');
const loadingInstance = compRef.$loading({
    text: '正在加载...'
});
loadingInstance.close()