@lumal/core

后台核心包：应用安装器、布局、路由菜单、权限、请求、主题与基础组件。

项	值
包名	@lumal/core
本地路径	packages/core
在线文档	https://lumal.cuteyuchen.top/packages/core
npm 地址	https://www.npmjs.com/package/@lumal/core
详细 API	Core API

安装

pnpm add @lumal/core@0.0.4-beta @lumal/icons@0.0.4-beta @lumal/icons-vue@0.0.4-beta vue@^3.5 vue-router@^4.5 element-plus@^2.11 @iconify/vue@^5

Pinia 按需安装。只使用 minimal / request 等纯服务入口时无需 UI peer，详见 安装与包地址。

本地 monorepo：

{ "dependencies": { "@lumal/core": "workspace:*" } }

公开入口

入口	用途
@lumal/core	createLumalAdmin 等根导出
@lumal/core/minimal	无默认 UI 注册表的轻启动入口
@lumal/core/components	Schema 表单/表格、Page、CRUD 等
@lumal/core/layout	LumalLayout、侧栏、标签、Header 等
@lumal/core/router	菜单路由运行时
@lumal/core/permission	权限 Store / 上下文
@lumal/core/request	createRequestClient
@lumal/core/theme	偏好 Store、主题应用
@lumal/core/dictionary	字典上下文
@lumal/core/auth	认证相关导出
@lumal/core/composables	组合式 API
@lumal/core/directives	权限指令等
@lumal/core/utils	工具
@lumal/core/style.css	运行时 CSS
@lumal/core/theme-chalk/index.scss	主题 SCSS 变量与样式

默认 UI 启动

下例显式使用 Pinia，另需安装 pinia@^3.0.3；框架不会自动创建或安装 Pinia。

import { createLumalAdmin } from '@lumal/core'
import ElementPlus from 'element-plus'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
import { createPinia } from 'pinia'
import { createRouter, createWebHistory } from 'vue-router'
import '@lumal/core/theme-chalk/index.scss'
import '@lumal/core/style.css'
import '@lumal/icons-vue/style.css'
import App from './App.vue'

const router = createRouter({
  history: createWebHistory(),
  routes: [],
})

const framework = createLumalAdmin({
  preset: 'admin-default',
  rootComponent: App,
  router,
  pinia: createPinia(),
  elementPlus: {
    plugin: ElementPlus,
    options: { locale: zhCn },
  },
  dictionary: {
    fetcher: async () => ({ items: [] }),
  },
  icons: {
    localSvg: [],
  },
  components: true,
  setup: ({ app }) => {
    // 应用级扩展
  },
})

await framework.mount('#app')

createLumalAdmin 要点

• preset：admin-default | minimal；不内部创建 Pinia
• elementPlus：支持 Plugin 或 { plugin, options }
• components：true / false / 组件名数组 / 组件映射
• mount() 异步：等待 setup 与 router.isReady()
• 安装顺序：本地图标 → 字典 → pinia → router → elementPlus → components

轻启动

import { createLumalAdmin } from '@lumal/core/minimal'
await createLumalAdmin({ rootComponent: App }).mount('#app')

轻入口默认不安装字典，只接受显式组件映射，不静态加载 Element Plus、Sortable 或图表引擎。根入口的 preset: 'minimal' 只关闭默认组件注册，不是隔离体积的入口。纯服务子入口也不需要 Element Plus；使用 UI 组件仍需对应 peer 与样式。

组件（@lumal/core/components）

• LumalSchemaForm / LumalSchemaTable / LumalCrudTable
• LumalPage / LumalPageLayout / LumalPagination / LumalInfoTable
• LumalIcon / LumalIconPicker / LumalIconPickerDialog（也可从 @lumal/icons-vue 引入）

Schema 表单示例

<script setup lang="ts">
import type { SchemaFormItem, SchemaFormModel } from '@lumal/core/components'
import { LumalSchemaForm } from '@lumal/core/components'
import { shallowRef } from 'vue'

const model = shallowRef<SchemaFormModel<{ name: string, status: string }>>({})
const schemas: SchemaFormItem[] = [
  { field: 'name', label: '名称', component: 'input', rules: [{ required: true, message: '必填' }] },
  { field: 'status', label: '状态', dictionary: 'status' },
]
</script>

<template>
  <LumalSchemaForm v-model="model" :schemas="schemas" show-actions />
</template>

内置控件：input、textarea、select、number、switch、date、datetime、daterange、radio、checkbox、tree-select、upload、hidden。

布局

<script setup lang="ts">
import { LumalLayout, LumalRouterView } from '@lumal/core/layout'
</script>

<template>
  <LumalLayout
    title="My Admin"
    :menus="menus"
    :preferences="preferences"
    route-driven
    tab-storage-key="my-admin:tabs"
  >
    <LumalRouterView />
  </LumalLayout>
</template>

布局支持侧栏 / 顶栏 / 混合导航、标签固定与淘汰策略、全局搜索、面包屑、移动抽屉等。字段与偏好细节见 Core API。

路由与菜单

import { createMenuRouteRuntime } from '@lumal/core/router'

const runtime = createMenuRouteRuntime({
  router,
  staticMenus,
  loadRemoteMenus: () => api.fetchMenus(),
  componentResolver: (name) => viewModules[name],
  hasPermission: codes => permissionStore.hasPermission(codes),
})

标准菜单语义字段：path、name、component、children、meta.title、meta.authority、meta.activeMenu、meta.badge。非标准结构在应用层映射，勿写入 core。

请求

import { createRequestClient } from '@lumal/core/request'

const client = createRequestClient({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  getToken: () => session.accessToken,
  getCacheScope: () => currentTenantId,
  authRefresh: { refresh: () => auth.refresh() },
})

支持统一错误、接口适配、Token 刷新单飞与安全重放。分页标准形态：{ items, total }。

缓存默认关闭，非 GET 缓存必须显式给出 key。退出或切换上下文时调用 client.clearCache()；Authorization 或 getCacheScope() 变化也会自动失效。完整缓存与标签视图生命周期契约见 Core API。

主题与偏好

import { createPreferencesStore, applyThemePreferences } from '@lumal/core/theme'

const store = createPreferencesStore({
  storage: localStorage,
  storageKey: 'app:preferences',
  defaults: { theme: { mode: 'system', colorPrimary: '#1677ff' } },
})

store.patch({ theme: { mode: 'dark' } })

与示例对齐

参考 apps/lumal-admin/src/main.ts 的完整接入：Element Plus 暗色 CSS 变量、本地 SVG 图标、权限 Store、字典 fetcher 与 SCSS 入口。

边界

• Element Plus / vue-router / pinia 为 peer，由应用安装
• 不默认引入 i18n、VXE、ECharts
• 业务状态码与字段映射留在应用层