Web 확장
Web 확장은 달빛약속 코드에서 웹 브라우저의 HTML 요소를 생성하고 조작할 수 있게 해주는 확장입니다. 버튼, 텍스트, 입력칸 등의 UI 요소를 약속 코드로 직접 만들고, 이벤트를 구독할 수 있습니다.
Web 확장은 브라우저 환경에서만 사용할 수 있습니다. Node.js나 Deno
환경에서는 사용할 수 없습니다. :::
설치 및 설정
Web 확장은 web/ 디렉토리에 포함되어 있으며, 브라우저 프로젝트에서 직접 가져와 사용합니다.
import { YaksokSession } from '@dalbit-yaksok/core'
import { WebExtension } from './web-extension'
const session = new YaksokSession()
const webExtension = new WebExtension()
webExtension.bindSession(session)
await session.extend(webExtension)Web 확장은 id="app"인 HTML 요소를 자동으로 찾아 UI 요소를 추가합니다. 해당 요소가 없으면 새로 생성하여 document.body에 추가합니다.
사용 가능한 함수
제목 그리기
화면에 <h1> 제목 요소를 추가합니다.
@web-std 제목 ("내 앱") 그리기텍스트 그리기
화면에 텍스트(<p>) 요소를 추가합니다. 반환된 값을 변수에 저장하면 나중에 내용을 변경할 수 있습니다.
@web-std 내_텍스트 = 텍스트 ("안녕하세요") 그리기화면에 그리기
간단한 텍스트를 화면에 출력합니다.
@web-std ("결과: " + 값) 화면에 그리기버튼 그리기
클릭 가능한 버튼을 추가합니다. 이벤트 구독과 함께 사용합니다.
@web-std 내_버튼 = 버튼 ("클릭하세요") 그리기문자 입력칸 / 숫자 입력칸 그리기
사용자 입력을 받을 수 있는 입력칸을 추가합니다. 입력칸은 값 속성을 통해 현재 입력된 값을 읽을 수 있습니다.
@web-std 이름_입력 = 문자 입력칸 ("이름을 입력하세요") 그리기
@web-std 나이_입력 = 숫자 입력칸 ("나이를 입력하세요") 그리기
# 입력된 값 읽기
이름_입력.값 보여주기박스 그리기
다른 요소를 담을 수 있는 컨테이너(<div>) 요소를 추가합니다.
@web-std 내_박스 = 박스 그리기요소에 넣기
한 요소를 다른 요소(박스) 안에 넣습니다.
@web-std 내_박스 = 박스 그리기
@web-std 내_버튼 = 버튼 ("클릭") 그리기
@web-std (내_박스)에 (내_버튼) 넣기요소에 내용 그리기
텍스트 요소의 내용을 변경합니다.
@web-std 내_텍스트 = 텍스트 ("기존 내용") 그리기
@web-std (내_텍스트)에 ("새로운 내용") 그리기요소 비우기
입력칸의 내용을 비웁니다.
@web-std (이름_입력) 비우기요소 지우기
화면에서 요소를 제거합니다.
@web-std (내_버튼) 지우기이벤트 구독
Web 확장은 눌렀을 때 이벤트를 지원합니다. 버튼, 텍스트, 박스 등의 요소에 클릭 이벤트를 구독할 수 있습니다.
@web-std 내_버튼 = 버튼 ("인사하기") 그리기
내_버튼.눌렀을 때
@web-std ("안녕하세요!") 화면에 그리기눌렀을 때 블록 안에서는 자신 키워드로 이벤트가 발생한 요소에 접근할 수 있습니다.
전체 예제
아래는 이름을 입력받아 인사하는 간단한 웹 앱 예제입니다.
@web-std 제목 ("인사 앱") 그리기
@web-std 이름_입력 = 문자 입력칸 ("이름을 입력하세요") 그리기
@web-std 인사_버튼 = 버튼 ("인사하기") 그리기
@web-std 결과 = 텍스트 ("") 그리기
인사_버튼.눌렀을 때
@web-std (결과)에 ("안녕하세요, " + 이름_입력.값 + "님!") 그리기기술 세부 사항
이벤트 콜백 구조
눌렀을 때 이벤트는 내부적으로 session.eventCreation의 PubSub 시스템을 통해 동작합니다. 콜백 함수는 세 개의 인자를 받습니다:
args: 약속 스크립트에서 전달된 매개변수들callback(): 약속 스크립트의 이벤트 핸들러 실행을 재개하기 위해 반드시 호출해야 합니다terminate(): 이벤트 리스너를 해제하고 싶을 때 호출합니다
입력칸의 래퍼(Wrapper) 동작
입력칸(문자 입력칸, 숫자 입력칸)을 생성하면 내부적으로 <input> 요소가 부모 블록 요소로 감싸져 생성됩니다. 이 래퍼는 다음과 같은 동작에 영향을 줍니다:
요소에 넣기: 입력칸을 다른 요소에 넣으면,<input>자체가 아닌 래퍼 블록 전체가 이동됩니다요소 지우기: 입력칸을 지우면 래퍼 블록이 함께 제거됩니다요소 비우기: 입력칸의value를 빈 문자열로 초기화합니다
반환되는 값 타입
Web 확장의 각 생성 함수는 InstanceValue를 상속받는 전용 값 타입을 반환합니다:
| 함수 | 반환 타입 | 설명 |
|---|---|---|
버튼 그리기 | HTMLButtonValue | 클릭 이벤트 구독 가능 |
텍스트 그리기 | HTMLTextValue | 내용 변경 가능 |
문자 입력칸 그리기 | HTMLInputValue | .값으로 입력값 접근 |
숫자 입력칸 그리기 | HTMLInputValue | .값으로 입력값 접근 (숫자 타입) |
박스 그리기 | HTMLBoxValue | 다른 요소를 담는 컨테이너 |
입력칸의 값 속성은 사용자가 입력할 때마다 자동으로 갱신됩니다. 약속 코드에서 입력칸.값으로 접근하면 항상 최신 입력값을 읽을 수 있습니다.