Back to Details

shopify-polaris-viz

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Shopify Polaris Viz

Shopify Polaris Viz

Polaris Viz is Shopify's data visualization component library for React. It provides accessible, themeable chart components that match the Shopify Admin visual style.
Note: This library was archived in June 2025. While still functional, Shopify recommends reaching out to support for migration assistance if building new features.
Polaris Viz是Shopify面向React的数据可视化组件库。它提供了符合Shopify Admin视觉风格、支持无障碍访问、可自定义主题的图表组件。
注意：本库已于2025年6月归档。虽然仍可正常使用，但如果你要构建新功能，Shopify建议联系支持团队获取迁移协助。

Installation

安装

bash
npm install @shopify/polaris-viz
bash
npm install @shopify/polaris-viz

Required peer dependencies

Required peer dependencies

npm install @shopify/polaris @shopify/polaris-tokens
undefined
npm install @shopify/polaris @shopify/polaris-tokens
undefined

Setup

初始化配置

Wrap your application with 
PolarisVizProvider
:
jsx
import { PolarisVizProvider } from '@shopify/polaris-viz';
import '@shopify/polaris-viz/build/esm/styles.css';

function App() {
  return (
    <PolarisVizProvider>
      {/* Your app */}
    </PolarisVizProvider>
  );
}
使用
PolarisVizProvider
包裹你的应用：
jsx
import { PolarisVizProvider } from '@shopify/polaris-viz';
import '@shopify/polaris-viz/build/esm/styles.css';

function App() {
  return (
    <PolarisVizProvider>
      {/* Your app */}
    </PolarisVizProvider>
  );
}

Core Design Principles

核心设计原则

  1. One Question Per Chart: Each visualization should answer a single, specific question
  2. Accuracy First: Faithfully represent the original dataset
  3. Accessibility: Support screen readers, color-blind users, and multiple data formats
  4. Consistency: Use Polaris themes for visual harmony with Shopify Admin
  1. 一图一问：每个可视化图表仅用来回答一个明确的特定问题
  2. 准确性优先：忠实还原原始数据集的真实情况
  3. 无障碍支持：适配屏幕阅读器、色盲用户，支持多种数据格式
  4. 一致性：使用Polaris主题保证与Shopify Admin的视觉风格统一

Available Chart Components

可用图表组件

ComponentUse CaseMax Data Points
BarChart
Comparing discrete categories~6 categories
SimpleBarChart
Simple horizontal bars~6 categories
LineChart
Trends over time30+ points
SparkLineChart
Compact inline trendsAny
DonutChart
Part-to-whole relationships~6 segments
StackedAreaChart
Cumulative trends30+ points
FunnelChart
Conversion funnels~6 stages
组件适用场景最大数据量
BarChart
离散类别对比约6个类别
SimpleBarChart
简单横向柱状图约6个类别
LineChart
随时间变化的趋势30个以上数据点
SparkLineChart
紧凑型行内趋势图无限制
DonutChart
部分与整体的关系约6个分段
StackedAreaChart
累积趋势30个以上数据点
FunnelChart
转化漏斗约6个阶段

Quick Examples

快速示例

Bar Chart

柱状图

jsx
import { BarChart } from '@shopify/polaris-viz';

const data = [
  {
    name: 'Sales',
    data: [
      { key: 'Monday', value: 150 },
      { key: 'Tuesday', value: 200 },
      { key: 'Wednesday', value: 175 },
    ],
  },
];

<BarChart data={data} />
jsx
import { BarChart } from '@shopify/polaris-viz';

const data = [
  {
    name: 'Sales',
    data: [
      { key: 'Monday', value: 150 },
      { key: 'Tuesday', value: 200 },
      { key: 'Wednesday', value: 175 },
    ],
  },
];

<BarChart data={data} />

Line Chart

折线图

jsx
import { LineChart } from '@shopify/polaris-viz';

const data = [
  {
    name: 'Orders',
    data: [
      { key: 'Jan', value: 100 },
      { key: 'Feb', value: 150 },
      { key: 'Mar', value: 200 },
    ],
  },
];

<LineChart data={data} />
jsx
import { LineChart } from '@shopify/polaris-viz';

const data = [
  {
    name: 'Orders',
    data: [
      { key: 'Jan', value: 100 },
      { key: 'Feb', value: 150 },
      { key: 'Mar', value: 200 },
    ],
  },
];

<LineChart data={data} />

Donut Chart

环形图

jsx
import { DonutChart } from '@shopify/polaris-viz';

const data = [
  { name: 'Direct', data: [{ key: 'Direct', value: 200 }] },
  { name: 'Social', data: [{ key: 'Social', value: 150 }] },
  { name: 'Email', data: [{ key: 'Email', value: 100 }] },
];

<DonutChart data={data} />
jsx
import { DonutChart } from '@shopify/polaris-viz';

const data = [
  { name: 'Direct', data: [{ key: 'Direct', value: 200 }] },
  { name: 'Social', data: [{ key: 'Social', value: 150 }] },
  { name: 'Email', data: [{ key: 'Email', value: 100 }] },
];

<DonutChart data={data} />

Spark Line (Inline Trend)

迷你折线图（行内趋势）

jsx
import { SparkLineChart } from '@shopify/polaris-viz';

const data = [
  {
    data: [
      { key: 0, value: 100 },
      { key: 1, value: 150 },
      { key: 2, value: 120 },
      { key: 3, value: 180 },
    ],
  },
];

<SparkLineChart data={data} />
jsx
import { SparkLineChart } from '@shopify/polaris-viz';

const data = [
  {
    data: [
      { key: 0, value: 100 },
      { key: 1, value: 150 },
      { key: 2, value: 120 },
      { key: 3, value: 180 },
    ],
  },
];

<SparkLineChart data={data} />

Data Structure

数据结构

All charts use a consistent 
DataSeries
format:
typescript
interface DataPoint {
  key: string | number;  // X-axis value or category
  value: number | null;  // Y-axis value (null for gaps)
}

interface DataSeries {
  name: string;           // Series label
  data: DataPoint[];      // Array of data points
  color?: string;         // Optional color override
  isComparison?: boolean; // Mark as comparison data (renders grey)
}
所有图表都使用统一的
DataSeries
格式：
typescript
interface DataPoint {
  key: string | number;  // X轴数值或分类
  value: number | null;  // Y轴数值（空值用null表示）
}

interface DataSeries {
  name: string;           // 系列标签
  data: DataPoint[];      // 数据点数组
  color?: string;         // 可选自定义颜色
  isComparison?: boolean; // 标记为对比数据（渲染为灰色）
}

Theming

主题定制

Use the 
theme
prop to switch between themes:
jsx
// Use built-in themes
<BarChart data={data} theme="Light" />
<BarChart data={data} theme="Dark" />

// Or define custom themes in provider
<PolarisVizProvider
  themes={{
    MyBrand: {
      chartContainer: { backgroundColor: '#f9f9f9' },
      seriesColors: { upToEight: ['#5c6ac4', '#47c1bf'] },
    },
  }}
>
  <BarChart data={data} theme="MyBrand" />
</PolarisVizProvider>
使用
theme
属性切换主题：
jsx
// 使用内置主题
<BarChart data={data} theme="Light" />
<BarChart data={data} theme="Dark" />

// 也可以在Provider中定义自定义主题
<PolarisVizProvider
  themes={{
    MyBrand: {
      chartContainer: { backgroundColor: '#f9f9f9' },
      seriesColors: { upToEight: ['#5c6ac4', '#47c1bf'] },
    },
  }}
>
  <BarChart data={data} theme="MyBrand" />
</PolarisVizProvider>

Color Guidelines

颜色使用指南

  • Single series: Use one consistent color
  • Comparison to past: Current = purple, Historical = grey
  • Multiple series: Use contrasting colors (max 4 lines recommended)
  • Positive/Negative: Green = positive, Red = negative
  • 单数据系列：使用统一的颜色
  • 与历史数据对比：当前数据=紫色，历史数据=灰色
  • 多数据系列：使用对比色（建议最多4条折线）
  • 正负值区分：绿色=正向，红色=负向

Accessibility Requirements

无障碍要求

  1. Color contrast: Ensure sufficient contrast between elements
  2. Screen readers: Charts render with ARIA attributes
  3. Text alternatives: Provide data tables as alternative format
  4. No color-only meaning: Use patterns or labels alongside color
  1. 颜色对比度：确保元素之间有足够的对比度
  2. 屏幕阅读器支持：图表自带ARIA属性
  3. 文本替代方案：提供数据表格作为替代展示形式
  4. 禁止仅靠颜色传递含义：在颜色之外搭配图案或标签使用

Common Props

通用属性

Most chart components accept these props:
PropTypeDescription
data
DataSeries[]
Chart data
theme
string
Theme name
isAnimated
boolean
Enable/disable animations
showLegend
boolean
Show legend
xAxisOptions
object
X-axis configuration
yAxisOptions
object
Y-axis configuration
emptyStateText
string
Text when no data
大多数图表组件都支持以下属性：
属性类型说明
data
DataSeries[]
图表数据
theme
string
主题名称
isAnimated
boolean
开/关动画效果
showLegend
boolean
是否显示图例
xAxisOptions
object
X轴配置
yAxisOptions
object
Y轴配置
emptyStateText
string
无数据时的提示文字

Axis Label Formatting

轴标签格式化

Follow Shopify's formatting standards:
  • Times: 12-hour lowercase (12am, 6pm)
  • Days: Three letters (Sun, Mon)
  • Months: Three letters (Feb, Mar)
  • Dates: "10 Apr" format
  • Numbers: Use "k" for thousands, max 3 digits + decimal + letter
遵循Shopify的格式化标准：
  • 时间：12小时制小写（12am、6pm）
  • 天：三个字母缩写（Sun、Mon）
  • 月：三个字母缩写（Feb、Mar）
  • 日期：使用「10 Apr」格式
  • 数字：千位用「k」表示，最多保留3位数字+小数+单位

Anti-Patterns to Avoid

需要避免的反模式

  • DO NOT exceed 6 categories in bar/donut charts - use tables instead
  • DO NOT use more than 4 lines in a line chart
  • DO NOT rely on color alone to convey meaning
  • DO NOT use edge-to-edge axis lines - keep them within data range
  • DO NOT mix Polaris Viz with other chart libraries in the same app
  • 不要在柱状图/环形图中使用超过6个类别，超出请使用表格
  • 不要在折线图中使用超过4条折线
  • 不要仅依赖颜色传递信息
  • 不要使用占满整个画布的轴线，轴线范围应匹配数据区间
  • 不要在同一个应用中混合使用Polaris Viz和其他图表库

References

参考资料

  • Chart Components - Detailed props and examples for each chart type
  • Theming Guide - Custom theme configuration
  • Data Structures - Complete TypeScript interfaces
  • 图表组件 - 各类图表的详细属性和示例
  • 主题指南 - 自定义主题配置说明
  • 数据结构 - 完整TypeScript接口定义

External Resources

外部资源