数学图像功能实现教程

功能预览#

最终效果：

✅ 在 Markdown 中使用 mathgraph 代码块
✅ 自动渲染交互式数学图形
✅ 滑动条实时调整参数
✅ 左图右参数布局
✅ 自动适配 Fuwari 主题
✅ 支持亮色/暗色模式
✅ 移动端响应式设计

NOTE
所有代码都是AI敲的，所以相关问题不要问我

实现步骤#

步骤 1: 下载 JSXGraph 库到本地#

首先，我们需要将 JSXGraph 库下载到本地，避免远程调用可能遇到的网络问题。

1
# 创建目录
2
mkdir -p public/jsxgraph
3

4
# 下载 JSXGraph 核心库
5
curl -o public/jsxgraph/jsxgraphcore.js https://cdn.jsdelivr.net/npm/jsxgraph@1.8.0/distrib/jsxgraphcore.js
6

7
# 下载 JSXGraph 样式
8
curl -o public/jsxgraph/jsxgraph.css https://cdn.jsdelivr.net/npm/jsxgraph@1.8.0/distrib/jsxgraph.css

说明：

public/ 目录下的文件会被直接复制到构建输出
使用本地文件避免依赖远程 CDN
确保部署到任何平台都能正常工作

步骤 2: 创建 Remark 插件#

创建 src/plugins/remark-mathgraph.js 文件，用于解析 Markdown 中的 mathgraph 代码块。

1
import { visit } from "unist-util-visit";
2

3
/**
4
 * Remark plugin to detect and transform mathgraph code blocks.
5
 * Converts ```mathgraph code blocks to interactive math graph components.
6
 */
7
export function remarkMathGraph() {
8
  return (tree) => {
9
    visit(tree, "code", (node) => {
10
      if (node.lang === "mathgraph") {
11
        const config = parseMathGraphConfig(node.value || "");
12
        const configJson = JSON.stringify(config);
13
        const graphId = `mathgraph-${Math.random().toString(36).substr(2, 9)}`;
14

15
        // 创建完整的 HTML 结构
16
        node.data = {
17
          hName: "div",
18
          hProperties: {
19
            className: ["math-graph-container"],
20
          },
21
          hChildren: [
22
            {
23
              type: "element",
24
              tagName: "div",
25
              properties: {
26
                className: ["math-graph-wrapper"],
27
              },
28
              children: [
29
                {
30
                  type: "element",
31
                  tagName: "div",
32
                  properties: {
33
                    className: ["math-graph-canvas"],
34
                    id: graphId,
35
                    "data-config": configJson,
36
                  },
37
                  children: [],
38
                },
39
              ],
40
            },
41
          ],
42
        };
43
      }
44
    });
45
  };
46
}
47

48
function parseMathGraphConfig(content) {
49
  const config = {
50
    sliders: [],
51
    expressions: [],
52
    axis: true,
53
    grid: true,
54
  };
55

56
  const lines = content.split("\n");
57
  let currentSection = "";
58

59
  for (const line of lines) {
60
    const trimmed = line.trim();
61

62
    // 跳过空行和注释
63
    if (!trimmed || trimmed.startsWith("#")) continue;
64

65
    // 检测区块
66
    if (trimmed === "sliders:") {
67
      currentSection = "sliders";
68
      continue;
69
    }
70
    if (trimmed === "expressions:") {
71
      currentSection = "expressions";
72
      continue;
73
    }
74

75
    // 解析滑动条配置
76
    if (currentSection === "sliders") {
77
      const sliderMatch = trimmed.match(/^(\w+):\s*\[([^\]]+)\]$/);
78
      if (sliderMatch) {
79
        const name = sliderMatch[1];
80
        const values = sliderMatch[2].split(",").map((v) => parseFloat(v.trim()));
81
        if (values.length >= 3) {
82
          config.sliders.push({
83
            name,
84
            min: values[0],
85
            value: values[1],
86
            max: values[2],
87
            step: values[3] || 0.1,
88
          });
89
        }
90
      }
91
    }
92

93
    // 解析表达式
94
    if (currentSection === "expressions") {
95
      const exprMatch = trimmed.match(/^-\s*(.+)$/);
96
      if (exprMatch) {
97
        config.expressions.push(exprMatch[1].trim());
98
      }
99
    }
100

101
    // 解析其他配置
102
    if (trimmed.startsWith("axis:")) {
103
      config.axis = trimmed.split(":")[1].trim() === "true";
104
    }
105
    if (trimmed.startsWith("grid:")) {
106
      config.grid = trimmed.split(":")[1].trim() === "true";
107
    }
108
  }
109

110
  return config;
111
}

代码说明：

使用 unist-util-visit 遍历 Markdown AST
检测 lang === "mathgraph" 的代码块
解析配置内容（滑动条、表达式等）
生成 HTML 结构，包含配置数据

步骤 3: 注册 Remark 插件#

在 astro.config.mjs 中注册插件：

1
import { remarkMathGraph } from "./src/plugins/remark-mathgraph.js";
2

3
export default defineConfig({
4
  // ... 其他配置
5
  markdown: {
6
    remarkPlugins: [
7
      // ... 其他插件
8
      remarkMathGraph,
9
    ],
10
  },
11
});

步骤 4: 添加样式#

创建 src/styles/mathgraph.css 文件：

1
/* MathGraph 样式 - 左图右参数布局 */
2

3
.math-graph-container {
4
  margin: 1.5rem 0;
5
  border-radius: 0.75rem;
6
  overflow: hidden;
7
  background: var(--card-bg);
8
  border: 1px solid var(--line-divider);
9
}
10

11
/* 左图右参数布局 */
12
.math-graph-layout {
13
  display: flex;
14
  flex-direction: row;
15
  gap: 0;
16
  min-height: 400px;
17
}
18

19
.math-graph-canvas-wrapper {
20
  flex: 1;
21
  min-width: 0;
22
  position: relative;
23
}
24

25
.math-graph-canvas {
26
  width: 100%;
27
  height: 400px;
28
  background: var(--page-bg);
29
}
30

31
/* 参数控制面板 */
32
.math-graph-controls {
33
  width: 280px;
34
  min-width: 280px;
35
  background: var(--btn-regular-bg);
36
  border-left: 1px solid var(--line-divider);
37
  display: flex;
38
  flex-direction: column;
39
}
40

41
.math-graph-controls-title {
42
  padding: 1rem;
43
  font-size: 0.875rem;
44
  font-weight: 600;
45
  color: var(--btn-content);
46
  border-bottom: 1px solid var(--line-divider);
47
  text-align: center;
48
}
49

50
/* 滑动条样式 */
51
.math-slider-wrapper {
52
  display: flex;
53
  flex-direction: column;
54
  gap: 0.5rem;
55
  padding: 0.75rem;
56
  background: var(--card-bg);
57
  border-radius: 0.5rem;
58
  border: 1px solid var(--line-divider);
59
}
60

61
.math-slider-label {
62
  font-size: 0.875rem;
63
  font-weight: 600;
64
  color: var(--btn-content);
65
  display: flex;
66
  justify-content: space-between;
67
}
68

69
.math-slider-value {
70
  color: var(--primary);
71
}
72

73
.math-slider-input {
74
  width: 100%;
75
  height: 6px;
76
  border-radius: 3px;
77
  background: var(--btn-plain-bg-hover);
78
  outline: none;
79
  -webkit-appearance: none;
80
  cursor: pointer;
81
}
82

83
.math-slider-input::-webkit-slider-thumb {
84
  -webkit-appearance: none;
85
  width: 16px;
86
  height: 16px;
87
  border-radius: 50%;
88
  background: var(--primary);
89
  cursor: pointer;
90
}
91

92
/* 响应式设计 */
93
@media (max-width: 768px) {
94
  .math-graph-layout {
95
    flex-direction: column;
96
  }
97

98
  .math-graph-controls {
99
    width: 100%;
100
    border-left: none;
101
    border-top: 1px solid var(--line-divider);
102
  }
103
}

样式要点：

使用 Fuwari 的 CSS 变量（--card-bg, --primary 等）
左图右参数布局（桌面端）
移动端自动切换为上下布局

步骤 5: 在 Layout 中引入样式和脚本#

编辑 src/layouts/Layout.astro：

1
---
2
// 在文件顶部引入样式
3
import "../styles/mathgraph.css";
4
---
5

6
<head>
7
  <!-- 其他 head 内容 -->
8

9
  <!-- JSXGraph 库 -->
10
  <link rel="stylesheet" href="/jsxgraph/jsxgraph.css" />
11
  <script src="/jsxgraph/jsxgraphcore.js" defer></script>
12
</head>

步骤 6: 添加初始化脚本#

在 src/layouts/Layout.astro 的 <script> 标签中添加初始化代码：

1
// ========== 数学图形初始化 ==========
2
let mathGraphObserver = null;
3

4
function initMathGraphs() {
5
  const containers = document.querySelectorAll(
6
    '.math-graph-canvas[data-config]:not([data-initialized])'
7
  );
8

9
  if (containers.length === 0) return;
10

11
  // 检查 JSXGraph 是否已加载
12
  if (!window.JXG) {
13
    waitForJSXGraph().then(initMathGraphs);
14
    return;
15
  }
16

17
  containers.forEach((container) => {
18
    const configStr = container.getAttribute('data-config');
19
    if (!configStr) return;
20

21
    try {
22
      const config = JSON.parse(configStr);
23
      createMathGraph(container, config);
24
      container.setAttribute('data-initialized', 'true');
25
    } catch (e) {
26
      console.error('MathGraph config parse error:', e);
27
    }
28
  });
29
}
30

31
// 使用 MutationObserver 监听 DOM 变化
32
function observeMathGraphs() {
33
  if (mathGraphObserver) {
34
    mathGraphObserver.disconnect();
35
  }
36

37
  initMathGraphs();
38

39
  mathGraphObserver = new MutationObserver((mutations) => {
40
    let shouldInit = false;
41

42
    mutations.forEach((mutation) => {
43
      mutation.addedNodes.forEach((node) => {
44
        if (node instanceof Element) {
45
          if (node.classList?.contains('math-graph-canvas') ||
46
              node.querySelector?.('.math-graph-canvas')) {
47
            shouldInit = true;
48
          }
49
        }
50
      });
51
    });
52

53
    if (shouldInit) {
54
      setTimeout(initMathGraphs, 100);
55
    }
56
  });
57

58
  mathGraphObserver.observe(document.body, {
59
    childList: true,
60
    subtree: true,
61
  });
62
}
63

64
// 等待 JSXGraph 加载
65
function waitForJSXGraph() {
66
  return new Promise((resolve) => {
67
    if (window.JXG) {
68
      resolve();
69
    } else {
70
      const checkInterval = setInterval(() => {
71
        if (window.JXG) {
72
          clearInterval(checkInterval);
73
          resolve();
74
        }
75
      }, 100);
76

77
      setTimeout(() => {
78
        clearInterval(checkInterval);
79
        console.error('JSXGraph loading timeout');
80
      }, 5000);
81
    }
82
  });
83
}
84

85
// 创建数学图形
86
async function createMathGraph(container, config) {
87
  const boardId = container.id;
88
  const JXG = window.JXG;
89

90
  // 获取父容器
91
  const wrapper = container.parentElement;
92
  if (!wrapper) return;
93

94
  // 创建布局容器
95
  const layoutContainer = document.createElement('div');
96
  layoutContainer.className = 'math-graph-layout';
97

98
  const graphContainer = document.createElement('div');
99
  graphContainer.className = 'math-graph-canvas-wrapper';
100

101
  const controlsContainer = document.createElement('div');
102
  controlsContainer.className = 'math-graph-controls';
103

104
  const controlsTitle = document.createElement('div');
105
  controlsTitle.className = 'math-graph-controls-title';
106
  controlsTitle.textContent = '参数调整';
107
  controlsContainer.appendChild(controlsTitle);
108

109
  const slidersContainer = document.createElement('div');
110
  slidersContainer.className = 'math-graph-sliders-vertical';
111
  controlsContainer.appendChild(slidersContainer);
112

113
  // 移动容器到新布局
114
  wrapper.removeChild(container);
115
  graphContainer.appendChild(container);
116
  layoutContainer.appendChild(graphContainer);
117
  layoutContainer.appendChild(controlsContainer);
118
  wrapper.appendChild(layoutContainer);
119

120
  // 创建 JSXGraph 画板
121
  const board = JXG.JSXGraph.initBoard(boardId, {
122
    boundingbox: [-10, 10, 10, -10],
123
    axis: config.axis !== false,
124
    grid: config.grid !== false,
125
    showCopyright: false,
126
    showNavigation: false,
127
    keepAspectRatio: false,
128
  });
129

130
  const sliders = {};
131

132
  // 创建滑动条
133
  config.sliders.forEach((sliderConfig, index) => {
134
    const sliderWrapper = document.createElement('div');
135
    sliderWrapper.className = 'math-slider-wrapper';
136

137
    const labelRow = document.createElement('div');
138
    labelRow.className = 'math-slider-label';
139

140
    const labelText = document.createElement('span');
141
    labelText.textContent = sliderConfig.name;
142

143
    const valueDisplay = document.createElement('span');
144
    valueDisplay.className = 'math-slider-value';
145
    valueDisplay.textContent = sliderConfig.value.toFixed(2);
146

147
    labelRow.appendChild(labelText);
148
    labelRow.appendChild(valueDisplay);
149

150
    const slider = document.createElement('input');
151
    slider.type = 'range';
152
    slider.min = String(sliderConfig.min);
153
    slider.max = String(sliderConfig.max);
154
    slider.step = String(sliderConfig.step);
155
    slider.value = String(sliderConfig.value);
156
    slider.className = 'math-slider-input';
157

158
    slider.addEventListener('input', () => {
159
      const val = parseFloat(slider.value);
160
      valueDisplay.textContent = val.toFixed(2);
161
      sliders[sliderConfig.name].setValue(val);
162
      board.update();
163
    });
164

165
    sliderWrapper.appendChild(labelRow);
166
    sliderWrapper.appendChild(slider);
167
    slidersContainer.appendChild(sliderWrapper);
168

169
    // 创建 JSXGraph 内部滑动条
170
    sliders[sliderConfig.name] = board.create('slider', [
171
      [-8, -8 + index * 1.5],
172
      [-3, -8 + index * 1.5],
173
      [sliderConfig.min, sliderConfig.value, sliderConfig.max]
174
    ], {
175
      name: sliderConfig.name,
176
      visible: false,
177
    });
178
  });
179

180
  // 创建函数曲线
181
  config.expressions.forEach((expr, index) => {
182
    try {
183
      const func = new Function(
184
        'x',
185
        ...Object.keys(sliders),
186
        `with(Math) { return ${expr}; }`
187
      );
188

189
      board.create('functiongraph', [
190
        (x) => {
191
          const sliderValues = Object.keys(sliders).map(key => sliders[key].Value());
192
          return func(x, ...sliderValues);
193
        }
194
      ], {
195
        strokeColor: getGraphColor(index),
196
        strokeWidth: 2,
197
      });
198
    } catch (e) {
199
      console.error('Expression parse error:', expr, e);
200
    }
201
  });
202
}
203

204
function getGraphColor(index) {
205
  const colors = [
206
    '#3b82f6',
207
    '#e74c3c',
208
    '#27ae60',
209
    '#f39c12',
210
    '#9b59b6',
211
    '#1abc9c',
212
  ];
213
  return colors[index % colors.length];
214
}
215

216
// 初始化
217
function initOnLoad() {
218
  waitForJSXGraph().then(() => {
219
    observeMathGraphs();
220
  });
221
}
222

223
document.addEventListener('DOMContentLoaded', initOnLoad);
224

225
if (document.readyState !== 'loading') {
226
  initOnLoad();
227
}
228

229
// 支持 Swup 页面切换
230
document.addEventListener('swup:contentReplaced', () => {
231
  setTimeout(initMathGraphs, 300);
232
});
233

234
if (window?.swup?.hooks) {
235
  window.swup.hooks.on('page:view', () => {
236
    setTimeout(initMathGraphs, 300);
237
  });
238
}

关键点说明：

MutationObserver: 监听 DOM 变化，自动初始化新添加的图形
waitForJSXGraph: 等待 JSXGraph 库加载完成
防重复初始化: 使用 data-initialized 标记
Swup 兼容: 监听页面切换事件

使用方法#

基本语法#

在 Markdown 文件中使用：

1
```mathgraph
2
sliders:
3
  参数名: [最小值, 默认值, 最大值, 步长]
4
expressions:
5
  - 数学表达式
6
axis: true/false
7
grid: true/false
8
```

支持的数学函数#

基本运算: +, -, *, /, ^
三角函数: sin, cos, tan, asin, acos, atan
指数对数: exp, log, log10, sqrt
其他: abs, floor, ceil, round

进阶定制#

自定义颜色#

修改 getGraphColor 函数：

1
function getGraphColor(index) {
2
  const colors = [
3
    '#your-color-1',
4
    '#your-color-2',
5
    // ...
6
  ];
7
  return colors[index % colors.length];
8
}

调整画板范围#

修改 boundingbox 参数：

1
const board = JXG.JSXGraph.initBoard(boardId, {
2
  boundingbox: [-5, 5, 5, -5], // [x_min, y_max, x_max, y_min]
3
  // ...
4
});

添加更多配置选项#

在 parseMathGraphConfig 函数中添加新的配置项：

1
if (trimmed.startsWith("boundingbox:")) {
2
  const values = trimmed.split(":")[1].trim().split(",").map(Number);
3
  config.boundingbox = values;
4
}

常见问题#

Q: 图形不显示？#

A: 检查以下几点：

JSXGraph 文件是否正确下载到 public/jsxgraph/
浏览器控制台是否有错误
Markdown 语法是否正确

Q: 需要手动刷新才显示？#

A: 这是初始化时机问题，确保：

使用了 MutationObserver
等待 JSXGraph 加载完成
监听了 Swup 页面切换事件