@kernelift/markdown 1.1.1 → 1.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +355 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,13 +1,364 @@
|
|
|
1
1
|
# @kernelift/markdown
|
|
2
2
|
|
|
3
|
-
`markdown-it` 和 `
|
|
3
|
+
基于 `markdown-it` 和 `highlight.js` 的 Markdown 渲染组件，提供强大的 Markdown 渲染和代码高亮功能。
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## 功能特性
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
- 基于 `markdown-it` 的完整 Markdown 语法支持
|
|
8
|
+
- 集成 `highlight.js` 代码高亮，支持多种编程语言
|
|
9
|
+
- 代码块带行号显示
|
|
10
|
+
- 代码块支持一键复制
|
|
11
|
+
- 代码块支持折叠/展开（超过指定行数自动折叠）
|
|
12
|
+
- 代码块行号与内容滚动同步
|
|
13
|
+
- 表格样式美化，支持斑马纹和悬停效果
|
|
14
|
+
- 支持自定义 Markdown 渲染配置
|
|
15
|
+
- 支持自定义插件扩展
|
|
16
|
+
- 支持暗黑模式样式
|
|
17
|
+
- 响应式设计
|
|
18
|
+
- 提供 `MdRender`（带完整样式）和 `MdRenderSimple`（简化版）两个组件
|
|
19
|
+
|
|
20
|
+
## 安装
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pnpm add @kernelift/markdown
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## 基础用法
|
|
27
|
+
|
|
28
|
+
### 简单示例
|
|
29
|
+
|
|
30
|
+
```vue
|
|
31
|
+
<script setup lang="ts">
|
|
32
|
+
import { ref } from 'vue';
|
|
33
|
+
import { MdRender } from '@kernelift/markdown';
|
|
34
|
+
|
|
35
|
+
const content = ref(`
|
|
36
|
+
# Hello World
|
|
37
|
+
|
|
38
|
+
这是一个 Markdown 渲染组件示例。
|
|
39
|
+
|
|
40
|
+
## 代码示例
|
|
41
|
+
|
|
42
|
+
\`\`\`javascript
|
|
43
|
+
function hello() {
|
|
44
|
+
console.log('Hello, World!');
|
|
45
|
+
}
|
|
46
|
+
\`\`\`
|
|
47
|
+
|
|
48
|
+
## 表格示例
|
|
49
|
+
|
|
50
|
+
| 姓名 | 年龄 | 职业 |
|
|
51
|
+
|------|------|------|
|
|
52
|
+
| 张三 | 25 | 工程师 |
|
|
53
|
+
| 李四 | 30 | 设计师 |
|
|
54
|
+
`);
|
|
55
|
+
</script>
|
|
56
|
+
|
|
57
|
+
<template>
|
|
58
|
+
<MdRender v-model="content" />
|
|
59
|
+
</template>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### 使用 Tailwind Prose 样式
|
|
8
63
|
|
|
9
64
|
```vue
|
|
65
|
+
<script setup lang="ts">
|
|
66
|
+
import { ref } from 'vue';
|
|
67
|
+
import { MdRender } from '@kernelift/markdown';
|
|
68
|
+
|
|
69
|
+
const content = ref('# Hello World');
|
|
70
|
+
</script>
|
|
71
|
+
|
|
10
72
|
<template>
|
|
11
|
-
<
|
|
73
|
+
<MdRender v-model="content" class="prose" />
|
|
12
74
|
</template>
|
|
13
75
|
```
|
|
76
|
+
|
|
77
|
+
### 自定义代码块配置
|
|
78
|
+
|
|
79
|
+
```vue
|
|
80
|
+
<script setup lang="ts">
|
|
81
|
+
import { ref } from 'vue';
|
|
82
|
+
import { MdRender } from '@kernelift/markdown';
|
|
83
|
+
|
|
84
|
+
const content = ref(`
|
|
85
|
+
\`\`\`javascript
|
|
86
|
+
// 这是一个很长的代码块
|
|
87
|
+
function longFunction() {
|
|
88
|
+
console.log('Line 1');
|
|
89
|
+
console.log('Line 2');
|
|
90
|
+
console.log('Line 3');
|
|
91
|
+
// ... 更多代码
|
|
92
|
+
console.log('Line 25');
|
|
93
|
+
}
|
|
94
|
+
\`\`\`
|
|
95
|
+
`);
|
|
96
|
+
|
|
97
|
+
const handleCopy = (code: string) => {
|
|
98
|
+
console.log('复制代码:', code);
|
|
99
|
+
navigator.clipboard.writeText(code);
|
|
100
|
+
};
|
|
101
|
+
</script>
|
|
102
|
+
|
|
103
|
+
<template>
|
|
104
|
+
<MdRender
|
|
105
|
+
v-model="content"
|
|
106
|
+
:code-max-height="15"
|
|
107
|
+
copy-text="复制"
|
|
108
|
+
expand-text="查看更多"
|
|
109
|
+
collapse-text="收起"
|
|
110
|
+
:on-copy="handleCopy"
|
|
111
|
+
/>
|
|
112
|
+
</template>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### 自定义 Markdown 配置
|
|
116
|
+
|
|
117
|
+
```vue
|
|
118
|
+
<script setup lang="ts">
|
|
119
|
+
import { ref } from 'vue';
|
|
120
|
+
import { MdRender } from '@kernelift/markdown';
|
|
121
|
+
import type { MarkdownItOptions } from '@kernelift/markdown';
|
|
122
|
+
|
|
123
|
+
const content = ref('# Hello World');
|
|
124
|
+
|
|
125
|
+
const options: MarkdownItOptions = {
|
|
126
|
+
html: false, // 禁用 HTML 标签
|
|
127
|
+
linkify: true, // 自动识别链接
|
|
128
|
+
breaks: true, // 启用换行符
|
|
129
|
+
typographer: true, // 启用排版优化
|
|
130
|
+
table: true // 启用表格
|
|
131
|
+
};
|
|
132
|
+
</script>
|
|
133
|
+
|
|
134
|
+
<template>
|
|
135
|
+
<MdRender
|
|
136
|
+
v-model="content"
|
|
137
|
+
:options="options"
|
|
138
|
+
/>
|
|
139
|
+
</template>
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### 使用自定义插件
|
|
143
|
+
|
|
144
|
+
```vue
|
|
145
|
+
<script setup lang="ts">
|
|
146
|
+
import { ref } from 'vue';
|
|
147
|
+
import { MdRender } from '@kernelift/markdown';
|
|
148
|
+
import markdownItEmoji from 'markdown-it-emoji';
|
|
149
|
+
|
|
150
|
+
const content = ref('Hello :smile: World!');
|
|
151
|
+
|
|
152
|
+
const plugins = [markdownItEmoji];
|
|
153
|
+
</script>
|
|
154
|
+
|
|
155
|
+
<template>
|
|
156
|
+
<MdRender
|
|
157
|
+
v-model="content"
|
|
158
|
+
:plugins="plugins"
|
|
159
|
+
/>
|
|
160
|
+
</template>
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### 使用 Expose 方法
|
|
164
|
+
|
|
165
|
+
```vue
|
|
166
|
+
<script setup lang="ts">
|
|
167
|
+
import { ref } from 'vue';
|
|
168
|
+
import { MdRender } from '@kernelift/markdown';
|
|
169
|
+
|
|
170
|
+
const content = ref('# Hello World');
|
|
171
|
+
const renderRef = ref();
|
|
172
|
+
|
|
173
|
+
const getRenderedHtml = () => {
|
|
174
|
+
renderRef.value?.execMethods((instance) => {
|
|
175
|
+
const html = instance.render(content.value);
|
|
176
|
+
console.log('渲染后的 HTML:', html);
|
|
177
|
+
});
|
|
178
|
+
};
|
|
179
|
+
|
|
180
|
+
const parseInline = () => {
|
|
181
|
+
renderRef.value?.execMethods((instance) => {
|
|
182
|
+
const result = instance.parseInline('**粗体** *斜体*', {});
|
|
183
|
+
console.log('解析结果:', result);
|
|
184
|
+
});
|
|
185
|
+
};
|
|
186
|
+
</script>
|
|
187
|
+
|
|
188
|
+
<template>
|
|
189
|
+
<div>
|
|
190
|
+
<div style="margin-bottom: 10px;">
|
|
191
|
+
<button @click="getRenderedHtml">获取渲染 HTML</button>
|
|
192
|
+
<button @click="parseInline">解析内联文本</button>
|
|
193
|
+
</div>
|
|
194
|
+
<MdRender
|
|
195
|
+
ref="renderRef"
|
|
196
|
+
v-model="content"
|
|
197
|
+
/>
|
|
198
|
+
</div>
|
|
199
|
+
</template>
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### 暗黑模式
|
|
203
|
+
|
|
204
|
+
```vue
|
|
205
|
+
<script setup lang="ts">
|
|
206
|
+
import { ref } from 'vue';
|
|
207
|
+
import { MdRender } from '@kernelift/markdown';
|
|
208
|
+
|
|
209
|
+
const content = ref('# Hello World');
|
|
210
|
+
const isDark = ref(true);
|
|
211
|
+
</script>
|
|
212
|
+
|
|
213
|
+
<template>
|
|
214
|
+
<div :class="{ dark: isDark }">
|
|
215
|
+
<MdRender
|
|
216
|
+
v-model="content"
|
|
217
|
+
:class="{ dark: isDark }"
|
|
218
|
+
/>
|
|
219
|
+
</div>
|
|
220
|
+
</template>
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
### 使用简化版组件
|
|
224
|
+
|
|
225
|
+
```vue
|
|
226
|
+
<script setup lang="ts">
|
|
227
|
+
import { ref } from 'vue';
|
|
228
|
+
import { MdRenderSimple } from '@kernelift/markdown';
|
|
229
|
+
|
|
230
|
+
const content = ref('# Hello World');
|
|
231
|
+
</script>
|
|
232
|
+
|
|
233
|
+
<template>
|
|
234
|
+
<MdRenderSimple v-model="content" />
|
|
235
|
+
</template>
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
## Props
|
|
239
|
+
|
|
240
|
+
| 参数 | 说明 | 类型 | 默认值 |
|
|
241
|
+
|------|------|------|--------|
|
|
242
|
+
| modelValue | Markdown 内容（v-model） | `string` | - |
|
|
243
|
+
| plugins | 自定义插件数组 | `Array<any>` | `[]` |
|
|
244
|
+
| options | MarkdownIt 配置选项 | `MarkdownItOptions` | 见下方默认配置 |
|
|
245
|
+
| onCopy | 复制代码回调 | `(code: string) => void` | - |
|
|
246
|
+
| copyText | 复制按钮文本 | `string` | `'复制代码'` |
|
|
247
|
+
| expandText | 展开按钮文本 | `string` | `'展开'` |
|
|
248
|
+
| collapseText | 收起按钮文本 | `string` | `'收起'` |
|
|
249
|
+
| codeMaxHeight | 代码块最大高度（行数），超过则折叠 | `number` | `20` |
|
|
250
|
+
|
|
251
|
+
### MarkdownItOptions 默认配置
|
|
252
|
+
|
|
253
|
+
| 参数 | 默认值 | 说明 |
|
|
254
|
+
|------|--------|------|
|
|
255
|
+
| html | `true` | 允许 HTML 标签 |
|
|
256
|
+
| linkify | `true` | 自动识别链接 |
|
|
257
|
+
| breaks | `false` | 启用换行符转换 |
|
|
258
|
+
| typographer | `true` | 启用排版优化 |
|
|
259
|
+
| table | `true` | 启用表格支持 |
|
|
260
|
+
| xhtmlOut | `false` | 关闭 XHTML 严格模式 |
|
|
261
|
+
|
|
262
|
+
## Emits
|
|
263
|
+
|
|
264
|
+
| 事件名 | 说明 | 参数 |
|
|
265
|
+
|--------|------|------|
|
|
266
|
+
| update:modelValue | 内容变化时触发 | `(value: string)` |
|
|
267
|
+
|
|
268
|
+
## Expose
|
|
269
|
+
|
|
270
|
+
| 方法名/属性 | 说明 | 类型 |
|
|
271
|
+
|-------------|------|------|
|
|
272
|
+
| renderInstance | MarkdownIt 实例 | `ShallowRef<MarkdownIt \| undefined>` |
|
|
273
|
+
| execMethods | 执行 MarkdownIt 实例方法 | `(fn: (renderInstance: MarkdownIt) => void) => void` |
|
|
274
|
+
|
|
275
|
+
## 组件对比
|
|
276
|
+
|
|
277
|
+
| 特性 | MdRender | MdRenderSimple |
|
|
278
|
+
|------|----------|----------------|
|
|
279
|
+
| 完整样式 | ✅ | ❌ |
|
|
280
|
+
| 暗黑模式 | ✅ | ❌ |
|
|
281
|
+
| 表格美化 | ✅ | ✅ |
|
|
282
|
+
| 代码高亮 | ✅ | ✅ |
|
|
283
|
+
| 代码块折叠 | ✅ | ✅ |
|
|
284
|
+
| 代码块复制 | ✅ | ✅ |
|
|
285
|
+
| 行号显示 | ✅ | ✅ |
|
|
286
|
+
| 滚动同步 | ✅ | ✅ |
|
|
287
|
+
| 体积 | 较大 | 较小 |
|
|
288
|
+
|
|
289
|
+
## 样式说明
|
|
290
|
+
|
|
291
|
+
### 内置样式
|
|
292
|
+
|
|
293
|
+
`MdRender` 组件内置了完整的 Markdown 渲染样式，包括：
|
|
294
|
+
- 标题样式（h1-h6）
|
|
295
|
+
- 段落样式
|
|
296
|
+
- 列表样式
|
|
297
|
+
- 引用样式
|
|
298
|
+
- 代码块样式
|
|
299
|
+
- 表格样式
|
|
300
|
+
- 链接样式
|
|
301
|
+
- 图片样式
|
|
302
|
+
- 分隔线样式
|
|
303
|
+
|
|
304
|
+
### Tailwind Prose
|
|
305
|
+
|
|
306
|
+
如果使用 Tailwind CSS，可以配合 `@tailwindcss/typography` 插件使用：
|
|
307
|
+
|
|
308
|
+
```vue
|
|
309
|
+
<template>
|
|
310
|
+
<MdRender v-model="content" class="prose prose-sm max-w-none" />
|
|
311
|
+
</template>
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
### 自定义样式
|
|
315
|
+
|
|
316
|
+
可以通过 CSS 变量自定义样式：
|
|
317
|
+
|
|
318
|
+
```css
|
|
319
|
+
.kernelift-md-render {
|
|
320
|
+
--markdown-text-color: #2c3e50;
|
|
321
|
+
}
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
## 代码高亮
|
|
325
|
+
|
|
326
|
+
组件使用 `highlight.js` 进行代码高亮，支持以下语言：
|
|
327
|
+
|
|
328
|
+
- JavaScript / TypeScript
|
|
329
|
+
- Python
|
|
330
|
+
- Java
|
|
331
|
+
- C / C++
|
|
332
|
+
- Go
|
|
333
|
+
- Rust
|
|
334
|
+
- PHP
|
|
335
|
+
- Ruby
|
|
336
|
+
- HTML / CSS
|
|
337
|
+
- Vue
|
|
338
|
+
- React (JSX)
|
|
339
|
+
- 等更多语言...
|
|
340
|
+
|
|
341
|
+
## 注意事项
|
|
342
|
+
|
|
343
|
+
1. 代码块默认超过 20 行会自动折叠，可通过 `codeMaxHeight` 调整
|
|
344
|
+
2. 使用 `plugins` 时，插件必须符合 `markdown-it` 插件规范
|
|
345
|
+
3. `onCopy` 回调优先于默认复制行为
|
|
346
|
+
4. 暗黑模式需要父容器或组件本身添加 `dark` 类名
|
|
347
|
+
5. `MdRenderSimple` 不包含内置样式，需要自行引入样式或使用 Tailwind Prose
|
|
348
|
+
|
|
349
|
+
## 类型定义
|
|
350
|
+
|
|
351
|
+
```typescript
|
|
352
|
+
export type MarkdownItOptions = import('markdown-it').Options;
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
## 依赖
|
|
356
|
+
|
|
357
|
+
- `markdown-it`: ^14.1.0
|
|
358
|
+
- `highlight.js`: ^11.11.1
|
|
359
|
+
- `lodash-es`: ^4.17.21
|
|
360
|
+
- `vue`: ^3.5.22
|
|
361
|
+
|
|
362
|
+
## 许可证
|
|
363
|
+
|
|
364
|
+
GPL-3.0-only
|