@cimom/vben-core-composables

Vue 组合式 API 工具集，提供了一系列可复用的组合式函数（Composables），用于简化 Vue 应用开发中的常见任务。

安装

npm install @cimom/vben-core-composables

可用组合式函数

useIsMobile

检测当前设备是否为移动设备。

import { useIsMobile } from '@cimom/vben-core-composables';

const { isMobile } = useIsMobile();

// 使用示例
if (isMobile.value) {
  // 执行移动设备相关逻辑
}

返回值：

• isMobile: Ref<boolean> - 是否为移动设备

useLayoutStyle

用于管理布局样式，包括头部和页脚的高度设置。

import {
  useLayoutHeaderStyle,
  useLayoutFooterHeight,
} from '@cimom/vben-core-composables';

// 设置头部高度
const { setLayoutHeaderHeight, layoutHeaderHeight } = useLayoutHeaderStyle();
setLayoutHeaderHeight(60);

// 设置页脚高度
const { setLayoutFooterHeight, layoutFooterHeight } = useLayoutFooterStyle();
setLayoutFooterHeight(40);

返回值：

• setLayoutHeaderHeight: (height: number) => void - 设置头部高度的函数
• layoutHeaderHeight: Ref<number> - 头部高度值
• setLayoutFooterHeight: (height: number) => void - 设置页脚高度的函数
• layoutFooterHeight: Ref<number> - 页脚高度值

useNamespace

用于生成带命名空间的 CSS 类名，便于组件样式隔离。

import { useNamespace } from '@cimom/vben-core-composables';

// 创建一个命名空间为 'button' 的工具
const ns = useNamespace('button');

// 使用示例
const classes = {
  base: ns.b(), // 'vben-button'
  primary: ns.m('primary'), // 'vben-button--primary'
  disabled: ns.is('disabled'), // 'is-disabled'
  icon: ns.e('icon'), // 'vben-button__icon'
};

参数：

• block: string - 组件的基础名称

返回值：

• b: () => string - 返回基础类名
• e: (element: string) => string - 返回元素类名
• m: (modifier: string) => string - 返回修饰符类名
• be: (block: string, element: string) => string - 返回块元素组合类名
• em: (element: string, modifier: string) => string - 返回元素修饰符组合类名
• bm: (block: string, modifier: string) => string - 返回块修饰符组合类名
• bem: (block: string, element: string, modifier: string) => string - 返回块元素修饰符组合类名
• is: (name: string, state?: boolean) => string - 返回状态类名

usePriorityValues

用于处理具有优先级的属性值，可以从多个来源获取值并按优先级返回。

import { usePriorityValues } from '@cimom/vben-core-composables';

const props = {
  title: '默认标题',
  showIcon: true,
};

const state = ref({
  title: '状态标题',
  showIcon: false,
});

// 使用示例
const { title, showIcon } = usePriorityValues(props, state);
console.log(title.value); // '状态标题' (state 优先级高于 props)

参数：

• sources: ...any[] - 多个值来源，按优先级从低到高排列

返回值：

• 包含所有属性的响应式对象，每个属性都是一个 Ref

useScrollLock

用于锁定/解锁页面滚动。

import { useScrollLock } from '@cimom/vben-core-composables';

const { lockScroll, unlockScroll } = useScrollLock();

// 锁定滚动
lockScroll();

// 解锁滚动
unlockScroll();

返回值：

• lockScroll: () => void - 锁定滚动的函数
• unlockScroll: () => void - 解锁滚动的函数

useSimpleLocale

简化的国际化工具，用于获取和设置语言。

import { useSimpleLocale } from '@cimom/vben-core-composables';

const { $t, locale, setLocale } = useSimpleLocale();

// 翻译文本
const welcomeText = $t('welcome');

// 获取当前语言
console.log(locale.value); // 'zh-CN'

// 设置语言
setLocale('en-US');

返回值：

• $t: (key: string) => string - 翻译函数
• locale: Ref<string> - 当前语言
• setLocale: (locale: string) => void - 设置语言的函数

useSortable

用于实现元素拖拽排序功能。

import { useSortable } from '@cimom/vben-core-composables';

// 在组件中使用
const containerRef = ref<HTMLElement | null>(null);

// 初始化排序功能
const { destroy } = useSortable(containerRef, {
  animation: 150,
  onEnd: (evt) => {
    console.log('排序结束', evt.oldIndex, evt.newIndex);
  },
});

// 组件卸载时销毁
onUnmounted(() => {
  destroy();
});

参数：

• el: Ref<HTMLElement | null> - 容器元素引用
• options: SortableOptions - Sortable.js 配置选项

返回值：

• destroy: () => void - 销毁排序功能的函数

从 radix-vue 导出的工具

import {
  useEmitAsProps,
  useForwardExpose,
  useForwardProps,
  useForwardPropsEmits,
} from '@cimom/vben-core-composables';

// useEmitAsProps: 将组件的 emit 事件转换为 props
// useForwardExpose: 转发组件暴露的属性和方法
// useForwardProps: 转发组件的 props
// useForwardPropsEmits: 同时转发组件的 props 和 emits

使用示例

在组件中使用 useNamespace 和 useIsMobile

<template>
  <div :class="[ns.b(), isMobile ? ns.m('mobile') : '']">
    <header :class="ns.e('header')">
      <h1 :class="ns.e('title')">标题</h1>
    </header>
    <main :class="ns.e('content')">内容区域</main>
  </div>
</template>

<script setup lang="ts">
import { useNamespace, useIsMobile } from '@cimom/vben-core-composables';

const ns = useNamespace('layout');
const { isMobile } = useIsMobile();
</script>

使用 usePriorityValues 处理组件属性

<template>
  <div>
    <h1>{{ title }}</h1>
    <button v-if="showButton">点击</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { usePriorityValues } from '@cimom/vben-core-composables';

const props = defineProps({
  title: { type: String, default: '默认标题' },
  showButton: { type: Boolean, default: true },
});

const state = ref({
  title: '状态中的标题',
});

// 优先使用 state 中的值，如果没有则使用 props 中的值
const { title, showButton } = usePriorityValues(props, state);
</script>