Tangramino

    Base Editor

    @tangramino/base-editor 提供可视化编辑器的核心能力，包括拖拽系统、画布编辑器、物料管理等。

    安装

    npm install @tangramino/base-editor
# 或
pnpm add @tangramino/base-editor

    EditorProvider

    编辑器上下文提供者，是构建编辑器的根组件。管理 Schema 状态、插件、物料，并处理所有拖拽操作。

    import { EditorProvider } from '@tangramino/base-editor';

<EditorProvider
  schema={initialSchema}
  materials={materials}
  plugins={[historyPlugin]}
  onChange={(newSchema) => console.log(newSchema)}
>
  <CanvasEditor />
</EditorProvider>;

    Props

    属性类型必填说明
    schemaSchema否初始 Schema
    materialsMaterial[]是可用物料数组
    pluginsEditorPlugin[]否编辑器插件数组
    childrenReact.ReactNode否子组件
    onChange(schema: Schema) => void否Schema 变化时的回调

    CanvasEditor

    画布编辑器组件，负责渲染可编辑的画布区域。

    import { CanvasEditor } from '@tangramino/base-editor';

<CanvasEditor
  className="canvas"
  style={{ height: '100vh' }}
  renderElement={({ children, elementProps, material }) => (
    <div className="element-wrapper">{children}</div>
  )}
  renderDropIndicator={({ position }) => (
    <div className={`drop-indicator ${position}`} />
  )}
  renderOverlayContent={() => <ToolBar />}
/>;

    Props

    属性类型说明
    styleReact.CSSProperties画布样式
    classNamestring画布 CSS 类名
    overlayStyleReact.CSSProperties覆盖层样式
    overlayClassNamesstring覆盖层 CSS 类名
    renderElement(props: EnhancedComponentProps) => React.ReactNode自定义元素渲染
    renderDropIndicator(props: DropPlaceholderProps) => React.ReactNode自定义拖放指示器渲染
    renderOverlayContent() => React.ReactNode覆盖层内容渲染

    EnhancedComponentProps

    interface EnhancedComponentProps {
  children: React.ReactElement;
  elementProps: Record<string, unknown>;
  material: Material;
  className?: string;
  onClick?: (e: React.MouseEvent) => void;
}

    Draggable

    可拖拽组件，用于物料面板中的可拖拽物料项。

    import { Draggable } from '@tangramino/base-editor';

<Draggable material={buttonMaterial} className="material-item">
  <div>按钮</div>
</Draggable>;

    Props

    属性类型必填说明
    materialMaterial是物料配置
    childrenReact.ReactNode否子元素
    classNamestring否CSS 类名
    styleReact.CSSProperties否样式
    isTransformboolean否是否启用拖拽时的变换效果，默认 false

    Movable

    可移动组件，用于在画布中移动已有元素。

    import { Movable } from '@tangramino/base-editor';

<Movable className="move-handle" onClick={handleClick}>
  <MoveIcon />
</Movable>;

    Props

    属性类型说明
    childrenReact.ReactNode子元素
    classNamestringCSS 类名
    onClick(e: React.MouseEvent) => void点击回调

    DragOverlay

    拖拽覆盖层组件，显示拖拽时的预览效果。

    import { DragOverlay } from '@tangramino/base-editor';

<DragOverlay>
  <div className="drag-preview">拖拽预览</div>
</DragOverlay>;

    Props

    属性类型说明
    childrenReact.ReactNode拖拽时显示的预览内容

    useEditorCore

    编辑器核心状态 Hook，用于访问和操作编辑器状态。

    import { useEditorCore } from '@tangramino/base-editor';

function MyComponent() {
  const {
    schema,
    engine,
    materials,
    activeElement,
    insertPosition,
    dragElement,
    setSchema,
    setActiveElement,
  } = useEditorCore();

  // 使用状态...
}

    返回值

    属性类型说明
    engineEngine引擎实例
    schemaSchema当前 Schema
    setSchema(schema: Schema) => void更新 Schema
    materialsMaterial[]物料列表
    setMaterials(materials: Material[]) => void更新物料列表
    activeElementActiveElement | null当前激活的元素
    setActiveElement(element: ActiveElement | null) => void设置激活元素
    insertPositionInsertPosition | null当前插入位置
    setInsertPosition(position: InsertPosition | null) => void设置插入位置
    dragElementDragElement | null当前拖拽的元素
    setDragElement(element: DragElement | null) => void设置拖拽元素

    ActiveElement 类型

    interface ActiveElement {
  id: string;
  type: string;
  props: Record<string, unknown>;
  material: Material;
  parents?: ActiveElement[];
}

    InsertPosition 类型

    interface InsertPosition {
  id: string;
  position: 'before' | 'after' | 'up' | 'down';
}

    Material

    物料定义接口，描述可在编辑器中使用的组件。

    interface Material {
  // 物料对应的 React 组件
  Component: React.ComponentType;
  // 物料名称
  title: string;
  // 物料类型唯一标识
  type: string;
  // 物料图标
  icon?: React.ReactNode;
  // 允许拖拽到的物料类型
  dropTypes?: string[];
  // 默认属性
  defaultProps?: Record<string, unknown>;
  // 是否为容器
  isContainer?: boolean;
  // 是否为块级元素
  isBlock?: boolean;
  // 编辑器配置
  editorConfig?: EditorConfig;
  // 上下文配置
  contextConfig?: ContextConfig;
}

    MaterialComponentProps

    物料组件自动注入的 Props。

    interface MaterialComponentProps {
  // 元素实例 ID
  'data-element-id'?: string;
  // 是否只读
  tg_readonly?: boolean;
  // 当前模式
  tg_mode?: 'design' | 'render';
  // 拖拽占位符（仅容器有）
  tg_dropPlaceholder?: React.ReactNode;
  // 设置上下文值
  tg_setContextValues?: (values: Record<string, unknown>) => void;
}

    EditorConfig

    编辑器配置，定义物料的属性面板。

    interface EditorConfig {
  panels?: PanelConfig[];
}

interface PanelConfig {
  // 面板标题
  title?: React.ReactNode;
  // 属性配置
  configs?: AttributeConfig[];
}

interface AttributeConfig {
  // 属性标签
  label?: React.ReactNode;
  // 属性字段名
  field: string;
  // UI 类型
  uiType?: string;
  // 默认值
  defaultValue?: string | number | boolean;
  // 是否必填
  required?: boolean;
  // 联动显示
  linkageShow?: {
    field: string;
    value?: string | number | boolean;
    isNotEmpty?: boolean;
  }[];
  // 自定义渲染
  render?: (props: AttributeConfig) => React.ReactNode;
}