Skip to content

9. 语言扩展规范(contributes.languages + grammars/*.json) ​

语言扩展插件用于为 Block 补充代码语法高亮与编辑辅助,采用纯声明式、零子进程、零权限模型在宿主机内直接运行:

  • 零进程与零权限:当 manifest.category 为 "language"、contributes.languages 非空、且未声明 entry.command、permissions、surfaces 与任何运行时 UI 贡献(titlebar_buttons / settings_sections / commands / page_menu / editor_menu / panels / status_items / dialogs)时,插件以纯声明式模式加载,不启动任何外部子进程,安装页也不展示危险权限提示。
  • 双场景同步生效:编译后的语法同时作用于打开其他文件夹时的源码编辑器与 Markdown 代码块(按 aliases 与 id 匹配语言标识)。
  • 生命周期:首次安装纯声明式语言扩展时自动启用;在设置页停用或卸载插件时,编辑器与代码块高亮实时生效(移除对应语言注册)。
  • 系统「打开方式」自动关联:启用、停用或卸载语言扩展时,宿主会在后台无感同步 extensions 到操作系统的「打开方式」菜单(macOS 通过用户目录隐形中转小壳自动跳过主程序已接管的纯文本与多段后缀;Windows 写当前用户 HKCU 专属 Block.Document ProgID 的 OpenWithProgids,均不抢占默认程序;Linux 维护 NoDisplay=true 的用户级 block-plugins.desktop,仅关联系统 MIME 数据库已收录的类型、不覆写主入口也不新增自定义 MIME,若桌面未给某细分子类型单独指定默认应用,部分桌面如 GNOME/GIO 可能优先按精确子类型回落),无需管理员权限;仅靠 filenames 匹配的规则不会注册到系统菜单。

9.1 contributes.languages 字段定义 ​

contributes.languages 为对象数组,单插件最多声明 16 个语言条目;所有条目均须符合以下字段与约束:

字段必填类型与约束
id是字符串,匹配 ^[a-z][a-z0-9_-]{0,31}$,同一插件内不可重复
name是LocalizedText(zh 与 en 均必填非空,禁止含 Emoji)
extensions与 filenames 至少其一字符串数组,最多 16 项,不可重复;每项匹配 ^\.[a-z0-9][a-z0-9._-]{0,23}$(小写点号前缀,如 ".plist")
filenames与 extensions 至少其一字符串数组,最多 16 项,不可重复;纯文件基本名(非空、<= 64 字节、不含 / \ :,不可为 . 或 ..)
aliases否字符串数组,最多 16 项,不可重复;每项匹配 ^[a-z0-9][a-z0-9._+-]{0,31}$(用于 Markdown 代码块围栏标识)
display_tags否字符串数组,最多 8 项;每项去空白后非空且 <= 24 字节、禁止含 Emoji。用于商店列表与详情页展示;省略时优先回退 filenames,若为空则回退 extensions(商店索引 file_extensions 跨语言去重后最多保留 6 个)
grammar是字符串,插件目录内相对 / 分隔路径,须以 .json 结尾,禁止以 / 开头、禁止含 \ 或 :、禁止 .. 路径逃逸;单文件大小上限 256 KiB

9.2 grammars/*.json Schema(RE2 有状态行分词器) ​

Grammar JSON 采用严格解码:禁止重复键、禁止未知字段。

顶层字段 ​

字段必填类型与约束
schema_version是固定整数 1
line_comment否字符串,单行注释前缀(如 "//"、"#")
block_comment否2 元素字符串数组 [open, close](如 ["<!--", "-->"])
word_chars否字符串,追加到标识符词边界的额外字符集(如 ".-/")
tab_size否整数,0–16(0 表示沿用编辑器默认)
hard_tabs否布尔值,是否优先使用硬制表符 \t(默认 false)
brackets否[open, close] 二元组数组,用于括号匹配高亮
auto_close否[open, close] 二元组数组,用于输入时自动闭合括号/引号
initial_state否字符串,初始状态名,省略时默认为 "root";必须存在于 states 中
states是对象(map[string][]GrammarRule),至少 1 个、最多 63 个状态;状态名匹配 ^[a-zA-Z_][a-zA-Z0-9_-]{0,31}$;每状态最多 128 条规则,全部状态合计最多 512 条规则;状态栈最大深度 9 层(超深时退化为替换当前栈顶)
sample否字符串,用于设置页/详情页的语法高亮预览示例

GrammarRule 字段 ​

字段必填类型与约束
match是非空 RE2 正则表达式字符串;编译时自动以 \A(?:...) 锚定到当前行扫描位置
token否字符串,合法 Token 名称之一(见下表,大小写不敏感)
captures否对象(map[string]string),键为 "1"–"16" 的捕获组编号(不可超过 match 的子表达式数量),值为合法 Token 名称
next否字符串,切换到指定状态名(须存在于 states 中)
push否字符串,将指定状态名压栈并进入(须存在于 states 中)
pop否布尔值,true 时弹栈返回上一状态(栈空时回到初始状态)

规则约束:token、captures、next、push、pop 至少设置其一;next、push、pop 至多设置其一;零长度匹配仅在发生状态转移时允许,连续零步循环上限为 8 次。

全部合法 token 名称(共 25 个) ​

  • 基础与标识符:text、keyword、type、function、variable、property、constant
  • 字面量与注释:number、string、escape、regexp、comment
  • 语法符号与标记:operator、punctuation、tag、attribute、meta
  • 文档与差异状态:heading、emphasis、strong、link、code、inserted、deleted、invalid

9.3 可复制的精简示例 ​

目录结构:

text
example-lang/
├── manifest.json
├── README.md
├── README.en.md
└── grammars/
    └── conf.json

manifest.json:

json
{
  "app": "blockmd",
  "schema_version": 1,
  "id": "example-lang",
  "category": "language",
  "name": {
    "zh": "示例配置语言",
    "en": "Example Config"
  },
  "version": "1.0.0",
  "author": "Your Name",
  "repo": "your-org/example-lang",
  "summary": {
    "zh": "为 .conf 配置文件提供语法高亮",
    "en": "Syntax highlighting for .conf configuration files"
  },
  "permissions": [],
  "surfaces": [],
  "contributes": {
    "languages": [
      {
        "id": "example-conf",
        "name": {
          "zh": "示例配置",
          "en": "Example Config"
        },
        "extensions": [".conf"],
        "filenames": ["example.conf"],
        "aliases": ["conf", "example-conf"],
        "display_tags": [".conf"],
        "grammar": "grammars/conf.json"
      }
    ]
  },
  "icon": {
    "view_box": "0 0 24 24",
    "fill_paths": ["M5.5 3.5h8.5l4.5 4.5v12.5a1.5 1.5 0 0 1-1.5 1.5H7a1.5 1.5 0 0 1-1.5-1.5v-17Z"],
    "stroke_paths": [
      "M5.5 3.5h8.5l4.5 4.5v12.5a1.5 1.5 0 0 1-1.5 1.5H7a1.5 1.5 0 0 1-1.5-1.5v-17Z",
      "M14 3.5V8h4.5"
    ],
    "accent_paths": ["M9 12.5h6", "M9 16h4"]
  }
}

grammars/conf.json:

json
{
  "schema_version": 1,
  "line_comment": "#",
  "tab_size": 2,
  "brackets": [["[", "]"], ["{", "}"]],
  "auto_close": [["\"", "\""], ["[", "]"]],
  "initial_state": "root",
  "states": {
    "root": [
      { "match": "#.*$", "token": "comment" },
      { "match": "^\\[[^\\]]+\\]", "token": "heading" },
      { "match": "\"(?:\\\\.|[^\"\\\\])*\"", "token": "string" },
      { "match": "\\b(?:true|false|null)\\b", "token": "constant" },
      { "match": "\\b[0-9]+(?:\\.[0-9]+)?\\b", "token": "number" },
      { "match": "([A-Za-z_][A-Za-z0-9_.-]*)(\\s*=)", "captures": { "1": "property", "2": "operator" } },
      { "match": "[ \\t]+", "token": "text" }
    ]
  },
  "sample": "# Example config\n[server]\nhost = \"127.0.0.1\"\nport = 8080\ntls = true"
}