简体中文
安装与使用
本页介绍返回结构化结果的核心包。如果希望直接在 Markdown 中使用交互代码块,请先阅读 VitePress 集成;如果需要高亮 HTML,请阅读 Shiki 集成。
准备运行环境
分析在能够运行仓颉 SDK 的本地环境中执行。JavaScript 运行时需要提供 AsyncDisposableStack 和 Symbol.asyncDispose;使用 await using 的源码还需要相应的语法或转译支持。
可以检查运行时是否具备所需 API:
bash
node -p "typeof AsyncDisposableStack"
node -p "typeof Symbol.asyncDispose"预期分别输出 function 和 symbol。
安装适合当前操作系统和 CPU 架构的仓颉 SDK。sdkPath 指向 SDK 根目录,其下应包含:
text
cangjie/
├── bin/cjc
├── tools/bin/LSPServer
└── runtime/lib/Windows 下对应的可执行文件使用 .exe 扩展名。文档示例使用 SDK 1.2.1 验证。
安装核心包
bash
pnpm add -D @cjslash/core核心 API 通过 sdkPath 显式指定 SDK。读取 CJSLASH_SDK_PATH 和 CANGJIE_HOME 的便利行为属于 VitePress 插件。
创建分析器
ts
import { createCjslasher } from '@cjslash/core'
await using cjslasher = await createCjslasher({
sdkPath: '/path/to/cangjie',
})
const source = 'let answer = 42\n// ^?\nmain() { println(answer) }\n'
const result = await cjslasher.analyze(source)
console.log(result.code)
console.log(result.queries[0]?.text)result.code 是移除注释标记和隐藏区域后的源码;result.queries 包含显式查询节点。结果本身不包含高亮 HTML,详细字段见分析结果。
createCjslasher() 校验 SDK,并返回异步分析器。每次 analyze() 都创建独立临时工程和 LSP 会话,分析结束后释放它们。同一分析器上的调用按队列依次执行,不会共享前一个示例的源码或包声明。
释放资源
await using 在离开作用域时调用 [Symbol.asyncDispose]()。如果所在环境不能使用该语法,可以显式释放:
ts
import { createCjslasher } from '@cjslash/core'
const cjslasher = await createCjslasher({ sdkPath: '/path/to/cangjie' })
try {
const result = await cjslasher.analyze('main() {}')
console.log(result.errors)
}
finally {
await cjslasher[Symbol.asyncDispose]()
}释放会取消执行中和排队的任务,等待资源清理。已释放的实例不能继续分析;重复释放共享同一个清理 Promise。
编写独立示例
每个示例应包含完整的仓颉分析上下文。可以用 @filename 组织同一根模块的多个文件,用裁剪标记隐藏准备代码;隐藏部分仍参与分析。
如果需要声明包,将 package 放在源码顶部:
cj
package example.models.user
let answer = 42
main() { println(answer) }上例生成模块名为 example 的临时工程,并将源码写入 src/models/user/index.cj。单段包名使用 src/index.cj,没有声明时使用 default 包。映射仅用于当前示例,不会从其他代码块导入文件。
在本仓库中开发文档
根目录的任务由 vite.config.ts 管理:
bash
CJSLASH_SDK_PATH=/path/to/cangjie vp run docs:dev
CJSLASH_SDK_PATH=/path/to/cangjie vp run docs:build这两个任务会先构建文档依赖的工作区包。SDK 路径也可通过 CANGJIE_HOME 指定;没有配置 SDK 时,文档仍能构建,但仓颉代码块仅有静态高亮。