@hy-bricks/experimental-vue-page-importer

实验性独立可选包。.vue 文件 → opaque page 导入(整页一张画布,内部 DOM 不可单独编辑)。

npm dist-tag experimental,不进主 4 包。MVP 2026-05-25 playground 验证通过。

---

功能语义

上传 .vue 文件 → 平台生成一张可渲染画布。

跟"组件库导入"不同:

• ❌ 不是把 .vue 拆成多个 hc 组件
• ❌ 不是让用户在画布上单独编辑内部 DOM 元素
• ✅ 是整页一张画布,挂一个根组件,用户可以加旁路装饰但不能拆动内部 DOM

适用:把现有 Vue 单文件页面(Login.vue / Dashboard.vue)快速搬进平台,享受 SDK 的多画布编排 + 数据绑定 + 主题切换。

安装

pnpm add @hy-bricks/experimental-vue-page-importer@experimental

@experimental tag 必需(不带 tag 装会"version not found")。

强边界(★ 必读)

1. 不改 runtime / compileComponent / RuntimeBox / PageDocument 主协议
2. @vue/compiler-sfc 只在本包(主 bundle 不带,605 KB / gzip 193 KB lazy chunk 只在访问时下载)
3. release 双层隔离(package.json release 字段 + .changeset/config.json ignore)
4. bundle 实测:主 bundle 仅 +1 KB,experimental lazy chunk 只在访问 /vue-import 时下载

API

function importVuePage(source: string, options?: ImportVuePageOptions): ImportResult

interface ImportVuePageOptions {
  pageId?: string
  fileName?: string
  componentVersionKey?: string  // 默认 'vue-import@1'
}

interface ImportResult {
  ok: boolean
  document?: PageDocument
  componentVersionAsset?: ComponentVersionAsset
  diagnostics: ImportDiagnostic[]
}

用法

<script setup lang="ts">
import { ref } from 'vue'
import { HyperCardPageRenderer, type PageDocument } from '@hy-bricks/canvas'
import { importVuePage } from '@hy-bricks/experimental-vue-page-importer'

const document = ref<PageDocument | null>(null)
const sourceMap = ref(null)

async function onUpload(file: File) {
  const text = await file.text()
  const result = importVuePage(text, { fileName: file.name })
  if (result.ok && result.document && result.componentVersionAsset) {
    document.value = result.document
    sourceMap.value = { [result.componentVersionAsset.key]: result.componentVersionAsset }
  }
}
</script>

<template>
  <input type="file" accept=".vue" @change="onUpload($event.target.files[0])" />
  <section v-if="document" class="h-[600px]">
    <HyperCardPageRenderer
      :document="document"
      :component-source-map="sourceMap"
      canvas-id="vue-import-page"
    />
  </section>
</template>

playground demo

pnpm --filter @hy-bricks/playground dev
# 浏览器:/vue-import
# 点「载入示例」→ 真渲染 + click button → count 响应式递增

verified 2026-05-25:playwright e2e 7/7 全过 + 0 console error。

MVP 不含(挂后续)

• npm publish(脚本就位,需要时单独发布)
• 业务宿主接入
• 结构化拆节点(范围外,需另起 HC 标注 DSL)