【kintone】客制化程式码的错误处理

在开发 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 客制化开发中，妥善的错误处理能提升系统稳定性与使用者体验。本篇介绍了多种错误提示方式，包括：

event.error / record.栏位代码.error → 适用于表单验证与提交时的错误提示。

window.alert() → 简单易用，适用于一般错误通知。

SweetAlert2 → 提供美观、可自订的错误视窗，提升使用体验。

选择错误处理方式时，应依据错误类型与应用场景灵活搭配，确保错误讯息能有效传达。希望这篇文章能帮助开发者更顺利处理错误，让 kintone 应用更加稳定流畅！ 🚀