Code snippet

Code snippet (코드 스니펫)

코드 스니펫은 코드 파일에 복사해서 삽입할 수 있는 재사용 가능한 문자열 조각이나 작은 코드 블록이에요. 사용자가 긴 문자열을 쉽게 복사하거나 중요한 키워드를 강조하고 싶을 때 유용합니다.

출처: Code snippet

본문

개요 (Overview)

코드 스니펫에는 인라인(inline), 단일 라인(single line), 다중 라인(multi-line)의 세 가지 변형이 있어요. 다양한 줄 길이의 사용 사례에 맞춰 선택할 수 있습니다.

변형 (Variants)

변형 (Variant)	용도 (Purpose)
Inline	문장이나 단락과 함께 인라인으로 쓰는 텍스트 블록.
Single line	한 줄의 코드.
Multi-line	여러 줄의 코드로, 더 많은/더 적은 문자열을 보여주는 기능이 있어요.

언제 사용할까요 (When to use)

사용자가 문자열을 쉽게 복사하도록 돕거나, 사용자에게 강조할 키워드를 알리고 싶을 때 코드 스니펫을 사용하세요.
코드 스니펫은 보통 사용자가 빠르게 시작하도록 돕는 코드 문서에서 쓰여요.

언제 사용하지 말아야 할까요 (When not to use)

사용자가 입력 값을 변경하길 원한다면 코드 스니펫을 사용하지 마세요. Carbon 코드 스니펫은 읽기 전용이에요.

포맷 (Formatting)

구조 (Anatomy)

스니펫 텍스트(Snippet text): 코드의 줄 또는 블록.
복사 버튼(Copy button, 선택): 코드를 클립보드에 복사하는 아이콘 버튼.
더 보기 버튼(Show more button, 선택): 코드 스니펫을 펼치거나 접어 더 많거나 적은 줄의 코드를 보여주는 고스트 버튼.

배치 (Placement)

코드 스니펫 컨테이너는 페이지의 다른 폼 컴포넌트와 그리드에 세로로 정렬되어야 해요.

참고: 인라인 코드 스니펫을 사용한다면 스니펫은 텍스트 본문 안에 위치합니다.

코드 스니펫 컨테이너를 그리드에 정렬하세요.

코드 스니펫 텍스트를 그리드에 정렬하고 컨테이너를 걸치게 하지 마세요.

콘텐츠 (Content)

주요 요소 (Main elements)

스니펫 텍스트 (Snippet text)

사용자가 클립보드에 복사해도 코드가 깨지지 않도록, 코드가 올바른 구문(syntax)을 쓰고 있는지 확인하세요.

복사 버튼 툴팁 (Copy button tooltip)

복사 버튼에는 툴팁이 함께 제공되어야 해요. 툴팁 피드백 텍스트는 간결해야 하며, 사용자가 복사 버튼을 클릭했을 때 취해지는 동작을 설명해야 합니다. 기본적으로 "Copied to clipboard" 텍스트를 표시해요.

추가 가이드 (Further guidance)

더 자세한 콘텐츠 지침은 Carbon의 콘텐츠 가이드라인을 참고하세요.

공통 동작 (Universal behaviors)

클립보드에 복사 (Copy to clipboard)

코드 스니펫은 기본적으로 제공된 코드를 사용자의 클립보드에 복사할 수 있는 복사 기능을 가져요. 복사 아이콘에는 항목을 클립보드에 복사하는 성공적인 동작을 알리는 확인 툴팁이 함께 제공되어야 합니다. 복사 기능은 선택 사항이며, 사용 사례에 필요 없다면 제거할 수 있어요.

인터랙션 (Interactions)

마우스 (Mouse)

인라인 코드 스니펫은 스니펫 자체의 아무 곳이나 클릭해 복사할 수 있어요.

단일 라인 코드 스니펫은 "복사(copy)" 아이콘을 클릭해 복사할 수 있어요. 브라우저는 텍스트를 수동으로 강조하고 컨텍스트 메뉴(우클릭)에서 "복사"를 선택하는 방법도 제공합니다.

다중 라인 코드 스니펫은 복사 아이콘을 클릭하거나 텍스트를 수동으로 강조하고 우클릭 "복사"로 복사할 수 있어요.

키보드 (Keyboard)

복사 버튼 (Copy button):

인라인 코드 스니펫과 단일 라인·다중 라인 스니펫의 복사 버튼은 Tab을 눌러 포커스할 수 있어요.
복사 기능은 Space 또는 Enter를 눌러 실행할 수 있어요.
복사가 실행된 후에는 컨텍스트가 바뀌지 않으므로 포커스가 버튼에 유지됩니다.

인라인 (Inline)

텍스트 본문 안에서 인라인 코드 스니펫을 사용하세요. 인라인으로 코드 스니펫을 쓰면 복사할 중요한 키워드에 강조를 만들고 긴 텍스트 본문을 훑어보기 쉽게 만들어요. 여러 줄로 확장되는 인라인 코드 스니펫은 피하세요.

단일 라인 (Single line)

여전히 한 줄로 표현할 수 있는 더 긴 코드 문자열에는 단일 라인 코드 스니펫을 사용하세요.

단일 라인 넘침 콘텐츠 (Single line overflow content)

단일 라인 코드 스니펫의 텍스트가 길면 텍스트는 가로 스크롤로 넘치게 됩니다.

다중 라인 (Multi-line)

여러 줄의 코드를 표시할 때는 다중 라인 코드 스니펫을 사용하세요.

다중 라인 넘침 콘텐츠 (Multi-line overflow content)

세로 스크롤 (Vertical scroll)

또는 코드 줄이 아홉 줄보다 많다면 코드 스니펫에 세로 스크롤을 적용할 수 있어요.

가로 스크롤 (Horizontal scroll)

터미널 명령은 종종 더 긴 문자열이며 한 줄에만 나타나야 해요. 이렇게 긴 문자열에 대해 박스의 설정된 너비를 유지하려면 가로 스크롤을 적용하세요.

수정자 (Modifiers)

Light

그 테마의 UI 배경이 아닌 다른 배경에서 코드 스니펫을 사용할 때는 light prop 수정자를 사용하세요. light prop은 코드 스니펫의 배경색 토큰을 field-01에서 field-02로 바꿉니다.

더 알아보기 (Learn more)

코드 스니펫은 사용자가 코드를 빠르게 복사해 시작할 수 있게 도와주는 문서용 컴포넌트예요. 줄 길이에 따라 inline, single line, multi-line 변형을 고르고, 공간이 부족할 때는 Show more 버튼이나 스크롤을 활용하세요. 모든 스니펫은 읽기 전용이며, 복사 성공 확인 툴팁을 항상 함께 제공해야 해요.