syidaxdesign system
홈 가격 내 정보
ComponentsInputs

Tree Select

PRO

조직이나 폴더처럼 계층으로 나뉜 목록에서 항목을 선택합니다.

<sy-tree-select>설치 안내 기본 사용법
Live preview
컴포넌트를 조작하면 여기에 결과가 표시됩니다.
코드 보기
HTML
<sy-tree-select
  placeholder="팀 선택"
  maxtagcount="2"
  expandable
  expandall
  line
  clearable
  name="team"
  id="sample"
  aria-label="팀 선택"
></sy-tree-select>

<script type="module">
  const component1 = document.querySelector("#sample");
  Object.assign(component1, {
    "nodes": [{
        "label": "Product",
        "value": "product",
        "children": [{
            "label": "Design",
            "value": "design"
          },
          {
            "label": "Engineering",
            "value": "engineering"
          }
        ]
      },
      {
        "label": "Business",
        "value": "business",
        "children": [{
            "label": "Sales",
            "value": "sales"
          },
          {
            "label": "Support",
            "value": "support"
          }
        ]
      }
    ]
  });
</script>

사용 가이드

#

조직·카테고리처럼 계층이 있는 후보에서 값을 선택할 때 사용합니다.

  1. 오류 문구는 error 슬롯에 작성합니다.

    컴포넌트 안에 <span slot="error">오류 메시지</span>을 넣으세요. 글자뿐 아니라 링크 등 필요한 안내도 넣을 수 있습니다. noNativeValidity를 지원하는 입력은 이를 켜면 브라우저 팝업 대신 이 안내를 표시합니다. Switch는 항상 컴포넌트 아래에 오류를 표시합니다.

  2. 업무 규칙의 실패는 setCustomError()로 알립니다.

    예를 들어 서버가 중복된 값을 거절하면 error 슬롯의 문구를 바꾸고 setCustomError()를 호출하세요. 이 메서드에는 메시지 인자를 전달하지 않습니다. 사용자 지정 오류가 있으면 폼 제출도 차단됩니다.

  3. 해결 후 해제하고 제출 가능 여부를 확인합니다.

    clearCustomError()로 업무 규칙 오류를 해제하세요. required나 입력 형식 검사까지 해제되지는 않습니다. await checkValidity()는 true/false를, reportValidity()는 검사 결과와 오류 표시를 함께 제공합니다. name을 지정한 유효한 값은 제출 시 FormData로 읽습니다.

  1. 계층 데이터 준비

    nodes에 label·value와 children을 가진 트리 배열을 전달합니다.

  2. 선택과 펼침 설정

    checkable로 복수 선택을, expandable로 가지 펼침을 허용합니다. expandAll은 처음부터 전체 트리를 펼칩니다.

  3. 선택 결과 정리

    clearable로 선택 비우기를 제공하고 maxTagCount로 표시할 선택 태그 수를 조절하세요.

예제

#

계층에서 선택

부모를 펼치고 실제 팀을 선택하세요.

코드 보기
HTML
<sy-tree-select
  placeholder="팀 선택"
  expandable
  expandall
  line
  id="sample"
></sy-tree-select>

<script type="module">
  const component1 = document.querySelector("#sample");
  Object.assign(component1, {
    "nodes": [{
        "label": "Product",
        "value": "product",
        "children": [{
            "label": "Design",
            "value": "design"
          },
          {
            "label": "Engineering",
            "value": "engineering"
          }
        ]
      },
      {
        "label": "Business",
        "value": "business",
        "children": [{
            "label": "Sales",
            "value": "sales"
          },
          {
            "label": "Support",
            "value": "support"
          }
        ]
      }
    ]
  });
</script>

복수 선택과 태그

checkable을 사용하면 여러 항목을 선택할 수 있습니다.

코드 보기
HTML
<sy-tree-select
  checkable
  expandall
  maxtagcount="1"
  defaultvalue="design,engineering,sales"
  clearable
  id="sample"
></sy-tree-select>

<script type="module">
  const component1 = document.querySelector("#sample");
  Object.assign(component1, {
    "nodes": [{
        "label": "Product",
        "value": "product",
        "children": [{
            "label": "Design",
            "value": "design"
          },
          {
            "label": "Engineering",
            "value": "engineering"
          }
        ]
      },
      {
        "label": "Business",
        "value": "business",
        "children": [{
            "label": "Sales",
            "value": "sales"
          },
          {
            "label": "Support",
            "value": "support"
          }
        ]
      }
    ]
  });
</script>

선택 상태 유지

읽기 전용과 비활성화 상태에서도 현재 선택값을 보여줍니다.

코드 보기
HTML
<div style="display:grid;gap:16px;width:100%">
  <sy-tree-select
    defaultvalue="design"
    readonly
    id="readonly"
  ></sy-tree-select>
  <sy-tree-select
    defaultvalue="engineering"
    disabled
    id="disabled"
  ></sy-tree-select>
</div>

<script type="module">
  const component1 = document.querySelector("#readonly");
  Object.assign(component1, {
    "nodes": [{
        "label": "Product",
        "value": "product",
        "children": [{
            "label": "Design",
            "value": "design"
          },
          {
            "label": "Engineering",
            "value": "engineering"
          }
        ]
      },
      {
        "label": "Business",
        "value": "business",
        "children": [{
            "label": "Sales",
            "value": "sales"
          },
          {
            "label": "Support",
            "value": "support"
          }
        ]
      }
    ]
  });
  const component2 = document.querySelector("#disabled");
  Object.assign(component2, {
    "nodes": [{
        "label": "Product",
        "value": "product",
        "children": [{
            "label": "Design",
            "value": "design"
          },
          {
            "label": "Engineering",
            "value": "engineering"
          }
        ]
      },
      {
        "label": "Business",
        "value": "business",
        "children": [{
            "label": "Sales",
            "value": "sales"
          },
          {
            "label": "Support",
            "value": "support"
          }
        ]
      }
    ]
  });
</script>

이벤트와 전달 값

컴포넌트를 조작하고 최근 이벤트의 이름과 detail 값을 확인하세요. 코드에는 이 컴포넌트와 하위 구성 요소가 보내는 이벤트의 구독 방법이 모두 포함되어 있습니다.

코드 보기
HTML
<sy-tree-select
  placeholder="팀 선택"
  maxtagcount="2"
  expandable
  expandall
  line
  clearable
  name="team"
  id="sample"
  aria-label="팀 선택"
></sy-tree-select>
<output id="demo-events" aria-live="polite">컴포넌트를 조작하면 최근 이벤트와 전달 값이 표시됩니다.
</output>

<script type="module">
  const describeResult = value => JSON.stringify(value, (_key, item) => {
    if (item instanceof File) return {
      name: item.name,
      size: item.size,
      type: item.type
    };
    if (item instanceof Element) return `<${item.localName}>`;
    return item;
  }) ?? '완료';
  const component1 = document.querySelector("#sample");
  Object.assign(component1, {
    "nodes": [{
        "label": "Product",
        "value": "product",
        "children": [{
            "label": "Design",
            "value": "design"
          },
          {
            "label": "Engineering",
            "value": "engineering"
          }
        ]
      },
      {
        "label": "Business",
        "value": "business",
        "children": [{
            "label": "Sales",
            "value": "sales"
          },
          {
            "label": "Support",
            "value": "support"
          }
        ]
      }
    ]
  });
  for (const name of ["changed"]) {
    document.addEventListener(name, event => {
      document.querySelector('#demo-events').textContent =
        `${event.target.localName} · ${name}: ${describeResult(event.detail)}`;
    });
  }
</script>

계층 데이터를 기다리는 상태

loading은 항목을 불러오는 동안 사용합니다. 응답 후 loading을 false로 바꾸고 nodes를 갱신하세요.

코드 보기
HTML
<sy-tree-select
  placeholder="팀 선택"
  maxtagcount="2"
  expandable
  expandall
  line
  clearable
  loading
  name="team"
  id="sample"
  aria-label="팀 선택"
></sy-tree-select>

<script type="module">
  const component1 = document.querySelector("#sample");
  Object.assign(component1, {
    "nodes": [{
        "label": "Product",
        "value": "product",
        "children": [{
            "label": "Design",
            "value": "design"
          },
          {
            "label": "Engineering",
            "value": "engineering"
          }
        ]
      },
      {
        "label": "Business",
        "value": "business",
        "children": [{
            "label": "Sales",
            "value": "sales"
          },
          {
            "label": "Support",
            "value": "support"
          }
        ]
      }
    ]
  });
  const component2 = document.querySelector("#sample");
  Object.assign(component2, {
    "loading": true
  });
</script>

팝업 너비와 배치

nodeWidth로 항목 너비를 확보하고 appendParent로 부모 영역에 팝업을 배치합니다. 선택란을 열어 긴 항목과 패널 위치를 확인하세요.

코드 보기
HTML
<sy-tree-select
  placeholder="팀 선택"
  maxtagcount="2"
  expandable
  expandall
  line
  clearable
  nodewidth="280"
  appendparent
  name="team"
  id="sample"
  aria-label="팀 선택"
></sy-tree-select>

<script type="module">
  const component1 = document.querySelector("#sample");
  Object.assign(component1, {
    "nodes": [{
        "label": "Product",
        "value": "product",
        "children": [{
            "label": "Design",
            "value": "design"
          },
          {
            "label": "Engineering",
            "value": "engineering"
          }
        ]
      },
      {
        "label": "Business",
        "value": "business",
        "children": [{
            "label": "Sales",
            "value": "sales"
          },
          {
            "label": "Support",
            "value": "support"
          }
        ]
      }
    ]
  });
  const component2 = document.querySelector("#sample");
  Object.assign(component2, {
    "nodeWidth": 280,
    "appendParent": true
  });
</script>

폼과 유효성 검사

값을 비운 채 제출하면 필수 입력 검사가 동작합니다. 값을 입력한 뒤 제출해 폼 데이터를 확인하고, 사용자 지정 오류도 켜고 꺼보세요.

코드 보기
HTML
<form style="display:grid;gap:16px">
  <sy-tree-select
    name="field"
    required
    placeholder="팀 선택"
    expandall
    id="sample"
  ><span slot="error">팀을 선택하세요.</span></sy-tree-select>
  <div style="display:flex;flex-wrap:wrap;gap:8px">
    <sy-button type="submit" variant="primary">제출</sy-button>
    <sy-button type="reset">초기화</sy-button>
  </div>
</form>
<div class="demo-actions"
  style="display:flex;flex-wrap:wrap;gap:8px;margin-top:16px"
>
  <sy-button id="action-0" size="small">유효성 확인</sy-button>
  <sy-button id="action-1" size="small">오류 표시</sy-button>
  <sy-button id="action-2" size="small">오류 해제</sy-button>
</div>
<output id="demo-result" aria-live="polite"></output>

<script type="module">
  const describeResult = value => JSON.stringify(value, (_key, item) => {
    if (item instanceof File) return {
      name: item.name,
      size: item.size,
      type: item.type
    };
    if (item instanceof Element) return `<${item.localName}>`;
    return item;
  }) ?? '완료';
  const component1 = document.querySelector("#sample");
  Object.assign(component1, {
    "nodes": [{
        "label": "Product",
        "value": "product",
        "children": [{
            "label": "Design",
            "value": "design"
          },
          {
            "label": "Engineering",
            "value": "engineering"
          }
        ]
      },
      {
        "label": "Business",
        "value": "business",
        "children": [{
            "label": "Sales",
            "value": "sales"
          },
          {
            "label": "Support",
            "value": "support"
          }
        ]
      }
    ]
  });
  const actionTarget0 = document.querySelector("#sample");
  document.querySelector('#action-0').addEventListener('click', async () => {
    const result = await actionTarget0.checkValidity();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget1 = document.querySelector("#sample");
  document.querySelector('#action-1').addEventListener('click', async () => {
    const result = await actionTarget1.setCustomError();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget2 = document.querySelector("#sample");
  document.querySelector('#action-2').addEventListener('click', async () => {
    const result = await actionTarget2.clearCustomError();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  document.querySelector('form').addEventListener('submit', event => {
    event.preventDefault();
    document.querySelector('#demo-result').textContent = describeResult([...new FormData(event
      .currentTarget)]);
  });
</script>

검사 결과와 오류 상태 읽기

제출 전에 검사하거나 오류를 화면에 표시할 수 있습니다. 필수 값을 비워 두고 검사한 다음, 값을 채워 반환 값이 어떻게 달라지는지 확인하세요. 상태 조회는 사용자 지정 오류와 필수 입력 오류를 구분하는 데 사용합니다.

코드 보기
HTML
<form style="display:grid;gap:16px">
  <sy-tree-select
    name="field"
    required
    placeholder="팀 선택"
    expandall
    id="sample"
  ><span slot="error">팀을 선택하세요.</span></sy-tree-select>
  <div style="display:flex;flex-wrap:wrap;gap:8px">
    <sy-button type="submit" variant="primary">제출</sy-button>
    <sy-button type="reset">초기화</sy-button>
  </div>
</form>
<div class="demo-actions"
  style="display:flex;flex-wrap:wrap;gap:8px;margin-top:16px"
>
  <sy-button id="action-0" size="small">유효성 확인</sy-button>
  <sy-button id="action-1" size="small">오류 표시</sy-button>
  <sy-button id="action-2" size="small">오류 해제</sy-button>
  <sy-button id="action-3" size="small">오류와 함께 검사</sy-button>
  <sy-button id="action-4" size="small">검증 상태 조회</sy-button>
</div>
<output id="demo-result" aria-live="polite"></output>

<script type="module">
  const describeResult = value => JSON.stringify(value, (_key, item) => {
    if (item instanceof File) return {
      name: item.name,
      size: item.size,
      type: item.type
    };
    if (item instanceof Element) return `<${item.localName}>`;
    return item;
  }) ?? '완료';
  const component1 = document.querySelector("#sample");
  Object.assign(component1, {
    "nodes": [{
        "label": "Product",
        "value": "product",
        "children": [{
            "label": "Design",
            "value": "design"
          },
          {
            "label": "Engineering",
            "value": "engineering"
          }
        ]
      },
      {
        "label": "Business",
        "value": "business",
        "children": [{
            "label": "Sales",
            "value": "sales"
          },
          {
            "label": "Support",
            "value": "support"
          }
        ]
      }
    ]
  });
  const actionTarget0 = document.querySelector("#sample");
  document.querySelector('#action-0').addEventListener('click', async () => {
    const result = await actionTarget0.checkValidity();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget1 = document.querySelector("#sample");
  document.querySelector('#action-1').addEventListener('click', async () => {
    const result = await actionTarget1.setCustomError();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget2 = document.querySelector("#sample");
  document.querySelector('#action-2').addEventListener('click', async () => {
    const result = await actionTarget2.clearCustomError();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget3 = document.querySelector("#sample");
  document.querySelector('#action-3').addEventListener('click', async () => {
    const result = await actionTarget3.reportValidity();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget4 = document.querySelector("#sample");
  document.querySelector('#action-4').addEventListener('click', async () => {
    const result = await actionTarget4.getStatus();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  document.querySelector('form').addEventListener('submit', event => {
    event.preventDefault();
    document.querySelector('#demo-result').textContent = describeResult([...new FormData(event
      .currentTarget)]);
  });
</script>

문자열로 유효성 설정

setCustomValidity(message)는 메시지가 비어 있지 않으면 오류를 설정합니다. 빈 문자열을 전달하면 이 오류를 해제합니다. 필수 입력 검사는 계속 적용됩니다.

코드 보기
HTML
<form style="display:grid;gap:16px">
  <sy-tree-select
    name="field"
    required
    placeholder="팀 선택"
    expandall
    id="sample"
  ><span slot="error">팀을 선택하세요.</span></sy-tree-select>
  <div style="display:flex;flex-wrap:wrap;gap:8px">
    <sy-button type="submit" variant="primary">제출</sy-button>
    <sy-button type="reset">초기화</sy-button>
  </div>
</form>
<div class="demo-actions"
  style="display:flex;flex-wrap:wrap;gap:8px;margin-top:16px"
>
  <sy-button id="action-0" size="small">업무 규칙 오류</sy-button>
  <sy-button id="action-1" size="small">업무 규칙 오류 해제</sy-button>
  <sy-button id="action-2" size="small">상태 조회</sy-button>
</div>
<output id="demo-result" aria-live="polite"></output>

<script type="module">
  const describeResult = value => JSON.stringify(value, (_key, item) => {
    if (item instanceof File) return {
      name: item.name,
      size: item.size,
      type: item.type
    };
    if (item instanceof Element) return `<${item.localName}>`;
    return item;
  }) ?? '완료';
  const component1 = document.querySelector("#sample");
  Object.assign(component1, {
    "nodes": [{
        "label": "Product",
        "value": "product",
        "children": [{
            "label": "Design",
            "value": "design"
          },
          {
            "label": "Engineering",
            "value": "engineering"
          }
        ]
      },
      {
        "label": "Business",
        "value": "business",
        "children": [{
            "label": "Sales",
            "value": "sales"
          },
          {
            "label": "Support",
            "value": "support"
          }
        ]
      }
    ]
  });
  const actionTarget0 = document.querySelector("#sample");
  document.querySelector('#action-0').addEventListener('click', async () => {
    const result = await actionTarget0.setCustomValidity("이 부서는 현재 선택할 수 없습니다.");
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget1 = document.querySelector("#sample");
  document.querySelector('#action-1').addEventListener('click', async () => {
    const result = await actionTarget1.setCustomValidity("");
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  const actionTarget2 = document.querySelector("#sample");
  document.querySelector('#action-2').addEventListener('click', async () => {
    const result = await actionTarget2.getStatus();
    document.querySelector('#demo-result').textContent = describeResult(result);
  });
  document.querySelector('form').addEventListener('submit', event => {
    event.preventDefault();
    document.querySelector('#demo-result').textContent = describeResult([...new FormData(event
      .currentTarget)]);
  });
</script>

사용자 지정 오류 메시지

서버 중복 검사나 업무 규칙에 맞지 않을 때 오류 문구를 직접 표시합니다. 아래 문구를 바꿔 보고 제출을 눌러 차단되는지 확인하세요. 오류 해제 후에는 필수 입력 조건까지 만족해야 제출됩니다.

코드 보기
HTML
<label for="error-message">표시할 오류 메시지</label><input
  id="error-message"
  value="서버에서 이 값을 승인하지 않았습니다. 내용을 확인해 주세요."
  type="text"
>
<form style="display:grid;gap:16px">
  <sy-tree-select
    nonativevalidity
    name="field"
    required
    placeholder="팀 선택"
    expandall
    id="sample"
  ><span slot="error">팀을 선택하세요.</span></sy-tree-select>
  <div style="display:flex;flex-wrap:wrap;gap:8px">
    <sy-button type="submit" variant="primary">제출</sy-button>
    <sy-button type="reset">초기화</sy-button>
  </div>
</form>
<div class="demo-actions">
  <sy-button id="show-custom-error" variant="primary">오류 표시</sy-button>
  <sy-button id="clear-custom-error">오류 해제</sy-button>
</div>
<output id="custom-error-result" aria-live="polite"></output>
<output id="demo-result" aria-live="polite"></output>

<script type="module">
  const describeResult = value => JSON.stringify(value, (_key, item) => {
    if (item instanceof File) return {
      name: item.name,
      size: item.size,
      type: item.type
    };
    if (item instanceof Element) return `<${item.localName}>`;
    return item;
  }) ?? '완료';
  const component1 = document.querySelector("#sample");
  Object.assign(component1, {
    "nodes": [{
        "label": "Product",
        "value": "product",
        "children": [{
            "label": "Design",
            "value": "design"
          },
          {
            "label": "Engineering",
            "value": "engineering"
          }
        ]
      },
      {
        "label": "Business",
        "value": "business",
        "children": [{
            "label": "Sales",
            "value": "sales"
          },
          {
            "label": "Support",
            "value": "support"
          }
        ]
      }
    ]
  });
  await (async function customErrorSetup(root) {
    const field = root.querySelector('#sample');
    const message = root.querySelector('[slot="error"]');
    const input = root.querySelector('#error-message');
    const output = root.querySelector('#custom-error-result');
    const update = async () => {
      message.textContent = input.value.trim() || _msg("m_4eea8cef81c6");
      await field.setCustomError();
      output.textContent = _msg("m_e00bd46236d3", [message.textContent]);
    };
    input.addEventListener('input', update);
    root.querySelector('#show-custom-error').addEventListener('click', update);
    root.querySelector('#clear-custom-error').addEventListener('click', async () => {
      await field.clearCustomError();
      output.textContent = await field.checkValidity() ? _msg("m_c454251167b2") : _msg(
        "m_5b8cb48627e5");
    });
    root.querySelector('form').addEventListener('invalid', () => {
      output.textContent = _msg("m_c702c7778166");
    }, true);
    root.querySelector('form').addEventListener('reset', () => {
      output.textContent = _msg("m_b90c2b4dc30f");
    });
    await update();
  })(document);
  document.querySelector('form').addEventListener('submit', event => {
    event.preventDefault();
    document.querySelector('#demo-result').textContent = describeResult([...new FormData(event
      .currentTarget)]);
  });
</script>

API reference

#

이름에 마우스를 올리거나 키보드로 선택하면 적용 코드를 확인할 수 있습니다. 터치 화면에서는 이름을 누르세요.

<sy-tree-select>

Properties

Attribute / PropertyTypeDefaultDescription
TreeNode[][]label·value·children으로 구성한 트리 노드 배열입니다.

객체·배열 값은 JavaScript 프로퍼티로 전달합니다.

booleanfalse체크박스로 복수 항목을 선택합니다.
booleanfalse현재 값을 비우는 버튼을 표시합니다.
string''처음 표시할 선택값입니다.
booleanfalse사용자 조작과 키보드 포커스를 차단합니다.
'error' | 'default''default'기본·성공·경고·오류 상태를 시각적으로 표현합니다.
booleanfalse트리 가지의 펼침 제어를 허용합니다.
booleanfalse모든 트리 가지를 처음부터 펼칩니다.
booleanfalse부모·자식 사이 연결선을 표시합니다.
booleanfalse처리 중임을 표시합니다.
number0한 번에 표시할 선택 태그 수입니다. 0이면 모두 표시합니다.
number | nullnull트리 노드의 표시 너비입니다.
string''값이 비어 있을 때 표시할 안내 문구입니다.
booleanfalse선택 결과에 부모 노드를 포함하는 방식을 설정합니다.
booleanfalse현재 값을 보여주면서 사용자 수정을 막습니다.
booleanfalse값이 없으면 폼 검증을 실패시킵니다.
string''FormData에 사용되는 필드 이름입니다.
booleanfalse브라우저의 기본 오류 표시 대신 앱의 오류 UI를 사용할 때 지정합니다. checkValidity 검사 자체는 유지됩니다.

Events

EventDetailDescription
CustomEvent<{ selectedItem: { value: string; label: string }[]; isValid: boolean }>값 또는 선택 상태가 바뀔 때 발생합니다.

Methods

MethodReturnsDescription
Promise<void>지정한 메시지로 사용자 정의 유효성을 설정합니다. 빈 문자열은 오류를 해제합니다.
Promise<boolean>현재 제약 조건에 맞으면 true, 아니면 false를 반환합니다.
Promise<boolean>현재 값을 검사하고 오류를 사용자에게 표시합니다.
Promise<void>사용자 지정 오류 상태를 설정합니다.
Promise<void>사용자 지정 오류 상태를 해제합니다.
Promise<"" | "custom" | "valueMissing">현재 유효성 검사 상태를 반환합니다.

Slots

SlotDescription
유효성 검사 오류 메시지입니다.
Design SystemTab 이동 Enter 열기