Integra fácilmente funcionalidad profesional de mapas mentales en tu web - Mind Elixir

En la era de la explosión informativa, cada día debemos procesar grandes cantidades de información e ideas complejas. Las notas lineales tradicionales a menudo no logran mostrar la naturaleza dinámica y las conexiones del pensamiento, mientras que los mapas mentales, como herramienta de toma de notas semi-automática, nos ayudan a organizar mejor nuestras ideas, estructurar el conocimiento y estimular la inspiración creativa, siendo además más fáciles de usar que las pizarras o software de diagramación.

Ya sea construyendo plataformas de gestión del conocimiento, sitios web educativos en línea o herramientas colaborativas, integrar funcionalidad de mapas mentales puede mejorar significativamente la experiencia del usuario, haciendo que la presentación e interacción de información compleja sea más intuitiva y eficiente.

Si quieres integrar funcionalidad de mapas mentales en tu proyecto Web, con Mind Elixir, con solo unas pocas líneas de código puedes añadir funcionalidad profesional de mapas mentales a tu sitio web. Por ejemplo, en un blog personal, puedes usar mapas mentales para mostrar la estructura de conocimiento de los artículos, crear notas de aprendizaje interactivas; esta funcionalidad no solo hace el contenido más dinámico e interesante, sino que también mejora significativamente la profesionalidad del blog.

El núcleo de mapas mentales JavaScript de código abierto Mind Elixir cuenta con las siguientes características principales:

• Experiencia de usuario fluida Interacción suave, retroalimentación natural, compatible con dispositivos móviles.
• Ligero y de alto rendimiento Tamaño pequeño, carga y renderizado rápidos, garantiza alta tasa de frames incluso con gráficos complejos.
• Independiente del framework Ya sea React, Vue, Svelte o proyectos nativos, se puede integrar fácilmente o ejecutar de forma independiente.
• Arquitectura de plugins Sistema de plugins flexible, soporta extensiones oficiales o plugins personalizados, combinación libre de módulos funcionales.
• Soporte para exportar PNG / HTML Exporta mapas mentales como imágenes o páginas HTML, conveniente para compartir e incrustar.
• Resúmenes de nodos / Conexiones de nodos Soporta resúmenes de nodos, líneas de conexión, etiquetas y otros estilos de nodos diversos, satisfaciendo diferentes necesidades.
• Soporte para deshacer / rehacer Pila completa de historial de operaciones, cualquier modificación puede deshacerse o rehacerse rápidamente, operación sin preocupaciones.
• Soporte eficiente de atajos de teclado Abundantes atajos de teclado, mejora la eficiencia operativa de usuarios profesionales.
• Personalización de estilos con variables CSS Control fácil de estilos de nodos y tema general a través de variables CSS, logra diseños hermosos altamente personalizados.

¡A continuación te explico cómo integrar rápidamente Mind Elixir en tu proyecto! 🤗

Integración súper sencilla

Instalar dependencias:

npm i mind-elixir -S

Importar Mind Elixir:

import MindElixir from "mind-elixir";
import "mind-elixir/style"; // Las versiones posteriores a 5.0 requieren importar estilos activamente

Por supuesto, también puedes importarlo directamente con script:

<script type="module" src="https://cdn.jsdelivr.net/npm/mind-elixir/dist/MindElixir.js"></script>

Antes de la inicialización, necesitamos ajustar los estilos del elemento objetivo de montaje. Específicamente, necesitamos darle un ancho y alto definidos, especialmente presta atención a la altura. Los amigos frontend que han sido torturados por CSS saben que height: 100% es una configuración bastante difícil de manejar. A continuación usaremos directamente un div de 500px de altura como ejemplo.

<div id="map"></div>
<style>
  #map {
    height: 500px;
    width: 100%;
  }
</style>

Luego viene la inicialización formal. Si no consideramos otras opciones de inicialización, ¡solo necesitamos pasar el elemento de montaje!

import MindElixir from "mind-elixir";
import "mind-elixir/style";

let options = {
  el: "#map", // o HTMLDivElement
};

let mei = new MindElixir(options);
const data = MindElixir.new("new topic");
mei.init(data);

¡Con esto ya hemos completado la integración más básica!

Escucha de eventos

Después de usar mapas mentales en tu proyecto, la necesidad más común es escuchar eventos. Necesitas escuchar varias operaciones de nodos y luego responder a las acciones del usuario. Por ejemplo, cuando un usuario crea un nuevo nodo, necesitas guardarlo oportunamente.

Mind Elixir usa bus para despachar eventos, esta palabra proviene del concepto de “bus”, todos los eventos serán despachados por este “bus”. Su uso es similar al addEventListener del navegador, mientras puedas obtener el bus, puedes escuchar eventos en cualquier lugar.

Hasta la última versión Mind Elixir 5.0, existen los siguientes eventos:

type EventMap = {
  operation: (info: Operation) => void;
  selectNode: (nodeObj: NodeObj, e?: MouseEvent) => void;
  selectNewNode: (nodeObj: NodeObj) => void;
  selectNodes: (nodeObj: NodeObj[]) => void;
  unselectNodes: (nodeObj: NodeObj[]) => void;
  expandNode: (nodeObj: NodeObj) => void;
  linkDiv: () => void;
  scale: (scale: number) => void;
  move: (data: { dx: number; dy: number }) => void;
  updateArrowDelta: (arrow: Arrow) => void;
  showContextMenu: (e: MouseEvent) => void;
};

La mayoría de los eventos de operación de nodos están agrupados en el evento operation. ¡Talk is cheap! Agrégalo al proyecto y luego opera algunos nodos para entenderlo bien:

mei.bus.addListener("operation", (operation) => {
  console.log(operation);
});

A veces escuchar eventos no es suficiente. Si necesitas asegurar que los datos se inserten en la base de datos antes de mostrarlos, entonces necesitas usar interceptación de operaciones. Agrega la opción before en options, este es un objeto donde la clave es la operación que necesitas interceptar. Si necesitas interceptar la operación addChild, puedes escribir así:

let mei = new MindElixir({
  // ...
  before: {
    async addChild(el, obj) {
      try {
        await saveToDatabase(obj);
        return true;
      } catch (error) {
        console.error("Error adding child:", error);
        return false;
      }
    },
  },
});

De esta manera, el nodo hijo solo se agregará realmente después de que saveToDatabase() se ejecute exitosamente; si falla, se cancelará la operación de inserción.

Redibujo de mapas mentales

Además de usar el comportamiento predeterminado del núcleo Mind Elixir para actualizar mapas mentales, también puedes redibujar mapas mentales actualizando directamente los datos de los nodos.

La estructura completa de datos de nodo es la siguiente:

export interface NodeObj {
  topic: string;
  id: Uid;
  style?: {
    fontSize?: string;
    color?: string;
    background?: string;
    fontWeight?: string;
  };
  children?: NodeObj[];
  tags?: string[];
  icons?: string[];
  hyperLink?: string;
  expanded?: boolean;
  direction?: Left | Right;
  image?: {
    url: string;
    width: number;
    height: number;
    fit?: "fill" | "contain" | "cover";
  };
  branchColor?: string;
  dangerouslySetInnerHTML?: string;
  note?: string;
}

Modificando los datos del nodo puedes insertar elementos como imágenes, etiquetas, hipervínculos, etc. en los nodos. Por ejemplo, puedes obtener los datos actuales del mapa mental leyendo nodeData de la instancia Mind Elixir, luego modificarlos y finalmente llamar al método refresh para redibujar el mapa mental.

const data = mind.nodeData;
console.log(data);
data.topic = data.topic + "new Data";
mind.refresh();

¿Pero qué pasa si quieres actualizar todo el mapa mental con datos completamente nuevos? ¡También es posible! Pasa datos que cumplan con el formato Mind Elixir al método refresh y podrás actualizar inmediatamente todo el mapa.

import data from "https://esm.sh/mind-elixir/dist/example.js";
mind.refresh(data);

Libertad de rediseño

Mind Elixir te otorga la libertad de rediseñar mapas mentales.

Primero puedes ajustar fácilmente el estilo de todo el mapa mental a través de theme y cssVar. El núcleo incluye dos temas claro y oscuro MindElixir.DARK_THEME y MindElixir.THEME para elegir. Si necesitas un tema personalizado, puedes escribir un objeto según el formato del tema y pasarlo a Mind Elixir.

Un tema completo de Mind Elixir y su forma de uso es la siguiente:

const PROFESSIONAL_THEME = {
  name: "Professional",
  type: "light",
  palette: ["#2c2c2c", "#404040", "#555555", "#6a6a6a", "#7f7f7f", "#949494", "#a9a9a9"],
  cssVar: {
    "--node-gap-x": "32px",
    "--node-gap-y": "12px",
    "--main-gap-x": "68px",
    "--main-gap-y": "48px",
    "--root-radius": "8px",
    "--main-radius": "6px",
    "--root-color": "#ffffff",
    "--root-bgcolor": "#1a1a1a",
    "--root-border-color": "#333333",
    "--main-color": "#2c2c2c",
    "--main-bgcolor": "#ffffff",
    "--topic-padding": "4px",
    "--color": "#4a4a4a",
    "--bgcolor": "#fafafa",
    "--selected": "#666666",
    "--panel-color": "#2c2c2c",
    "--panel-bgcolor": "#ffffff",
    "--panel-border-color": "#e0e0e0",
  },
};

let mind = new MindElixir({
  el: "#map",
  theme: PROFESSIONAL_THEME,
});

Ten en cuenta que data también puede contener theme, y sobrescribirá el theme en options. Esto es para garantizar que cada mapa mental pueda tener un tema independiente. Si necesitas un tema fijo, recuerda establecer el theme de data como undefined durante la inicialización.

P.D. Si quieres modificar el tema nuevamente después de la inicialización, puedes usar el método changeTheme.

El main-gap comúnmente usado en cssVar puede ajustar el espaciado entre nodos principales:

node-gap puede ajustar el espaciado interno de los nodos:

Para otros parámetros que no se pueden ajustar a través de variables CSS, también puedes hacer ajustes finos directamente sobrescribiendo con CSS.

Profundizando un poco más, puedes ajustar el estilo de las líneas de conexión a través de generateMainBranch y generateSubBranch. (Ver ejemplos en el enlace de codepen a continuación)

Después de escribir generateMainBranch y generateSubBranch apropiados, si encuentras que la posición del botón de expandir/contraer no es correcta, puedes hacer ajustes finos a través de CSS. El estilo predeterminado es el siguiente:

// Estilo del botón expandir/contraer para nodos principales (nodos de siguiente nivel del nodo raíz)
me-main > me-wrapper > me-parent > me-epd {
  top: 50%;
  transform: translateY(-50%);
}
// Estilo del botón expandir/contraer para otros nodos hijos
me-epd {
  top: 100%;
  transform: translateY(-50%);
}
// Ajuste específico para botones expandir/contraer del lado izquierdo
.lhs {
  & > me-wrapper > me-parent > me-epd {
    left: -10px;
  }
  me-epd {
    left: 5px;
  }
}
// Ajuste específico para botones expandir/contraer del lado derecho
.rhs {
  & > me-wrapper > me-parent > me-epd {
    right: -10px;
  }
  me-epd {
    right: 5px;
  }
}

Estilos de nodos

Si además del estilo general, también tienes necesidades de personalización para los nodos, los nodos mismos pueden configurar style:

//...
{
  fontSize?: string
  color?: string
  background?: string
  fontWeight?: string
}
// ...

Si tienes necesidades de personalización muy fuertes para los nodos y sientes que esta configuración de style no es suficiente, ¡no hay problema, aún podemos satisfacerte!

También puedes ser más creativo a través de dangerouslySetInnerHTML, por ejemplo:

const data = {
  nodeData: {
    id: "me-root",
    topic: "Mind Elixir",
    tags: ["Mind Map Core"],
    children: [
      {
        topic: "Customized Div",
        id: "c00a2264f4532615",
        children: [
          {
            topic: "",
            id: "c00a2264f4532614",
            dangerouslySetInnerHTML:
              '<div><style>.title{font-size:50px}</style><div class="title">Title</div><div style="color: red; font-size: 20px;">Hello world</div></div>',
          },
        ],
      },
    ],
  },
};

Exportar imágenes

Gracias a modern-screenshot, que utiliza svg de manera inteligente para convertir divs intactos en imágenes. Básicamente, si no has hecho algo demasiado extremo con dangerouslySetInnerHTML (como videos), podrás exportar imágenes normalmente. @ssshooter/modern-screenshot agrega adicionalmente la opción padding para ajustar los márgenes de la captura de pantalla.

import { domToPng } from "@ssshooter/modern-screenshot";

const download = async () => {
  const dataUrl = await domToPng(mind.nodes, {
    onCloneNode: (node) => {
      const n = node as HTMLDivElement;
      n.style.position = "";
      n.style.top = "";
      n.style.left = "";
      n.style.bottom = "";
      n.style.right = "";
    },
    padding: 300,
    quality: 1,
  });
  const link = document.createElement("a");
  link.download = "screenshot.png";
  link.href = dataUrl;
  link.click();
};

Usar directamente modern-screenshot o el recientemente lanzado snapdom está bien. Si encuentras situaciones de capturas incompletas (principalmente resúmenes y líneas de conexión incompletas), puedes ajustar --map-padding en cssVar.

import { snapdom } from "@zumer/snapdom";

const dl2 = async () => {
  const result = await snapdom(mind.nodes);
  await result.download({ format: "jpg", filename: "my-capture" });
};

Si aún aparecen situaciones donde la imagen solo captura una parte, puede ser causado por scale no igual a 1. Puedes intentar establecer scale a 1 antes de la captura y restaurar el tamaño original después de completarla.

Uso en frameworks de renderizado del lado del servidor

Al usar Mind Elixir en frameworks de renderizado del lado del servidor como Next.js, a menudo te encontrarás con problemas como window is not defined. La razón es que Mind Elixir depende intensamente de varias operaciones DOM, no puede funcionar normalmente en entornos SSR.

Para resolver este problema, puedes usar useEffect para cargar Mind Elixir durante el renderizado del lado del cliente. Aquí tienes un ejemplo simple:

"use client";
import { useEffect } from "react";
import { mindMapExample } from "./mapExample";

export const MindMap = ({ className }: { className: string }) => {
  useEffect(() => {
    import("mind-elixir").then((MindElixir) => {
      const theme = MindElixir.default.DARK_THEME;
      theme.cssVar["--bgcolor"] = "rgba(0,0,0,0)";
      const mei = new MindElixir.default({
        el: "#map",
        direction: 2,
        theme,
      });
      mei.init({
        nodeData: mindMapExample,
      });
      mei.toCenter();
      window.addEventListener("resize", () => {
        mei.toCenter();
      });
    });
  }, []);
  return (
    <div id="wrapper" className={className}>
      <div
        id="map"
        className="pointer-events-none h-[50vh] w-screen"
        onScroll={(e) => e.preventDefault()}
      ></div>
    </div>
  );
};

Otras opciones de Mind Elixir

Mind Elixir tiene muchas otras opciones que se pueden configurar:

interface Options {
  // ...
  direction?: number; // Dirección de disposición de nodos, 0 izquierda 1 derecha 2 ambos lados
  locale?: Locale; // Selección de idioma
  contextMenu?: boolean | ContextMenuOption; // Si habilitar menú contextual, se pueden agregar opciones
  toolBar?: boolean; // Si habilitar barra de herramientas integrada
  keypress?: boolean | KeypressOptions; // Si habilitar atajos de teclado, se pueden agregar atajos personalizados
  mouseSelectionButton?: 0 | 2; // Botón de arrastre, arrastre con botón derecho por defecto
  before?: Before; // Interceptación de operaciones mencionada arriba
  newTopicName?: string; // Valor predeterminado para nuevos nodos
  allowUndo?: boolean; // Si habilitar deshacer/rehacer
  overflowHidden?: boolean; // Si la pantalla puede moverse, útil al mostrar tarjetas de mapas mentales
  alignment?: Alignment; // Cuando se establece como nodes, el centro de la pantalla es el centro del mapa mental; cuando se establece como root, el centro de la pantalla es el centro del nodo raíz, root por defecto
  scaleSensitivity?: number; // Sensibilidad de zoom de rueda de desplazamiento y menú
  draggable?: boolean; // Si se pueden arrastrar nodos
  editable?: boolean; // Si es editable
  // ...
}

Conclusión

A través de la introducción de este artículo, creo que ya has dominado varias técnicas de Mind Elixir desde el uso básico hasta la personalización avanzada. Si encuentras problemas durante el uso, o tienes mejores ideas y sugerencias, puedes compartirlas en la sección de comentarios, ¡también eres bienvenido a participar en discusiones en GitHub y enviar PRs! ¡Hagamos Mind Elixir más perfecto juntos!