Annil for VS Code

为使用 Annil 开发微信小程序的项目提供组件诊断、快速修复、定义跳转和代码生成能力。

安装

从 Visual Studio Marketplace 安装 Annil，或在 VS Code Extensions 视图中搜索 Annil。

使用前，项目应已安装并按 Annil 约定编写组件；本扩展不是 Annil 运行时或项目脚手架。

功能

组件诊断

打开组件目录中的 .ts、.wxml 或 .json 文件时，扩展会解析同目录下的组件文件并发布诊断。组件目录需要包含同名的 .ts、.wxml、.json 三个文件。

WXML：检查未知标签、重复 id、block 和 wx:for 结构、条件链、Annil 注释、自定义组件属性契约、事件及表达式数据引用。
JSON：检查组件导入、占位组件、导入路径和未知配置项。
TypeScript 数据使用：提示未使用的数据，并对可改为内部字段的数据提供建议。

数据使用诊断包括：

RootComponent 的非内部字段若被 WXML 或子组件 inherit 使用，不提示；仅被 TypeScript 逻辑引用时建议改为内部字段；没有引用时提示未使用。
RootComponent 内部字段，以及 CustomComponent、ChunkComponent 的内部字段，若没有 TypeScript 引用则提示未使用。
无法静态判断的动态字段访问不会据此报告未使用。

快速修复

WXML、JSON 和 TypeScript 诊断可提供相应的 Quick Fix。TypeScript 未使用数据诊断的单项 Quick Fix 包含删除字段和将字段改为内部字段，并会同步处理能够分析到的引用。

annil.fix-all 会处理当前组件的 .wxml 和 .json 文件中的可自动修复诊断，不执行 TypeScript 未使用数据修复。该命令要求 GitHub 登录并验证当前账号已 Star Annil 仓库；没有 Star 时会提示登录或前往仓库。此限制只作用于整组件修复，不影响单条 Quick Fix。

定义跳转

在组件 WXML 中使用 VS Code 的“转到定义”（F12 / Ctrl+单击；macOS 通常为 Cmd+单击）可跳转到已识别的 Annil 定义，包括自定义组件声明、部分组件属性对应的数据字段、Chunk ID 对应的声明、Chunk 宿主上的事件名对应的 events 配置，以及 Root 数据字段。

组件与页面创建

在 Explorer 中右键目标文件夹，选择“新建自定义组件”或“新建页面组件”。扩展会根据内置或用户自定义代码片段生成 .ts、.json、.wxml 和 .wxss 文件。

miniTest 类生成

打开 WXML 文件并运行 annil.generateMiniTestClass，扩展会根据 WXML 内容生成 Python miniTest 包装类。ChunkComponent 通过原生标签 ID 识别：使用最后一个 _ 后的字段匹配 TS 变量名；没有 _ 时整个 ID 即为标记。该规则同时用于 WXML 诊断和定义跳转。Chunk 宿主仍按普通原生节点处理，不会作为自定义组件导入或写入 customComponents。默认输出目录为工作区下的 miniTest/components。

默认代码片段

扩展会在 VS Code 用户 snippets 目录初始化 Annil 组件和页面片段。TypeScript、JSON、WXML 和 WXSS 中可使用 ancomp（组件）或 anpage（页面）前缀。运行 annil.insertDefaultSnippet 可选择并恢复默认片段；恢复操作会覆盖所选的用户片段。

命令与快捷键

快捷键可在 VS Code 的 Keyboard Shortcuts 中修改。macOS 与其他平台使用的组合键可能不同。

命令	默认快捷键	说明
`annil.fix-all`	Windows/Linux：Alt+S；macOS：Ctrl+S	修复当前组件中可自动修复的诊断；需通过 GitHub Star 验证。
`annil.check-all`	Windows/Linux：Alt+Z；macOS：Ctrl+Z	打开工作区中的 WXML 文件以触发组件诊断。
`annil.createComponent`	无	新建自定义组件；也可从 Explorer 文件夹右键菜单运行。
`annil.createPage`	无	新建页面组件；也可从 Explorer 文件夹右键菜单运行。
`annil.insertDefaultSnippet`	Windows/Linux：Ctrl+R Ctrl+I；macOS：Cmd+R Cmd+I	恢复指定类型的默认组件或页面片段。
`annil.generateMiniTestClass`	Windows/Linux：Ctrl+Shift+T；macOS：Cmd+Shift+T	从当前 WXML 生成 miniTest Python 类。

macOS 上 annil.fix-all 默认使用 Ctrl+S。若与个人保存快捷键冲突，可在 Keyboard Shortcuts 中搜索 annil.fix-all 并修改绑定。

配置

在用户或工作区的 settings.json 中设置：

设置	类型	默认值	作用
`annil.innerDataPrefix`	string	`_`	以该前缀开头的字段按内部字段处理。
`annil.ignoreTags`	string[]	`[]`	忽略指定标签的未知标签诊断。
`annil.allowUnknownAttributes`	string[]	`[]`	自定义组件允许额外使用的属性名；`data-*` 属性始终允许。放行属性后仍会校验其 mustache 表达式。
`annil.jsonConfigKeys`	string[]	`[]`	额外允许的 JSON 配置键；默认已允许 `usingComponents`、`component`、`componentPlaceholder` 和 `disableScroll`。
`annil.validDatas`	string[]	`[]`	WXML 检查中额外允许的数据名称。
`annil.testFilePath`	string	`miniTest/components`	miniTest Python 文件输出目录，相对于工作区根目录。
`annil.generateAttrs`	string[]	`class`、`style`	生成 miniTest 类时要读取的附加属性列表；`class`、`style`、`data-*` 和 tap 事件按生成器规则处理。

示例：

{
  "annil.allowUnknownAttributes": ["custom-data", "aria-label"],
  "annil.ignoreTags": ["third-party-widget"],
  "annil.jsonConfigKeys": ["lazyCodeLoading"]
}

使用前提与范围

诊断和定义跳转只针对同一组件目录中同名的 .ts、.wxml、.json 文件。
TypeScript 组件信息按 Annil 组件 API 结构收集；自定义组件和 Chunk 的属性、数据与事件诊断取决于能够静态解析的组件定义。
定义跳转是基于已解析组件定义的局部跳转，不是通用 TypeScript/WXML 符号索引；动态表达式或无法静态确定的目标可能无法跳转。
annil.check-all 会通过打开工作区的 WXML 文件触发检查，并非独立的文件扫描器。
miniTest 命令生成的是由 WXML 驱动的 Python 包装类，不是通用小程序页面测试框架。

开发与测试

本仓库当前实现位于 _src/，Extension Host 测试位于 _test/。详见项目维护说明与 _test/README.md。

Annil

missannil