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

### 🔸 useGetAppInstance

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

` function useGetAppInstance(): App`

#### 参数

无

#### 返回值

返回 `App` 实例对象

#### 示例

```javascript
// 在组件开发模式中调用使用 `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`

#### 示例

```javascript
// 在组件开发模式中调用使用 `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`，使得开发者可以在应用程序中轻松地创建和管理事件。
:::

#### 参数

无

#### 返回值

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

#### 示例

```javascript
// 在组件开发模式中调用使用 `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()
```

### 🔸 useGetCompTree

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

`function useGetCompTree(): CompNodeType[] | undefined`

#### 参数

无

#### 返回值

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

#### 示例

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

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

const compTree = useGetCompTree()
console.log(compTree)
// 输出: App 当前页面的组件树数组或 undefined
```

### 🔸 useGetCompTreeByPath

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

`function useGetCompTreeByPath(path: string): CompNodeType[]`

#### 参数

| <div style="width: 60px">名称</div> | <div style="width: 60px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| ---- | -------- | --- | --------- |
| path | `string` | —   | 路由 `path`，如：`/xxx`  |

#### 返回值

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

#### 示例

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

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

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

### 🔸 useGetAppRouter

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

`function useGetAppRouter(): AppRouterType`

#### 参数

无

#### 返回值

返回路由实例对象或 `undefined`

#### 示例

```javascript
// 在组件开发模式中调用使用 `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`

#### 示例

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

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

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

### 🔸 useGetGlobalProperties

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

`function useGetGlobalProperties(): GlobalPropertiesType`

#### 参数

无

#### 返回值

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

#### 示例

```javascript
// 在组件开发模式中调用使用 `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`

#### 参数

| <div style="width: 60px">名称</div> | <div style="width: 60px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| --- | --- | --- | ---|
| key    | `string` | —   | 要注册的属性键名                   |
| target | `T`      | —   | 被注册绑定对象, 接受一个泛型类型为 `T` 的参数 |

#### 返回值

无返回值

#### 示例

```javascript
// 在组件开发模式中调用使用 `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` 函数

#### 示例

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

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

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

### 🔸 useReactive

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

`function useReactive(): typeof reactive`

#### 参数

无

#### 返回值

返回一个 `reactive` 函数

#### 示例

```javascript
// 在组件开发模式中调用使用 `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` 对象。[了解更多](https://cn.vuejs.org/api/reactivity-core#computed)
:::

#### 参数

无

#### 返回值

返回一个 `computed` 函数

#### 示例

```javascript
// 在组件开发模式中调用使用 `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()` 默认是懒侦听的，即仅在侦听源发生变化时才执行回调函数。[了解更多](https://cn.vuejs.org/api/reactivity-core#watch)
:::

#### 参数

无

#### 返回值

返回一个 `watch` 函数

#### 示例

```javascript
// 在组件开发模式中调用使用 `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()` 创建的。[了解更多](https://cn.vuejs.org/api/reactivity-utilities#torefs)
:::

#### 参数

无

#### 返回值

返回一个 `toRefs` 函数

#### 示例

```javascript
// 在组件开发模式中调用使用 `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`，它将会被调用并且返回它的返回值。[了解更多](https://cn.vuejs.org/api/reactivity-utilities#tovalue)
:::

#### 参数

无

#### 返回值

返回一个 `toValue` 函数

#### 示例

```javascript
// 在组件开发模式中调用使用 `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()` 创建的代理对应的原始对象。[了解更多](https://cn.vuejs.org/api/reactivity-advanced#toraw)
:::

#### 参数

无

#### 返回值

返回一个 `toRaw` 函数

#### 示例

```javascript
// 在组件开发模式中调用使用 `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()` 常常用于对大型数据结构的性能优化或是与外部的状态管理系统集成。[了解更多](https://cn.vuejs.org/api/reactivity-advanced#shallowref)
:::

#### 参数

无

#### 返回值

返回一个 `shallowRef` 函数

#### 示例

```javascript
// 在组件开发模式中调用使用 `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()` 不同，这里没有深层级的转换：一个浅层响应式对象里只有根级别的属性是响应式的。[了解更多](https://cn.vuejs.org/api/reactivity-advanced#shallowreactive)
:::

#### 参数

无

#### 返回值

返回一个 `shallowReactive` 函数

#### 示例

```javascript
// 在组件开发模式中调用使用 `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` 函数

#### 示例

```javascript
// 在组件开发模式中调用使用 `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` 函数

#### 示例

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

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

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

### 🔸 useOnUnmounted

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

`function useOnUnmounted(): typeof onUnmounted`

#### 参数

无

#### 返回值

返回一个 `onUnmounted` 函数

#### 示例

```javascript
// 在组件开发模式中调用使用 `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` 函数

#### 示例

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

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

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

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

### 🔸 useOnUpdated

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

`function useOnUpdated(): typeof onUpdated`

#### 参数

无

#### 返回值

返回一个 `onUpdated` 函数

#### 示例

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

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

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

### 🔸 useGetCurrentInstance

获取当前组件内部实例。

`function useGetCurrentInstance(): CurrentInstanceType`

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

#### 参数

无

#### 返回值

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

#### 示例

```javascript
// 在组件开发模式中调用使用 `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>`

::: info
💡 如一个组件使用了 `<script setup>` ，则默认是私有的，外部无法访问到该组件中的任何东西，除非该组件在其中通过 `defineExpose` 宏显式暴露。
:::

#### 参数

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

#### 返回值

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

#### 示例

```javascript
// 在组件开发模式中调用使用 `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` 函数获取组件元数据进行更新。
:::

#### 参数

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

#### 返回值

返回一个 `CompRefPropsType` 类型的组件实例属性对象或无任何值的 `Promise`

#### 示例

```javascript
// 在组件开发模式中调用使用 `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`

#### 参数

| <div style="width: 60px">名称</div> | <div style="width: 60px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| --- | --- | --- | --- |
| compId  | `string` |  — | 目标组件 `ID` |

#### 返回值

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

#### 示例

```javascript
// 在组件开发模式中调用使用 `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`

#### 参数

| <div style="width: 60px">名称</div> | <div style="width: 60px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| --- | --- | --- | --- |
| compId  | `string` |  — | 目标组件 `ID` |

#### 返回值

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

#### 示例

```javascript
// 在组件开发模式中调用使用 `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`

#### 参数

| <div style="width: 60px">名称</div> | <div style="width: 60px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| --- | --- | --- | --- |
| compId  | `string` |  — | 目标组件 `ID` |

#### 返回值

无返回值

#### 示例

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

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

useReloadCompNode('c_3u4523d')
```

### 🔸 useUnrenderCompNode

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

`function useUnrenderCompNode(compId: string): void`

#### 参数

| <div style="width: 60px">名称</div> | <div style="width: 60px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| --- | --- | --- | --- |
| compId  | `string` |  — | 目标组件 `ID` |

#### 返回值

无返回值

#### 示例

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

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

useUnrenderCompNode('c_3u4523d')
```

### 🔸 useResolveAsyncCompLoader

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

`function useResolveAsyncCompLoader(compName: string): AsyncComponentLoader | null`

#### 参数

| <div style="width: 60px">名称</div> | <div style="width: 60px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| --- | --- | --- | --- |
| compName  | `string` |  — | 组件名称 |

#### 返回值

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

#### 示例

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

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

### 🔸 useDefineComponent

定义一个局部组件。

`function useDefineComponent(component: ComponentOptions): DefineComponent`

#### 参数

| <div style="width: 60px">名称</div> | <div style="width: 60px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| --- | --- | --- | --- |
| component  | `ComponentOptions` |  — | 组件选项对象 |

#### 返回值

返回该组件选项对象本身

#### 示例

```javascript
// 在组件开发模式中调用使用 `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`

#### 参数

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

#### 类型

```typescript
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`）

#### 示例

```javascript
// 在组件开发模式中调用使用 `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`

#### 参数

| <div style="width: 80px">名称</div> | <div style="width: 230px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| --- | --- | --- | --- |
| compName  | `string` |  — | 组件名称 |
| source  | `Component` \| `AsyncComponentLoader` |  — | 接受一个 `Component` 类型的组件或一个异步组件 `loader`（如：`() => import('/src/components/index.mjs')`） |

#### 返回值

无返回值

#### 示例

```javascript
// 在组件开发模式中调用使用 `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()` 或渲染函数内调用。
::: 

#### 参数

| <div style="width: 60px">名称</div> | <div style="width: 60px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| --- | --- | --- | --- |
| compName  | `string` |  — | 组件名称 |

#### 返回值

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

#### 示例

```javascript
// 在组件开发模式中调用使用 `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`

#### 参数

| <div style="width: 60px">名称</div> | <div style="width: 60px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| --- | --- | --- | --- |
| name  | `string` |  — | 指令名称 |
| directive  | `Directive` |  — | 接受一个 `Directive` 类型的指令定义 |

#### 返回值

无返回值

#### 示例

```javascript
// 在组件开发模式中调用使用 `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()` 或渲染函数内调用。
::: 

#### 参数

| <div style="width: 60px">名称</div> | <div style="width: 60px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| --- | --- | --- | --- |
| name  | `string` |  — | 指令名称 |

#### 返回值

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

#### 示例

```javascript
// 在组件开发模式中调用使用 `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` 渲染函数一致。[了解更多](https://cn.vuejs.org/guide/extras/render-function.html)
::: 

#### 参数

无参数

#### 返回值

返回一个 `h` 函数

#### 示例

```javascript
// 在组件开发模式中调用使用 `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` 函数

#### 示例

```javascript
// 在组件开发模式中调用使用 `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` 渲染函数一致。[了解更多](https://cn.vuejs.org/guide/extras/render-function.html)
::: 

#### 参数

| <div style="width: 80px">名称</div> | <div style="width: 130px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| --- | --- | --- | --- |
| component  | `Component` \| `string` |  — | 接受一个 `Component` 类型的单文件组件（SFC）或一个组件模块名字符串（如全局注册组件，则传入该组件的注册名） |
| props  | `ObjectType` |  — | 定义组件内属性 |
| slots  | `ObjectType` |  — | 定义组件内插槽 |

#### 返回值

返回一个 `vnode` 或 `null`

#### 示例

```javascript
import { myComponent } from 'xxxx' 

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

// 在组装编排模式中调用
const { useResolveVnode } = __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()` 内执行自动完成组件实例的事件注册。
::: 

#### 参数

无

#### 返回值

无返回值

#### 示例

```javascript
// 在组件开发模式中调用使用 `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](https://axios-http.com/zh/)
::: 

#### 参数

无参数

#### 类型
```typescript
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` 实例

#### 示例

```javascript
// 在组件开发模式中调用使用 `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` 函数仅限在开发组件模式中接入数据源调用。
::: 

#### 参数

| <div style="width: 80px">名称</div> | <div style="width: 130px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
| --- | --- | --- | --- |
| dsConfig  | `CompDataSourceType` |  — | 数据源配置项 |
| customParams  | `Record<string, any>` |  — | 自定义请求参数 |

#### 类型
```typescript
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`

#### 示例

```javascript
// 在组件开发模式中调用使用 `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）

- ##### 参数

    | <div style="width: 70px">名称</div> | <div style="width: 110px">类型</div> | <div style="width: 60px">默认值</div> | 描述 |
    | --- | --- | --- | ---|
    | attributes | `DefineAttrsType ` | —   | 定义对话框的属性项，[配置参数详见 `Element-Plus` 官方文档](https://element-plus.org/zh-CN/component/dialog.html#api) |

- ##### 类型

    <details>
    <summary>点击展开/折叠类型说明</summary><br>
    
    ```typescript
    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
    }
    ```
    </details>

#### 方法（Methods）

- ##### service

    `useDialog.service(attributes?: DefineAttrsType, callback?: Callback): Promise<ServiceReturnType>`
    
    - **描述**：创建一个服务式对话框，支持更多扩展功能
    - **参数**：
        - `attributes?: DefineAttrsType` - 更新对话框属性
        - `callback?: Callback` - 回调函数，在对话框显示后被调用
    - **返回值**：
        - `Promise<ServiceReturnType>` - 返回当前对话框的属性代理对象
    - **示例**：
    ```javascript
    // 在组件开发模式中调用使用 `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` - 回调函数，在对话框显示后被调用
    - **示例**：
    
    ```html
    <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` - 回调函数，在对话框关闭后被调用

### 🔸 useMessage

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

`function useElMessage(): ElMessageType`

#### 参数

[配置参数详见 `Element-Plus` 官方文档](https://element-plus.org/zh-CN/component/message.html)

#### 返回值

返回一个 `ElMessage` 实例

#### 示例

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

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

const ElMessage = useMessage()

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

// 或

ElMessage.success('提示文本')

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

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

### 🔸 useLoading

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

`function useElLoading(): ElLoadingType`

#### 参数

[配置参数详见 `Element-Plus` 官方文档](https://element-plus.org/zh-CN/component/loading.html)

#### 返回值

返回一个 `ElLoading` 实例

#### 示例

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

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

const ElLoading = useLoading()
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()
```

### 🌳 ColorPickerSetter

引擎内置的颜色设置器 `UI` 组件，用于颜色选择，支持多种格式。

::: info
💡 引擎内置的 `UI` 组件，一般在定制开发组件设置器时使用。
:::

#### 属性

| <div style="width: 60px">属性名</div> | 说明 | <div style="width: 60px">类型</div> | <div style="width: 60px">默认值</div> |
| --- | --- | --- | ---|
| model-value / v-model | 绑定的颜色值 | `string` | — |
| width | 宽度 | `string`  | `100%` |
| size | 尺寸 | `large` \| `default` \| `small` |  `default` |
| show-alpha | 是否支持透明度选择 | `boolean`  | `true` |
| color-format | 写入 `v-model` 的颜色的格式 | `hsl` \| `hsv` \| `hex` \| `rgb` | — |
| rgba-to-hex | 是否将透明值为 1 的 `rgba` 颜色值自动转换为 `hex` 十六进制颜色值 | `boolean`  | `true` |
| predefine | 预定义颜色 | `string[]`  | — |
| popper-class | `ColorPicker` 下拉框的类名 | `string`  | — |
| tooltip | 文字提示 | `string`  | — |
| disabled | 是否禁用状态 | `boolean`  | `false` |
| teleported  | 是否将 `popover` 的下拉列表渲染至 `body` 下 | `boolean` | `true` |

#### 事件

| <div style="width: 60px">事件名</div> | 说明 | 类型 |
| --- | --- | --- |
| updated | 当绑定值更新时触发 | `Function` (value: string) => void |

#### 示例

```html
<template>
<color-picker-setter v-model="color" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ColorPickerSetter } from '@klweb/compose-app-engine/ui'

const color = ref('rgba(19, 206, 102, 0.8)')
</script>
```

### 🌳 NumericUnitSetter

引擎内置的数值单位设置器 `UI` 组件，仅允许输入标准的数字值，可定义范围。

#### 属性

| <div style="width: 60px">属性名</div> | 说明 | <div style="width: 60px">类型</div> | <div style="width: 60px">默认值</div> |
| --- | --- | --- | ---|
| model-value / v-model | 绑定值，如：`20px` 或 `20` | `string` \| `number` | — |
| width | 宽度 | `string`  | `100%` |
| min | 允许的最小值 | `number` |  `-Infinity` |
| max | 允许的最大值 | `number` |  `Infinity` |
| step | 计数器步长 | `number`  | `1` |
| size | 计数器尺寸 | `large` \| `default` \| `small` |  `default` |
| units | 默认单位 | `UnitType[]`  | `['px', '%', 'vw', 'vh', 'rem', 'em']` |
| excludeUnits | 排除某个单位 | `UnitType[]`  | — |
| unUnit | 禁用单位 | `boolean`  | `false` |
| tooltip | 文字提示 | `string`  | — |
| disabled | 是否禁用状态 | `boolean`  | `false` |

#### 类型

```typescript
type UnitType = 
    | 'px' | 'pt' | 'pc' | 'cm' 
    | 'mm' | 'in' | '%' | 'em'
    | 'rem' | 'ex' | 'ch' | 'vw'
    | 'vh' | 'vmax' | 'vmin' | 'deg'
    | 'grad' | 'rad' | 'turn' | 's'
    | 'ms' | 'Hz' | 'kHz' | 'dpi'
    | 'dpcm' | 'dppx'
```

#### 事件

| <div style="width: 60px">事件名</div> | 说明 | 类型 |
| --- | --- | --- |
| updated | 当绑定值更新时触发 | `Function` (value: string \| number) => void |

#### 示例

```html
<template>
<numeric-unit-setter v-model="widthVal" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { NumericUnitSetter } from '@klweb/compose-app-engine/ui'

const widthVal = ref('100px')
</script>
```
