이 페이지의 내용
문서API 레퍼런스
API 레퍼런스05

HTMLColumn

값, 유효성 검사, DOM 연결에 사용하는 컬럼 API입니다.

한국어 문서약 25분

구성 요소#

속성#

항목 설명
_valueTypes 컬럼값(value)으로 가능한 타입을 제한합니다.
_entity 컬럼이 속한 엔티티(MetaTable 또는 MetaView)를 가르킵니다.
value 컬럼의 현재값을 나타냅니다.
default 컬럼의 초기값을 지정합니다.
getter 컬럼의 값(value)를 조회할 때 실행되는 사용자 정의 함수입니다.
setter 컬럼의 값(value)를 설정할 때 실행되는 사용자 정의 함수입니다.
getFilter 값(value)를 가져올 때 필터를 적용하는 함수입니다.
setFilter 값(value)를 설정할 때 필터를 적용하는 함수입니다.
selector 컬럼과 HTML 요소 간의 동기화를 정의합니다.
required 컬럼 값이 필수인지 여부를 정의합니다.
constraints 컬럼 값의 제약 조건을 정의합니다.
columnName 컬럼의 고유 이름을 정의합니다.
alias 컬럼의 별칭입니다.
caption 컬럼의 설명이나 라벨로 사용됩니다.

메소드#

항목 설명
addConstraint() 컬럼에 제약 조건(constraints)을 추가합니다.
valid() 컬럼값(value)이 제약 조건을 충족하는지 확인합니다.
clone() 컬럼을 복제하여 새로운 인스턴스를 생성합니다.

이벤트#

항목 설명
onChanged 컬럼 값이 변경될 때 호출되는 이벤트 입니다.

주요 속성#

_valueTypes#

컬럼값(value)으로 가능한 타입을 제한하는 속성입니다.

ts
type _valueTypes = any[];
  • any[]: 컬럼에 value 으로 등록을 제한할 타입

추후 동적타입관리에 대한 정보가 제공될 예정입니다.

_valueTypes속성은 컬럼값(value) 타입을 제한합니다. 특정 규칙에 따라 값을 제한할 때 유용합니다.

js
const c1 = new HTMLColumn('aa');

// 타입 재정의
c1._valueTypes = [String];

c1.value = 'Mike';     // 값 등록 성공
c1.value = 10;         // 제약조건으로 예외 발생!!

console.log(c1._valueTypes); // Out: [String]
  • _valueTypes에 String 타입을 추가하여 이 컬럼에서 문자열만 허용되도록 설정합니다.
  • 10은 String 타입이 아니므로 제약조건이 위반되어 예외가 발생합니다.

_entity#

컬럼이 속한 엔티티(MetaTable 또는 MetaView)를 가르키는 속성입니다.

ts
type _entity = MetaTable | MetaView;

_entity 속성은 컬럼이 속한 테이블(MetaTable)이나 뷰(MetaView)를 가르킵니다.

  • 컬럼과 테이블 간의 연결 관계를 확인할 수 있습니다.

Tip: 동일한 엔티티에 소속된 컬럼을 찾을 때 유용합니다. (_entity.columns['컬럼명'])

js
const table = new MetaView('users');

table.columns.add('name');

console.log(table.columns['name']._entity.viewName); // Out: 'users'
  • _entity 속성을 사용하여 name 컬럼이 속한 테이블의 이름을 확인합니다.

value#

컬럼의 현재값을 나타내는 속성입니다.

ts
type value = string | number | boolean;

value 속성은 컬럼의 현재값을 나타내며, 컬럼값을 설정하거나 조회할 수 있습니다.

값(value)의 특성을 다양한 방식으로 지정할 수 있습니다.

  • getter / setter : 값 조회 및 설정 시 사용자 정의 함수 설정
  • getFilter / setFilter : 값 변환을 위해 필터 함수 설정
  • selector : UI 와 동기화하기 위한 선택자 설정

참조 : 컬럼값 호출 구조

js
const column = new HTMLColumn('age');

// 기본값 설정
column.default = 15;

// getter / setter 정의
column.getter = () => column.default * 2;
column.setter = (val) => { if (val > 0) column.default = val; };

console.log(column.value); // Out: 30 (getter를 통해 값 조회)
column.value = 30;         // setter를 통해 값 설정
console.log(column.value); // Out: 60 (getter를 통해 값 조회)
  • default 속성을 통해 초기값을 설정하고, setter를 사용해 조건부로 값을 변경합니다.

default#

컬럼의 초기값을 지정하는 속성입니다.

ts
type DefaultValue = string | number | boolean | '';
  • 초기값 : 빈공백

default 속성은 컬럼의 value 값이 지정되지 않았을 때 사용하는 기본값입니다.

  • 초기 데이터를 제공하고, 데이터가 누락된 경우에도 일관성을 유지하게 합니다.
  • value 값이 null 이면 default 속성 값을 반환합니다.
  • newRow(), getValue() 메소드에서 value 값이 없으면 default 속성 값으로 대체됩니다.
js
const column = new HTMLColumn('status');

// 기본값 설정
column.default = 'active';

// 값 설정 후 확인
column.value = 'inactive';
console.log(column.value);  // Out: 'inactive'

// 기본값 반환
column.value = null;
console.log(column.value);  // Out: 'active'
  • 값이 설정되지 않은 경우, default 속성을 통해 기본값을 반환합니다.

getter#

컬럼의 값(value)를 조회할 때 실행되는 사용자 정의 함수입니다.

ts
type getter = () => any;
  • 함수로 정의되며, 반환값이 컬럼의 현재값으로 간주됩니다.

getter 속성은 컬럼 값(value)을 조회할 때 실행되는 함수로, 추가 가공이나 조건부 처리를 수행할 수 있습니다.

가장 높은 우선순위를 가지며, 이후 단계는 무시됩니다.

  • 이후단계 : getFilter 함수 호출 > selector 조회 > 내부값 조회

참조 : 컬럼값 호출 구조

js
const column = new HTMLColumn('price');

// getter 정의
column.getter = () => {
    return column.default + 50;
};

// 기본값 설정
column.default = 100;

// 값 조회
console.log(column.value); // Out: 150
  • getter 정의: getter 함수를 통해 기본값에 50을 더한 값을 반환하도록 설정합니다.
  • 값 조회: value 속성을 호출할 때 getter 함수가 실행되어 가공된 값이 반환됩니다.

setter#

컬럼의 값(value)를 설정할 때 실행되는 사용자 정의 함수입니다.

ts
type setter = (value: string | number | boolean) => void | any;
  • value: 설정하려는 값
  • 반환값: void 또는 추가 로직에서 사용할 값을 반환할 수 있습니다.

setter 속성은 값이 설정될 때 실행되며, 유효성 검사, 변환, 추가 처리를 수행하는 함수입니다.

  • 가장 높은 우선순위로 실행되며, 순차적으로 다음 단계가 처리됩니다.
  • 반환값이 존재하면 이후 단계에서 설정 값으로 사용됩니다.

이후단계 : 내부값 저장 > setFilter 함수 호출 > selector 설정

참조 : 컬럼값 호출 구조

js
const column = new HTMLColumn('discount');

// setter 설정
column.setter = (value) => {
    if (typeof value !== 'number' || value < 0 || value > 100) {
        throw new Error('Discount must be a number from 0 to 100.');
    }
    return value;  // 내부에 저장됨
};

// 값 설정
column.value = 20;
console.log(column.value); // Out: 20

try {
    column.value = 150;   // 유효성 검사 실패!!
} catch (e) {
    console.error(e.message); // Out: 'Discount must be a number from 0 to 100.'
}
  • 입력값이 0 ~ 100 사이의 숫자인지 확인하며, 조건을 만족하지 않으면 예외가 발생합니다.

getFilter#

값(value)를 가져올 때 필터를 적용하는 함수입니다.

ts
type getFilter = (selectorValue?: any) => any;
  • selectorValue(선택): selector에 의해 전달된 값
  • 반환값: 필터링된 결과로 반환될 값입니다.

getFilter 속성은 컬럼 값에 사용자 정의 필터를 적용하여 데이터를 변환하거나 가공된 값을 반환합니다.

  • getter 함수가 정의되지 않은 경우 호출됩니다.
  • selector 속성과 함께 동작하여 UI에서 가져온 데이터를 처리할 수 있습니다.

참조 : 컬럼값 호출 구조

js
const column = new HTMLColumn('price');

// getFilter 설정
column.getFilter = (selectorValue) => {
    return `$${selectorValue.toFixed(2)}`;
};

// selector 설정
column.selector = { key: '#price-input', type: 'value' };
// DOM 에 값 입력
document.querySelector('#price-input').value = 123.456;

console.log(column.value); // Out: '$123.45'
  • selector 속성을 통해 입력된 값을 getFilter 함수에서 가공하여 반환합니다.

setFilter#

값(value)를 설정할 때 필터를 적용하는 함수입니다.

ts
type setFilter = (innerValue: any) => void | any;
  • innerValue: setter 이후 전달된 내부값 또는 설정값
  • 반환값: 선택적으로 반환값이 있고, selector 속성이 존재하면 해당 값이 UI에 설정됩니다.

setFilter 속성는 내부값을 입력받아 이를 변환하거나 추가 처리를 수행합니다.

  • 반환값이 존재하고 selector 속성이 정의된 경우, 해당 반환값이 selector 속성 위치에 동기화 됩니다.

Tip: setFilter 반환값이 존재하지 않고, selector 속성이 지정된 경우 각각 독립적으로 처리됩니다.

참조 : 컬럼값 호출 구조

js
const column = new HTMLColumn('price');

// setFilter 설정
column.setFilter = (innerValue) => {
    return `$${innerValue.toFixed(2)}`; // 통화 형식으로 변환
};

// selector 설정
column.selector = { key: '#price-input', type: 'value' };

// 값 설정
column.value = 123.456;
console.log(document.querySelector('#price-input').value); // Out: '$123.45'
  • setFilter 함수의 반환값이 selector 속성를 통해 UI에 설정됩니다.

selector#

컬럼과 HTML 요소 간의 동기화를 정의하기 위한 속성입니다.

ts
type selector = {
    key: string;
    type: 'value' | 'text' | 'html' | 'prop' | 'attr' | 'css';
};
  • key: HTML 요소를 식별하기 위한 셀렉터 문자열
  • type: 동기화 방식
    • value: HTML 요소의 값(value)을 동기화합니다.
    • text: HTML 요소의 텍스트 내용을 동기화합니다.
    • html: HTML 요소의 내부 HTML을 동기화합니다.
    • prop: 요소의 속성(property) 값을 동기화합니다.
    • attr: 요소의 특정 속성(attribute)을 동기화합니다.
    • css: CSS 스타일을 동기화합니다.

selector 속성은 컬럼과 HTML 요소 간의 값을 동기화하는 데 사용됩니다.

  • 컬럼 값과 HTML 요소 값이 상호 반영됩니다.
  • getFilter 함수 또는 setFilter 함수와 함께 사용하여 데이터를 가공할 수 있습니다.
  • getter 함수가 정의된 경우, selector 지정 값은 가져오지 않습니다.

Tip: value 값 설정은 setter → setFilter → selector 순으로 수행되며, 값 조회는 우선순위에 따라 getter, getFilter, selector 중 하나가 선택되어 실행됩니다.

참조 : 컬럼값 호출 구조

js
const column = new HTMLColumn('status');

// selector 설정
column.selector = { key: '#status-input', type: 'value' };

// 값 설정
column.value = 'Active'; // HTML 요소의 값이 업데이트됨
console.log(document.querySelector('#status-input').value); // Out: 'Active'

// DOM 값 입력
document.querySelector('#status-input').value = 'Inactive';
console.log(column.value); // Out: 'Inactive'
  • 다양한 type 옵션을 통해 HTML 요소와의 동작 방식을 세부적으로 제어할 수 있습니다.

required#

컬럼 값이 필수인지 여부를 정의하는 속성입니다.

ts
type required = boolean;
  • true: 컬럼 값이 필수입니다.
  • false: 컬럼 값이 선택적입니다.

required 속성은 컬럼 값의 필수 여부를 지정합니다. true로 설정되면 값(value)이 비어 있거나 미설정 상태일 경우 유효성 검사가 실패합니다.

참조 : 컬럼 관리 > 제약조건

js
const column = new HTMLColumn('username');

// 필수 설정
column.required = true;

// 유효성 검사
if (!column.valid(column.value)) {
    console.error('Value is required for username.');
} else {
    console.log('Value is valid.');
}
  • valid() 메서드를 사용하여 값이 유효한지 검사합니다. 값이 비어 있으면 오류가 발생합니다.

constraints#

컬럼 값의 제약 조건을 정의하는 속성입니다.

ts
// 1. 정규식 기반 조건
type ConstraintType = { 
	regex: RegExp,       // 검사할 정규식
	msg: string,         // 조건 미충족 시 출력할 메시지
	code?: string,       // 조건 미충족 시 반환할 코드 (선택적)
	condition?: boolean  // true: 매칭 조건, false: 비매칭 조건 (기본값: true)
};
// 2. 함수 기반 조건
type FailMsgType = { msg: string, code: string };
type FunctionType = (value: any, _this) => boolean | FailMsgType | void;
// 3. 복합 타입 (ConstraintType 또는 FunctionType)
type complexType = ConstraintType | FunctionType;

// constraints 타입 (단일 또는 배열)
type constraints = complexType[] | complexType;
  • ConstraintType: 정규식과 메시지를 포함하여 값의 패턴
    • condition 값이 true이면 정규식 매칭 조건, false이면 정규식 비매칭 조건
  • FunctionType: 값의 유효성을 확인하기 위한 사용자 정의 함수
    • true 또는 undefined : 성공
    • false 또는 FailMsgType : 실패
  • complexType: ConstraintType과 FunctionType의 조합
  • constraints: 단일 조건 또는 복합 배열 조건

constraints 속성은 컬럼 값이 특정 조건을 만족하는지 검사하는 규칙을 설정합니다.

정규식 또는 사용자 정의 함수를 사용하여 유효성을 확인할 수 있으며, 여러 조건을 배열로 설정하여 복합 검사 가 가능합니다. 값이 조건을 만족하지 못하면 유효성 검사가 실패로 처리됩니다.

사용자 함수로 제약 조건을 설정할 경우, 반환값이 true 또는 undefined이면 성공, FailMsgType 객체 또는 false이면 실패로 처리됩니다.

Tip : 정규식 속성 condition = false 로 설정하면 정규식과 비매칭될 경우 성공을 반환하며, 매칭되면 실패 메세지를 반환합니다.

js
const column = new HTMLColumn('email');
let check;

// constraints 설정
column.constraints = [
    { regex: /^[^@]+@[^@]+\.[^@]+$/, msg: 'Invalid email format.' },
    (value) => value.length > 3
];

// 값 설정 및 유효성 검사
column.value = 'example@example.com';
check = column.valid(column.value);
if (check) {
    console.error(check.msg);
}

column.value = 'a@b';
check = column.valid(column.value);
if (check) {
    console.error(check.msg); // Out: 'function constraint failed.'
}

column.value = 'invalid-email';
check = column.valid(column.value);
if (check) {
    console.error(check.msg); // Out: 'Invalid email format.'
}
  • constraints 속성에 정규식과 사용자 정의 함수를 사용하여 값을 검사합니다.
  • valid() 메서드는 검사가 실패하면 객체를 반환하고, 성공하면 undefined를 반환합니다.

columnName#

컬럼의 고유 이름을 정의하는 속성입니다.

ts
type columnName = string;
  • string: 컬럼의 이름

columnName 속성은 컬럼을 식별하는 속성입니다.

  • 컬럼 이름은 컬렉션 내에서 고유해야 합니다.
  • columnName 속성은 상위 속성 _name 으로 조회할 수 있습니다.
js
const column = new HTMLColumn('username');

console.log(column.columnName); // Out: 'username'
console.log(column._name);      // OUt: 'username'
  • 컬럼 생성시 columnName 속성이 인자로 전달됩니다.

alias#

컬럼의 별칭 속성입니다.

ts
type alias = string;
  • string: 컬럼의 별칭으로 사용되는 문자열

Tip : alias 속성이 설정되어 있으면 getValue() 및 newRow() 에서 컬럼 대신 별칭이 사용합니다.

alias 속성은 컬럼명과 행(row) 데이터 간의 매칭 역할을 합니다.

  • 서버의 데이터 키와 컬럼 이름이 다를 경우, alias 속성을 활용하여 데이터를 매핑할 수 있습니다.
  • alias 속성은 컬렉션 내에서 고유해야 하며, columnName 속성 또는 기존의 다른 alias 속성과 중복될 수 없습니다.
js
const view = new MetaView('userView');

// 컬럼 추가 및 별칭 설정
view.columns.add('u_name', { alias: 'user_name' });

let row = view.newRow();
row['user_name'] = 'John';
view.rows.add(row);

console.log(view.rows[0]['user_name']); // Out: 'John'
  • alias 속성은 MetaRow 객체에 매핑되는 값으로 사용됩니다.

caption#

컬럼의 설명이나 라벨로 사용되는 속성입니다.

ts
type caption = string;
  • caption 컬럼의 설명
js
const column = new HTMLColumn('username');

// caption 설정
column.caption = 'User Name';

console.log(column.caption); // Out: 'User Name'
  • caption은 컬럼의 용도를 사람이 읽기 쉬운 텍스트로 표현하는 데 사용됩니다.

주요 메소드#

addConstraint()#

컬럼에 제약 조건(constraints)을 추가하는 메서드입니다.

ts
type FailMsg = { msg: string, code?: string };
declare function addConstraint(
    regex: RegExp | (val: any, _this: this) => boolean | FailMsg | undefined, 
    msg?: string, 
    code?: string, 
    condition?: boolean
): void;
  • regex: 값을 검증하기 위한 정규식 또는 사용자 정의 함수
    • RegExp: 값이 특정 패턴과 일치하는지 확인합니다.
    • Function: 값을 인자로 받아 유효성을 검사합니다.
      • true 또는 undefined: 성공으로 간주됩니다.
      • FailMsgType: 오류 메시지를 포함하여 실패 처리합니다.
      • false: 기본 실패 처리가 가능합니다.
  • msg(선택): 검증 실패 시 출력될 메시지
  • code(선택): 오류 코드
  • condition(선택): 매칭 및 비매칭 여부 (기본값 true)
    • true 는 정규식과 매칭되면 성공합니다.
    • false 의 정규식과 비매칭되면 성공합니다.

addConstraint() 메서드는 constraints 속성에 새로운 유효성 검사 규칙을 추가하며, 모든 조건이 만족되어야 유효성 검사를 통과합니다.

  • 여러 조건을 일괄 등록하려면 constraints 속성에 배열로 직접 추가할 수 있습니다.
js
const column = new HTMLColumn('age');

// 제약 조건 추가: 숫자만 허용
column.addConstraint({regex: /^\d+$/, msg: 'must be a valid number.'});

// 제약 조건 추가: 사용자 정의 함수
column.addConstraint((value) => value > 10);

// 값 설정 및 유효성 검사
column.value = 25;
console.log(column.valid(column.value));  // Out: undefined

column.value = 'A';
console.log(column.valid(column.value));  // { msg: 'must be a valid number.' }

column.value = 5;
console.log(column.valid(column.value));  // { msg: 'valid(value); function constraint failed...' }
  • 추가된 모든 조건을 기반으로 값이 유효한지 검사합니다. (제약 조건 : 10 보다 큰 숫자)

valid()#

컬럼값(value)이 제약 조건을 충족하는지 확인하는 메서드입니다.

ts
type FailMsg = { msg: string, code?: string };
declare function valid(value: any): FailMsg | undefined;
  • value: 검사할 값
  • 반환값:
    • undefined: 값이 유효한 경우 성공
    • FailMsg 객체: 오류 메시지와 선택적인 오류 코드를 포함한 객체를 반환합니다.

valid() 메서드는 컬럼에 설정된 constraints와 required 속성을 기반으로 값의 유효성을 검사합니다.

정규식 또는 사용자 정의 함수로 제약 조건을 평가하며, 모든 조건을 충족해야 유효합니다. 실패 시 이유를 포함한 객체를 반환합니다.

js
const column = new HTMLColumn('age');

// 제약 조건 추가: 숫자만 허용
column.addConstraint({regex: /^\d+$/, msg: 'must be a valid number.'});

// 제약 조건 추가: 사용자 정의 함수
column.addConstraint((value) => value > 10);

// 값 설정 및 유효성 검사
column.value = 25;
console.log(column.valid(column.value));  // Out: undefined

column.value = 'A';
console.log(column.valid(column.value));  //{ msg: 'must be a valid number.' }

column.value = 5;
console.log(column.valid(column.value));  // { msg: 'valid(value); function constraint failed...' }
  • 값이 조건을 만족하지 못하는 경우, 오류 메시지 객체를 반환하여 실패 원인을 제공합니다.

clone()#

컬럼을 복제하여 새로운 인스턴스를 생성하는 메서드입니다.

ts
declare function clone(entity?: MetaTable | MetaView): HTMLColumn;
  • entity(선택): 컬럼이 소속되는MetaTable 또는 MetaView
  • 반환값: 복제된 HTMLColumn 객체를 반환합니다.

clone() 메서드는 현재 컬럼 객체를 복제하여 원본과 동일한 초기 속성을 가진 독립적인 새로운 객체를 생성합니다.

js
const column = new HTMLColumn('username');

// 값 설정
column.value = 'John';

// 컬럼 복제
const clonedColumn = column.clone();

// 복제된 컬럼 확인
console.log(clonedColumn.columnName); // Out: 'username'
console.log(clonedColumn.value);      // Out: 'John'
  • 복제된 컬럼과 원본은 서로 독립적으로 동작하며, 값 변경이 서로에게 영향을 미치지 않습니다.

entity 지정된 컬럼의 경우 동일 이름으로 복제 되므로 문제가 있음 #이슈


주요 이벤트#

onChanged#

컬럼 값이 변경될 때 호출되는 이벤트 입니다.

ts
type onChanged = (nVal: any, oVal: any, _this: this) => void;
  • newValue: 새로 설정된 값
  • oldValue: 이전 값
  • _this: 현재 컬럼 객체에 대한 참조
  • 반환값: 없음 (void)

컬럼 값이 변경될 때 호출되는 이벤트로, 변경 전 후 값을 비교하거나 특정 동작을 실행하는 데 사용됩니다.

Tip : 이벤트 속성에 콜백함수를 설정하면, 기존 이벤트는 그대로 유지되며 새 이벤트가 추가됩니다.

js
const column = new HTMLColumn('status');

// onChanged 이벤트 설정
column.onChanged = (newValue, oldValue) => {
    console.log(`Value changed from '${oldValue}' to '${newValue}'`);
};

// 값 변경
column.value = 'Active';   // Out: "Value changed from 'null' to 'Active'"
column.value = 'Inactive'; // Out: "Value changed from 'Active' to 'Inactive'"
  • 값(value)이 변경될 때마다 onChanged 이벤트가 호출됩니다.

검색어를 입력해 보세요.