# coze-out-variable-component

**Repository Path**: snove/coze-out-variable-component

## Basic Information

- **Project Name**: coze-out-variable-component
- **Description**: 为扣子工作流节点属性面板实现一个输出属性的树形编辑器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-10
- **Last Updated**: 2026-01-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 扣子工作流节点输出属性树形编辑器

## 需求描述

为扣子工作流节点属性面板实现一个输出属性的树形编辑器，支持以下功能：

- **树形结构展示**：以树形方式组织输出属性，支持无限层级嵌套
- **双展开模式**：区分"树展开"（子节点显示/隐藏）和"详情展开"（描述和示例的显示/隐藏）
- **多种数据类型**：支持 String、Number、Boolean、Array、Object 五种类型
- **灵活编辑**：可直接编辑属性名、类型、描述和示例
- **动态管理**：支持添加根节点、添加子项、删除节点
- **固定宽度布局**：每个位置固定宽度，确保界面整齐对齐
- **简洁界面**：无行边框，无 hover 样式，保持界面清爽

## 封装功能

### 核心功能

1. **树形结构管理**
   - 递归组件渲染，支持无限层级
   - 节点缩进显示，直观展示层级关系
   - 展开/折叠子树结构

2. **节点类型支持**
   - String：字符串类型
   - Number：数字类型
   - Boolean：布尔类型
   - Array：数组类型，可包含子项
   - Object：对象类型，可包含子项

3. **编辑能力**
   - 属性名编辑
   - 类型切换
   - 描述编辑
   - 示例编辑

4. **操作功能**
   - 添加根属性
   - 为 Array/Object 类型添加子项
   - 删除节点（带确认）
   - 切换树展开状态
   - 切换详情展开状态

## 实现过程

### 1. 技术选型

- **框架**：Next.js 16.0.10 (App Router)
- **语言**：TypeScript 5
- **样式**：Tailwind CSS 4
- **状态管理**：React Hooks (useState)

### 2. 架构设计

采用**递归组件**模式，将树形编辑器拆分为两个组件：

- **OutputTreePanel**：容器组件，负责整体状态管理和操作逻辑
- **TreeNode**：叶子组件，负责单个节点的渲染和交互

### 3. 关键实现

#### 数据结构
```typescript
interface PropertyNode {
  id: string;              // 节点唯一标识
  name: string;            // 属性名
  type: PropertyType;       // 属性类型
  description?: string;    // 描述
  example?: any;           // 示例值
  required?: boolean;      // 是否必填
  children?: PropertyNode[]; // 子节点
  expanded?: boolean;       // 树展开状态
  detailsExpanded?: boolean; // 详情展开状态
  level: number;           // 层级深度
}
```

#### 递归渲染
TreeNode 组件根据 `node.children` 递归调用自身，实现无限层级。

#### 双展开模式
- `expanded`：控制子节点的显示/隐藏（树展开）
- `detailsExpanded`：控制描述和示例的显示/隐藏（详情展开）

#### 固定宽度布局
- 树展开按钮：24px
- 属性名输入框：flex: 1（自适应）
- 类型选择器：120px
- 添加子项按钮：28px（含占位）
- 详情展开按钮：28px
- 删除按钮：28px

### 4. 开发步骤

1. 创建 TreeNode 组件，实现单节点渲染
2. 添加递归逻辑，支持子节点渲染
3. 实现双展开模式（树展开/详情展开）
4. 创建 OutputTreePanel 容器组件
5. 实现状态管理（增删改查）
6. 优化布局和样式
7. 清理不相关代码

## 组件说明

### TreeNode 组件

**作用**：树形结构的叶子节点，负责渲染单个属性节点及其子节点。

**主要职责**：
- 渲染节点行（属性名、类型、操作按钮）
- 渲染详情展开区域（描述、示例）
- 递归渲染子节点
- 处理节点级别的交互（编辑、删除、展开/折叠）

**Props**：
```typescript
interface TreeNodeProps {
  node: PropertyNode;                          // 节点数据
  onUpdate: (id: string, updates: Partial<PropertyNode>) => void;  // 更新节点
  onDelete: (id: string) => void;              // 删除节点
  onAddChild: (parentId: string) => void;      // 添加子节点
  onToggleExpand: (id: string) => void;        // 切换树展开
  onToggleDetails: (id: string) => void;       // 切换详情展开
}
```

**特点**：
- 纯展示组件，不管理状态
- 通过 props 接收数据和回调函数
- 支持无限层级递归

### OutputTreePanel 组件

**作用**：容器组件，管理整个树形编辑器的状态和业务逻辑。

**主要职责**：
- 管理所有节点数据
- 实现增删改查操作
- 提供操作按钮和界面布局
- 处理节点查找和更新逻辑

**Props**：
```typescript
interface OutputTreePanelProps {
  title?: string;        // 面板标题，默认"输出属性"
  className?: string;    // 自定义样式类名
}
```

**内置功能**：
- 初始化演示数据
- 添加根节点
- 递归查找节点
- 递归更新节点
- 递归删除节点

**特点**：
- 智能组件，包含业务逻辑
- 状态集中管理
- 提供默认数据和操作

## 组件使用方式

### 基础使用

```tsx
import OutputTreePanel from '@/components/OutputTreePanel';

export default function Page() {
  return (
    <div className="h-[600px]">
      <OutputTreePanel />
    </div>
  );
}
```

### 自定义标题

```tsx
import OutputTreePanel from '@/components/OutputTreePanel';

export default function Page() {
  return (
    <div className="h-[600px]">
      <OutputTreePanel title="API 输出参数" />
    </div>
  );
}
```

### 自定义样式

```tsx
import OutputTreePanel from '@/components/OutputTreePanel';

export default function Page() {
  return (
    <div className="h-[600px]">
      <OutputTreePanel className="border border-gray-200 rounded-lg" />
    </div>
  );
}
```

### 完整示例

```tsx
'use client';

import OutputTreePanel from '@/components/OutputTreePanel';

export default function OutputPropertyEditor() {
  return (
    <div className="flex min-h-screen items-center justify-center bg-gray-100 p-8">
      <div className="w-full max-w-[956px] overflow-hidden rounded-xl bg-white shadow-xl">
        <OutputTreePanel 
          title="工作流输出属性"
          className="h-[600px]"
        />
      </div>
    </div>
  );
}
```

### 操作说明

1. **添加属性**：点击右上角"添加属性"按钮，直接添加新的根节点
2. **编辑属性**：直接在输入框中编辑属性名、类型、描述和示例
3. **添加子项**：对于 Array/Object 类型，点击 + 号按钮添加子节点
4. **删除属性**：点击删除图标，确认后删除节点（及其所有子节点）
5. **展开/折叠子树**：点击左侧箭头图标，展开或折叠子节点
6. **展开/折叠详情**：点击右侧箭头图标，展开或折叠描述和示例区域

## 文件结构

```
src/
├── components/
│   ├── OutputTreePanel.tsx    # 容器组件
│   └── TreeNode.tsx           # 树节点组件
├── app/
│   └── page.tsx               # 示例页面
└── README.md                  # 本文件
```

## 技术特点

- **TypeScript**：完整的类型定义，提供类型安全
- **递归组件**：优雅的无限层级实现
- **响应式布局**：固定宽度 + flex 自适应，确保对齐
- **零依赖**：仅依赖 React 和 Next.js 核心库
- **可扩展**：易于添加新的属性类型或功能

## 注意事项

- 删除节点时会删除其所有子节点，操作不可逆
- Array/Object 类型才能添加子节点
- 节点 ID 自动生成，确保唯一性
- 默认包含演示数据，可手动清空后重新添加