在開發 kintone 客製化 JavaScript 程式碼時，執行過程中可能因各種錯誤導致程式中斷，進而影響預期的業務流程。例如，當客製化程式碼應在表單流程推進時，自動同步更新另一個應用程式的記錄，卻因程式錯誤導致資料未能正確更新。

若缺乏適當的錯誤提示，使用者與開發者可能無法即時察覺問題，進而影響系統的可靠性與使用者體驗。因此，在 kintone 客製化開發中，建立完善的錯誤處理機制至關重要。

使用 try...catch 語法捕捉錯誤

在處理錯誤之前，首先必須確保能夠正確捕捉程式執行過程中的異常情況。我們可以在 kintone 事件處理器（event handler）中使用 try...catch 語法，將主要邏輯放入 try 區塊內，一旦發生錯誤，錯誤訊息就會被拋至 catch 區塊，讓我們能夠適當處理並記錄錯誤。以下是範例程式碼：

kintone.events.on('...', event => {
  try {
    // 執行主要邏輯
  } catch (error) {
    console.error('發生錯誤:', error);
  }  
  return event;
});

需要特別注意的是，在 event handler 內渲染自訂元素並為其附加事件監聽器（event listener）時，事件監聽器的觸發時機是在 event handler 執行結束之後。因此，當 event listener 內部發生錯誤時，這些錯誤不會被 event handler 內的 try...catch 捕捉，而必須獨立處理。

以下是一個範例：

kintone.events.on('...', event => {
  try {
    const spaceEl = kintone.app.record.getSpaceElement('button-space');
    const button = document.createElement('button');
    spaceEl.appendChild(button);

    button.addEventListener('click', () => {
      try {
        // 這裡的錯誤需要在事件監聽器內部獨立處理
      } catch (error) {
        console.error('按鈕點擊事件發生錯誤:', error);
      }
    });
  } catch (error) {
    console.error('事件處理器發生錯誤:', error);
  }  
  return event;
});

顯示錯誤提示的方法

上一節示範了如何捕捉程式錯誤，並透過 console.error() 在開發者工具的主控台顯示錯誤訊息。然而，一般使用者並不會隨時開啟開發者工具，因此需要建立適當的錯誤提示機制，以便即時通知使用者程式發生錯誤。以下介紹幾種顯示錯誤提示的方法。

方法一：使用 kintone 的 event.error

在特定情境下，event 物件提供 error 屬性，允許我們設定錯誤訊息，讓 kintone 直接顯示提示。使用方式相當簡單，只需對 event.error 賦值，如下所示：

kintone.events.on('app.record.create.submit', event => {
  try {
    const { record } = event;
    const content = record['內容'].value || '';

    if (content.length < 20) {
      throw new Error('內容至少需填20字！'); // 自訂錯誤訊息
    }

  } catch (error) {
    console.error('發生錯誤:', error); // 主控台顯示完整錯誤，供開發者除錯
    event.error = error.message; // 顯示錯誤訊息給使用者
  }  
  return event; // 必須 return event，`event.error` 才會生效
});

運作方式解析

• event.error 設定錯誤訊息後，kintone 會自動顯示錯誤提示，阻止提交記錄。
• return event 必須保留，否則 event.error 不會生效。
• event.error 的效果類似 return false，會終止記錄的提交動作。

以上述範例來說，當使用者在「內容」欄位輸入的文字少於 20 個字時，將拋出錯誤並顯示「內容至少需填20字！」的錯誤訊息，且記錄不會被保存。

方法二：針對欄位顯示錯誤訊息

在某些情境下，直接針對欄位顯示錯誤提示會更直觀，例如輸入的內容不符合規則時，提示訊息能夠直接顯示在欄位下方。這可以透過 record.欄位代碼.error 來實現，範例如下：

kintone.events.on('app.record.create.submit', event => {
  try {
    const { record } = event;
    const content = record['內容'].value; // 未做空值處理

    // 若未輸入內容，content 為 undefined，會導致 content.length 報錯
    if (content.length < 20) { 
      record['內容'].error = '內容至少需填20字！'; // 針對欄位顯示錯誤訊息
    }

  } catch (error) {
    console.error('發生錯誤:', error); // 主控台顯示完整錯誤，供開發者除錯
    event.error = error.message; // 顯示錯誤訊息給使用者
  }  
  return event; // 必須 return event，`event.error` 才能生效
});

關鍵解析

• record.欄位代碼.error 可用於特定欄位，錯誤訊息會顯示在該欄位下方，使使用者更容易理解問題。
• 這種方式適用於表單驗證，例如必填欄位、格式檢查等。

處理潛在錯誤

上述程式碼中存在一個潛在問題：如果 record['內容'].value 為 undefined（例如使用者完全未輸入內容），則 content.length 會導致 JavaScript 錯誤，因為 undefined 沒有 length 屬性。這時候，程式將進入 catch 區塊，由 console.error() 記錄錯誤，並透過 event.error 通知使用者。

這樣的錯誤處理機制能確保：

• 使用者在輸入錯誤時獲得即時回饋。
• 開發者能透過主控台快速診斷問題，提升除錯效率。

kintone 錯誤顯示功能的限制

前述介紹的兩種錯誤顯示方式 (event.error 和 record.欄位代碼.error) 是 kintone API 提供的內建機制，然而這些方法並不適用於所有情境。

上圖擷取自 🔗 kintone 官方文件 - 可以用事件物件執行的操作 ，可以清楚看出這兩種錯誤顯示方式的適用畫面與時機。例如：

• event.error 無法用於 app.record.detail.show 之類的事件。
• record.欄位代碼.error 僅適用於 表單提交類型的事件（如 app.record.create.submit）。

然而，程式碼錯誤可能發生在任何地方，當 kintone 無法提供內建錯誤提示時，我們仍需要建立一套有效的錯誤提示機制，以確保使用者能夠即時獲得錯誤資訊並採取適當行動。

方法三：使用 window.alert 提示

當 kintone 內建的錯誤提示機制無法適用時，我們可以使用 window.alert() 來向使用者顯示錯誤訊息。這是一種簡單直接的方式，適用於任何執行環境，例如記錄詳細畫面 (app.record.detail.show)、按鈕點擊事件，甚至是非 kintone 事件內的錯誤處理。

為了提高程式碼的可讀性與可重複使用性，可以將錯誤處理邏輯封裝成函式：

// 封裝錯誤處理函式
function showError(error) {
  console.error('發生錯誤:', error);
  window.alert(error.message);
}

kintone.events.on('app.record.detail.show', event => {
  try {
    const spaceEl = kintone.app.record.getSpaceElement('button-space');
    const button = document.createElement('button');
    spaceEl.appendChild(button);

    button.addEventListener('click', () => {
      try {
        // 點擊按鈕後執行的邏輯
      } catch (error) {
        showError(error);
      }
    });

  } catch (error) {
    showError(error);
  }  
  return event;
});

處理表單送出事件時的注意事項

在表單送出或執行流程動作（如新增／編輯保存記錄，或流程推進）時，如果發生錯誤且需要中斷事件處理，則必須在 catch 區塊內回傳 false，以終止事件的執行。例如：

kintone.events.on('app.record.create.submit', event => {
  try {
    const { record } = event;
    const content = record['內容'].value || '';

    if (content.length < 20) { 
      throw new Error('內容至少需填 20 字！');
    }

    // 其他邏輯
    // ...

  } catch (error) {
    showError(error);
    return false; // 發生錯誤時，終止事件處理，防止錯誤資料送出
  }  
  return event;
});

方法四：使用 SweetAlert2 提示

雖然 window.alert() 簡單易用，但它的缺點是樣式過於簡單且不夠美觀。如果希望同時兼顧易用性與視覺效果，可以考慮使用 SweetAler2 套件。

若專案使用 Webpack、Vite 等打包工具，可以透過 npm 安裝 SweetAlert2。此外，Cybozu 也提供了 CDN 連結，可直接在 kintone 應用程式設定中加入使用：

🔗 Cybozu CDN - sweetalert2

引入 sweetalert2 後，可以根據需求自訂提示視窗的樣式。以下是簡單的錯誤提示範例：

function showError(error) {
  console.error(error);
  Swal.fire({
    icon: 'error',
    title: 'Error',
    text: error.message
  });
};

這段程式碼與先前介紹的 window.alert() 功能相同，但視覺呈現更加美觀。效果如下：

SweetAlert2 的優勢

• 支援自訂樣式：可以調整字體、顏色、動畫等，使提示視窗更符合 UI 設計風格。
• 彈性設定：可用於錯誤提示、成功通知、確認對話框等多種情境。
• 不影響使用體驗：不像 window.alert() 會阻塞操作，SweetAlert2 可設定非同步關閉方式，讓使用者有更好的體驗。

SweetAlert2 提供豐富的 API 可供調整，適用於各種提示與互動需求，有興趣的讀者可以前往官方文件查看更多用法。

結語

在 kintone 客製化開發中，妥善的錯誤處理能提升系統穩定性與使用者體驗。本篇介紹了多種錯誤提示方式，包括：

1. event.error / record.欄位代碼.error → 適用於表單驗證與提交時的錯誤提示。
2. window.alert() → 簡單易用，適用於一般錯誤通知。
3. SweetAlert2 → 提供美觀、可自訂的錯誤視窗，提升使用體驗。

選擇錯誤處理方式時，應依據錯誤類型與應用場景靈活搭配，確保錯誤訊息能有效傳達。希望這篇文章能幫助開發者更順利處理錯誤，讓 kintone 應用更加穩定流暢！ 🚀