Vue / Nuxt 集成#

在 Vue 或 Nuxt 中直接使用 ideal.house 浏览器 SDK，并使其生成的按钮容器与响应式商品状态保持同步。本指南中没有独立的 ideal.house Vue npm 包。

验证状态： SDK 标记已对照当前 Dashboard 模板进行检查；查阅了 2026年9月7日上 Vue 和 Nuxt 的官方文档。由于没有客户应用程序或生产凭据。

加载 SDK 之前： 打开 Dashboard → 设置，将您的店铺前台来源添加到 Allowed Origins (CORS) 中，然后点击 Save。包含发布的hostname以及任何预览或预发环境来源；多个来源用逗号分隔。参见配置步骤。

前提条件和边界#

准备 Shop ID、Publishable Key、已导入的 SKU 以及响应式已选变体记录。Shop ID 和 Publishable Key 可能客户端可见。将 Client Secrets、AI API 密钥和商品导入凭据保留在服务器上。

最小的 SDK 契约#

html

<script
  src="https://sdk.ideal.house/sdk.js"
  data-shop-id="<SHOP_ID>"
  data-publishable-key="<PUBLISHABLE_KEY>"
  async
></script>

<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>

Product Code 必须与目录 sku 完全匹配。

Vue 组件#

为容器提供一个 key，以便 Vue 在选择的 SKU 变化时创建一个干净的节点：

vue

<script setup lang="ts">
import { computed } from 'vue'

const props = defineProps<{ productCode?: string | null }>()
const code = computed(() => props.productCode?.trim() || '')
</script>

<template>
  <div
    v-if="code"
    :key="code"
    data-idealhouse-button-container
    :data-product-code="code"
  />
</template>

传入规范的已选变体 SKU。如果选择未完成则渲染空，而不是保留之前代码的可见状态。

Nuxt 加载器#

Nuxt 的 useHead 支持外部脚本标签。在 app.vue 或覆盖商品页的布局中注册一次：

vue

<script setup lang="ts">
const config = useRuntimeConfig()

useHead({
  script: [
    {
      key: 'idealhouse-room-visualizer-sdk',
      src: 'https://sdk.ideal.house/sdk.js',
      async: true,
      'data-shop-id': config.public.idealhouseShopId,
      'data-publishable-key': config.public.idealhousePublishableKey,
    },
  ],
})
</script>

仅在 runtimeConfig.public 下配置公共值。对于纯 Vue，将脚本添加到应用程序 HTML 中，或在根组件的 onMounted() 中创建，并使用 querySelector 进行重复检查。浏览器 DOM API 必须在客户端运行。

变体和动态导航#

将 selectedVariant.sku 绑定到组件。有 key 的节点可在无需未文档化的 SDK 方法的情况下处理选项更改。当 Nuxt 路由数据在组件实例被复用时发生变化，计算出的代码更新并且旧容器被销毁。

对于商品网格，每张卡片都需要一个商品级的 SKU 和稳定的 Vue key。无限滚动和过滤器应从状态渲染新组件；切勿复制 SDK 已填充过的 DOM。快速查看抽屉应在关闭时卸载，新商品应获得一个新的组件 key。

如果 SSR 和水合不知道相同的 SKU，则在客户端商品状态就绪之前不渲染按钮，或在页面负载中序列化规范的 SKU。避免仅从渲染的选项文本读取 SKU。

导入商品数据#

将每个商业变体的规范 SKU 映射到 ideal.house 的 sku。使用商品上传及导入商品、任务状态、列出商品、更新商品、删除商品和错误与重试指南。

后端商业客户端、webhooks、计划同步和私有凭据保持在浏览器 SDK 外部。

验证与移除#

测试 SSR/水合、硬重载、客户端导航、浏览器前进/后退、每个变体、空白/未知 SKU、重复卡片、快速查看、<KeepAlive>、加载状态、移动端、同意控件以及生产构建。确认恰好一个 SDK 请求以及准确的 DOM Product Code/SKU 相等性。检查构建产物中的秘密。

要移除，删除 useHead/根加载器以及所有按钮组件，移除公共运行时配置，重新构建，并验证 SDK URL 和 data-idealhouse-* 标记已不存在。