简体中文
Shiki 语法高亮
@cjslash/shiki 把 @cjslash/core 的分析结果接入 Shiki。节点拆分、位置映射和 HTML 渲染复用 @shikijs/twoslash,使用相同的 twoslash-* CSS 类。
安装
bash
pnpm add -D @cjslash/core @cjslash/shiki shiki @shikijs/twoslash@shikijs/twoslash 在这里用于直接导入展示样式;高亮器使用 @cjslash/shiki 导出的仓颉语法。
先分析,再高亮
ts
import { createCjslasher } from '@cjslash/core'
import { cangjieLanguage, transformerCjslash } from '@cjslash/shiki'
import { createHighlighter } from 'shiki'
await using cjslasher = await createCjslasher({ sdkPath: '/path/to/cangjie' })
const transformer = transformerCjslash({ cjslasher: cjslasher.analyze })
const source = 'let answer = 42\n// ^?\nmain() { println(answer) }\n'
await transformer.prepare(source)
const highlighter = await createHighlighter({
langs: [cangjieLanguage],
themes: ['monokai'],
})
try {
const html = highlighter.codeToHtml(source, {
lang: 'cj',
theme: 'monokai',
transformers: [transformer],
})
console.log(html)
}
finally {
highlighter.dispose()
}仓颉 LSP 是异步的,而 Shiki transformer 在渲染时同步读取结果。因此必须先等待 prepare(source),再把完全相同的原始源码传给 codeToHtml()。不要替换为 result.code,裁剪与坐标转换会由 transformer 完成。
安装展示样式
在展示 HTML 的应用入口导入:
ts
import '@shikijs/twoslash/style-rich.css'此样式供默认富文本渲染器使用。若希望在 VitePress 中获得 FloatingVue 悬浮层,请使用 VitePress 插件,它会自动安装客户端和样式。
准备结果的缓存
同一 transformer 按完整原始源码缓存成功结果。相同源码的并发 prepare() 共享一个 Promise,失败后可以重试。缓存属于 transformer 实例,不是磁盘缓存,也不跨构建保存。
执行选项在创建 transformer 时保存,可克隆的配置会被复制;取消信号和回调保留原始引用。更换 SDK 或分析配置时应创建新的 transformer。已准备的结果可以在分析器释放后继续渲染。
分析器由调用方管理,transformer 不会替调用方释放它。
触发规则
Shiki 集成默认转换 cj,同时支持 cangjie、Cangjie 别名,默认不要求 cjslash 元信息。设置 explicitTrigger: true 后,只转换元信息包含 cjslash 的代码块:
ts
import { createCjslasher } from '@cjslash/core'
import { transformerCjslash } from '@cjslash/shiki'
await using cjslasher = await createCjslasher({ sdkPath: '/path/to/cangjie' })
const transformer = transformerCjslash({
cjslasher: cjslasher.analyze,
explicitTrigger: true,
})nocjslash 和 no-cjslash 默认禁用转换。直接调用 Shiki 时,元信息通过 meta: { __raw: 'cjslash' } 传入。触发规则只决定渲染阶段是否转换,不能替代 prepare()。
自定义渲染
rendererRich 使用上游 RendererRichOptions,例如隐藏 SDK 返回的文档正文:
ts
import { createCjslasher } from '@cjslash/core'
import { transformerCjslash } from '@cjslash/shiki'
await using cjslasher = await createCjslasher({ sdkPath: '/path/to/cangjie' })
const transformer = transformerCjslash({
cjslasher: cjslasher.analyze,
rendererRich: { jsdoc: false },
})完全自定义 HTML 时可以传入上游 TwoslashRenderer 形状的 renderer。rendererClassic、rendererRich、ShikiTwoslashError 和相关类型直接重导出,接口见API 参考。
错误处理
prepare() 失败会直接拒绝 Promise,需要由调用方捕获。throws、onTwoslashError 和 onShikiError 控制同步渲染阶段的上游行为,不会捕获前一步的异步分析异常。
遇到“source has not been prepared”时,检查是否等待了准备完成,以及两次传入的源码在换行符和末尾空白上是否一致。