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

$3

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

function useGetAppInstance(): App

#### 参数

无

#### 返回值

返回 App 实例对象

#### 示例

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

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

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

$3

获取当前应用 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
`

$3

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

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()
`

$3

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

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
`

$3

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

function useGetCompTreeByPath(path: string): CompNodeType[]

#### 参数

|

名称

|

类型

|

默认值

| 描述 |
| ---- | -------- | --- | --------- |
| path | string | — | 路由 path，如：/xxx |

#### 返回值

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

#### 示例

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

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

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

$3

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

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
}
})
`

$3

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

function useGetAppRoute(): AppRouteType

#### 参数

无

#### 返回值

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

#### 示例

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

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

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

$3

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

function useGetGlobalProperties(): GlobalPropertiesType

#### 参数

无

#### 返回值

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

#### 示例

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

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

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

$3

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

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

#### 参数

|

名称

|

类型

|

默认值

| 描述 |
| --- | --- | --- | ---|
| 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!
`

$3

接受一个内部值，返回一个响应式的、可更改的 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)
`

$3

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

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++
`

$3

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

function useComputed(): typeof computed

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

#### 参数

无

#### 返回值

返回一个 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
`

$3

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

function useWatch(): typeof watch

::: info
💡 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) => {
// ...
})
`

$3

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

function useToRefs(): typeof toRefs

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

#### 参数

无

#### 返回值

返回一个 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)
`

$3

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

function useToValue(): typeof toValue

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

#### 参数

无

#### 返回值

返回一个 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
`

$3

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

function useToRaw(): typeof toRaw

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

#### 参数

无

#### 返回值

返回一个 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
`

$3

ref() 的浅层作用形式。

function useShallowRef(): typeof shallowRef

::: info
💡 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 }
`

$3

reactive() 的浅层作用形式。

function useShallowReactive(): typeof shallowReactive

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

#### 参数

无

#### 返回值

返回一个 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++
`

$3

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

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
`

$3

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

function useOnMounted(): typeof onMounted

#### 参数

无

#### 返回值

返回一个 onMounted 函数

#### 示例

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

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

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

$3

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

function useOnUnmounted(): typeof onUnmounted

#### 参数

无

#### 返回值

返回一个 onUnmounted 函数

#### 示例

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

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

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

$3

等待下一次 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();
//...
`

$3

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

function useOnUpdated(): typeof onUpdated

#### 参数

无

#### 返回值

返回一个 onUpdated 函数

#### 示例

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

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

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

$3

获取当前组件内部实例。

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 实例对象
`

$3

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

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

::: info
💡 如一个组件使用了
`

- ##### close

useDialog.close(callback?: Callback): void

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

$3

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

function useElMessage(): ElMessageType

#### 参数

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

#### 返回值

返回一个 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('提示文本')
`

$3

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

function useElLoading(): ElLoadingType

#### 参数

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

#### 返回值

返回一个 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()
`

$3

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

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

#### 属性

|

属性名

| 说明 |

类型

|

默认值

|
| --- | --- | --- | ---|
| 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 |

#### 事件

|

事件名

| 说明 | 类型 |
| --- | --- | --- |
| updated | 当绑定值更新时触发 | Function (value: string) => void |

#### 示例

`html



`

$3

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

#### 属性

|

属性名

| 说明 |

类型

|

默认值

|
| --- | --- | --- | ---|
| 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'
`

#### 事件

|

事件名

| 说明 | 类型 |
| --- | --- | --- |
| updated | 当绑定值更新时触发 | Function (value: string \| number) => void |

#### 示例

`html



``