본문으로 건너뛰기

WebView (웹뷰) Widget Control

WebView(웹뷰) 위젯을 스크립트에서 제어할 때 사용하는 Widget Control(Property · Method · Event) 목록입니다. 위젯 소개와 사용법은 WebView 문서를 참고하세요.

정보

아래 예시의 webviewID는 캔버스에서 WebView 위젯에 지정한 이름(ID)입니다. 스크립트에서는 위젯ID.멤버 형태로 접근합니다.

Widget Control 요약​

Widget Control종류시그니처설명
valuePropertywebviewID.valueWebView가 로드하는 콘텐츠(URL·에셋 경로·HTML 데이터). 읽기/쓰기, 문자열
userAgentPropertywebviewID.userAgent기본 User-Agent 뒤에 덧붙이는 커스텀 User-Agent. 읽기/쓰기, 문자열
embedInParentScrollPropertywebviewID.embedInParentScroll트랙패드/휠 스크롤을 부모 스크롤 뷰로 전달할지 여부(macOS 전용). 읽기/쓰기, 불리언
setValueMethodwebviewID.setValue(s)로드할 콘텐츠를 설정. value 대입과 동일
runJavaScriptMethodwebviewID.runJavaScript(funcName, args, callback)로드된 페이지에서 JavaScript를 실행
asyncRunJavaScriptMethodwebviewID.asyncRunJavaScript(funcName, args, callback)JavaScript를 비동기로 실행하고 결과를 대기
sendDataToWebMethodwebviewID.sendDataToWeb(funcName, args, callback)페이지의 JavaScript 함수를 이름으로 호출하며 데이터를 전달
onReceiveDataMethodwebviewID.onReceiveData(callback)페이지가 호스트로 밀어 보낸 데이터를 받는 콜백을 등록
addJavaScriptHandlerMethodwebviewID.addJavaScriptHandler(handlerName, callback)페이지가 이름으로 호출할 수 있는 JavaScript 핸들러를 등록
isCreatedNewWindowMethodwebviewID.isCreatedNewWindow(result)링크를 새 창으로 열도록 허용할지 설정
injectGlowMethodwebviewID.injectGlow(json)로드된 페이지 위에 애니메이션 글로우 효과를 덧씌움
removeGlowMethodwebviewID.removeGlow()injectGlow로 추가한 글로우 효과를 제거
onFinishedEventwebviewID.onFinished = (value) => { ... }현재 페이지 로딩이 끝났을 때 실행
onShouldOverrideUrlEventwebviewID.onShouldOverrideUrl = (value) => { ... }페이지가 hybrid:// 브리지로 호스트에 메시지를 보낼 때 실행

Property​

value​

WebView가 로드하는 콘텐츠입니다. 위젯의 타입(URL·에셋 경로·인라인 HTML)에 따라 해석되며, 값을 대입하면 새 콘텐츠로 다시 로드합니다.

  • 종류: Property (읽기/쓰기)
  • 타입: 문자열
  • Returns(get): 현재 로드 중인 콘텐츠 문자열

Example

webviewID.value = "https://example.com";
let current = webviewID.value;

userAgent​

기본 User-Agent 문자열 뒤에 덧붙이는 커스텀 User-Agent입니다.

  • 종류: Property (읽기/쓰기)
  • 타입: 문자열
  • Returns(get): 덧붙인 커스텀 User-Agent 문자열

Example

webviewID.userAgent = "MyApp/1.0";

embedInParentScroll​

WebView 위에서 발생한 트랙패드/마우스 휠 스크롤을 부모 스크롤 뷰로 전달할지 여부입니다(macOS 전용). WebView가 생성된 뒤 true로 설정하면 즉시 반영되며, 다른 플랫폼에서는 무시됩니다.

  • 종류: Property (읽기/쓰기)
  • 타입: 불리언
  • Returns(get): 부모 스크롤 전달 여부(불리언). 기본값 false

Example

webviewID.embedInParentScroll = true;

Method​

setValue​

WebView가 로드할 콘텐츠를 설정합니다. value 속성에 대입하는 것과 동일하며, 문자열은 위젯의 타입(URL·에셋 경로·HTML 데이터)에 따라 해석됩니다.

  • Parameters
    • s (문자열): 로드할 콘텐츠 (URL·에셋 경로·HTML 데이터)
  • Returns: 없음

Example

webviewID.setValue("https://example.com");

runJavaScript​

로드된 페이지에서 JavaScript를 실행합니다. funcName(args) 형태로 호출되며(args는 JSON으로 인코딩), args가 비어 있거나 생략되면 funcName을 그대로 평가합니다(원시 표현식 전달 가능). 페이지 로딩이 끝나지 않았다면 호출은 큐에 쌓였다가 페이지 준비 후 실행됩니다.

  • Parameters
    • funcName (문자열): 실행할 JavaScript 함수 이름 또는 표현식
    • args: 함수에 전달할 인자 (JSON 인코딩)
    • callback (선택): 결과 {success, data, error}를 받는 콜백
  • Returns: 없음 (결과는 callback으로 전달)

Example

webviewID.runJavaScript("window.someFunction", { value: 100 }, function() {});

asyncRunJavaScript​

JavaScript를 비동기로 실행하고 결과를 대기합니다. args가 주어지면 funcName을 반환값을 대기하는 함수 본문으로 취급하고, 그렇지 않으면 funcName을 표현식으로 평가합니다. 페이지 로딩이 끝나지 않았다면 호출은 큐에 쌓였다가 페이지 준비 후 실행됩니다.

  • Parameters
    • funcName (문자열): JavaScript 함수 본문 또는 표현식
    • args: 함수 본문에서 사용할 인자
    • callback (선택): 결과 {success, data, error}를 받는 콜백
  • Returns: 없음 (결과는 callback으로 전달)

Example

webviewID.asyncRunJavaScript("myFunc(param);", { "param": data });

sendDataToWeb​

로드된 페이지의 JavaScript 함수를 호출하며 args를 인자로 전달합니다. funcName(args) 형태로 호출되며(args는 JSON 인코딩), 비어 있거나 생략된 맵을 넘기면 funcName을 그대로 평가합니다. 페이지 로딩이 끝나지 않았다면 호출은 큐에 쌓였다가 페이지 준비 후 실행됩니다.

  • Parameters
    • funcName (문자열): 호출할 JavaScript 함수 이름
    • args: 함수에 전달할 인자 (JSON 인코딩)
    • callback (선택): 결과 {success, data, error}를 받는 콜백
  • Returns: 없음 (비동기로 완료, 결과는 callback으로 전달)

Example

webviewID.sendDataToWeb("window.someFunction", data, function() {});

onReceiveData​

로드된 페이지가 호스트로 밀어 보낸 데이터를 받는 콜백을 등록합니다. 콜백은 메시지 페이로드를 인자로 받아 호출됩니다.

  • Parameters
    • callback: 페이지가 보낸 데이터를 인자로 받는 함수
  • Returns: 없음

Example

webviewID.onReceiveData((data) => {
  // data = 페이지가 밀어 보낸 페이로드
});

addJavaScriptHandler​

로드된 페이지가 이름으로 호출할 수 있는(페이지의 호스트 브리지 경유) JavaScript 핸들러를 등록합니다. 페이지 로딩이 끝나지 않았다면 등록은 큐에 쌓였다가 페이지 준비 후 적용됩니다.

  • Parameters
    • handlerName (문자열): 페이지가 이 핸들러를 호출할 때 사용하는 이름
    • callback: 페이지가 넘긴 인자를 받아 호출되는 함수
  • Returns: 없음

Example

webviewID.addJavaScriptHandler("onQuote", (args) => {
  // args = 페이지가 보낸 데이터
});

isCreatedNewWindow​

WebView가 링크를 새 창으로 열도록 허용할지 제어합니다.

  • Parameters
    • result (불리언): 새 창 생성을 허용하면 true, 막으면 false
  • Returns: 없음

Example

webviewID.isCreatedNewWindow(true);

injectGlow​

로드된 페이지 위에 애니메이션 글로우 효과를 덧씌웁니다(Canvas 2D 오버레이로 렌더링). 효과 프리셋 JSON을 문자열로 전달합니다.

  • Parameters
    • json (문자열): 글로우 효과 프리셋 (JSON 문자열)
  • Returns: 없음

Example

webviewID.injectGlow(JSON.stringify({ color: "#FF4CAF50", intensity: 0.8 }));

removeGlow​

injectGlow로 추가한 글로우 효과를 제거합니다.

  • Parameters: 없음
  • Returns: 없음

Example

webviewID.removeGlow();

Event​

onFinished​

현재 페이지의 로딩이 끝났을 때 실행됩니다.

  • 종류: Event
  • 핸들러 인자: value - 로딩이 끝난 페이지의 URL
  • Returns: 없음

Example

webviewID.onFinished = (value) => {
  // value = 로딩이 끝난 URL
};

onShouldOverrideUrl​

로드된 페이지가 hybrid:// URL(페이지→호스트 IPC 브리지)로 호스트에 메시지를 보낼 때 실행됩니다. 호스트가 네비게이션을 가로채 직접 처리할 수 있게 합니다.

  • 종류: Event
  • 핸들러 인자: value - 페이지가 보낸 디코딩된 JSON 페이로드(객체)
  • Returns: 없음

Example

webviewID.onShouldOverrideUrl = (value) => {
  if (value["FunctionName"] == "OnReceiveData") {
    let data = value["Data"];
  }
};

공통 Widget Control (모든 위젯)​

노트

모든 위젯은 setProperty / getProperty / setStyleProperty 같은 이름 기반 공통 Widget Control(Method)을 사용할 수 있습니다. 공통 레퍼런스 문서(작성 예정)를 참고하세요.