Help us learn about your current experience with the documentation. Take the survey.

ViewComponent

ViewComponent 是一个用于创建可重用、可测试和封装的视图组件的框架，基于 Ruby on Rails 开发，无需使用 Vue 等 JavaScript 框架。这些组件在服务器端渲染，可以与 Haml 等模板语言无缝使用。

更多信息请参阅官方文档或这个介绍视频。

使用 Lookbook 浏览组件

我们在 http://gdk.test:3000/rails/lookbook（仅在开发模式下可用）中有一个 Lookbook，用于浏览和交互 ViewComponent 预览。

Pajamas 组件

我们 Pajamas 设计系统中的部分组件在 app/components/pajamas 中以 ViewComponent 的形式提供。

我们仍在创建这些组件的过程中，因此并非每个 Pajamas 组件都可作为 ViewComponent 使用。如果您需要的组件尚未可用，请联系 Design Systems 团队。

可用组件

此列表仅供参考。完整列表请参见 app/components/pajamas。也可以查看我们的 Lookbook（http://gdk.test:3000/rails/lookbook），以更交互式的方式浏览我们的组件。

Alert

Pajamas::AlertComponent 遵循 Pajamas Alert 规范。

示例：

默认情况下，这会创建一个带有图标的可关闭信息提示：

= render Pajamas::AlertComponent.new(title: "快完成了！")

您可以设置变体、隐藏图标等：

= render Pajamas::AlertComponent.new(title: "全部完成！",
  variant: :success,
  dismissible: :false,
  show_icon: false)

完整选项列表请参阅其源代码。

Pajamas::BannerComponent 遵循 Pajamas Banner 规范。

示例：

最简单的横幅组件如下所示：

= render Pajamas::BannerComponent.new(button_text: '了解更多', button_link: example_path,
  svg_path: 'illustrations/example.svg') do |c|
  - c.with_title { '你好世界！' }
  %p 横幅内容放在这里...

如果您需要更多控制，也可以使用 illustration 插槽代替 svg_path，使用 primary_action 插槽代替 button_text 和 button_link：

= render Pajamas::BannerComponent.new do |c|
  - c.with_illustration do
    = custom_icon('my_inline_svg')
  - c.with_title do
    你好世界！
  - c.with_primary_action do
    = render 'my_button_in_a_partial'

完整选项列表请参阅其源代码。

Button

Pajamas::ButtonComponent 遵循 Pajamas 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|
  返回首页

完整选项列表请参阅其源代码。

Card

Pajamas::CardComponent 遵循 Pajamas Card 规范。

示例：

卡片有一个必需的 body 插槽和可选的 header 和 footer 插槽：

= 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_options 和 footer_options 也可用。

完整选项列表请参阅其源代码。

Checkbox tag

Pajamas::CheckboxTagComponent 遵循 Pajamas 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.md'), target: '_blank', rel: 'noopener noreferrer', data: { track_action: 'followed' }

完整选项列表请参阅其源代码。

Checkbox

Pajamas::CheckboxComponent 遵循 Pajamas Checkbox 规范。

Pajamas::CheckboxComponent 被 GitLab UI 表单构建器内部使用，需要传入一个 ActionView::Helpers::FormBuilder 实例作为 form 参数。建议使用 gitlab_ui_checkbox_component 方法来渲染此 ViewComponent。要使用不带 ActionView::Helpers::FormBuilder 实例的复选框，请使用 CheckboxTagComponent。

完整选项列表请参阅其源代码。

Toggle

Pajamas::ToggleComponent 遵循 Pajamas Toggle 规范。

= render Pajamas::ToggleComponent.new(classes: 'js-force-push-toggle',
  label: s_("ProtectedBranch|切换允许强制推送"),
  is_checked: protected_branch.allow_force_push,
  label_position: :hidden) do
  利用此块来渲染丰富的帮助文本。要渲染纯文本帮助文本，请优先使用 `help` 参数。

切换 ViewComponent 很特殊，因为它依赖于 Vue.js 组件。 要实际初始化此组件，请确保从 ~/toggles 调用 initToggle 辅助方法。

完整选项列表请参阅其源代码。

布局组件

布局组件可用于创建 GitLab 中常用的布局模式。

可用组件

页面标题

带有页面标题和可选操作的标准页面标题。

示例：

= render ::Layouts::PageHeadingComponent.new(_('页面标题')) do |c|
  - c.with_actions do
    = buttons

完整选项列表请参阅其源代码。

CRUD 组件

用于托管表格或列表的容器，包含创建、读取、更新、删除等用户操作。

示例：

= render ::Layouts::CrudComponent.new(_('CRUD 标题'), icon: 'ICONNAME', count: COUNT) do |c|
  - c.with_description do
    = description
  - c.with_actions do
    = buttons
  - c.with_form do
    = 添加项目表单
  - c.with_body do
    = body
  - c.with_pagination do
    = 分页组件
  - c.with_footer do
    = 可选页脚

完整选项列表请参阅其源代码。

水平区块

许多设置页面使用一种布局，标题和描述在左侧，设置字段在右侧。Layouts::HorizontalSectionComponent 可用于创建此布局。

示例：

= render ::Layouts::HorizontalSectionComponent.new(options: { class: 'gl-mb-6' }) do |c|
  - c.with_title { _('命名、可见性') }
  - c.with_description do
    = _('更新您的组名称、描述、头像和可见性。')
    = link_to _('了解更多关于组的信息。'), help_page_path('user/group/_index.md')
  - c.with_body do
    .form-group.gl-form-group
      = f.label :name, _('新组名称')
      = f.text_field :name

完整选项列表请参阅其源代码。

设置区块

用于分组相关设置的设置区块（手风琴）。

示例：

= render ::Layouts::SettingsBlock.new(_('设置区块标题')) do |c|
  - c.with_description do
    = description
  - c.with_body do
    = body

完整选项列表请参阅其源代码。

设置区块

与设置区块（见上文）类似，此组件用于将相关设置分组在一起。与设置区块不同，它不提供手风琴功能。使用粘性标题。

示例：

= render ::Layouts::SettingsSection.new(_('设置区块标题')) do |c|
  - c.with_description do
    = description
  - c.with_body do
    = body

完整选项列表请参阅其源代码。

最佳实践

如果您要创建新的 Haml 视图，请使用可用的组件，而不是使用带有 CSS 类的普通 Haml 标签。
如果您正在修改现有的 Haml 视图，并且看到例如仍用普通 Haml 实现的按钮，考虑将其迁移为使用 ViewComponent。
如果您决定创建新组件，也考虑为其创建预览。这将帮助其他人通过 Lookbook 发现您的组件，也使测试其不同状态变得容易得多。

预览布局

如果您需要为 ViewComponent 预览使用自定义布局，请考虑使用以下路径来存放布局代码：

app/views/layouts/lookbook 用于您的布局 HAML 文件
app/assets/javascripts/entrypoints/lookbook 用于您的自定义 JavaScript 代码
app/assets/stylesheets/lookbook 用于您的自定义 SASS 代码

JavaScript 和 SASS 代码必须手动包含在布局中。