Skip to content

jQuery Mobile 치트시트

모바일 웹 앱을 위한 터치 최적화 HTML5 UI 프레임워크입니다.

01

시작하기

페이지 구조

jQuery Mobile은 data-role 속성으로 HTML을 강화합니다. 페이지는 header, main, footer 섹션을 담은 data-role=page div입니다. 모바일 기기에서 올바른 스케일링에는 viewport 메타 태그가 필수입니다. jquery.mobile.js 전에 jQuery 코어를 로드하세요.

jquery-mobile
<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="https://code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
  <script src="https://code.jquery.com/jquery-1.11.1.min.js"></script>
  <script src="https://code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>
</head>
<body>
  <div data-role="page" id="home">
    <div data-role="header"><h1>Home</h1></div>
    <div data-role="main" class="ui-content">Content</div>
    <div data-role="footer"><h4>Footer</h4></div>
  </div>
</body>
</html>

하나의 문서에 여러 페이지

단일 HTML 파일에 여러 개의 data-role=page div를 넣을 수 있습니다. 앵커 href(#about)로 서로 연결하세요. jQuery Mobile은 한 번에 한 페이지를 보여주고 전환을 애니메이션합니다. 초기 로드에는 소스 순서상 첫 페이지만 표시됩니다.

jquery-mobile
<div data-role="page" id="home">
  <div data-role="header"><h1>Home</h1></div>
  <div data-role="main" class="ui-content">
    <a href="#about" class="ui-btn">Go to About</a>
  </div>
</div>

<div data-role="page" id="about" data-theme="b">
  <div data-role="header"><h1>About</h1></div>
  <div data-role="main" class="ui-content">
    <a href="#home" class="ui-btn" data-direction="reverse">Back</a>
  </div>
</div>

AJAX 내비게이션 & 링크

기본적으로 내부(#id)와 같은 오리진 페이지로의 링크는 AJAX로 가져와 전환과 함께 교체됩니다. 일반 전체 페이지 로드를 강제하려면 data-ajax=false를 쓰세요(jQuery Mobile이 아닌 페이지에 유용). data-prefetch는 대상을 미리 로드해 전환이 즉시 느껴지게 합니다.

jquery-mobile
<!-- Default: links load via AJAX and animate a transition -->
<a href="detail.html" class="ui-btn">Open detail (AJAX)</a>

<!-- Force a full page reload (no AJAX) -->
<a href="external.html" data-ajax="false">Full reload</a>

<!-- Open in new window/tab -->
<a href="https://example.com" rel="external">External site</a>

<!-- Prefetch a page when this page loads -->
<a href="next.html" data-prefetch="true" class="ui-btn">Prefetch next</a>

프리페치 & DOM 캐싱

프리페칭은 링크된 페이지를 백그라운드에서 불러와 내비게이션이 즉각적으로 느껴지게 합니다. 기본적으로 방문한 페이지는 DOM에서 제거되지만, domCache는 메모리를 대가로 더 빠른 뒤로 가기 위해 유지합니다. 페이지별로는 data-dom-cache, 전역으로는 page 프로토타입 옵션으로 활성화하세요.

jquery-mobile
<!-- Prefetch several pages -->
<a href="page1.html" data-prefetch="true">Page 1</a>
<a href="page2.html" data-prefetch="true">Page 2</a>

<!-- Globally enable DOM caching of visited pages -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.page.prototype.options.domCache = true;
});
</script>

<!-- Cache a single page -->
<div data-role="page" id="cached" data-dom-cache="true">...</div>

다이얼로그 페이지

링크에 data-rel=dialog를(또는 페이지에 data-dialog=true를) 추가하면 닫기 버튼과 전환이 있는 모달 대화상자 스타일 페이지가 열립니다. 링크에 data-rel=back을 쓰면 닫고 이전 페이지로 돌아갑니다.

jquery-mobile
<!-- Open a page as a dialog -->
<a href="#dialog" class="ui-btn" data-rel="dialog">Open dialog</a>

<div data-role="page" id="dialog" data-dialog="true">
  <div data-role="header"><h1>Dialog</h1></div>
  <div data-role="main" class="ui-content">
    <p>This page is styled as a dialog.</p>
    <a href="#" class="ui-btn" data-rel="back">Close</a>
  </div>
</div>

전역 설정 (mobileinit)

mobileinit 이벤트는 jQuery 코어가 로드된 뒤, jQuery Mobile이 초기화되기 전에 발생합니다 — jquery.mobile.js를 포함하기 전에 여기서 설정을 바인딩하세요. 흔한 오버라이드: 기본 전환, AJAX 설정, 로딩 메시지 텍스트. autoInitializePage=false는 첫 페이지가 언제 초기화될지 제어하게 해 줍니다.

jquery-mobile
<script src="jquery-1.11.1.min.js"></script>
<script>
// Bind BEFORE loading jquery.mobile.js
$(document).on("mobileinit", function () {
  $.mobile.defaultPageTransition = "slide";
  $.mobile.defaultDialogTransition = "pop";
  $.mobile.loadingMessage = "Loading...";
  $.mobile.ajaxEnabled = true;
  $.mobile.linkBindingEnabled = true;
  $.mobile.autoInitializePage = true;
});
</script>
<script src="jquery.mobile-1.4.5.min.js"></script>
02

페이지 전환

기본 전환

링크에 data-transition을 추가해 이동 시 애니메이션을 고르세요. 전환은 CSS 기반입니다(가능한 곳은 하드웨어 가속). 'none'은 애니메이션을 건너뛰어 즉시 이동합니다. 같은 속성이 다이얼로그와 팝업에도 동작합니다.

jquery-mobile
<!-- Apply a transition to a link -->
<a href="#page2" data-transition="slide">Slide</a>
<a href="#page2" data-transition="fade">Fade</a>
<a href="#page2" data-transition="pop">Pop</a>
<a href="#page2" data-transition="flip">Flip</a>
<a href="#page2" data-transition="none">None (instant)</a>

전환 타입

jQuery Mobile은 2D/3D CSS 전환 집합을 제공합니다. 3D 전환(turn, flow, flip)은 성능 좋은 기기에서 멋지지만 오래된 하드웨어에서 우아하게 폴백합니다. pop과 fade가 가장 효율적이며 다이얼로그와 팝업에 권장됩니다.

jquery-mobile
<!-- Available transitions in jQuery Mobile 1.4 -->
fade      <!-- default, fade in/out -->
pop       <!-- scale in from center (good for dialogs) -->
slide     <!-- slide left to right -->
slideup   <!-- slide up from bottom -->
slidedown <!-- slide down from top -->
slidfade  <!-- slide + fade -->
turn      <!-- 3D turn -->
flow      <!-- 3D flow -->
flip      <!-- 3D flip -->
none      <!-- no animation -->

방향 & 역방향

data-direction=reverse는 전환을 거꾸로 재생합니다 — 앞으로 가는 내비게이션을 미러링하도록 Back 버튼에 주로 씁니다. data-transition과 짝짓습니다; 전환이 설정되지 않으면 기본 전환이 역방향으로 재생됩니다.

jquery-mobile
<!-- Reverse a transition (e.g., for Back buttons) -->
<a href="#home" data-transition="slide" data-direction="reverse">Back</a>

<!-- Globally reverse the default -->
<a href="#home" data-direction="reverse">Back (uses default transition reversed)</a>

다이얼로그 전환

다이얼로그에는 어떤 전환이든 쓸 수 있지만 모달에는 pop과 slidedown이 가장 자연스럽습니다. mobileinit 중 $.mobile.defaultDialogTransition으로 전역 기본값을 설정하세요. 다이얼로그의 닫기 액션은 전환을 자동으로 역방향으로 재생합니다.

jquery-mobile
<!-- Combine data-rel=dialog with a transition -->
<a href="#settings" data-rel="dialog" data-transition="pop">Settings</a>
<a href="#settings" data-rel="dialog" data-transition="slidedown">Settings (slide down)</a>

<!-- Set a global default dialog transition -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.defaultDialogTransition = "pop";
});
</script>

비활성화 & 폴백

data-transition=none이나 전역 기본값을 'none'으로 두면 애니메이션이 꺼집니다 — 저사양 기기나 접근성에 유용합니다. jQuery Mobile은 3D transform 지원을 자동 감지해 지원되지 않을 때 3D 전환(flip, turn, flow)을 단순 fade로 저하시킵니다.

jquery-mobile
<!-- Disable transitions for a specific link -->
<a href="#page2" data-transition="none">No animation</a>

<!-- Globally disable (useful for older devices / testing) -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.defaultPageTransition = "none";
  $.mobile.defaultDialogTransition = "none";
});
</script>

<!-- 3D transitions fall back to fade when not supported -->
03

툴바 (Header & Footer)

고정 헤더 & 푸터

data-position=fixed를 추가하면 페이지가 스크롤되는 동안 헤더나 푸터가 뷰포트 위/아래에 고정됩니다. 기본적으로 페이지를 탭하면 툴바 가시성이 토글됩니다. 툴바 뒤에 숨지 않도록 페이지 콘텐츠에 패딩이 붙습니다.

jquery-mobile
<div data-role="page" id="home">
  <div data-role="header" data-position="fixed">
    <h1>Fixed Header</h1>
  </div>
  <div data-role="main" class="ui-content">
    <p>Scroll the page — the toolbars stay in place.</p>
  </div>
  <div data-role="footer" data-position="fixed">
    <h4>Fixed Footer</h4>
  </div>
</div>

풀스크린 툴바

data-fullscreen=true는 공간을 예약하는 대신 고정 툴바를 콘텐츠 위에(반투명으로) 겹칩니다. 콘텐츠가 화면을 채워야 하는 사진 뷰어나 지도에 좋습니다. 툴바는 고정 툴바처럼 탭으로 나타났다 사라집니다.

jquery-mobile
<div data-role="page" id="photo">
  <div data-role="header" data-position="fixed" data-fullscreen="true">
    <h1>Photos</h1>
  </div>
  <div data-role="main" class="ui-content">
    <img src="photo.jpg" style="width:100%">
  </div>
  <div data-role="footer" data-position="fixed" data-fullscreen="true">
    <h4>Footer over content</h4>
  </div>
</div>

지속 툴바

두 페이지가 같은 data-id와 data-position=fixed를 가진 푸터(또는 헤더)를 가지면, 툴바는 페이지와 함께 애니메이션되는 대신 페이지 전환에 걸쳐 지속됩니다. 지속되는 하단 내비게이션 바의 표준 패턴입니다 — 페이지마다 활성 링크만 바뀝니다.

jquery-mobile
<!-- Both pages use the SAME data-id so the footer persists -->
<div data-role="page" id="home">
  <div data-role="footer" data-id="main-nav" data-position="fixed">
    <div data-role="navbar">
      <ul><li><a href="#home" class="ui-btn-active">Home</a></li>
      <li><a href="#settings">Settings</a></li></ul>
    </div>
  </div>
</div>

<div data-role="page" id="settings">
  <div data-role="footer" data-id="main-nav" data-position="fixed">
    <div data-role="navbar">
      <ul><li><a href="#home">Home</a></li>
      <li><a href="#settings" class="ui-btn-active">Settings</a></li></ul>
    </div>
  </div>
</div>

탭 토글 동작

고정 툴바는 사용자가 페이지를 탭하면 가시성을 토글합니다. 툴바를 항상 보이게 하려 data-tap-toggle=false를 쓰세요. 관련 요소별 옵션: data-hide-during-focus(input 포커스 시 숨김)과 data-update-page-padding(리사이즈 시 페이지 패딩 재적용).

jquery-mobile
<!-- Disable tap-to-toggle on a fixed toolbar -->
<div data-role="header" data-position="fixed" data-tap-toggle="false">
  <h1>Always visible</h1>
</div>

<!-- Globally turn off tap toggle -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.toolbar.prototype.options.tapToggle = false;
});
</script>

툴바 테마 & 버튼

헤더는 ui-btn-left / ui-btn-right 클래스로 배치된 버튼을 담을 수 있습니다. data-theme이 바의 색 스와치를 정합니다. data-iconpos=notext는 아이콘만 보여 컴팩트한 모양을 만듭니다. 헤더 안의 버튼은 인라인 버튼으로 자동 스타일링됩니다.

jquery-mobile
<div data-role="header" data-theme="b">
  <a href="#" class="ui-btn-left" data-icon="home" data-iconpos="notext">Home</a>
  <h1>Title</h1>
  <a href="#" class="ui-btn-right" data-icon="gear" data-iconpos="notext">Settings</a>
</div>

동적 툴바 갱신

런타임에 툴바 마크업을 바꾼 뒤에는 $(el).toolbar('refresh')를 호출해 스타일링과 패딩을 재적용하세요. 툴바 위젯(1.4에서 도입)이 고정 위치와 탭 토글을 관리합니다; 페이지 생성 후 툴바를 추가했다면 $().toolbar()로 수동 초기화하세요.

jquery-mobile
<script>
// Update the header title and re-enhance after DOM change
$(function () {
  $("#my-header h1").text("New Title");
  $("#my-header").toolbar("refresh");
});
</script>

<div data-role="header" id="my-header" data-position="fixed">
  <h1>Old Title</h1>
</div>
05

버튼

버튼 기본

class=ui-btn을 가진 모든 <a>(또는 data-role=button), 그리고 <button>과 <input type=button|submit|reset>이 스타일된 버튼으로 자동 강화됩니다. ui-btn 클래스가 data-role에 의존하지 않고 링크를 버튼으로 표시하는 현대적 방법입니다.

jquery-mobile
<!-- Anchor button -->
<a href="#" class="ui-btn">Link Button</a>

<!-- <button> and <input> auto-enhanced -->
<button class="ui-btn">Button Element</button>
<input type="button" value="Input Button">
<input type="submit" value="Submit">

<!-- Use data-role explicitly -->
<a href="#" data-role="button">Anchor via role</a>

인라인 버튼

기본 버튼은 전체 너비(block)입니다. ui-btn-inline(또는 data-inline=true)을 추가하면 버튼이 라벨 크기만큼만 되어 여러 버튼이 나란히 앉습니다. '취소 | 확인' 같은 액션 행에 유용합니다.

jquery-mobile
<!-- Inline: only as wide as the content -->
<a href="#" class="ui-btn ui-btn-inline">A</a>
<a href="#" class="ui-btn ui-btn-inline">B</a>
<a href="#" class="ui-btn ui-btn-inline">C</a>

<!-- Default (block) buttons fill the width -->
<a href="#" class="ui-btn">Full-width button</a>

버튼 아이콘

아이콘 추가에는 ui-icon-{name}, 배치에는 ui-btn-icon-{pos}를 쓰세요(left, right, top, bottom, notext). ui-btn-icon-notext는 텍스트를 숨기고 아이콘만 보여줍니다 — 접근성/스크린 리더를 위해 그래도 텍스트를 제공하세요.

jquery-mobile
<a href="#" class="ui-btn ui-icon-home ui-btn-icon-left">Home</a>
<a href="#" class="ui-btn ui-icon-search ui-btn-icon-right">Search</a>
<a href="#" class="ui-btn ui-icon-gear ui-btn-icon-top">Settings</a>
<a href="#" class="ui-btn ui-icon-star ui-btn-icon-notext">Star (icon only)</a>
<a href="#" class="ui-btn ui-icon-delete ui-btn-icon-bottom">Delete</a>

아이콘 위치 & 인라인

data-iconpos 속성은 ui-btn-icon-* 클래스의 레거시 등가물입니다. 'notext'는 아이콘만 보여줍니다(요소 텍스트로 스크린 리더용 보이는 텍스트는 항상 유지). 한 버튼에 인라인과 아이콘 클래스를 자유롭게 조합할 수 있습니다.

jquery-mobile
<!-- data-* equivalents -->
<a href="#" data-role="button" data-icon="home" data-iconpos="left">Home</a>
<a href="#" data-role="button" data-icon="home" data-iconpos="notext">Home</a>

<!-- Combine inline + icon -->
<a href="#" class="ui-btn ui-btn-inline ui-icon-plus ui-btn-icon-left">Add</a>
<a href="#" class="ui-btn ui-btn-inline ui-icon-minus ui-btn-icon-left">Remove</a>

미니 & 비활성 버튼

더 작고 컴팩트한 버튼에는 ui-mini(또는 data-mini=true)를 추가하세요 — 촘촘한 툴바에 유용합니다. 버튼 비활성화에는 ui-state-disabled(또는 <button>/<input>의 네이티브 disabled 속성)를 씁니다. 비활성 버튼은 탭을 무시합니다.

jquery-mobile
<!-- Mini (smaller) button -->
<a href="#" class="ui-btn ui-mini">Mini</a>

<!-- Disabled button -->
<a href="#" class="ui-btn ui-state-disabled">Disabled</a>

<!-- Native disabled -->
<button disabled>Disabled button</button>
<input type="submit" value="Go" disabled>

버튼 그룹 (Controlgroup)

controlgroup이 버튼을 시각적으로 묶습니다 — 인접 버튼이 둥근 모서리를 공유하고 간격이 없습니다. data-type=horizontal은 한 행에 배치합니다(세그먼트 컨트롤에 좋음); 기본 세로는 쌓습니다. 체크박스/라디오도 통합 세트로 그룹화합니다.

jquery-mobile
<div data-role="controlgroup" data-type="horizontal">
  <a href="#" class="ui-btn">Yes</a>
  <a href="#" class="ui-btn">No</a>
  <a href="#" class="ui-btn">Maybe</a>
</div>

<!-- Vertical group (default) -->
<div data-role="controlgroup">
  <a href="#" class="ui-btn">Option 1</a>
  <a href="#" class="ui-btn">Option 2</a>
</div>
06

리스트 뷰

기본 Listview

<ul>에 data-role=listview를 추가하면 전체 너비의 탭 가능한 행을 가진 터치 친화적 리스트가 됩니다. <a>를 포함한 각 <li>가 오른쪽 화살표가 있는 링크 행이 됩니다. data-inset=true는 끝까지 이어지는 대신 둥근 모서리와 마진이 있는 인셋 리스트로 만듭니다.

jquery-mobile
<ul data-role="listview" data-inset="true">
  <li><a href="#">Apple</a></li>
  <li><a href="#">Banana</a></li>
  <li><a href="#">Cherry</a></li>
</ul>

인셋 리스트

끝까지 이어지는 리스트는 전체 너비를 차지합니다(풀스크린 메뉴에 좋음); 인셋 리스트는 둥근 모서리와 둘러싼 마진이 있습니다(페이지 내 콘텐츠 섹션에 좋음). 인셋 리스트에는 data-inset=true를 쓰세요 — 그룹화된 설정 패널처럼 보입니다.

jquery-mobile
<!-- Edge-to-edge (default) -->
<ul data-role="listview">
  <li><a href="#">Item 1</a></li>
</ul>

<!-- Inset: rounded, with margins -->
<ul data-role="listview" data-inset="true">
  <li><a href="#">Item 1</a></li>
  <li><a href="#">Item 2</a></li>
</ul>

리스트 구분선

data-role=list-divider를 가진 <li>는 클릭 불가능한 섹션 헤더가 됩니다. data-autodividers=true는 각 항목 텍스트의 첫 글자를 기준으로 구분선을 자동 삽입합니다 — 알파벳순 연락처 리스트에 완벽합니다.

jquery-mobile
<ul data-role="listview" data-inset="true">
  <li data-role="list-divider">Fruits</li>
  <li><a href="#">Apple</a></li>
  <li><a href="#">Banana</a></li>
  <li data-role="list-divider">Vegetables</li>
  <li><a href="#">Carrot</a></li>
</ul>

<!-- Auto dividers from first letter -->
<ul data-role="listview" data-autodividers="true">
  <li><a href="#">Alice</a></li>
  <li><a href="#">Bob</a></li>
</ul>

카운트 버블 & 썸네일

<li> 안에 class=ui-li-count를 가진 span을 넣으면 오른쪽에 숫자 카운트 버블이 표시됩니다. 왼쪽 썸네일에는 class=ui-li-thumb을 가진 <img>(보통 80x80)를 쓰세요. <h3>/<p>와 결합하면 앱 같은 풍부한 리스트 행이 됩니다.

jquery-mobile
<ul data-role="listview" data-inset="true">
  <!-- Count bubble -->
  <li><a href="#">Inbox <span class="ui-li-count">12</span></a></li>
  <!-- Thumbnail on the left -->
  <li>
    <a href="#">
      <img src="thumb.jpg" class="ui-li-thumb">
      <h3>Title</h3>
      <p>Description</p>
      <span class="ui-li-count">3</span>
    </a>
  </li>
</ul>

검색 필터

data-filter=true는 리스트 위에 검색 input을 추가해 텍스트 기준으로 항목을 실시간 필터링합니다. data-filter-placeholder가 안내 문구를 커스터마이징합니다. data-filter-reveal=true는 사용자가 타이핑할 때까지 모든 항목을 숨깁니다 — 자동완성식 조회에 유용합니다.

jquery-mobile
<ul data-role="listview" data-filter="true"
    data-filter-placeholder="Search fruits...">
  <li><a href="#">Apple</a></li>
  <li><a href="#">Banana</a></li>
  <li><a href="#">Cherry</a></li>
</ul>

<!-- Filter reveals hidden items (collapsible search) -->
<ul data-role="listview" data-filter="true" data-filter-reveal="true">
  <li><a href="#">Hidden until searched</a></li>
</ul>

분할 버튼 & 중첩 리스트

<li>가 <a> 두 개를 담으면 jQuery Mobile이 분할 버튼을 렌더링합니다: 주 행이 첫 링크로 이동하고, 오른쪽의 별개 아이콘 버튼(data-split-icon으로 설정)이 두 번째를 엽니다. <li> 안의 중첩 <ul>은 자동으로 드릴다운 서브페이지가 됩니다.

jquery-mobile
<!-- Split button: row link + icon link on the right -->
<ul data-role="listview" data-split-icon="gear" data-inset="true">
  <li>
    <a href="#detail">Go to detail</a>
    <a href="#edit">Edit</a>
  </li>
</ul>

<!-- Nested list (child <ul> becomes a sub-page) -->
<ul data-role="listview">
  <li>Fruits
    <ul>
      <li><a href="#">Apple</a></li>
      <li><a href="#">Banana</a></li>
    </ul>
  </li>
</ul>
07

폼 컨트롤

폼 구조 & AJAX 제출

jQuery Mobile은 폼 input을 자동 강화하고 기본적으로 AJAX로 폼을 제출해, 로딩 스피너를 보여주고 결과 페이지로 전환합니다. 전통적 전체 페이지 제출을 하려 data-ajax=false를 설정하세요(현대 API를 쓰지 않는 파일 업로드에 필요).

jquery-mobile
<form action="/submit" method="post" data-ajax="true">
  <label for="name">Name:</label>
  <input type="text" name="name" id="name" placeholder="Your name">

  <button type="submit" class="ui-btn">Submit</button>
</form>

<!-- Disable AJAX for this form (normal full submit) -->
<form action="/upload" method="post" data-ajax="false">...</form>

텍스트 입력 & 지우기 버튼

모든 HTML5 input 타입(text, email, tel, number, password, date 등)이 일관되게 스타일링됩니다. data-clear-btn=true는 필드 안 지우기(x) 버튼을 추가합니다. 컨트롤을 jQuery Mobile 스타일링 없이 순수 네이티브 input으로 두려 data-role=none을 쓰세요.

jquery-mobile
<label for="email">Email</label>
<input type="email" id="email" data-clear-btn="true" placeholder="[email protected]">

<label for="phone">Phone</label>
<input type="tel" id="phone" data-clear-btn="true" data-clear-btn-text="Clear">

<!-- Non-enhanced native input -->
<input type="text" data-role="none">

필드 컨테이너

라벨 + 컨트롤 쌍을 class=ui-field-contain을 가진 div로 감싸세요. 넓은 화면에서는 라벨과 input이 나란히 놓이고, 좁은 폰에서는 세로로 쌓입니다. 이 반응형 동작이 구형 data-role=fieldcontain 속성을 대체합니다.

jquery-mobile
<div class="ui-field-contain">
  <label for="user">Username</label>
  <input type="text" id="user">
</div>

<div class="ui-field-contain">
  <label for="pwd">Password</label>
  <input type="password" id="pwd">
</div>

검색 입력

<input type=search>는 돋보기 아이콘이 있는 검색 필드로 강화됩니다. listview와 짝지으려 input에 id를 주고 listview의 filter에 data-input=#id를 설정하세요 — 이로써 검색 상자를 페이지 어디에나 둘 수 있습니다.

jquery-mobile
<label for="q">Search</label>
<input type="search" id="q" placeholder="Search...">

<!-- Search input feeding a listview filter -->
<input type="search" id="my-filter" data-type="search">
<ul data-role="listview" data-filter="true"
    data-input="#my-filter">
  <li><a href="#">Apple</a></li>
  <li><a href="#">Banana</a></li>
</ul>

Textarea & 히든 입력

textarea는 다른 input과 어울리게 스타일링되며 기본적으로 타이핑에 따라 자동으로 커집니다; 높이를 고정하고 스크롤바를 두려 data-autogrow=false를 설정하세요. 히든 input은 그대로 통과됩니다. 모든 input처럼 반응형 라벨을 위해 ui-field-contain으로 감싸세요.

jquery-mobile
<label for="bio">Bio</label>
<textarea id="bio" placeholder="Tell us about you"></textarea>

<!-- Auto-grow textarea -->
<textarea id="bio" data-autogrow="false"></textarea>

<!-- Hidden inputs are not styled -->
<input type="hidden" name="id" value="42">

자동 강화 끄기

컨트롤에 data-role=none을 추가하면 jQuery Mobile 강화를 건너뛰고 네이티브로 유지됩니다. 프로젝트 전역 규칙으로는 mobileinit에서 keepNative를 절대 강화하지 말아야 할 요소의 선택자 문자열로 설정하세요 — 커스텀 스타일 컨트롤과 jQM 페이지를 섞을 때 유용합니다.

jquery-mobile
<!-- Keep a control native (no jQM styling) -->
<select data-role="none">...</select>
<input type="checkbox" data-role="none">

<!-- Globally disable enhancement for a tag -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.page.prototype.options.keepNative = "select, input[type=checkbox]";
});
</script>
08

슬라이더

기본 범위 슬라이더

min, max, value, step을 가진 <input type=range>가 값 버블이 있는 터치 친화적 슬라이더로 강화됩니다. value 속성이 초기 위치를 정합니다. 슬라이더는 값을 input에 다시 쓰므로 폼과 함께 정상 제출됩니다.

jquery-mobile
<label for="volume">Volume</label>
<input type="range" name="volume" id="volume"
       value="50" min="0" max="100" step="1">

하이라이트 슬라이더

data-highlight=true는 핸들 왼쪽 트랙을 활성 테마 색으로 채워 현재 수준을 명확히 보여줍니다. 없으면 트랙은 단일 평면 색입니다. 볼륨이나 밝기 같은 설정에 유용합니다.

jquery-mobile
<label for="brightness">Brightness</label>
<input type="range" id="brightness"
       value="70" min="0" max="100"
       data-highlight="true">

미니 슬라이더

data-mini=true는 세로 공간을 덜 차지하는 더 작고 컴팩트한 슬라이더를 렌더링합니다 — 설정 패널에 여러 컨트롤을 묶을 때 편리합니다. 일반 슬라이더와 동일하게 동작하되 크기만 줄어듭니다.

jquery-mobile
<label for="age">Age</label>
<input type="range" id="age" value="25" min="0" max="120"
       data-mini="true" data-highlight="true">

Step & 다중 슬라이더

step이 증분을 제어합니다(예: step=5면 0, 5, 10, ...으로 스냅). 각 range input이 독립적인 슬라이더입니다; 이중 핸들 범위를 원하면 커스텀 위젯을 만들거나 서드파티 플러그인을 써야 합니다. 네이티브 value, min, max 속성이 동작을 구동합니다.

jquery-mobile
<label for="temp">Temperature (step 5)</label>
<input type="range" id="temp" value="20" min="0" max="100" step="5">

<!-- Two independent sliders -->
<label for="low">Min</label>
<input type="range" id="low" value="10" min="0" max="100">
<label for="high">Max</label>
<input type="range" id="high" value="90" min="0" max="100">

슬라이더 이벤트

슬라이더는 사용자가 핸들 드래그를 시작하면 slidestart를, 드래그가 끝나면 slidestop을 발생시킵니다. 드래그 중 지속적인 업데이트에는 기저 range input의 네이티브 'input'이나 'change' 이벤트에 바인딩하세요. 값 읽기/쓰기는 $(el).val()입니다.

jquery-mobile
<label for="vol">Volume</label>
<input type="range" id="vol" value="50" min="0" max="100">

<script>
$("#vol").on("slidestart", function () {
  console.log("User started dragging");
});
$("#vol").on("slidestop", function () {
  console.log("Value is now " + $(this).val());
});
</script>
09

플립 토글 스위치

기본 플립 토글

플립 스위치는 정확히 두 개의 <option>과 data-role=slider를 가진 <select>입니다. iOS식 on/off 토글로 렌더링됩니다. 선택된 옵션이 초기 상태를 결정하며 값은 일반 select처럼 제출됩니다(선택된 옵션의 값).

jquery-mobile
<label for="notify">Notifications</label>
<select name="notify" id="notify" data-role="slider">
  <option value="off">Off</option>
  <option value="on" selected>On</option>
</select>

커스텀 라벨

두 옵션의 텍스트가 스위치 양쪽의 라벨이 됩니다. 어떤 짧은 텍스트든 쓸 수 있습니다(On/Off, Yes/No, 사용/사용 안 함). 작은 화면에서 잘리지 않도록 라벨을 짧게 유지하세요.

jquery-mobile
<label for="wifi">Wi-Fi</label>
<select id="wifi" data-role="slider">
  <option value="disabled">Disabled</option>
  <option value="enabled" selected>Enabled</option>
</select>

미니 플립 스위치

data-mini=true는 세로 공간을 덜 차지하는 더 작은 플립 스위치를 렌더링하며, 미니 슬라이더와 다른 미니 컨트롤과 어울립니다. 촘촘한 설정 패널에서 미니 컨트롤을 함께 두어 일관된 컴팩트 모양을 만드세요.

jquery-mobile
<label for="sync">Auto-sync</label>
<select id="sync" data-role="slider" data-mini="true">
  <option value="no">No</option>
  <option value="yes" selected>Yes</option>
</select>

플립 테마

data-theme이 스위치 핸들의 색을 정하고, data-track-theme이 그 뒤의 트랙 색을 정합니다. 스와치를 섞으면(예: 밝은 트랙에 어두운 핸들) 활성 상태가 시각적으로 더 구별됩니다.

jquery-mobile
<label for="darkmode">Dark mode</label>
<select id="darkmode" data-role="slider"
        data-theme="b" data-track-theme="a">
  <option value="off">Off</option>
  <option value="on" selected>On</option>
</select>

프로그래밍 토글

$(el).val(value)로 값을 설정한 뒤 .slider('refresh')를 호출해 시각 토글을 맞추세요. 현재 상태 읽기는 .val()입니다. 코드로 기저 select의 값을 바꾼 뒤에는 항상 refresh하세요 — 아니면 핸들이 움직이지 않습니다.

jquery-mobile
<select id="power" data-role="slider">
  <option value="off">Off</option>
  <option value="on">On</option>
</select>

<script>
// Turn the switch on programmatically
$("#power").val("on").slider("refresh");
// Read current state
var state = $("#power").val(); // "on" or "off"
</script>
10

체크박스 & 라디오

체크박스

체크박스는 <label for=id>가 감싸거나(또는 인접한) 일반 <input type=checkbox>입니다. jQuery Mobile이 라벨을 탭 가능한 블록으로 스타일링합니다. 라벨이 input을 감쌀 때는 for 속성이 선택입니다. 체크 상태는 예전처럼 폼과 함께 제출됩니다.

jquery-mobile
<label for="agree"><input type="checkbox" id="agree" name="agree"> I agree</label>

<label for="news"><input type="checkbox" id="news" name="news" checked> Newsletter</label>

<!-- Wrap in ui-field-contain for layout -->
<div class="ui-field-contain">
  <label for="agree">I agree to terms</label>
  <input type="checkbox" id="agree">
</div>

라디오 버튼

같은 name 속성을 주어 라디오를 그룹화하세요. 그룹을 data-role=controlgroup을 가진 fieldset으로(그리고 <legend>와 함께) 감싸면 공유 모서리로 시각적으로 묶입니다. 같은 이름의 그룹에서는 한 번에 하나의 라디오만 체크될 수 있습니다.

jquery-mobile
<fieldset data-role="controlgroup">
  <legend>Choose a color:</legend>
  <label for="r"><input type="radio" name="color" id="r" value="red" checked> Red</label>
  <label for="g"><input type="radio" name="color" id="g" value="green"> Green</label>
  <label for="b"><input type="radio" name="color" id="b" value="blue"> Blue</label>
</fieldset>

가로 Controlgroup

data-type=horizontal은 체크박스나 라디오를 세로 스택 대신 세그먼트 컨트롤처럼 한 행에 배치합니다. 컴팩트하며 짧은 라벨(S/M/L, 예/아니오)에 잘 맞습니다. 좁은 화면에 맞도록 라벨을 짧게 유지하세요.

jquery-mobile
<fieldset data-role="controlgroup" data-type="horizontal">
  <legend>Size:</legend>
  <label for="s"><input type="radio" name="size" id="s" value="s" checked> S</label>
  <label for="m"><input type="radio" name="size" id="m" value="m"> M</label>
  <label for="l"><input type="radio" name="size" id="l" value="l"> L</label>
</fieldset>

미니 & 테마

data-mini=true가 컨트롤을 줄이고, data-theme은 항목이 체크/활성일 때 적용되는 스와치를 정합니다. 페이지 배경에서 두드러지도록 활성 상태에 테마를 주세요. 이 옵션들은 controlgroup 전체에 한 번에 적용됩니다.

jquery-mobile
<fieldset data-role="controlgroup" data-mini="true" data-theme="b">
  <label for="a"><input type="checkbox" id="a"> Option A</label>
  <label for="b"><input type="checkbox" id="b"> Option B</label>
</fieldset>

변경 후 refresh

코드에서 체크박스/라디오의 checked 프로퍼티를 설정한 뒤 .checkboxradio('refresh')를 호출해 강화된 시각을 맞추세요. 런타임에 controlgroup 안의 input을 추가하거나 제거했다면 .controlgroup('refresh')로 그룹화된 스타일링을 재적용하세요.

jquery-mobile
<input type="checkbox" id="c1">

<script>
// Check programmatically and update the visual state
$("#c1").prop("checked", true).checkboxradio("refresh");

// For a controlgroup, refresh the group after adding/removing items
$("#grp").controlgroup("refresh");
</script>
11

Select 메뉴

네이티브 Select

기본적으로 jQuery Mobile은 커스텀 스타일 select를 보여주지만, 밑의 OS 피커가 여전히 열립니다. 기기의 네이티브 드롭다운을 완전히 쓰려 data-native-menu=true(또는 data-role=none)를 설정하세요 — 더 빠르고 익숙하지만 플랫폼 간 시각적 일관성이 떨어집니다.

jquery-mobile
<label for="country">Country</label>
<select id="country" data-native-menu="true">
  <option value="us">United States</option>
  <option value="ca">Canada</option>
  <option value="uk">United Kingdom</option>
</select>

<!-- data-role="none" also keeps it fully native -->
<select data-role="none">...</select>

커스텀 Select 메뉴

data-native-menu=false는 네이티브 피커 대신 jQuery Mobile 스타일 팝업 메뉴를 열어 모든 기기에서 일관된 모양을 줍니다. 폰에서는 '완료' 버튼이 있는 전체 화면 다이얼로그로, 태블릿에서는 필드 근처의 작은 팝업으로 나타납니다.

jquery-mobile
<label for="fruit">Fruit</label>
<select id="fruit" data-native-menu="false">
  <option value="apple">Apple</option>
  <option value="banana">Banana</option>
  <option value="cherry">Cherry</option>
</select>

플레이스홀더 & multiple

값이 비어 있는 첫 옵션이 플레이스홀더 역할을 합니다. data-overlay-theme이 커스텀 메뉴의 배경색을 정합니다. multiple 속성을 추가하면 커스텀 메뉴가 사용자가 여러 옵션을 고를 수 있는 체크리스트 다이얼로그가 되며, 버튼에 쉼표로 구분해 표시됩니다.

jquery-mobile
<label for="color">Color</label>
<select id="color" data-native-menu="false" data-overlay-theme="b">
  <option value="">Choose a color...</option>
  <option value="red">Red</option>
  <option value="green">Green</option>
</select>

<!-- Multiple selection (renders as a checklist dialog) -->
<label for="tags">Tags</label>
<select id="tags" multiple data-native-menu="false">
  <option value="a">A</option>
  <option value="b">B</option>
</select>

Select 테마 & 오버레이

data-theme은 select 버튼 자체를 스타일링하고, data-overlay-theme은 팝업/배경색을 정하며, data-divider-theme은 메뉴 안의 list-divider 구분선을 색칠합니다. 옵션 사이에 <li data-role=list-divider> 요소를 넣어 시각적으로 그룹화할 수 있습니다.

jquery-mobile
<label for="size">Size</label>
<select id="size" data-native-menu="false"
        data-theme="a" data-overlay-theme="b" data-divider-theme="a">
  <option value="s">Small</option>
  <option value="m">Medium</option>
  <li data-role="list-divider">Large sizes</li>
  <option value="l">Large</option>
</select>

Select 이벤트

선택에 반응하려면 표준 'change' 이벤트를 listen하세요. 코드로 값(또는 옵션)을 바꾼 뒤에는 .selectmenu('refresh')를 호출해 버튼 라벨이 새 선택과 일치하게 하세요. 메뉴 재구축은 재초기화가 아니라 'refresh'로 하세요.

jquery-mobile
<label for="city">City</label>
<select id="city" data-native-menu="false">
  <option value="ny">New York</option>
  <option value="la">Los Angeles</option>
</select>

<script>
$("#city").on("change", function () {
  console.log("Selected: " + $(this).val());
});
// Update options then refresh
$("#city").val("la").selectmenu("refresh");
</script>
12

팝업

기본 팝업

팝업은 data-role=popup을 가진 div입니다. data-rel=popup으로 그 id에 링크해 엽니다. 팝업은 기본적으로 가운데 정렬로 페이지 위에 겹칩니다. 패딩에는 ui-content를 더하고, 안의 링크에 data-rel=back을 써 닫으세요.

jquery-mobile
<a href="#myPopup" data-rel="popup" class="ui-btn">Open popup</a>

<div data-role="popup" id="myPopup" class="ui-content">
  <p>This is a popup.</p>
  <a href="#" class="ui-btn" data-rel="back">Close</a>
</div>

팝업 전환

여는 링크(또는 팝업 자체)에 data-transition을 써 애니메이션을 고르세요. 팝업에는 pop과 fade가 가장 자연스럽습니다. 페이지용 전환 집합이 여기에도 적용되며, 닫기 액션은 전환을 자동으로 역방향으로 재생합니다.

jquery-mobile
<a href="#p" data-rel="popup" data-transition="pop">Pop</a>
<a href="#p" data-rel="popup" data-transition="fade">Fade</a>
<a href="#p" data-rel="popup" data-transition="slidedown">Slide down</a>

<div data-role="popup" id="p" class="ui-content" data-theme="a">
  <p>Transitioned in.</p>
</div>

팝업 위치

data-position-to가 팝업이 나타날 곳을 제어합니다: 'origin'(연 요소, 기본값), '#someId'(특정 요소), 'window'(화면 중앙). popup('open', x, y)으로 프로그래밍 방식으로 열 때는 x/y 좌표를 전달할 수도 있습니다.

jquery-mobile
<!-- Position relative to an element / coordinates -->
<a href="#tip" data-rel="popup" data-position-to="origin">Tip (on the link)</a>
<a href="#tip" data-rel="popup" data-position-to="#target">Tip (on #target)</a>
<a href="#tip" data-rel="popup" data-position-to="window">Centered</a>

<div data-role="popup" id="tip" class="ui-content">
  <p>Positioned popup.</p>
</div>

팝업 메뉴 & 툴팁

팝업은 어떤 콘텐츠든 담을 수 있습니다 — listview는 컨텍스트 메뉴가 되고, 문단은 툴팁이 됩니다. 팝업은 data-theme으로, 안의 콘텐츠는 자체 테마로 스타일링하세요. 사용자가 바깥을 탭하면 팝업이 자동 닫힙니다(data-dismissible=false면 제외).

jquery-mobile
<a href="#menu" data-rel="popup" class="ui-btn">Menu</a>
<div data-role="popup" id="menu" data-theme="b">
  <ul data-role="listview" data-inset="true" data-theme="d">
    <li data-role="divider">Actions</li>
    <li><a href="#">Edit</a></li>
    <li><a href="#">Share</a></li>
    <li><a href="#">Delete</a></li>
  </ul>
</div>

다이얼로그 팝업

창 중앙에 위치하고 닫기 버튼이 있는 팝업이 모달 다이얼로그 역할을 합니다. 모서리에 X 버튼(ui-btn-icon-notext를 가진 ui-icon-delete)을 추가하세요. 전체 너비 시트 대신 진짜 다이얼로그 모양을 위해 max-width 스타일로 너비를 제한하세요.

jquery-mobile
<a href="#dlg" data-rel="popup" data-position-to="window"
   data-transition="pop" class="ui-btn">Open dialog</a>

<div data-role="popup" id="dlg" data-theme="a" class="ui-content"
     style="max-width:400px;">
  <a href="#" data-rel="back" class="ui-btn ui-corner-all ui-icon-delete
     ui-btn-icon-notext ui-btn-right">Close</a>
  <h3>Confirm</h3>
  <p>Are you sure?</p>
  <a href="#" class="ui-btn ui-btn-b" data-rel="back">Yes</a>
  <a href="#" class="ui-btn" data-rel="back">No</a>
</div>

프로그래밍 열기 & 닫기 허용

코드로 팝업을 열거나 닫으려 .popup('open'/'close')을 쓰세요. data-dismissible=false는 바깥 탭으로 닫기를 막아 Close 버튼 사용을 강제합니다 — 필수 확인에 이상적입니다. 열 때 x/y 좌표나 위치 객체를 전달할 수 있습니다.

jquery-mobile
<div data-role="popup" id="p2" data-dismissible="false">
  <p>Cannot close by tapping outside.</p>
  <a href="#" class="ui-btn" data-rel="back">Close</a>
</div>

<script>
// Open programmatically (optionally at coordinates)
$("#p2").popup("open");
$("#p2").popup("open", { x: 100, y: 200 });
// Close programmatically
$("#p2").popup("close");
</script>
13

패널

기본 패널

패널은 data-role=panel을 가진 div이며 페이지 안에(보통 헤더 앞에) 둡니다. 버튼으로 그 id에 링크해 엽니다. 안의 링크에 data-rel=close를 써 패널을 닫으세요. 패널은 슬라이드아웃 내비게이션 메뉴에 완벽합니다.

jquery-mobile
<div data-role="page" id="home">
  <div data-role="panel" id="myPanel">
    <h2>Menu</h2>
    <p>Panel content here.</p>
    <a href="#" class="ui-btn" data-rel="close">Close</a>
  </div>

  <div data-role="header">
    <a href="#myPanel" class="ui-btn ui-btn-inline ui-corner-all ui-icon-bars ui-btn-icon-notext">Menu</a>
    <h1>Home</h1>
  </div>
  <div data-role="main" class="ui-content">
    <p>Page content.</p>
  </div>
</div>

패널 표시 모드

data-display가 열림 애니메이션을 제어합니다: 'reveal'(기본값)은 페이지를 옆으로 밀어 아래의 패널을 드러내고, 'overlay'는 패널을 페이지 위에 겹치며, 'push'는 패널이 들어오고 페이지가 밀립니다. 메뉴에는 overlay가 가장 흔합니다.

jquery-mobile
<div data-role="panel" id="p1" data-display="reveal">Reveal</div>
<div data-role="panel" id="p2" data-display="overlay">Overlay</div>
<div data-role="panel" id="p3" data-display="push">Push</div>

<!-- data-display controls how the panel interacts with the page:
     reveal : panel sits under the page, page slides away
     overlay: panel slides over the page (page stays)
     push   : both panel and page slide -->

패널 위치

data-position=left(기본값) 또는 right가 패널이 어느 쪽에서 슬라이드되는지 정합니다. 같은 페이지에 왼쪽과 오른쪽 패널을 모두 둘 수 있습니다. 한 번에 하나의 패널만 열릴 수 있으며, 두 번째를 열면 첫 번째가 닫힙니다.

jquery-mobile
<!-- Left panel (default) -->
<div data-role="panel" id="leftP" data-position="left">Left</div>

<!-- Right panel -->
<div data-role="panel" id="rightP" data-position="right">Right</div>

<a href="#leftP" class="ui-btn">Open left</a>
<a href="#rightP" class="ui-btn">Open right</a>

닫기 허용 & 스와이프

data-dismissible=true(기본값)는 바깥을 탭하면 패널을 닫습니다. data-swipe-close=true는 사용자가 반대 방향으로 스와이프해 닫게 합니다(예: 오른쪽 스와이프로 왼쪽 패널 닫기). 둘 다 overlay 패널에서 기본 켜져 있습니다.

jquery-mobile
<div data-role="panel" id="p"
     data-dismissible="true"
     data-swipe-close="true"
     data-position="left"
     data-display="overlay">
  <p>Tap outside or swipe to close.</p>
</div>

패널 이벤트

패널은 panelbeforeopen, panelopen, panelbeforeclose, panelclose 이벤트를 발생시킵니다. 'before' 핸들러에서 false를 반환하면 액션이 취소됩니다 — 닫기 전 확인에 유용. 코드로 열거나 닫으려 .panel('open'/'close')을 쓰세요.

jquery-mobile
<div data-role="panel" id="p">...</div>

<script>
$("#p").on("panelopen", function () {
  console.log("Panel opened");
});
$("#p").on("panelbeforeclose", function () {
  // return false here to prevent closing
  console.log("About to close");
});
$("#p").on("panelclose", function () {
  console.log("Panel closed");
});

// Open / close programmatically
$("#p").panel("open");
$("#p").panel("close");
</script>
14

Collapsible

기본 Collapsible

data-role=collapsible을 가진 div는 클릭 가능한 헤더(제목 h1-h6)와 펼칠 수 있는 콘텐츠(나머지)를 감쌉니다. 기본적으로 접힌 상태로 시작합니다. 헤더 클릭이 +/- 아이콘과 함께 콘텐츠를 열고 닫습니다.

jquery-mobile
<div data-role="collapsible">
  <h3>Section title</h3>
  <p>Hidden content shown when expanded.</p>
  <p>Click the header to toggle.</p>
</div>

Collapsible 아이콘 & 테마

표시자 커스터마이징에는 data-collapsed-icon과 data-expanded-icon을 쓰세요(기본 plus/minus). data-theme은 헤더를, data-content-theme은 펼쳐진 콘텐츠 영역을 스타일링합니다. data-collapsed=false는 섹션이 접힌 대신 펼쳐진 채 시작되게 합니다.

jquery-mobile
<div data-role="collapsible"
     data-collapsed-icon="carat-r"
     data-expanded-icon="carat-d"
     data-theme="b" data-content-theme="a"
     data-collapsed="false">
  <h3>Initially open</h3>
  <p>Custom icons and theme.</p>
</div>

Collapsible 세트 (아코디언)

collapsibleset이 collapsible들을 묶어 한 번에 하나만 열리게 합니다 — 아코디언입니다. 하나를 열면 나머지가 자동으로 닫힙니다. (1.4에서는 속성이 data-role=collapsibleset입니다; 구형 collapsible-set 이름도 동작합니다.) 전체 세트가 통합 테마를 공유합니다.

jquery-mobile
<div data-role="collapsibleset" data-theme="a" data-content-theme="a">
  <div data-role="collapsible">
    <h3>Section 1</h3>
    <p>Only one section open at a time.</p>
  </div>
  <div data-role="collapsible" data-collapsed="false">
    <h3>Section 2 (open by default)</h3>
    <p>Opening this closes Section 1.</p>
  </div>
  <div data-role="collapsible">
    <h3>Section 3</h3>
    <p>Third section.</p>
  </div>
</div>

미리 펼침 & 인셋

collapsibleset에서 처음 열리길 원하는 섹션에는 data-collapsed=false를 설정하세요. data-inset=true(세트의 기본값)가 그룹에 둥근 모서리와 마진을 줍니다. 끝까지 이어지는 세트에는 전체 너비를 차지하도록 data-inset=false를 쓰세요.

jquery-mobile
<!-- A set always starts with one open by default; control with data-collapsed -->
<div data-role="collapsibleset" data-inset="true">
  <div data-role="collapsible" data-collapsed="false">
    <h3>Open first</h3>
    <p>Content</p>
  </div>
  <div data-role="collapsible">
    <h3>Closed second</h3>
    <p>Content</p>
  </div>
</div>

Listview가 있는 Collapsible

collapsible은 listview를 포함해 어떤 위젯이든 담을 수 있습니다. 긴 리스트를 collapsible 헤더 아래 그룹화하기 좋은 패턴입니다. collapsible에 data-filter=true를 추가하면 헤더 영역 안의 검색 상자로 안쪽 listview의 항목을 필터링합니다.

jquery-mobile
<div data-role="collapsible" data-filter="true">
  <h3>Contacts</h3>
  <ul data-role="listview">
    <li><a href="#">Alice</a></li>
    <li><a href="#">Bob</a></li>
    <li><a href="#">Carol</a></li>
  </ul>
</div>

프로그래밍 펼침/접기

코드로 collapsible을 제어하려 .collapsible('expand')와 .collapsible('collapse')를 쓰세요. 사용자 토글에 반응하려 'collapse'와 'expand' 이벤트를 listen하세요. 세트에서는 프로그래밍 방식으로 한 섹션을 펼치면 나머지가 자동으로 접힙니다.

jquery-mobile
<div data-role="collapsible" id="c">
  <h3>Section</h3>
  <p>Content</p>
</div>

<script>
// Expand or collapse from code
$("#c").collapsible("expand");
$("#c").collapsible("collapse");
// Toggle based on current state
$("#c h3").click(); // simplest manual toggle
</script>
15

탭

기본 탭

탭 위젯은 탭 링크의 navbar와 링크 href와 일치하는 id를 가진 콘텐츠 패널들을 담은 data-role=tabs div입니다. ui-btn-active를 가진 링크가 먼저 표시됩니다. 탭을 클릭하면 그 패널이 보이고 다른 패널은 숨겨집니다 — 페이지 전환 없음.

jquery-mobile
<div data-role="tabs" id="myTabs">
  <div data-role="navbar">
    <ul>
      <li><a href="#tab1" class="ui-btn-active">One</a></li>
      <li><a href="#tab2">Two</a></li>
      <li><a href="#tab3">Three</a></li>
    </ul>
  </div>
  <div id="tab1" class="ui-body-d ui-content">Content 1</div>
  <div id="tab2" class="ui-body-d ui-content">Content 2</div>
  <div id="tab3" class="ui-body-d ui-content">Content 3</div>
</div>

아이콘 있는 탭

탭 링크에 ui-icon-{name}과 ui-btn-icon-top 클래스를 추가하면 라벨 위에 아이콘이 표시되어 앱 같은 탭 바가 됩니다. 활성 탭은 ui-btn-active를 유지합니다. 탭 스트립에서 아이콘이 텍스트 위에 앉도록 ui-btn-icon-top을 쓰세요.

jquery-mobile
<div data-role="tabs">
  <div data-role="navbar">
    <ul>
      <li><a href="#t1" class="ui-btn-active ui-icon-home ui-btn-icon-top">Home</a></li>
      <li><a href="#t2" class="ui-icon-search ui-btn-icon-top">Search</a></li>
      <li><a href="#t3" class="ui-icon-gear ui-btn-icon-top">Settings</a></li>
    </ul>
  </div>
  <div id="t1" class="ui-content">Home tab</div>
  <div id="t2" class="ui-content">Search tab</div>
  <div id="t3" class="ui-content">Settings tab</div>
</div>

AJAX 탭

탭 링크의 href가 URL(#id가 아님)이면, 탭 위젯이 활성화 시 그 페이지를 AJAX로 컨테이너에 로드합니다. 첫 탭은 페이지 초기화 시 자동 로드됩니다. 무거운 콘텐츠를 탭별로 지연 로드할 때 유용합니다.

jquery-mobile
<div data-role="tabs">
  <div data-role="navbar">
    <ul>
      <li><a href="ajax-tab1.html" class="ui-btn-active">One</a></li>
      <li><a href="ajax-tab2.html">Two</a></li>
    </ul>
  </div>
  <!-- The first tab's content is loaded into this container -->
  <div class="ui-content" id="ajax-content"></div>
</div>

탭 지속성

탭은 기본적으로 리로드 사이에 활성 상태를 기억하지 않습니다. tabsactivate 이벤트(ui.newPanel/ui.oldPanel을 줌)에 localStorage를 결합해 선택을 지속하세요. 로드 시 저장된 탭의 클릭을 다시 트리거해 복원하세요.

jquery-mobile
<div data-role="tabs" id="t">
  <div data-role="navbar">
    <ul>
      <li><a href="#a" class="ui-btn-active">A</a></li>
      <li><a href="#b">B</a></li>
    </ul>
  </div>
  <div id="a" class="ui-content">A</div>
  <div id="b" class="ui-content">B</div>
</div>

<script>
// Remember the active tab across reloads
var saved = localStorage.getItem("activeTab") || "#a";
$("#t a[href='" + saved + "']").click();
$("#t").on("tabsactivate", function (e, ui) {
  localStorage.setItem("activeTab", "#" + ui.newPanel.attr("id"));
});
</script>

탭 이벤트

tabsbeforeactivate는 탭 전환 전에 발생하고(취소하려 false 반환), tabsactivate는 그 후에 발생합니다. 둘 다 ui.newTab/ui.oldTab(<a> 링크)과 ui.newPanel/ui.oldPanel(콘텐츠 div)을 줍니다. 지연 로드, 분석 로그, 전환 전 검증에 쓰세요.

jquery-mobile
<div data-role="tabs" id="t">...</div>

<script>
$("#t").on("tabsbeforeactivate", function (e, ui) {
  // ui.newTab, ui.oldTab, ui.newPanel, ui.oldPanel
  // return false to cancel the switch
  console.log("Switching to", ui.newPanel.attr("id"));
});
$("#t").on("tabsactivate", function (e, ui) {
  console.log("Now showing", ui.newPanel.attr("id"));
});
</script>
16

테마

테마 스와치 (a-e)

jQuery Mobile 테마는 하나의 색이 아니라 문자 스와치(a-e)를 씁니다. a가 가장 대비가 강한(어두운) 것이며 헤더/푸터의 기본이고, b는 파랑 강조, c는 기본 밝은 페이지 배경입니다. 어떤 요소든 data-theme으로 스와치를 적용합니다.

jquery-mobile
<!-- jQuery Mobile ships with 5 swatches: a, b, c, d, e -->
<!-- a = black (high contrast), b = blue, c = light gray,
     d = medium gray, e = yellow -->

<div data-role="page" data-theme="b">
  <div data-role="header" data-theme="a"><h1>Dark header</h1></div>
  <div data-role="main" class="ui-content">Page body</div>
  <div data-role="footer" data-theme="a"><h4>Dark footer</h4></div>
</div>

테마 적용

버튼에는 ui-btn-{swatch} 클래스를 쓰세요(예: 파란 버튼에는 ui-btn-b). 다른 요소에는 data-theme={swatch}를 쓰세요. 명시적으로 설정하지 않으면 자식이 부모의 스와치를 상속합니다. 기본 페이지 스와치는 'c'(밝은 회색)입니다.

jquery-mobile
<!-- Per element -->
<a href="#" class="ui-btn ui-btn-a">Swatch A button</a>
<a href="#" class="ui-btn ui-btn-b">Swatch B button</a>

<!-- On bars, lists, forms -->
<div data-role="header" data-theme="b">...</div>
<ul data-role="listview" data-theme="c">...</ul>
<input type="text" data-theme="b">

오버레이 테마

data-overlay-theme은 팝업, 다이얼로그, 커스텀 select 메뉴 뒤의 어두운 배경색을 정합니다. 전경 콘텐츠가 돋보이도록 오버레이에는 어두운 스와치(a 또는 b)를 쓰세요. 팝업 자체의 data-theme이 팝업 상자 색을 제어합니다.

jquery-mobile
<!-- Overlay theme for popups, dialogs, custom selects -->
<div data-role="popup" id="p" data-overlay-theme="b" data-theme="a"
     class="ui-content">
  <p>Dark backdrop, light popup.</p>
</div>

<a href="#p" data-rel="popup" data-transition="pop" class="ui-btn">Open</a>

리스트 & 버튼 테마

listview는 별개의 테마를 받습니다: 행에는 data-theme, 구분선 헤더에는 data-divider-theme, 카운트 버블에는 data-count-theme. 이로써 행을 은은하게 유지하면서 구분선을 강조할 수 있습니다. 같은 세밀한 테마 적용이 버튼과 폼에도 이뤄집니다.

jquery-mobile
<ul data-role="listview" data-theme="d" data-divider-theme="b"
    data-count-theme="b" data-inset="true">
  <li data-role="list-divider">Group (swatch b)</li>
  <li><a href="#">Item (swatch d) <span class="ui-li-count">5</span></a></li>
</ul>

커스텀 스와치

각 스와치는 CSS 클래스 집합일 뿐입니다(.ui-bar-{x}, .ui-body-{x}, .ui-btn-up-{x} 등). 커스텀 스와치 'f'를 추가하려면 이 규칙들을 복사해 색을 다시 입히거나, ThemeRoller 도구로 완전한 커스텀 테마 파일을 생성하세요. 그런 뒤 data-theme=f로 참조합니다.

jquery-mobile
/* Add a custom swatch 'f' by copying the .ui-bar-f, .ui-body-f,
   .ui-btn-up-f, .ui-btn-hover-f, .ui-btn-down-f rules and changing
   the colors. ThemeRoller generates these for you. */
.ui-bar-f { background: #6c2; color: #fff; }
.ui-body-f { background: #efe; color: #030; }
.ui-btn-up-f { background: #6c2; color: #fff; }
.ui-btn-hover-f { background: #5b1; color: #fff; }

<!-- Use it like any built-in swatch -->
<div data-role="header" data-theme="f"><h1>Green header</h1></div>

테마 상속

요소는 자신의 것을 설정하지 않으면 가장 가까운 조상의 스와치를 상속합니다. 높은 곳(예: 페이지)에 스와치를 설정해 안의 모든 것을 일관되게 테마하고, 필요에 따라 개별 요소를 오버라이드하세요. 전역 기본 페이지 테마는 mobileinit 중 바꿉니다.

jquery-mobile
<div data-role="page" data-theme="b">
  <!-- Inherits swatch b unless overridden -->
  <div data-role="main" class="ui-content">
    <a href="#" class="ui-btn">Inherits b</a>
    <a href="#" class="ui-btn ui-btn-a">Explicit a</a>
    <a href="#" class="ui-btn" data-theme="a">Explicit a (attr)</a>
  </div>
</div>

<!-- Global default swatch -->
<script>
$(document).on("mobileinit", function () {
  $.mobile.page.prototype.options.theme = "b";
});
</script>
17

반응형 레이아웃

그리드 레이아웃

그리드는 위젯이 아니라 CSS 클래스입니다. ui-grid-a가 2열, ui-grid-b가 3열, ui-grid-d(5열)까지입니다. 자식들이 순서대로 ui-block-a, ui-block-b, ...을 받고 자동으로 감깁니다. 그리드는 항상 100% 너비이며 스스로는 브레이크포인트에 반응하지 않습니다.

jquery-mobile
<!-- 2-column grid (ui-grid-a) -->
<div class="ui-grid-a">
  <div class="ui-block-a"><div class="ui-bar">A</div></div>
  <div class="ui-block-b"><div class="ui-bar">B</div></div>
</div>

<!-- 3-column grid (ui-grid-b), 4 = ui-grid-c, 5 = ui-grid-d -->
<div class="ui-grid-b">
  <div class="ui-block-a">A</div>
  <div class="ui-block-b">B</div>
  <div class="ui-block-c">C</div>
</div>

반응형 그리드

jQuery Mobile 그리드에는 내장 브레이크포인트가 없지만 커스텀 미디어 쿼리를 더할 수 있습니다: 좁은 너비에서는 블록을 width:100%와 float:none으로 두어 세로로 쌓고, 넓은 화면에서는 기본 열이 적용되게 하세요. 규칙 스코프에는 마커 클래스를 추가하세요.

jquery-mobile
<style>
/* Stack grid columns on phones, side-by-side on tablets */
@media (max-width: 40em) {
  .ui-responsive .ui-block-a,
  .ui-responsive .ui-block-b { width: 100%; float: none; }
}
</style>

<div class="ui-grid-a ui-responsive">
  <div class="ui-block-a">Left (stacks on phone)</div>
  <div class="ui-block-b">Right (stacks on phone)</div>
</div>

Reflow 테이블

reflow 테이블(data-mode=reflow)은 좁은 화면에서 쌓인 카드 레이아웃으로 재편되며 각 열의 헤더를 값 옆 라벨로 반복합니다. ui-responsive 클래스를 추가하면 브레이크포인트 아래에서만 reflow가 작동해 넓은 화면에서는 일반 테이블이 유지됩니다.

jquery-mobile
<table data-role="table" data-mode="reflow" class="ui-responsive">
  <thead><tr><th>Name</th><th>Age</th><th>City</th></tr></thead>
  <tbody>
    <tr><td>Alice</td><td>30</td><td>NYC</td></tr>
    <tr><td>Bob</td><td>25</td><td>LA</td></tr>
  </tbody>
</table>

<!-- On narrow screens each cell shows its column header as a label -->

열 토글 테이블

columntoggle 테이블은 사용자가 표시할 열을 고를 수 있는 'Columns...' 버튼을 더합니다. 선택적 열에는 data-priority=1..6을 지정하세요(낮을수록 중요, 더 넓은 브레이크포인트에서 표시); 우선순위가 없는 열은 항상 표시됩니다. 가장 중요한 열이 폰에 남고, 나머지는 메뉴에 들어갑니다.

jquery-mobile
<table data-role="table" data-mode="columntoggle"
       class="ui-responsive" id="tbl">
  <thead>
    <tr>
      <th data-priority="1">Rank</th>
      <th data-priority="2">Name</th>
      <th>Team</th>           <!-- priority 'persist' (always shown) -->
      <th data-priority="3">Points</th>
      <th data-priority="4">Wins</th>
    </tr>
  </thead>
  <tbody><tr><td>1</td><td>Alice</td><td>Red</td><td>100</td><td>10</td></tr></tbody>
</table>

브레이크포인트 & 헬퍼 클래스

jQuery Mobile에는 유틸리티 브레이크포인트 클래스가 없으므로 커스텀 레이아웃용 미디어 쿼리를 직접 쓰세요. 내장 40em(640px) 브레이크포인트는 반응형 테이블(ui-responsive)이 쌓임 모드와 표 모드 사이를 바꾸는 시점만 제어합니다. 그리드와 패널에는 em 기반 쿼리로 자신만의 브레이크포인트를 정의하세요.

jquery-mobile
<!-- jQuery Mobile doesn't ship breakpoint classes like Bootstrap,
     but you can combine media queries with jQM structure. -->

<style>
@media (min-width: 45em) { /* tablet+ */
  .split { width: 50%; float: left; box-sizing: border-box; padding: 0 .5em; }
}
</style>

<div class="split">Left panel</div>
<div class="split">Right panel</div>

<!-- ui-responsive class triggers table breakpoints at 40em (640px) -->
18

터치 이벤트

Tap & Taphold

tap은 빠른 터치에서 발생합니다(모바일의 ~300ms 기다리는 click보다 빠르고 신뢰적). taphold는 사용자가 손가락을 약 750ms 동안 누르고 있을 때 발생합니다. 둘 다 마우스와 터치에서 동작하도록 정규화되어 같은 코드가 데스크톱과 모바일에서 실행됩니다.

jquery-mobile
<div id="box" class="ui-bar">Tap or hold me</div>

<script>
$("#box").on("tap", function () {
  $(this).css("background", "yellow");
});
$("#box").on("taphold", function () {
  $(this).css("background", "red");
});
</script>

Swipe & 방향

swipe는 가로 스와이프에서 발생하고, swipeleft와 swiperight가 방향을 알려줍니다 — 이미지 캐러셀이나 페이지 내비게이션에 편리합니다. 이들은 가로 움직임 기반입니다; 세로 스크롤은 의도적으로 스와이프로 취급되지 않아 일반 페이지 스크롤이 계속 동작합니다.

jquery-mobile
<div id="card" class="ui-bar">Swipe me</div>

<script>
$("#card").on("swipe", function () {
  console.log("Swiped in any direction");
});
$("#card").on("swipeleft", function () {
  $(this).text("Swiped left -> next");
});
$("#card").on("swiperight", function () {
  $(this).text("Swiped right -> prev");
});
</script>

스와이프 임계값

스와이프는 durationThreshold(기본 1000ms) 안에 최소 horizontalDistanceThreshold(기본 30px)를 커버하고, 세로로는 verticalDistanceThreshold 아래에 머물 때만 인식됩니다. 가로 임계값을 올리면 더 긴 스와이프가 필요하고, 내리면 더 민감해집니다. mobileinit 중 설정하세요.

jquery-mobile
<script>
// Globally tune swipe sensitivity (bind before jQM loads)
$(document).on("mobileinit", function () {
  $.event.special.swipe.horizontalDistanceThreshold = 60; // px, default 30
  $.event.special.swipe.durationThreshold = 800;          // ms, default 1000
  $.event.special.swipe.verticalDistanceThreshold = 40;   // px, default 75
});
</script>

<script src="jquery.mobile-1.4.5.min.js"></script>

가상 마우스 이벤트

vmouse* 이벤트는 jQuery Mobile의 통합 마우스/터치/포인터 이벤트입니다 — 손가락이든 마우스든 일관되게 발생합니다. 모바일의 300ms 지연을 피하려 click 대신 vclick을 쓰세요. tap과 swipe가 만들어진 기반 요소들입니다.

jquery-mobile
<script>
// vmouse events unify mouse + touch + pointer
$("#el").on("vmousedown", function () { /* finger down / mouse down */ });
$("#el").on("vmouseup",   function () { /* finger up / mouse up   */ });
$("#el").on("vmousemove", function () { /* drag                    */ });
$("#el").on("vmouseover", function () { /* hover-in (best-effort)  */ });
$("#el").on("vmouseout",  function () { /* hover-out (best-effort) */ });
$("#el").on("vclick",     function () { /* tap/click unified       */ });
</script>

방향 전환

orientationchange는 기기가 회전할 때 발생하며 e.orientation이 'portrait'이나 'landscape'입니다. 이벤트 발생 직후에도 뷰포트 치수가 약간 갱신되므로 레이아웃 의존 코드를 짧은 setTimeout으로 감싸세요. 자이로스코프가 없는 기기의 폴백으로 'resize' 이벤트를 listen하세요.

jquery-mobile
<script>
$(window).on("orientationchange", function (e) {
  // e.orientation is "portrait" or "landscape"
  console.log("Now " + e.orientation);
});

// React after the rotation finishes (layout is settled)
$(window).on("orientationchange", function (e) {
  setTimeout(function () {
    $("body").removeClass("portrait landscape").addClass(e.orientation);
  }, 300);
});
</script>

스크롤 & 스로틀링

scrollstart와 scrollstop은 jQuery Mobile의 스로틀된 스크롤 이벤트입니다(브라우저가 스크롤 핸들러를 네이티브로 스로틀하지만, 이들이 명확한 시작/끝 순간을 줍니다). 요소의 스크롤/줌을 막으려 — 예: 드로잉 캔버스나 지도 — touchmove에 바인딩하고 false를 반환하세요.

jquery-mobile
<script>
// scrollstart / scrollstop are throttled for performance
$(document).on("scrollstart", function () {
  $("#hint").hide();
});
$(document).on("scrollstop", function () {
  $("#hint").show();
});

// Silence touch scroll on a specific element
$("#canvas").on("touchmove", false);
</script>
19

페이지 이벤트 & 라이프사이클

페이지 초기화 이벤트

pagebeforecreate는 jQuery Mobile이 페이지 마크업을 강화하기 전에 발생합니다 — 클래스나 위젯을 주입해 함께 강화되게 하는 최적의 자리입니다. pagecreate는 강화가 완료된 직후 발생합니다 — 이벤트 핸들러 바인딩과 플러그인 초기화에 쓰세요. 각각 페이지당 한 번 발생합니다.

jquery-mobile
<div data-role="page" id="home">
  <div data-role="main" class="ui-content">
    <a href="#second" class="ui-btn">Go to second</a>
  </div>
</div>

<script>
$(document).on("pagebeforecreate", "#home", function () {
  // Before enhancement — good place to add classes/widgets
});
$(document).on("pagecreate", "#home", function () {
  // After enhancement, before show — bind widgets here
  console.log("Home page created");
});
</script>

페이지 표시 & 숨김

pagebeforeshow/pageshow는 페이지가 보이기 전/후에 발생하고, pagebeforehide/pagehide는 숨겨지기 전/후에 발생합니다. 'show' 이벤트는 페이지가 표시될 때마다(한 번만이 아니라) 발생하므로, 페이지로 돌아올 때 동적 데이터를 갱신하는 적합한 자리입니다.

jquery-mobile
<script>
$(document).on("pagebeforeshow", "#home", function () {
  console.log("About to show home");
});
$(document).on("pageshow", "#home", function () {
  console.log("Home shown (transition done)");
});
$(document).on("pagebeforehide", "#home", function () {
  console.log("About to leave home");
});
$(document).on("pagehide", "#home", function () {
  console.log("Home hidden");
});
</script>

페이지 변경 전

pagebeforechange는 어떤 내비게이션보다 먼저 발생하며 이를 가로채거나 리다이렉트하는 자리입니다(취소하려 preventDefault 호출). pagechange는 성공적인 내비게이션 뒤에, pagechangefailed는 대상 페이지 로드가 오류를 냈을 때 발생합니다. 내부(#id)와 AJAX 내비게이션 모두에서 발생합니다.

jquery-mobile
<script>
$(document).on("pagebeforechange", function (e, data) {
  // data.toPage is the target (URL string or jQuery object)
  // data.options has transition, reverse, etc.
  // return false (or e.preventDefault()) to cancel navigation
  if (typeof data.toPage === "string" && data.toPage.indexOf("block") > -1) {
    e.preventDefault();
    alert("Blocked");
  }
});
$(document).on("pagechange", function (e, data) {
  console.log("Navigation completed");
});
$(document).on("pagechangefailed", function (e, data) {
  console.log("Navigation failed");
});
</script>

페이지 컨테이너 로드

pageload는 AJAX로 가져온 페이지가 성공적으로 DOM에 삽입됐을 때 발생합니다(data.url과 data.page가 제공됨). pageloadfailed는 로드 오류 시 발생합니다 — 기본적으로 jQM이 오류 메시지를 보여주며, 핸들러에서 false를 반환하면 직접 처리했다고 알리는 것입니다.

jquery-mobile
<script>
// Fires when a page is loaded via AJAX into the DOM
$(document).on("pageload", function (e, data) {
  console.log("Loaded: " + data.url);
  console.log("Page obj:", data.page);
});
$(document).on("pageloadfailed", function (e, data) {
  // return false to let jQM show its default error message
  console.log("Failed to load: " + data.url);
});
</script>

페이지 이벤트 바인딩

페이지 이벤트는 document에서 이벤트 위임으로 바인딩하고 페이지의 #id 선택자로 필터하세요 — 나중에 AJAX로 들어온 페이지에서도 동작합니다. 프로그래밍 방식 내비게이션에는 pagecontainer 위젯의 'change' 메서드($.mobile.changePage의 현대적 대체)를 쓰고 대상과 옵션을 전달하세요.

jquery-mobile
<script>
// Delegate by page id — works for AJAX-loaded pages too
$(document).on("pagecreate", "#settings", function () {
  var page = $(this);
  page.find("#save").on("tap", function () {
    alert("Saved settings");
  });
});

// Use the pagecontainer widget (1.4+) for programmatic navigation
$(":mobile-pagecontainer").pagecontainer("change", "#settings", {
  transition: "slide",
  reverse: false
});
</script>

페이지 제거 & 정리

기본적으로 jQuery Mobile은 다른 곳으로 이동하면 페이지를 DOM에서 제거합니다(domCache가 켜져 있지 않다면). pageremove는 제거 직전에 발생합니다 — 인터벌, 리스너, 플러그인 인스턴스를 여기서 정리하세요. pagehide 이벤트의 ui.prevPage가 방금 숨겨진 페이지의 jQuery 객체를 줘 해체에 쓸 수 있습니다.

jquery-mobile
<script>
// Fires when a page is removed from the DOM (default behavior for
// non-cached pages after navigation away)
$(document).on("pageremove", function (e, ui) {
  console.log("Page removed from DOM:", ui.prevPage);
});

// Clean up resources when a page is hidden for good
$(document).on("pagehide", "#temp", function () {
  clearInterval($(this).data("timer"));
});
</script>

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.