@arronqzy/abuilder-vue 0.1.7 → 0.1.9

package/README.md

@@ -27,6 +27,7 @@ createApp(App).use(Antd).mount("#app");
   :initial-zoom="1"
   default-theme="dark"
   locale="zh-CN"
+  name-space="my-app"
 />
 ```
 
@@ -36,13 +37,71 @@ createApp(App).use(Antd).mount("#app");
 | `initialZoom` | 画布初始缩放 | `1` |
 | `defaultTheme` | `light` / `dark` | `dark` |
 | `locale` | `zh-CN` / `en-US`；省略则按 localStorage → 浏览器 → zh-CN | `null` |
+| `nameSpace` | 隔离 IndexedDB / 缓存；同一页面多个 App 传入不同值 | — |
 | `previewSearch` | 覆盖预览 URL 查询串 | 当前 `location.search` |
+| `preview` | `true` 为预览页（用 `initialWorkspace`），`false` 为编辑面板 | `false` |
+| `initialWorkspace` | 完整工作区；空则首次渲染空白，不会自动打开 IndexedDB 记录 | — |
 
 顶栏「语言」可运行时切换中文 / English（写入 `abuilder.locale`）。Ant Design Vue 的 `ConfigProvider.locale` 会随语言同步。
 
-### 在线预览 URL
+### 编辑 / 预览模式
 
-当 URL 含 `?preview=online&projectId=<id>` 时，自动渲染 `VueViewOnlinePreview`。
+```vue
+<!-- 编辑：把后端工作区灌进面板 -->
+<App :key="workspace.id" :initial-workspace="workspace" />
+
+<!-- 预览：根据同一份数据直接渲染预览页 -->
+<App :key="workspace.id" preview :initial-workspace="workspace" />
+```
+
+切换工作区时建议配合 `key`。URL 含 `?preview=online&projectId=<id>` 时也会进入预览（从 IndexedDB 加载）。传了 `nameSpace` 时预览 URL 会带 `ns=`。
+
+### 外部持久化
+
+创建 / 同步工作区时会发出事件，回调带完整 `WorkspaceData`，请写入自己的后端，不要去调编辑器内部的 IndexedDB：
+
+```ts
+import {
+  addEventSubscription,
+  AbuilderEvents,
+  parseWorkspaceData,
+  type WorkspaceData,
+} from "@arronqzy/abuilder-vue";
+
+const addSub = addEventSubscription(AbuilderEvents.workspaceAdd, async (workspace: WorkspaceData) => {
+  await saveToServer(workspace);
+});
+const syncSub = addEventSubscription(AbuilderEvents.workspaceSync, async (workspace) => {
+  await saveToServer(workspace);
+});
+addSub.unsubscribe();
+syncSub.unsubscribe();
+```
+
+从后端取回后用 `parseWorkspaceData` 规范化，再交给 `initialWorkspace`：
+
+```ts
+import {
+  parseWorkspaceData,
+  createEmptyWorkspace,
+  createWorkspaceProjectId,
+  validateViewData,
+  validateBlueprintData,
+  validateWorkspaceData,
+} from "@arronqzy/abuilder-vue";
+
+const parsed = parseWorkspaceData(jsonFromBackend);
+if (parsed.ok && parsed.value) {
+  // <App :initial-workspace="parsed.value" />
+}
+
+createEmptyWorkspace({ name: "未命名", id: createWorkspaceProjectId() });
+validateWorkspaceData(workspace); // 只检查，不改数据
+```
+
+`validate*` 只回答能不能用。`parseWorkspaceData` 会补齐 `id` / 时间戳 / 空字段。只检查视图或只检查蓝图时用 `validateViewData` / `parseViewData`、`validateBlueprintData` / `parseBlueprintData`。
+
+本包 **没有** `getPreviewSnapshot`（React 的 `@arronqzy/abuilder` 才有画布截图）。Vue 侧若需要缩略图，请自行对预览 DOM 截图，不要假定存在同名导出。
 
 ## 依赖包
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arronqzy/abuilder-vue",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Abuilder Vue 3 可视化编辑器入口包",
   "license": "MIT",
   "type": "module",
@@ -14,8 +14,8 @@
   "dependencies": {
     "ant-design-vue": "^4.2.6",
     "vue": "^3.5.13",
-    "@arronqzy/i18n": "0.1.7",
-    "@arronqzy/vue-view": "0.1.9"
+    "@arronqzy/vue-view": "0.1.11",
+    "@arronqzy/i18n": "0.1.8"
   },
   "peerDependencies": {
     "vue": "^3.4.0"

package/src/App.vue

@@ -9,16 +9,26 @@ import {
   parseOnlinePreviewSearchParams,
 } from "@arronqzy/vue-view";
 import { provideI18n } from "@arronqzy/i18n/vue";
-import { isLocale } from "@arronqzy/i18n";
+import { isLocale, LOCALE_STORAGE_KEY } from "@arronqzy/i18n";
 import type { AbuilderVueAppProps } from "./types";
 
 const props = withDefaults(defineProps<AbuilderVueAppProps>(), {
   initialZoom: 1,
   defaultTheme: "dark",
   locale: null,
+  nameSpace: null,
+  preview: false,
 });
 
-const i18n = provideI18n({ locale: props.locale });
+const localeStorageKey = (() => {
+  const ns = (props.nameSpace ?? "").trim();
+  return ns ? `${LOCALE_STORAGE_KEY}__${ns.slice(0, 120)}` : LOCALE_STORAGE_KEY;
+})();
+
+const i18n = provideI18n({
+  locale: props.locale,
+  storageKey: localeStorageKey,
+});
 
 watch(
   () => props.locale,
@@ -48,14 +58,23 @@ const antdLocale = computed(() =>
     }"
   >
     <VueViewOnlinePreview
-      v-if="previewParams"
+      v-if="props.preview"
+      :workspace="props.initialWorkspace"
+      :project-id="props.initialWorkspace?.id"
+      :name-space="props.nameSpace"
+    />
+    <VueViewOnlinePreview
+      v-else-if="previewParams"
       :project-id="previewParams.projectId"
       :preview-instance-id="previewParams.previewInstanceId"
+      :name-space="previewParams.nameSpace ?? props.nameSpace"
     />
     <VueViewPanel
       v-else
       :class="props.class"
       :initial-zoom="props.initialZoom"
+      :name-space="props.nameSpace"
+      :initial-workspace="props.initialWorkspace"
     />
   </ConfigProvider>
 </template>

package/src/index.ts

@@ -1,9 +1,28 @@
 export { default as App } from "./App.vue";
-export type { AbuilderVueAppProps } from "./types";
+export type { AbuilderVueAppProps, WorkspaceProjectRecord } from "./types";
 export type { Locale } from "@arronqzy/i18n";
 
 export {
   VueViewPanel,
   VueViewOnlinePreview,
   parseOnlinePreviewSearchParams,
+  parseViewData,
+  validateViewData,
+  parseBlueprintData,
+  validateBlueprintData,
+  validateWorkspaceData,
+  parseWorkspaceData,
+  createEmptyWorkspace,
+  createWorkspaceProjectId,
+  addEventSubscription,
+  AbuilderEvents,
+} from "@arronqzy/vue-view";
+export type {
+  ParseCheckResult,
+  WorkspaceParseCheckResult,
+  AbuilderEventName,
+  AbuilderEventPayloadMap,
+  WorkspaceAddEventPayload,
+  WorkspaceSyncEventPayload,
+  WorkspaceData,
 } from "@arronqzy/vue-view";

package/src/types.ts

@@ -1,9 +1,28 @@
+import type { WorkspaceProjectRecord } from "@arronqzy/vue-view";
+
+export type { WorkspaceProjectRecord };
+
 export type AbuilderVueAppProps = {
   class?: string;
   initialZoom?: number;
   defaultTheme?: "dark" | "light";
   previewSearch?: string;
+  /**
+   * 是否为预览模式。`true` 时根据 `initialWorkspace` 直接渲染预览页；`false` 为编辑面板。
+   * @default false
+   */
+  preview?: boolean;
   /** 界面语言。省略时按 localStorage → 浏览器语言 → zh-CN 解析。 */
   locale?: "zh-CN" | "en-US" | null;
+  /**
+   * 隔离 IndexedDB / localStorage / BroadcastChannel。
+   * 同一页面挂多个 App 时传入不同值，避免工作区、蓝图库、预览缓存互相覆盖。
+   * 省略或空字符串保持历史全局库名。
+   */
+  nameSpace?: string | null;
+  /**
+   * 外部传入的完整工作区。省略或空则首次渲染空画布 / 空蓝图，不会自动打开 IndexedDB 中的记录。
+   */
+  initialWorkspace?: WorkspaceProjectRecord | null;
 };