shopify-polaris-web-components

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shopify Polaris Web Components

Use this skill when building UI for Shopify App Home surfaces using Polaris Web Components.

本技能适用于使用Polaris Web Components为Shopify App Home界面构建UI的场景。

When to Use

适用场景

Building App Home pages (the app surface outside of Shopify Admin iframe)
Creating UI with
```
s-*
```
custom elements
Designing layouts with s-section, s-stack, s-box
Building forms, modals, or lists for App Home

Important: App Home uses Polaris Web Components (

s-*

elements), NOT Polaris React (

@shopify/polaris

). These are different technologies.

开发App Home页面（Shopify管理后台iframe之外的应用界面）
使用
```
s-*
```
自定义元素创建UI
利用s-section、s-stack、s-box设计布局
为App Home构建表单、模态框或列表

重要提示：App Home使用Polaris Web Components（

s-*

元素），而非Polaris React（

@shopify/polaris

），二者是不同的技术。

Polaris React vs Web Components

Feature	Polaris React	Polaris Web Components
Use for	Embedded admin apps	App Home surfaces
Import	`@shopify/polaris`	No import (native elements)
Syntax	`<Button>`	`<s-button>`
Framework	React components	Custom HTML elements

特性	Polaris React	Polaris Web Components
适用场景	嵌入式后台应用	App Home界面
引入方式	`@shopify/polaris`	无需引入（原生元素）
语法	`<Button>`	`<s-button>`
所属框架	React组件	自定义HTML元素

Core Components

核心组件

Page Structure

页面结构

html

<s-page heading="Dashboard">
  <s-section heading="Overview">
    <!-- Content -->
  </s-section>
  
  <s-section heading="Settings">
    <!-- More content -->
  </s-section>
</s-page>

html

<s-page heading="Dashboard">
  <s-section heading="Overview">
    <!-- 内容 -->
  </s-section>
  
  <s-section heading="Settings">
    <!-- 更多内容 -->
  </s-section>
</s-page>

Layout with Stack

利用Stack布局

html

<!-- Vertical stack (default) -->
<s-stack direction="block" gap="large">
  <s-text>Item 1</s-text>
  <s-text>Item 2</s-text>
</s-stack>

<!-- Horizontal stack -->
<s-stack direction="inline" gap="medium" alignItems="center">
  <s-button>Cancel</s-button>
  <s-button variant="primary">Save</s-button>
</s-stack>

<!-- Stack with justification -->
<s-stack 
  direction="inline" 
  justifyContent="space-between"
  alignItems="center"
>
  <s-text variant="headingMd">Title</s-text>
  <s-button>Action</s-button>
</s-stack>

html

<!-- 垂直堆叠（默认） -->
<s-stack direction="block" gap="large">
  <s-text>Item 1</s-text>
  <s-text>Item 2</s-text>
</s-stack>

<!-- 水平堆叠 -->
<s-stack direction="inline" gap="medium" alignItems="center">
  <s-button>Cancel</s-button>
  <s-button variant="primary">Save</s-button>
</s-stack>

<!-- 带对齐方式的堆叠 -->
<s-stack 
  direction="inline" 
  justifyContent="space-between"
  alignItems="center"
>
  <s-text variant="headingMd">Title</s-text>
  <s-button>Action</s-button>
</s-stack>

Section (Card-like Container)

Section（类卡片容器）

Use

s-section

for grouped content with optional heading:

html

<!-- Section with heading -->
<s-section heading="Chat Widget Settings">
  <s-stack direction="block" gap="medium">
    <s-text>Configure your widget appearance.</s-text>
    <!-- Form fields -->
  </s-stack>
</s-section>

<!-- Section without heading -->
<s-section>
  <s-text>Simple content block</s-text>
</s-section>

使用

s-section

包裹带可选标题的分组内容：

html

<!-- 带标题的Section -->
<s-section heading="Chat Widget Settings">
  <s-stack direction="block" gap="medium">
    <s-text>配置您的小部件外观。</s-text>
    <!-- 表单字段 -->
  </s-stack>
</s-section>

<!-- 无标题的Section -->
<s-section>
  <s-text>简单内容块</s-text>
</s-section>

Box (Generic Layout Container)

Box（通用布局容器）

Use

s-box

for padding, borders, and spacing - NOT for cards:

html

<!-- Box with padding -->
<s-box padding="large">
  <s-text>Padded content</s-text>
</s-box>

<!-- Box with border -->
<s-box 
  padding="medium" 
  borderWidth="base" 
  borderRadius="base"
>
  <s-text>Bordered content</s-text>
</s-box>

<!-- Box for spacing -->
<s-box paddingBlockStart="large">
  <s-text>Content with top margin</s-text>
</s-box>

Rule: Use

s-section

for card-like containers,

s-box

for layout/spacing only.

使用

s-box

实现内边距、边框和间距——请勿用于卡片：

html

<!-- 带内边距的Box -->
<s-box padding="large">
  <s-text>带内边距的内容</s-text>
</s-box>

<!-- 带边框的Box -->
<s-box 
  padding="medium" 
  borderWidth="base" 
  borderRadius="base"
>
  <s-text>带边框的内容</s-text>
</s-box>

<!-- 用于间距的Box -->
<s-box paddingBlockStart="large">
  <s-text>带顶部间距的内容</s-text>
</s-box>

规则：使用

s-section

实现类卡片容器，

s-box

仅用于布局/间距调整。

Buttons

按钮

html

<!-- Primary action -->
<s-button variant="primary" type="submit">
  Save Settings
</s-button>

<!-- Default button -->
<s-button>Cancel</s-button>

<!-- Destructive -->
<s-button variant="primary" tone="critical">
  Delete
</s-button>

<!-- Disabled -->
<s-button disabled>Unavailable</s-button>

<!-- With click handler (in JS) -->
<s-button id="save-btn">Save</s-button>
<script>
  document.getElementById('save-btn').addEventListener('click', handleSave);
</script>

html

<!-- 主要操作按钮 -->
<s-button variant="primary" type="submit">
  保存设置
</s-button>

<!-- 默认按钮 -->
<s-button>取消</s-button>

<!-- 危险操作按钮 -->
<s-button variant="primary" tone="critical">
  删除
</s-button>

<!-- 禁用状态按钮 -->
<s-button disabled>不可用</s-button>

<!-- 带点击事件的按钮（JS中实现） -->
<s-button id="save-btn">保存</s-button>
<script>
  document.getElementById('save-btn').addEventListener('click', handleSave);
</script>

Text

文本

html

<!-- Headings -->
<s-text variant="headingLg">Large Heading</s-text>
<s-text variant="headingMd">Medium Heading</s-text>
<s-text variant="headingSm">Small Heading</s-text>

<!-- Body text -->
<s-text>Default body text</s-text>
<s-text variant="bodySm">Small body text</s-text>

<!-- Tones -->
<s-text tone="subdued">Muted text</s-text>
<s-text tone="critical">Error text</s-text>
<s-text tone="success">Success text</s-text>

html

<!-- 标题文本 -->
<s-text variant="headingLg">大标题</s-text>
<s-text variant="headingMd">中标题</s-text>
<s-text variant="headingSm">小标题</s-text>

<!-- 正文文本 -->
<s-text>默认正文</s-text>
<s-text variant="bodySm">小尺寸正文</s-text>

<!-- 文本色调 -->
<s-text tone="subdued">弱化文本</s-text>
<s-text tone="critical">错误文本</s-text>
<s-text tone="success">成功文本</s-text>

Banner

横幅

html

<!-- Info banner -->
<s-banner>
  <p>This is an informational message.</p>
</s-banner>

<!-- Critical banner -->
<s-banner tone="critical">
  <p>Something went wrong. Please try again.</p>
</s-banner>

<!-- Success banner -->
<s-banner tone="success">
  <p>Settings saved successfully!</p>
</s-banner>

<!-- Dismissible banner -->
<s-banner tone="warning" onDismiss="handleDismiss">
  <p>Your trial ends in 3 days.</p>
</s-banner>

html

<!-- 信息横幅 -->
<s-banner>
  <p>这是一条提示信息。</p>
</s-banner>

<!-- 错误横幅 -->
<s-banner tone="critical">
  <p>出现错误，请重试。</p>
</s-banner>

<!-- 成功横幅 -->
<s-banner tone="success">
  <p>设置保存成功！</p>
</s-banner>

<!-- 可关闭横幅 -->
<s-banner tone="warning" onDismiss="handleDismiss">
  <p>您的试用将在3天后到期。</p>
</s-banner>

Link

链接

html

<s-link href="/settings">Go to Settings</s-link>

<s-link href="https://shopify.dev" external>
  Documentation
</s-link>

html

<s-link href="/settings">前往设置</s-link>

<s-link href="https://shopify.dev" external>
  官方文档
</s-link>

Form Elements

表单元素

html

<!-- Text field -->
<s-text-field 
  label="Store name"
  value="My Store"
  helpText="This appears in your widget"
></s-text-field>

<!-- Select -->
<s-select label="Language">
  <option value="en">English</option>
  <option value="es">Spanish</option>
</s-select>

<!-- Checkbox -->
<s-checkbox label="Enable notifications" checked></s-checkbox>

html

<!-- 文本输入框 -->
<s-text-field 
  label="店铺名称"
  value="我的店铺"
  helpText="该名称将显示在您的小部件中"
></s-text-field>

<!-- 下拉选择框 -->
<s-select label="语言">
  <option value="en">English</option>
  <option value="es">Spanish</option>
</s-select>

<!-- 复选框 -->
<s-checkbox label="启用通知" checked></s-checkbox>

Common Patterns

常见模式

Settings Page

设置页面

html

<s-page heading="Settings">
  <s-stack direction="block" gap="large">
    
    <s-section heading="General">
      <s-stack direction="block" gap="medium">
        <s-text-field 
          label="Welcome message"
          value="Hello! How can we help?"
        ></s-text-field>
        <s-checkbox label="Enable auto-reply"></s-checkbox>
      </s-stack>
    </s-section>
    
    <s-section heading="Appearance">
      <s-stack direction="block" gap="medium">
        <s-select label="Theme">
          <option value="light">Light</option>
          <option value="dark">Dark</option>
        </s-select>
      </s-stack>
    </s-section>
    
    <s-box paddingBlockStart="large">
      <s-stack direction="inline" gap="medium" justifyContent="flex-end">
        <s-button>Cancel</s-button>
        <s-button variant="primary">Save</s-button>
      </s-stack>
    </s-box>
    
  </s-stack>
</s-page>

html

<s-page heading="Settings">
  <s-stack direction="block" gap="large">
    
    <s-section heading="General">
      <s-stack direction="block" gap="medium">
        <s-text-field 
          label="欢迎语"
          value="您好！有什么可以帮您的？"
        ></s-text-field>
        <s-checkbox label="启用自动回复"></s-checkbox>
      </s-stack>
    </s-section>
    
    <s-section heading="Appearance">
      <s-stack direction="block" gap="medium">
        <s-select label="主题">
          <option value="light">浅色</option>
          <option value="dark">深色</option>
        </s-select>
      </s-stack>
    </s-section>
    
    <s-box paddingBlockStart="large">
      <s-stack direction="inline" gap="medium" justifyContent="flex-end">
        <s-button>取消</s-button>
        <s-button variant="primary">保存</s-button>
      </s-stack>
    </s-box>
    
  </s-stack>
</s-page>

Empty State

空状态

html

<s-section>
  <s-stack direction="block" gap="medium" alignItems="center">
    <s-text variant="headingMd">No campaigns yet</s-text>
    <s-text tone="subdued">
      Create your first campaign to get started.
    </s-text>
    <s-button variant="primary">Create Campaign</s-button>
  </s-stack>
</s-section>

html

<s-section>
  <s-stack direction="block" gap="medium" alignItems="center">
    <s-text variant="headingMd">暂无营销活动</s-text>
    <s-text tone="subdued">
      创建您的第一个营销活动以开始使用。
    </s-text>
    <s-button variant="primary">创建营销活动</s-button>
  </s-stack>
</s-section>

List with Actions

带操作的列表

html

<s-section heading="Campaigns">
  <s-stack direction="block" gap="none">
    
    <s-box padding="medium" borderBlockEnd="base">
      <s-stack direction="inline" justifyContent="space-between" alignItems="center">
        <s-stack direction="block" gap="extraSmall">
          <s-text variant="headingSm">Welcome Series</s-text>
          <s-text tone="subdued">Active • 1,234 sent</s-text>
        </s-stack>
        <s-button>Edit</s-button>
      </s-stack>
    </s-box>
    
    <s-box padding="medium" borderBlockEnd="base">
      <s-stack direction="inline" justifyContent="space-between" alignItems="center">
        <s-stack direction="block" gap="extraSmall">
          <s-text variant="headingSm">Abandoned Cart</s-text>
          <s-text tone="subdued">Paused • 567 sent</s-text>
        </s-stack>
        <s-button>Edit</s-button>
      </s-stack>
    </s-box>
    
  </s-stack>
</s-section>

html

<s-section heading="Campaigns">
  <s-stack direction="block" gap="none">
    
    <s-box padding="medium" borderBlockEnd="base">
      <s-stack direction="inline" justifyContent="space-between" alignItems="center">
        <s-stack direction="block" gap="extraSmall">
          <s-text variant="headingSm">欢迎系列</s-text>
          <s-text tone="subdued">已激活 • 已发送1,234条</s-text>
        </s-stack>
        <s-button>编辑</s-button>
      </s-stack>
    </s-box>
    
    <s-box padding="medium" borderBlockEnd="base">
      <s-stack direction="inline" justifyContent="space-between" alignItems="center">
        <s-stack direction="block" gap="extraSmall">
          <s-text variant="headingSm">购物车挽回</s-text>
          <s-text tone="subdued">已暂停 • 已发送567条</s-text>
        </s-stack>
        <s-button>编辑</s-button>
      </s-stack>
    </s-box>
    
  </s-stack>
</s-section>

TypeScript Support

TypeScript 支持

Add types for s-* components in your

tsconfig.json

json

{
  "compilerOptions": {
    "types": ["@shopify/polaris-types"]
  }
}

在

tsconfig.json

中添加s-*组件的类型声明：

json

{
  "compilerOptions": {
    "types": ["@shopify/polaris-types"]
  }
}

Best Practices

最佳实践

Use s-section for cards - Not s-box
Use s-box for layout only - Padding, borders, spacing
Prefer s- over custom divs* - Only use div when s-* can't achieve the layout
Use semantic structure - s-page > s-section > content
Consistent spacing - Use gap props, not manual margins
Check the docs - Components have many props not shown here

使用s-section实现类卡片容器 - 而非s-box
仅将s-box用于布局 - 内边距、边框、间距调整
*优先使用s-组件而非自定义div - 仅当s-*组件无法实现所需布局时才使用div
使用语义化结构 - s-page > s-section > 内容
保持间距一致 - 使用gap属性，而非手动设置外边距
查阅官方文档 - 组件包含许多本文未提及的属性

When to Use Custom Styles

何时使用自定义样式

Only use plain

div

and inline styles when:

The user explicitly requests it
After trying s-* components and they can't achieve the required layout
For very specific visual effects not supported by Polaris

仅在以下场景使用普通

div

和内联样式：

用户明确要求
尝试过s-*组件但无法实现所需布局
实现Polaris不支持的特殊视觉效果

shopify-polaris-web-components

Original

Translation

Shopify Polaris Web Components

Shopify Polaris Web Components

When to Use

适用场景

Polaris React vs Web Components

Polaris React vs Web Components

Core Components

核心组件

Page Structure

页面结构

Layout with Stack

利用Stack布局

Section (Card-like Container)

Section（类卡片容器）

Box (Generic Layout Container)

Box（通用布局容器）

Buttons

按钮

Text

文本

Banner

横幅

Link

链接

Form Elements

表单元素

Common Patterns

常见模式

Settings Page

设置页面

Empty State

空状态

List with Actions

带操作的列表

TypeScript Support

TypeScript 支持

Best Practices

最佳实践

When to Use Custom Styles

何时使用自定义样式

References

参考资料