[]
        
(Showing Draft Content)

Angular 구성요소

Wijmo Angular 2 컴포넌트는 각각 별도의 npm 패키지로 제공됩니다. 각 컴포넌트의 npm 패키지 이름은 해당 기본 라이브러리 이름에 "angular2"를 추가한 형태입니다. 예를 들어, "wijmo.angular2.grid" 패키지는 기본 라이브러리 "wijmo.grid"에 대한 Angular 컴포넌트를 제공합니다.


더불어 필요한 컴포넌트만 개별적으로 설치하거나, "wijmo.angular2.all" 패키지를 이용해 모든 컴포넌트를 한 번에 설치할 수도 있습니다.

npm install @mescius/wijmo.angular2.all

Wijmo npm 패키지에 대한 자세한 내용은 npm을 통해 Wijmo 레퍼런싱 항목을 참조하시기 바랍니다.

Wijmo Angular 2 컴포넌트는 Angular 2.2.1 이상 버전(10.* 버전 포함)을 지원합니다.

Wijmo Angular 2 컴포넌트는 템플릿 마크업에서 사용하도록 설계되었습니다.

코드에서 Wijmo 컨트롤을 직접 생성할 경우, Angular2 컴포넌트가 아닌 기본 모듈의 Wijmo 컨트롤을 사용해야 합니다.

예를 들어, FlexGrid를 코드로 생성할 때는 "wijmo.angular2.grid"가 아니라 "@mescius/wijmo.grid"의 FlexGrid를 사용합니다:

import { FlexGrid } from '@mescius/wijmo.grid';
let flex = new FlexGrid('#host_element');

Wijmo CSS 추가하기

Wijmo는 @mescius/wijmo.styles라는 npm 패키지를 통해 CSS 파일을 제공합니다. 포함된 파일은 다음과 같습니다:

  • Wijmo.css: 모든 컨트롤에 대한 스타일을 포함

  • wijmo-core.css: Enterprise 컨트롤 스타일을 제외한 축약 버전

이 스타일 파일들은 Angular 애플리케이션에 다음과 같은 방법으로 추가할 수 있습니다:

1. 기본 styles.css 파일에 추가

@import '@mescius/wijmo.styles/wijmo.css';

2. 또는 angular.json 파일에 경로 추가

"styles": [
  "node_modules/@mescius/wijmo.styles/wijmo.css"
]


Angular 마크업 구문

Wijmo Angular 컴포넌트는 명확한 규칙을 따라 이름이 지정됩니다:

  • 컴포넌트 이름: 소문자와 대시(-)를 사용합니다.

    예: WjInputNumber 컴포넌트 → <wj-input-number> 형태로 작성.

<wj-input-number [(value)]="amount"></wj-input-number>
  • 디렉티브 이름: 클래스 이름은 camelCase를 사용합니다.


    예: WjFlexGridCellTemplate 디렉티브는 wjFlexGridCellTemplate 속성으로 사용합니다.

<template wjFlexGridCellTemplate [cellType]="'Cell'"></template>
  • 속성 바인딩 및 이벤트 바인딩 규칙:

    • 단방향 바인딩: [속성명]

    • 양방향 바인딩: [(속성명)]

    • 이벤트 바인딩: (이벤트명)

<wj-input-number
  [(value)]="amount"  // 양방향 바인딩
  [format]="'n0'"      // 문자열 단방향 바인딩
  [isReadOnly]="true"  // 불리언 단방향 바인딩
  (valueChanged)="valueChanged($event)"> // 이벤트 바인딩
</wj-input-number>

주의: 바인딩 표현식은 해당 속성 타입과 일치해야 합니다.

예를 들어, 문자열 타입에는 반드시 작은따옴표(')로 묶인 문자열 리터럴을 사용해야 하고, 불리언 타입은 true처럼 따옴표 없이 작성해야 합니다.

이벤트 바인딩 작성

Wijmo 이벤트 핸들러는 두 개의 인자를 받습니다:

  • sender: 이벤트를 발생시킨 컴포넌트

  • eventArgs: 이벤트 관련 데이터

Angular에서는 $event 변수를 통해 하나의 이벤트 인자만 전달하므로, Wijmo 이벤트 데이터는 $event에 담겨 전달됩니다.

<wj-flex-grid
  [itemsSource]="data"
  (deletingRow)="beforeDelete($event)">
</wj-flex-grid>

(이 경우 $eventCellRangeEventArgs 객체입니다.)


만약 핸들러에서 컴포넌트 인스턴스(sender)이벤트 데이터(eventArgs) 를 모두 받고 싶다면, 컴포넌트에 로컬 변수를 설정하고 함께 전달하면 됩니다:

<wj-flex-grid #flex
  [itemsSource]="data"
  (deletingRow)="beforeDelete(flex, $event)">
</wj-flex-grid>

여기서 #flex<wj-flex-grid> 컴포넌트 인스턴스를 참조합니다.

"initialized(초기화)" 이벤트

모든 Wijmo Angular 컴포넌트는 initialized 이벤트를 제공합니다.

이 이벤트는 컨트롤이 페이지에 추가되고 초기화가 완료된 후에 발생합니다.

이벤트를 활용하면 단순한 속성 설정을 넘어 추가적인 설정을 수행할 수 있습니다.

<wj-flex-grid #flex (initialized)="initGrid(flex)">
</wj-flex-grid>
export class AppComponent {
  constructor() {
    this.data = ...;
  }

  // FlexGrid에 커스텀 MergeManager 추가
  initGrid(flex) {
    flex.mergeManager = new CustomMerge(flex);
  }
}

Angular 9 (Ivy) 이상의 속성 초기화 순서

Angular 8 이하에서는 Wijmo 구성 요소에서 속성 초기화 순서가 내부적으로 정의되었으므로 컴포넌트의 요소에 지정된 속성 지정 순서와 상관없이 항상 동일한 순서로 초기화됩니다. 기술적으로 초기화 순서는 @Component 데코레이터의 inputs 속성에 있는 속성 이름의 순서에 따라 결정 됩니다.


Angular 9에서는 상황이 변경되었으며, 기본적으로 이 프레임워크에서 사용되는 새로운 Ivy 컴파일러가 등장했습니다. 이제 속성은 개발자가 요소에 지정한 순서대로 정확하게 초기화됩니다. 따라서 Angular 9부터는 올바른 속성 초기화 순서를 지정하는 것이 컴포넌트를 사용하는 개발자의 책임입니다.


예를 들어, 아래 마크업을 고려해 보겠습니다.

<wj-list-box [selectedIndex]="3" [itemsSource]="data"></wj-list-box>

Angular 8 이하에서 올바르게 작동합니다 - 네번째 항목이 선택된 상태로 목록이 나타납니다.


하지만, Angular 9 이상에서는 그렇지 않습니다. 첫 번째 항목이 선택된 상태로 목록이 표시되고 selectedIndex 속성에 대한 할당이 무시됩니다. 이는 selectedIndex 가 여기 itemsSource 앞에 정의 되어 있고, 컨트롤이 itemsSource 속성을 통해 항목 배열을 받기 전에 할당되므로 현재 인덱스 3이 있는 항목이 없기 때문입니다.


Angular 8 이하에서는 초기화 순서가 구성 요소에 의해 내부적으로 정의되어 selectedIndex 가 항상 itemsSource 에 할당됩니다 .


이 문제를 해결하고, Angular 9 및 다른 모든 버전에서 예상한대로 동작하도록 마크업을 하려면, 우리는 selectedIndex 정의를 itemsSource 에 정의할 필요가 있습니다:

<wj-list-box [itemsSource]="data" [selectedIndex]="3"></wj-list-box>

또 다른 좋은 예는 [isRequired] = "false"속성을 사용하여 구성 요소에서 null 값을 허용하는 것입니다. 이 마크 업은 Angular 9에서 예외를 발생시킵니다 (그러나 Angular 8에서는 작동합니다).

<wj-input-number [value]="null" [isRequired]="false"></wj-input-number>

isRequired가 false로 설정되기 전에 null 값 지정 시도가 수행되기 때문입니다.


올바른 정의는 다음과 같습니다.

<wj-input-number [isRequired]="false" [value]="null"></wj-input-number>

이것은 모든 Angular 버전에서 작동합니다.

Angular 8 이하에서 ES 모듈 비활성화

wijmo.angular2. * 모듈의 ESM 버전은 빌드 5.20202.699 (2020 년 7 월 22 일 릴리스)부터 기본적으로 사용됩니다. Angular 버전 8 이하를 기반으로 하는 프로젝트에서는 일부 특정 사용 시나리오에서 문제가 발생할 수 있습니다.


이러한 사용 사례의 예는 wjFlexGridCellTemplate 또는 wjItemTemplate 지시자를 포함하는 사용자 정의 컴포넌트 템플릿과 함께, Wijmo 컴포넌트에서 상속된 컴포넌트가 있는 경우입니다. 또는 Menu 컴포넌트가 있는 경우입니다. 해당 문제는 Angular AOT 컴파일러(ViewEngine)에 의해 발생하므로 프로덕션 번들에서만 발생한다 점을 유의하십시오.


이 문제가 발생하면 wijmo-esm 유틸리티를 사용하여 달성 할 수 있는, wijmo.angular2. * 모듈의 ESM 버전을 비활성화해야 합니다. 일반적으로 옵션을 전달하지 않고 이 유틸리티를 호출합니다. 이 경우 프로젝트에 사용된 Angular 버전을 자동으로 감지하여 Wijmo ESM 모듈이 8 이하인 경우 비활성화하거나, 버전이 9 이상인 경우 활성화합니다. ESM이 비활성화되면 Angular는 CommonJS 모듈을 사용합니다.


-disable 또는 -enable 옵션을 지정하여 무조건 ESM 모듈을 비활성화하거나 활성화 할 수도 있습니다. 도구는 프로젝트의 node modules/.bin_ 폴더에 설치됩니다 . 이를 사용하는 권장 방법은 npm "postinstall" 이벤트에서 호출하는 것입니다.

    "scripts": {
        "postinstall": "wijmo-esm",
        ..........
    }

수동으로 실행하려면 프로젝트 패키지의 npm 스크립트에 추가하십시오.

    "scripts": {
        "wijmo-esm": "wijmo-esm",
        ..........
    }

그 후 다음 명령을 사용하여 실행할 수 있습니다.

 npm run wijmo-esm

또는 옵션을 지정해야하는 경우 :

 npm run wijmo-esm -- -disable

사용 가능한 옵션에 대한 도움말 정보를 표시하려면 다음 명령을 실행하십시오.

 npm run wijmo-esm -- -help

도구의 실행 파일은 프로젝트의, 해당 경로 아래에 있습니다.

node_modules/@mescius/wijmo.angular2.directivebase/tools/wijmo-esm.js