[]
데모 테마 디자이너 도움말 API
다른 샘플 다운로드
(Showing Draft Content)

WebComponents (beta)

이 항목에서는 Wijmo 컨트롤을 WebComponents로 표시하는 Wijmo WebComponents v1 interop의 베타 버전을 소개합니다. Wijmo 웹 컴포넌트는 HTML 페이지에 Wijmo 컨트롤을 선언적으로 추가하고, 추가 프레임워크를 사용하지 않고 일반적인 DOM 요소처럼 조작할 수 있도록 해줍니다. 여전히 WebComponents 표준을 완전히 지원하지 않는 일부 브라우저에는 일부 추가 폴리필(polyfills)이 필요할 수 있습니다.


만약 여러분이 WebComponents에 익숙하지 않다면, 해당 정보를 통해 해당 기술에 대해서 확인할 수 있습니다.


현재 Wijmo WebComponents 구현 상태의 주요 측면은 아래와 같습니다:

  1. FlexGrid 컨트롤을 나타내는 wjc-flex-grid 컴포넌트와 같이 Wijmo 컨트롤을 나타내는 Wijmo "최상위" 웹 컴포넌트는 해당 컨트롤 클래스에서 상속됩니다. 예를 들어, WjcFlexGrid 구성 요소 클래스는 FlexGrid 컨트롤 클래스를 확장합니다.


    이는 또한 "WebComponents mode"에서 Wijmo가 사용될 때 기본 Wijmo Control 클래스가 HTMLElement 클래스를 확장함을 의미합니다 .

  2. FlexGrid 열을 정의하는 wjc-flex-grid-column 컴포넌트와 같이 최상위 컴포넌트를 보완하는 하위 컴포넌트는 해당 컴포넌트가 나타내는 Wijmo 클래스에 대한 래퍼(wrapper) 역할을 합니다. 자식 컴포넌트는 HTMLElement 클래스에서 직접 상속되며, 기본 Wijmo 클래스 인스턴스는 컴포넌트의 특수 컨트롤 속성을 통해 액세스할 수 있습니다 .

  1. 컴포넌트 요소의 속성을 사용하여 Wijmo 클래스 특성을 정의할 수 있습니다. 속성 값이 변경되면 해당 Wijmo 클래스 속성이 그에 따라 업데이트됩니다. 클래스 속성 값을 변경한다고 해서 해당 속성 값이 변경되는 것은 아닙니다. 이것은 아마도 미래에 변경될 수 있지만, 현재 우리는 그것이 필요한지에 대한 결정이 없습니다.

  1. JavaScript 코드는 네이티브 Element.addEventListener ( 'event', handler) 메소드를 사용하여 Wijmo 제어 이벤트에 핸들러를 등록할 수 있습니다.

  1. Wijmo 컴포넌트는 이제 Shadow DOM을 사용하지 않습니다. 이 문제는 이후 버전의 interop에서 해결 될 것입니다. 여기서 과제 중 하나는 Wijmo가 CSS를 통해 컨트롤의 여러 부분을 깊게 사용자 정의할 수 있는 반면, Shadow DOM의 목표는 이를 방지하는 것입니다. 이러한 제한을 완화할 수있는 Shadow DOM 사양에 대한 새로운 제안이 있습니다. 우리는 변경 사항을 계속 추적합니다. 현재 Wijmo 웹 컴포넌트 및 해당 부분은 전역 CSS를 사용하여 일반 Wijmo 컨트롤과 동일한 방식으로 사용자 지정할 수 있습니다.

Wijmo 웹 컴포넌트 interop를 사용하면 다음 예제와 같이 선언적으로 HTML 마크업에 컨트롤을 추가 할 수 있습니다:

<label>InputNumber</label>
<wjc-input-number value="5" step="3"></wjc-input-number>
<label>FlexGrid with Filter and specific columns</label>
<wjc-flex-grid id="gridIntro">
  <wjc-flex-grid-filter></wjc-flex-grid-filter>
  <wjc-flex-grid-column binding="country" header="Country" width="*">
  </wjc-flex-grid-column>
  <wjc-flex-grid-column binding="date" header="Date"> </wjc-flex-grid-column>
  <wjc-flex-grid-column binding="downloads" header="Downloads">
  </wjc-flex-grid-column>
</wjc-flex-grid>
let gridIntro = document.getElementById("gridIntro");
gridIntro.itemsSource = dataSvc.getData(100);

설정(Setup)

이 샘플은 npm 모듈을 기반으로하며 SystemJS 런타임 모듈 로더 또는 Webpack 번들러를 사용하여 실행되도록 구성되어 있습니다.


WebComponents 기반 애플리케이션 구성의 주요 측면은 다음과 같습니다.

  1. NodeJS 명령 프롬프트에서 최신 Wijmo Nightly 빌드를 설치하십시오.

    > npm install @mescius/wijmo.webcomponents.all@nightly --save

  2. WebComponents 폴리필(polyfills) 설치:

    > npm install @webcomponents/webcomponentsjs --save

    루트 (default.htm) 페이지에 추가하십시오.


    이 polyfill은 웹 컴포넌트를 ES5 코드로 사용하여 애플리케이션을 실행하는 경우에만 필요합니다:

    <script src="node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>

    이 폴리필(polyfills)은 Chrome을 제외한 모든 브라우저에 필요합니다.

    <script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-lite.js"></script>

  3. 루트 html 페이지에서 다음 지정을 사용하여 Wijmo "WebComponents mode"를 사용으로 설정하십시오. Wijmo 모듈을 로드하기 전에 수행해야합니다.

    <script>
  window["wj-control-is-element"] = true;
</script>

    이 할당으로 인해 기본 Wijmo Control 클래스가 정상적으로 Object 클래스 대신 HTMLlement 클래스를 확장하게 됩니다.

  4. ES6/TypeScript 코드에서 필요한 Wijmo WebComponents interop 모듈 가져 오기:

    import "@mescius/wijmo.webcomponents.input";
import "@mescius/wijmo.webcomponents.grid";

    이러한 import는 모듈이 window.customElements.define (…) 메소드를 사용하여 웹 컴포넌트를 포함하는 전역으로 등록하게 합니다.

  5. (이 샘플에는 적용되지 않습니다!) Wijmo WebComponents interop를 전역 모듈로 사용하려면 Wijmo 다운로드 zip의 dist/interop /webcomponents 폴더에 있는 wijmo.webcomponents.js 파일을 스크립트 태그를 사용하여 루트 html 페이지에 추가해야합니다:

    <script src="path_to_wijmo/dist/interop/webcomponents/wijmo.webcomponents.js"></script>

    이 단일 파일에는 interop에서 제공하는 모든 구성 요소가 포함됩니다.

이제 애플리케이션에서 Wijmo 웹 컴포넌트를 사용할 수 있습니다:

<head>
  <script src="node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>
  <script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-lite.js"></script>
  <script>
    window["wj-control-is-element"] = true;
  </script>
  ...
</head>
<body>
  <wjc-input-number value="5" step="3"></wjc-input-number>
</body>
import "@mescius/wijmo.webcomponents.input";

속성 (Attributes)

Wijmo 웹 컴포넌트 요소에 정의된 해당 속성을 사용하여 특성 값을 지정할 수 있습니다.


다음 규칙을 고려해야 합니다.

  1. 속성 이름은 대시로 구분된 형식이어야 합니다. 예를 들어 firstDayOfWeek 속성 \의 값을 지정하려면 first-day-of-week 사용해야 합니다 .

  2. 단순 유형 특성만 속성으로 지정할 수 있습니다. 열거형 속성의 경우, 열거형 멤버 이름을 사용할 수 있습니다 (예 : selection-mode = "Day") .

  3. 속성값은 항상 문자열이므로 Wijmo 웹 컴포넌트는 값을 해당 특성에 지정하기 전에 적절한 값 변환을 수행합니다.

다음 예제는 다른 유형의 지정된 특성을 가진 wjc-calendar 웹 컴포넌트를 보여줍니다 .

<label>Calendar</label>
<wjc-calendar
  style="width:450px"
  show-header="true"
  value="04/07/2018"
  first-day-of-week="1"
  selection-mode="Day"
  format-day-headers="dddd"
>
</wjc-calendar>

하위 컴포넌트(Child components)

Wijmo Controls를 나타내는 "최상위" 웹 컴포넌트는 외에도, 상위 구성 요소의 설정을 선언적으로 사용자 정의하는 데 도움이 되는 하위 구성 요소도 있습니다. 예를 들어, wjc-flex-grid-column 컴포넌트를 사용하여 FlexGrid 열 목록을 지정하거나, wjc-flex-chart-series 하위 컴포넌트를 사용하여 FlexChart 계열을 정의할 수 있습니다.


하위 컴포넌트는 상위 컴포넌트의 직계 하위 컴포넌트여야 합니다.


예제는 다음과 같습니다:

  1. 그리드 컬럼의 목록을 정의하는 wjc-flex-grid 컴포넌트의 자식 wjc-flex-grid-column 컴포넌트, 그리고 그리드에 컬럼 필터를 적용하는 wjc-flex-grid-filter 자식 컴포넌트가 있습니다.

  2. 차트 계열을 정의하는 wjc-flex-chart 컴포넌트의 자식 wjc-flex-chart-series 컴포넌트, 그리고 차트의 X와 Y 축을 사용자 정의하는 wjc-flex-chart-axis 자식 컴포넌트가 있습니다.

<label>FlexGrid with Columns and Filter</label>
<wjc-flex-grid id="gridWithChildren" style="height:auto">
  <wjc-flex-grid-filter></wjc-flex-grid-filter>
  <wjc-flex-grid-column binding="country" header="Country" width="*">
  </wjc-flex-grid-column>
  <wjc-flex-grid-column binding="date" header="Date"> </wjc-flex-grid-column>
  <wjc-flex-grid-column binding="downloads" header="Downloads">
  </wjc-flex-grid-column>
  <wjc-flex-grid-column binding="sales" header="Sales" format="c2">
  </wjc-flex-grid-column>
</wjc-flex-grid>

<label>FlexChart with Series and Axes</label>
<wjc-flex-chart id="chartWithChildren" binding-x="country" style="height:300px">
  <wjc-flex-chart-axis wj-property="axisX" title="Countries" axis-line="true">
  </wjc-flex-chart-axis>
  <wjc-flex-chart-axis
    wj-property="axisY"
    title="Sales/Downloads"
    axis-line="true"
    major-grid="true"
  >
  </wjc-flex-chart-axis>
  <wjc-flex-chart-series name="Sales" binding="sales"> </wjc-flex-chart-series>
  <wjc-flex-chart-series name="Downloads" binding="downloads">
  </wjc-flex-chart-series>
</wjc-flex-chart>

코드에서 참조 및 사용

document.getElementById 메소드와 같은 기존 DOM API를 사용하여 Wijmo 웹 컴포넌트 요소를 찾을 수 있습니다. 그 후 다음 규칙에 따라 요소의 Wijmo 특정 API에 액세스할 수 있습니다.

  1. Wijmo Controls를 나타내는 최상위 컴포넌트의 경우 해당 컴포넌트가 해당 제어 클래스에서 직접 상속되므로 모든 컨트롤 API를 컴포넌트에서 바로 사용할 수 있습니다. 예를 들어, 다음 코드를 사용하여 FlexGrid 웹 컴포넌트에 데이터를 할당할 수 있습니다.

    document.querySelector("wjc-flex-grid").itemsSource = getData();

  2. Wijmo Control 구성 요소와 함께 제공되는 자식 컴포넌트의 경우 Wijmo 자식 컴포넌트가 나타내는 Wijmo 클래스 주위의 래퍼로 작동하기 때문에 특수 컨트롤 속성을 사용하여 기본 Wijmo 객체에 대한 참조를 가져와야 합니다. 예를 들어,이 코드를 사용하여 FlexGridFilter 웹 컴포넌트에 대한 필터 열 목록을 지정할 수 있습니다:

    document.querySelector("wjc-flex-grid-filter").control.filterColumns = [
  "country",
  "date",
];

다음 예는 wjc-group-panel 컴포넌트를 wjc-flex-grid 컴포넌트에 첨부하고 wjc-flex-grid-filter 컴포넌트의 필터 열 목록을 정의합니다 .

<label>FlexGrid with GroupPanel and Filter</label>
<wjc-group-panel id="panelRef" placeholder="Drag columns here...">
</wjc-group-panel>
<wjc-flex-grid id="gridRef">
  <wjc-flex-grid-filter id="filterRef"></wjc-flex-grid-filter>
</wjc-flex-grid>
// DOM 트리에서 그리드 요소 찾기
let gridRef = document.getElementById("gridRef");
// 요소(FlexGrid로부터 상속된)는 FlexGrid의 인스턴스이기도 함.
// 그래서 요소에 FlexGrid api를 사용할 수 있음 (e.g. 데이터 소스에 할당하기)
gridRef.itemsSource = dataSvc.getData(100);
// DOM 트리에서 그룹 패널 요소 찾기
let panelRef = document.getElementById("panelRef");
// Grid에 부착하기:
panelRef.grid = gridRef;
// DOM 트리에서 wjc-flex-grid-filter 컴포넌트 찾기
let filterRef = document.getElementById("filterRef");
// 기초 FlexGridFilter 객체의 filterColumns 속성값 지정하기
filterRef.control.filterColumns = ["country", "date"];

Events

기본 HTML 요소와 마찬가지로 일반적인 addEventListener 메소드를 사용하여 Wijmo 특정 이벤트를 구독할 수 있습니다. 이벤트 이름은 대시로 구분된 형식으로 지정해야 합니다 (예 : 기본 Wijmo valueChanged 이벤트의 경우 value-changed) .


예를 들어 다음과 같은 코드를 사용하여 해당 웹 컴포넌트의 InputNumber.valueChanged 이벤트를 구독할 수 있습니다.

document
  .querySelector("wjc-input-number")
  .addEventListener("value-changed", (e) => {
    alert(`New value is ${e.target.value}`);
  });

Wijmo 컴포넌트는 CustomEvent 유형의 이벤트를 트리거합니다. 이벤트 헨들러에서 사용할 수 있는 이벤트 객체는 두 가지 주요 속성이 있습니다.

  1. target - 이벤트를 트리거한 웹 구성 요소를 참조합니다.

  2. detail - Wijmo 이벤트의 이벤트 인자들을 보여합니다. 예를 들어,FlexGrid.formatItem 이벤트CustomEvent.detail 속성에 FormatItemEventArgs 유형의 객체가 포함됩니다.

Wijmo 컨트롤을 나타내는 Wijmo 웹 컴포넌트 두 가지 다른 버전의 addEventListener 메소드를 상속합니다.

하나는 wijmo.Control 고유의 메소드이고, 다른 하나는 wijmo.Control도 HTMLElement 클래스로 부터 해당 메소드를 상속 받기 때문입니다. 이 두 가지 메소드는 서명을 가지고 있기 때문에, Wijmo 웹 컴포넌트는 그것들을 구별할 수 있고, 적절한 실행을 호출할 수 있습니다.


다음 예제는 wjc-input-number 및 wjc-linear-gauge 컴포넌트의 value-changed 이벤트를 사용하여 해당 값을 동기화합니다. 또한 wjc-flex-grid 의 format-item 이벤트를 사용하여 Active 열의 셀 내용을 사용자 정의 합니다.

// valueChanged 이벤트를 사용하여 InputNumber와 LinearGauge 동기화
let inpNumEvents = document.getElementById("inpNumEvents");
let gaugeEvents = document.getElementById("gaugeEvents");
inpNumEvents.addEventListener("value-changed", (e: CustomEvent) => {
  // CustomEvent.target references the component where event occurred
  gaugeEvents.value = e.target.value;
});
gaugeEvents.addEventListener("value-changed", (e: CustomEvent) => {
  inpNumEvents.value = e.target.value;
});

// formatItem 이벤트를 사용하여 FlexGrid의 활성 열을 포맷팅
let gridEvents = document.getElementById("gridEvents");
gridEvents.itemsSource = dataSvc.getData(100);
gridEvents.addEventListener("format-item", (e: CustomEvent) => {
  // CustomEvent.detail contains corresponding Wijmo event arguments
  let args = e.detail,
    grid = args.panel.grid;
  if (
    args.panel === grid.cells &&
    grid.columns[args.col].binding === "active" &&
    !args.range.equals(grid.editRange)
  ) {
    args.cell.innerHTML = grid.getCellData(args.row, args.col, false)
      ? "Yes"
      : "No";
  }
});

프로그래밍 방식으로 생성

기본 HTML 요소에서와 동일한 방식으로 표준 DOM API를 사용하여 Wijmo 웹 컴포넌트에서 작업할 수 있습니다. 구체적으로 다음을 수행 할 수 있습니다.

  1. document.createElement 메소드를 사용하여 Wijmo 컴포넌트를 작성하십시오 (예 : document.createElement ( 'wjc-flex-grid')).

  2. document.appendChild , document.insertBefore 및 document.removeChild 와 같은 메소드를 사용하여 DOM 트리에 요소를 추가, 이동 및 제거 하십시오 .

  3. Wijmo 하위 컴포넌트의 경우에도 마찬가지 입니다. 예를 들어 부모 wjc-flex-grid 요소에서 wjc-flex-grid-column 요소를 추가/제거/재배열하여 그리드 열을 추가, 제거 및 재정렬할 수 있습니다 .

이 샘플은 해당 Wijmo 웹 컴포넌트를 작성하고, 이를 DOM 트리의 적절한 위치에 추가하여 프로그래밍방식으로 열 및 열 필터로 FlexGrid를 작성합니다.

<label>FlexGrid with columns and filter created programmatically</label>
<div id="gridProg"></div>
// placeholder 요소 찾기
let placeHolder = document.getElementById("gridProg");
// FlexGrid 웹 컴포넌트 생성
let gridProg = document.createElement("wjc-flex-grid");
// DOM에 grid 추가
placeHolder.appendChild(gridProg);
// 웹 컴포넌트 열 생성
let countryCol = document.createElement("wjc-flex-grid-column");
// 속성을 할당하기 전 부모에 자식 추가
gridProg.appendChild(countryCol);
countryCol.control.binding = "country";
countryCol.control.header = "Country";
countryCol.control.width = "*";
// 웹 컴포넌트 열 생성
let downloadsCol = document.createElement("wjc-flex-grid-column");
// 속성을 할당하기 전 부모에 자식 추가
gridProg.appendChild(downloadsCol);
downloadsCol.control.binding = "downloads";
downloadsCol.control.header = "Downloads";
// 웹 컴포넌트에 FlexGridFilter 생성
let filter = document.createElement("wjc-flex-grid-filter");
// 속성을 할당하기 전 부모에 자식 추가
gridProg.appendChild(filter);
filter.filterColumns = ["country"];

// grid 데이터 설정
gridProg.itemsSource = dataSvc.getData(100);