ERPTurbo_Client/.lingma/rules/dialog-implementation.md

trigger
manual

Dialog 功能实现指南

概述

Dialog 是系统中用于显示重要信息或请求用户确认操作的模态对话框组件。它通常用于警告、确认操作或显示关键信息。本指南将详细介绍如何在系统中实现 Dialog 功能。

技术栈

系统使用的是基于 Taro 的 React 框架，Dialog 组件来自 @nutui/nutui-react-taro 库。

基本用法

1. 导入 Dialog 组件

import { Dialog } from "@nutui/nutui-react-taro";

2. 基本属性

Dialog 组件常用属性包括：

• visible: 控制 Dialog 是否显示（boolean）
• title: Dialog 标题
• content: Dialog 内容（可以是字符串或 JSX 元素）
• onCancel: 取消按钮的回调函数
• onConfirm: 确认按钮的回调函数
• cancelText: 取消按钮文本
• confirmText: 确认按钮文本

3. 基本结构

<Dialog
  visible={visible}
  title="Dialog 标题"
  content="Dialog 内容"
  onCancel={() => setVisible(false)}
  onConfirm={handleConfirm}
/>

实现方式

系统中有两种主要使用 Dialog 的方式：

1. JSX 组件形式

直接在 JSX 中使用 Dialog 组件：

<Dialog
  visible={inputVisible}
  title="手动输入经销商"
  content={
    <View className={`flex h-10 w-full items-center rounded-md border-4 border-gray-300`}>
      <Input
        type="text"
        placeholder="请输入经销商名称"
        value={inputValue}
        onChange={(value) => setInputValue(value)}
      />
    </View>
  }
  onCancel={() => setInputVisible(false)}
  onConfirm={handleConfirm}
/>

2. 函数调用形式

通过 Dialog 提供的静态方法调用：

// 使用 Dialog.confirm
const onWithdraw = async () => {
  Dialog.confirm({
    title: "提示",
    content: "确认撤回审核？",
    onConfirm: async () => {
      // 确认操作
    },
    onCancel: () => {
      // 取消操作
    },
  });
};

// 使用 Dialog.open 和 Dialog.close
const handleApprove = () => {
  Dialog.open("dialog", {
    title: "审批通过",
    content: "确定要审批通过该采购订单吗？",
    confirmText: "确认",
    cancelText: "取消",
    onConfirm: async () => {
      await confirmApprove();
      Dialog.close("dialog");
    },
    onCancel: () => {
      Dialog.close("dialog");
    },
  });
};

实现步骤

1. 状态管理

对于 JSX 组件形式的 Dialog，需要定义控制 Dialog 显示/隐藏的状态：

const [visible, setVisible] = useState(false);

2. 触发 Dialog 显示

通过事件触发 Dialog 显示，例如点击按钮：

<Button onClick={() => setVisible(true)}>打开 Dialog</Button>

3. 处理确认和取消操作

实现 onConfirm 和 onCancel 回调函数：

const handleConfirm = () => {
  // 执行确认操作
  setVisible(false);
};

const handleCancel = () => {
  // 执行取消操作
  setVisible(false);
};

4. 关闭 Dialog

Dialog 可以通过以下方式关闭：

• 点击取消按钮
• 点击确认按钮
• 在 onCancel 或 onConfirm 回调中手动设置 visible 为 false
• 使用 Dialog.close() 方法（函数调用形式）

常见使用场景

1. 确认操作

用于确认删除、撤回等重要操作：

const handleDelete = () => {
  Dialog.confirm({
    title: "确认删除",
    content: "确定要删除这条记录吗？",
    onConfirm: async () => {
      // 执行删除操作
    },
  });
};

2. 输入信息

用于请求用户输入信息：

<Dialog
  visible={inputVisible}
  title="输入信息"
  content={
    <Input
      placeholder="请输入信息"
      value={inputValue}
      onChange={(value) => setInputValue(value)}
    />
  }
  onCancel={() => setInputVisible(false)}
  onConfirm={handleConfirm}
/>

3. 显示重要信息

用于显示重要提示或警告信息：

const handleSubmit = async () => {
  Dialog.open("submit-dialog", {
    title: "提交提醒",
    content: "提交后将无法修改，请确认信息无误。",
    confirmText: "确认提交",
    cancelText: "取消",
    onConfirm: async () => {
      // 执行提交操作
      Dialog.close("submit-dialog");
    },
    onCancel: () => {
      Dialog.close("submit-dialog");
    },
  });
};

最佳实践

1. 状态管理

• 使用 useState 管理 Dialog 的显示状态（JSX 组件形式）
• 对于函数调用形式，使用唯一标识符管理不同的 Dialog 实例

2. 用户体验

• 提供明确的标题和内容说明
• 使用合适的确认和取消按钮文本
• 在操作完成后及时关闭 Dialog

3. 错误处理

• 在 onConfirm 回调中处理可能的错误
• 提供友好的错误提示信息

4. 样式统一

• 保持 Dialog 标题、按钮等样式与系统一致
• 使用系统定义的颜色和间距变量

注意事项

1. 确保在组件卸载时关闭 Dialog
2. 注意 Dialog 内容的可访问性
3. 避免同时显示多个 Dialog
4. 在异步操作中正确处理 Dialog 的关闭时机
5. 对于函数调用形式，记得在适当时机调用 Dialog.close()

示例代码

import { Dialog, Button, View, Input } from "@nutui/nutui-react-taro";
import { useState } from "react";

export default function MyComponent() {
  const [visible, setVisible] = useState(false);
  const [inputValue, setInputValue] = useState("");
  
  const handleConfirm = () => {
    // 处理确认逻辑
    console.log("用户输入:", inputValue);
    setVisible(false);
    setInputValue("");
  };
  
  const showConfirmDialog = () => {
    Dialog.confirm({
      title: "确认操作",
      content: "确定要执行此操作吗？",
      onConfirm: () => {
        // 确认操作
        console.log("用户确认操作");
      },
    });
  };
  
  return (
    <View>
      <Button onClick={() => setVisible(true)}>打开输入 Dialog</Button>
      <Button onClick={showConfirmDialog}>显示确认 Dialog</Button>
      
      <Dialog
        visible={visible}
        title="请输入信息"
        content={
          <Input
            placeholder="请输入信息"
            value={inputValue}
            onChange={(value) => setInputValue(value)}
          />
        }
        onCancel={() => setVisible(false)}
        onConfirm={handleConfirm}
      />
    </View>
  );
}