ViewComponent

ViewComponent는 Ruby on Rails로 재사용 가능하고, 테스트 가능하며, 캡슐화된 뷰 컴포넌트를 생성하기 위한 프레임워크로, Vue와 같은 JavaScript 프레임워크가 필요하지 않습니다.

서버 측에서 렌더링되며, Haml과 같은 템플릿 언어와 원활하게 사용될 수 있습니다.

자세한 내용은 공식 문서 또는 이 소개 영상을 참조하세요.

Lookbook으로 컴포넌트 탐색하기

http://gdk.test:3000/rails/lookbook (개발 모드에서만 사용 가능)에서 ViewComponent 미리보기를 탐색하고 상호작용할 수 있는 Lookbook이 있습니다.

Pajamas 컴포넌트

우리의 Pajamas 디자인 시스템의 일부 컴포넌트가 app/components/pajamas에서 ViewComponent로 제공됩니다.

note
아직 이러한 컴포넌트를 생성하는 과정에 있으므로 모든 Pajamas 컴포넌트가 ViewComponent로 제공되는 것은 아닙니다. 찾고 있는 컴포넌트가 아직 사용 가능하지 않은 경우 디자인 시스템 팀에 문의하세요.

사용 가능한 컴포넌트

이 목록은 최선을 다한 노력입니다. 전체 목록은 app/components/pajamas에서 확인할 수 있습니다. 또한 우리 컴포넌트를 더욱 인터랙티브하게 탐색할 수 있는 Lookbook(http://gdk.test:3000/rails/lookbook)도 확인하시기 바랍니다.

Alert

Pajamas::AlertComponentPajamas Alert 사양을 따릅니다.

예시:

기본적으로 이는 아이콘이 포함된 닫을 수 있는 정보 알림을 생성합니다:

= render Pajamas::AlertComponent.new(title: "Almost done!")

변형을 설정하거나 아이콘을 숨기는 등 더 많은 옵션을 설정할 수 있습니다:

= render Pajamas::AlertComponent.new(title: "All done!",
  variant: :success,
  dismissible: :false,
  show_icon: false)

옵션의 전체 목록은 그 소스에서 확인하세요.

Pajamas::BannerComponentPajamas Banner 사양을 따릅니다.

예시:

가장 간단한 형태의 배너 컴포넌트는 다음과 같습니다:

= render Pajamas::BannerComponent.new(button_text: 'Learn more', button_link: example_path,
  svg_path: 'illustrations/example.svg') do |c|
  - c.with_title { 'Hello world!' }
  %p Content of your banner goes here...

더 많은 제어가 필요한 경우 svg_path 대신 illustration 슬롯을, button_textbutton_link 대신 primary_action 슬롯을 사용할 수 있습니다:

= render Pajamas::BannerComponent.new do |c|
  - c.with_illustration do
    = custom_icon('my_inline_svg')
  - c.with_title do
    Hello world!
  - c.with_primary_action do
    = render 'my_button_in_a_partial'

옵션의 전체 목록은 그 소스에서 확인하세요.

버튼

Pajamas::ButtonComponentPajamas Button 사양을 따릅니다.

예시:

버튼 컴포넌트는 많은 옵션이 있지만 모두 좋은 기본값을 가지고 있어, 가장 간단한 버튼은 다음과 같습니다:

= render Pajamas::ButtonComponent.new do |c|
  = _('버튼 텍스트가 여기에 들어갑니다')

다음 예시는 사용 가능한 대부분의 옵션을 보여줍니다:

= render Pajamas::ButtonComponent.new(category: :secondary,
  variant: :danger,
  size: :small,
  type: :submit,
  disabled: true,
  loading: false,
  block: true) do |c|
  버튼 텍스트가 여기에 들어갑니다

다음과 같이 버튼처럼 보이는 <a> 태그도 만들 수 있습니다:

= render Pajamas::ButtonComponent.new(href: root_path) do |c|
  집으로 가기

전체 옵션 목록은 다음 소스를 참조하세요.

카드

Pajamas::CardComponentPajamas Card 사양을 따릅니다.

예시:

카드는 필수 body 슬롯과 선택적 headerfooter 슬롯을 가지고 있습니다:

= render Pajamas::CardComponent.new do |c|
  - c.with_header do
    나는 헤더입니다.
  - c.with_body do
    %p 여러 줄
    %p 본문 내용.
  - c.with_footer do
    바닥글이 여기에 있습니다.

이러한 슬롯들 또는 카드 자체에 사용자 정의 속성을 추가하려면 다음 옵션을 사용하세요:

= render Pajamas::CardComponent.new(card_options: {id: "my-id"}, body_options: {data: { count: 1 }})

header_optionsfooter_options도 사용할 수 있습니다.

전체 옵션 목록은 다음 소스를 참조하세요.

체크박스 태그

Pajamas::CheckboxTagComponentPajamas Checkbox 사양을 따릅니다.

name 인자와 label 슬롯은 필수입니다.

예를 들어:

= render Pajamas::CheckboxTagComponent.new(name: 'project[initialize_with_sast]',
  checkbox_options: { data: { testid: 'initialize-with-sast-checkbox', track_label: track_label, track_action: 'activate_form_input', track_property: 'init_with_sast' } }) do |c|
  - c.with_label do
    = s_('ProjectsNew|정적 애플리케이션 보안 테스트 (SAST) 활성화')
  - c.with_help_text do
    = s_('ProjectsNew|알려진 보안 취약점에 대해 소스 코드를 분석합니다.')
    = link_to _('자세히 알아보기.'), help_page_path('user/application_security/sast/index'), target: '_blank', rel: 'noopener noreferrer', data: { track_action: 'followed' }

전체 옵션 목록은 다음 소스를 참조하세요.

체크박스

Pajamas::CheckboxComponentPajamas Checkbox 사양을 따릅니다.

참고: Pajamas::CheckboxComponentGitLab UI 폼 빌더에서 내부적으로 사용되며, form 인자로 ActionView::Helpers::FormBuilder의 인스턴스가 필요합니다.

gitlab_ui_checkbox_component 메서드를 사용하여 이 ViewComponent를 렌더링하는 것이 선호됩니다.

ActionView::Helpers::FormBuilder 인스턴스 없이 체크박스를 사용하려면 CheckboxTagComponent를 사용하세요.

전체 옵션 목록은 다음 소스를 참조하세요.

토글

Pajamas::ToggleComponentPajamas Toggle 사양을 따릅니다.

= render Pajamas::ToggleComponent.new(classes: 'js-force-push-toggle',
  label: s_("ProtectedBranch|Toggle allowed to force push"),
  is_checked: protected_branch.allow_force_push,
  label_position: :hidden) do
  이 블록을 활용하여 풍부한 도움말 텍스트를 렌더링합니다. 일반 텍스트 도움말 텍스트를 렌더링하려면 `help` 매개변수를 선호하세요.

참고:
토글 ViewComponent는 Vue.js 구성 요소에 의존하기 때문에 특수합니다.
이 구성 요소를 실제로 초기화하려면 ~/toggles에서 initToggle 헬퍼를 호출해야 합니다.

전체 옵션 목록은 해당
source를 참조하세요.

레이아웃

레이아웃 구성 요소는 GitLab에서 사용되는 일반 레이아웃 패턴을 만드는 데 사용할 수 있습니다.

사용 가능한 구성 요소

페이지 제목

페이지 제목과 선택적 작업이 포함된 표준 페이지 헤더입니다.

예제:

= render ::Layouts::PageHeadingComponent.new(_('Page title')) do |c|
  - c.with_actions do
    = buttons

전체 옵션 목록은 해당
source를 참조하세요.

CRUD 구성 요소

테이블이나 목록을 호스팅하고 생성, 읽기, 업데이트, 삭제와 같은 사용자 작업을 포함하는 목록 컨테이너입니다.

예제:

= render ::Layouts::CrudComponent.new(_('CRUD title'), icon: 'ICONNAME', count: COUNT) do |c|
  - c.with_description do
    = description
  - c.with_actions do
    = buttons
  - c.with_form do
    = add item form
  - c.with_body do
    = body
  - c.with_pagination do
    = pagination component
  - c.with_footer do
    = optional footer

전체 옵션 목록은 해당
source를 참조하세요.

수평 섹션

많은 설정 페이지는 제목과 설명이 왼쪽에 있고 설정 필드가 오른쪽에 있는 레이아웃을 사용합니다. Layouts::HorizontalSectionComponent를 사용하여 이 레이아웃을 만들 수 있습니다.

예제:

= render ::Layouts::HorizontalSectionComponent.new(options: { class: 'gl-mb-6' }) do |c|
  - c.with_title { _('Naming, visibility') }
  - c.with_description do
    = _('Update your group name, description, avatar, and visibility.')
    = link_to _('Learn more about groups.'), help_page_path('user/group/index')
  - c.with_body do
    .form-group.gl-form-group
      = f.label :name, _('New group name')
      = f.text_field :name

전체 옵션 목록은 해당
source를 참조하세요.

설정 블록

관련 설정을 그룹화하는 설정 블록(아코디언)입니다.

예제:

= render ::Layouts::SettingsBlock.new(_('Settings block heading')) do |c|
  - c.with_description do
    = description
  - c.with_body do
    = body

전체 옵션 목록은 해당
source를 참조하세요.

설정 섹션

SettingsBlock과 유사하게 이 구성 요소는 관련 설정을 함께 그룹화하는 데 사용됩니다. SettingsBlock과는 달리 아코디언 기능을 제공하지 않습니다. 스티키 헤더를 사용합니다.

예시:

= render ::Layouts::SettingsSection.new(_('설정 섹션 제목')) do |c|
  - c.with_description do
    = description
  - c.with_body do
    = body

전체 옵션 목록은 source를 참조하세요.

모범 사례

  • Haml에서 새 보기 생성이 필요할 경우, 일반 Haml 태그와 CSS 클래스를 사용하는 것보다 사용 가능한 구성 요소를 사용하세요.

  • 기존 Haml 보기를 변경하는 경우 예를 들어, 여전히 일반 Haml로 구현된 버튼을 발견하면, 이를 ViewComponent로 마이그레이션하는 것을 고려하세요.

  • 새로운 구성 요소를 생성하기로 결정하면, 해당 구성 요소에 대한 미리보기를 생성하는 것도 고려하세요.

    이는 다른 사람들이 Lookbook으로 귀하의 구성 요소를 발견하는 데 도움이 되며, 다양한 상태를 테스트하는 것도 훨씬 더 쉽게 만듭니다.

미리보기 레이아웃

ViewComponent 미리보기에 맞춤 레이아웃이 필요하면 레이아웃 코드에 대해 이러한 경로를 사용하는 것을 고려하세요:

  • app/views/layouts/lookbook — 레이아웃 HAML 파일용
  • app/assets/javascripts/entrypoints/lookbook — 사용자 정의 JavaScript 코드용
  • app/assets/stylesheets/lookbook — 사용자 정의 SASS 코드용

JavaScript 및 SASS 코드는 레이아웃에 수동으로 포함해야 함을 유의하세요.