跳到正文

分析结果 ​

analyze() 返回 CjslashResult。它继承 twoslash-protocol 的 TwoslashGenericResult,保留上游节点形状,增加仓颉元数据和分类 getter。

顶层字段 ​

字段类型含义
codestring最终用于展示的源码
extension'cj'输出语言扩展名
nodesTwoslashNode[]所有类型、诊断与标记节点
metaCjslashResultMeta配置和原始源码位置的元数据
hoversNodeHover[]自动 hover 节点
queriesNodeQuery[]显式类型查询节点
errorsNodeError[]诊断节点,包含警告等其他级别
highlightsNodeHighlight[]范围高亮节点
tagsNodeTag[]自定义注释标签
completionsNodeCompletion[]^| 或显式位置触发的补全节点

nodes 是唯一节点数据源,其余分类视图每次读取时从 nodes 派生。

ts
import { 
createCjslasher
} from '@cjslash/core'
await using
cjslasher
= await
createCjslasher
({
sdkPath
: '/path/to/cangjie' })
const
result
= await
cjslasher
.
analyze
('let answer = 42\n// ^?\nmain() { println(answer) }\n')
const
query
=
result
.
queries
[0]
if (
query
) {
console
.
log
(
query
.
text
)
console
.
log
(
result
.
code
.
slice
(
query
.
start
,
query
.
start
+
query
.
length
))
}

后一项输出查询目标 answer。

信息节点 ​

节点通过 type 区分,位置字段保留上游形状:

公共字段含义
typehover、query、error、highlight、tag 或 completion
start输出源码中的起始偏移,从零开始
length范围长度,允许为零
line起始行号,从零开始
character起始列号,从零开始

常用的类型专属字段:

节点字段
hover、querytarget 为目标源码,text 为签名,可包含 docs
errortext 为诊断消息,可包含 code、level、filename 和 id
highlight可包含说明 text
tagname 为标签名称,text 为可选内容
completioncompletions 为 { name, kind? }[],completionsPrefix 为输入前缀,length 为 0

使用 node.type 收窄联合类型后读取对应字段。NodeHover、NodeQuery 等直接来自 twoslash-protocol,没有额外的仓颉节点格式。

坐标与裁剪 ​

start、length、character 和显式位置参数使用 UTF-16 代码单元,而不是字节或视觉字符宽度。JavaScript 的字符串索引与 slice() 使用同样的单位;例如 emoji 可能占用两个代码单元。

数据坐标基准
result.nodes 和分类 getter最终的 result.code
result.meta.removals原始输入
result.meta.positionQueries原始输入
result.meta.positionCompletions原始输入
result.meta.positionHighlights原始输入
CjslashError.diagnostics失败分析的原始输入

节点区间为 [start, start + length)。裁剪和高亮区间为 [start, end),右端点不包含在范围内。

默认情况下,移除标记和隐藏代码后会重新计算节点位置。启用 keepNotations 时,result.code 保持原始输入,节点也对应原始输入;meta.removals 仍记录原本应移除的范围。

元数据 ​

CjslashResultMeta 字段含义
extension固定为 cj
handbookOptions应用默认值、调用配置和源码标记后的完整选项
removals原始输入中需要移除的区间
positionQueries原始输入中的显式查询偏移
positionCompletions原始输入中的补全光标偏移
positionHighlights原始输入中的 [start, end, text?] 高亮范围

元数据用于关联作者输入和最终展示。交给 Shiki 时仍传原始源码,由 transformer 读取准备好的结果。

多文件示例的节点偏移和行号仍对应完整代码块,不会在新文件处归零。诊断的 filename 对应相应的虚拟文件名;裁剪不会改变这个文件名。

协议工具 ​

从 @cjslash/protocol 可以直接导入上游的 Position、Range、TwoslashNode、NodeWithoutPosition 和节点类型,以及以下工具:

createPositionConverter、splitLines、isInRange、isInRanges、mergeRanges、removeCodeRanges、resolveNodePositions。

这些工具保留各自的上游语义。例如 isInRange 默认包含两个端点,不能直接把它的默认行为当作上文的半开区间判断。

序列化 ​

保存或传输结果时,可以将 code、extension、nodes 和 meta 作为数据。JSON 解析不会恢复 getter;需要动态分类视图时,按 node.type 从恢复后的 nodes 派生。核心 API 不提供独立的缓存恢复工厂。