@logicflow/core 2.2.1 → 2.2.2

package/dist/docs/tutorial/basic/theme.en.md

@@ -0,0 +1,154 @@
+---
+nav: Guide
+group:
+  title: Basics
+  order: 1
+title: Theme
+order: 3
+toc: content
+---
+
+LogicFlow provides a comprehensive theme customization feature that supports multiple ways to set and customize theme styles. Theme configuration allows unified management of styles for all elements in the canvas, including nodes, edges, text, and more.
+
+## Theme Configuration Categories
+
+Theme configuration supports the following main categories:
+
+- **Base Theme**: Common styles for base nodes and edges
+- **Node Theme**: Styles for various nodes (rectangle, circle, diamond, etc.)
+- **Edge Theme**: Styles for various edges (line, polyline, bezier curve, etc.)
+- **Text Theme**: Styles for node text and edge text
+- **Other Elements**: Styles for auxiliary elements like anchors, arrows, and snaplines
+- **Canvas Configuration**: Styles for background and grid
+
+For detailed theme configuration parameters, see [Theme API](../../api/logicflow-instance/theme.en.md)
+
+## Theme Configuration Methods
+
+### Way 1: Initialization Configuration
+
+When creating a LogicFlow instance, configure the theme using the `style` parameter.
+
+```tsx | pure
+const config = {
+  container: document.querySelector('#container'),
+  width: 1000,
+  height: 800,
+  style: { // Set default theme style
+    rect: { fill: '#FFFFFF', strokeWidth: 2 }, // Rectangle style
+    circle: { r: 15, fill: '#1E90FF' }, // Circle style
+    nodeText: { fontSize: 14, color: '#333333' }, // Node text style
+    edgeText: { fontSize: 12, color: '#666666' }, // Edge text style
+    anchor: { stroke: '#999999', fill: '#FFFFFF' }, // Anchor point style
+  },
+  themeMode: 'radius', // Set rounded corner theme
+}
+const lf = new LogicFlow(config)
+```
+
+### Way 2: Using the setTheme Method
+
+After creating a LogicFlow instance, dynamically update the theme configuration by calling the `setTheme` method.
+
+```tsx | pure
+// Dynamically configure theme
+lf.setTheme({
+  rect: { fill: '#FFFFFF', stroke: '#1890FF' }, // Rectangle style
+  circle: { r: 15, fill: '#1890FF' }, // Circle style
+  nodeText: { fontSize: 14, color: '#333333' }, // Node text style
+  edgeText: { fontSize: 12, color: '#666666' }, // Edge text style
+  anchor: { r: 4, fill: '#FFFFFF', stroke: '#1890FF' }, // Anchor point style
+}, 'radius')
+```
+
+## Built-in Theme Modes <Badge>2.0.14新增</Badge>
+
+LogicFlow comes with four built-in theme modes that allow you to quickly apply preset styles:
+
+- `default`: Default theme
+- `dark`: Dark theme
+- `colorful`: Colorful theme
+- `radius`: Rounded corner theme
+
+Applying built-in theme modes:
+
+```tsx | pure
+// Set theme mode during initialization
+const lf = new LogicFlow({
+  // ... other configurations
+  themeMode: 'radius', // Set rounded corner theme
+})
+
+// Dynamically switch theme modes
+lf.setTheme({}, 'dark') // Apply dark theme
+lf.setTheme({}, 'colorful') // Apply colorful theme
+
+// Apply theme mode with custom styles
+lf.setTheme({
+  rect: { fill: '#AECBFA' },
+  circle: { fill: '#C9DAF8' }
+}, 'radius')
+```
+
+## Custom Theme Modes <Badge>2.0.14新增</Badge>
+
+LogicFlow supports creating and managing custom theme modes. You can add new theme modes using the `addThemeMode` method:
+
+```tsx | pure
+// Register custom theme mode
+LogicFlow.addThemeMode('customTheme', {
+  baseNode: { fill: '#EFF5FF', stroke: '#4B83FF' },
+  rect: { radius: 8 },
+  circle: { r: 25 },
+  nodeText: { fontSize: 16, color: '#4B83FF' },
+  edgeText: { fontSize: 14, background: { fill: '#EEF7FE' } },
+  arrow: { offset: 6, verticalLength: 3 },
+})
+
+// Apply custom theme
+lf.setTheme({}, 'customTheme')
+```
+
+### Theme Style Priority
+
+The priority of theme styles (from low to high):
+
+#### Node, Edge, Text and Other Element Style Priority
+1. Built-in base styles (defaultTheme)
+2. Applied theme mode styles (specified via `themeMode` or second parameter of `setTheme`)
+3. Custom styles (specified via `style` or first parameter of `setTheme`)
+
+#### Background and Grid Style Priority
+Background and grid configurations have independent update mechanisms, with priority divided into two phases:
+
+**Initialization Phase Priority** (from low to high):
+1. Configuration in style: `background` and `grid` configurations in the constructor's `style` parameter
+2. Direct Parameter Configuration: Values set through `background` and `grid` parameters in the constructor (overrides configurations in style)
+
+**Runtime Phase Priority** (from low to high):
+1. Current Configuration: `background` and `grid` configurations after initialization
+2. Theme Mode Configuration: When calling `setTheme(style, themeMode)`, background and grid configurations in themeMode will override current configuration
+3. Custom Configuration: `background` and `grid` configurations in the style parameter of `setTheme(style, themeMode)` will override theme mode configuration
+
+```tsx | pure
+// Example: Priority application of background and grid
+
+// Initialization: Direct parameters > style parameters
+const lf = new LogicFlow({
+  style: {
+    background: { color: '#f0f0f0' }, // Lower priority
+    grid: { size: 15 }                // Lower priority
+  },
+  background: { color: '#f5f5f5' },   // Final effective (overrides style configuration)
+  grid: { size: 20 },                 // Final effective (overrides style configuration)
+})
+
+// Runtime: style parameters > themeMode parameters > current configuration
+lf.setTheme({
+  background: { color: '#ffffff' },   // Final effective background configuration
+  grid: { size: 10, visible: true },  // Final effective grid configuration
+}, 'dark') // Background and grid configurations in dark theme mode will be overridden by style parameters
+```
+
+## Usage Example
+<code id="graphData" src="../../../src/tutorial/basic/instance/theme"></code>

package/dist/docs/tutorial/basic/theme.zh.md

@@ -0,0 +1,157 @@
+---
+nav: 指南
+group:
+  title: 基础
+  order: 1
+title: 主题
+order: 3
+toc: content
+---
+
+LogicFlow 提供了完整的主题定制功能，支持通过多种方式设置和自定义主题样式。主题配置可以统一管理画布中所有元素的样式，包括节点、边、文本等。
+
+## 主题配置项
+
+主题配置支持以下主要类别：
+
+- **基础主题**：基础节点和边的通用样式
+- **节点主题**：各类节点（矩形、圆形、菱形等）的样式
+- **边主题**：各类边（直线、折线、贝塞尔曲线等）的样式
+- **文本主题**：节点文本、边文本的样式
+- **其他元素**：锚点、箭头、对齐线等辅助元素的样式
+- **画布配置**：背景和网格的样式
+
+详细的主题配置参数见[主题 API](../../api/logicflow-instance/theme.zh.md)
+
+
+## 主题配置方式
+
+### 方式一：初始化配置
+
+在创建 LogicFlow 实例时，通过 `style` 参数进行初始化配置。
+
+```tsx | pure
+const config = {
+  container: document.querySelector('#container'),
+  width: 1000,
+  height: 800,
+  style: { // 设置默认主题样式
+    rect: { fill: '#FFFFFF', strokeWidth: 2 }, // 矩形样式
+    circle: { r: 15, fill: '#1E90FF' }, // 圆形样式
+    nodeText: { fontSize: 14, color: '#333333' }, // 节点文本样式
+    edgeText: { fontSize: 12, color: '#666666' }, // 边文本样式
+    anchor: { stroke: '#999999', fill: '#FFFFFF' }, // 锚点样式
+  },
+  themeMode: 'radius', // 初始化设置圆角主题
+}
+const lf = new LogicFlow(config)
+```
+
+### 方式二：使用 setTheme 方法
+
+在 LogicFlow 实例创建后，调用 `setTheme` 方法动态更新主题配置。
+
+```tsx | pure
+// 动态配置主题
+lf.setTheme({
+  rect: { fill: '#FFFFFF', stroke: '#1890FF' }, // 矩形样式
+  circle: { r: 15, fill: '#1890FF' }, // 圆形样式
+  nodeText: { fontSize: 14, color: '#333333' }, // 节点文本样式
+  edgeText: { fontSize: 12, color: '#666666' }, // 边文本样式
+  anchor: { r: 4, fill: '#FFFFFF', stroke: '#1890FF' }, // 锚点样式
+}, 'radius')
+```
+
+## 内置主题模式<Badge>2.0.14新增</Badge>
+
+LogicFlow 内置了四种主题模式，可以快速应用预设样式：
+
+- `default`: 默认主题
+- `dark`: 暗黑主题
+- `colorful`: 彩色主题
+- `radius`: 圆角主题
+
+应用内置主题模式：
+
+```tsx | pure
+// 初始化时设置主题模式
+const lf = new LogicFlow({
+  // ... 其他配置
+  themeMode: 'radius', // 设置圆角主题
+})
+
+// 动态切换主题模式
+lf.setTheme({}, 'dark') // 应用暗黑主题
+lf.setTheme({}, 'colorful') // 应用彩色主题
+
+// 应用主题模式并自定义部分样式
+lf.setTheme({
+  rect: { fill: '#AECBFA' },
+  circle: { fill: '#C9DAF8' }
+}, 'radius')
+```
+
+## 自定义主题模式 <Badge>2.0.14新增</Badge>
+
+LogicFlow 支持创建和管理自定义主题模式。通过 `addThemeMode` 方法可以添加新的主题模式：
+
+```tsx | pure
+// 注册自定义主题模式
+LogicFlow.addThemeMode('customTheme', {
+  baseNode: { fill: '#EFF5FF', stroke: '#4B83FF' },
+  rect: { radius: 8 },
+  circle: { r: 25 },
+  nodeText: { fontSize: 16, color: '#4B83FF' },
+  edgeText: { fontSize: 14, background: { fill: '#EEF7FE' } },
+  arrow: { offset: 6, verticalLength: 3 },
+})
+
+// 应用自定义主题
+lf.setTheme({}, 'customTheme')
+```
+
+### 主题样式优先级
+
+主题样式的应用优先级（从低到高）：
+
+#### 节点、边、文本等元素样式优先级
+1. 内置基础样式（defaultTheme）
+2. 应用的主题模式样式（通过 `themeMode` 或 `setTheme` 的第二个参数设置）
+3. 自定义样式（通过 `style` 或 `setTheme` 的第一个参数设置）
+
+#### 背景和网格样式优先级
+背景（background）和网格（grid）配置具有独立的更新机制，其优先级分为两个阶段：
+
+**初始化阶段优先级**（从低到高）：
+1. style 中的配置：通过构造函数 `style` 参数中的 `background` 和 `grid` 配置
+2. 直接参数配置：通过构造函数中的 `background` 和 `grid` 参数设置的值（会覆盖 style 中的配置）
+
+**运行时阶段优先级**（从低到高）：
+1. 当前配置：初始化后的 `background` 和 `grid` 配置
+2. 主题模式配置：调用 `setTheme(style, themeMode)` 时，themeMode 中的背景和网格配置会覆盖当前配置
+3. 自定义配置：`setTheme(style, themeMode)` 中 style 参数的 `background` 和 `grid` 配置会覆盖主题模式配置
+
+```tsx | pure
+// 示例：背景和网格的优先级应用
+
+// 初始化时：直接参数 > style 参数
+const lf = new LogicFlow({
+  style: {
+    background: { color: '#f0f0f0' }, // 优先级较低
+    grid: { size: 15 }                // 优先级较低
+  },
+  background: { color: '#f5f5f5' },   // 最终生效（覆盖 style 中的配置）
+  grid: { size: 20 },                 // 最终生效（覆盖 style 中的配置）
+})
+
+// 运行时：style 参数 > themeMode 参数 > 当前配置
+lf.setTheme({
+  background: { color: '#ffffff' },   // 最终生效的背景配置
+  grid: { size: 10, visible: true },  // 最终生效的网格配置
+}, 'dark') // dark 主题模式的背景和网格配置会被 style 参数覆盖
+```
+
+## 使用示例
+<code id="graphData" src="../../../src/tutorial/basic/instance/theme"></code>
+
+