在純 HTML 和 CSS 網站上整合 Builder.io 指南

, ,
1

在純 HTML 和 CSS 網站上整合 Builder.io 指南

Builder.io 作為一個視覺化內容管理系統，不僅限於現代 JavaScript 框架，也能夠與純 HTML 和 CSS 網站順利整合。本指南將探討如何在不使用 React、Vue 或 Angular 等框架的情況下，將 Builder.io 整合到您的傳統網站中。

HTML API 整合方法

對於純 HTML 和 CSS 網站，HTML API 是最直接的整合方式，因為它不需要複雜的客戶端 JavaScript 代碼：

基本請求結構

Builder.io 的 HTML API 允許您從服務器請求預先渲染的 HTML 內容：

https://cdn.builder.io/api/v3/html/YOUR_MODEL_NAME?apiKey=YOUR_API_KEY&url=PAGE_URL

請求會返回可直接插入網站的 HTML：

{
  "id": "c923kd89",
  "name": "About page",
  "data": {
    "html": "<div data-builder-component=\"banner-ad\"><div class=\"builder-blocks\"><h1>Hello!</h1></div></builder-div>"
  }
}

實現自定義函數

您可以創建一個簡單的 JavaScript 函數來獲取 Builder 內容並顯示在您的網站上：

const getPage = async (model, pageURL, containerId, cacheSeconds = 0) => {
  const encodedPageURL = encodeURIComponent(pageURL);
  const url = `${endpoint}${model}?apiKey=${apiKey}&url=${encodedPageURL}&cacheSeconds=${cacheSeconds}`;
  
  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`Failed to fetch content: ${response.statusText}`);
    }
    const data = await response.json();
    const contentDiv = document.getElementById(containerId);
    if (!contentDiv) {
      throw new Error(`Container element not found: ${containerId}`);
    }
    contentDiv.innerHTML = data.data.html;
  } catch (error) {
    console.error('Error fetching content:', error.message);
  }
};

這個函數接受四個參數：模型名稱、頁面 URL、容器元素 ID 和緩存時間。您可以在網站的適當位置調用此函數來加載 Builder 內容。

Web Components API 整合

Builder.io 也提供 Web Components API，這是另一種在純 HTML 網站上整合的方法：

<builder-component model="page" api-key="YOUR_API_KEY">
  <!-- 內容加載時顯示的 HTML，例如加載動畫 -->
</builder-component>
<script async src="https://cdn.builder.io/js/webcomponents"></script>

Web Components API 提供更多動態功能，包括：

  1. 自動重新加載（當 URL 變化時）
  2. 事件處理（加載完成、錯誤等）
  3. 高級配置選項

支援的屬性

  • model（必填）：您的頁面或組件模型名稱
  • api-key（必填）：您的 Builder 公共 API 密鑰
  • entry（可選）：按 ID 加載特定 Builder 條目
  • reload-on-route（可選）：當瀏覽器 URL 變化時重新加載
  • options（可選）：自定義內容請求的選項

內容預覽設置

要在您的網站上預覽 Builder 內容，需要特別設置預覽功能：

  1. 在您的網站上創建一個路由（例如 /builder-preview）
  2. 此路由應服務 Builder 預覽 HTML 和 JavaScript
  3. 在 Builder 中設置預覽 URL，指向您的網站

這樣，您就可以在 Builder 編輯器中實時預覽更改如何在您的實際網站上顯示。

使用您網站的 CSS 樣式

Builder.io 元素可以應用您現有網站的 CSS 樣式。在 Builder 編輯器中：

  1. 點擊元素
  2. 點擊「STYLE」標籤
  3. 滾動到底部，找到「advanced」下的「CSS-classes」部分
  4. 添加您想應用的 CSS 類名

這使您可以保持網站的一致設計語言，而無需在 Builder 中重新創建所有樣式。

自定義代碼考量

Builder.io 允許您添加自定義 JavaScript 和 CSS 到內容中：

  1. 您可以訪問瀏覽器事件和狀態屬性
  2. 管理狀態和操作
  3. 添加事件處理程序

需要注意的是，有時自定義代碼在預覽中可能正常工作，但在發布的網站上可能不起作用。確保仔細測試您的集成。

限制和注意事項

使用 HTML API 進行集成時存在一些限制：

  1. 自定義組件不兼容：HTML API 不支持自定義組件功能，只支持 Builder 的內置組件
  2. 預覽配置：需要特殊設置才能正確預覽內容
  3. 客戶端交互有限：與完整 SDK 相比，HTML API 提供的客戶端交互功能較少

整合最佳實踐

  1. 緩存策略：使用 cacheSeconds 參數優化性能，為頻繁變化的內容設置較短的緩存時間，為靜態內容設置較長的緩存時間
  2. 漸進式增強：先實現基本 HTML API 集成，再根據需要添加更多功能
  3. 環境分離：為開發、測試和生產環境設置不同的 Builder.io 環境
  4. 錯誤處理：實現適當的錯誤處理，確保在加載失敗時顯示後備內容

結論

雖然 Builder.io 常與現代 JavaScript 框架一起使用，但它也為純 HTML 和 CSS 網站提供了完善的整合方案。HTML API 和 Web Components API 都提供了將 Builder 內容整合到傳統網站的方法，讓您能夠利用其視覺編輯和內容管理功能，同時保持網站的簡單性和性能。

選擇哪種方法取決於您的特定需求：如果您需要最簡單的解決方案，HTML API 是理想選擇；如果您需要更多客戶端功能和事件處理，Web Components API 可能更合適。無論您選擇哪種方法，Builder.io 都能為您的純 HTML 和 CSS 網站帶來強大的內容管理能力。