react-native-mask-segment-canvas/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/api/callbacks.md

id	title
callbacks	Props：回调

📞 Props：回调

Prop	签名	描述
onWatch	(state, durationMs, detail?) => void	初始化阶段回调；durationMs 从本次 init 开始计时
onPaintCallback	(payload: PaintCallbackPayload) => void	成功上色时触发，或未选择画笔时点击区域触发
onError	(message, error?) => void	分割或加载失败

PaintCallbackPayload

（可辨识联合类型，通过 payload.kind 区分）：

// 成功上色
{
  kind: 'painted';
  regionId: number;
  regionName: string;
  color: BgrColor;
  configJson?: Record<string, unknown>; // 来自 setPaintColor / initialPaintConfigJson
}

// 点击了有效区域但未选择画笔（未执行上色）
{
  kind: 'brush_required';
  hint: string;       // 如 "请先选择画笔颜色（底部颜色条或 ref.setPaintColor）"
  regionId: number;
  regionName: string;
}

示例：

onPaintCallback={payload => {
  if (payload.kind === 'brush_required') {
    showToast(payload.hint);
    return;
  }
  savePaintRecord(payload.regionId, payload.color, payload.configJson);
}}

onWatch detail（MaskSegmentWatchDetail）

字段	类型	描述
regionCount	number	当前有效区域数
maskPathsReady	boolean	轮廓 Skia 路径是否就绪
freqLayersReady	boolean	频域 Shader 纹理是否就绪
errorMessage	string	error 状态下的失败描述

onWatch 状态流转

init
  → images_loaded      原始图像和遮罩读取完成
  → mask_aligned       遮罩尺寸对齐
  → mask_sampled       遮罩像素采样完成
  → regions_ready      区域提取成功
  → layers_ready       上色纹理层就绪（detail.maskPathsReady 可能仍为 false）
  → interactive        可交互（可以点击区域、选择颜色、上色）
  → mask_paths_ready   轮廓路径就绪（轮播虚线轮廓可显示；detail.maskPathsReady 为 true）
  → error              失败（detail.errorMessage 包含描述）

layers_ready / interactive 可能在轮廓路径计算完成之前触发。如果宿主在 interactive 时关闭阻塞加载器，用户已可操作；轮播虚线轮廓在 mask_paths_ready 后自动显示。