Translator

Chrome 브라우저에는 AI가 내장되어 있으며, API를 통해 AI 기반 작업을 실행할 수 있도록 지원합니다.

Translator API를 이용하면 입력 텍스트를 원하는 언어로 번역할 수 있습니다.

0. 준비

• 브라우저 지원 현황을 확인하세요 MDN 에서 브라우저별 지원 현황을 확인할 수 있습니다.

• Typescript를 사용한다면 @types/dom-chromium-ai npm 패키지를 사용하여 TypeScript 타이핑을 가져오세요.

1. 브라우저가 Translator API를 지원하는지 확인

const isBrowserSupported = "Translator" in self;

2. AI 모델이 준비되었는지 확인

const availability = await Translator.availability({
  sourceLanguage: sourceLanguage, // 'en'
  targetLanguage: targetLanguage, // 'ko'
});

이 함수는 다음 값 중 하나가 포함된 프로미스를 반환합니다.

• available : 모델이 이미 다운로드되어 있고 사용할 수 있습니다.
• downloading : 모델이 다운로드 중입니다.
• downloadable : 모델을 다운로드 할 수 있습니다.
• unavailable : 지원되지 않습니다. 기기의 전원이나 디스크 공간이 부족할 수 있습니다. sourceLanguage와 targetLanguage가 같거나 지원되지 않는 언어일 수 있습니다.

3. 모델 다운로드 및 인스턴스 생성

모델 다운로드 및 인스턴스 생성을 위해 create() 함수를 호출합니다.

원본 언어와 번역할 언어를 전달하고, 작업을 중단하기 위한 시그널도 전달할 수 있습니다.

const abortController = new AbortController();
const translator = await Translator.create({
  sourceLanguage: sourceLanguage,
  targetLanguage: targetLanguage,
  monitor(m) {
    m.addEventListener("downloadprogress", (e) => {
      console.log(`Downloaded ${e.loaded * 100}%`);
    });
  },
  signal: abortController.signal,
});

4. 번역

번역을 위해 translate() 함수를 호출합니다.

이 함수는 번역된 텍스트를 반환합니다.

const translatedText = await translator.translate(text);

5. 인스턴스 해제

작업이 완료되면 인스턴스를 해제합니다.

translator.destroy();

create() 를 호출할 때 전달하는 signal을 통해서 작업을 중단해도 같은 효과를 얻을 수 있습니다

( create() 가 완료되기 전에 abort할 경우에는 create 작업이 취소됩니다. )

abortController.abort();

React 예제

사용자의 상호작용 없이 AI 모델을 다운로드하려고 하면 에러가 발생할 수 있습니다.

따라서 컴포넌트가 마운트되었을 때 인스턴스를 생성하는 것보다는

사용자의 상호작용이 있을 때 인스턴스를 생성할 수 있도록 유틸 함수를 작성합니다.

export const getTranslator = async (
  sourceLanguage: string,
  targetLanguage: string,
  signal: AbortSignal
) => {
  const isBrowserSupported = "Translator" in self;
  if (!isBrowserSupported) {
    throw new Error("Translator is not supported in this browser");
  }

  const availability = await Translator.availability({
    sourceLanguage: sourceLanguage,
    targetLanguage: targetLanguage,
  });

  if (availability === "unavailable") {
    throw new Error("Model is not available for the given languages");
  }

  return Translator.create({
    sourceLanguage: sourceLanguage,
    targetLanguage: targetLanguage,
    signal: signal,
  });
};

컴포넌트가 유지되는 동안은 Translator 인스턴스가 유지되도록 작성했습니다.

실제로 사용할 때는 원본 언어와 번역할 언어가 변경될 때 인스턴스를 새로 생성해야 할 수 있습니다.

import { getTranslator } from "@/utils/translator";

export const Translator = () => {
  const translatorRef = useRef<Translator | null>(null);
  const abortControllerRef = useRef<AbortController | null>(null);

  const [isLoading, setIsLoading] = useState(false);
  const [translatedText, setTranslatedText] = useState<string>("");

  useEffect(() => {
    return () => {
      abortControllerRef.current?.abort();
    };
  }, []);

  const translateText = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();

    const formData = new FormData(e.target as HTMLFormElement);
    const text = formData.get("text") as string;

    try {
      setIsLoading(true);
      if (!translatorRef.current) {
        abortControllerRef.current = new AbortController();
        translatorRef.current = await getTranslator(
          "en",
          "ko",
          abortControllerRef.current.signal
        );
      }

      const results = (await translatorRef.current?.translate(text)) ?? "";
      setTranslatedText(results);
    } catch (error) {
      console.error("Error translating text", error);
    } finally {
      setIsLoading(false);
    }
  };
  return (
    <div>
      <form onSubmit={translateText}>
        <input type="text" name="text" />
        <button type="submit">Translate</button>
      </form>
      <div>{translatedText}</div>
    </div>
  );
};

React 예제 : Language Detector + Translator

Language Detector를 함께 사용하면 원본 언어를 알지 못해도 번역할 수 있습니다.

우선 sourceLanguage와 targetLanguage를 선택할 수 있도록 하겠습니다.

export const Translator = () => {
  // ...
  const translateText = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();

    const formData = new FormData(e.target as HTMLFormElement);
    const text = formData.get("text") as string;
    const sourceLanguage = formData.get("sourceLanguage") as string;
    const targetLanguage = formData.get("targetLanguage") as string;

    // ...
  };
  return (
    <div>
      <form onSubmit={translateText}>
        <select name="sourceLanguage" id="sourceLanguage">
          <option value="auto">Detect Language</option>
          <option value="en">English</option>
          <option value="ko">Korean</option>
        </select>
        <select name="targetLanguage" id="targetLanguage">
          <option value="ko">Korean</option>
          <option value="en">English</option>
        </select>
        <input type="text" name="text" />
        <button type="submit">Translate</button>
      </form>
      <div>{translatedText}</div>
    </div>
  );
};

sourceLanguage가 auto인 경우에는 Language Detector를 사용해서 원본 언어를 감지해야 합니다.

원본 언어를 감지하기 위한 함수를 작성합니다.

마찬가지로 cleanup을 위해 detector와 detectorAbortController는 useRef로 선언합니다.

export const Translator = () => {
  const translatorRef = useRef<Translator | null>(null);
  const translatorAbortControllerRef = useRef<AbortController | null>(null);
  const detectorRef = useRef<LanguageDetector | null>(null);
  const detectorAbortControllerRef = useRef<AbortController | null>(null);

  const [isLoading, setIsLoading] = useState(false);
  const [translatedText, setTranslatedText] = useState<string>("");

  useEffect(() => {
    return () => {
      translatorAbortControllerRef.current?.abort();
      detectorAbortControllerRef.current?.abort();
    };
  }, []);

  const detectLanguage = async (text: string) => {
    if (!detectorRef.current) {
      detectorAbortControllerRef.current = new AbortController();
      detectorRef.current = await getDetector(
        [],
        detectorAbortControllerRef.current.signal
      );
    }
    const results = await detectorRef.current?.detect(text);
    if (!results?.[0]?.detectedLanguage) {
      throw new Error("Failed to detect language");
    }
    return results[0].detectedLanguage;
  };
  // ...
};

선택된 sourceLanguage와 targetLanguage를 이용해서 translate 하도록 수정합니다.

export const Translator = () => {
  // ...

  const translateText = async (e: React.FormEvent<HTMLFormElement>) => {
    // ...
    let sourceLanguage = formData.get("sourceLanguage") as string;
    const targetLanguage = formData.get("targetLanguage") as string;

    try {
      setIsLoading(true);

      // sourceLanguage가 auto인 경우에는 Language Detector를 사용해서 원본 언어를 감지합니다.
      if (sourceLanguage === "auto") {
        const detectedLanguage = await detectLanguage(text);
        sourceLanguage = detectedLanguage;
      }

      // 원본 언어와 번역할 언어가 같으면 번역하지 않습니다.
      if (sourceLanguage === targetLanguage) {
        setTranslatedText(text);
        return;
      }


      // 기존 요청을 취소하고 
      if (abortControllerRef.current) {
        abortControllerRef.current.abort();
      }

      // 새로운 인스턴스를 생성합니다.
      abortControllerRef.current = new AbortController();
      translatorRef.current = await getTranslator(
        sourceLanguage,
        targetLanguage,
        abortControllerRef.current.signal
      );


      const results = (await translatorRef.current?.translate(text)) ?? "";
      setTranslatedText(results);
  };
  // ...
};

참고

• AI on Chrome
• MDN - Translator
• Kangbit Blog

Language Detector

Chrome 브라우저에는 AI가 내장되어 있으며, API를 통해 AI 기반 작업을 실행할 수 있도록 지원합니다.

Language Detector는 입력 텍스트의 언어를 감지하여 확률이 높은 언어부터 낮은 언어 순으로 반환합니다.

이를 이용해 Translator API에 번역할 텍스트의 입력 언어를 전달할 수 있습니다.

0. 준비

• 브라우저 지원 현황을 확인하세요 MDN 에서 브라우저별 지원 현황을 확인할 수 있습니다.

• Typescript를 사용한다면 @types/dom-chromium-ai npm 패키지를 사용하여 TypeScript 타이핑을 가져오세요.

1. 브라우저가 Language Detector API를 지원하는지 확인

const isBrowserSupported = "LanguageDetector" in self;

2. API가 준비되었는지 확인

API가 준비되었는지 확인하려면 비동기 availability() 함수를 호출합니다.

const availability = await LanguageDetector.availability({
  expectedInputLanguages: languages,
});

이 함수는 다음 값 중 하나가 포함된 프로미스를 반환합니다.

• available : 모델이 이미 다운로드되어 있고 사용할 수 있습니다.
• downloading : 모델이 다운로드 중입니다.
• downloadable : 모델을 다운로드 할 수 있습니다.
• unavailable : 지원되지 않습니다. 기기의 전원이나 디스크 공간이 부족할 수 있습니다.

3. 모델 다운로드 및 인스턴스 생성

모델 다운로드 및 인스턴스 생성을 위해 create() 함수를 호출합니다.

이 때 예상 언어를 전달하거나, 작업을 중단하기 위한 시그널을 전달할 수 있습니다.

const abortController = new AbortController();
const detector = await LanguageDetector.create({
  expectedInputLanguages: languages,
  monitor(m) {
    m.addEventListener("downloadprogress", (e) => {
      console.log(`Downloaded ${e.loaded * 100}%`);
    });
  },
  signal: abortController.signal,
});

4. 언어 감지

언어 감지를 위해 detect() 함수를 호출합니다.

const detectedLanguages = await detector.detect(text);

이 함수는 다음과 같은 목록을 포함하는 프로미스를 반환합니다.

[
  {
      "confidence": 0.9427181482315063,
      "detectedLanguage": "en"
  },
  {
      "confidence": 0.016950147226452827,
      "detectedLanguage": "es"
  },
  ...
]

5. 인스턴스 삭제

작업이 완료되면 인스턴스를 삭제합니다.

detector.destroy();

create 함수를 호출할 때 전달하는 signal을 통해서 작업을 중단해도 같은 효과를 얻을 수 있습니다

( create() 가 완료되기 전에 abort할 경우에는 create 작업이 취소됩니다. )

abortController.abort();

React 예제

사용자의 상호작용 없이 AI 모델을 다운로드하려고 하면 에러가 발생할 수 있습니다.

따라서 컴포넌트가 마운트되었을 때 인스턴스를 생성하는 것보다는

사용자의 상호작용이 있을 때 인스턴스를 생성할 수 있도록 유틸 함수를 작성합니다.

export const getLanguageDetector = async (languages: string[], signal: AbortSignal) => {
  const isBrowserSupported = "LanguageDetector" in self;
  if (!isBrowserSupported) {
    throw new Error("Language Detector is not supported in this browser");
  }

  const availability = await LanguageDetector.availability({
    expectedInputLanguages: languages,
  });

  if (availability === "unavailable") {
    throw new Error("Model is not available for the given languages");
  }

  return LanguageDetector.create({
    expectedInputLanguages: languages,
    monitor(m) {
      m.addEventListener("downloadprogress", (e) => {
        console.log(`Downloaded ${e.loaded * 100}%`);
      });
    },
    signal: signal,
  });

컴포넌트가 유지되는 동안은 Language Detector 인스턴스가 유지되도록 작성했습니다.

클린업도 신경써주도록 합니다.

import { useEffect, useState } from "react";
import { getLanguageDetector } from "@/utils/languageDetector";

export const LanguageDetector = () => {
  const detectorRef = useRef<LanguageDetector | null>(null);
  const abortControllerRef = useRef<AbortController | null>(null);

  const [isLoading, setIsLoading] = useState(false);
  const [detectedLanguage, setDetectedLanguage] = useState<
    LanguageDetectionResult[]
  >([]);

  useEffect(() => {
    return () => {
      abortControllerRef.current?.abort();
    };
  }, []);

  const detectLanguage = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.target as HTMLFormElement);
    const text = formData.get("text") as string;

    try {
      setIsLoading(true);
      if (!detectorRef.current) {
        abortControllerRef.current = new AbortController();
        detectorRef.current = await getDetector(
          ["en"],
          abortControllerRef.current.signal
        );
      }

      const results = (await detectorRef.current?.detect(text)) ?? [];
      setDetectedLanguage(results);
    } catch (error) {
      console.error("Error detecting language", error);
    } finally {
      setIsLoading(false);
    }
  };
  return (
    <div>
      <form onSubmit={detectLanguage}>
        <input type="text" name="text" />
        <button type="submit">Detect</button>
      </form>
      {detectedLanguage.map((language) => (
        <div key={language.detectedLanguage}>
          {language.detectedLanguage}: {language.confidence}
        </div>
      ))}
    </div>
  );
};

참고

• AI on Chrome
• MDN - Language Detector
• Kangbit Blog

소개

Chrome 브라우저에는 AI가 내장되어 있으며, API를 통해 AI 기반 작업을 실행할 수 있도록 지원합니다.

Google은 이러한 API가 모든 브라우저에서 작동하도록 표준화하기 위해 노력하고 있습니다.

장점

자체 AI 모델을 배포하거나 관리할 필요 없이 AI 기반 기능을 제공할 수 있습니다.

사용자의 브라우저에서 실행되고 추론을 실행하기 때문에

지연 시간 감소, 사용자 개인 정보 보호 강화, 오프라인 액세스 등의 이점을 누릴 수 있습니다.

API 종류

개발 단계에 따라 사용할 수 있는 여러 API가 있습니다.

일부 API는 Chrome 안정화 버전에 있지만,

일부는 오리진 트라이얼에서 모든 개발자가 사용할 수 있고,

일부는 초기 미리보기 프로그램 (EPP) 참여자만 사용할 수 있습니다.

하드웨어 요구사항

일부 API는 휴대기기에서 작동하지 않으며

운영체제나 저장소 용량, GPU 또는 CPU, 네트워크 조건을 충족해야 할 수 있습니다.

이 조건은 여기서 확인할 수 있습니다.

주의사항

특정 용도에 맞게 만들기

내장 AI는 서버에서 실행되는 보통의 AI보다 작습니다.

특정 작업에서는 서버 측 모델보다 성능이 우수할 수 있지만,

일반적인 작업에서는 성능이 떨어질 수 있습니다.

다운로드 크기 고려하기

AI 모델은 크기가 커서 모바일 데이터와 저장 공간을 많이 사용할 수 있습니다.

상호작용 필요

내장 AI API를 지원하지만 모델이 아직 다운로드되지 않은 경우,

모델을 다운로드 하기 위해서는 페이지 로드가 완료된 후 사용자가 페이지와 직접 상호작용해야 합니다.

이러한 상호작용 없이 모델을 다운로드 하려고 하면 다음과 같은 오류가 발생할 수 있습니다.

NotAllowedError: Requires a user gesture when availability is "downloading" or "downloadable"

참고

• AI on Chrome
• Kangbit Blog

PIP-TOOLS

브라우저의 Picture-in-Picture 기능을 활용해서 만든 도구 모음을 소개합니다.

도구 아이콘을 클릭하면 PIP 모드로 열립니다.

가끔 색상 선택기를 사용할 때 브라우저 창(혹은 탭) 을 옮겨야 하는 불편한 경우가 있어 만들게 되었습니다.

현재 지원하는 기능은 다음과 같습니다.

• 시계: 현재 시간 표시
• 타이머: 카운트다운 타이머
• 색상 선택기: 색상 코드 추출 및 복사
• 이미지 리사이즈: 이미지 크기 조절
• 번역기: 다국어 번역 ( 크롬 번역 API 활용 )
• 메모: 간단한 텍스트 메모
• 룰렛: 랜덤 선택 게임

계산기, 단위 변환기, 스크립터, 이미지 워터마크 등을 추가할 계획중에 있고,

좌측 하단의 버튼을 통해 의견 주시면, 적극 반영하겠습니다.

필요한 도구가 있다면 의견 부탁드려요.

감사합니다.

Next.js React TypeScript react-document-pip

Document Picture in Picture API는 아직 실험적 기능입니다. ( 2025-07 ) 일부 브라우저에서 동작하지 않을 수 있습니다. CanIUse 에서 브라우저별 지원 현황을 확인할 수 있습니다.

Secure Context 에서만 사용할 수 있습니다.

BitPage - Document PIP 를 먼저 읽으시면 내용을 이해하는 데 도움이 됩니다.

BitPage - react pip에서도 확인할 수 있습니다.

react-document-pip를 이용하면, 구현된 컴포넌트를 쉽게 사용할 수 있습니다.

React에서의 Document PIP

Document PIP - HTML에서는 DOM 요소를 직접 선택하여 PIP 창으로 이동시켰습니다.

const element = document.getElementById("my-element");
pipWindow.document.body.appendChild(element);

하지만 DOM Element만 복사해서는 컴포넌트의 상태나 이벤트를 활용할 수 없습니다.

따라서 아래의 방법을 사용합니다.

PIP에 새로운 React 앱 마운트하기

PIP 창에 독립적인 React 앱을 렌더링할 수 있습니다.

다음과 같은 모습이 될 것 같습니다.

export const useDocumentPIP = (
  width: number,
  height: number,
  component: React.ComponentType
) => {
  const openPIPWindow = async () => {
    const pip = await window.documentPictureInPicture.requestWindow({
      width,
      height,
    });

    const appDiv = pip.document.createElement("div");
    appDiv.id = "pip-app";
    pip.document.body.appendChild(appDiv);

    const root = createRoot(pip.document.getElementById("pip-app")!);
    root.render(React.createElement(component));
  };

  return {
    openPIPWindow,
  };
};

이 방법으로도 어떤 컴포넌트에서는 충분할 것 같습니다.

하지만 외부 상태에 영향을 받는 컴포넌트라면 다음 방법을 사용하는 것이 나을 것 같습니다.

PIP로 Portal 하기

목표

React Portal을 이용하면 동일한 인스턴스에서 컴포넌트를 렌더링할 수 있습니다.

동일한 인스턴스에 존재하기 때문에 Store에도 간단히 접근할 수 있고,

다음과 같이 간단하게 props를 전달하고 event를 청취할 수 있습니다.

<>
  <MyComponent someProp={someProp} onSomeEvent={handleSomeEvent} />
  {createPortal(
      <MyComponent someProp={someProp} onSomeEvent={handleSomeEvent} />,
      pipRoot
  )}
</>

재사용성을 위해 DocumentPIP 컴포넌트를 만들고, children을 활용해 PIP 창에 렌더링하겠습니다.

이렇게 사용하는 것이 목표입니다.

return (
  <DocumentPIP isPipOpen={isPipOpen} size={{ width: 500, height: 200 }}>
    <PipContent />
  </DocumentPIP>
);

PIP 창 열기

먼저 PIP 창을 열고 컴포넌트가 Portal될 요소를 준비해야 합니다.

function DocumentPIP() {
  const openPIPWindow = async () => {
    const pip = await window.documentPictureInPicture.requestWindow({
      width: 500,
      height: 200,
    });

    const rootDiv = pip.document.createElement("div");
    rootDiv.id = "pip-root";
    pip.document.body.appendChild(rootDiv);
  };
}

우리는 이 pip 창이 열렸을 때 다음과 같이 컴포넌트를 조건부로 렌더링해야 합니다.

function DocumentPIP({ children }) {
  // ...

  if (pipRoot) {
    return createPortal(children, pipRoot);
  }

  return children;
}

pipRoot가 변경되었을 때 컴포넌트가 다시 렌더링되어야 합니다.

다음과 같이 수정하겠습니다.

function DocumentPIP({ children, isPipOpen }) {
  const [pipWindow, setPipWindow] = useState(null);

  const openPIPWindow = async () => {
    const pip = await window.documentPictureInPicture.requestWindow({
      width: 500,
      height: 200,
    });

    const rootDiv = pip.document.createElement("div");
    rootDiv.id = "pip-root";
    pip.document.body.appendChild(rootDiv);

    setPipWindow(pip);
  };

  const pipContent = () => {
    const pipRoot = pipWindow?.document.getElementById("pip-root");
    if (!pipRoot || !isPipOpen) {
      return children;
    }

    return createPortal(children, pipRoot);
  };

  return pipContent();
}

이제 props의 변화를 감지하고, 그 값에 따라 PIP 창을 열고 닫습니다.

function DocumentPIP({ children, isPipOpen }) {
  // ...

  useEffect(() => {
    togglePictureInPicture(isPipOpen);
  }, [isPipOpen]);

  const togglePictureInPicture = (open: boolean) => {
    if (open) {
      openPIPWindow();
    } else {
      closePIPWindow();
    }
  };

  const openPIPWindow = async () => {
    // ...
  };

  const closePIPWindow = () => {
    pipWindow.close();
    setPipWindow(null);
  };
}

Styled Component 사용하기

styled-components를 사용하고 있다면, 전체 스타일을 pipWindow로 복사하지 않아도 됩니다.

StyleSheetManager를 이용해 pipWindow에 스타일을 주입할 수 있습니다.

import { StyleSheetManager } from "styled-components";

const pipContent = () => {
  // ...

  return createPortal(
    <StyleSheetManager target={pipWindow?.document.head}>
      {children}
    </StyleSheetManager>,
    pipRoot
  );
};

전체 코드

전체 코드는 BitPage에서 확인할 수 있습니다.

참고 자료

• React Portal
• MDN
• Chrome for developers
• Can I Use

Document Picture in Picture API는 아직 실험적 기능입니다. ( 2025-07 ) 일부 브라우저에서 동작하지 않을 수 있습니다. CanIUse 에서 브라우저별 지원 현황을 확인할 수 있습니다.

Secure Context 에서만 사용할 수 있습니다.

BitPage - Document PIP 를 먼저 읽으시면 내용을 이해하는 데 도움이 됩니다.

BitPage - vue pip에서도 확인할 수 있습니다.

vue-pip를 이용하면, 구현된 컴포넌트를 쉽게 사용할 수 있습니다.

Vue에서의 Document PIP

Document PIP - HTML에서는 DOM 요소를 직접 선택하여 PIP 창으로 이동시켰습니다.

const element = document.getElementById("my-element");
pipWindow.document.body.appendChild(element);

하지만 Vue의 반응성이나 이벤트를 활용하기 위해서는 다른 방법을 사용해야 합니다.

PIP에 새로운 Vue 앱 마운트하기

PIP 창에 독립적인 Vue 앱을 마운트 할 수 있습니다.

다음과 같은 모습이 될 것 같습니다.

export const useDocumentPIP = (
  width: number,
  height: number,
  component: Component
) => {
  //...
  const openPIPWindow = async () => {
    const pip = await window.documentPictureInPicture.requestWindow({
      width,
      height,
    });

    const appDiv = pip.document.createElement('div');
    appDiv.id = 'pip-app';
    pip.document.body.appendChild(appDiv);

    const pipApp = createApp(component);
    pipApp.mount(pip.document.getElementById("pip-app")!);
  };

  return {
    openPIPWindow,
  };
};

이 방법으로도 어떤 컴포넌트에서는 충분할 것 같습니다.

하지만 외부 상태에 영향을 받는 컴포넌트라면 다음 방법을 사용하는 것이 나을 것 같습니다.

PIP로 Teleport 하기

목표

Teleport를 이용하면 동일한 인스턴스에서 컴포넌트를 렌더링 할 수 있습니다.

동일한 인스턴스에 존재하기 때문에 Store에도 간단히 접근할 수 있고,

다음과 같이 간단하게 props를 전달하고 event를 청취할 수 있습니다.

<template>
  <MyComponent @someEvent="handleSomeEvent" :someProp="someProp" />
  <Teleport :to="pipTarget">
    <MyComponent @someEvent="handleSomeEvent" :someProp="someProp" />
  </Teleport>
</template>

재사용성을 위해 DocumentPip 컴포넌트를 만들고, slot을 활용해 PIP 창에 렌더링하겠습니다.

이렇게 사용하는 것이 목표입니다.

<template>
  <DocumentPip :isPipOpen="isPipOpen" :size="{ width: 500, height: 200 }">
    <PipContent />
  </DocumentPip>
</template>

PIP 창 열기

먼저 PIP 창을 열고 컴포넌트가 Teleport될 요소를 준비해야 합니다.

<script setup lang="ts">
const openPIPWindow = async () => {
  const pip = await window.documentPictureInPicture.requestWindow({
    width: 500,
    height: 200,
  });

  const rootDiv = pip.document.createElement("div");
  rootDiv.id = "pip-root";
  pip.document.body.appendChild(rootDiv);

  const pipRoot = pip.document.getElementById("pip-root"); // Teleport Target
};
</script>

우리는 이 pip 창이 열렸을 때 다음과 같이 컴포넌트를 조건부로 렌더링해야 합니다.

<template>
  <slot v-if="!pipRoot"></slot>
  <Teleport v-else :to="pipRoot">
    <slot></slot>
  </Teleport>
</template>

pipRoot가 변경되었을 때 컴포넌트가 다시 렌더링되어야 합니다.

다음과 같이 수정하겠습니다.

<script setup lang="ts">
const pipWindow = ref<Window | null>(null);
const pipRoot = computed(() => {
  return pipWindow.value?.document.getElementById("pip-root") || null;
});

const openPIPWindow = async () => {
  const pip = await window.documentPictureInPicture.requestWindow({
    width: 500,
    height: 200,
  });

  const rootDiv = pip.document.createElement("div");
  rootDiv.id = "pip-root";
  pip.document.body.appendChild(rootDiv);

  pipWindow.value = pip;
};
</script>

이제 props의 변화를 감지하고, 그 값에 따라 PIP 창을 열고 닫습니다.

<script setup lang="ts">
// ...

watch(
  () => props.isPipOpen,
  (newVal: boolean) => {
    togglePictureInPicture(newVal);
  }
);

const togglePictureInPicture = (isPipOpen: boolean) => {
  if (isPipOpen) {
    openPIPWindow();
  } else {
    closePIPWindow();
  }
};

const openPIPWindow = async () => {
  // ...
};

const closePIPWindow = () => {
  pipWindow.value.close();
  pipWindow.value = null;
};
</script>

전체 코드

전체 코드는 BitPage에서 확인할 수 있습니다.

참고 자료

• Vue Teleport
• MDN
• Chrome for developers
• Can I Use

Picture in Picture (PIP)는 사용자가 다른 작업을 수행하면서도 특정 콘텐츠를 계속 볼 수 있도록 도와주는 기능입니다.

기존에는 주로 동영상 재생 시에 활용되어, 사용자가 웹 서핑이나 문서 작업을 하면서도 영상을 계속 시청할 수 있게 해주었습니다.

이 작은 팝업 창은 항상 다른 창들 위에 떠 있어서 필요한 정보를 지속적으로 제공합니다.

Document Picture In Picture

Document PIP API의 등장으로 이제는 웹 문서 전체를 작은 창으로 분리할 수 있게 되었습니다.

이는 단순한 비디오 재생을 넘어서, 채팅창, 대시보드, 문서 편집기 등 다양한 웹 애플리케이션을 독립적인 창으로 분리하여 멀티태스킹을 극대화할 수 있게 해줍니다.

Document PIP의 핵심은 콘텐츠의 완전한 이동과 스타일의 완벽한 복사에 있습니다.

사용자가 보고 있던 화면의 특정 부분을 그대로 PIP 창으로 이동시키고, 모든 스타일시트를 복사하여 원본과 동일한 모습을 유지할 수 있습니다.

예제와 함께 보기

여기서 설명하는 캐러셀은 최신 브라우저에서만 작동합니다. CanIUse 에서 브라우저별 지원 현황을 확인할 수 있습니다.

BitPage 에서는 예제와 함께 확인할 수 있습니다.

캐러셀이란?

캐러셀은 여러개의 컨텐츠를 슬라이드 형태로 보여주는 UI 요소입니다.

캐러셀은 보통 자동으로 슬라이드되거나 드래그를 통해 컨텐츠를 이동하지만,

좌우 버튼이나 페이지네이션을 포함하여 특정 컨텐츠로 이동할 수도 있습니다.

기존에도 javascript 없이 캐러셀을 구현할 수 있지만,

좌우 버튼이나 페이지네이션을 포함시킬 수는 없었습니다.

Chrome 135부터는 CSS Overflow Module Level 5을 사용하여

css만으로 좌우 버튼과 페이지네이션을 포함하는 캐러셀을 구현할 수 있습니다.

이 포스트에서는 이 기능을 사용하여 캐러셀을 구현하는 방법을 소개합니다.

캐러셀 예제

CSS Carousel Gallery 에서는 CSS로 만든 다양한 캐러셀 예제를 확인할 수 있습니다.

캐러셀 만들기

우선, 기본적인 형태의 캐러셀을 만들어 보겠습니다.

<div class="scroll-layout">
  <ul class="carousel">
    <li class="carousel-item"></li>
    <li class="carousel-item"></li>
    <li class="carousel-item"></li>
    <li class="carousel-item"></li>
    <li class="carousel-item"></li>
    <li class="carousel-item"></li>
    <li class="carousel-item"></li>
    <li class="carousel-item"></li>
    <li class="carousel-item"></li>
    <li class="carousel-item"></li>
  </ul>
</div>

li {
  list-style-type: none;
}

.scroll-layout {
  width: 100vw;
  display: flex;
  justify-content: center;
}

.carousel {
  width: 80%;
  display: grid;
  grid: 30vmin / auto-flow 40%;
  gap: 15px;
  padding: 0;
  margin: 0;

  overflow-x: auto;
  scroll-snap-type: x mandatory;
  scroll-behavior: smooth;
  scrollbar-width: none;
}

.carousel-item {
  border: 3px solid #888;
  scroll-snap-align: center;
}

좌우 버튼 추가하기

::scroll-button의사 요소를 이용해 캐러셀에 좌우 버튼을 추가할 수 있습니다.

.carousel {
  &::scroll-button(*) {
    position: fixed;
    position-anchor: --carousel;

    width: 48px;
    height: 48px;
    border-radius: 50%;
    border: 2px solid #999;

    margin: 5px;
  }

  &::scroll-button(left) {
    position-area: inline-start center;
    content: "⬅" / "Scroll Left";
  }

  &::scroll-button(right) {
    position-area: inline-end center;
    content: "⮕" / "Scroll Right";
  }
}

좌우 버튼은 기본적으로 스크롤 영역의 85% 를 스크롤합니다.

하나의 컨텐츠씩 스크롤하려면 아래와 같이 설정합니다.

.carousel-item {
  scroll-snap-stop: always;
}

페이지네이션 추가하기

::scroll-marker-group 의사 요소와

::scroll-marker 의사 요소를 이용해 페이지네이션을 추가할 수 있습니다.

.carousel {
  scroll-marker-group: after;

  &::scroll-marker-group {
    position: fixed;
    position-anchor: --carousel;
    position-area: block-end;

    display: grid;
    place-content: safe center;
    grid: 16px / auto-flow 16px;
    gap: 15px;
    padding: 15px;
  }
}

.carousel-item {
  &::scroll-marker {
    content: " ";

    border: 1px solid #bbb;
    border-radius: 50%;
    outline-offset: 4px;
  }

  &::scroll-marker:is(:hover, :focus-visible) {
    border-color: LinkText;
  }

  &::scroll-marker:target-current {
    background: LinkText;
    border-color: LinkText;
  }
}

참고

• CSS Overflow Module Level 5
• CSS Carousels with CSS
• CSS Carousel Configurator
• CSS Carousel Gallery

https://kangbit.github.io/posts/watermark-folderaction/

Vue3의 Composition Api에서 반응형 상태를 선언하는 방법은 ref와 reactive 두가지가 있습니다.

두 방법이 존재하다 보니 어떤 방법을 사용할지 헷갈려 하는 경우가 많습니다.

이 글이 생각을 정리하는 데 도움이 되었으면 좋겠습니다.

결론만 보고 싶은 분은 그래서 뭐 쓰라고 로 이동해주세요

공식 문서의 제안

공식 문서에서는 반응형 기초를 설명하는 첫 줄에서 ref를 사용할 것을 권장하고 있습니다.

reactive의 제한사항을 설명하면서도 ref를 기본으로 사용하기를 권장합니다.

그렇다면 reactive는 필요 없는 것 아닐까요?

ref와 reactive의 특징에 대해 살펴보면서 더 알아보겠습니다.

ref

1. value 속성

ref 객체는 value 속성을 갖습니다.

const count = ref(0)

console.log(count) // { value: 0 }
console.log(count.value) // 0

이 때문에 반응성 값임을 쉽게 확인할 수 있어서 선호한다는 의견이 있는 반면,

.value로 접근하는 것이 번거로워 ref를 선호하지 않는다는 의견도 있습니다.

확실히 다음과 같은 코드는 상당히 부자연스러워 보일 수 있습니다.

const arr = ref([1,2,3]);
arr.value.push(4)

2. 깊은 반응성

ref 는 깊게 반응합니다.

중첩된 객체나 배열이 변경되어도 적절하게 변경을 감지합니다.

다음과 같이 isReactive를 통해 확인해 보면,

객체 내부의 속성중 객체 유형은 reactive를 통해 Proxy 객체로 반환되는 것을 확인할 수 있습니다.

const obj = ref({property: [1,2,3], property2: 4});

console.log(isReactive(obj)); // false
console.log(isReactive(obj.value)); // true
console.log(isReactive(obj.value.property)); // true
console.log(isReactive(obj.value.property2)); // false

reactive

1. 객체 유형만 가능

reactive는 객체 유형에만 작동합니다.

간혹 이 내용을 보고 객체 유형에는 reactive를 사용해야 한다는 오해를 하시는 분도 있는 것 같습니다.

2. 깊은 반응성

ref와 마찬가지로 깊은 반응성을 제공합니다.

3. 전체 객체를 대체할 수 없음

다음과 같이 객체 전체를 대체하려고 하면 reactive 객체에 대한 반응성이 끊기게 됩니다.

let user = reactive({ name: 'Kim', age: 30 });
user = reactive({ name: 'Kim', age: 30 });

따라서, 전체 객체를 대체해야 할 필요가 있는 경우에 다음과 같이 사용하게 되는데,

const data = reactive({ user: { name: 'Kim', age: 30 } });
data.user = { name: 'Kim', age: 30 } ;

ref를 사용하는 게 더 나아 보입니다.

const user = ref({ name: 'Kim', age: 30 });
user.value = { name: 'Kim', age: 30 };

4. 분해 할당에 친화적이지 않음

공식문서의 reactive의 제한 사항에서는 분해 할당에 친화적이지 않다는 내용이 있습니다.

그렇다면 과연 reactive만 분해 할당에 친화적이지 않을지

다음 예제를 통해 살펴보면,

<script setup>
import { ref, reactive } from "vue";

// Vue에서 ref와 reactive 사용 예제
const refData = ref({ number: 1 });
const reactiveData = reactive({ number: 1 });

// 객체 속성을 개별 변수로 추출하며 반응성 유지
let { number: refNumber } = refData.value; // ref에서 값 추출
let { number: reactiveNumber } = reactiveData; // reactive에서 값 추출

const incrementValues = () => {
  refData.value.number++;
  reactiveData.number++;
};
</script>

<template>
<div class="example">
  <div>
    <button @click="incrementValues">Increment Values</button>
  </div>
  <p>ref: {{ refData }}, refNumber: {{ refNumber }}</p>
  <p>reactive: {{ reactiveData }}, reactiveNumber: {{ reactiveNumber }}</p>
</div>
</template>

ref 또한 분해할당에 친화적이지 않은 것을 볼 수 있습니다.

다만, ref와 reactive 모두 toRefs를 통해 반응성을 유지할 수 있습니다.

// const refNumber = toRef(refData.value, "number"); // 반응성 유지
const { number: refNumber } = toRefs(refData.value); // 반응성 유지
const { number: reactiveNumber } = toRefs(reactiveData); // 반응성 유지

그래서 뭐 쓰라고

사실 무엇을 사용해도 크게 문제되지 않습니다.

나만의 규칙을 만들어 보세요.

• 공식문서에서 제안하고 있으니 ref를 기본으로 사용하고 특수한 상황에서만 reactive를 사용한다.

• 원시 타입에만 ref를 사용하고 객체 유형은 reactive를 사용한다.

• 헷갈리지 않게 ref만 사용한다.

• 헷갈리지 않게 reactive만 사용한다.

• .value 가 보기 싫으니 reactive를 사용한다.

프로젝트에 합류했다면 규칙을 따르고, 확신이 있다면 규칙을 수정할 것을 제안해 보세요.

확실한 기준을 세우기

어떤 기준으로 직면한 문제를 해결할지 고민하는 순간이 많이 찾아옵니다.

프로젝트 큐모에 맞는 폴더 구조를 선택하는 것부터,

새로운 기술 도입이 우리 조직과 프로젝트에 적합한지를 판단하는 기준까지 깊이 있는 고민이 필요합니다.

코드의 중복을 어느 선까지 허용할지,

낮은 결합도를 위해 의도적으로 중복을 허용하는 때는 언제일지 고민해야 합니다.

이런 기준들을 세우고 제시할 수 있게 되는 것이 개발자로서 성장하는 길 중 하나가 아닐까 합니다.

https://kangbit.github.io/posts/vue-reactivity/

이 글은 VitePress의 실험적인 기능을 포함합니다

Sitemap 생성

Vitepress에서는 사이트맵 생성을 지원합니다.

아래와 같이 /.viteprss/config.mjs에 sitemap을 작성합니다.

export default defineConfig({
  sitemap: {
    hostname: "https://{userName}.github.io/",
  },
});

이후에 빌드를 해보면 다음과 같이 sitemap.xml 파일이 포함되어 있는 것을 볼 수 있습니다.

이 사이트맵을 Google Search Console과 Naver 웹마스터 도구에 등록하면

구글과 네이버의 검색 결과에 내 블로그의 콘텐츠를 노출할 수 있습니다.

Google 검색 엔진에 등록

Google Search Console 에 점속해서 내 블로그의 URL을 입력합니다.

입력 후 계속 버튼을 클릭하면 홈페이지의 소유권을 확인하기 위한 화면이 나타납니다.

저는 Google 애널리틱스를 통해 소유권을 인증하겠습니다.

구글 애널리틱스에 접속해서 계정과 속성을 생성 후, 태그 ID를 확인합니다.

태그 ID를 생성하고 확인하는 설명은 링크로 대체하겠습니다.

1.웹사이트 및 앱용 애널리틱스 설정
2.설정 어시스턴스를 사용하여 GA4 속성 구성하기
3.Google 태그 ID 찾기

태그 ID를 찾았다면, 다음 스크립트를 /.viteprss/config.mjs에 삽입합니다.

export default defineConfig({
  head: [
    [
      "script",
      {
        async: "",
        src: "https://www.googletagmanager.com/gtag/js?id={태그 ID}", // 태그 ID
      },
    ],
    [
      "script",
      {},
      `window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', '{태그 ID}');`, // 태그 ID
    ],
  ],
});

배포를 진행한 후, Google Search Console으로 돌아가 확인을 누르면 다음과 같은 팝업을 화인할 수 있습니다.

속성으로 이동 버튼을 클릭해 속성 페이지로 이동합니다.

좌측 메뉴의 Sitemaps 메뉴를 통헤 페이지에 진입한 후, 사이트맵의 주소를 입력합니다.

제출이 완료되면, 제출된 사이트맵에 다음과 같이 노출됩니다.

Naver 검색 엔진에 등록

Naver Search Advisor에 접속해서 내 블로그의 URL을 입력합니다.

구글과 마찬가지로 홈페이지의 소유권을 확인하기 위한 화면이 나타납니다.

HTML 태그를 통해 소유권을 확인하도록 하겠습니다.

content를 복사해서 /.viteprss/config.mjs에 스크립트를 삽입해 줍니다

export default defineConfig({
  head: [
    ...,
    [
      "meta",
      {
        name: "naver-site-verification",
        content: '{content}',
      },
    ],
  ],
});

배포 후 소유확인 버튼을 누르면 다음과 같은 팝업을 확인할 수 있습니다.

요청 > 사이트맵 제출 메뉴로 이동하여 사이트맵 URL을 입력해 줍니다.

며칠 기다리면, 네이버 검색에 내 블로그가 노출되는 것을 확인할 수 있습니다.

VitePress + Github Pages로 블로그 만들기 - SEO

VitePress | Vite & Vue로 구동되는 정적 사이트 생성기

.github/workflows 폴더를 생성 후 deplay.yml 파일을 생성해 줍니다

deploy.yml 파일에 공식 문서에 있는 샘플 워크플로우를 복사해서 붙여줍니다.

다만 우리는 공식 문서의 가이드와는 폴더 구조가 다르기 때문에 Upload artifact 설정을 수정해 주어야 합니다.

jobs:
  # 빌드 작업
  build:
    runs-on: ubuntu-latest
    steps:
      ...
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: .vitepress/dist 
          # path: docs/.vitepress/dist 

Github 저장소에 소스 코드 올리기

우선 새로운 저장소를 생성해 줍니다.

이 때 저장소의 이름을 {username}.github.io/ 로 해주지 않으면,

블로그의 주소가 https://{username}.github.io/{RepositoryName} 이 됩니다.

주소에 RepositoryName이 포함되게 되면 SEO 설정 시에 어려움이 있을 수 있습니다.

생성된 저장소의 설정을 수정해 줍니다.

이제 터미널을 통해 저장소에 소스 코드를 업로드합니다.

$ git init
$ git add --all
$ git commit -m "first commit"
$ git branch -M main
$ git remote add origin {깃허브 저장소 주소}
$ git push -u origin main

업로드 후에 저장소의 Actions 페이지에 접근해 보면, 배포 상황을 확인할 수 있습니다.

위와 같이 배포가 성공적으로 완료되었다면, https://{username}.github.io/로 접근해서 홈페이지를 확인할 수 있습니다.

전체 코드

전체 코드는 https://github.com/KangBit/kangbit.github.io 에서 확인할 수 있습니다.

VitePress + Github Pages로 블로그 만들기 - 배포

VitePress | Vite & Vue로 구동되는 정적 사이트 생성기

Node version: v20.11.1
Vitepress version: v1.1.0

프로젝트 생성

프로젝트 폴더를 생성한 후 폴더 내부에서 터미널을 통해 다음 명령어를 입력합니다. 최신 버전의 vitepress 프로젝트를 생성합니다.

$ npx vitepress init

프로젝트를 생성하기 위한 몇가지 설정을 미리 해주어야 합니다.

설정 파일과 컨텐츠들이 위치할 폴더를 정합니다. 현재 디렉토리로 설정합니다.

◇  Where should VitePress initialize the config?
│  ./

블로그의 타이틀을 정합니다. 설정 파일에서 손쉽게 수정할 수 있으므로 무엇으로 하든 무방합니다.

◇  Site title:
│  MyBlog

블로그의 설명을 정합니다. ( html의 meta 태그로 렌더링 됩니다. ) 설정 파일에서 손쉽게 수정할 수 있으므로 무엇으로 하든 무방합니다.

◇  Site description:
│  My VitePress Blog

테마를 커스텀해서 사용할지 말지 정합니다. 저는 배포 후에 커스텀할 생각이므로 두번째 옵션을 선택했습니다.

◇  Theme:
│  ○ Default Theme
│  ● Default Theme + Customization
│  ○ Custom Theme

개인 블로그용이라면 타입스크립트까지는 필요하지 않을 것 같습니다.

◇  Use TypeScript for config and theme files?
│  No

프로젝트를 실행, 빌드, 프리뷰하기 위한 스크립트를 자동으로 작성하도록 합니다.

◇  Add VitePress npm scripts to package.json?
│  Yes

프로젝트를 완료하면 다음과 같은 팁이 나타나는데, 지금은 잊어도 좋습니다.

Tips:
- Since you've chosen to customize the theme, you should also explicitly install vue as a dev dependency.

프로젝트 실행

프로젝트 생성이 완료되었습니다. 이제 다음과 같은 구조로 프로젝트가 생성되었을 겁니다.

이제 터미널에서 프로젝트를 실행해 보겠습니다.

$ npm run docs:dev

다음과 같은 메세지가 나타나며 실행에 실패했다면, 정상입니다.

sh: vitepress: command not found

프로젝트에 vitepress를 설치해 주겠습니다.

$ npm install -D vitepress

다시 프로젝트를 실행하면

$ npm run docs:dev

프로젝트가 실행되고, 접속할 수 있는 주소가 나타납니다.

  vitepress v1.1.4

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

브라우저에서 해당 주소로 접속하면, 성공적으로 실행된 화면을 볼 수 있습니다.

폴더 구조 변경

생성된 프로젝트의 폴더 구조를 보면, 다음과 같습니다.

.md 확장자의 파일들은 블로그에 추가될 페이지들입니다. 최상위 디렉토리에 위치할 경우 페이지가 늘어날수록 관리하기 힘들 수 있습니다. 폴더를 만들어 넣어주도록 하겠습니다. 저는 pages로 폴더를 만들었습니다.

하지만 폴더 구조를 수정하니, 페이지에 접근할 수 없습니다.

페이지의 폴더 구조가 변경되었음을 프로젝트에 알려주어야 합니다. 설정 파일인 /.viteprss/config.mjs 에 srcDir을 추가해 주면,

export default defineConfig({
...
  srcDir: "./pages",
...
})

페이지에 다시 접근할 수 있습니다.

VitePress + Github Pages로 블로그 만들기 - 소개

VitePress | Vite & Vue로 구동되는 정적 사이트 생성기

2024년 3월 21일 VitePress가 release 되었습니다 VitePress는 빠르고 컨텐츠 중심의 웹사이트를 구축하기 위해 설계된 '정적 사이트 생성기' 입니다.

VitePress는 개인 블로그 뿐 아니라 팀 블로그를 구성하거나 가이드 문서로 사용하기에도 아주 좋은 도구로 보입니다.

왜 VitePress인가

개발자가 아니여도 쉽게 생성할 수 있고, 개발자라면 더 강력하고 아름다운 정적 사이트를 생성할 수 있습니다.

문서

문서가 깔끔하고 번역이 잘 되어있습니다.

Vite + Vue3 애플리케이션의 개발자 경험 지원

마크다운 내부에서도 Vue를 사용할 수 있습니다. Vue3에 익숙한 개발자라면 손쉽게 테마를 커스텀 할 수 있고, 다양한 컴포넌트를 생성해 마크다운 내부에서 사용할 수 있습니다.

레이아웃

네비게이션 바, 사이드 바, Anchor aside, 푸터를 쉽게 추가할 수 있습니다.

검색

검색 기능을 쉽게 추가할 수 있습니다.

코드 블록 기능

하이라이트, 포커싱, 라인 번호, 그룹화 등 다양한 코드 블록 기능을 제공합니다.

Git 연동 기능

editLink를 통해 페이지를 편집하는 링크를 표시할 수 있습니다. lastUpdated를 통해 각 페이지의 마지막 Git 업데이트 타임스탬프를 가져올 수 있습니다.

VitePress + Github Pages로 블로그 만들기 - 소개

VitePress | Vite & Vue로 구동되는 정적 사이트 생성기

우연히 접한 안드로이드 컨퍼런스 행사 소식!

친한 네이티브 개발자를 꼬셔서

4월 6일 역삼에서 진행한 'Native vs Flutter 그리고 KMP' 에 다녀왔습니다.

주요 세션

참가한 이유

네이티브 개발 경험이 있는 프론트엔드 개발자입니다.

평소에 '자원이 충분하다면 네이티브로 개발하는게 최고' 라고 생각하고 있었고,

다른 의견이 있다면 들어보고 싶었습니다.

또한 개발자로서 하고 있는 많은 선택에 대한 근거를 선명하게 하는 데 도움이 되지 않을까 했습니다.

후기

### '크로스 플랫폼 프레임워크 개발도 네이티브 개발에 대한 이해가 바탕이 되어야 한다'

'결국 네이티브 개발 공부를 하게 된다'

모든 세션에서 동일하게 나온 내용입니다.

크로스 플랫폼 프레임워크를 이용해 개발하더라도 결국에는 각각의 플랫폼 위에서 동작하게 되고,

플랫폼의 자원을 사용하게 됩니다.

따라서 플랫폼에 대한 이해가 바탕이 되어야만 더 잘 개발할 수 있습니다.

하지만, 우리에겐 동료라는 자원이 있습니다.

옆에 네이티브 개발에 대해 깊게 이해하고 있는 개발자가 있다면

당장은 플랫폼에 대한 이해도가 크지 않아도 될 겁니다.

### '네이티브급 성능이라는 말 자체가 결국 네이티브보다 좋은 성능을 가질 수 없다는 뜻이다'

주 세션 이후의 라이트닝 토크에서 언급되었지만, 행사 중 가장 인상깊었던 말입니다.

그동안 머리 속에서만 떠돌던 내용이 문장으로 정립되었습니다.

'급', '처럼' 이라는 말 안에 한계를 내포하고 있다라는 것.

위에서 이야기했듯이 결국은 플랫폼의 자원을 사용하게 되고,

이 자원을 사용하는 데 네이티브 앱보다 좋은 퍼포먼스를 내기는 쉽지 않을 겁니다.

하지만, 그렇게 큰 차이가 나지는 않습니다.

많은 경우에 이정도의 성능 차이가 큰 문제가 되지는 않을 겁니다.

### 결국엔 네이티브! 를 바탕으로 한 경험입니다.

개발 범위가 어느 정도이고 활용할 수 있는 자원이 어느 정도인지 판단할 수 있어야 합니다.

자원을 적절하게 활용할 수 있으면서도 요구조건을 구현하는 데 어려움이 없는 기술이 무엇일지 잘 선택해야 합니다.

프론트엔드에서도 선택해야 하는 것들이 상당히 많아졌습니다.

React vs Vue vs Angular, CSR vs SSR vs SSG, TS 사용 여부, 테스트 코드 작성 여부 등등.

마찬가지로, 틀린 기술은 없습니다.

충분히 작은 프로젝트에 React를 사용할 필요가 있을까요?

충분하지 않은 시간 내에 개발해야 하고 유지보수되지 않을 프로젝트에 TS나 테스트 코드를 적용해야 할까요? (물론, 프로젝트 규모에 따라서 필요할 수 있습니다)

상황에 맞는 기술을 선택할 수 있도록 경험을 쌓고 안목을 길러야 합니다.

행사 정보

이를 위해 스크롤이 페이지 하단에 도달했음을 감지해서 데이터를 불러오는 로직이 필요합니다

이런 로직이 여러 페이지에서 반복되지 않도록 하기 위해 composable로 분리한 내용을 공유합니다

vue3 + typescript 로 작성했지만, 원활한 이해를 돕기 위해 초반 설명은 typescript 없이 진행합니다

테스트용 API 주소는 JSONPlaceholder 를 활용했습니다

주 기능 구현

이렇게 사용하고 싶습니다

컨테이너와 주소를 파라미터로 전달하면,

컨테이너 하단에 도달했을 때 자동으로 업데이트 되는 리스트를 반환해야 합니다

const { list } = useScrollLoad(scrollContainer, url);

API 사양에 따라 페이징 방법이 다를 수 있으므로 주소는 함수의 반환값으로 전달하도록 하겠습니다

JSONPlaceholder를 활용한 주소는 다음과 같습니다

const { list } = useScrollLoad(scrollContainer, (start, size) => {
  return `https://jsonplaceholder.typicode.com/todos?_start=${start}&_limit=${size}`;
});

구현

데이터를 로드하는 함수를 마운트되었을 때 한번 호출합니다

// @/composilbes/scrollLoad.js
import { onMounted, onUnmounted, ref, unref } from "vue";

export const useScrollLoad = (scrollContainer, url) => {
  const size = 10;

  const start = ref(0);
  const list = ref([]);

  const loadMore = () => {
    start.value = start.value + size;
    load();
  };

  const load = () => {
    fetchData();
  };

  const fetchData = () => {
    fetch(url(start.value, size))
      .then((res) => res.json())
      .then((res) => {
        list.value.push(...res);
      });
  };

  onMounted(() => {
    load();
  });
}

스크롤이 하단에 도달하는 이벤트를 감지하기 위해 이벤트 리스너를 추가합니다

  // 컨테이너가 ref인 것으로 가정합니다
  // 뒤에서 ref가 아닌 경우를 다루겠습니다
  onMounted(() => {
    load();
    scrollContainer.value.addEventListener("scroll", handleScrollEvent);
  });
  onUnmounted(() => {
    scrollContainer.value.removeEventListener("scroll", handleScrollEvent);
  });

  const handleScrollEvent = (e) => {
    const bottom = getScrollRest(e.target);
    if (bottom === 0) {
      loadMore();
    }
  };

  // 스크롤 영역 최하단까지의 남은 거리를 구합니다
  const getScrollRest = (element) => {
    const clientHeight = element.clientHeight;
    const scrollHeight = element.scrollHeight;
    const scrollTop = element.scrollTop;

    return scrollHeight - scrollTop - clientHeight;
  };

이제, 다음과 같이 사용할 수 있습니다

<!-- @/components/ScrollBox.vue -->
<template>
  <div class="container" ref="scrollContainer">
    <div v-for="(item, idx) in list" :key="idx">
      <p>{{ item.title }}</p>
    </div>
  </div>
</template>

<script setup>
import { useScrollLoad } from "@/composibles/scrollLoad";
import { ref } from "vue";

const scrollContainer = ref(null);

const { list } = useScrollLoad(scrollContainer, (start, size) => {
  return `https://jsonplaceholder.typicode.com/todos?_start=${start}&_limit=${size}`;
});
</script>

여기까지 완성된 코드는 GITHUB에서 확인할 수 있습니다

컨테이너가 window라면?

스크롤이 적용되는 컨테이너가 항상 ref로 주어지진 않을 것 같습니다

window로 한번 적용해보겠습니다

const { list } = useScrollLoad(window, (start, size) => {
  return `https://jsonplaceholder.typicode.com/todos?_start=${start}&_limit=${size}`;
});

useScrollLoad 로 전달되는 scrollContainer 는 더이상 ref가 아니므로 다음과 같이 수정할 수 있습니다

  onMounted(() => {
    scrollContainer.addEventListener("scroll", handleScrollEvent);
  });

하지만 ref로 전달되는 경우도 배제할 수 없습니다

다시 수정합니다

  onMounted(() => {
    const el = unref(scrollContainer);

    if (el) {
      load();
      el.addEventListener("scroll", handleScrollEvent);
    }
  });

  onUnmounted(() => {
    const el = unref(scrollContainer);

    if (el) {
        el.removeEventListener("scroll", handleScrollEvent);
    }
  });

handleScrollEvent에서 event.target 을 잘 찾지 못합니다

다음과 같이 수정합니다

  const handleScrollEvent = (e) => {
    let el = e.target;
    if (el.documentElement) {
      el = el.documentElement;
    }

    const bottom = getScrollRest(el);
    if (bottom === 0) {
      loadMore();
    }
  };

여기까지 완성된 코드는 GITHUB에서 확인할 수 있습니다

Typescript 적용

설명을 위해 빼두었던 Typescript를 다시 적용해보겠습니다

...
import type { Ref } from "vue";

type ContainerType = HTMLElement | Window | Document | null;

export const useScrollLoad = (
  scrollContainer: ContainerType | Ref<ContainerType>,
  url: (start: number, size: number) => string
) => {
  ...
  const list: Ref<any[]> = ref([]); // `any`가 조금 거슬립니다 뒤에서 수정하도록 하겠습니다
  ...
  const getScrollRest = (element: HTMLElement) => {
    ...
  }
  ...
}

아래에서는 오류가 발생합니다 HTMLElement는 documentElement를 프로퍼티로 가지지 않습니다

  const handleScrollEvent = (e: Event) => {
    const element = e.target as HTMLElement;
    if (element.documentElement) {        // ts Error!!
      element = element.documentElement;  // ts Error!!
    }

    const bottom = getScrollRest(element);
    if (bottom === 0) {
      loadMore();
    }
  };

다음처럼 변경합니다

  const handleScrollEvent = (e: Event) => {
    let element = e.target as HTMLElement;
    if ((e.target as Document).documentElement) {
      element = (e.target as Document).documentElement as HTMLElement;
    }

    const bottom = getScrollRest(element);

    if (bottom === 0) {
      loadMore();
    }
  };

이제 다시 정상적으로 동작합니다!

그럼 이제 위에서 신경쓰였던 any를 수정해 보겠습니다

// @/composilbes/scrollLoad.ts
export const useScrollLoad =  <ListItem>(
  scrollContainer: ContainerType | Ref<ContainerType>,
  url: (start: number, size: number) => string
) => {
  ...
  const list: Ref<ListItem[]> = ref([]); 
  ...
}

// @/components/ScrollBox.vue
type ListItem = {
  id: number;
  userId: number;
  title: string;
  completed: boolean;
};

const { list } = useScrollLoad<ListItem>(window, (start, size) => {
  return `https://jsonplaceholder.typicode.com/todos?_start=${start}&_limit=${size}`;
});

여기까지 완성된 코드는 GITHUB에서 확인할 수 있습니다

개선

최하단에 도달하기 전에 미리 데이터 불러오기

스크롤이 바닥에 닿기를 기다렸다가 데이터를 불러오면 사용자는 데이터를 불러오는 시간을 기다려야 합니다

조금 이른 시점에 새로운 컨텐츠를 미리 로드할 수 있도록 수정합니다

const handleScrollEvent = (e: Event) => {
  let element = e.target as HTMLElement;
  if ((e.target as Document).documentElement) {
    element = (e.target as Document).documentElement as HTMLElement;
  }

  const bottom = getScrollRest(element);
  if (bottom < element.clientHeight * 2) { // 수정됨
    loadMore();
  }
};

그런데 이게 웬걸, 한번에 여러번의 api 호출이 발생합니다

새로운 컨텐츠가 추가되어서 스크롤 영역이 넓어지기도 전에 또다른 스크롤 이벤트가 발생하기 때문입니다

데이터를 가져오는 동안에는 새로운 데이터를 요청하지 않도록 합니다

const isLoading = ref(false);

const loadMore = () => {
  if (isLoading.value) {
    return;
  }
  ...
}

const fetchData = () => {
  isLoading.value = true;
  fetch(url(start.value, size))
      .then((res) => res.json())
      .then((res) => {
        list.value.push(...res);
      })
      .catch((err) => {
        start.value = start.value - size;
      })
      .finally(() => {
        isLoading.value = false;
      });
};

스크롤 최적화

handleScrollEvent에서 로딩 상태를 체크할 수도 있을텐데 그러지 않은 이유는 무엇일까요

const handleScrollEvent = (e: Event) => {
  //if (isLoading.value) {
  //  return;
  //}

  let element = e.target as HTMLElement;
  if ((e.target as Document).documentElement) {
    element = (e.target as Document).documentElement as HTMLElement;
  }

  const bottom = getScrollRest(element);
  if (bottom < element.clientHeight * 2) {
    loadMore();
  }
};

handleScrollEvent는 target을 가져오고, 영역 하단까지의 거리를 계산하는 비용을 계속 지불하고 있습니다

여기서 로딩 상태를 체크한다고 해도 로딩중이 아닐 때의 비용은 줄일 수 없습니다

이 비용은 Throttle을 이용해 줄이려고 합니다

마치며

Throttle 처리를 포함하여 몇가지 아이디어와 수정사항이 있지만, 글이 너무 길어져서 여기까지만 작성합니다

감사합니다

적지 못한 아이디어

// @/components/ScrollBox.vue
const url = "https://jsonplaceholder.typicode.com/todos";
const params = ref({})
const getQueryString = (start: number, size: number) => {
  const qeuryParams = {
    ...params,
    _start: start,
    _limit: size,
  }

  return '?' + Object.entries(qeuryParams).map(([key, value])=>{
    return `${key}=${value}`
  }).join('&');
}
const { list } = useScrollLoad<ListItem>(scrollContainer, url, getQueryString);

// @/composilbes/scrollLoad.ts
useEventListener(element, "scroll", handleScrollEvent);

GITHUB

( Level 1에서 Level 2로 변경되었네요)

몇가지 실수로 인해 어렵게 느껴졌던 문제입니다

1. 접근방법

입사각과 반사각이 같고, 벽에 부딪히기 전과 후의 이동거리가 같습니다.

다음과 같이 흰색 공의 위치를 벽을 축으로 대칭이동시켰을 때, 흰색 공이 이동한 거리는 노란 공과 검은 공의 거리와 같을 것이라는 것을 쉽게 상상할 수 있습니다.

2. 문제를 어렵게 느끼게 했던 실수들

문제를 꼼꼼히 읽지 않았다

문제에 '머쓱이는 항상 같은 위치에 공을 놓고 쳐서 리스트에 담긴 위치에 놓인 공을 맞춥니다.' 라는 내용이 있습니다.

그런데도 각 수행마다 공의 위치가 변하는 것으로 생각했습니다. 머쓱합니다...

그래서 처음에는 balls.map 이 아니라 balls.reduce 로 방향을 잡고 시작해버렸네요.

네 코너에 인접한 경우의 수를 생각했다

문제에 다음과 같이 공이 코너에 맞는 경우 어떻게 진행되는지에 대해 설명하기 위한 그림이 있습니다.

하지만 애초에 코너에 맞는 경우를 생각할 필요가 없습니다.

잘 생각해보면, 코너에 맞고 나오는 거리보다 가까운 경우가 항상 존재함을 알 수 있습니다.

코드를 더 더 줄이고 싶었다

각 네 면에 대해서 각각 조건문을 달지 않고 싶었습니다만, 위 두가지 실수까지 겹치며 너무 오랜 시간이 흘러서 패스!

3. 코드

각 수행마다 최소 이동거리를 계산하여 배열로 반환합니다

function solution(m, n, startX, startY, balls) {
    return balls.map(([x, y]) => {
        return getNearlist(m, n, startX, startY, x, y);
    });
}

(StartX, StartY)를 네 벽에 대칭이동시켜 목적구와의 거리를 계산합니다.

이 때 대칭이동을 하려는 좌표와의 연장선상에 목적구가 있을 경우에는 거리를 계산하지 않습니다.

이렇게 계산한 거리들의 최솟값을 반환합니다.

const getNearlist = (m, n, x1, y1, x2, y2) => {
    let symmetryPoints = [];

    if (x1 !== x2 || y1 < y2) {
        const bottom = [x1, -y1];
        symmetryPoints.push(bottom);
    }
    if (x1 !== x2 || y1 > y2) {
        const top = [x1, n + n - y1];
        symmetryPoints.push(top);
    }
    if (y1 !== y2 || x1 < x2) {
        const left = [-x1, y1];
        symmetryPoints.push(left);
    }
    if (y1 !== y2 || x1 > x2) {
        const right = [m + m - x1, y1];
        symmetryPoints.push(right);
    }

    return symmetryPoints.reduce((min, [x,y])=>{
        return Math.min(min, (x-x2)**2 + (y-y2)**2);
    }, m**2 + n**2);
}

최근에 아래와 같은 컴포넌트를 수정할 일이 있었습니다

하나의 리스트는 탭을 선택할 때마다 목록을 비운 뒤에 api 호출을 통해 새로운 목록을 가져옵니다

이 때 리스트의 크기가 변화하면서 부자연스럽게 동작했습니다

부자연스러움을 해결하는 것이 일의 목적은 아니었지만,

그냥 보기 싫어서 어떻게 해결하면 좋을지 생각해 보게 됐습니다

생각의 흐름

고려사항

가장 쉽게 생각할 수 있는 것은 Api 호출 전 목록을 비우지 않는 것입니다

현재는 리스트의 높이가 x -> 0 -> y 로 변하지만,

목록을 비우지 않은 상태에서 다음 목록을 바로 로드한다면 높이의 변화는 x -> y 로 한단계 줄어듭니다

하지만 그렇게 되면 사용자는 해당 리스트가 로딩중인지 아닌지 알 수 없게 됩니다

그래서 처음 생각한 것은 목록을 비우지 않은 상태로 로딩 상태를 전달할 수 있도록 하는 것이었습니다

첫번째 아이디어

Progress Layer로 전체 화면을 덮는 것이었습니다

서비스 내부에서 대부분의 Data Fetch를 그렇게 처리하기도 했고, 가장 간편했습니다

그러나 목록을 빠르게 가져왔을 때 Progress Layer가 순식간에 사라지며 화면이 깜빡이는 것처럼 보였습니다

일정 시간동안은 Layer가 유지되도록 할 수도 있겠지만, 이 외에도 문제가 더 있었습니다

Layer에 접근하는 코드가 전체 소스 여기저기 흩어져 있어서 정확한 동작을 보장할 수도 없으며

탭을 변경하지 않은 다른 컴포넌트에 영향이 있다는 점에서 고려사항에서 제외했습니다

두번째 아이디어

각 컴포넌트 내부에서 Progress Bar를 표현하는 것이었습니다.

그러나 서비스 내에 이렇게 표현하는 화면이 전혀 없어서 이질적인 느낌이 들었습니다

디자인 협의 없이 독단적으로 결정할 수도 없었기에 다른 방안이 필요했습니다

세번째 아이디어

로딩중인 화면의 크기를 0이 아닌 값으로 고정하고자 했습니다

no-data 화면과 로딩중인 화면의 높이가 같아진다면

no-data 에서 출발하거나 no-data 가 되는 경우에는 훨씬 자연스럽게 보일 것 같았습니다

데이터가 있는 경우에도 30 -> 0 -> 80 의 변화보다는 30 -> 50 -> 80 의 변화가 더 자연스러울거라고 생각했습니다

( 지금 보면 터무니없는 생각입니다

첫번째 탭의 리스트 높이도 10이고 두번째 탭의 리스트 높이도 10이라고 했을 때

10 -> 50 -> 10 보다는 10 -> 0 -> 10의 변화가 더 자연스러울 것 같습니다 )

네번째 아이디어

이왕이면 스켈레톤 아이템을 이용해서 로딩중이라는 티도 조금 더 내고

화면이 심심하지 않게 보이도록 하고 싶었습니다

구현

1. 스켈레톤 아이템 생성

다음과 같이 실제 아이템과 같은 모양의 스켈레톤 아이템을 만들었습니다

각각의 리스트 컴포넌트는 다음과 같이 구성했습니다

<template>
  <div>
    <h2>{{ title }}</h2>
    <tag-menu
      :menus="menus"
      @onChangeMenu="handleChageMenu"
    ></tag-menu>

    <ul v-show="list.length === 0" class="list-container">
      <skeleton-item v-for="idx in 5" :key="idx"></skeleton-item>
    </ul>
    <ul v-show="list.length > 0" class="list-container">
      <list-item
        v-for="(item, idx) in list"
        :key="idx"
        :item="item"
      ></list-item>
    </ul>
  </div>
</template>

<script>
export default {
  ..., // 생략
  props: {
    title: {
      type: String,
      default: "",
    },
    menus: {
      type: Array,
      default: () => [],
    },
    totalList: {
      type: Array,
      default: () => [],
    },
  },

  data(){
    return {
      list: [],
    }
  },

  methods: {
    handleChageMenu(idx) {
      this.list = [];

      setTimeout(() => { // 로딩 딜레이는 타임아웃으로으로 대체했습니다 
        this.list = this.totalList[idx];
      }, 500);
    },
  },
}
</script>

조금 덜 부자연스러운 것 같고, 로딩중이구나 하는 느낌도 드시나요?

하지만, 아이템의 갯수에 따라서 여전히 부자연스럽다고 느꼈습니다

2. 변경 전 리스트 갯수를 활용

vue의 watch속성을 이용하면 변경 전의 리스트 갯수를 알 수 있고,

이것을 이용해 높이의 변화를 줄일 수 있을 것 같았습니다

<template>
  <div>
    <h2>{{ title }}</h2>
    <tag-menu
      :menus="menus"
      @onChangeMenu="handleChageMenu"
    ></tag-menu>

    <ul v-show="list.length === 0" class="list-container">
      <skeleton-item v-for="idx in skeletonSize" :key="idx"></skeleton-item>
    </ul>
    <ul v-show="list.length > 0" class="list-container">
      <list-item
        v-for="(item, idx) in list"
        :key="idx"
        :item="item"
      ></list-item>
    </ul>
  </div>
</template>

<script>
export default {
  ..., // 생략
  data(){
    return {
      list: [],
      skeletonSize: 5
    }
  },
  watch: {
    list(curr, prev){
      this.skeletonSize = prev.length;
    }
  },
  methods: {
    handleChageMenu(idx) {
      this.list = [];

      setTimeout(() => {
        this.list = this.totalList[idx];
      }, 500);
    },
  },
}
</script>

조금 더 나아졌나요?

3. NoItem 처리

만약 서버에서 가져온 리스트가 비어있다면, 스켈레톤 아이템이 노출될겁니다.

로딩 상태와 데이터가 없는 상태의 구분이 필요하겠네요

<template>
  <div>
    <h2>{{ title }}</h2>
    <tag-menu
      :menus="menus"
      @onChangeMenu="handleChageMenu"
    ></tag-menu>

    <ul v-show="isShowSkeletonItems" class="list-container">
      <skeleton-item v-for="idx in skeletonSize" :key="idx"></skeleton-item>
    </ul>
    <ul v-show="isShowNoItem" class="list-container">
      <h1>NO-ITEM</h1>
    </ul>
    <ul v-show="isShowItems" class="list-container">
      <list-item
        v-for="(item, idx) in list"
        :key="idx"
        :item="item"
      ></list-item>
    </ul>

  </div>
</template>

<script>
export default {
  ..., // 생략
  data(){
    return {
      list: null,
      skeletonSize: 5
    }
  },

  computed: {
    isShowSkeletonItems() {
      return this.list === null;
    },
    isShowNoItem() {
      return Array.isArray(this.list) && this.list.length === 0;
    },
    isShowItems() {
      return !this.isShowSkeletonItems && !this.isShowNoItem;
    },
  },

  watch: {
    list(curr, prev){
      if (!Array.isArray(prev)) {
        this.skeletonSize = 5;
        return;
      }

      if (prev.length === 0) {
        this.skeletonSize = 1;
      } else {
        this.skeletonSize = prev.length;
      }
    }
  },
  methods: {
    handleChageMenu(idx) {
      this.list = null;

      setTimeout(() => {
        this.list = this.totalList[idx];
      }, 500);
    },
  },
}
</script>

대단한건 아니지만

대단한 기술도 아니고 대단한 발상도 아니지만

어떤 사고의 과정을 통해 결과물을 도출했는지 기록하고 공유하고 싶었습니다

전체 코드

• Kangbit Github

예전에 설정해 두었던 github pages가 동작하지 않더군요

그래서 그냥 새로 만들기로 했습니다

생각보다 삽질을 많이 하게 되어서 이번엔 정리를 좀 해두려구요

01. 프로젝트 생성

저는 다음과 같이 프로젝트를 생성했습니다.

npx create-react-app bitpage --template typescript

02. Git 연결

새로운 Repository를 생성합니다.

아래의 주소를 복사하고

프로젝트 폴더로 이동해서 깃을 연결합니다

cd bitpage
git remote add origin '복사한 주소'
git branch -M main
git push -u origin main

03. gh-pages 설정

npm install -D gh-pages

gh-pages 모듈을 설치하고

프로젝트의 package.json에 homepage와 deploy 스크립트를 작성합니다

이제 배포를 하고 나니,

npm run deploy

다음과 같이 gh-pages라는 브랜치가 생겼습니다

이제 settings로 이동하여 Pages 설정을 다음과 같이 변경해주면,

다음과 같이 페이지를 확인할 수 있습니다

04. 배포 자동화

하지만 매번 deploy 명령어를 통해 배포하지 않고,

git의 main 브랜치에 push하는 것만으로 배포가 되게끔 하고 싶습니다

다음 경로에 yml 파일을 생성하고,

다음과 같이 작성합니다

name: gh-pages Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [16.x]

    steps:
      - uses: actions/checkout@v3

      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: Build
        run: |
          npm ci
          npm run build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

이제 소스를 수정하고 push를 하면 다음과 같이 새로운 workflow가 동작하고

변경사항이 자동으로 페이지에 반영됩니다