# react-variable-editor

**Repository Path**: zym6666/react-variable-editor

## Basic Information

- **Project Name**: react-variable-editor
- **Description**: 一个支持变量拖拽插入的 React 文本编辑器组件库。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-17
- **Last Updated**: 2026-06-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# react-variable-editor

一个支持变量拖拽插入的 React 文本编辑器组件库。

## 功能

- 上方展示变量列表
- 支持把变量拖拽到编辑器中
- 支持普通文本和变量混排
- 变量以整块 token 形式展示
- 删除变量时整块删除
- 支持导出 JSON、HTML、模板字符串
- 支持自定义变量模板符号，例如 `{{key}}`、`${key}`、`[[key]]`

## 使用示例

```tsx
import { useState } from 'react';
import {
  VariableEditor,
  toTemplate,
  type EditorValue
} from 'react-variable-editor';

const variables = [
  { key: 'userName', label: '用户名' },
  { key: 'companyName', label: '公司名' }
];

export default function Demo() {
  const [value, setValue] = useState<EditorValue>({
    segments: []
  });

  return (
    <VariableEditor
      variables={variables}
      value={value}
      onChange={setValue}
      placeholder="请输入内容"
    />
  );
}
```

```tsx
const template = toTemplate(value, {
  open: '${',
  close: '}'
});
```

## 组件属性

### `VariableEditorProps`

| 属性 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `variables` | `VariableItem[]` | 是 | - | 变量列表，显示在编辑器上方，也用于拖拽插入。 |
| `value` | `EditorValue` | 否 | - | 受控模式下的编辑器值。传入后由外部完全控制内容。 |
| `defaultValue` | `EditorValue` | 否 | `{ segments: [] }` | 非受控模式下的初始值。 |
| `onChange` | `(value: EditorValue) => void` | 否 | - | 内容变化时触发，返回最新的结构化结果。 |
| `placeholder` | `string` | 否 | `''` | 编辑器为空时显示的占位提示。 |
| `disabled` | `boolean` | 否 | `false` | 是否禁用编辑器和变量拖拽。 |
| `className` | `string` | 否 | - | 传给编辑器根节点的自定义类名。 |

## 数据结构

### `VariableItem`

```ts
type VariableItem = {
  key: string;
  label: string;
};
```

- `key`：变量唯一标识，用于模板输出，例如 `userName`
- `label`：界面展示名称，例如 `用户名`

### `EditorValue`

```ts
type EditorValue = {
  segments: Array<
    | { type: 'text'; text: string }
    | { type: 'variable'; key: string; label: string }
  >;
};
```

- `text` 片段表示普通文本
- `variable` 片段表示变量标签
- 导出的 JSON、HTML、模板字符串都基于这个结构转换

## 序列化方法

### `toTemplate`

```ts
toTemplate(value, syntax?)
```

- 作用：把 `EditorValue` 转成模板字符串
- 默认变量符号：`{{key}}`
- 可选第二个参数：自定义变量符号

```tsx
const template = toTemplate(value, {
  open: '${',
  close: '}'
});
```

### `fromTemplate`

```ts
fromTemplate(template, variables?, syntax?)
```

- 作用：把模板字符串解析回 `EditorValue`
- `variables` 用来补齐变量标签显示名
- `syntax` 用来指定模板变量包裹符号

```tsx
const value = fromTemplate(
  '你好${userName}',
  [{ key: 'userName', label: '用户名' }],
  {
    open: '${',
    close: '}'
  }
);
```

### `toHtml`

```ts
toHtml(value)
```

- 作用：把 `EditorValue` 转成 HTML 字符串
- 变量会输出为带 `data-token="variable"` 和 `data-key` 的 `span`

## 开发

```bash
npm install
npm run dev
```

## 测试

```bash
npm run test
```

## 构建

```bash
npm run build
```