在 kintone 的客製化開發中，我們經常需要根據使用者操作狀況，顯示自定義提示訊息或是確認視窗。過去若要達成這類效果，通常需要自行撰寫 HTML／CSS 或搭配外部函式庫，例如 SweetAlert2 、官方提供的 kintone UI Component 等套件，來自行建立元件。

不過從 2025 年 9 月與 10 月 的 API 更新開始，kintone 官方新增了數個方便的 UI 操作 API，
開發者現在可以直接呼叫內建函式，快速顯示對話框、提示訊息、或控制載入畫面，不需要再額外引入 kintone UI Component 即可使用。

新增的 API 包含以下四個：

這四個 API 能在 kintone 電腦版中適用客製化的頁面上使用，但須注意不支援以下頁面：

• 搜尋頁面
• 應用程式商店
• 外掛設定畫面

接下來就分別介紹這四個 API 的用途與基本使用方式。

1. 顯示確認視窗：kintone.showConfirmDialog()

kintone.showConfirmDialog(config) 可顯示一個確認對話框，讓使用者選擇是否執行某項操作，並可取得使用者的選擇結果。

kintone.showConfirmDialog(config)

參數說明

回傳值

此函式會回傳一個 Promise 物件。
當使用者選擇任一操作後，Promise 會被解析（fulfilled），並傳回以下值：

範例

// 基本的確認對話框
kintone.showConfirmDialog({
  title: '刪除確認',
  body: '是否確定要刪除此筆記錄？',
  showOkButton: true,
  showCancelButton: true,
  okButtonText: '刪除',
  cancelButtonText: '取消',
  showCloseButton: true
}).then((result) => {
  if (result === 'OK') {
    console.log('執行刪除動作')
  } else {
    console.log('已取消刪除')
  }
})

2. 建立自訂對話框：kintone.createDialog()

使用 kintone.createDialog(config) 可在頁面上建立可自訂內容的對話框。
與 kintone.showConfirmDialog() 不同，此 API 允許插入自訂 HTML 元素、輸入欄位、按鈕等互動元件，並可在關閉前執行驗證或額外邏輯。

kintone.createDialog(config)

參數說明

回傳值

此函式會回傳一個 Promise 物件，物件中包含兩個可用方法：

範例

// kintone submit 事件中

// 建立可輸入內容的自訂對話框
const inputElement = document.createElement('textarea')
inputElement.style.width = '100%'
inputElement.style.height = '80px'
inputElement.placeholder = '請輸入備註...'

const dialog = await kintone.createDialog({
  title: '輸入備註',
  body: inputElement,
  showCancelButton: true,
  cancelButtonText: '取消',
  okButtonText: '確定',
  showCloseButton: true,
  beforeClose: (action) => {
    const text = inputElement.value.trim()
    if (action === 'OK' && !text) {
      alert('請輸入內容再按確定。')
      return false
    } else if (action === 'OK' && text) {
      record['備註'].value = text
    }
  }
})

// 顯示對話框並取得結果
const result = await dialog.show()
if (result === 'OK') {
  return event // 完成 submit 事件
} else {
  return false // 取消 submit 事件
}

注意事項

指定於 config.body 的元素（Element object）會直接插入對話框中。
若內容包含使用者輸入或動態字串，請務必進行防止 XSS 的處理（Sanitize）。

3. 顯示提示訊息：kintone.showNotification()

使用 kintone.showNotification(type, message) 可在畫面上方顯示提示訊息。
此訊息會依照不同類型以顏色區分，可用來提示操作成功、錯誤、或一般資訊。

kintone.showNotification(type, message)

參數說明

回傳值

此函式會回傳一個 Promise 物件。
當提示訊息顯示完成後，Promise 會被解析（fulfilled）。

範例

// 顯示錯誤訊息
kintone.showNotification('ERROR', '資料儲存失敗。')

// 顯示成功訊息
kintone.showNotification('SUCCESS', '資料已成功儲存。')

// 顯示資訊訊息
kintone.showNotification('INFO', '開始處理中...')

// 非同步處理範例
kintone.showNotification('SUCCESS', '處理完成。').then(() => {
  console.log('提示訊息已顯示')
})

注意事項

• 提示訊息顯示後不會自動消失，需由使用者手動關閉或由系統覆蓋。
• 當前頁面一次只能顯示一則訊息。
  若同時呼叫多次，僅最後一則會顯示（包含原生系統提示訊息）。

💡2025/11/12 註：
由於目前此 API 不支援主動關閉以及設定顯示時長的方法，如果要做到這些效果，還是推薦使用 kintone UI Component 的 Notification 元件：
https://ui-component.kintone.dev/docs/components/desktop/notification

4. 控制載入畫面：kintone.showLoading()

使用 kintone.showLoading(state) 可以顯示或隱藏載入中的 UI 畫面。
當載入畫面顯示時，使用者無法進行任何操作，適合用於等待 API 回應或長時間處理的情境。

kintone.showLoading(state)

參數說明

回傳值

此函式會回傳一個 Promise 物件。
當載入畫面顯示或隱藏完成後，Promise 會被解析（fulfilled）。

範例

// 顯示載入畫面
kintone.showLoading('VISIBLE')

// 模擬長時間處理
setTimeout(() => {
  // 隱藏載入畫面
  kintone.showLoading('HIDDEN')
}, 3000)

注意事項

• 顯示載入畫面期間，使用者無法操作頁面。
• 客製化中一次只能顯示一個載入畫面，但這與 kintone 系統內建的載入畫面互不影響。

結語

這四個全新的 UI 操作 API，讓 kintone 的客製化開發更貼近系統原生體驗。
無論是提示訊息、確認對話框，或是載入畫面，都能以簡潔的語法快速呼叫、免去手動撰寫 HTML 與樣式的麻煩。

對於以往習慣使用 kintone UI Component 或外部函式庫的開發者，這些 API 提供了更輕量、維護性更高的替代方案。
未來若有需要彈出訊息、顯示載入狀態或輸入對話框的情境，不妨優先考慮使用這些官方 API，讓你的客製化程式更簡潔、穩定、並與 kintone 介面完美融合。