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

---
trigger: manual
---

# Dialog 功能实现指南

## 概述

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

## 技术栈

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

## 基本用法

### 1. 导入 Dialog 组件

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

### 2. 基本属性

Dialog 组件常用属性包括：

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

### 3. 基本结构

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

## 实现方式

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

### 1. JSX 组件形式

直接在 JSX 中使用 Dialog 组件：

```tsx
<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 提供的静态方法调用：

```tsx
// 使用 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 显示/隐藏的状态：

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

### 2. 触发 Dialog 显示

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

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

### 3. 处理确认和取消操作

实现 onConfirm 和 onCancel 回调函数：

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

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

### 4. 关闭 Dialog

Dialog 可以通过以下方式关闭：
- 点击取消按钮
- 点击确认按钮
- 在 onCancel 或 onConfirm 回调中手动设置 visible 为 false
- 使用 Dialog.close() 方法（函数调用形式）

## 常见使用场景

### 1. 确认操作

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

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

### 2. 输入信息

用于请求用户输入信息：

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

### 3. 显示重要信息

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

```tsx
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()

## 示例代码

```tsx
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>
  );
}
```