JSI 封裝整合第三方類庫實戰：Scriptaculous Effect 滑動面板案例

前言：JavaScript 類庫管理的痛點

Java 擁有龐大成熟類庫生態，JavaScript 卻面臨依賴混亂、命名衝突、腳本載入順序敏感等難題。JSI (JavaScript Integration) 雖非公共 API，卻能隔離依賴、隔離執行上下文、消除命名衝突，大幅提升類庫易用性。本文以 Windows XP 風格滑動摺疊面板為例，示範 JSI 封裝 Scriptaculous Effect 類庫全流程。

案例目標：滑動摺疊面板效果

點擊面板標題觸發滑動展開/收合，基於 Scriptaculous Effect.SlideDown/Effect.SlideUp 實現。

步驟 1：整合 Scriptaculous 類庫

官方發布版已內建於 us.aculo.script 套件，可直接作為系統內建類庫使用。詳細整合步驟請參考「集成實戰」文件。

步驟 2：編寫面板控制函數 (example/effect.js)

/**
 * 滑動面板實現
 * 可見時向上滑動收合，不可見時向下滑動展開
 */
function slidePanel(panel) {
    panel = $(panel);
    if (panel.style.display == 'none') {
        new Effect.SlideDown(panel); // 展開
    } else {
        new Effect.SlideUp(panel);   // 收合
    }
}

步驟 3：定義套件相依性 (example/__$package.js)

// 註冊 slidePanel 函數
this.addScript("effect.js", "slidePanel", null);

// 宣告 effect.js 依賴 us.aculo.script.effects.js（載入後依賴）
this.addScriptDependence("effect.js", "us/aculo/script/effects.js", false);

步驟 4：網頁應用整合

<html>
<head>
  <title>重用 aculo Effect 腳本實例</title>
  <link rel="stylesheet" type="text/css" href="/styles/default.css" />
  <script src="/scripts/boot.js"></script>
  <script>
    $import("example.slidePanel");
  </script>
</head>
<body>
  <div class="menu_header" onclick="slidePanel('menu_block1')">面板 1</div>
  <div class="menu_block" id="menu_block1">
    <ul><li>text1</li><li>text2</li><li>text3</li></ul>
  </div>
</body>
</html>

僅需引入 boot.js 並 $import("example.slidePanel")，HTML 乾淨無雜訊。

對比：無 JSI 的傳統寫法

<head>
  <script src="/scripts/net/conio/prototype/v1_5/prototype.js"></script>
  <script src="/scripts/us/aculo/script/v1_7/effects.js"></script>
  <script src="/scripts/us/aculo/script/v1_7/builder.js"></script>
  <script src="/scripts/example/effect.js"></script>
</head>

缺點顯而易見：

• 手動管理多層依賴順序（prototype → effects → builder → effect.js）
• HTML 混雜大量 <script> 標籤，重構極其困難
• 全域命名空間污染風險（如 jQuery 與 Prototype 的 $ 衝突）

JSI 核心優勢深度解析

1. 隔離執行上下文，消除命名衝突

每個腳本擁有獨立執行上下文，頂層變數互不干擾，不污染全域空間。甚至可間接載入同一類庫不同版本共存不衝突。

2. 封裝依賴細節，防止依賴擴散

套件定義檔一次性宣告相依關係，使用者無需關心間接依賴。類庫開發者將依賴終結於自身，提升易用性。

3. 套件結構助力代碼組織與文檔

雖需編寫套件定義檔，但一勞永逸。套件結構天然支援模組化開發、代碼重用、文檔生成。

結語

JSI 讓 JavaScript 類庫管理邁向 Java 級成熟度：依賴隔離、上下文隔離、命名空間保護。建議類庫開發者主動封裝依賴，讓使用者專注業務邏輯而非基建配置。本案例展示從第三方庫封裝出專屬功能模組的標準範式，可擴展至任何複雜前端架構。