핵심 장점
mpvue는 Vuex 기반의 중앙 집중식 상태 관리를 제공하여 복잡한 애플리케이션의 데이터 흐름을 효율적으로 제어할 수 있습니다. 이는 기존 미니프로그램 프레임워크들이 해결하지 못한 고급 상태 관리 패턴을 구현할 수 있게 해줍니다.
프로젝트 구성 방법
# 프로젝트 생성
vue init mpvue/mpvue-quickstart my-app
cd my-app
# 의존성 설치
npm install
# 개발 모드 실행
npm run dev
# 프로덕션 빌드
npm run build
# 플랫폼별 개발 빌드
npm run dev:wx # WeChat
npm run dev:swan # Baidu
npm run dev:tt # Toutiao
npm run dev:my # Alipay
# 플랫폼별 프로덕션 빌드
npm run build:wx
npm run build:swan
npm run build:tt
npm run build:my
# 번들 분석 리포트 생성
npm run build -- --report
라이프사이클 특성
미니프로그램의 페이지 파라미터는 기존 onLoad 메서드를 통해 전달되었지만, mpvue는 이를 개선하여 this.$root.$mp.query를 통한 직접 접근을 지원합니다. 단, 이 속성은 onLoad 라이프사이클 이후에만 접근 가능하므로 주의가 필요합니다.
템플릿 문법 지원 범위
HTML 제한사항
미니프로그램 환경에서는 BOM/DOM API를 사용할 수 없으므로 v-html 디렉티브가 완전히 제한됩니다. 대신 위챗의 rich-text 컴포넌트를 활용해야 합니다.
JS 표현식 제약조건
현재 지원되는 연산자: + - * % ?: ! == === > < [] . 기타 고급 표현식은 컴파일 단계에서 제한됩니다.
필터 기능 미지원
템플릿은 wxml로 변환되는 과정에서 필터 파이프라인이 제거됩니다. 데이터 가공은 computed 속성이나 메서드에서 사전 처리가 필요합니다.
계산된 속성
Vue의 computed 속성이 완전히 지원되어 복잡한 데이터 파생 로직을 선언적으로 구현할 수 있습니다.
템플릿 내 메서드 호출 제한
methods에 정의된 함수를 템플릿에서 직접 호출하는 구문은 지원되지 않습니다. 모든 데이터 처리는 computed 속성이나 데이터 바인딩으로 해결해야 합니다.
Class 및 Style 바인딩
객체 구문의 class 바인딩은 제한적입니다. 문자열이나 배열 구문을 사용하는 것이 안전합니다.
<template>
<!-- 사용 가능 -->
<view class="container" :class="activeClassName"></view>
<view class="container" :class="{highlight: isHighlighted}"></view>
<!-- 사용 불가 -->
<view class="container" :class="classObject"></view>
</template>
<script>
export default {
data() {
return {
isHighlighted: true
}
},
computed: {
activeClassName() {
return this.isHighlighted ? 'highlight' : ''
},
classObject() {
return { highlight: this.isHighlighted } // 비권장 패턴
}
}
}
</script>
컴포넌트 스타일 바인딩
컴포넌트 노드에 직접 class나 style을 바인딩하는 것은 현재 지원되지 않습니다. 스타일은 반드시 컴포넌트 내부 최상위 요소에 적용해야 합니다.
조건부 렌더링
v-if, v-else-if, v-else가 완전 지원되어 조건에 따른 노드 제어가 가능합니다.
목록 렌더링
v-for 디렉티브가 지원되나, 중첩된 반복문에서는 각각 고유한 인덱스 키를 반드시 지정해야 합니다.
이벤트 처리기
대부분의 Vue 이벤트 문법이 지원되지만, 플랫폼 특성상 주의사항이 존재합니다.
폼 컨트롤 이벤트 변환
input과 textarea의 change 이벤트는 내부적으로 blur 이벤트로 변환됩니다.
이벤트 수식어 주의점
.stop: 이벤트 전파는 차단하나, 버블링이 아닌 이벤트와 함께 사용 시catchEventName이 무효화될 수 있습니다..prevent: 미니프로그램에는 기본 동작 개념이 없으므로 사용이 무의미합니다..capture: 1.0.9 버전부터 지원됩니다..self: 식별 가능한 마커가 없어 구현이 불가능합니다..once:removeEventListener미지원으로 인해 구현되지 않았습니다.
폼 컨트롤 양방향 바인딩
대부분의 폼 요소가 지원되지만, 네이티브 컴포넌트 매핑이 필요합니다.
select→picker컴포넌트로 대체radio→radio-group컴포넌트로 대체
컴포넌트 시스템
Vue 컴포넌트 제약사항
단일 파일 컴포넌트(.vue)만 사용 가능하며, 다음 기능들은 지원되지 않습니다:
- 동적 컴포넌트 & 비동기 컴포넌트
- 인라인 템플릿 & X-템플릿
- keep-alive, transition
- 슬롯의 scoped 슬롯
- 컴포넌트 노드의 네이티브 이벤트 바인딩
네이티브 컴포넌트 통합
미니프로그램의 기본 컴포넌트를 그대로 사용할 수 있으며, 이벤트 바인딩만 Vue 문법으로 변경하면 됩니다.
<!-- 네이티브 문법 -->
<picker bindchange="onPickerChange"></picker>
<!-- mpvue 문법 -->
<picker @change="handlePickerUpdate"></picker>
성능 최적화 전략
데이터 구조 최소화
데이터 객체는 setData를 통해 직렬화되어 전송되므로, 불필요한 중첩과 대용량 데이터는 제거해야 합니다.
대량 목록 렌더링 개선
- v-for 내부에 하위 컴포넌트를 중첩하지 않습니다.
- 숨김 처리 시
wx:if대신 CSSdisplay속성을 고려합니다. - 100개 이상의 목록은 가상 스크롤이나 페이지네이션을 구현합니다.
양방향 바인딩 최적화
v-model.lazy 수식어를 사용하여 입력 이벤트 빈도를 제한하고 불필요한 업데이트를 방지합니다.
API 추상화 계층
플랫폼별 API 차이를 직접 호출하기보다는 어댑터 패턴을 적용한 유틸리티 레이어를 구축하는 것이 유지보수에 유리합니다.
자주 묻는 질문
페이지 진입 파라미터 접근
모든 페이지 컴포넌트에서 this.$root.$mp.query로 접근 가능합니다.
앱 전역 파라미터 접근
this.$root.$mp.appOptions를 통해 앱 실행 시 전달된 옵션을 확인할 수 있습니다.
앱 수준 오류 처리
루트 컴포넌트에 onError 콜백을 정의하여 전역 오류를 캡처합니다.
export default {
onAppLaunch() {
// 앱 초기화
},
onError(exception) {
console.error('전역 오류:', exception)
// 오류 추적 서비스 전송 로직
}
}
라우터 라이브러리 사용 가능 여부
미니프로그램의 페이지 스택 관리 방식상 vue-router 구현이 기술적으로 불가능합니다. 대신 mpvue.navigateTo와 mpvue.switchTab을 활용한 네비게이션 유틸리티를 구현합니다.
methods: {
routeTo(path) {
const currentPlatform = mpvuePlatform
if (currentPlatform === 'wx') {
mpvue.switchTab({ url: path })
} else {
mpvue.navigateTo({ url: path })
}
}
}
신규 페이지 반영 안 됨
webpack 엔트리 설정에 자동으로 추가되지 않으므로, 페이지 생성 후 npm run dev를 재실행해야 합니다.
서드파티 UI 라이브러리 통합
DOM/BOM API 의존성을 제거하고 미지원 Vue 기능을 제거한 후, 미니프로그램 호환 CSS 선택기로 수정하면 사용 가능합니다.
echarts 등 네이티브 컴포넌트 사용
미니프로그램의 네이티브 컴포넌트는 모두 지원되며, mpvue의 라이프사이클 내에서 정상 동작합니다.
예약어 컴포넌트 명칭
다음은 컴포넌트 이름으로 사용할 수 없는 예약어입니다:
// 기본 요소
div, span, view, text, image, img, input, textarea
// 레이아웃
header, content, cell, scroller, scrollable, list
// 특수 컴포넌트
canvas, svg, video, web, embed, switch, slider
// 템플릿
template, slot, script, style
// 기타
a, link, meta, indicator, marquee, richtext, refresh, loading