wix-cli-site-component

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wix Site Component Builder

Wix 站点组件构建工具

Creates production-quality React site components with editor manifests for Wix CLI applications. Site components are React components that integrate with the Wix Editor, allowing site owners to customize content, styling, and behavior through a visual interface.

为Wix CLI应用创建带有编辑器清单的生产级React站点组件。站点组件是与Wix编辑器集成的React组件，允许站点所有者通过可视化界面自定义内容、样式和行为。

Architecture

架构

Site components consist of four required files:

站点组件包含四个必填文件：

1. Component Manifest (

manifest.json

)

1. 组件清单（

manifest.json

）

Defines the contract between the React component and Wix ecosystem:

editorElement: Root element configuration (selector, displayName, archetype, layout)
cssProperties: CSS API for styling customization
data: Data API for content configuration
elements: Nested element definitions for granular editing
behaviors: Editor interaction behaviors

定义React组件与Wix生态系统之间的契约：

editorElement：根元素配置（选择器、显示名称、原型、布局）
cssProperties：用于样式自定义的CSS API
data：用于内容配置的数据API
elements：用于精细化编辑的嵌套元素定义
behaviors：编辑器交互行为

2. React Component (

component.tsx

)

2. React组件（

component.tsx

）

Production-ready React functional component:

Implements props interface matching manifest data structure
Applies className and id to root element
Handles element removal state via
```
wix.elementsRemovalState
```
Uses sub-component pattern for nested elements
Includes proper TypeScript typing and error handling

生产就绪的React函数式组件：

实现与清单数据结构匹配的props接口
为根元素应用className和id
通过
```
wix.elementsRemovalState
```
处理元素移除状态
对嵌套元素使用子组件模式
包含适当的TypeScript类型定义和错误处理

3. CSS Styles (

style.css

)

3. CSS样式（

style.css

）

Modern CSS with responsive design:

Synced selectors with manifest and React classNames
CSS variables for dynamic styling
Responsive design without media queries (flexbox, grid, clamp)
Pointer events enabled for editor elements
No inline styles for static values
Each selector once only,
```
box-sizing: border-box
```
all elements
NO
```
transition: all
```
, NO media queries (except
```
prefers-reduced-motion
```
)
Root display: Declare
```
--display: [value]
```
CSS variable, then use
```
display: var(--display)
```
on root

具有响应式设计的现代CSS：

与清单和React类名同步选择器
使用CSS变量实现动态样式
无需媒体查询的响应式设计（flexbox、grid、clamp）
为编辑器元素启用指针事件
静态值不使用内联样式
每个选择器仅出现一次，所有元素设置
```
box-sizing: border-box
```
禁止使用
```
transition: all
```
，禁止使用媒体查询（
```
prefers-reduced-motion
```
除外）
根元素显示：声明
```
--display: [value]
```
CSS变量，然后在根元素上使用
```
display: var(--display)
```

4. TypeScript Types (

types.ts

)

4. TypeScript类型定义（

types.ts

）

Strict type definitions:

Props interfaces for all components
Data type mappings (text → string, image → Image object)
Element props structure with optional chaining
Wix system types (Wix interface, REMOVED type)

严格的类型定义：

所有组件的Props接口
数据类型映射（text → string、image → Image对象）
带有可选链的元素props结构
Wix系统类型（Wix接口、REMOVED类型）

Component Manifest Structure

组件清单结构

You MUST read MANIFEST_GUIDELINES.md before implementing a site component. It contains the complete manifest structure, all data types, element configurations, and required patterns.

The manifest defines the editor contract using these key sections:

在实现站点组件之前，你必须阅读MANIFEST_GUIDELINES.md。其中包含完整的清单结构、所有数据类型、元素配置和必填模式。

清单通过以下关键部分定义编辑器契约：

editorElement (Root Configuration)

editorElement（根配置）

json

{
  "selector": ".component-name",
  "displayName": "Component Name",
  "archetype": "Container",
  "layout": {
    "resizeDirection": "horizontalAndVertical",
    "contentResizeDirection": "horizontal"
  },
  "cssProperties": {
    "backgroundColor": {
      "displayName": "Background Color",
      "defaultValue": "#ffffff"
    }
  },
  "data": {
    "columns": {
      "dataType": "number",
      "displayName": "Number of Columns",
      "number": { "minimum": 1, "maximum": 4 }
    }
  },
  "elements": {
    "title": {
      "elementType": "inlineElement",
      "inlineElement": {
        "selector": ".component-name__title",
        "displayName": "Title",
        "data": {
          "titleText": {
            "dataType": "text",
            "displayName": "Title Text"
          }
        },
        "behaviors": {
          "selectable": true,
          "removable": true
        }
      }
    }
  }
}

json

{
  "selector": ".component-name",
  "displayName": "Component Name",
  "archetype": "Container",
  "layout": {
    "resizeDirection": "horizontalAndVertical",
    "contentResizeDirection": "horizontal"
  },
  "cssProperties": {
    "backgroundColor": {
      "displayName": "Background Color",
      "defaultValue": "#ffffff"
    }
  },
  "data": {
    "columns": {
      "dataType": "number",
      "displayName": "Number of Columns",
      "number": { "minimum": 1, "maximum": 4 }
    }
  },
  "elements": {
    "title": {
      "elementType": "inlineElement",
      "inlineElement": {
        "selector": ".component-name__title",
        "displayName": "Title",
        "data": {
          "titleText": {
            "dataType": "text",
            "displayName": "Title Text"
          }
        },
        "behaviors": {
          "selectable": true,
          "removable": true
        }
      }
    }
  }
}

Data Types Reference

数据类型参考

Type	Runtime Value	Use Case
`text`	string	Names, titles, descriptions
`textEnum`	string	Predefined options
`number`	number	Quantities, dimensions
`booleanValue`	boolean	Toggles, flags
`a11y`	Object	Accessibility attributes
`link`	`{ href, target, rel }`	Navigation links
`image`	`{ uri, url, alt, width, height }`	Images
`video`	Video object	Media content
`vectorArt`	Sanitized SVG object	Icons, graphics
`localDate`	string (YYYY-MM-DD)	Date values
`localTime`	string (hh:mm)	Time values
`webUrl`	string	External URLs
`richText`	string (HTML)	Formatted content
`arrayItems`	Array	Collections, lists
`direction`	string	HTML dir attribute
`menuItems`	Array of menu items	Navigation menus

类型	运行时值	使用场景
`text`	string	名称、标题、描述
`textEnum`	string	预定义选项
`number`	number	数量、尺寸
`booleanValue`	boolean	开关、标记
`a11y`	Object	无障碍属性
`link`	`{ href, target, rel }`	导航链接
`image`	`{ uri, url, alt, width, height }`	图片
`video`	Video对象	媒体内容
`vectorArt`	经过清理的SVG对象	图标、图形
`localDate`	string（YYYY-MM-DD）	日期值
`localTime`	string（hh:mm）	时间值
`webUrl`	string	外部URL
`richText`	string（HTML）	格式化内容
`arrayItems`	Array	集合、列表
`direction`	string	HTML dir属性
`menuItems`	菜单项数组	导航菜单

CSS Properties Reference

CSS属性参考

Common CSS properties for styling customization:

Layout:
```
display
```
,
```
gap
```
,
```
padding
```
,
```
margin
```
,
```
width
```
,
```
height
```
Typography:
```
font
```
,
```
fontSize
```
,
```
fontWeight
```
,
```
textAlign
```
,
```
color
```
Background:
```
backgroundColor
```
,
```
backgroundImage
```
Border:
```
border
```
,
```
borderRadius
```
,
```
boxShadow
```
Positioning:
```
alignItems
```
,
```
justifyContent
```
,
```
flexDirection
```

Complete CSS properties reference: See CSS_GUIDELINES.md for all CSS properties, variable patterns, and styling best practices.

用于样式自定义的常见CSS属性：

布局：
```
display
```
、
```
gap
```
、
```
padding
```
、
```
margin
```
、
```
width
```
、
```
height
```
排版：
```
font
```
、
```
fontSize
```
、
```
fontWeight
```
、
```
textAlign
```
、
```
color
```
背景：
```
backgroundColor
```
、
```
backgroundImage
```
边框：
```
border
```
、
```
borderRadius
```
、
```
boxShadow
```
定位：
```
alignItems
```
、
```
justifyContent
```
、
```
flexDirection
```

完整CSS属性参考：查看CSS_GUIDELINES.md获取所有CSS属性、变量模式和样式最佳实践。

React Component Patterns

React组件模式

Complete reference: See REACT_PATTERNS.md for detailed component architecture, all coding patterns, and implementation examples.

完整参考：查看REACT_PATTERNS.md获取详细的组件架构、所有编码模式和实现示例。

Props Structure

Props结构

typescript

interface ComponentProps {
  // Standard props (always present)
  className: string;
  id: string;
  wix?: Wix;

  // Component-level data (from editorElement.data)
  columns?: number;
  layout?: string;

  // Element props (from elements definitions)
  elementProps?: {
    title?: {
      titleText?: string;
      wix?: Wix;
    };
    button?: {
      buttonText?: string;
      buttonLink?: Link;
      wix?: Wix;
    };
  };
}

typescript

interface ComponentProps {
  // 标准props（始终存在）
  className: string;
  id: string;
  wix?: Wix;

  // 组件级数据（来自editorElement.data）
  columns?: number;
  layout?: string;

  // 元素props（来自元素定义）
  elementProps?: {
    title?: {
      titleText?: string;
      wix?: Wix;
    };
    button?: {
      buttonText?: string;
      buttonLink?: Link;
      wix?: Wix;
    };
  };
}

Sub-Component Pattern

子组件模式

Extract every distinct UI element into named sub-components:

typescript

// Title sub-component
interface TitleProps {
  titleText?: string;
  className: string;
}

const Title: FC<TitleProps> = ({ titleText = "Default Title", className }) => (
  <h2 className={className}>{titleText}</h2>
);

// Main component
const ProductCard: FC<ProductCardProps> = ({
  className,
  id,
  elementProps,
  wix
}) => {
  const removalState = wix?.elementsRemovalState || {};

  return (
    <div className={`product-card ${className}`} id={id}>
      {!removalState['title'] && (
        <Title
          className="product-card__title"
          {...elementProps?.title}
        />
      )}
      {!removalState['button'] && (
        <Button
          className="product-card__button"
          {...elementProps?.button}
        />
      )}
    </div>
  );
};

将每个不同的UI元素提取为命名子组件：

typescript

// 标题子组件
interface TitleProps {
  titleText?: string;
  className: string;
}

const Title: FC<TitleProps> = ({ titleText = "Default Title", className }) => (
  <h2 className={className}>{titleText}</h2>
);

// 主组件
const ProductCard: FC<ProductCardProps> = ({
  className,
  id,
  elementProps,
  wix
}) => {
  const removalState = wix?.elementsRemovalState || {};

  return (
    <div className={`product-card ${className}`} id={id}>
      {!removalState['title'] && (
        <Title
          className="product-card__title"
          {...elementProps?.title}
        />
      )}
      {!removalState['button'] && (
        <Button
          className="product-card__button"
          {...elementProps?.button}
        />
      )}
    </div>
  );
};

Conditional Rendering

条件渲染

All elements must be conditionally rendered based on removal state:

typescript

const removalState = wix?.elementsRemovalState || {};

return (
  <div className={`component ${className}`} id={id}>
    {!removalState['elementKey'] && <Element />}
  </div>
);

所有元素必须根据移除状态进行条件渲染：

typescript

const removalState = wix?.elementsRemovalState || {};

return (
  <div className={`component ${className}`} id={id}>
    {!removalState['elementKey'] && <Element />}
  </div>
);

CSS Guidelines

CSS指南

Responsive Design Strategy

响应式设计策略

Components live in user-resizable containers (300-1200px) within varying viewports:

Root element:
```
width: 100%; height: 100%
```
Layout structure: Use CSS Grid and Flexbox for fluid responsiveness
Typography: Use
```
clamp()
```
for fluid scaling
Spacing: Fixed or tight clamp spacing (≤50% variation)

组件位于用户可调整大小的容器（300-1200px）中，适配不同视口：

根元素：
```
width: 100%; height: 100%
```
布局结构：使用CSS Grid和Flexbox实现流畅的响应式效果
排版：使用
```
clamp()
```
实现流畅缩放
间距：固定或窄范围的clamp间距（变化≤50%）

CSS Variables for Dynamic Styling

用于动态样式的CSS变量

css

.component {
  --display: block;
  --background-color: #ffffff;
  --text-color: #333333;

  display: var(--display);
  background-color: var(--background-color);
  color: var(--text-color);
  pointer-events: auto;
}

css

.component {
  --display: block;
  --background-color: #ffffff;
  --text-color: #333333;

  display: var(--display);
  background-color: var(--background-color);
  color: var(--text-color);
  pointer-events: auto;
}

Selector Synchronization

选择器同步

CRITICAL: CSS selectors must match manifest selectors and React classNames exactly:

React:
```
className="product-card__title"
```
CSS:
```
.product-card__title { ... }
```
Manifest:
```
"selector": ".product-card__title"
```

关键：CSS选择器必须与清单选择器和React类名完全匹配：

React：
```
className="product-card__title"
```
CSS：
```
.product-card__title { ... }
```
清单：
```
"selector": ".product-card__title"
```

Design Guidelines

设计指南

Complete reference: See DESIGN_SYSTEM.md for visual design principles, creative guidelines, and aesthetic best practices.

完整参考：查看DESIGN_SYSTEM.md获取视觉设计原则、创意指南和美学最佳实践。

Spacing as Communication

间距作为沟通方式

Relationship	Value	Use Case
Tight (icon + label)	0.25-0.5rem (4-8px)	Clustering related items
Same category	1-1.5rem (16-24px)	Card sections, form fields
Different sections	2-3rem (32-48px)	Major content blocks
Emphasis/Drama	4rem+ (64px+)	Hero content, luxury feel

关系	值	使用场景
紧凑（图标+标签）	0.25-0.5rem（4-8px）	相关项聚类
同类项	1-1.5rem（16-24px）	卡片区块、表单字段
不同区块	2-3rem（32-48px）	主要内容块
强调/突出	4rem+（64px+）	首屏内容、高端风格

Visual Consistency

视觉一致性

Corner Radius: All similar elements share same radius (0-4px sharp, 6-12px rounded)
Shadow Levels: Max 3 levels (rest, hover, floating)
Element Heights: Consistent heights for similar elements
Color Strategy: Use full palette purposefully for hierarchy and zones

圆角半径：所有相似元素使用相同的半径（0-4px为锐利，6-12px为圆润）
阴影层级：最多3个层级（静止、悬停、悬浮）
元素高度：相似元素使用一致的高度
色彩策略：有目的地使用完整调色板构建层级和区域

Creative Exploration

创意探索

Push beyond obvious solutions:

Cards: Asymmetric grids, overlapping elements, thick accent borders
Lists: Alternating styles, spotlight patterns, color rhythm
Interactive Elements: Split buttons, colored icon circles, smooth transitions
Content Hierarchy: Large numbers for stats, quote callouts, whitespace dividers

超越常规解决方案：

卡片：非对称网格、重叠元素、粗强调边框
列表：交替样式、焦点模式、色彩节奏
交互元素：拆分按钮、彩色图标圆圈、平滑过渡
内容层级：大数字展示统计数据、引用标注、空白分隔符

Component Elements Guidelines

组件元素指南

One Element = One Manifest Entry

一个元素 = 一个清单条目

Each distinct visual part requires a separate manifest element:

✅ 3 buttons → 3 separate elements
✅ Image + text → 2 separate elements
❌ Multiple items grouped as one element

每个不同的视觉部分都需要单独的清单元素：

✅ 3个按钮 → 3个单独元素
✅ 图片+文本 → 2个单独元素
❌ 多个项分组为一个元素

Data Scoping Rules

数据作用域规则

editorElement.data - Component-wide configuration only:

✅ Layout enums, numbers (columns: 3, speed: 500)
❌ Text, links, images (belongs to elements)
❌ show/hide booleans (use removable: true instead)

elements[key].data - Content for that specific element:

✅ Element-specific content (title text, button link, image)

editorElement.data - 仅用于组件级配置：

✅ 布局枚举、数字（columns: 3, speed: 500）
❌ 文本、链接、图片（属于元素）
❌ 显示/隐藏布尔值（改用removable: true）

elements[key].data - 该特定元素的内容：

✅ 元素专属内容（标题文本、按钮链接、图片）

Asset Requirements

资源要求

When components need default images, use this format:

typescript

// Import in component
import { heroImage } from './assets/defaultImages';

// Usage
<img src={heroImage} alt="Hero" />

Asset specification format:

<imageUrlName>
{ "description": "Modern cityscape at sunset", "width": 1920, "height": 1088 }
</imageUrlName>

Rules:

Import as named export from
```
'./assets/defaultImages'
```
Width/height: multiples of 64, between 128-2048px
NEVER use external URLs

当组件需要默认图片时，使用以下格式：

typescript

// 在组件中导入
import { heroImage } from './assets/defaultImages';

// 使用
<img src={heroImage} alt="Hero" />

资源规范格式：

<imageUrlName>
{ "description": "Modern cityscape at sunset", "width": 1920, "height": 1088 }
</imageUrlName>

规则：

从
```
'./assets/defaultImages'
```
作为命名导出导入
宽度/高度：64的倍数，介于128-2048px之间
禁止使用外部URL

Output Structure

输出结构

src/site/components/
└── {component-name}/
    ├── manifest.json        # Component manifest
    ├── component.tsx        # React component
    ├── style.css           # CSS styles
    ├── types.ts            # TypeScript types
    └── assets/             # Optional assets
        └── defaultImages.ts

src/site/components/
└── {component-name}/
    ├── manifest.json        # 组件清单
    ├── component.tsx        # React组件
    ├── style.css           # CSS样式
    ├── types.ts            # TypeScript类型定义
    └── assets/             # 可选资源
        └── defaultImages.ts

Examples

示例

Complete working example: See EXAMPLE.md for a full production-ready site component with all patterns, including manifest, React component, CSS, and types.

完整可用示例：查看EXAMPLE.md获取包含所有模式的完整生产级站点组件示例，包括清单、React组件、CSS和类型定义。

Product Card Component

产品卡片组件

Request: "Create a product card component with image, title, price, and buy button"

Output:

Manifest with 4 elements (image, title, price, button)
React component with sub-components for each element
CSS with responsive grid layout and hover effects
TypeScript types for all props and data structures

需求： "创建包含图片、标题、价格和购买按钮的产品卡片组件"

输出：

包含4个元素（图片、标题、价格、按钮）的清单
带有每个元素子组件的React组件
带有响应式网格布局和悬停效果的CSS
所有props和数据结构的TypeScript类型定义

Hero Section Component

首屏区块组件

Request: "Build a hero section with background image, headline, subtitle, and CTA button"

Output:

Manifest with background image CSS property and 3 text elements
React component with overlay design and typography hierarchy
CSS with responsive text scaling and dramatic spacing
Asset specifications for default hero images

需求： "构建包含背景图片、标题、副标题和CTA按钮的首屏区块"

输出：

包含背景图片CSS属性和3个文本元素的清单
带有覆盖层设计和排版层级的React组件
带有响应式文本缩放和醒目间距的CSS
默认首屏图片的资源规范

Feature List Component

功能列表组件

Request: "Create a features component with configurable number of items"

Output:

Manifest with arrayItems data type for feature collection
React component mapping over features array with safety checks
CSS with flexible grid layout adapting to item count
Sub-components for feature icons, titles, and descriptions

需求： "创建可配置项数量的功能组件"

输出：

带有arrayItems数据类型的清单，用于功能集合
对功能数组进行映射并包含安全检查的React组件
可根据项数自适应的灵活网格布局CSS
功能图标、标题和描述的子组件

Extension Registration

扩展注册

Extension registration is MANDATORY and has TWO required steps.

扩展注册是强制性的，包含两个必填步骤。

Step 1: Create Component-Specific Extension File

步骤1：创建组件专属扩展文件

Each site component requires an

extensions.ts

file in its folder:

typescript

import { extensions } from "@wix/astro/builders";
import manifest from "./site/components/my-component/manifest.json";

export const sitecomponentMyComponent = extensions.siteComponent({
  ...manifest,
  id: "{{GENERATE_UUID}}",
  description: "My Component",
  type: "platform.builder.{{GENERATE_UUID}}",
  resources: {
    client: {
      component: "./site/components/my-component/component.tsx",
      componentUrl: "./site/components/my-component/component.tsx",
    },
  },
});

Note: The

id

and

type

should use the same UUID.

CRITICAL: UUID Generation

The

id

must be a unique, static UUID v4 string. Generate a fresh UUID for each extension - do NOT use

randomUUID()

or copy UUIDs from examples.

每个站点组件在其文件夹中都需要一个

extensions.ts

文件：

typescript

import { extensions } from "@wix/astro/builders";
import manifest from "./site/components/my-component/manifest.json";

export const sitecomponentMyComponent = extensions.siteComponent({
  ...manifest,
  id: "{{GENERATE_UUID}}",
  description: "My Component",
  type: "platform.builder.{{GENERATE_UUID}}",
  resources: {
    client: {
      component: "./site/components/my-component/component.tsx",
      componentUrl: "./site/components/my-component/component.tsx",
    },
  },
});

注意：

id

和

type

应使用相同的UUID。

关键：UUID生成

id

必须是唯一的静态UUID v4字符串。为每个扩展生成新的UUID - 不要使用

randomUUID()

或复制示例中的UUID。

Step 2: Register in Main Extensions File

步骤2：在主扩展文件中注册

CRITICAL: After creating the component-specific extension file, you MUST read wix-cli-extension-registration and follow the "App Registration" section to update

src/extensions.ts

Without completing Step 2, the site component will not be available in the Wix Editor.

关键： 创建组件专属扩展文件后，你必须阅读wix-cli-extension-registration并按照“应用注册”部分的说明更新

src/extensions.ts

。

未完成步骤2的话，站点组件将无法在Wix编辑器中使用。

Code Quality Requirements

代码质量要求

Complete reference: See TYPESCRIPT_QUALITY.md for comprehensive type safety guidelines and code quality standards.

完整参考：查看TYPESCRIPT_QUALITY.md获取全面的类型安全指南和代码质量标准。

TypeScript Standards

TypeScript标准

Strict TypeScript with no
```
any
```
types
Explicit return types for all functions
Proper null/undefined handling with optional chaining
No
```
@ts-ignore
```
or
```
@ts-expect-error
```
comments

严格模式TypeScript，禁止使用
```
any
```
类型
所有函数的显式返回类型
使用可选链正确处理null/undefined
禁止使用
```
@ts-ignore
```
或
```
@ts-expect-error
```
注释

React Best Practices

React最佳实践

Functional components with hooks
Proper dependency arrays in useEffect
Component must react to prop changes
SSR-safe code (no browser APIs at module scope)

使用hooks的函数式组件
useEffect中正确的依赖数组
组件必须响应props变化
支持SSR的代码（模块作用域中禁止使用浏览器API）

ESLint Compliance

ESLint合规性

No unused vars/params/imports (
```
@typescript-eslint/no-unused-vars
```
)
No external images:
```
img
```
```
src
```
not
```
https://...
```
(allowed: local imports,
```
wixstatic.com
```
, variables)
SSR-safe: No
```
window
```
/
```
document
```
at module scope/constructor, guard browser APIs in
```
useEffect
```
/handlers
No
```
dangerouslySetInnerHTML
```
or inline
```
<style>
```
tags - use CSS variables or inline
```
style
```
prop for dynamic values
No
```
window.fetch
```
(
```
no-restricted-properties
```
)
Hooks
```
exhaustive-deps
```
: ALL values from component scope used inside
```
useEffect
```
/
```
useCallback
```
MUST be in dependency array
Use
```
const
```
/
```
let
```
(no
```
var
```
), no unknown JSX properties

无未使用的变量/参数/导入（
```
@typescript-eslint/no-unused-vars
```
）
无外部图片：
```
img
```
的
```
src
```
不能是
```
https://...
```
（允许：本地导入、
```
wixstatic.com
```
、变量）
支持SSR：模块作用域/构造函数中禁止使用
```
window
```
/
```
document
```
，在
```
useEffect
```
/处理函数中对浏览器API进行防护
禁止使用
```
dangerouslySetInnerHTML
```
或内联
```
<style>
```
标签 - 使用CSS变量或内联
```
style
```
prop实现动态值
禁止使用
```
window.fetch
```
（
```
no-restricted-properties
```
）
Hooks
```
exhaustive-deps
```
：
```
useEffect
```
/
```
useCallback
```
中使用的所有组件作用域内的值必须在依赖数组中
使用
```
const
```
/
```
let
```
（禁止使用
```
var
```
），禁止未知的JSX属性

Hard Constraints

硬性约束

Do NOT invent or assume new types, modules, functions, props, events, or imports
Use only entities explicitly present in the provided references or standard libraries already used in this project

Do NOT add dependencies; do NOT use

@wix/design-system

@wix/wix-ui-icons-common

All user-facing content must come from props (no hardcoded text)
Links/media from manifest only, never hardcode URLs
NEVER use mocks, placeholders, or TODOs in any code
ALWAYS implement complete, production-ready functionality

禁止发明或假设新的类型、模块、函数、props、事件或导入
仅使用提供的参考资料中明确存在的实体，或本项目中已使用的标准库

禁止添加依赖；禁止使用

@wix/design-system

或

@wix/wix-ui-icons-common

所有面向用户的内容必须来自props（禁止硬编码文本）
链接/媒体仅来自清单，禁止硬编码URL
禁止在任何代码中使用模拟数据、占位符或TODO
始终实现完整的生产级功能

Verification

验证

After implementation, use wix-cli-app-validation to validate TypeScript compilation, build, preview, and runtime behavior.

实现完成后，使用wix-cli-app-validation验证TypeScript编译、构建、预览和运行时行为。

Reference Documentation

参考文档

Complete Example - Full production-ready site component example with all patterns
Component Manifest Guidelines - Detailed manifest structure and best practices
React Patterns - Component architecture and coding patterns
CSS Guidelines - Styling conventions and responsive design
Design System - Visual design principles and creative guidelines
TypeScript Quality - Type safety and code quality standards

完整示例 - 包含所有模式的完整生产级站点组件示例
组件清单指南 - 详细的清单结构和最佳实践
React模式 - 组件架构和编码模式
CSS指南 - 样式约定和响应式设计
设计系统 - 视觉设计原则和创意指南
TypeScript质量标准 - 类型安全和代码质量标准

wix-cli-site-component

Original

Translation

Wix Site Component Builder

Wix 站点组件构建工具

Architecture

架构

1. Component Manifest (manifest.json)

1. 组件清单（manifest.json）

2. React Component (component.tsx)

2. React组件（component.tsx）

3. CSS Styles (style.css)

3. CSS样式（style.css）

4. TypeScript Types (types.ts)

4. TypeScript类型定义（types.ts）

Component Manifest Structure

组件清单结构

editorElement (Root Configuration)

editorElement（根配置）

Data Types Reference

数据类型参考

CSS Properties Reference

CSS属性参考

React Component Patterns

React组件模式

Props Structure

Props结构

Sub-Component Pattern

子组件模式

Conditional Rendering

条件渲染

CSS Guidelines

CSS指南

Responsive Design Strategy

响应式设计策略

CSS Variables for Dynamic Styling

用于动态样式的CSS变量

Selector Synchronization

选择器同步

Design Guidelines

设计指南

Spacing as Communication

间距作为沟通方式

Visual Consistency

视觉一致性

Creative Exploration

创意探索

Component Elements Guidelines

组件元素指南

One Element = One Manifest Entry

一个元素 = 一个清单条目

Data Scoping Rules

数据作用域规则

Asset Requirements

资源要求

Output Structure

输出结构

Examples

示例

Product Card Component

产品卡片组件

Hero Section Component

首屏区块组件

Feature List Component

功能列表组件

Extension Registration

扩展注册

Step 1: Create Component-Specific Extension File

步骤1：创建组件专属扩展文件

Step 2: Register in Main Extensions File

步骤2：在主扩展文件中注册

Code Quality Requirements

代码质量要求

TypeScript Standards

TypeScript标准

React Best Practices

React最佳实践

ESLint Compliance

ESLint合规性

Hard Constraints

1. Component Manifest (
`manifest.json`
)

1. 组件清单（
`manifest.json`
）

2. React Component (
`component.tsx`
)

2. React组件（
`component.tsx`
）

3. CSS Styles (
`style.css`
)

3. CSS样式（
`style.css`
）

4. TypeScript Types (
`types.ts`
)

4. TypeScript类型定义（
`types.ts`
）