shopify-polaris-web-components

Shopify Polaris Web Components

在使用 Polaris Web Components 为 Shopify App Home 界面构建 UI 时，请使用此技能。

适用场景

• 构建 App Home 页面（Shopify Admin iframe 外部的应用界面）
• 使用 s-* 自定义元素创建 UI
• 使用 s-section、s-stack、s-box 设计布局
• 为 App Home 构建表单、模态框或列表

重要：App Home 使用 Polaris Web Components（s-* 元素），而非 Polaris React（@shopify/polaris）。这是两种不同的技术。

Polaris React 与 Web Components

特性	Polaris React	Polaris Web Components
用途	嵌入式管理应用	App Home 界面
导入方式	@shopify/polaris	无需导入（原生元素）
语法	<Button>	<s-button>
框架	React 组件	自定义 HTML 元素

核心组件

页面结构

<s-page heading="Dashboard">
  <s-section heading="Overview">
    
  </s-section>
  
  <s-section heading="Settings">
    
  </s-section>
</s-page>

使用 Stack 布局

<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（卡片式容器）

使用 s-section 组织内容，并可选择添加标题：

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


<s-section>
  <s-text>Simple content block</s-text>
</s-section>

Box（通用布局容器）

使用 s-box 添加内边距、边框和间距——不要用于卡片：

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


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


<s-box paddingBlockStart="large">
  <s-text>Content with top margin</s-text>
</s-box>

规则：使用 s-section 作为卡片式容器，仅使用 s-box 进行布局和间距设置。

按钮

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


<s-button>Cancel</s-button>


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


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


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

文本

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


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


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

横幅

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


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


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


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

链接

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

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

表单元素

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


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


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

常见模式

设置页面

<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>

空状态

<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>

带操作项的列表

<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>

TypeScript 支持

在 tsconfig.json 中为 s-* 组件添加类型：

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

最佳实践

1. 卡片使用 s-section——不要使用 s-box
2. s-box 仅用于布局——内边距、边框、间距
3. 优先使用 s-*，而非自定义 div——只有 s-* 无法实现所需布局时才使用 div
4. 使用语义化结构——s-page > s-section > 内容
5. 保持间距一致——使用 gap 属性，而非手动设置外边距
6. 查阅文档——组件还有许多此处未展示的属性

何时使用自定义样式

仅在以下情况下使用普通 div 和内联样式：

• 用户明确要求
• 尝试使用 s-* 组件后，仍无法实现所需布局
• 实现 Polaris 不支持的特定视觉效果

参考资料

• Polaris Web Components
• 使用 Polaris 组件
• App Home 概览
• 组件参考