@composy/template-vue

@composy/template-vue

@composy/template-vue 是 @composy/template-core 的 Vue 3 适配层。它复用 core 的注册、查询、运行时和管理器能力，只负责 Vue 组件渲染、组合式 API、指令、上下文注入和插件安装。

职责边界

• 不复制 TemplateRegistry、TemplateManager、TemplateQuery、缓存、版本和实验逻辑。
• 原生 Vue Plugin 与 @composy/engine-core plugin 复用同一条 runtime 安装链路。
• 内置模板通过 scanner 转换为 core 元数据，再交给 core manager 管理。
• 设备监听、模板选择缓存、locale 和 runtime store 保持在 Vue 上下文层，便于组件生命周期清理。

目录结构

src/
  components/   模板渲染、选择器、切换器和基础 UI
  composables/  useTemplate、useTemplateList、useLayout 等组合式 API
  context/      注入 key、runtime store、设备观察、locale 和选择缓存
  directives/   v-template-device 与 v-template-category
  plugin/       原生 Vue Plugin 与共享 runtime 安装逻辑
  plugins/      面向 @composy/engine-core 的 plugin 入口
  scanner/      可注入模块发现器的模板扫描器
  templates/    登录、布局、仪表盘等内置模板
  types/        Vue 侧配置类型

原生 Vue Plugin

import { createTemplatePlugin } from '@composy/template-vue'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.use(
  createTemplatePlugin({
    autoScan: true,
    globalPropertyName: '$templates',
    categories: {
      login: {
        defaultTemplate: 'default',
      },
    },
  })
)

app.mount('#app')

Engine Plugin

import { createVueEngine } from '@composy/engine-vue'
import { createTemplateEnginePlugin } from '@composy/template-vue/plugins'

const engine = createVueEngine({
  plugins: [
    createTemplateEnginePlugin({
      autoScan: true,
      name: 'template',
      version: '1.0.0',
    }),
  ],
})

void engine

常用组合式 API

import { useTemplate, useTemplateList } from '@composy/template-vue'

const { component, error, load, loading, template } = useTemplate(
  'login:desktop:default'
)
const { templates } = useTemplateList('layout')

void component
void error
void load
void loading
void template
void templates

useTemplate() 支持完整 ID，也支持只传分类名并由当前设备和默认模板补全。组件外调用时不会注册 Vue 生命周期钩子，适合单元测试或纯运行时验证。

模板扫描

内置模板使用静态注册表，因此其在 Vite、浏览器 UMD、CJS 和 SSR 环境中的模板集合一致。若应用需要由 Vite 自动发现额外模板，请把 import.meta.glob 显式传给扫描器：

import { createTemplateScanner } from '@composy/template-vue'

const scanner = createTemplateScanner({
  glob: import.meta.glob,
})

const templates = scanner.scan()

void templates

TemplateScanner 不会在包运行时直接调用 import.meta.glob。这使 CommonJS/SSR 导入保持安全；没有提供 glob 时，扫描器返回空列表。非 Vite 构建工具可以传入具有相同签名的模块发现函数。

组件与指令

TemplateSelector 与 TemplateSwitcher 都是 @composy/template-core/web-components 的 Vue 生命周期与事件桥接。模板卡片、预览、标签、下拉定位、选择状态和可访问性由同一个 <ldesign-template-selector> 实现：TemplateSelector 使用 Grid 直出，TemplateSwitcher 使用工具栏图标下拉。Vue 侧只同步响应式模板数据、locale、设备以及 v-model / 回调事件，不发布独立样式包。

<script setup lang="ts">
import { TemplateRenderer, TemplateSelector } from '@composy/template-vue'
</script>

<template>
  <TemplateSelector category="login" />
  <TemplateRenderer template-id="login:desktop:default" />
  <button v-template-device="'desktop'">
    <span> Desktop only </span>
  </button>
</template>

指令只读取 Vue context/runtime store，不直接查询 DOM 外部状态。需要跨框架的匹配或选择逻辑时，应下沉到 core。

构建产物

• dist：浏览器直连/UMD 产物，包含 dist/index.min.js。
• es：ESM 主产物和类型声明。
• esm：ESM 镜像产物。
• lib：CommonJS 产物，入口为 lib/index.cjs。

构建配置位于 .ldesign/builder.config.ts，由 @composy/builder 的 rolldown 引擎生成 dist、es、esm、lib 四类产物。ESLint 和 TypeScript 权威配置位于 .ldesign/；旧路径保留兼容 shim。postbuild 会归一化并检查 exports 与声明文件。

验证命令

pnpm -C packages/template/packages/vue run lint:check
pnpm -C packages/template/packages/vue run type-check
pnpm -C packages/template/packages/vue run build

维护约定

• 新增 composable 前先确认 core 是否已有对应能力。
• 新增内置模板时必须提供 template.config.ts，并保证 scanner 能生成稳定元数据。
• 新增公开子路径后同步 package.json exports、README 和测试。