快速开始

这一页只讲“宿主项目怎么把 HyperCard SDK 跑起来”。业务后台、权限、组件库管理都不是 SDK 自己做。

安装

pnpm add @hy-bricks/core @hy-bricks/canvas @hy-bricks/editor @hy-bricks/devtools

真实接入分三步走:注入 / 渲染 / 数据对接,下面逐步说明。

样式怎么生效

SDK 的 SFC <style> 都通过 vite-plugin-css-injected-by-js 内联在 JS bundle 里,host import 时样式自动生效:

包	host 需要 import CSS 吗?
@hy-bricks/core	否(无 SFC 样式)
@hy-bricks/canvas	否(选中框 / 标尺 / runtime wrapper 全自动)
@hy-bricks/editor	shadcn 主题 仍需 import '@hy-bricks/editor/style.css'(那是 tailwind utility,跟 SFC 无关);组件内部样式自动
@hy-bricks/devtools	否(浮窗样式 + auto subpath 双注入)

editor 还要在宿主 tailwind.config.js extend preset:

import hyBricksPreset from '@hy-bricks/editor/tailwind-preset'
export default {
  presets: [hyBricksPreset],
  content: ['./index.html', './src/**/*.{vue,ts,tsx}'],
}

注册运行时

@hy-bricks/core 提供 createHyperCard()。宿主把 Vue 插件、图表库、HTTP 客户端、业务函数都从这里注入。

import { createApp } from 'vue'
import { createHyperCard } from '@hy-bricks/core'
import ElementPlus from 'element-plus'
import * as echarts from 'echarts'
import App from './App.vue'
import { http } from './http'

const app = createApp(App)

app.use(createHyperCard({
  libs: {
    ui: ElementPlus,
    echarts,
    http,
  },
}))

app.mount('#app')

组件源码里可以访问:

__HYPERCARD__.libs.echarts
__HYPERCARD__.libs.http
__HYPERCARD__.canvases

渲染一个页面

运行态只需要拿到 PageRenderPayload。

<script setup lang="ts">
import { HyperCardPageRenderer } from '@hy-bricks/canvas'

const payload = await api.pages.getRender(pageId)
</script>

<template>
  <HyperCardPageRenderer
    :payload="payload"
    canvas-id="dashboard-card-a"
  />
</template>

如果你是自己造 PageDocument(不走后端),用 helper 别手写:

import { createMinimalPageDocument } from '@hy-bricks/canvas'

const doc = createMinimalPageDocument({
  canvasWidth: 1280,
  canvasHeight: 720,
  instances: [/* PageInstance[] */],
})

createMinimalPageDocument / createFreePageDocument 直接输出 normalize 后的 v1 形态(layout: { type, canvas: { width, height }, rootLayout }),避免手写时忘 rootLayout 或把 layout 写成字符串(把 layout 写成字符串是旧 schema,typecheck 会拒)。完整字段见 PageDocument 概念。

接入设计器

设计态用 HyperCardCanvasDesigner。宿主保管 PageDocument,SDK 通过 v-model 更新它。

<script setup lang="ts">
import { ref } from 'vue'
import { HyperCardCanvasDesigner, type CanvasHandle } from '@hy-bricks/canvas'

const document = ref(page.document)
const sourceMap = ref(page.componentVersions)
const handle = ref<CanvasHandle | null>(null)
</script>

<template>
  <HyperCardCanvasDesigner
    v-model="document"
    :component-source-map="sourceMap"
    @handle-ready="handle = $event"
  />
</template>

接入编辑器

组件源码编辑器是受控组件。它不自己请求后端,也不判断权限。

<script setup lang="ts">
import { HyperCardEditor } from '@hy-bricks/editor'
</script>

<template>
  <HyperCardEditor
    v-model="source"
    :features="{ showHistory: true, showDiff: true, enablePublish: true }"
    @open-history="openHistoryDrawer"
    @open-diff="openDiffDialog"
  />
</template>

开开发期诊断浮窗

DEV 模式建议把 @hy-bricks/devtools 浮窗装上 —— 看 hit-test / drag / render 失败的真实原因比看 console 强。

import { enableHyBricksDiagnostics } from '@hy-bricks/devtools'

if (import.meta.env.DEV) {
  enableHyBricksDiagnostics({ level: 'debug' })
}

canvases 是可选的 — 单 demo / 简单场景一行就够,SDK 内部 fallback(createCanvasesRegistry() 是同一份全局 instanceRegistry 的视图,不是独立内存池)。复杂多画布建议显式传同一份 registry,语义清晰 + 初始化顺序可控,见 devtools API。

下一步

• 踩坑了:读 常见问题排查。
• 想了解包边界:读 SDK 包边界。
• 想跑运行态:读 渲染一个页面。
• 想做设计器:读 设计器接入。
• 想理解布局:读 LayoutBox 布局模型。