@composy/3d-viewer-vue

@composy/3d-viewer-vue

@composy/3d-viewer-core 的 Vue 3 适配层：提供 PanoramaViewer 组件（含加载 / 错误插槽与完整方法暴露）、useBookmarks 等组合式函数以及全局插件桥接，让全景查看器以声明式方式接入 Vue 应用。

✨ 核心能力

• 🗺️ 声明式组件：PanoramaViewer 封装核心运行时，Props 直传、事件透出
• 🧩 插槽体系：默认插槽 + loading / error / controls / info 四个具名插槽
• 🛠️ 方法全暴露：通过 defineExpose 暴露核心全部公开方法，可用模板 ref 直接调用
• 🧰 组合式函数：usePanoramaViewer、useHotspots、useFullscreen、useBookmarks、useColorAdjustment、usePerformance、useAutoTour
• 🔌 全局插件：createVuePlugin / createEnginePlugin 注入共享配置与引擎扩展
• 🎨 Token 化样式：DOM 类名使用 ldesign-3d-viewer* 命名空间，样式基于 --ldesign-3d-viewer-* 与 --ld-* 变量

📦 安装

pnpm add @composy/3d-viewer-vue @composy/3d-viewer-core three vue

Peer 依赖：@composy/3d-viewer-core ^0.0.1、three ^0.160.0、vue ^3.5.32。

子路径导出：.、./composables/*、./plugins/*，样式入口 ./index.css、./index.min.css。

🚀 快速开始

<script setup lang="ts">
import { PanoramaViewer } from '@composy/3d-viewer-vue'

function onReady() {
  console.log('viewer 已就绪')
}

function onError(error: Error) {
  console.error(error)
}
</script>

<template>
  <PanoramaViewer
    image="/panorama.jpg"
    :auto-rotate="true"
    :viewer-options="{
      zoomIndicator: true,
      helpOverlay: true,
    }"
    @ready="onReady"
    @error="onError"
  >
    <template #controls="{ viewer }">
      <button @click="viewer?.setFov(60)">缩小视野</button>
    </template>
  </PanoramaViewer>
</template>

注意：viewer-options 接受 ViewerOptions 去掉 container / eventBus 后的任意子集；不存在 sharePanel、loadingIndicator 这类字段。

📖 API 参考

PanoramaViewer Props（默认值来自源码）

Emits

Slots

组合式函数与插件

import {
  createEnginePlugin,
  createVuePlugin,
  useAutoTour,
  useBookmarks,
  useColorAdjustment,
  useFullscreen,
  useHotspots,
  usePanoramaViewer,
  usePerformance,
} from '@composy/3d-viewer-vue'

• usePanoramaViewer(options)：创建并管理查看器生命周期，返回 UsePanoramaViewerReturn
• useBookmarks(viewer, options?)：书签的创建与动画恢复（支持 RestoreBookmarkOptions）
• useHotspots(viewer) / useFullscreen(viewer)：热点管理与全屏切换（入参为 Ref<PanoramaViewer | null>）
• useColorAdjustment / usePerformance / useAutoTour：调色、性能与自动导览的状态化封装
• createVuePlugin(options) / createEnginePlugin(options)：应用级插件入口

主入口同时重导出核心类型：ViewerOptions、ViewerSnapshot、Hotspot、Bookmark、MarkerInput、QualityPreset 等。

🎨 样式与主题

• 组件与核心运行时共用 ldesign-3d-viewer 类名前缀；组件状态类同样遵循该命名空间。
• 请确保宿主应用已加载 LDesign color / size token 样式；组件引用 --ld-bg-elevated、--ld-text-inverse、--ld-spacing-*、--ld-font-*、--ld-radius-*、--ld-px-* 等变量。
• 可在组件根上覆盖查看器变量：

.ldesign-3d-viewer {
  --ldesign-3d-viewer-height: var(--ld-px-720);
  --ldesign-3d-viewer-panel-bg: var(--ld-bg-elevated);
  --ldesign-3d-viewer-accent: var(--ld-primary-default);
}

按需引入样式：import '@composy/3d-viewer-vue/index.css'。

🔨 构建产物与验证

使用 @composy/builder 构建，产出：

packages/vue/
├─ dist/  浏览器产物与样式：index.js、index.min.js、index.css、index.min.css
├─ es/    ESM（含类型声明）
├─ esm/   保留模块结构的 ESM
└─ lib/  CommonJS（含类型声明）

配置入口：.ldesign/builder.config.ts、.ldesign/tsconfig.typecheck.json、.ldesign/tsconfig.cjs.json、.ldesign/eslint.config.js。旧的根级配置文件仅转发到这些权威配置。

验证命令（取自包 package.json）：

pnpm type-check      # ESM 与 CJS 类型检查
pnpm build           # builder + 产物归一化与契约检查
pnpm test            # ltesting run:unit
pnpm lint:check       # strict ESLint，--max-warnings 0

🔗 相关链接

• 工作区总览
• @composy/3d-viewer-core — 核心运行时完整 API 与样式契约
• Playground — 可运行示例与使用文档（pnpm playground:dev）