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

trigger
manual

Popup 功能实现指南

概述

Popup 是系统中常用的 UI 组件，用于在当前页面上显示一个浮层，通常用于显示额外信息、表单或选择器等。本指南将详细介绍如何在系统中实现 Popup 功能。

技术栈

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

基本用法

1. 导入 Popup 组件

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

2. 基本属性

Popup 组件常用属性包括：

• visible: 控制 Popup 是否显示（boolean）
• position: Popup 出现的位置（"top" | "bottom" | "left" | "right" | "center"）
• title: Popup 标题
• onClose: 关闭时的回调函数
• onOverlayClick: 点击遮罩层时的回调函数
• closeable: 是否显示关闭按钮
• round: 是否显示圆角
• lockScroll: 是否锁定背景滚动

3. 基本结构

<Popup
  visible={visible}
  position="bottom"
  title="Popup 标题"
  onClose={() => setVisible(false)}
  closeable
  round
  lockScroll
>
  <View>Popup 内容</View>
</Popup>

实现步骤

1. 状态管理

在组件中定义控制 Popup 显示/隐藏的状态：

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

2. 触发 Popup 显示

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

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

3. Popup 内容实现

Popup 内容根据具体需求实现，可以包含表单、列表、文本等。

4. 关闭 Popup

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

• 点击关闭按钮（如果设置了 closeable）
• 点击遮罩层（如果未阻止）
• 调用 onClose 回调函数
• 在 Popup 内部通过按钮等操作手动设置 visible 为 false

常见使用场景

1. 选择器

常用于实现各种选择器，如经销商选择、供应商选择等：

<Popup
  visible={visible}
  position="bottom"
  title="选择经销商"
  onClose={() => setVisible(false)}
>
  <View>经销商列表</View>
</Popup>

2. 表单编辑

用于编辑某一项信息：

<Popup
  visible={visible}
  position="bottom"
  title={`编辑${supplier.name}销售单价`}
  onClose={() => setVisible(false)}
>
  <View className="flex flex-col gap-3 p-2.5">
    <Input
      placeholder="请输入销售单价"
      type="digit"
      value={price}
      onChange={(value) => setPrice(value)}
    />
    <Button onClick={handleSave}>保存</Button>
  </View>
</Popup>

3. 确认弹窗

用于确认操作：

<Popup
  visible={visible}
  position="bottom"
  title="确认操作"
  onClose={() => setVisible(false)}
>
  <View className="p-4">
    <View className="mb-4">确定要执行此操作吗？</View>
    <View className="flex gap-2">
      <Button onClick={() => setVisible(false)}>取消</Button>
      <Button onClick={handleConfirm}>确认</Button>
    </View>
  </View>
</Popup>

最佳实践

1. 状态管理

• 使用 useState 管理 Popup 的显示状态
• 对于复杂场景，可以使用 useReducer 或状态管理库

2. 性能优化

• 对于内容较多的 Popup，考虑使用懒加载
• 在 Popup 关闭时清理相关状态

3. 用户体验

• 合理设置 Popup 的位置和大小
• 提供明确的关闭方式
• 添加适当的动画效果

4. 样式统一

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

注意事项

1. 确保在组件卸载时清理相关状态和副作用
2. 注意 Popup 内容的可访问性
3. 避免同时显示多个 Popup
4. 考虑移动端的适配问题
5. 在 Popup 关闭时重置相关表单数据（如需要）

示例代码

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

export default function MyComponent() {
  const [visible, setVisible] = useState(false);
  
  return (
    <View>
      <Button onClick={() => setVisible(true)}>打开 Popup</Button>
      
      <Popup
        visible={visible}
        position="bottom"
        title="示例 Popup"
        onClose={() => setVisible(false)}
        closeable
        round
      >
        <View className="p-4">
          <View>这是 Popup 内容</View>
          <Button 
            block 
            type="primary" 
            className="mt-4"
            onClick={() => setVisible(false)}
          >
            关闭
          </Button>
        </View>
      </Popup>
    </View>
  );
}