Solely Framework SupportVS Code 扩展,为 Solely 框架的 HTML 模板提供语法高亮、代码补全、智能跳转、悬停提示和错误诊断。 功能总览
语法高亮打开任意 HTML 模板文件即可自动启用,支持以下语法着色: 插值表达式
控制流标签
事件与属性绑定
指令
生命周期
支持 模板引用
代码补全在 HTML 模板中输入时自动触发补全:
|
| 模板表达式 | 跳转目标 |
|---|---|
this.method() |
TS 类方法定义 |
this.prop |
TS getter 定义 |
this.prop.method() |
链式调用:先找属性类型,再跳转到对应类的方法 |
$data.prop |
super({...}) 或 interface 中的属性定义 |
$data |
数据定义(interface/BaseElement</super({) |
ref="xxx" |
TS 中 this.$refs.xxx 的使用位置 |
s-model="prop" |
同 $data.prop,跳转到属性定义 |
跳转支持继承链:如果当前组件类中找不到定义,会自动向上查找父类文件。对于通过包名导入的父类(例如 import { BaseElement } from 'solely'),扩展会解析依赖包的 types/typings 声明入口、export * 链和 .d.ts 文件。例如 this.emit() 可以跳转到 solely 包中的 BaseElement 声明。
悬停提示
鼠标悬停在模板中的标识符上,显示相关信息:
| 悬停目标 | 显示内容 |
|---|---|
this.method() |
方法签名 + 来源类 + 跳转提示 |
this.prop |
getter 类型 + 来源类 + 跳转提示 |
$data.prop |
属性类型 + 定义位置 + 跳转提示 |
$data |
响应式数据说明 |
ref="xxx" |
模板引用说明 + this.$refs.xxx 访问方式 |
错误诊断
打开 HTML 模板时自动检查以下问题:
控制流标签配对
<!-- ✅ 正确 -->
<If test="...">...</If>
<!-- ❌ 错误: <If> 未闭合 -->
<If test="..."
>...
<!-- ❌ 错误: <ElseIf> 必须在 <If> 或 <ElseIf> 之后 -->
<div>内容</div>
<ElseIf test="...">...</ElseIf></If
>
插值表达式闭合
<!-- ✅ 正确 -->
<span>{{ $data.name }}</span>
<!-- ❌ 错误: 未闭合的插值 -->
<span>{{ $data.name </span>
属性语法
<!-- ⚠️ 警告: 值没有加引号(框架本身支持,只是建议统一加引号) -->
<button @click="this.handleClick()">点击</button>
HTML 引用诊断
检查模板中引用的方法和数据属性是否在 TS 组件中存在,帮助发现拼写错误:
<!-- ❌ 错误: 方法 'hanldeClick' 在组件及其父类中未定义 -->
<button @click="this.hanldeClick()">点击</button>
<!-- ❌ 错误: 数据属性 'nweTodo' 在 super({}) 或 interface 中未定义 -->
<span>{{ $data.nweTodo }}</span>
<!-- ✅ 不报错: BaseElement 继承成员 emit() 可直接使用 -->
<button @click="this.emit('change')">触发事件</button>
诊断采用保守策略,避免误报:
- 只检查表达式区域:
{{ ... }}的插值内容,以及@click/onclick/:class/s-model/test等动态属性的值(带引号或不带引号都会检查)。注释、<style>、<script>和正文文案都不参与检查 - 只检查
this.method()(带括号)和$data.prop - 跳过
$开头的框架内置成员 - 检查继承链(组件类 + 所有父类),并支持多行签名与泛型方法
- 放行
BaseElement的emit()/emitNative()/refresh()/dispose()等公开成员,以及setAttribute()/querySelector()等 HTMLElement API - 无法解析
super({})时跳过$data.xxx检查 - 只有能关联到 TS 组件的 HTML 才会被当作 Solely 模板校验,普通 HTML(Handlebars / Jinja / 静态演示页)不会被
{{ }}之类的规则打扰
单文件多组件(一个
.ts里既有父组件也有私有子组件)时,扩展会根据@CustomElement({ template })里绑定的模板找到对应那个类,而不是文件里的第一个类。
HTML ↔ TS 快速切换
通过命令面板在 HTML 模板和对应的 TS 组件之间一键切换:
- 按
Ctrl+Shift+P打开命令面板 - 输入
Solely: 切换到对应文件 - 执行后自动跳转到对应文件
- 在 HTML 模板中执行 → 跳转到对应的 TS 组件
- 在 TS 组件中执行 → 跳转到对应的 HTML 模板
扩展通过解析 import template from './xxx.html?solely' 或 ?raw 自动建立关联。
模板关联机制
扩展通过以下方式自动关联 HTML 模板与 TS 组件:
- HTML → TS:在 HTML 文件所在目录、其父目录、以及父目录下的兄弟目录里搜索 TS 文件,匹配
import template from './xxx.html?solely'或?raw语句 - TS → HTML:解析 TS 文件中的模板导入语句,定位 HTML 文件
- 路径精确比对:导入说明符会先解析成绝对路径再比较,不同目录下的同名
index.html不会互相串台 - 支持依赖包父类解析:可解析
node_modules中通过裸模块导入的父类,以及其types/typings、export *和.d.ts声明链 - 实时生效:TS 内容改动(包括未保存的编辑)会立即刷新模板侧的方法/属性解析,不需要重启扩展
// TS 组件中的模板导入(两种方式均可)
import template from './index.html?solely'; // 框架预编译
import template from './index.html?raw'; // 原始字符串
@CustomElement({
tagName: 'my-component',
template,
})
class MyComponent extends BaseElement<MyData> {
// ...
}
安装
方式一:通过 VS Code 扩展面板安装(推荐)
按 Ctrl+Shift+X 打开扩展面板,搜索 "Solely Framework Support" 即可安装。
方式二:通过命令行安装
code --install-extension solely.solely-vscode
方式三:从源码构建
cd vscode-extension
npm install
npm run compile
# 按 F5 选择「运行扩展(Extension Host)」启动调试
npm test # 编译后跑 tests/ 下的解析与诊断用例
使用
安装后,在 Solely 项目中打开任意 HTML 模板文件即可自动启用,无需额外配置。
扩展支持单引号和双引号属性值:
<!-- 两种写法均可识别 -->
<input ref="inputRef" />
<input ref="inputRef" />
模板需要能被
import ... from './xxx.html?solely'(或?raw)关联到某个 TS 组件, 才会启用诊断与补全。没有关联的普通 HTML 不会被当作 Solely 模板处理。
版本要求
- VS Code
>= 1.85.0 - 项目需使用
import template from './xxx.html?raw'或?solely方式导入模板
问题反馈
如有问题或建议,请在 GitHub Issues 提交。