Zent

https://github.com/youzan/zent
Admin
Zent is a React component library developed at Youzan, offering a collection of essential UI...
Tokens:243,446
Snippets:829
Trust Score:9.5
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Zent Development Environment Setup

Source: https://github.com/youzan/zent/blob/master/site/README.md

Instructions to set up and run the Zent development server locally. This involves installing project dependencies and starting the development server, which will be accessible via a web browser at the specified address.

```bash
yarn

npm run dev
```

--------------------------------

### Initialize Zent Development Environment

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/CONTRIBUTING_en-US.md

Sets up the Zent project by installing dependencies and preparing the development environment. Ensure `coreutils` is installed before running this command.

```bash
yarn bootstrap
```

--------------------------------

### Run Zent Documentation Site Locally

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/CONTRIBUTING_en-US.md

Starts a local development server for the Zent documentation website. This command should be executed from within the `site` directory to view documentation changes in real-time.

```bash
yarn dev
```

--------------------------------

### Initialize Zent Project Development Environment

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/CONTRIBUTING_zh-CN.md

This command initializes the Zent project, setting up all necessary dependencies and configurations for local development. It is crucial to ensure `coreutils` is installed beforehand, especially on macOS where it can be installed via Homebrew.

```bash
# 请确保安装 coreutils，OSX 可以使用 brew 安装
yarn bootstrap
```

--------------------------------

### Run Local Zent Documentation Website

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/CONTRIBUTING_zh-CN.md

This command starts the local development server for the Zent documentation website. It enables developers to preview changes to components and their documentation in real-time, adhering to the principle that 'documentation is code'.

```bash
yarn dev
```

--------------------------------

### Start Development Server for Component Testing

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/CONTRIBUTING_en-US.md

Launches the development server, which is useful for manually testing and verifying changes made to components. This command allows developers to observe the impact of their code modifications in a live environment.

```bash
yarn dev
```

--------------------------------

### Generate New Zent Component Boilerplate

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/CONTRIBUTING_zh-CN.md

This command automates the initial setup for a new component within the `packages/zent` directory. Running this script creates the necessary folder structure and boilerplate files, streamlining the component creation process. Replace `YOUR-COMPONENT-NAME` with the desired name for your new component.

```bash
yarn new-component YOUR-COMPONENT-NAME
```

--------------------------------

### Example Demo Component Styling with CSS/LESS

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/MARKDOWN_en-US.md

Provides an example of embedding styles directly within a demo using a `<style>` block. It shows basic CSS/LESS syntax with nested rules for component-specific styling, typically used for minor adjustments.

```CSS
.zent-badge {
  .nested {
    background: red;
  }
}
```

--------------------------------

### Configure babel-plugin-zent in .babelrc

Source: https://github.com/youzan/zent/blob/master/packages/babel-plugin-zent/README_en-US.md

Example configuration for babel-plugin-zent in a .babelrc file, demonstrating how to enable the plugin in your Babel setup.

```javascript
{
	"plugins": [
		["zent"]
	]
}
```

--------------------------------

### Nested CSS Styling Example (PreCSS Syntax)

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/MARKDOWN_zh-CN.md

Illustrates how to define component-specific styles using a nested CSS syntax, often referred to as 'precss'. This example shows styling for a `.zent-badge` class with a nested `.nested` element, demonstrating a common pattern for organizing component styles.

```css
// precss 语法
<style>
  .zent-badge {
    .nested {
      background: red;
    }
  }
<style>
```

--------------------------------

### Menu Component Hierarchical Structure Example

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/menu/README_en-US.md

An example demonstrating the nested structure of Menu, SubMenu, and MenuItem components, illustrating how internal keys are assigned based on hierarchy or explicit `key` properties.

```html
	<Menu>
		<MenuItem>   -------- 'item_0'
		<SubMenu>
			<MenuItem> -------- 'item_1_0'
			<MenuItem> -------- 'item_1_1'
		</SubMenu>
		<MenuItem>   -------- 'item_2'
	</Menu>
```

--------------------------------

### Install Zent UI Library

Source: https://github.com/youzan/zent/blob/master/README-zh_CN.md

This snippet provides commands to install the Zent UI component library using either Yarn or npm package managers. It adds Zent as a dependency to your project, making its components available for use.

```Shell
yarn add zent

# or

npm install zent --save
```

--------------------------------

### Style Zent Prompt Examples

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/prompt/demos/1.baisc.md

This CSS code provides basic styling for the container holding the Zent prompt examples and for the text links within the prompts. It adds vertical spacing between prompt instances and horizontal margins for the links to improve readability and layout.

```css
.zent-prompt-example > div {
	margin-bottom: 16px;
}
.zent-prompt-demo-text {
	margin-left: 8px;
	margin-right: 10px;
}
```

--------------------------------

### Zent Form Value Subscription and Dynamic Field Management Example

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/form/demos/20.reactive-value.md

This complete JSX example demonstrates building a dynamic form using Zent. It covers: 
1. **Form Initialization**: Using `useForm` to create the form instance and render basic input fields (`App` component).
2. **Dynamic Field Arrays**: Managing a list of dynamic inputs (e.g., hobbies) with `useFieldArray`, allowing additions and removals (`FieldArray` component).
3. **Real-time Value Subscription**: Subscribing to and displaying the entire form's current value using `useFormValue` for live preview or debugging (`Preview` component).
This example highlights the integration of these core Zent form functionalities.

```jsx
import {
	Form,
	FormError,
	FormStrategy,
	FormControl,
	Input,
	Validators,
	FieldSet,
	FormInputField,
	Button,
	Notify,
	Icon,
} from 'zent';

const { useState, useEffect, useCallback } = React;
const { useForm, useFieldArray, useFormValue } = Form;

function App() {
	const form = useForm(FormStrategy.View);

	return (
		<Form form={form} layout="vertical">
			<FormInputField required name="name" label="{i18n.name}" />
			<FormInputField name="address" label="{i18n.address}" />
			<FieldSet name="stature">
				<FormInputField name="weight" label="{i18n.weight}" />
				<FormInputField name="height" label="{i18n.height}" />
			</FieldSet>
			<FieldArray />
			<Preview form={form} />
		</Form>
	);
}

function FieldArray() {
	const model = useFieldArray('hobbies', [], ['{i18n.reading}']);
	model.destroyOnUnmount = true;

	return (
		<FormControl label="{i18n.hobbies}">
			{model.children.map((child, index) => {
				return (
					<div key={child.id}>
						<FormInputField
							withoutLabel
							model={child}
							props={{
								addonAfter: (
									<Icon
										type="close"
										style={{ cursor: 'pointer' }}
										onClick={() => model.splice(index, 1)}
									/>
								),
							}}
						/>
					</div>
				);
			})}
			<Button type="primary" onClick={() => model.push('')}>
				{i18n.add}
			</Button>
		</FormControl>
	);
}

function Preview({ form }) {
	// You will see a warning about performance issues in console.
	// Only do this if you know what you are doing.
	const value = useFormValue(form);

	return (
		<>
			<div>Form Value</div>
			<pre>{JSON.stringify(value, null, 2)}</pre>
		</>
	);
}

ReactDOM.render(<App />, mountNode);
```

--------------------------------

### Main Application Component for Form Rendering and Submission

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/form/demos/9.model-first.md

The 'App' component serves as the main entry point for the form. It initializes the form using 'Form.useForm' with the defined schema, renders the form fields, and provides functions to get the current form values, get submit values, and dynamically patch form values.

```jsx
function App() {
	const form = Form.useForm(formBuilder);
	const { number, members } = form.model.children;
	const setArray = useCallback(() => {
		form.patchValue({
			number: 42,
			members: [
				{
					name: 'john',
					sex: '1',
					hobbies: ['H1'],
				},
			],
		});
	}, [form]);

	const getFormValue = useCallback(() => {
		console.log(form.getValue());
	}, [form]);

	const getSubmitValue = useCallback(() => {
		console.log(form.getSubmitValue());
	}, [form]);

	return (
		<Form className="demo-form" layout="horizontal" form={form}>
			<FormNumberInputField
				model={number}
				label="{i18n.totalNumber}："
				required
			/>
			<Members model={members} />
			<div style={{ marginTop: 16 }}>
				<Button type="primary" htmlType="submit" onClick={getFormValue}>
					{i18n.submit}
				</Button>
				<Button type="primary" htmlType="submit" onClick={getSubmitValue}>
					{i18n.submitValue}
				</Button>
				<Button onClick={setArray}>{i18n.setArray}</Button>
			</div>
		</Form>
	);
}
```

--------------------------------

### Install Zent UI Library

Source: https://github.com/youzan/zent/blob/master/README.md

Commands to add the Zent UI component library to your project using either Yarn or npm package managers. This step is necessary to include Zent as a dependency in your application.

```shell
yarn add zent

# or

npm install zent --save
```

--------------------------------

### Example Demo Configuration YAML

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/MARKDOWN_en-US.md

Illustrates the YAML configuration block used for defining demo metadata, including `order` for display sequence and internationalized titles and content for different locales (e.g., Chinese and English). This configuration is automatically processed by the documentation loader.

```YAML
order: 1                          // `order` defines the order in the final documentation, smaller first
zh-CN:                            // Start of Chinese string definitions
  title: 基础用法                  // Required, demo title
  content: 公告内容                // `content` will be replace as `公告内容` in Chinese documentaion
en-US:                            // Start of English string definitions
  title: Basic                    // Required, demo title
  content: Alert content          // `content` will be replace as `Alert content` in English documentaion
```

--------------------------------

### CopyButton for edit-o Icon (Zent)

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/icon/demos/all.md

An example of the `CopyButton` component displaying the 'edit-o' (outline) icon. This snippet shows the setup for copying an icon's name to the clipboard.

```jsx
<CopyButton
  text={this.getIconString("edit-o")}
  onCopySuccess="edit 已复制到剪贴板"
>
  <div
    className="zi-grid-item"
    data-index="editeditoutline"
  >
    <Icon type="edit-o" />
    <span className="zi-grid-item-name">edit</span>
  </div>
</CopyButton>
```

--------------------------------

### CopyButton for upload Icon (Zent)

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/icon/demos/all.md

An example of the `CopyButton` component displaying the 'upload' icon. This snippet shows the standard setup for copying an icon's name and providing user feedback.

```jsx
<CopyButton
  text={this.getIconString("upload")}
  onCopySuccess="upload 已复制到剪贴板"
>
  <div
    className="zi-grid-item"
    data-index="uploadupload"
  >
    <Icon type="upload" />
    <span className="zi-grid-item-name">upload</span>
  </div>
</CopyButton>
```

--------------------------------

### CopyButton for save-o Icon (Zent)

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/icon/demos/all.md

An example of the `CopyButton` component displaying the 'save-o' (outline) icon. This snippet shows the standard setup for copying an icon's name and providing user feedback.

```jsx
<CopyButton
  text={this.getIconString("save-o")}
  onCopySuccess="save 已复制到剪贴板"
>
  <div
    className="zi-grid-item"
    data-index="savesaveoutline"
  >
    <Icon type="save-o" />
    <span className="zi-grid-item-name">save</span>
  </div>
</CopyButton>
```

--------------------------------

### Opening and Closing Dialogs with Zent's openDialog

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/dialog/demos/open.md

This JavaScript example illustrates two methods for managing dialogs using the `zent` library. The first method shows how to close a dialog by passing its unique `dialogId` to the `closeDialog` function. The second method demonstrates closing a dialog using the `close` function returned directly when `openDialog` is called, providing a more direct control mechanism.

```js
import { Dialog, Button } from 'zent';

const { openDialog, closeDialog } = Dialog;
const id = 'my_dialog';

// 使用 `closeDialog` 关闭需要传入 `dialogId`
const open = () => {
	openDialog({
		dialogId: id, // id is used to close the dialog
		title: '{i18n.title1}',
		children: <div>Hello World</div>,
		footer: (
			<>
				<Button onClick={() => closeDialog(id)}>{i18n.close}</Button>
				<Button type="primary" onClick={() => closeDialog(id)}>
					{i18n.ok}
				</Button>
			</>
		),
		onClose() {
			console.log('outer dialog closed');
		},
	});
};

// 使用 `openDialog` 返回的 `close` 函数关闭
let close;
const open2 = () => {
	close = openDialog({
		title: '{i18n.title1}',
		children: <div>Hello World</div>,
		footer: (
			<>
				<Button onClick={() => close()}>{i18n.close}</Button>
				<Button type="primary" onClick={() => close()}>
					{i18n.ok}
				</Button>
			</>
		),
		onClose() {
			console.log('outer dialog closed');
		},
	});
};

ReactDOM.render(
	<>
		<Button type="primary" onClick={open}>
			{i18n.open}
		</Button>
		<Button type="primary" onClick={open2}>
			{i18n.open}2
		</Button>
	</>,
	mountNode
);
```

--------------------------------

### Loading Component API Reference

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/loading/README_zh-CN.md

Detailed API documentation for the Loading component, including common parameters shared across all types (BlockLoading, InlineLoading, FullScreenLoading) and specific parameters for each type.

```APIDOC
Loading Component API:
  Description: The Loading component has 3 types: BlockLoading, InlineLoading, and FullScreenLoading. All types share most parameters, but each may have unique ones.

  Common Parameters:
    loading: boolean (optional, default: false)
      Description: Controls display.
    delay: number (optional, default: 0)
      Description: Display delay time (milliseconds).
    icon: string (optional, default: 'circle', options: 'youzan')
      Description: Icon style.
    iconSize: number (optional)
      Description: Icon size.
    iconText: string (optional)
      Description: Icon text.
    colorPreset: string (optional, default: 'primary', options: 'grey')
      Description: Preset theme color.
    textPosition: string (optional, default: 'bottom', options: 'top' | 'left' | 'right')
      Description: Text position relative to icon.
    textSize: number (optional)
      Description: Text font size.
    className: string (optional)
      Description: Custom extra class name.

  BlockLoading Component:
    Description: Block-level Loading, can wrap content or be given a height. Commonly used for page section loading.
    (Inherits Common Parameters)
    Specific Parameters:
      height: number (default: 160)
        Description: If wraps component, defaults to component height; otherwise uses default height.
      children: ReactNode (optional)
        Description: Wrapped content.

  InlineLoading Component:
    Description: Inline Loading, cannot wrap content, displays inline.
    (Inherits Common Parameters)
    (No specific parameters listed)

  FullScreenLoading Component:
    Description: Full-screen Loading, cannot wrap content, displays full screen. Used for page-level loading.
    (Inherits Common Parameters)
    Specific Parameters:
      zIndex: number (optional)
        Description: Overlay z-index.
      showBackground: bool (optional)
        Description: Whether to show Loading bottom background color.
```

--------------------------------

### Get theme color in RGB format with theme-rgb SCSS function

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/Theme-Coding_en-US.md

The `theme-rgb` function returns a CSS variable in RGB format for a specified color category and index. This function is useful in scenarios where the standard mixins like `theme-color` do not provide the necessary flexibility for theming.

```SCSS
.container {
	box-shadow: 0 1px 0 0 $theme-stroke-6;
	box-shadow: 0 1px 0 0 theme-rgb(stroke, 6);
}
```

--------------------------------

### Get theme color in RGBA format with theme-rgba SCSS function

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/Theme-Coding_en-US.md

The `theme-rgba` function is similar to `theme-rgb` but includes an additional `$opacity` parameter, returning a CSS variable in RGBA format. It's designed for applying themed colors with transparency, offering more control over visual effects.

```SCSS
.container {
	box-shadow: 0 1px 0 0 rgba($theme-stroke-6, 0.8);
	box-shadow: 0 1px 0 0 theme-rgba(stroke, 6, 0.8);
}
```

--------------------------------

### React Component Demonstrating BlockLoading with Switch

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/loading/demos/wrapper-mode.md

This React component, `Wrapper`, showcases the usage of `BlockLoading` and `Switch` components from the `zent` library. It manages a `loading` state which, when true, activates the `BlockLoading` component around a 'Hello World' div, visually indicating a loading state. The `Switch` component allows users to toggle this loading state on and off, demonstrating dynamic control over the loading overlay.

```js
import { BlockLoading, Switch } from 'zent';

class Wrapper extends React.Component {
	state = { loading: false };

	onChange = value => {
		this.setState({ loading: value });
	};

	render() {
		const { loading } = this.state;

		return (
			<div>
				<BlockLoading loading={loading}>
					<div className="zent-loading-example-hello-world">Hello World</div>
				</BlockLoading>
				<Switch
					className="zent-loading-example-switch"
					checked={loading}
					onChange={this.onChange}
					size="small"
				/>
			</div>
		);
	}
}

ReactDOM.render(<Wrapper />, mountNode);
```

--------------------------------

### Loading Component API Reference

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/loading/README_en-US.md

Detailed API documentation for the `Loading` component and its variants (`BlockLoading`, `InlineLoading`, `FullScreenLoading`), including common and specific properties.

```APIDOC
Loading Component:
  Description: Shows the loading state of data without a specific duration. Has 3 different types: BlockLoading, InlineLoading and FullScreenLoading.
  Common Props:
    loading:
      Description: Loading state
      Type: boolean
      Required: No
      Default: false
      Alternative: true
    delay:
      Description: Milliseconds to delay before loading
      Type: number
      Required: No
      Default: 0
    icon:
      Description: Icon type
      Type: string
      Required: No
      Default: 'circle'
      Alternative: 'youzan'
    iconSize:
      Description: Icon size
      Type: number
      Required: No
      Default: None
    iconText:
      Description: Icon text
      Type: string
      Required: No
      Default: None
    colorPreset:
      Description: Color preset
      Type: string
      Required: No
      Default: 'primary'
      Alternative: 'grey'
    textPosition:
      Description: Text position relative to icon
      Type: string
      Required: No
      Default: 'bottom'
      Alternative: 'top' | 'left' | 'right'
    textSize:
      Description: Text Font Size
      Type: number
      Required: No
      Default: None
    className:
      Description: Custom class
      Type: string
      Required: No
      Default: None

BlockLoading Component:
  Description: Block level Loading, content can be wrapped or a default height will be used. Used for loading a page section.
  Props:
    height:
      Description: Uses content height if wrapping content, or uses a default height
      Type: number
      Required: No
      Default: 160
    children:
      Description: Wrapped content
      Type: ReactNode
      Required: No
      Default: None

InlineLoading Component:
  Description: Inline Loading, can't wrap content.
  Props: None

LoadingFullScreen Component:
  Description: Full screen Loading, can't wrap content. Used for page loading.
  Props:
    zIndex:
      Description: Mask z-index
      Type: number
      Required: No
      Default: None
    showBackground:
      Description: Show loading Background
      Type: bool
      Required: No
      Default: None
```

--------------------------------

### YAML Configuration for Component Demo Metadata

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/MARKDOWN_zh-CN.md

Defines the metadata for a component demonstration, including `order` for sequence, and internationalized `title` and `content` for both Chinese (zh-CN) and English (en-US) versions. This configuration is crucial for the documentation loader to correctly insert and display examples.

```yaml
---
order: 1
zh-CN:
  title: 基础用法
  content: 公告内容
en-US:
  title: Basic
  content: Alert content
---
```

--------------------------------

### Disable Dates in Zent DatePicker Components

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/date-picker/demos/disabled-date.md

This React component demonstrates how to use the `disabledDate` prop across different Zent date picker components. It shows examples of disabling dates based on a day of the week (Monday), a minimum date, and custom logic for date ranges (e.g., disabling the 15th for start date). The `disabledDate` prop accepts either a function or an object with `min` and `max` properties.

```jsx
import { DatePicker, WeekPicker, CombinedDateRangePicker } from 'zent';

class Demo extends Component {
	state = {};
	onChangeDate = val => {
		this.setState({
			dateValue: val,
		});
	};
	onChangeDate2 = val => {
		console.log('onChangeDate2', val);
		this.setState({
			dateValue2: val,
		});
	};
	onChangeRange = val => {
		this.setState({
			rangeValue: val,
		});
	};
	onChangeCombinedDate = val => {
		this.setState({
			combinedValue: val,
		});
	};
	onDisabledRange = (val, type) =>
		type === 'start' ? val.getDate() === 15 : false;
	onDisabledCombinedDate = val => val.getDate() < 9;
	render() {
		const { dateValue, dateValue2, rangeValue, combinedValue } = this.state;
		return (
			<div>
				<DatePicker
					value={dateValue}
					className="zent-datepicker-demo"
					onChange={this.onChangeDate}
					disabledDate={date => date.getDay() === 1}
				/>
				<br />
				<DatePicker
					value={dateValue2}
					className="zent-datepicker-demo"
					onChange={this.onChangeDate2}
					disabledDate={{ min: '2020-6-15' }}
				/>
				<br />
				<DateRangePicker
					className="zent-datepicker-demo"
					value={rangeValue}
					onChange={this.onChangeRange}
					disabledDate={this.onDisabledRange}
				/>
				<br />
				<CombinedDateRangePicker
					className="zent-datepicker-demo"
					value={combinedValue}
					onChange={this.onChangeCombinedDate}
					disabledDate={this.onDisabledCombinedDate}
				/>
			</div>
		);
	}
}
ReactDOM.render(<Demo />, mountNode);
```

--------------------------------

### Disable Specific Hours for Start Date in DateRangePicker

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/date-picker/demos/disabled-time.md

Shows how to conditionally disable specific hours (e.g., 3, 4, 5 AM) only for the 'start' date in a Zent DateRangePicker or CombinedTimeRangePicker. The `disabledTime` function receives both the date and the type ('start' or 'end'), allowing different rules to be applied based on the selected range boundary.

```jsx
import { DateRangePicker, CombinedTimeRangePicker } from 'zent';
import { isSameDay } from 'date-fns';

// Inside a React component class
disabledTime3 = (date, type) => {
    return type === 'start'
        ? {
                disabledHours: () => [3, 4, 5],
                disabledMinutes: () => [],
                disabledSeconds: () => []
          }
        : {};
};

// In render method
<DateRangePicker
    className="zent-datepicker-demo"
    showTime={{ format: 'HH:mm', defaultTime: [
            date => (isSameDay(date, new Date()) ? '12:30' : '00:00'),
            '23:59'
        ] }}
    format="YYYY-MM-DD HH:mm"
    value={rangeValue}
    onChange={this.onChangeRange}
    disabledTime={this.disabledTime3}
/>

<CombinedTimeRangePicker
    className="zent-datepicker-demo"
    value={combinedTimeValue}
    onChange={this.onChangeCombinedTime}
    disabledTime={this.disabledTime3}
/>
```

--------------------------------

### Run Single Zent Component Unit Tests

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/CONTRIBUTING_zh-CN.md

This command allows developers to execute unit tests for a specific component. Provide the directory name or file name of the component's test suite, located under `__tests__`, as an argument to run its associated tests.

```bash
yarn test-component button
```

--------------------------------

### previewImage Component API Reference

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/preview-image/README_zh-CN.md

API documentation for the previewImage component, detailing available properties, their types, default values, and descriptions.

```APIDOC
previewImage Component Properties:
  images: array
    description: 待预览图片 url
  index: number
    description: 显示第几张，从 0 开始
    default: 0
  showRotateBtn: bool
    description: 是否显示翻转按钮
    default: true
    values: true,false
  scaleRatio: number
    description: 自定义缩放比例
    default: 1.5
  parentComponent: ReactInstance
    description: 父级组件实例，i18n 需要通过这个传递 context
  className: string
    description: 可选，自定义类名
    default: ''
```

--------------------------------

### Generate New Zent Component Boilerplate

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/CONTRIBUTING_en-US.md

Automates the creation of a new component's basic file structure, including JavaScript, styles, tests, and documentation templates. Replace `YOUR-COMPONENT-NAME` with the desired component name to generate the necessary boilerplate.

```bash
yarn new-component YOUR-COMPONENT-NAME
```

--------------------------------

### Style Zent ScrollAlert Example Container

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/alert/demos/scroll.md

This CSS snippet provides basic styling for the example container. It targets the `zent-alert-scroll` class within `zent-alert-example` to apply a bottom margin, ensuring proper spacing between multiple `ScrollAlert` instances.

```css
.zent-alert-example .zent-alert-scroll {
	margin-bottom: 16px;
}
```

--------------------------------

### Style Zent StatusBar Example Container

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/status-bar/demos/1.basic.md

Provides CSS styling for the example container of the Zent StatusBar. It defines margins for `zent-alert` elements and adjusts horizontal margins for links within the alert component to ensure proper spacing.

```css
.zent-status-bar-example .zent-alert {
	margin-bottom: 24px;
}
.zent-status-bar-example .zent-alert a {
	margin: 0 10px 0 8px;
}
```

--------------------------------

### previewImage Component API Reference

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/preview-image/README_en-US.md

Detailed API documentation for the previewImage component, outlining its configurable properties, their types, default values, and descriptions for effective usage.

```APIDOC
previewImage Component API:
  Properties:
    - name: images
      description: Urls for images
      type: array
      default: ""
      alternatives: ""
    - name: index
      description: Start index
      type: number
      default: "0"
      alternatives: ""
    - name: showRotateBtn
      description: Show rotate button
      type: bool
      default: "true"
      alternatives: "true,false"
    - name: scaleRatio
      description: Custom scale Ratio
      type: number
      default: "1.5"
      alternatives: ""
    - name: parentComponent
      description: Parent component instance，i18n needs this to pass context through
      type: ReactInstance
      default: ""
      alternatives: ""
    - name: className
      description: Optional. Custom class name
      type: string
      default: "''"
      alternatives: ""
```

--------------------------------

### Example Demo Component Rendering with JSX

Source: https://github.com/youzan/zent/blob/master/packages/zent/docs/MARKDOWN_en-US.md

Demonstrates how to render a Zent component (`Alert`) using `ReactDOM.render` within a demo. It shows the use of `i18n.content` for internationalized text placeholders and `mountNode` as the predefined rendering target for the component.

```JSX
import { Alert } from 'zent';
ReactDOM.render(                  // ReactDOM.render is the entry point
  <Alert>{i18n.content}</Alert>   // The component you want to render
  , mountNode                     // `mountNode` is predefined
);
```

--------------------------------

### Basic Usage of Zent Pagination Components

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/pagination/demos/01-basic.md

This example demonstrates the fundamental usage of Zent's Pagination, LitePagination, and MiniPagination components. It sets up a React component with state for current page and page size, and an onChange handler to update the state. The render method showcases how to integrate these pagination components with different configurations, including a bordered and a non-bordered Pagination, LitePagination, and MiniPagination.

```jsx
import { Pagination, MiniPagination, LitePagination } from 'zent';

class Test extends Component {
	state = {
		pageSize: 10,
		current: 1,
	};

	onChange = options => {
		console.log(options);
		this.setState(options);
	};

	render() {
		const { current, pageSize } = this.state;

		return (
			<div>
				<Pagination
					current={current}
					pageSize={pageSize}
					total={101}
					onChange={this.onChange}
				/>

				<br />

				<Pagination
					current={current}
					pageSize={pageSize}
					total={101}
					onChange={this.onChange}
					buttonBordered={false}
				/>

				<br />

				<LitePagination
					current={current}
					pageSize={pageSize}
					total={101}
					onChange={this.onChange}
				/>

				<br />

				<MiniPagination
					current={current}
					pageSize={pageSize}
					total={101}
					onChange={this.onChange}
				/>
			</div>
		);
	}
}

ReactDOM.render(<Test />, mountNode);
```

--------------------------------

### Example: Custom Popover Position Function

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/popover/README_zh-CN.md

A TypeScript example demonstrating how to define a custom positioning function for the Popover component. This function calculates the 'TopCenter' position based on the content, relative element rectangles, and a cushion offset, returning style and class name.

```TypeScript
const TopCenter: IPositionFunction = (options) => {
	const { contentRect, relativeRect, cushion } = options;
  const { right, left, top } = relativeRect;
  const middle = (left + right) / 2;
  const x = middle - contentRect.width / 2;
  const y = top - contentRect.height - cushion;

  return {
    style: {
      position: 'absolute',
      left: x,
      top: y,
    },

    className: prefix('position-top-center'),
  };
};
```

--------------------------------

### Preview Images using zent's previewImage Function

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/preview-image/demos/basic.md

This snippet illustrates how to integrate and use the `previewImage` function from the `zent` library within a React component. It initializes an array of image URLs and renders them as clickable thumbnails. Upon clicking an image, the `handlePreview` method is invoked, which calls `previewImage` to open a modal displaying the clicked image within a gallery, allowing navigation through all defined images. Configuration options like `scaleRatio` are also demonstrated.

```javascript
import { previewImage } from 'zent';

const imgArr = [
	'http://img.yzcdn.cn/public_files/2017/6/30/b0717bad7ad3ebd025e175d624ade39f.png',
	'http://img.yzcdn.cn/public_files/2017/6/30/8a0536db89fafaa1269afeaa807a579b.png',
	'http://img.yzcdn.cn/public_files/2017/6/30/7fe46674b697a514d9b6e2e155e88f1c.png',
	'http://img.yzcdn.cn/public_files/2017/6/30/b7a98d721698fe8dc93689683706db45.png'
];

class Simple extends React.Component {
	handlePreview = (e) => {
		previewImage({
			images: imgArr,
			index: imgArr.indexOf(e.target.src),
			parentComponent: this,
			scaleRatio: 3
		});
	}

	render() {
		return (
			<div className="image-preview-demo">
				{
					imgArr.map((image, index) => {
						return (<img src={image} key={index} onClick={this.handlePreview} alt="" width="160" />);
					})
				}
			</div>
		)
	}
}

ReactDOM.render(
	<Simple />
	, mountNode
);
```

--------------------------------

### Pop Component API Reference

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/pop/README_zh-CN.md

Comprehensive API documentation for the Zent Pop component, detailing its properties, methods, and behavior based on different trigger types. Includes parameters for general Pop usage, specific parameters for 'click' and 'hover' triggers, methods exposed by the `withPop` Higher-Order Component, and important behavioral notes.

```APIDOC
Pop Component Properties:
  content: node (required) - Content of the overlay.
  trigger: string (optional, default: 'none') - Trigger method. Options: 'click', 'hover', 'focus'.
  position: string | func (optional, default: 'top-center') - Position of the popover. Accepts function (Popover.Position.create).
  centerArrow: bool (optional, default: false) - Whether to center the small arrow with the trigger.
  cushion: number (optional, default: 10) - Offset distance between popover edge and trigger element.
  header: node (optional) - Custom header for the popover.
  block: bool (optional, default: false) - Whether the overlay appears as a block-level element in the document flow.
  onShow: func (optional, default: noop) - Callback after overlay opens.
  onClose: func (optional, default: noop) - Callback after overlay closes.
  onBeforeShow: func (optional, default: noop) - Callback before overlay opens (only for user-triggered open).
  onBeforeClose: func (optional, default: noop) - Callback before overlay closes (only for user-triggered close).
  onConfirm: func (optional) - Custom callback for confirm behavior (makes Pop act as confirm dialog).
  onCancel: func (optional) - Custom callback for cancel behavior when using confirm.
  confirmText: string (optional, default: '确定') - Custom text for confirm button.
  cancelText: string (optional, default: '取消') - Custom text for cancel button.
  type: string (optional, default: 'primary') - Affects confirm button style. Options: 'primary', 'default'.
  visible: bool (optional) - External control for Pop display state. Must be used with onVisibleChange.
  onVisibleChange: func (optional) - Used with visible.
  onPositionUpdated: func (optional, default: noop) - Callback when position is updated (position may not have changed).
  onPositionReady: func (optional, default: noop) - Callback when position enters window (called once per lifecycle).
  containerSelector: string (optional, default: 'body') - CSS selector for the parent node of the overlay. Options: Any valid CSS selector.
  className: string (optional) - Custom class name for the overlay.
  style: CSSProperties (optional) - Custom style for the overlay.

Trigger-specific Parameters:
  Click Trigger:
    closeOnClickOutside: bool (optional, default: true) - Automatically close when clicking outside the overlay and trigger node.
  Hover Trigger:
    mouseEnterDelay: number (optional, default: 200) - Delay for hover open (milliseconds).
    mouseLeaveDelay: number (optional, default: 200) - Delay for closing (milliseconds).
    anchorOnly: boolean (optional, default: false) - Only consider Trigger as the activation area.
    fixMouseEventsOnDisabledChildren: boolean (optional, default: false) - Compatibility handling for disabled child mouse events.
      Note: Only effective for Zent components.
      Background: Native input/button disabled state prevents mouse events (issue #142).
      Solution: Wrap input/button in another element, then apply `{pointer-events: none}` to input/button.
  None Trigger:
    Note: onConfirm and onCancel do not automatically close Pop. User must control 'visible' in callbacks.

withPop Higher-Order Component:
  Exposed Methods:
    open: func - Opens the Pop.
    close: func - Closes the Pop.

Methods:
  adjustPosition(): Manually adjusts Pop position.
  getWrappedPopover(): Gets the internal Popover instance.

Behavioral Notes:
  Content Area Positioning Issues:
    Problem: Positioning errors when content area text is very long.
    Reason: Component measures overlay width on body, which differs from actual rendered width due to wrapping behavior and screen edge position.
    Solution: Provide a width to the 'content' prop.
  centerArrow:
    Default: Pop aligns edges of overlay and trigger based on 'position'. For '*-center' positions, arrow spacing to overlay edge is fixed. If trigger is small, arrow may align outside trigger.
    With centerArrow=true: Arrow always aligns to the center of the trigger, and the overlay positions relative to the arrow, regardless of trigger size.
  onConfirm and onCancel:
    Supports asynchronous responses; button will show loading state.
    If Promise is returned: Pop closes after Promise resolves.
    Supports parameter-based async response: Accepts a 'close' parameter; user must manually call 'close' within the function.
```

--------------------------------

### CSS Styling for Zent Tooltip Examples

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/tooltip/demos/trigger.md

This CSS block provides styling for the container holding the Zent Tooltip examples. It uses flexbox for layout and includes specific styles for a custom tag element (`.zent-doc-tooltip-tag`) and adjusts margins for the input wrapper (`.zent-input-wrapper`) within the container.

```css
.zent-doc-tooltip-container {
		display: flex;
		justify-content: left;
		align-items: center;

		.zent-doc-tooltip-tag {
			border: 1px solid #e5e5e5;
			border-radius: 20%;
			padding: 3px;
			font-size: 12px;
			cursor: default;

			&:not(:last-child) {
				margin-right: 10px;
			}
		}

		.zent-input-wrapper {
			margin-left: 10px;
		}
	}
```

--------------------------------

### Babel Plugin Zent Import Transformation Example

Source: https://github.com/youzan/zent/blob/master/packages/zent/README_en-US.md

This example demonstrates the code transformation performed by `babel-plugin-zent`. It shows how a standard named import from the 'zent' library is automatically converted into a direct import from the component's specific ES module path, which helps in reducing bundle size through better tree-shaking.

```javascript
import { Button } from 'zent';

// Transforms into

import Button from 'zent/es/button';
```

--------------------------------

### Switch Component API Reference

Source: https://github.com/youzan/zent/blob/master/packages/zent/src/switch/README_zh-CN.md

API documentation for the Switch component, detailing available properties and their usage. This section lists parameters, their descriptions, types, default values, and possible options.

```APIDOC
Switch Component Properties:
  checked:
    description: Specifies the current state
    type: bool
    default: (none)
  onChange:
    description: Callback function when the state changes, parameter is the new `checked` value
    type: func(checked: bool)
    default: noop
  disabled:
    description: Controls the state
    type: bool
    default: false
    options: true
  size:
    description: Size of the switch
    type: string
    default: 'default'
    options: 'small'
  className:
    description: Custom additional class name
    type: string
    default: ''
  loading:
    description: Loading state
    type: bool
    default: false
    options: true
```
Tokens:
Raw