新人と先輩の会話形式で理解しよう

新人

「先輩、ThymeleafでJavaScriptを外部ファイルとして読み込む方法を教えてもらえますか？」

先輩

「もちろんだよ。外部JavaScriptファイルを読み込む方法は、画面の管理をきれいに保つのにとても大事なんだ。pleiades環境でも、Spring Bootを使わずにGradleプロジェクトで簡単に設定できるよ。」

新人

「外部ファイルの読み込みって、どうやって書くんですか？」

先輩

「それじゃあ、まず外部JavaScriptファイルの役割と基本的な使い方から一緒に見ていこう！」

1. JavaScript外部ファイルの役割と基本的な使い方

JavaScript外部ファイルは、HTMLファイル内に直接記述する代わりに、別のファイルとして管理する方法です。これにより、HTMLとJavaScriptのコードが分かれて見やすくなり、メンテナンス性が高まります。さらに、複数ページで同じスクリプトを使い回せるので、Webアプリケーション開発でも役立ちます。

基本的には<script src="ファイルパス"></script>を使って読み込みます。JavaScriptの拡張子は.jsです。

2. Thymeleafで外部JavaScriptファイルを読み込む方法

Spring MVCの@Controllerでモデルに値を設定して、Thymeleafで外部ファイルを読み込むときも、基本の<script src="...">タグを使います。Thymeleafのth:src属性を使うと、プロジェクト内のパスを動的に設定できるので便利です。


@Controller
public class ScriptController {
    @GetMapping("/script-demo")
    public String scriptDemo(Model model) {
        model.addAttribute("message", "外部ファイルからこんにちは！");
        return "script-demo";
    }
}

次に、ThymeleafのHTMLテンプレートです。外部JavaScriptファイルとしてjs/main.jsを読み込む例を見てみましょう。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>Thymeleaf外部JS読み込みデモ</title>
    <script th:src="@{/js/main.js}"></script>
</head>
<body>
    <h2>外部JavaScriptファイルの読み込みデモ</h2>
    <button id="btn">クリックして処理実行</button>
</body>
</html>

上記のth:src="@{/js/main.js}"がポイントです。Thymeleafの@{}構文を使うと、アプリケーションのルートからのパスを解決できます。これで、src/main/resources/static/js/main.jsに置いたmain.jsが読み込まれます。

3. 外部ファイルの配置場所とHTMLでの読み込み方法

pleiades環境＋Gradleのプロジェクトでは、外部JavaScriptファイルをsrc/main/resources/static/jsフォルダに置くのが一般的です。このstaticフォルダ配下のjsフォルダに配置すると、Webサーバーが静的リソースとして認識してくれます。

たとえば、以下のようにプロジェクト構成を整えます。


src
 └── main
     ├── java
     │    └── com.example.controller.ScriptController
     ├── resources
     │    ├── static
     │    │    └── js
     │    │         └── main.js
     │    └── templates
     │         └── script-demo.html

外部JavaScriptファイルmain.jsには、クリックイベントでModelから渡されたメッセージを表示する処理を書けます。例として、main.jsの内容です。


document.addEventListener("DOMContentLoaded", function(){
  var btn = document.getElementById("btn");
  btn.addEventListener("click", function(){
    alert("外部ファイルのスクリプトが動きました！");
  });
});

これで、HTML側では<script th:src="@{/js/main.js}">を記述するだけで外部スクリプトが実行されるようになります。Modelから渡された値を使いたいときは、別のセクションで解説しますが、th:inline="javascript"を併用して変数を受け渡す方法も便利です。

4. JavaScript外部ファイルでThymeleafの値を利用する方法

外部JavaScriptファイルでは、Thymeleafのサーバーサイド変数を直接使えません。そのため、HTML内でth:inline="javascript"を使い、JavaScriptの変数として渡す方法が有効です。例えば、コントローラからユーザー名を渡すケースを見ていきましょう。


@Controller
public class UserController {
    @GetMapping("/user-info")
    public String userInfo(Model model) {
        model.addAttribute("username", "山田太郎");
        return "user-info";
    }
}

次に、HTMLテンプレートで外部JavaScriptファイルと連携する例です。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>ユーザー情報デモ</title>
    <script th:src="@{/js/user.js}"></script>
    <script th:inline="javascript">
        var username = /*[[${username}]]*/ "ゲスト";
    </script>
</head>
<body>
    <h2>ユーザー情報ページ</h2>
    <button id="showUser">ユーザー名を表示</button>
</body>
</html>

そして、外部JavaScriptファイルuser.jsの内容です。


document.addEventListener("DOMContentLoaded", function(){
  var btn = document.getElementById("showUser");
  btn.addEventListener("click", function(){
    alert("ユーザー名：" + username);
  });
});

このようにth:inline="javascript"で変数にサーバーサイドの値を代入してから、外部ファイルでその変数を使うと安全にデータを扱えます。

5. よくあるエラーとその解決方法

外部JavaScriptファイルとThymeleafの連携で初心者がつまずきやすいポイントを紹介します。

外部ファイルが読み込まれない

静的リソースの配置パスが正しくないと、外部JavaScriptファイルが読み込まれません。Gradle＋pleiades環境では、必ずsrc/main/resources/static/jsにファイルを置きましょう。

サーバーサイドの変数がundefinedになる

サーバー側の変数を外部ファイルで直接呼び出そうとすると、undefinedエラーになります。これは、外部ファイル内ではサーバーの値を認識できないためです。必ずth:inline="javascript"でHTML内のJavaScript変数に代入してから、外部ファイルで利用しましょう。

JavaScriptの実行タイミングに注意

JavaScriptの実行タイミングによっては、HTML内の変数がまだ読み込まれていないことがあります。外部ファイルではDOMContentLoadedイベントなどで読み込み完了後に実行する書き方を心がけましょう。

6. 外部ファイルとThymeleafのスコープ管理の注意点

外部JavaScriptファイルを活用するときは、スコープ（変数の有効範囲）に注意が必要です。特に、複数のJavaScriptファイルやHTML内のスクリプトで同じ変数名を使うと、思わぬバグが発生することがあります。

グローバル変数の衝突を避ける

外部JavaScriptファイルの中で変数をグローバルに宣言すると、ほかのスクリプトでも上書きされる可能性があります。これを避けるには、関数内で変数を宣言するか、IIFE（即時関数）でスコープを限定します。


(function(){
  var privateVar = "プライベートデータ";
  window.showPrivate = function(){
    console.log(privateVar);
  };
})();

この方法なら、privateVarは外部から直接アクセスできません。必要な部分だけをwindowオブジェクトに公開します。

サーバー変数の安全な取り扱い

サーバーサイドから渡された値をJavaScriptで扱うときは、HTMLエスケープやエンコードに注意しましょう。特にユーザー入力が含まれる場合は、スクリプトインジェクションのリスクがあります。Thymeleafのth:inline="javascript"を正しく使えば自動的に安全な形で埋め込まれますが、基本的な対策を理解しておくことが大切です。