API 레퍼런스

공개 API는 types/vfunc.d.ts에 선언된 것이 전부입니다. _로 시작하는 멤버는 내부용입니다. vf의 공식 멤버는 읽기 전용입니다.

컴포넌트

vf.vfunc(options)

컴포넌트를 만듭니다(new 선택). 옵션:

인스턴스: $node, state, methods, ids, refs, setState(patch | (state) => patch)(얕은 병합, 한 tick에 한 번 렌더), scheduleRefresh(), refresh(), mount(parent) → Promise, destroy(), toString(). ids·refs는 루트 안쪽 요소만 담습니다(루트 밖은 vf.$). destroy()는 childs의 인스턴스를 먼저 destroy합니다. 예약어(state, refresh, mount 등과 _로 시작하는 이름)는 상태 키·메서드·id의 바로 접근 이름으로 쓸 수 없습니다. 인스턴스에 직접 속성을 붙이지 말고, 리스너 함수와 타이머는 클로저에 둡니다.

vf.attach(target, options)

이미 페이지에 있는 요소를 컴포넌트로 만듭니다. 옵션은 vf.vfunc와 같습니다. 그 요소가 루트가 되고 속성과 리스너가 유지됩니다. render가 없으면 마크업과 입력값도 그대로입니다. render가 있으면 요소의 안쪽만 돌려줍니다. 요소 자신의 태그 안으로 파싱하므로 <tbody>에 바로 행을 그릴 수 있습니다. 상태에 따라 바뀌는 루트 속성은 onMount/onUpdate에서 설정합니다. replaceRoot: true면 마크업의 첫 요소가 요소를 대체합니다. 대상이 없으면 null. destroy()는 요소를 페이지에 남기고 리스너를 해제하며, render/innerHTML로 그린 안쪽만 지웁니다. 같은 요소에 다시 attach할 수 있습니다.

안전한 HTML

vf.html

태그 템플릿. 값이 들어가는 위치에 맞게 이스케이프하고, 위험한 위치(on*, <script>, 따옴표 없는 속성)는 거부합니다. 따옴표 속성 안에서 null, undefined는 빈 값, 배열은 공백으로 이어 붙이고, false도 빈 값입니다. 다만 aria-*, data-*에서는 boolean이 "true"/"false"로 남습니다(aria-selected="${on}"). SafeHtml을 반환합니다. ES5에서는 vf.html(['<b>', '</b>'], value)처럼 함수로도 부릅니다.

vf.tpl(template, data)

템플릿 리터럴 없이 {key}, {user.name}을 data의 자기 속성에서 채웁니다. vf.html과 같은 보호.

vf.unsafeHtml(markup)

이스케이프하지 않을 마크업으로 표시합니다. 직접 작성한 마크업에만, 이유를 주석으로 남기고 씁니다.

vf.esc(value)

& < > " '를 이스케이프한 문자열.

vf.nl2br(value)

이스케이프 후 줄바꿈을 <br>로 바꾼 SafeHtml.

vf.safeUrl(url)

상대 경로와 http·https·mailto·tel만 통과시키고, 그 밖의 스킴은 '#'로 바꿉니다.

vf.SafeHtml

vf.html 결과를 확인하는 생성자(value instanceof vf.SafeHtml).

vf.config(options)

{ strict, strictRender }. strict: true면 위험한 보간에서 예외를 던집니다. strictRender는 개발 빌드에서 render가 일반 문자열을 반환하면 경고합니다.

DOM과 폼

vf.$(selector, root?)

querySelector.

vf.$$(selector, root?)

querySelectorAll을 배열로.

vf.el(tag, props?)

요소를 만들고 opts와 같은 안전 규칙으로 속성을 넣습니다.

vf.node(markup)

마크업의 첫 요소. 마크업은 그대로 신뢰합니다. <div> 안에서 파싱하므로 표의 행에는 쓰지 않습니다.

vf.frag(markup)

모든 최상위 노드를 담은 DocumentFragment.

vf.idMap(root)

하위 요소의 { id: element }.

vf.form

vf.form.values(target, { skipPassword? })는 { id: value }(체크박스는 boolean, 다중 select는 배열), vf.form.reset(target)은 값을 비우고 결과를 돌려줍니다.

SPA

vf.router(options)

{ mode: 'hash' | 'history', base, routes, notFound, onChange, linkSelector, focus } → start(), stop(), go(path, { replace }), replace(path), current(), href(path). /로 시작하는 앱 경로만 따릅니다.

vf.store(initial)

get(key?)(키가 없으면 전체 상태), set(patch | (state) => patch)(얕은 병합: 다른 키는 유지, tick당 한 번 알림), subscribe(fn)(새 상태를 받음) → 해제 함수.

다국어

vf.i18n

setup({ locale, fallback, locales, messages, load, persist }) → Promise<locale>, set(locale), locale(), add(locale, messages, { defaults }?), subscribe(fn), apply(root?). set은 메시지를 불러온 뒤 구독자를 부르고 로케일로 resolve합니다. add(…, { defaults: true })는 컴포넌트의 내장 기본 메시지를 넣습니다. 넣는 순서와 관계없이 앱 메시지가 이기고, 그 로케일을 "불러옴"으로 세지 않아 load가 그대로 호출됩니다.

vf.t(key, params?)

메시지를 평문으로. {name} 치환, params.count로 복수형 선택. vf.t('nav.home')은 { "nav": { "home": "…" } }와 { "nav.home": "…" }를 모두 찾습니다.

vf.fmt

number(n, opts), currency(n, code, opts), date(d, opts), relative(n, unit). 현재 로케일의 Intl을 쓰고, 없으면 단순 문자열.

확장

vf.use(plugin, options?)

{ name, version?, requires?, install(vf, options) }를 설치하고 install의 반환값을 vf.ext[name]에 둡니다.

vf.ext

설치된 확장. 사용자 확장은 여기에만 둡니다.

vf.version

빌드 버전(예: 1.2.0). 소스를 직접 불러오면 0.0.0-dev.

공식 플러그인

vfunc/plugins/update(dist/plugins/update.min.js → 전역 vfUpdate): vf.use(vfUpdate, { url, current, policy, interval, minGap, onAvailable, onError }) → check(force), status(), navigated(), apply(), stop(). 확장을 보세요.

vfunc/plugins/shortcut(dist/plugins/shortcut.min.js → 전역 vfShortcut): vf.use(vfShortcut, { target, apple }) → add(combo, handler, { label, allowInInput, preventDefault })(해제 함수를 돌려줌), remove(combo, handler?), list(), parse(combo), destroy(). 확장을 보세요.

vfunc/plugins/list(dist/plugins/list.min.js → 전역 vfList, 1.1.0부터): vf.use(vfList) → create(container, { key, render, items }) → set(items), refresh(key?), items(), element(key), destroy(). 컨테이너를 찾지 못하면 null. 확장을 보세요.