Legacy JavaScript Toolkit

繁體中文 | English

Legacy JavaScript Toolkit 是為 Java / Spring Boot / 傳統 Java Web 專案設計的 VS Code 擴充套件。它補強原生 JavaScript 的 inline HTML 語法高亮、function 與 CSS class 定義導覽、Hover、Maven 前端資產索引，以及 jsconfig.json 建立輔助。

功能展示

0.0.2 起支援 Maven parent、transitive dependency 與 Spring Boot dependency JAR 內的前端資產，可直接導覽共用 dependency 提供的 function，不需要設定特定電腦的套件原始碼路徑。

0.0.3 起可檢查並安全更新既有 jsconfig.json。更新前可查看差異，套用時只補入缺少的目錄與建議設定，不會改寫既有 target、paths 或其他人工設定。

0.0.6 可從 Maven parent 的 dependencyManagement 找出共用前端資產，改善 dependency JAR 內 function 與回傳物件方法的導覽，並移除舊版自動產生且已被 TypeScript 6 棄用的 "baseUrl": "."。

0.0.7 新增 CSS class 導覽，可從 HTML、JSP 與常見 JavaScript DOM API 的 class 名稱移動到專案或 Maven dependency 中的 CSS 定義，Hover 時可直接查看規則內容。

適合的專案類型

• Spring Boot 的 src/main/resources/static、public 與 META-INF/resources
• 傳統 Java Web 的 src/main/webapp
• 使用 JSP、JSPX、Tag File 的專案
• Eclipse 常見的 WebRoot 或 WebContent 專案
• 透過 Maven WebJar 引用 JavaScript 的專案
• 未使用 npm bundler、以原生 JavaScript 為主的既有系統
• Maven 多模組 workspace；掃描範圍不限於 workspace 根目錄下的單一模組

Inline HTML Highlight

擴充套件使用 TextMate grammar injection，將符合規則的 JavaScript / TypeScript template literal 內容交由 HTML grammar 高亮。支援 .js、.jsx、.ts、.tsx。

自動辨識規則

變數名稱包含 html、template、markup、view（不分大小寫），或名稱本身就是上述字詞：

const html = `<div>${name}</div>`;
const rowHtml = `<tr><td>${id}</td></tr>`;
const USER_HTML = `<section>${content}</section>`;
const pageTemplate = `<main>${title}</main>`;

DOM HTML 屬性與 API：

element.innerHTML = `<div>${message}</div>`;
element?.outerHTML = `<section>${title}</section>`;
element.insertAdjacentHTML("beforeend", `<li>${item.name}</li>`);

明確標記

/*html*/、/* html */ 與大小寫變形是最穩定的指定方式：

const result = /*html*/ `<div class="card">${content}</div>`;

HTML 內的 ${...} 會切回 JavaScript expression 高亮。TextMate grammar 是 regex 規則，不是完整 parser；巢狀大括號或很複雜的 expression 仍可能受限。

一般的 SQL、訊息、URL 與 query template literal 不符合命名、DOM API 或 marker 規則，因此不會全部被誤判成 HTML：

const sql = `SELECT * FROM USER`;
const message = `hello ${name}`;
const url = `/api/user/${id}`;

JavaScript Function Navigator

擴充套件啟動後會延遲掃描 workspace，並以 TypeScript AST 建立輕量 function index。支援：

• Ctrl + Click 與 Go to Definition
• Peek Definition
• Hover 顯示參數、JSDoc 摘要、@param、@returns、來源路徑與來源類型
• 同名 function 回傳多個 location，由 VS Code 顯示候選位置
• Qualified name 優先比對，例如 MyApp.util.getUserName
• JS / JSX / TS / TSX，以及 HTML / JSP 內可辨識的呼叫位置

目前索引下列常見形式：

function foo(value) {}
const foo = function (value) {};
const foo = (value) => {};
const service = { foo(value) {} };
MyApp.util.foo = function (value) {};
window.foo = function (value) {};
$.fn.myPlugin = function (options) {};
class Service { foo(value) {} }

檔案建立或修改後會做 500 ms debounce 的單檔增量更新。大量移動、設定變更或 WebJar dependency 更新後，建議執行 Rebuild JavaScript and CSS Index。

CSS Class Navigator

CSS class 索引支援專案 .css、target/classes 前端資產，以及 HTML / JSP <link href> 或靜態 Thymeleaf th:href 實際引用的 Maven dependency CSS。將游標放在 class 名稱上可使用 Ctrl+Click、Go to Definition、Peek Definition 與 Hover；同名 class 會回傳所有候選位置。

支援 HTML、JSP 與 JavaScript / TypeScript inline HTML：

<div class="card toolbar-item"></div>

也支援常見 DOM API 與 selector：

element.classList.add("active");
element.classList.toggle("hidden");
element.setAttribute("class", "card selected");
document.getElementsByClassName("card");
document.querySelector(".card");
element.closest(".panel");

為避免誤判，一般 JavaScript 字串不會被視為 class。JSP EL、scriptlet 或 JavaScript expression 內動態產生的 class 名稱也不會強行解析。

jsconfig.json 輔助功能

jsconfig.json 能讓 VS Code 的 JavaScript / TypeScript Language Service 更清楚專案範圍，改善內建的 Ctrl+Click、定義導覽、Hover 與 JSDoc 體驗。

啟動時只在符合以下條件時詢問：

• workspace 沒有 jsconfig.json
• workspace 沒有 tsconfig.json
• 偵測到 pom.xml、build.gradle 或 Java Web 常見資料夾
• promptCreateJsconfig 已啟用，且使用者未選擇「不要再提醒」

只有選擇「建立」才會寫入檔案，include 只納入實際存在的目錄，也支援 Maven 多模組路徑。既有 jsconfig.json 不會被覆蓋；手動執行建立指令時，可以開啟既有檔案或另建 jsconfig.generated.json。

檢查與安全更新

若既有 jsconfig.json 缺少新加入的 Maven 模組、JavaScript 目錄、建議 exclude 或必要 compilerOptions，擴充套件會詢問是否安全更新。支援含註解與尾端逗號的 JSONC 格式。

安全更新遵守以下規則：

• 只追加缺少的 include 與 exclude。
• 只補入不存在的 compilerOptions，不修改現有值。
• 新建的設定不再加入 TypeScript 6 已棄用的 baseUrl；安全更新會移除舊版擴充套件產生的 "baseUrl": "."。
• 若 baseUrl 是其他客製值，會予以保留，避免改變既有模組解析行為。
• 保留註解、paths、自訂 target 與其他人工設定。
• 寫入前重新讀取檔案，避免預覽期間的修改被舊內容覆蓋。
• JSONC 格式或欄位型別錯誤時不寫入，只提示並開啟檔案。
• workspace 已有 tsconfig.json 時不主動提示更新；仍可手動執行檢查指令。

WebJar 支援

索引器依序嘗試：

1. 掃描 target/classes 下的 META-INF/resources、static、public 與 resources JavaScript / CSS。
2. 解析 workspace POM、parent POM、dependencyManagement、imported BOM 與相關 transitive dependency。
3. 從每台電腦自己的 Maven local repository 找到對應 JAR，不依賴固定磁碟或專案原始碼路徑。
4. 索引標準 META-INF/resources/webjars，以及 Spring Boot dependency JAR 內的 static、public、resources、META-INF/resources。
5. 辨識 HTML / JSP / Thymeleaf 的 script src、stylesheet href 與靜態 th:src / th:href，並優先解壓實際引用的前端資產。

Maven local repository 依序取自：

1. legacyJavaScriptToolkit.mavenRepository 設定。
2. workspace 的 .mvn/maven.config 內 -Dmaven.repo.local。
3. MAVEN_REPO_LOCAL 或 M2_REPO 環境變數。
4. 使用者 ~/.m2/settings.xml 的 <localRepository>。
5. 使用者的 ~/.m2/repository。

例如專案透過 Maven parent 管理共用前端資產時，索引器可從本機 Maven repository 的 dependency JAR 找到頁面實際引用的 JavaScript，不需要知道套件原始碼位於哪個磁碟。

這是 best-effort 索引，不等同 Java classpath。Minified JavaScript 的 function 導覽通常不理想；第三方 library 建議另外提供 .d.ts、@types/* 或專案自己的 typings。

指令列表

診斷訊息會寫入 Output 面板的 Legacy JavaScript Toolkit channel。

Extension settings

TextMate grammar contribution 目前無法由 extension runtime 動態卸載；若要完全停用 inline HTML grammar，請停用此擴充套件。enableInlineHtmlHighlight 保留為偏好設定與後續版本相容用途。

安裝方式

從 VSIX 安裝：

code --install-extension legacy-javascript-toolkit-0.0.7.vsix

也可以在 VS Code 的 Extensions 檢視中，使用 Install from VSIX...。

開發方式

需求：Node.js 20 以上與 VS Code 1.90 以上。

npm ci
npm run compile

用 VS Code 開啟此資料夾，按 F5 啟動 Extension Development Host。修改 TypeScript 時可執行：

npm run watch

VSIX 打包方式

npm run package

成功後會在專案根目錄產生 legacy-javascript-toolkit-0.0.7.vsix。

已知限制

• JavaScript 是動態語言，function 來源不一定能 100% 精準判斷。
• 同名 function 可能有多個候選；擴充套件會全部交給 VS Code，不任意選第一個。
• 動態產生的 script src 無法保證解析。
• JSP 以 Java 變數、EL 或字串運算組出的 script path 不一定能解析。
• 目前不索引 JSP / HTML 的 inline <script> function，只利用其中的呼叫與靜態 src 關聯。
• Minified JS 的導覽效果可能不好，超過 2 MB 的單一檔案會略過。
• Big5、MS950 或其他非 UTF-8 檔案會略過並在 Output channel 顯示警告。
• Maven dependency resource 支援是 best-effort，不等同完整 Maven effective model；複雜 profile、classifier、exclusion 或非標準資產目錄可能無法定位。
• WebJar 不是 npm package，VS Code 不一定能自動取得型別；第三方 library 建議搭配 .d.ts 或 @types/*。
• jsp language id 取決於已安裝的 JSP 語言擴充套件；若檔案被辨識為其他 language id，JSP Provider 不會自動生效。
• TextMate grammar injection 對複雜 template literal 的判斷有限，/*html*/ 是最穩定的明確標記方式。
• ${...} expression 目前使用 JavaScript grammar；TypeScript 專屬型別語法的內嵌高亮可能不完整。
• CSS class 索引以一般 CSS selector 為主；CSS escape、複雜動態 class、CSS Modules 與 HTML / JSP inline <style> 尚未完整支援。
• JavaScript class 導覽只辨識 inline HTML、classList、setAttribute("class", ...)、getElementsByClassName 與常見 selector API，不會將所有字串當成 class。

疑難排解

• 無法跳轉：先執行 Show JavaScript and CSS Index Status，確認 function 或 class 數量，再執行 Rebuild JavaScript and CSS Index。
• 檔案未被索引：檢查 excludeGlobs、maxFilesToIndex 與 Output channel 的警告。
• WebJar 或 Spring Boot dependency resource 未被索引：確認 JAR 已存在 Maven local repository；自訂 repository 可設定 legacyJavaScriptToolkit.mavenRepository。
• VS Code 內建 JavaScript 導覽不足：執行 Create jsconfig.json 後，選擇 Restart TS Server 或 Reload Window。
• Inline HTML 未高亮：確認變數名稱符合規則，或改用 /*html*/；變更擴充套件或 grammar 後請重新載入視窗。

授權

MIT