jQuery / HTML 문서와 연결하는 방법, 사용하는 방법

HTML 문서에서 jQuery를 사용하려면 jQuery 파일을 script로 먼저 불러온 뒤 jQuery를 사용하는 코드를 실행합니다. CDN 주소를 연결하거나 다운로드한 파일을 로컬 경로로 연결할 수 있습니다. 라이브러리 로딩 순서와 HTML 요소가 준비되는 시점을 각각 맞춰야 합니다.

연결할 파일과 실행 순서 정하기

jQuery는 JavaScript로 작성된 라이브러리입니다. HTML에 별도 전용 태그를 추가하는 것이 아니라 script 요소의 src로 파일을 읽고, jQuery 함수로 요소를 선택해 메서드를 호출합니다. 기본 실습에는 npm이나 빌드 도구가 필요하지 않습니다.

예제는 공식 다운로드에서 제공하는 4.0.0 일반 script 파일을 버전까지 지정해 사용합니다. min 파일은 전송량을 줄인 압축본이며 기능을 뜻하는 구분은 아닙니다. slim은 Ajax와 effects 모듈을 제외하므로 이후 작업에서 그 기능이 필요한지 보고 선택합니다. 아래 즉시 표시·숨김 예제 자체에 시간 지정 효과나 Ajax는 없습니다.

한 페이지에는 의도한 jQuery를 한 번만 불러옵니다. 기존 사이트에 이미 있는 파일을 모르고 추가하면 플러그인과 데이터가 서로 다른 인스턴스에 연결될 수 있습니다. 처음에는 아래 독립 파일에서 동작을 확인한 뒤 실제 사이트의 의존성 구조를 살핍니다.

CDN으로 연결하는 한 파일 예제

CDN(Content Delivery Network)은 외부 서버에서 파일을 전달하는 방식입니다. 아래 코드를 UTF-8의 cdn-demo.html로 저장해 브라우저로 엽니다. 인터넷 연결이 필요하고, 별도 서버나 설치는 필요하지 않습니다. 파일을 선택할 때는 공식 CDN 목록에서 버전과 일반 script 형식을 확인합니다. 이 CDN 예제는 Windows Edge에서 3.7.1·4.0.0으로 각각 실행했습니다.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Load jQuery and use it</title>
  <style>body { font: 16px/1.6 sans-serif; margin: 20px; } button { font: inherit; margin: 4px; } pre { white-space: pre-wrap; }</style>
</head>
<body>
  <button type="button" id="toggle" aria-controls="message" aria-expanded="true">Toggle message</button>
  <button type="button" id="reset">Reset</button>
  <p id="message">This message is controlled by jQuery.</p>
  <pre id="status" aria-live="polite">Waiting for scripts.</pre>
  <script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
  <script>
jQuery(function ($) {
  let clicks = 0;
  function report() {
    const visible = $("#message").is(":visible");
    $("#toggle").attr("aria-expanded", String(visible));
    $("#status").text(`ready=true\nmessage visible=${visible}\nclicks=${clicks}`);
  }
  $("#toggle").on("click", function () { clicks++; $("#message").toggle(); report(); });
  $("#reset").on("click", function () { clicks = 0; $("#message").show(); report(); });
  report();
});
  </script>
</body>
</html>

정상 실행되면 다음 결과가 나타납니다. Waiting for scripts.는 초기 HTML에 적은 상태이고, jQuery 코드가 실제 실행돼야 ready=true로 바뀝니다.

ready=true
message visible=true
clicks=0

1. Toggle message를 누르면 문장이 숨겨지고 message visible=false, clicks=1입니다.
2. 다시 누르면 문장이 보이고 clicks=2입니다. 버튼의 aria-expanded도 현재 표시 상태와 함께 바뀝니다. 키보드로 버튼에 포커스를 두고 Enter를 눌러도 사용할 수 있습니다.
3. Reset은 문장을 다시 표시하고 횟수를 0으로 돌립니다. 페이지를 다시 읽지 않고 초기 동작을 반복할 수 있습니다.

jQuery 파일 뒤의 일반 script가 의존 코드를 실행합니다. 문서 준비 처리인 jQuery(function ($) { ... })는 DOM(Document Object Model)을 조작할 준비가 된 뒤 콜백을 실행합니다. 이 지역 $는 jQuery 별칭입니다. ready가 jQuery 파일 자체의 다운로드를 기다려 주는 것은 아니므로 라이브러리보다 먼저 호출하면 오류입니다.

로컬 파일과 defer로 연결하기

외부 CDN에 의존하지 않으려면 같은 버전 파일을 공식 다운로드에서 저장합니다. 예를 들어 새 폴더 안에 index.html·app.js를 두고, 그 안의 vendor 폴더에 jquery-4.0.0.min.js를 둡니다. 파일 이름과 확장자를 실제 저장 결과에서 확인하며 .js.txt로 저장되지 않게 합니다.

1. vendor/jquery-4.0.0.min.js에는 다운로드한 라이브러리를 저장합니다. 라이브러리 코드에 아래 app.js 내용을 덮어쓰지 않습니다.
2. index.html에는 다음 전체 HTML을 저장합니다. 이 경로에서 ./vendor/는 HTML 파일이 있는 폴더 아래를 뜻합니다.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Local jQuery with ordered deferred scripts</title>
  <script defer src="./vendor/jquery-4.0.0.min.js"></script>
  <script defer src="./app.js"></script>
  <style>body { font: 16px/1.6 sans-serif; margin: 20px; } button { font: inherit; margin: 4px; } pre { white-space: pre-wrap; }</style>
</head>
<body>
  <button type="button" id="toggle" aria-controls="message" aria-expanded="true">Toggle message</button>
  <button type="button" id="reset">Reset</button>
  <p id="message">This message is controlled by jQuery.</p>
  <pre id="status" aria-live="polite">Waiting for scripts.</pre>
</body>
</html>

같은 폴더의 app.js에는 아래 전체 JavaScript를 저장합니다. 이 파일에 script 시작·종료 태그를 넣지 않습니다.

jQuery(function ($) {
  let clicks = 0;
  function report() {
    const visible = $("#message").is(":visible");
    $("#toggle").attr("aria-expanded", String(visible));
    $("#status").text(`ready=true\nmessage visible=${visible}\nclicks=${clicks}`);
  }
  $("#toggle").on("click", function () { clicks++; $("#message").toggle(); report(); });
  $("#reset").on("click", function () { clicks = 0; $("#message").show(); report(); });
  report();
});

index.html을 열면 CDN 예제와 같은 결과입니다. Windows Edge에서 실제 로컬 4.0.0 파일로 확인했습니다. 로컬 파일 방식은 준비한 파일들을 그대로 사용하므로 jQuery를 다운로드한 뒤에는 이 실습을 외부 CDN 없이 실행할 수 있습니다.

ready=true
message visible=true
clicks=0

defer가 있는 일반 외부 script는 HTML 분석 뒤 문서에 적은 순서대로 실행하므로 라이브러리를 먼저, app.js를 나중에 둡니다. async는 다운로드 완료 순서에 따라 실행돼 이 의존 순서를 보장하지 않습니다. 인라인 script에 defer만 붙여 같은 동작을 기대하지 말고, 위처럼 의존 코드를 외부 파일로 나눕니다.

정상 연결 확인과 오류 찾기

개발자 도구 Console에서 typeof window.jQuery가 function인지, jQuery.fn.jquery가 의도한 버전 문자열인지 확인합니다. 첫 검사가 undefined라면 버전 속성을 읽으려 하지 말고 로딩부터 해결합니다. Network에서 실제 .js 요청의 주소·응답 상태와 내용을 확인합니다. HTML 오류 페이지를 .js 이름으로 받았다고 라이브러리가 로딩된 것은 아닙니다.

‘jQuery is not defined’는 파일 경로·네트워크 차단·실행 순서를 먼저 확인할 신호입니다. CDN을 막으면 이 예제는 Waiting for scripts.에 남고 기본 문장은 보입니다. 로컬 파일은 대소문자, 상위 폴더, 확장자를 확인합니다. HTTPS 페이지에서 HTTP 파일을 연결하거나 사이트의 스크립트 허용 정책이 차단하는 경우도 Network·Console에서 원인을 확인합니다.

‘$ is not a function’이라면 jQuery 로딩 여부와 함께 다른 라이브러리가 $를 사용하는지 봅니다. 파일이 로딩돼도 선택한 id가 다르거나 이벤트를 중복 등록하면 기대한 결과가 나오지 않습니다. 연결 확인, 요소 선택, 이벤트 실행을 단계별로 나누면 원인을 좁히기 쉽습니다.

운영 사이트에는 버전별 변경 사항과 의존 플러그인 지원 범위를 확인한 뒤 적용하고, 기존 연결을 보관해 되돌릴 수 있게 합니다. jQuery를 이미 관리하는 CMS나 프레임워크에는 예제 CDN을 추가로 붙이기보다 기존 파일 등록·의존 순서를 먼저 확인합니다.