npm - slick-address-kr - Versions diffs - 1.0.0 - Mend

slick-address-kr 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/API-KEY-GUIDE.md +428 -0
package/AUTOCOMPLETE-GUIDE.md +399 -0
package/HOW-TO-USE.md +416 -0
package/LICENSE +21 -0
package/README.ko.md +88 -0
package/README.md +434 -0
package/config.example.js +16 -0
package/dist/address-finder.d.ts +68 -0
package/dist/address-finder.js +262 -0
package/dist/api-client.d.ts +25 -0
package/dist/api-client.js +79 -0
package/dist/index.d.ts +8 -0
package/dist/index.js +8 -0
package/dist/styles.css +279 -0
package/dist/types.d.ts +83 -0
package/dist/types.js +1 -0
package/index.html +85 -0
package/korean-address-finder.js +360 -0
package/package.json +58 -0

package/dist/types.d.ts ADDED Viewed

@@ -0,0 +1,83 @@
+/**
+ * 주소 검색 결과 인터페이스
+ */
+export interface AddressResult {
+    /** 도로명 주소 */
+    roadAddress: string;
+    /** 지번 주소 */
+    jibunAddress: string;
+    /** 우편번호 */
+    zipCode: string;
+    /** 건물명 */
+    buildingName?: string;
+    /** 상세 주소 입력용 */
+    detailAddress?: string;
+    /** 참고 항목 */
+    extraAddress?: string;
+    /** 시도명 */
+    sido?: string;
+    /** 시군구명 */
+    sigungu?: string;
+    /** 읍면동명 */
+    bname?: string;
+}
+/**
+ * 주소 검색 설정 옵션
+ */
+export interface AddressFinderOptions {
+    /** 행정안전부 API 키 (선택사항 - 공개 API 사용 가능) */
+    apiKey?: string;
+    /** 한 페이지에 표시할 결과 수 (기본값: 10) */
+    countPerPage?: number;
+    /** 현재 페이지 번호 (기본값: 1) */
+    currentPage?: number;
+    /** 검색 결과를 표시할 컨테이너 ID */
+    containerId?: string;
+    /** 주소 선택 시 콜백 함수 */
+    onSelect?: (address: AddressResult) => void;
+    /** 상세주소 입력 필드 표시 여부 (기본값: true) */
+    showDetailInput?: boolean;
+    /** 커스텀 스타일 클래스 */
+    customClass?: string;
+    /** 자동완성 모드 사용 여부 (기본값: false) */
+    autocompleteMode?: boolean;
+}
+/**
+ * API 응답 인터페이스 (행정안전부 주소 API)
+ */
+export interface JusoApiResponse {
+    results: {
+        common: {
+            totalCount: string;
+            currentPage: string;
+            countPerPage: string;
+            errorCode: string;
+            errorMessage: string;
+        };
+        juso: Array<{
+            roadAddr: string;
+            roadAddrPart1: string;
+            roadAddrPart2: string;
+            jibunAddr: string;
+            zipNo: string;
+            bdNm: string;
+            admCd: string;
+            rnMgtSn: string;
+            bdMgtSn: string;
+            detBdNmList?: string;
+            bdKdcd: string;
+            siNm: string;
+            sggNm: string;
+            emdNm: string;
+            liNm: string;
+            rn: string;
+            udrtYn: string;
+            buldMnnm: string;
+            buldSlno: string;
+            mtYn: string;
+            lnbrMnnm: string;
+            lnbrSlno: string;
+            emdNo: string;
+        }>;
+    };
+}

package/dist/types.js ADDED Viewed

	@@ -0,0 +1 @@
1	+ export {};

package/index.html ADDED Viewed

@@ -0,0 +1,85 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>한국 주소 검색</title>
+  <style>
+    body {
+      font-family: 'Malgun Gothic', -apple-system, sans-serif;
+      max-width: 800px;
+      margin: 50px auto;
+      padding: 20px;
+      background-color: #f5f5f5;
+    }
+    h1 {
+      text-align: center;
+      color: #333;
+    }
+    .container {
+      background: white;
+      padding: 30px;
+      border-radius: 10px;
+      box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+    }
+    .info-box {
+      background-color: #e3f2fd;
+      padding: 15px;
+      border-radius: 5px;
+      margin-bottom: 20px;
+      font-size: 14px;
+      line-height: 1.6;
+    }
+  </style>
+</head>
+<body>
+  <h1>🏠 한국 주소 검색</h1>
+  <div class="container">
+    <div class="info-box">
+      <strong>💡 사용 방법:</strong><br>
+      1. 아래 검색창에 주소를 입력하세요 (예: 판교역로)<br>
+      2. <strong>자동으로 검색 결과가 나타납니다!</strong> (2글자 이상 입력 시)<br>
+      3. 목록에서 원하는 주소를 클릭하세요<br>
+      <br>
+      <strong>✨ 자동완성 기능:</strong> 타이핑하는 즉시 결과가 표시됩니다!
+    </div>
+    <!-- 주소 검색 컴포넌트가 여기에 렌더링됩니다 -->
+    <div id="address-finder"></div>
+  </div>
+  <!-- 1. config.js 파일 로드 (API 키 포함) -->
+  <script src="config.js"></script>
+  <!-- 2. 주소 검색 라이브러리 로드 -->
+  <script src="korean-address-finder.js"></script>
+  <!-- 3. 초기화 -->
+  <script>
+    // config.js에서 API 키 가져오기
+    const apiKey = window.CONFIG && window.CONFIG.jusoApiKey
+      ? window.CONFIG.jusoApiKey
+      : 'devU01TX0FVVEgyMDI1MDExMDE1MTY0MTExNTM2MjY='; // 기본 테스트 키
+    // 주소 검색 초기화
+    const addressFinder = new KoreanAddressFinder({
+      containerId: 'address-finder',
+      apiKey: apiKey,
+      onSelect: function(address) {
+        console.log('선택된 주소:', address);
+        // 여기서 폼에 값을 채우거나 서버로 전송
+        // 예시:
+        // document.getElementById('zipcode').value = address.zipCode;
+        // document.getElementById('address1').value = address.roadAddress;
+      }
+    });
+    addressFinder.init();
+  </script>
+</body>
+</html>

package/korean-address-finder.js ADDED Viewed

@@ -0,0 +1,360 @@
+/**
+ * Korean Address Finder - 실제 적용용
+ *
+ * 사용 방법:
+ * 1. 이 파일을 프로젝트에 복사
+ * 2. HTML에 포함: <script src="korean-address-finder.js"></script>
+ * 3. config.js 파일에 API 키 입력
+ * 4. 초기화 코드 실행
+ */
+(function(window) {
+  'use strict';
+  // API 설정
+  const API_URL = 'https://business.juso.go.kr/addrlink/addrLinkApi.do';
+  /**
+   * 주소 검색 클래스
+   */
+  class KoreanAddressFinder {
+    constructor(options = {}) {
+      this.apiKey = options.apiKey || '';
+      this.containerId = options.containerId || 'address-finder';
+      this.onSelect = options.onSelect || function() {};
+      this.countPerPage = options.countPerPage || 10;
+      this.autocomplete = options.autocomplete !== false; // 기본값: true (자동완성 켜짐)
+      this.minLength = options.minLength || 2; // 최소 검색 글자 수
+      this.debounceTimer = null; // 디바운스 타이머
+      if (!this.apiKey) {
+        console.warn('⚠️ API 키가 설정되지 않았습니다. config.js 파일을 확인하세요.');
+      }
+    }
+    /**
+     * UI 초기화
+     */
+    init() {
+      const container = document.getElementById(this.containerId);
+      if (!container) {
+        console.error(`❌ 컨테이너를 찾을 수 없습니다: #${this.containerId}`);
+        return;
+      }
+      // HTML 구조 생성
+      container.innerHTML = `
+        <div class="kaf-wrapper">
+          <div class="kaf-search-box">
+            <input type="text" class="kaf-search-input" placeholder="주소를 입력하세요 (예: 판교역로 235)">
+            <button type="button" class="kaf-search-btn">검색</button>
+          </div>
+          <div class="kaf-results" style="display: none;"></div>
+          <div class="kaf-selected-address" style="display: none;"></div>
+        </div>
+      `;
+      // CSS 적용
+      this.injectStyles();
+      // 이벤트 리스너 등록
+      this.attachEvents(container);
+      console.log('✅ Korean Address Finder 초기화 완료');
+    }
+    /**
+     * 스타일 주입
+     */
+    injectStyles() {
+      if (document.getElementById('kaf-styles')) return;
+      const style = document.createElement('style');
+      style.id = 'kaf-styles';
+      style.textContent = `
+        .kaf-wrapper {
+          width: 100%;
+          max-width: 600px;
+          font-family: -apple-system, BlinkMacSystemFont, 'Malgun Gothic', sans-serif;
+        }
+        .kaf-search-box {
+          display: flex;
+          gap: 8px;
+          margin-bottom: 12px;
+        }
+        .kaf-search-input {
+          flex: 1;
+          padding: 12px 16px;
+          font-size: 14px;
+          border: 2px solid #e0e0e0;
+          border-radius: 8px;
+          outline: none;
+        }
+        .kaf-search-input:focus {
+          border-color: #4a90e2;
+        }
+        .kaf-search-btn {
+          padding: 12px 24px;
+          font-size: 14px;
+          font-weight: 600;
+          color: white;
+          background-color: #4a90e2;
+          border: none;
+          border-radius: 8px;
+          cursor: pointer;
+        }
+        .kaf-search-btn:hover {
+          background-color: #357abd;
+        }
+        .kaf-results {
+          border: 1px solid #e0e0e0;
+          border-radius: 8px;
+          max-height: 400px;
+          overflow-y: auto;
+          background: white;
+        }
+        .kaf-result-item {
+          padding: 16px;
+          border-bottom: 1px solid #f0f0f0;
+          cursor: pointer;
+        }
+        .kaf-result-item:hover {
+          background-color: #f8f9fa;
+        }
+        .kaf-result-item:last-child {
+          border-bottom: none;
+        }
+        .kaf-result-type {
+          display: inline-block;
+          padding: 2px 8px;
+          font-size: 11px;
+          font-weight: 600;
+          color: white;
+          background-color: #4a90e2;
+          border-radius: 4px;
+          margin-right: 8px;
+        }
+        .kaf-result-address {
+          font-size: 14px;
+          color: #333;
+        }
+        .kaf-result-zipcode {
+          font-size: 12px;
+          color: #666;
+          margin-top: 4px;
+        }
+        .kaf-selected-address {
+          margin-top: 16px;
+          padding: 16px;
+          background-color: #f0f8ff;
+          border: 1px solid #4a90e2;
+          border-radius: 8px;
+        }
+        .kaf-selected-address h3 {
+          color: #4a90e2;
+          margin: 0 0 10px 0;
+          font-size: 16px;
+        }
+        .kaf-selected-address p {
+          margin: 5px 0;
+          font-size: 14px;
+        }
+        .kaf-loading, .kaf-error {
+          text-align: center;
+          padding: 20px;
+        }
+        .kaf-loading {
+          color: #666;
+        }
+        .kaf-error {
+          color: #e74c3c;
+        }
+      `;
+      document.head.appendChild(style);
+    }
+    /**
+     * 이벤트 리스너 등록
+     */
+    attachEvents(container) {
+      const input = container.querySelector('.kaf-search-input');
+      const button = container.querySelector('.kaf-search-btn');
+      const resultsDiv = container.querySelector('.kaf-results');
+      // 검색 버튼 클릭
+      button.addEventListener('click', () => this.search(input.value));
+      // 엔터키 검색
+      input.addEventListener('keypress', (e) => {
+        if (e.key === 'Enter') {
+          this.search(input.value);
+        }
+      });
+      // 자동완성 기능
+      if (this.autocomplete) {
+        input.addEventListener('input', (e) => {
+          const keyword = e.target.value.trim();
+          // 최소 길이 체크
+          if (keyword.length < this.minLength) {
+            resultsDiv.style.display = 'none';
+            return;
+          }
+          // 디바운스 적용 (300ms 대기)
+          clearTimeout(this.debounceTimer);
+          this.debounceTimer = setTimeout(() => {
+            this.search(keyword);
+          }, 300);
+        });
+        // 포커스 시 결과 다시 표시
+        input.addEventListener('focus', () => {
+          if (resultsDiv.innerHTML && resultsDiv.innerHTML !== '<div class="kaf-loading">검색 중...</div>') {
+            resultsDiv.style.display = 'block';
+          }
+        });
+        // 외부 클릭 시 결과 닫기
+        document.addEventListener('click', (e) => {
+          if (!container.contains(e.target)) {
+            resultsDiv.style.display = 'none';
+          }
+        });
+      }
+    }
+    /**
+     * 주소 검색
+     */
+    async search(keyword) {
+      if (!keyword || keyword.trim().length === 0) {
+        alert('검색어를 입력하세요');
+        return;
+      }
+      const container = document.getElementById(this.containerId);
+      const resultsDiv = container.querySelector('.kaf-results');
+      resultsDiv.style.display = 'block';
+      resultsDiv.innerHTML = '<div class="kaf-loading">검색 중...</div>';
+      try {
+        const params = new URLSearchParams({
+          confmKey: this.apiKey,
+          currentPage: '1',
+          countPerPage: this.countPerPage.toString(),
+          keyword: keyword.trim(),
+          resultType: 'json'
+        });
+        const response = await fetch(`${API_URL}?${params.toString()}`);
+        const data = await response.json();
+        if (data.results.common.errorCode !== '0') {
+          resultsDiv.innerHTML = `
+            <div class="kaf-error">
+              <strong>검색 오류:</strong><br>
+              ${data.results.common.errorMessage}<br><br>
+              <small>API 키를 확인하세요.</small>
+            </div>
+          `;
+          return;
+        }
+        this.displayResults(data.results.juso, resultsDiv);
+      } catch (error) {
+        console.error('검색 오류:', error);
+        resultsDiv.innerHTML = '<div class="kaf-error">검색 중 오류가 발생했습니다.</div>';
+      }
+    }
+    /**
+     * 결과 표시
+     */
+    displayResults(addresses, resultsDiv) {
+      if (!addresses || addresses.length === 0) {
+        resultsDiv.innerHTML = '<div class="kaf-error">검색 결과가 없습니다.</div>';
+        return;
+      }
+      let html = '';
+      addresses.forEach(addr => {
+        html += `
+          <div class="kaf-result-item" data-zipno="${addr.zipNo}" data-road="${addr.roadAddr}" data-jibun="${addr.jibunAddr}">
+            <div>
+              <span class="kaf-result-type">도로명</span>
+              <span class="kaf-result-address">${addr.roadAddr}</span>
+            </div>
+            <div style="margin-top: 4px;">
+              <span class="kaf-result-type" style="background-color: #999;">지번</span>
+              <span class="kaf-result-address">${addr.jibunAddr}</span>
+            </div>
+            <div class="kaf-result-zipcode">우편번호: ${addr.zipNo}</div>
+          </div>
+        `;
+      });
+      resultsDiv.innerHTML = html;
+      // 클릭 이벤트
+      resultsDiv.querySelectorAll('.kaf-result-item').forEach(item => {
+        item.addEventListener('click', () => {
+          this.selectAddress({
+            zipCode: item.dataset.zipno,
+            roadAddress: item.dataset.road,
+            jibunAddress: item.dataset.jibun
+          });
+        });
+      });
+    }
+    /**
+     * 주소 선택
+     */
+    selectAddress(address) {
+      const container = document.getElementById(this.containerId);
+      const selectedDiv = container.querySelector('.kaf-selected-address');
+      const resultsDiv = container.querySelector('.kaf-results');
+      selectedDiv.innerHTML = `
+        <h3>✅ 선택된 주소</h3>
+        <p><strong>우편번호:</strong> ${address.zipCode}</p>
+        <p><strong>도로명 주소:</strong> ${address.roadAddress}</p>
+        <p><strong>지번 주소:</strong> ${address.jibunAddress}</p>
+      `;
+      selectedDiv.style.display = 'block';
+      resultsDiv.style.display = 'none';
+      // 콜백 실행
+      this.onSelect(address);
+      console.log('선택된 주소:', address);
+    }
+  }
+  // 전역으로 노출
+  window.KoreanAddressFinder = KoreanAddressFinder;
+})(window);

package/package.json ADDED Viewed

@@ -0,0 +1,58 @@
+{
+  "name": "slick-address-kr",
+  "version": "1.0.0",
+  "description": "행정안전부 도로명주소 API 기반 팝업 없는 한국 주소 검색 컴포넌트 (자동완성 지원) - Korean address search with autocomplete using official road address API",
+  "main": "korean-address-finder.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc && npm run copy-css",
+    "copy-css": "cp src/styles.css dist/styles.css",
+    "dev": "tsc --watch",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "korean",
+    "address",
+    "autocomplete",
+    "도로명주소",
+    "주소검색",
+    "자동완성",
+    "address-search",
+    "juso",
+    "postcode",
+    "우편번호",
+    "korea",
+    "도로명주소API",
+    "행정안전부",
+    "daum-address",
+    "address-finder",
+    "road-address"
+  ],
+  "author": "Devguru-J",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Devguru-J/slick-address-kr.git"
+  },
+  "homepage": "https://github.com/Devguru-J/slick-address-kr#readme",
+  "bugs": {
+    "url": "https://github.com/Devguru-J/slick-address-kr/issues"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist",
+    "korean-address-finder.js",
+    "config.example.js",
+    "index.html",
+    "README.md",
+    "README-KR.md",
+    "HOW-TO-USE.md",
+    "API-KEY-GUIDE.md",
+    "AUTOCOMPLETE-GUIDE.md",
+    "LICENSE"
+  ]
+}