---
url: https://taroify.com/introduce/index.md
---

# 介绍

![logo](https://img.yzcdn.cn/vant/logo.png)

**轻量、可靠、面向多端的 Taro React UI 组件库
**

基于 Vant 设计语言，为小程序与 H5 提供一致、类型安全且高度可定制的开发体验。


[**官网
**](https://taroify.com/) · [**快速上手
**](https://taroify.com/quickstart/) · [**在线演示
**](https://taroify.com/h5/index.html) · [**CLI / MCP
**](https://taroify.com/cli/) · [**讨论区
**](https://github.com/taroify/taroify/discussions)


## Taroify 是什么

Taroify 是移动端组件库 [Vant](https://github.com/youzan/vant) 的 Taro React 版本，两者基于相同的视觉规范，提供近似一致的 API 接口，助力开发者快速搭建小程序应用。

## ✨ 特性

- 🚀 性能极佳，组件平均体积小于 1KB（min+gzip）
- 💎 70+ 个高质量组件，覆盖移动端主流场景
- 💪 使用 TypeScript 编写，提供完整的类型定义
- 💪 单元测试覆盖率超过 90%，提供稳定性保障
- 📖 提供完善的中文文档和组件示例
- 🍭 支持 React
- 🍭 支持主题定制，内置 700+ 个主题变量
- 🍭 支持按需引入和 Tree Shaking

## 浏览器支持

支持现代浏览器以及 Chrome >= 51、iOS >= 10.0。

## 安装

在现有项目中使用 Taroify 时，可以通过 `npm` 进行安装

## 快速开始

### 安装


```sh [npm]
npm install @taroify/core
```

```sh [yarn]
yarn add @taroify/core
```

```sh [pnpm]
pnpm add @taroify/core
```

### 使用组件

```tsx
import { Button } from "@taroify/core"
import "@taroify/core/button/style"

export default function Index() {
  return <Button color="primary">开始使用 Taroify</Button>
}
```

推荐配置自动按需引入，以获得更简洁的源码和更小的构建产物。完整配置请查看
[快速上手](https://taroify.com/quickstart/)。

## Packages

Taroify 采用 Monorepo 组织，各能力可以独立安装和组合：

| Package                                                                | 说明                           |
| :--------------------------------------------------------------------- | :--------------------------- |
| [`@taroify/core`](https://www.npmjs.com/package/@taroify/core)         | 核心 UI 组件与主题系统                |
| [`@taroify/icons`](https://www.npmjs.com/package/@taroify/icons)       | Taro React 图标组件              |
| [`@taroify/hooks`](https://www.npmjs.com/package/@taroify/hooks)       | 面向组件与业务场景的 React Hooks       |
| [`@taroify/commerce`](https://www.npmjs.com/package/@taroify/commerce) | 电商场景扩展组件                     |
| [`@taroify/cli`](https://www.npmjs.com/package/@taroify/cli)           | 离线组件知识 CLI、MCP 与 Agent Skill |
| [`@taroify/mcp`](https://www.npmjs.com/package/@taroify/mcp)           | 现有独立 MCP 服务                  |

## 本地开发

```bash
# 克隆仓库
git clone https://github.com/taroify/taroify.git
cd taroify

# 安装根目录、工作区和官网依赖
pnpm run install:node_modules

# 启动 H5 组件示例与文档站点
pnpm develop
```

更多仓库结构、组件开发与提交规范，请阅读
[贡献指南](https://taroify.com/contribution/)。

## 社区

如果你发现问题、希望增加组件，或对 API 设计有建议，欢迎通过以下方式参与：

- [提交 Issue](https://github.com/mataroifyllfoundry/taroify/issues)
- [发起 Pull Request](https://github.com/taroify/taroify/pulls)
- [参与 Discussions](https://github.com/taroify/taroify/discussions)
- [查看更新日志](https://taroify.com/changelog/)


**加入微信交流群
**

![Taroify 微信交流群](/introduce/wechat-qrcode.jpg)

添加好友时请备注「taroify」，通过后邀请进群。



## 贡献者

感谢每一位为 Taroify 提交代码、文档、设计、Issue 与建议的贡献者。

[![contributors](https://contrib.rocks/image?repo=taroify/taroify)](https://github.com/taroify/taroify/graphs/contributors)
部分图形设计来自 [@BiscuitCoder](https://uyyu.xyz/)。

## 生态与致谢

Taroify 的设计规范与大量组件经验来自 Vant。感谢
[Vant 团队](https://github.com/youzan/vant) 多年来对移动端组件生态的持续投入，也感谢
[JetBrains](https://www.jetbrains.com/) 为开源项目提供开发工具支持。


**Vant 官方生态
**

| 项目                                                                                          | 描述           |
| :------------------------------------------------------------------------------------------ | :----------- |
| [Vant](https://github.com/youzan/vant)                                                      | Vant Vue 版   |
| [Vant Weapp](https://github.com/youzan/vant-weapp)                                          | Vant 微信小程序版  |
| [Vant Demo](https://github.com/youzan/vant-demo)                                            | Vant 官方示例合集  |
| [Vant CLI](https://github.com/youzan/vant/tree/dev/packages/vant-cli)                       | 开箱即用的组件库搭建工具 |
| [Vant Icons](https://github.com/youzan/vant/tree/dev/packages/vant-icons)                   | Vant 图标库     |
| [Vant Touch Emulator](https://github.com/youzan/vant/tree/dev/packages/vant-touch-emulator) | 桌面端触摸事件模拟工具  |


**社区生态与友情推荐
**

| 项目                                                                   | 描述                       |
| :------------------------------------------------------------------- | :----------------------- |
| [React Vant](https://github.com/3lang3/react-vant)                   | 参照 Vant 打造的 React 移动端组件库 |
| [mockm](https://github.com/wll8/mockm)                               | 面向前端开发的接口模拟工具            |
| [taro-hooks](https://github.com/innocces/taro-hooks)                 | 为 Taro 设计的 Hooks Library |
| [tarojs-router-next](https://github.com/lblblong/tarojs-router-next) | 提供类型提示与参数能力的 Taro 路由库    |

### 支持者

感谢
[@Yorksh1re](https://github.com/Yorksh1re)、
[@akazwz](https://github.com/akazwz)、
[@Yang](https://github.com/programmer-yang)、
[@coderYarn](https://github.com/coderYarn)、
[@蔡包](https://github.com/shaolongcai)、
[@王昆](https://github.com/lifeneedspassion)
以及所有支持 Taroify 的开发者。

## License

[MIT](https://github.com/taroify/taroify/blob/main/LICENSE) © Taroify Contributors



---
url: https://taroify.com/quickstart/index.md
---

# 快速上手

### 介绍

通过本章节你可以了解到 Taroify 的安装方法和基本使用姿势。

### 安装


```sh [npm]
npm install @taroify/core
```

```sh [yarn]
yarn add @taroify/core
```

```sh [pnpm]
pnpm add @taroify/core
```

## 引入组件

### 方式一. 自动按需引入组件 (推荐)

[babel-plugin-import](https://github.com/ant-design/babel-plugin-import) 是一款 babel 插件，它会在编译过程中将 import 的写法自动转换为按需引入的方式。


```sh [npm]
npm install babel-plugin-import -D
```

```sh [yarn]
yarn add babel-plugin-import -D
```

```sh [pnpm]
pnpm add babel-plugin-import -D
```

加载Sass源文件，通过Taro转成CSS

```js title="babel.config.js" lineNumbers
module.exports = {
  plugins: [
    [
      "import",
      {
        libraryName: "@taroify/core",
        libraryDirectory: "",
        style: true,
      },
      "@taroify/core",
    ],
    [
      "import",
      {
        libraryName: "@taroify/icons",
        libraryDirectory: "",
        camel2DashComponentName: false,
        style: () => "@taroify/icons/style",
        customName: (name) => name === "Icon" ? "@taroify/icons/van/VanIcon" : `@taroify/icons/${name}`,
      },
      "@taroify/icons",
    ],
  ],
};
```

若不想加载Sass源文件或者其他情况，也可以加载编译后的CSS文件

```js title="babel.config.js" lineNumbers
module.exports = {
  plugins: [
    [
      "import",
      {
        libraryName: "@taroify/core",
        libraryDirectory: "",
        style: (name) => `${name}/index.css`,
      },
      "@taroify/core",
    ],
    [
      "import",
      {
        libraryName: "@taroify/icons",
        libraryDirectory: "",
        camel2DashComponentName: false,
        style: () => "@taroify/icons/index.css",
        customName: (name) => name === "Icon" ? "@taroify/icons/van/VanIcon" : `@taroify/icons/${name}`,
      },
      "@taroify/icons",
    ],
  ],
};
```

Vite 版本


```sh [npm]
npm install vite-plugin-style-import consola -D
```

```sh [yarn]
yarn add vite-plugin-style-import consola -D
```

```sh [pnpm]
pnpm add vite-plugin-style-import consola -D
```

```ts title="config/index.ts" lineNumbers
import { createStyleImportPlugin } from "vite-plugin-style-import";

export default defineConfig<"vite">(async (merge, { command, mode }) => {
  const baseConfig: UserConfigExport<"vite"> = {
    compiler: {
      type: "vite",
      vitePlugins: [
        createStyleImportPlugin({
          libs: [
            {
              libraryName: "@taroify/core",
              esModule: true,
              resolveStyle: (name: string) => `@taroify/core/${name}/style/index.js`,
              ensureStyleFile: true,
            },
            {
              libraryName: "@taroify/icons",
              esModule: true,
              resolveStyle: () => "@taroify/icons/style",
            },
          ],
        }),
      ],
    },
  }

  process.env.BROWSERSLIST_ENV = process.env.NODE_ENV;

  if (process.env.NODE_ENV === "development") {
    // 本地开发构建配置（不混淆压缩）
    return merge({}, baseConfig, devConfig);
  }
  // 生产构建配置（默认开启压缩混淆等）
  return merge({}, baseConfig, prodConfig);
})
```

接着你可以在代码中直接引入 Taroify 组件：

```tsx
// 插件会自动将代码转化为方式二中的按需引入形式
import { Button } from "@taroify/core"
```

### 方式二. 手动按需引入组件

在不使用插件的情况下，可以手动引入需要的组件。

```tsx
import "@taroify/core/button/style"
import { Button } from "@taroify/core"
// css
import "@taroify/core/button/index.css"
import { Button } from "@taroify/core"
```

###

在使用上面两种CSS方式引入时，若要使用[Style 内置样式](/components/style.md), 需要单独引入(版本 > 0.8.1 才产出次文件，之前未产出，低版本无法通过CSS方式引入)

```tsx
import "@taroify/core/styles/index.css"
```

### 方式三. 导入所有组件样式

Taroify 支持一次性导入所有组件，引入所有组件会增加代码包体积，因此不推荐这种做法。

```tsx title="app.ts"
import "@taroify/icons/index.scss"
import "@taroify/core/index.scss"
// css
import "@taroify/icons/index.css"
import "@taroify/core/index.css"
```

> Tips: 配置按需引入后，将不允许直接导入所有组件。

## 适配

### Rem 布局适配

Taroify 默认采用 `rem` 单位，需要对 `@taroify` 里的样式单位进行转换适配。

```js title="config/index.js" lineNumbers
const config = {
  h5: {
    esnextModules: ["@taroify"],
  }
}
```

### designWidth

Taroify designWidth 为 750。如果你的 `designWidth` 为 375，显示效果会放大两倍。由于 Taroify 内部样式已经改为 Sass Modules（`@use`），旧的 `sass.data: "$hd: 1;"` 写法已经不会生效，需要改为在构建时配置 `variables` 模块：

```js title="config/index.js" lineNumbers
module.exports = {
  // ...
  sass: {
    data: '@use "@taroify/core/styles/variables" as taroify_variables with ($hd: 1);'
  }
}
```

同时需要确保引入的是 scss 入口：

```tsx
import "@taroify/core/index.scss"
import "@taroify/icons/index.scss"
```

如果引入的是 `@taroify/core/index.css` 或 `@taroify/icons/index.css`，Sass 变量覆盖不会生效。



---
url: https://taroify.com/contribution/index.md
---

# 开发指南

### 介绍

感谢你使用 Taroify。

以下是关于向 Taroify 提交反馈或代码的指南。在向 Taroify 提交 issue 或者 PR 之前，请先花几分钟时间阅读以下文字。

### Issue 规范

- 遇到问题时，请先确认这个问题是否已经在 issue 中有记录或者已被修复
- 提 issue 时，请用简短的语言描述遇到的问题，并添加出现问题时的环境和复现步骤

## 参与开发

### 本地开发

按照下面的步骤操作，即可在本地开发 Taroify 组件。

```bash
# 全局安装 rimraf
npm install -g rimraf

# 克隆仓库
# 默认为 main 分支，包含 Taroify 的代码
git clone https://github.com/taroify/taroify.git

# 安装依赖
cd taroify && pnpm run install:node_modules

# 进入开发模式，浏览器访问 http://localhost:8000
pnpm run develop
```

### 目录结构

- 仓库的组件代码位于 packages/core 下，每个组件一个文件夹
- site 目录下是文档网站的代码，本地开发时可以运行 pnpm --dir site run site:develop 开启文档网站

项目主要目录如下：

```text
taroify
├─ bundles         # 构建
├─ packages/core   # 组件
├─ packages        # 子包
├─ site            # 文档
└─ scripts         # 脚本
```

### 添加新组件

添加新组件时，请按照下面的目录结构组织文件。

```text
src
└─ button
   ├─ __tests__        # 单元测试
   ├─ variables.scss   # 组件样式变量
   ├─ button.tsx       # 具名组件
   ├─ button.scss      # 组件样式
   ├─ index.ts         # 组件入口
   ├─ index.scss       # 组件样式入口
```

## 提交 PR

### Pull Request 规范

- 如果遇到问题，建议保持你的 PR 足够小。保证一个 PR 只解决一个问题或只添加一个功能
- 当新增组件或者修改原有组件时，记得增加或者修改测试代码，保证代码的稳定
- 在 PR 中请添加合适的描述，并关联相关的 Issue

### Pull Request 流程

1. fork 主仓库，如果已经 fork 过，请同步主仓库的最新代码
2. 基于 fork 后仓库的 main 分支新建一个分支，比如`feature/button-color`
3. 在新分支上进行开发，开发完成后，提 Pull Request 到主仓库的 dev 分支
4. Pull Request 会在 Review 通过后被合并到主仓库
5. 等待 Taroify 发布版本，一般是每周一次

### 同步最新代码

提 Pull Request 前，请依照下面的流程同步主仓库的最新代码：

```bash
# 添加主仓库到 remote，作为 fork 后仓库的上游仓库
git remote add upstream https://github.com/taroify/taroify.git

# 拉取主仓库最新代码
git fetch upstream

# 切换至 dev 分支
git checkout main

# 合并主仓库代码
git merge upstream/main
```



---
url: https://taroify.com/changelog/index.md
---

# 更新日志

### 介绍

Taroify 遵循 [Semver](https://semver.org/lang/zh-CN/) 语义化版本规范。

**发布节奏**

- 修订号：每周发布，包含新特性和问题修复。
- 次版本号：每隔一至二个月发布，包含新特性和较大的功能更新，向下兼容。
- 主版本号：发布时间不定，包含不兼容更新。

<!-- 新版本在文档构建时从 GitHub Releases 自动追加。 -->

## 更新内容

### v1.0.2

`2026-07-27`

#### What's Changed

##### New Features 🎉

- feat(image): 🎸 增强图片组件能力 by [@Pilotager](https://github.com/Pilotager) in [#1052](https://github.com/taroify/taroify/pull/1052)
- feat(icon): 新增图标并支持图片图标 by [@Pilotager](https://github.com/Pilotager) in [#1049](https://github.com/taroify/taroify/pull/1049)
- feat(flex): 🎸 增强布局间距并完善工程校验 by [@Pilotager](https://github.com/Pilotager) in [#1057](https://github.com/taroify/taroify/pull/1057)
- feat(popup): 🎸 增强弹出层并完善文档展示 by [@Pilotager](https://github.com/Pilotager) in [#1060](https://github.com/taroify/taroify/pull/1060)

##### Bug Fixes 🐞

- fix: 🐛 修复小程序样式并完善组件测试 by [@Pilotager](https://github.com/Pilotager) in [#1077](https://github.com/taroify/taroify/pull/1077)

##### Other Changes

- chore(deps): update actions/setup-node action to v7 by [@renovate\[bot\]](https://github.com/apps/renovate) in [#1045](https://github.com/taroify/taroify/pull/1045)
- chore(deps): update actions/checkout action to v7 by [@renovate\[bot\]](https://github.com/apps/renovate) in [#1044](https://github.com/taroify/taroify/pull/1044)
- chore(deps): update dependency lefthook to v2 by [@renovate\[bot\]](https://github.com/apps/renovate) in [#1066](https://github.com/taroify/taroify/pull/1066)
- chore(deps): update dependency jest-transform-css to v6 by [@renovate\[bot\]](https://github.com/apps/renovate) in [#1065](https://github.com/taroify/taroify/pull/1065)
- chore(deps): 升级 Lerna 并清理无用资源 by [@Pilotager](https://github.com/Pilotager) in [#1071](https://github.com/taroify/taroify/pull/1071)
- chore(deps): update github artifact actions (major) by [@renovate\[bot\]](https://github.com/apps/renovate) in [#1076](https://github.com/taroify/taroify/pull/1076)
- chore(deps): update actions/github-script digest to 3a2844b by [@renovate\[bot\]](https://github.com/apps/renovate) in [#1075](https://github.com/taroify/taroify/pull/1075)
- chore: 🤖 Release 1.0.2 by [@Pilotager](https://github.com/Pilotager) in [#1078](https://github.com/taroify/taroify/pull/1078)

**Full Changelog**: [https://github.com/taroify/taroify/compare/v1.0.1...v1.0.2](https://github.com/taroify/taroify/compare/v1.0.1...v1.0.2)

### v1.0.1

`2026-07-25`

#### What's Changed

##### New Features 🎉

- feat(button): 完善按钮自定义、加载和无障碍能力 by [@Pilotager](https://github.com/Pilotager) in [#1032](https://github.com/taroify/taroify/pull/1032)
- feat(site): 自动同步 GitHub Release 变更日志 by [@Pilotager](https://github.com/Pilotager) in [#1028](https://github.com/taroify/taroify/pull/1028)
- feat(cell): 升级单元格组件 by [@Pilotager](https://github.com/Pilotager) in [#1036](https://github.com/taroify/taroify/pull/1036)
- feat: 新增 Taroify CLI 与 MCP 支持 by [@Pilotager](https://github.com/Pilotager) in [#1043](https://github.com/taroify/taroify/pull/1043)
- feat: 🎸 Release 1.0.1 by [@Pilotager](https://github.com/Pilotager) in [#1046](https://github.com/taroify/taroify/pull/1046)

##### Bug Fixes 🐞

- fix: 🐛 Radio 和 Checkbox 的背景色和边框区分度不够明显 by [@Pilotager](https://github.com/Pilotager) in [#1025](https://github.com/taroify/taroify/pull/1025)

##### Document 📖

- docs(site): 完善文档展示与版本标记 by [@Pilotager](https://github.com/Pilotager) in [#1023](https://github.com/taroify/taroify/pull/1023)

##### Other Changes

- test(core): 补全组件测试 by [@Pilotager](https://github.com/Pilotager) in [#1022](https://github.com/taroify/taroify/pull/1022)
- docs: ✏️ 更改地址 by [@Pilotager](https://github.com/Pilotager) in [#1026](https://github.com/taroify/taroify/pull/1026)
- chore(deps): update jamesives/github-pages-deploy-action action to v4.8.0 by [@renovate\[bot\]](https://github.com/apps/renovate) in [#1038](https://github.com/taroify/taroify/pull/1038)
- chore(deps): update actions/checkout action to v7 by [@renovate\[bot\]](https://github.com/apps/renovate) in [#1039](https://github.com/taroify/taroify/pull/1039)
- chore(deps): update actions/setup-node action to v7 by [@renovate\[bot\]](https://github.com/apps/renovate) in [#1040](https://github.com/taroify/taroify/pull/1040)

#### New Contributors

- [@renovate\[bot\]](https://github.com/apps/renovate) made their first contribution in [#1038](https://github.com/taroify/taroify/pull/1038)

**Full Changelog**: [https://github.com/taroify/taroify/compare/v1.0.0...v1.0.1](https://github.com/taroify/taroify/compare/v1.0.0...v1.0.1)

### v1.0.0

`2026-07-20`

**新功能 🎉**

- Tour
  - 新增漫游式引导组件 [83027f7](https://github.com/taroify/taroify/commit/83027f755fedbf1022597081ee6267ad85ed5931) [@Pilotager](https://github.com/Pilotager)
- ConfigProvider
  - 支持暗黑模式 [7d0fcc8](https://github.com/taroify/taroify/commit/7d0fcc8cefc56208ea166cc80d6b5c5ff03d6e50) [@Pilotager](https://github.com/Pilotager)
- Checkbox / Radio
  - 增加 `shape="button"`，支持按钮式选择场景 [#1017](https://github.com/taroify/taroify/pull/1017) [@Pilotager](https://github.com/Pilotager)
- SafeArea
  - 支持自定义安全区背景 [#1016](https://github.com/taroify/taroify/pull/1016) [@Pilotager](https://github.com/Pilotager)
- 文档站
  - 从 Gatsby 迁移至 Rspress 2，新增定制主题、搜索和组件模拟器 [#1020](https://github.com/taroify/taroify/pull/1020) [@Pilotager](https://github.com/Pilotager)

**性能优化 🚀**

- Form
  - Rule 支持布尔类型表单项 [#1015](https://github.com/taroify/taroify/pull/1015) [@felix9ia](https://github.com/felix9ia)

**Bug 修复 🐞**

- ActionBar
  - 修复图标按钮 Badge 包装后缺少 React key 的警告 [#1016](https://github.com/taroify/taroify/pull/1016) [@Pilotager](https://github.com/Pilotager)
- Input
  - 修复 `type="number"` 时未过滤非数字字符的问题 [#1016](https://github.com/taroify/taroify/pull/1016) [@Pilotager](https://github.com/Pilotager)
- DropdownMenu
  - 增加 `ellipsis` 配置，支持关闭标题省略 [#1016](https://github.com/taroify/taroify/pull/1016) [@Pilotager](https://github.com/Pilotager)
- FloatingPanel / FixedView
  - 增加 `safeAreaProps`，支持独立配置安全区背景 [#1016](https://github.com/taroify/taroify/pull/1016) [@Pilotager](https://github.com/Pilotager)
- List / PullRefresh
  - 修复固定高度下拉刷新问题 [#1016](https://github.com/taroify/taroify/pull/1016) [@Pilotager](https://github.com/Pilotager)
- Transition
  - 修复微信小程序 `nodeRef` 警告 [#1016](https://github.com/taroify/taroify/pull/1016) [@Pilotager](https://github.com/Pilotager)
- Textarea
  - 修复安卓端 `limit` 字数限制失效问题 [#1016](https://github.com/taroify/taroify/pull/1016) [@Pilotager](https://github.com/Pilotager)
- Form
  - 修复嵌套字段提交结构 [#1018](https://github.com/taroify/taroify/pull/1018) [@Pilotager](https://github.com/Pilotager)

**其他变更**

- 更新 `vite-plugin-style-import` 配置 [#1011](https://github.com/taroify/taroify/pull/1011) [@xuxucode](https://github.com/xuxucode)

**Full Changelog**: [v0.9.2...v1.0.0](https://github.com/taroify/taroify/compare/v0.9.2...v1.0.0)

### v0.9.2

`2026-03-10`

**Bug Fixes**

- Cell

  - 修复 `value` 空占位问题 [1006](https://github.com/taroify/taroify/pull/1006) [@Duo-Huang](https://github.com/Duo-Huang)

- Collapse

  - 修复在小程序上表现卡顿问题 [1002](https://github.com/taroify/taroify/pull/1002) [@Pilotager](https://github.com/Pilotager)

### v0.9.1

`2026-03-08`

**Feature**

- Calendar

  - 支持配置是否显示主标题 [972](https://github.com/taroify/taroify/pull/972) [@qiuxsgit](https://github.com/qiuxsgit)

- TabPanel

  - 将TabPane重命名为TabPanel并更新相关组件和文档 [975](https://github.com/taroify/taroify/pull/975) [@Shixuebin](https://github.com/Shixuebin)

- FloatingPanel

  - 禁用内部 `ScrollView` 的在 IOS 上的 `bounces` 橡皮筋回弹效果 [988](https://github.com/taroify/taroify/pull/988) [@felix9ia](https://github.com/felix9ia)

- Cell

  - 增加 `valueClass` 属性 [994](https://github.com/taroify/taroify/pull/994) [@xuxucode](https://github.com/xuxucode)

**Bug Fixes**

- PullRefresh

  - 在 h5 环境下包裹 List 不能正常滚动的问题 [964](https://github.com/taroify/taroify/pull/964) [@felix9ia](https://github.com/felix9ia)

- Upload

  - `Uploader` 自定义预览样式异常，增加 `customUploadButton` 属性 [966](https://github.com/taroify/taroify/pull/966) [@naFeKnehC](https://github.com/naFeKnehC)
  - 增加 `itemRender` 用来修复使用react children属性时图片重复渲染 [967](https://github.com/taroify/taroify/pull/967) [@naFeKnehC](https://github.com/naFeKnehC)

- Cell

  - 修复 taroify-cell\_\_value 为空的时候依然占位 [968](https://github.com/taroify/taroify/pull/968) [@felix9ia](https://github.com/felix9ia)

- FixedView

  - 修复切换页面高度问题 [996](https://github.com/taroify/taroify/pull/996) [@Pilotager](https://github.com/Pilotager)

- Toast

  - 修复多个 `Toast` 叠加问题 [998](https://github.com/taroify/taroify/pull/998) [@Duo-Huang](https://github.com/Duo-Huang)

- Icon

  - 修复 `color` 属性不生效问题 [999](https://github.com/taroify/taroify/pull/999) [@Pilotager](https://github.com/Pilotager)

- Radio

  - 修复 `1px` 边框问题 [1000](https://github.com/taroify/taroify/pull/1000) [@Pilotager](https://github.com/Pilotager)

**Other**

- 修正 `List` 搭配 `PullRefresh` 的使用示例 [968](https://github.com/taroify/taroify/pull/968) [@felix9ia](https://github.com/felix9ia)
- 更新 `Progress` 示例 [969](https://github.com/taroify/taroify/pull/969) [@lvqq](https://github.com/lvqq)
- 修复 `CI` 环境报错 [970](https://github.com/taroify/taroify/pull/970) [@lvqq](https://github.com/lvqq)
- 更新 `Dialog` 样式文档 [973](https://github.com/taroify/taroify/pull/973) [@lvqq](https://github.com/lvqq)
- 更新 `Cell` 测试快照 [981](https://github.com/taroify/taroify/pull/981) [@Pilotager](https://github.com/Pilotager)
- 更新 `Vite` 按需加载示例 [996](https://github.com/taroify/taroify/pull/996) [@Pilotager](https://github.com/Pilotager)
- 更新 `$hd` 注入文档 [1001](https://github.com/taroify/taroify/pull/1001) [@Pilotager](https://github.com/Pilotager)

### v0.9.0

`2025-06-15`

**Other**

- sass 里使用 @use 和 @forward 替换 @import [961](https://github.com/taroify/taroify/pull/961) [@hbztd](https://github.com/hbztd)
- 文档添加可以使用编译后的css相关说明 [961](https://github.com/taroify/taroify/pull/961) [@hbztd](https://github.com/hbztd)
- Field 文档更新 [960](https://github.com/taroify/taroify/pull/960) [@Zhengxing-Gu](https://github.com/Zhengxing-Gu)

### v0.8.1

`2025-05-25`

**Feature**

- FloatingPanel

  - 添加手动设置高度功能 [943](https://github.com/taroify/taroify/pull/944) [@HyaCiovo](https://github.com/HyaCiovo)

**Bug Fixes**

- Popup

  - Popup 组件初次挂载时会执行 onClose 事件 [943](https://github.com/taroify/taroify/pull/943) [@HyaCiovo](https://github.com/HyaCiovo)

- Transition

  - 修复 Transition 组件的 findDOMNode API报错问题 [949](https://github.com/taroify/taroify/pull/949) [@HyaCiovo](https://github.com/HyaCiovo)

- Checkbox

  - 在背景中使用正确的变量 [951](https://github.com/taroify/taroify/pull/951) [@lvqq](https://github.com/lvqq)

- Dialog

  - 未传入 title 时仍然渲染 header 的问题 [954](https://github.com/taroify/taroify/pull/954) [@twomoonbird](https://github.com/twomoonbird)

  - 支持设置 message 的 font-weight [955](https://github.com/taroify/taroify/pull/955) [@twomoonbird](https://github.com/twomoonbird)

### v0.8.0

`2025-04-20`

**Feature**

- Skeleton

  - 重构 `Skeleton`，放弃旧版本 `Skeleton` 使用方式 [925](https://github.com/taroify/taroify/pull/925) [@Pilotager](https://github.com/Pilotager)

- Cell

  - 添加 `titleStyle`、`titleClass`、`valueClass`、`briefClass` 属性 [930](https://github.com/taroify/taroify/pull/930) [@Pilotager](https://github.com/Pilotager)

**Other**

- 文档更新 `MCP` 使用方式 [939](https://github.com/taroify/taroify/pull/939) [@Pilotager](https://github.com/Pilotager)

### v0.7.0

`2025-04-06`

**Feature**

- Divider

  - 添加 `type` 属性使分割线垂直展示 [909](https://github.com/taroify/taroify/pull/909) [@Pilotager](https://github.com/Pilotager)

- TextEllipsis

  - 增加 `toggle` 方法 [915](https://github.com/taroify/taroify/pull/915) [@Pilotager](https://github.com/Pilotager)

- Toast

  - 增加 `Toast.allowMultiple()` 方法 [921](https://github.com/taroify/taroify/pull/921) [@Pilotager](https://github.com/Pilotager)

- Dialog

  - 实现多实例 [922](https://github.com/taroify/taroify/pull/922) [@Pilotager](https://github.com/Pilotager)

**Bug Fixes**

- ActionBar

  - 优化文字换行 [899](https://github.com/taroify/taroify/pull/899) [@Pilotager](https://github.com/Pilotager)

- Toast

  - 微信小程序Toast或Dialog在特定的回调里报错 [917](https://github.com/taroify/taroify/pull/917) [@Pilotager](https://github.com/Pilotager)

**Other**

- Biome 格式化 [904](https://github.com/taroify/taroify/pull/904) [@Pilotager](https://github.com/Pilotager)

### v0.6.4-alpha.0

`2025-02-23`

**Feature**

- List

  - 新增 `onScroll` 事件 [892](https://github.com/taroify/taroify/pull/892) [@hbztd](https://github.com/hbztd)

- Tabs

  - 新增 `shrink` 属性 [892](https://github.com/taroify/taroify/pull/892) [@hbztd](https://github.com/hbztd)

- Field

  - Input、Textarea 设置 `min-height` 值为 `inherit` [892](https://github.com/taroify/taroify/pull/892) [@hbztd](https://github.com/hbztd)

- Switch

  - 开关组件按有赞美化 [894](https://github.com/taroify/taroify/pull/894) [@wenqiyun](https://github.com/wenqiyun)

**Bug Fixes**

- SafeArea

  - 替换成 getWindowInfo 方法 [885](https://github.com/taroify/taroify/pull/885) [@Pilotager](https://github.com/Pilotager)

- FixedView

  - 修复设置 placheholder 后 render 过程中 children 会重建 [892](https://github.com/taroify/taroify/pull/892) [@hbztd](https://github.com/hbztd)

- Navbar

  - 修复设置 placheholder 后 render 过程中 children 会重建 [892](https://github.com/taroify/taroify/pull/892) [@hbztd](https://github.com/hbztd)

- Dialog

  - 消除节点新增删除带来的副作用 [896](https://github.com/taroify/taroify/pull/896) [@wenqiyun](https://github.com/wenqiyun)

### v0.6.3-alpha.0

`2025-01-05`

**Bug Fixes**

- Picker

  - 修复 `Picker` 中 `columns` 更新未更新选中值 [875](https://github.com/taroify/taroify/pull/875) [@Pilotager](https://github.com/Pilotager)

**Other**

- 添加 Biome [872](https://github.com/taroify/taroify/pull/872) [@ianzone](https://github.com/ianzone)
- 文档新增新特性版本号 [870](https://github.com/taroify/taroify/pull/870) [@CodeMak1r-zy](https://github.com/CodeMak1r-zy)

### v0.6.2-alpha.0

`2024-12-25`

**Bug Fixes**

- Toast

  - 修复 `close` 方法不生效问题 [865](https://github.com/taroify/taroify/pull/865) [@Pilotager](https://github.com/Pilotager)

- Notify

  - 修复 `close` 方法不生效问题 [865](https://github.com/taroify/taroify/pull/865) [@Pilotager](https://github.com/Pilotager)

**Other**

- 添加属性新特性版本号 [867](https://github.com/taroify/taroify/pull/867) [@Pilotager](https://github.com/Pilotager)

### v0.6.1-alpha.0

`2024-12-18`

**Other**

- lodash 支持 tree shaking [861](https://github.com/taroify/taroify/pull/861) [@hbztd](https://github.com/hbztd)

### v0.6.0-alpha.0

`2024-12-08`

**Feature**

- Toast

  - 支持直接函数调用 [852](https://github.com/taroify/taroify/pull/852) [@hbztd](https://github.com/hbztd)

- Notify

  - 支持直接函数调用，添加 `color` `background` 属性 [852](https://github.com/taroify/taroify/pull/852) [@hbztd](https://github.com/hbztd)

- Dialog

  - 支持直接函数调用，添加 `title` `message` `messageAlign` `theme` `confirm` `cancel` `onBeforeClose` 属性 [852](https://github.com/taroify/taroify/pull/852) [@hbztd](https://github.com/hbztd)

**Bug Fixes**

- ActionSheet

  - 为 `ActionSheet` 组件添加默认的安全区域 [840](https://github.com/taroify/taroify/pull/840) [@sweet7788](https://github.com/sweet7788)

- List

  - `scrollParentRect` 判空 [843](https://github.com/taroify/taroify/pull/843) [@Pilotager](https://github.com/Pilotager)

- Pick

  - 修复 picker 组件在快速上滑或者下滑时，执行惯性动画期间，再次滚动 picker-column 后出现的位置卡顿问题 [844](https://github.com/taroify/taroify/pull/844) [@kunkuntang](https://github.com/kunkuntang)

- Popup

  - 修复手动关闭未触发 `onClose` 事件 [852](https://github.com/taroify/taroify/pull/852) [@hbztd](https://github.com/hbztd)

- TextArea

  - 修复 `getStringLength` 在输入 emoji 时无法正确统计字符长度 [853](https://github.com/taroify/taroify/pull/853) [@CodeMak1r-zy](https://github.com/CodeMak1r-zy)

- Form

  - 修复 `validateFirst` [857](https://github.com/taroify/taroify/pull/857) [@linxianxi](https://github.com/linxianxi)

**Other**

- 完善 DateTimePicker 文档 [834](https://github.com/taroify/taroify/pull/834) [@sweet7788](https://github.com/sweet7788)
- 完善 FormItem 文档 [837](https://github.com/taroify/taroify/pull/837) [@Niubility-SunLight](https://github.com/Niubility-SunLight)
- 完善 Form 文档 [847](https://github.com/taroify/taroify/pull/847) [@lvqq](https://github.com/lvqq)
- 完善 Calendar 文档 [850](https://github.com/taroify/taroify/pull/853) [@CodeMak1r-zy](https://github.com/CodeMak1r-zy)
- lodash 支持 tree shaking [851](https://github.com/taroify/taroify/pull/851) [@hbztd](https://github.com/hbztd)

### v0.5.1-alpha.0

`2024-10-28`

**Feature**

- SafeArea

  - 新增 `nativeSafeTop` 属性，是否启用小程序顶部安全区高度 [830](https://github.com/taroify/taroify/pull/830) [@Pilotager](https://github.com/Pilotager)

**Bug Fixes**

- SafeArea

  - 修复安全区底部判断问题 [830](https://github.com/taroify/taroify/pull/830) [@Pilotager](https://github.com/Pilotager)

### v0.5.0-alpha.0

`2024-10-27`

**Feature**

- Cascader

  - 新增 `ellipsis` 属性 [817](https://github.com/taroify/taroify/pull/817) [@Pilotager](https://github.com/Pilotager)

- Form

  - `FormItem` 添加 `validateFirst` 属性， 用于只返回第一个失败校验 [818](https://github.com/taroify/taroify/pull/818) [@Niubility-SunLight](https://github.com/Niubility-SunLight)

**Bug Fixes**

- Form

  - 修复设置 `controlAlign` right 后，feedback 没有向右对齐 [820](https://github.com/taroify/taroify/pull/820) [@Niubility-SunLight](https://github.com/Niubility-SunLight)

- SafeArea

  - 优化小程序环境顶部安全区距离 [826](https://github.com/taroify/taroify/pull/826) [@CodeMak1r-zy](https://github.com/CodeMak1r-zy)

- IndexList

  - 修复异步传入数据时 `anchorRects` 报错问题 [828](https://github.com/taroify/taroify/pull/828) [@Pilotager](https://github.com/Pilotager)

**Other**

- `SafeArea` 新增单测[826](https://github.com/taroify/taroify/pull/826) [@CodeMak1r-zy](https://github.com/CodeMak1r-zy)

### v0.4.2-alpha.0

`2024-10-13`

**Bug Fixes**

- Cascader

  - 修复不能上下滑动问题 [813](https://github.com/taroify/taroify/pull/813) [@Pilotager](https://github.com/Pilotager)

- Uploader

  - 修复图片加载中或者未加载出来样式问题 [814](https://github.com/taroify/taroify/pull/814) [@Pilotager](https://github.com/Pilotager)

### v0.4.1-alpha.0

`2024-09-22`

**Bug Fixes**

- Icon

  - 修复 icon css 后加载导致 `Rate` 没有颜色 [804](https://github.com/taroify/taroify/pull/804) [@hbztd](https://github.com/hbztd)

- Tabbar

  - 修复 `Tabbar.TabItem` icon className 丢失 [804](https://github.com/taroify/taroify/pull/804) [@hbztd](https://github.com/hbztd)

- Uploader

  - 修复 `Uploader` 自定义样式，无法触发 `onUpload` [804](https://github.com/taroify/taroify/pull/804) [@hbztd](https://github.com/hbztd)

- Form

  - 修复 Form rules 某些情况下，trigger 过滤错误 [804](https://github.com/taroify/taroify/pull/804) [@hbztd](https://github.com/hbztd)
  - 修复 Form Input 输入后立即调用 reset，未清空错误显示 [804](https://github.com/taroify/taroify/pull/804) [@hbztd](https://github.com/hbztd)

**Other**

- 完善 `Cell` 单测 [805](https://github.com/taroify/taroify/pull/805) [@Pilotager](https://github.com/Pilotager)

### v0.4.0-alpha.0

`2024-08-18`

**Feature**

- Search

  - 透传 `enableNative` 属性 [790](https://github.com/taroify/taroify/pull/790) [@Pilotager](https://github.com/Pilotager)

- Toast

  - `duration` 为 `0` 时，提示不消失 [793](https://github.com/taroify/taroify/pull/793) [@Pilotager](https://github.com/Pilotager)

- Tag

  - 添加边框颜色 `css` 变量 [801](https://github.com/taroify/taroify/pull/801) [@hbztd](https://github.com/hbztd)

- Circle

  - 重构，WEB 和小程序都使用 `Canvas 2D` 接口实现 [801](https://github.com/taroify/taroify/pull/801) [@hbztd](https://github.com/hbztd)
  - 添加 `startPosition` 属性 [801](https://github.com/taroify/taroify/pull/801) [@hbztd](https://github.com/hbztd)

**Bug Fixes**

- NumberKeyboard

  - 优化按钮字体大小 [788](https://github.com/taroify/taroify/pull/788) [@Pilotager](https://github.com/Pilotager)

- Cascader

  - 修复 `Cascader` 第一次打开时动画卡顿 [801](https://github.com/taroify/taroify/pull/801) [@hbztd](https://github.com/hbztd)

- Popup

  - 修复 `duration` 属性不起作用 [801](https://github.com/taroify/taroify/pull/801) [@hbztd](https://github.com/hbztd)

- Backdrop

  - 修复 `duration` 属性不起作用 [801](https://github.com/taroify/taroify/pull/801) [@hbztd](https://github.com/hbztd)

**Other**

- 完善 `FixedNav` 文档 [789](https://github.com/taroify/taroify/pull/789) [@Pilotager](https://github.com/Pilotager)
- `Progress` 文档更新 [799](https://github.com/taroify/taroify/pull/799) [@Pilotager](https://github.com/Pilotager)
- 内置样式添加触摸反馈 [801](https://github.com/taroify/taroify/pull/801) [@hbztd](https://github.com/hbztd)

### v0.3.2-alpha.0

`2024-08-04`

**Feature**

- Image

  - 添加 `width` `height` 属性 [784](https://github.com/taroify/taroify/pull/784) [@hbztd](https://github.com/hbztd)

**Bug Fixes**

- Empty

  - 修复 `Empty` 组件图片居中问题 [779](https://github.com/taroify/taroify/pull/779) [@CodeMak1r-zy](https://github.com/CodeMak1r-zy)

- FloatingBubble

  - 修复 `sass` 变量未进行适配 [782](https://github.com/taroify/taroify/pull/782) [@Pilotager](https://github.com/Pilotager)

- Image

  - 修复加载中未显示 `placeholder` [784](https://github.com/taroify/taroify/pull/784) [@hbztd](https://github.com/hbztd)

### v0.3.1-alpha.0

`2024-07-09`

**Feature**

- Form

  - Form 添加 `disabled` 属性，实例添加 `submit` 方法 [767](https://github.com/taroify/taroify/pull/767) [@hbztd](https://github.com/hbztd)

**Bug Fixes**

- BackTop

  - Scss 添加 `$hd` 变量配置 [762](https://github.com/taroify/taroify/pull/762) [@Pilotager](https://github.com/Pilotager)

- FixedNav

  - Scss 添加 `$hd` 变量配置 [768](https://github.com/taroify/taroify/pull/768) [@Pilotager](https://github.com/Pilotager)

- Form

  - 修复 `Checkbox.Group` 设置 `disabled` 无效 [767](https://github.com/taroify/taroify/pull/767) [@hbztd](https://github.com/hbztd)

- Avatar

  - 修复 `Avatar` 里为图片时，样式不对 [777](https://github.com/taroify/taroify/pull/767) [@hbztd](https://github.com/hbztd)
  - `Image` 默认继承父元素宽高 [777](https://github.com/taroify/taroify/pull/767) [@hbztd](https://github.com/hbztd)

**Other**

- 修复 `taro` 预编译 `@taroify/core` `@taroify/icons` 失败 [763](https://github.com/taroify/taroify/pull/763) [@hbztd](https://github.com/hbztd)

- package.json 添加 `repository` 和 `bugs` [764](https://github.com/taroify/taroify/pull/764) [@Pilotager](https://github.com/Pilotager)

### v0.3.0-alpha.0

`2024-06-23`

**Feature**

- Flex

  - 为 `flex align` 添加了初始属性 [753](https://github.com/taroify/taroify/pull/753) [@sehmbimanvir](https://github.com/sehmbimanvir)

- Badge

  - 重构 `Badge` 组件，`Grid` `Sidebar` `Tabbar` `Tabs` `TreeSelect` 组件徽标相关代码调整 [754](https://github.com/taroify/taroify/pull/754) [@hbztd](https://github.com/hbztd)

- Icon

  - 支持自定义图标 [754](https://github.com/taroify/taroify/pull/754) [@hbztd](https://github.com/hbztd)

- ActionSheet

  - 添加 actions，description, cancelText 属性 [760](https://github.com/taroify/taroify/pull/760) [@hbztd](https://github.com/hbztd)

**Bug Fixes**

- CountDown

  - 修复 Countdown 组件在卸载时仍然继续执行倒计时并触发 onComplete [760](https://github.com/taroify/taroify/pull/760) [@hbztd](https://github.com/hbztd)

- ActionSheet

  - 修复 loading 和 disabled 属性不起作用 [760](https://github.com/taroify/taroify/pull/760) [@hbztd](https://github.com/hbztd)

**Other**

- 修复 `@taroify/core` `@taroify/icons`，taro 预编译失败 [755](https://github.com/taroify/taroify/pull/755) [@hbztd](https://github.com/hbztd)

- 删除 babel 转换和 sourcemap 文件[755](https://github.com/taroify/taroify/pull/755) [@hbztd](https://github.com/hbztd)

### v0.2.3-alpha.0

`2024-06-02`

**Bug Fixes**

- Cascader

  - 修复级联选择 `options` 无法设置为空 [746](https://github.com/taroify/taroify/pull/746) [@hbztd](https://github.com/hbztd)

- Calendar

  - 修复日历 `subtitle` 在手动设置 `value` 时，可能出现显示错误 [747](https://github.com/taroify/taroify/pull/747) [@hbztd](https://github.com/hbztd)

**Feature**

- DropdownMenu

  - 背景板添加类型 [748](https://github.com/taroify/taroify/pull/748) [@Pilotager](https://github.com/Pilotager)

**Other**

- 文档代码示例添加复制按钮 [746](https://github.com/taroify/taroify/pull/746) [@hbztd](https://github.com/hbztd)

- 更新文档内示例以及属性 [747](https://github.com/taroify/taroify/pull/747) [@hbztd](https://github.com/hbztd)

### v0.2.2-alpha.1

`2024-05-30`

**Bug Fixes**

- Tabbar

  - 修复 `Tabbar icon` 传递 `ReactNode` 丢失原有 `className` [736](https://github.com/taroify/taroify/pull/736) [@wenqiyun](https://github.com/wenqiyun)

- Signature

  - 修复 `getWindowInfo` 在抖音小程序报错问题 [738](https://github.com/taroify/taroify/pull/736) [@Pilotager](https://github.com/Pilotager)

- PullRefresh

  - 修复小程序环境内 `throttle` 报 `now of undefined` [743](https://github.com/taroify/taroify/pull/743) [@Pilotager](https://github.com/Pilotager)

### v0.2.2-alpha.0

`2024-05-19`

**Bug Fixes**

- Input

  - 修复 `readonly` 属性 [731](https://github.com/taroify/taroify/pull/731) [@SexySix](https://github.com/SexySix)

- Form

  - 修复 `Form.Label`设置 `className` 后，组件本身 `className` 被覆盖 [733](https://github.com/taroify/taroify/pull/733) [@hbztd](https://github.com/hbztd)

  - 修复 `Form.Item`、`isLink` 属性不起作用 [733](https://github.com/taroify/taroify/pull/733) [@hbztd](https://github.com/hbztd)

- BackTop

  - 组件默认高亮颜色应该从 `--primary-color` 取，而不是 `--blue` [734](https://github.com/taroify/taroify/pull/734) [@hbztd](https://github.com/hbztd)

- Badge

  - 组件默认高亮颜色应该从 `--primary-color` 取，而不是 `--blue` [734](https://github.com/taroify/taroify/pull/734) [@hbztd](https://github.com/hbztd)

- NavBar

  - 组件默认高亮颜色应该从 `--primary-color` 取，而不是 `--blue` [734](https://github.com/taroify/taroify/pull/734) [@hbztd](https://github.com/hbztd)

- Pagination

  - 组件默认高亮颜色应该从 `--primary-color` 取，而不是 `--blue` [734](https://github.com/taroify/taroify/pull/734) [@hbztd](https://github.com/hbztd)

- Slider

  - 组件默认高亮颜色应该从 `--primary-color` 取，而不是 `--blue` [734](https://github.com/taroify/taroify/pull/734) [@hbztd](https://github.com/hbztd)

- Swiper

  - 组件默认高亮颜色应该从 `--primary-color` 取，而不是 `--blue` [734](https://github.com/taroify/taroify/pull/734) [@hbztd](https://github.com/hbztd)

- Tabbar

  - 组件默认高亮颜色应该从 `--primary-color` 取，而不是 `--blue` [734](https://github.com/taroify/taroify/pull/734) [@hbztd](https://github.com/hbztd)

### v0.2.1-alpha.0

`2024-05-10`

**Feature**

- IndexList

  - 添加 `showSidebar` 和 `onChange` 属性 [723](https://github.com/taroify/taroify/pull/723) [@Pilotager](https://github.com/Pilotager)

  - 添加手动调用 `scrollTo` 方法 [724](https://github.com/taroify/taroify/pull/724) [@Pilotager](https://github.com/Pilotager)

### v0.2.0-alpha.0

`2024-05-09`

**Feature**

- IndexList

  - 添加底部弹窗内使用方式 [721](https://github.com/taroify/taroify/pull/721) [@Pilotager](https://github.com/Pilotager)

**Other**

- Taro 相关依赖项改为 >=3 [721](https://github.com/taroify/taroify/pull/721) [@Pilotager](https://github.com/Pilotager)

### v0.1.7-alpha.0

`2024-04-28`

**Feature**

- Dropdown

  - DropdownMenuItem: 支持 `lock` 和 `options` 属性 [718](https://github.com/taroify/taroify/pull/718) [@hbztd](https://github.com/hbztd)

**Bug Fixes**

- Flex

  - 修复 `flex` 在 `wrap` 情况下，如果设置了 `gutter`, 换行后首个元素错位 [712](https://github.com/taroify/taroify/pull/712) [@Pilotager](https://github.com/Pilotager)

- DatetimePicker

  - 修复 `DatetimePicker` 可选择月和日的情况下，由于代码中先设置月份，会导致所有最后一天小于 `minDate` 的日的月份被设置为下一个月 [714](https://github.com/taroify/taroify/pull/714) [@SexySix](https://github.com/SexySix)

- Swiper

  - 修复 `SwiperItem` 初始化后再渲染 [717](https://github.com/taroify/taroify/pull/717) [@hbztd](https://github.com/hbztd)
  - 修复在微信上 `TabsHeader` 滚动时，不应显示滚动条 [717](https://github.com/taroify/taroify/pull/717) [@hbztd](https://github.com/hbztd)

- Dropdown

  - 修复 `Search` 有两个 X [718](https://github.com/taroify/taroify/pull/718) [@hbztd](https://github.com/hbztd)

### v0.1.6-alpha.0

`2024-03-24`

**Feature**

- Form

  - Form.Item 添加 `dependencies` `shouldUpdate` `noStyle` 属性 [705](https://github.com/taroify/taroify/pull/705) [@hbztd](https://github.com/hbztd)

**Bug Fixes**

- Grid

  - 修复 `children` 为 null 引发的错误问题 [703](https://github.com/taroify/taroify/pull/703) [@Hector-Chong](https://github.com/Hector-Chong)

- Form

  - 修复 Form.Item 点击报错(taro>=3.6.23 事件绑定 undefined 触发时报错) [705](https://github.com/taroify/taroify/pull/705) [@hbztd](https://github.com/hbztd)
  - 修复 Field 未提供 FormItemInstance [705](https://github.com/taroify/taroify/pull/705) [@hbztd](https://github.com/hbztd)

- Style

  - 修复 `Radio` 和 `Checkbox` 默认字体大小比其他大，`Input` 和 `Textarea` 字体不一致问题 [706](https://github.com/taroify/taroify/pull/706) [@hbztd](https://github.com/hbztd)
  - 修复 `Form` 右对齐时，\*位置不对问题 [706](https://github.com/taroify/taroify/pull/706) [@hbztd](https://github.com/hbztd)

- FloatingPanel

  - 修复 `FloatingPanel` 无法向下滑动关闭问题 [709](https://github.com/taroify/taroify/pull/709) [@Pilotager](https://github.com/Pilotager)

**Other**

- 升级 Taro 版本为 3.6.23 [700](https://github.com/taroify/taroify/pull/700) [@Pilotager](https://github.com/Pilotager)

- Button 测试率覆盖 100% [701](https://github.com/taroify/taroify/pull/701) [@sehmbimanvir](https://github.com/sehmbimanvir)

- 修复 Form 组件文档内连接链接多了前缀 [705](https://github.com/taroify/taroify/pull/705) [@hbztd](https://github.com/hbztd)

### v0.1.5-alpha.0

`2024-02-19`

**Bug Fixes**

- Loading

  - 修复 `addUnitPx` 判断条件错误 [693](https://github.com/taroify/taroify/pull/693) [@sehmbimanvir](https://github.com/sehmbimanvir)

**Feature**

- Popup

  - `placement` 添加 `center` 选项 [690](https://github.com/taroify/taroify/pull/690) [@Hector-Chong](https://github.com/Hector-Chong)

**Other**

- 修复 `jest` 配置错误导致 `yarn test` 报错问题 [691](https://github.com/taroify/taroify/pull/691) [@sehmbimanvir](https://github.com/sehmbimanvir)

- 完善 `NavBar` 测试用例 [692](https://github.com/taroify/taroify/pull/692) [@sehmbimanvir](https://github.com/sehmbimanvir)

- 完善 `FixedNav` 测试用例 [694](https://github.com/taroify/taroify/pull/694) [@Pilotager](https://github.com/Pilotager)

- 完善 `FloatingPanel` 测试用例 [695](https://github.com/taroify/taroify/pull/695) [@Pilotager](https://github.com/Pilotager)

**Doc**

- npm 文档更新 [698](https://github.com/taroify/taroify/pull/698) [@Pilotager](https://github.com/Pilotager)

### v0.1.4-alpha.0

`2024-02-09`

**Bug Fixes**

- Input

  - 修复 Input 组件的 `font-size` 无法被正常继承问题 [680](https://github.com/taroify/taroify/pull/680) [@Hector-Chong](https://github.com/Hector-Chong)

- Radio

  - 添加泛型 [681](https://github.com/taroify/taroify/pull/681) [@Hector-Chong](https://github.com/Hector-Chong)

- Checkbox

  - 添加泛型 [681](https://github.com/taroify/taroify/pull/681) [@Hector-Chong](https://github.com/Hector-Chong)

- AreaSelector

  - 修复值未定义时异常处理 [682](https://github.com/taroify/taroify/pull/682) [@Hector-Chong](https://github.com/Hector-Chong)

- Uploader

  - `onChange` 事件添加优化类型定义 [683](https://github.com/taroify/taroify/pull/683) [@Hector-Chong](https://github.com/Hector-Chong)

- Popup

  - 去除 console [684](https://github.com/taroify/taroify/pull/684) [@Pilotager](https://github.com/Pilotager)

- FixedNav

  - 去除 console [685](https://github.com/taroify/taroify/pull/685) [@Pilotager](https://github.com/Pilotager)

**Feature**

- Popup

  - 添加 `lock` 属性以及 H5 禁止滚动穿透 [679](https://github.com/taroify/taroify/pull/679) [@Pilotager](https://github.com/Pilotager)

### v0.1.3-alpha.1

`2024-02-04`

**Bug Fixes**

- Input

  - 修复 `Input` 在只读模式下字体颜色问题 [674](https://github.com/taroify/taroify/pull/674) [@Pilotager](https://github.com/Pilotager)

- Flex
  - 修复 `Flex` 无法渲染文本节点(导致 `Timeline` 无法渲染) [676](https://github.com/taroify/taroify/pull/676) [@hbztd](https://github.com/hbztd)

**Doc**

- 优化线上打开文档页面会闪一下 [675](https://github.com/taroify/taroify/pull/675) [@hbztd](https://github.com/hbztd)
- 优化文档内跳转 [675](https://github.com/taroify/taroify/pull/675) [@hbztd](https://github.com/hbztd)
- 链接地址修复 [675](https://github.com/taroify/taroify/pull/675) [@hbztd](https://github.com/hbztd)

### v0.1.3-alpha.0

`2024-02-02`

**Bug Fixes**

- Image

  - 修复 `Image` 组件快速加载样式问题 [668](https://github.com/taroify/taroify/pull/668) [@Pilotager](https://github.com/Pilotager)

- Flex

  - 优化 `Flex` 两边间距 [669](https://github.com/taroify/taroify/pull/669) [@Pilotager](https://github.com/Pilotager)

- Watermark
  - 修复 `Watermark` 样式引入问题 [670](https://github.com/taroify/taroify/pull/670) [@sehmbimanvir](https://github.com/sehmbimanvir)

**Feature**

- Popup
  - `Popup` 居中弹出添加圆角属性 [672](https://github.com/taroify/taroify/pull/672) [@Pilotager](https://github.com/Pilotager)

**Doc**

- Popup：添加居中弹出圆角示例
- Popup：添加自定义图标示例
- Flex: 优化示例内代码

### v0.1.2-alpha.0

`2024-01-27`

**Bug Fixes**

- AreaPicker
  - 修复 AreaPicker 选中确认报错问题 [664](https://github.com/taroify/taroify/pull/664) [@Pilotager](https://github.com/Pilotager)

**Feature**

- FixedNav

  - 添加 FixedNav 组件 [662](https://github.com/taroify/taroify/pull/662) [@Pilotager](https://github.com/Pilotager)

- FloatingPanel

  - 优化反弹动画 [661](https://github.com/taroify/taroify/pull/661) [@Pilotager](https://github.com/Pilotager)

- Watermark
  - 添加 CSS Variables 类型 [665](https://github.com/taroify/taroify/pull/665) [@Pilotager](https://github.com/Pilotager)

**Doc**

- 完善 Tab 文档，添加 `dot` `badge` 属性 [660](https://github.com/taroify/taroify/pull/660) [@Pilotager](https://github.com/Pilotager)
- 添加全文搜索功能 [666](https://github.com/taroify/taroify/pull/666) [@Pilotager](https://github.com/Pilotager)

### v0.1.1-alpha.11

`2024-01-21`

**Bug Fixes**

- Popup
  - 修复滚动穿透问题 [657](https://github.com/taroify/taroify/pull/657) [@Pilotager](https://github.com/Pilotager)

**Feature**

- Tabs

  - 添加 `dot` 和 `badge` 属性 [655](https://github.com/taroify/taroify/pull/655) [@Pilotager](https://github.com/Pilotager)

- Watermark
  - 添加 Watermark 水印 [658](https://github.com/taroify/taroify/pull/658) [@hbztd](https://github.com/hbztd)

### v0.1.1-alpha.10

`2024-01-01`

**Bug Fixes**

- Form
  - 修复 CellTitle 导入问题 [651](https://github.com/taroify/taroify/pull/651) [@Pilotager](https://github.com/Pilotager)

### v0.1.1-alpha.9

`2023-12-15`

**Feature**

- TextEllipsis
  - 添加 TextEllipsis 文字省略组件 [646](https://github.com/taroify/taroify/pull/646) [@hbztd](https://github.com/hbztd)

### v0.1.1-alpha.8

`2023-12-07`

**Bug Fixes**

- DatetimePicker
  - 修复 DatetimePicker 多了一个空白 [643](https://github.com/taroify/taroify/pull/643) [@Pilotager](https://github.com/Pilotager)

### v0.1.1-alpha.7

`2023-11-28`

**Feature**

- AreaPicker
  - 添加 `areaList` `title` `confirmText` `cancelText` `optionHeight`, 支持通过属性配置 AreaPicker [639](https://github.com/taroify/taroify/pull/639) [@hbztd](https://github.com/hbztd)

**Bug Fixes**

- AreaPicker

  - 修复 AreaPicker 多了一个空白 [639](https://github.com/taroify/taroify/pull/639) [@hbztd](https://github.com/hbztd)

- Picker
  - 修复选项文字内容超长时未省略 [639](https://github.com/taroify/taroify/pull/639) [@hbztd](https://github.com/hbztd)

### v0.1.1-alpha.6

`2023-11-14`

**Feature**

- Calendar
  - 添加 `poppable` `showPopup` `onClose` 属性，支持弹框展示日历 [636](https://github.com/taroify/taroify/pull/636) [@hbztd](https://github.com/hbztd)
  - 添加 `showConfirm` `confirmText` `confirmDisabledText`，支持自定义确认按钮文案 [636](https://github.com/taroify/taroify/pull/636) [@hbztd](https://github.com/hbztd)
  - 添加 `showSubtitle`，修改 `subtitle`，支持自定义副标题 [636](https://github.com/taroify/taroify/pull/636) [@hbztd](https://github.com/hbztd)

**Bug Fixes**

- Navbar

  - 修复 `placeholder` 属性值默认为 false [634](https://github.com/taroify/taroify/pull/634) [@Pilotager](https://github.com/Pilotager)

- Tabs

  - 修复 TabPane 内容 DOM 上不该有 `title` 属性 [635](https://github.com/taroify/taroify/pull/635) [@hbztd](https://github.com/hbztd)

- Calendar
  - 修复日历在 h5 无法滑动
  - 修复设置 defaultValue，value 没有跳转到对应位置
  - 修复底部按钮在微信小程序里颜色不对

### v0.1.1-alpha.5

`2023-11-05`

**Feature**

- Picker

  - 添加 `optionHeight` 属性，支持配置选项高度 [629](https://github.com/taroify/taroify/pull/629) [@hbztd](https://github.com/hbztd)
  - 添加 `title` `confirmText` `cancelText` `columns` `columnsFieldNames`，支持通过数据配置选项 [629](https://github.com/taroify/taroify/pull/629) [@hbztd](https://github.com/hbztd)

- Cell

  - Cell(Form.Item, Field) 添加 `isLink` `arrowDirection` 属性 [630](https://github.com/taroify/taroify/pull/630) [@hbztd](https://github.com/hbztd)

- Icon [631](https://github.com/taroify/taroify/pull/631) [@Pilotager](https://github.com/Pilotager)
  - 图标：添加一个实底的 records 图标
  - 图标：添加一个实底的 contact 图标
  - 图标：添加一个实底的 discount 图标
  - 图标：添加一个实底的 completed 图标
  - 图标：添加一个实底的 description 图标
  - 图标：添加一个实底的 cash-back-record 图标
  - 图标：添加新的 user 图标
  - 图标：添加新的 notes 图标
  - 图标：添加新的 newspaper 图标
  - 图标：添加新的 list-switch 图标
  - 图标：添加新的 list-switching 图标
  - 图标：将 records 图标重命名为 records-o
  - 图标：将 contact 图标重命名为 contact-o
  - 图标：将 discount 图标重命名为 discount-o
  - 图标：将 completed 图标重命名为 completed-o
  - 图标：将 description 图标重命名为 description-o
  - 图标：将 cash-back-record 图标重命名为 cash-back-record-o

**Bug Fixes**

- Picker
  - 修复 siblingCount 属性未生效 [629](https://github.com/taroify/taroify/pull/629) [@hbztd](https://github.com/hbztd)

### v0.1.1-alpha.4

`2023-10-27`

**Feature**

- Cascader
  - 添加 `options` `fieldNames` `loadData`，支持指定数据源，自定义 options 结构中的字段，动态加载选项 [626](https://github.com/taroify/taroify/pull/626) [@hbztd](https://github.com/hbztd)
  - `useCascader` 添加缓存，提高性能 [626](https://github.com/taroify/taroify/pull/626) [@hbztd](https://github.com/hbztd)

**Bug Fixes**

- Swiper

  - 修复动态设置 SwiperItem 时可能出现页面异常 [626](https://github.com/taroify/taroify/pull/626) [@hbztd](https://github.com/hbztd)

- Filed
  - 修复单独使用 Filed 时，form 为空报错 [627](https://github.com/taroify/taroify/pull/627) [@hbztd](https://github.com/hbztd)

### v0.1.1-alpha.3

`2023-10-26`

**Feature**

- Form

  - Form 表单支持动态增减表单项 [622](https://github.com/taroify/taroify/pull/622) [@hbztd](https://github.com/hbztd)

- NoticeBar
  - 添加 `reset` 实例方法 [#623](https://github.com/taroify/taroify/pull/623) [@hbztd](https://github.com/hbztd)
  - `NoticeBarIcon` 和 `NoticeBarAction` onClick 阻止冒泡触发 NoticeBar Click 事件 [#623](https://github.com/taroify/taroify/pull/623) [@hbztd](https://github.com/hbztd)

**Bug Fixes**

- NoticeBar
  - 修复 `onReplay` 未触发 [#623](https://github.com/taroify/taroify/pull/623) [@hbztd](https://github.com/hbztd)

### v0.1.1-alpha.2

`2023-10-13`

**New Component**

- 新增 Signature 组件 [#618](https://github.com/taroify/taroify/pull/618) [@hbztd](https://github.com/hbztd)

**Feature**

- Space
  - 支持自定间距，添加 `fill` 属性 [#619](https://github.com/taroify/taroify/pull/619) [@hbztd](https://github.com/hbztd)
- List
  - 重构 List 实现。删除 `scrollTop`、`onLoading`，添加 `fixedHeight`、`immediateCheck`、`disabled`、`check` [#620](https://github.com/taroify/taroify/pull/620) [@hbztd](https://github.com/hbztd)

### v0.1.1-alpha.1

`2023-09-29`

**New Component**

- 新增 FloatingBubble 组件 [#610](https://github.com/taroify/taroify/pull/610) [@Pilotager](https://github.com/Pilotager)

**Feature**

- DropdownMenu
  - 新增 `onOpen` `onClose` `onOpened` `onClosed` 事件 [#612](https://github.com/taroify/taroify/pull/612) [@hbztd](https://github.com/hbztd)

**Bug Fixes**

- Input

  - 修复设置 readonly 属性的，原生 input dom 上是 disabled，会导致无法聚焦触发 onClick，电脑上 h5 调试打不开 Picker [#613](https://github.com/taroify/taroify/pull/613) [@hbztd](https://github.com/hbztd)

- Image

  - 修复 img onload 不一定触发问题 [#614](https://github.com/taroify/taroify/pull/614) [@hbztd](https://github.com/hbztd)

- Tabs
  - Tabs 设置 lazyRender 属性后，会加载当前，前后选项卡，和预期不符(延迟渲染未展示的选项卡) [#615](https://github.com/taroify/taroify/pull/615) [@hbztd](https://github.com/hbztd)

### v0.1.1-alpha.0

`2023-09-17`

**Feature**

- Button
  - 添加 `iconPosition` 属性 [#606](https://github.com/taroify/taroify/pull/606) [@Pilotager](https://github.com/Pilotager)
- Taro 版本升级为 v3.6.16 [#607](https://github.com/taroify/taroify/pull/607) [@Pilotager](https://github.com/Pilotager)

### v0.1.0-alpha.12

`2023-09-04`

**Bug Fixes**

- Button
  - 消除 `key` 警告 [#596](https://github.com/taroify/taroify/pull/596) [@rtmax0](https://github.com/rtmax0)
- Avatar
  - 修复群组使用 `size` 属性时最后一个元素尺寸问题 [#600](https://github.com/taroify/taroify/pull/600) [@Pilotager](https://github.com/Pilotager)
- Picker
  - 修复滚动时卡顿问题 [#601](https://github.com/taroify/taroify/pull/601) [@Pilotager](https://github.com/Pilotager)

### v0.1.0-alpha.11

`2023-08-21`

**Bug Fixes**

- IndexList
  - 修复微信小程序端点击事件报错 [#592](https://github.com/taroify/taroify/pull/592) [@450669540](https://github.com/450669540)

### v0.1.0-alpha.10

`2023-08-11`

**Feature**

- Stepper
  - 新增 `cursor` 属性 [#590](https://github.com/taroify/taroify/pull/590) [@Pilotager](https://github.com/Pilotager)

### v0.1.0-alpha.9

`2023-07-27`

**Feature**

- Pagination
  - 新增 `prevText`、`nextText`、`mode` 属性 [#588](https://github.com/taroify/taroify/pull/588) [@Pilotager](https://github.com/Pilotager)
- Navbar
  - 完善文档 [#587](https://github.com/taroify/taroify/pull/587)[@Pilotager](https://github.com/Pilotager)

### v0.1.0-alpha.8

`2023-07-19`

**Feature**

- Taro 版本升级为 v3.6.8 [#583](https://github.com/taroify/taroify/pull/583) [@Pilotager](https://github.com/Pilotager)
- Tab
  - 新增 swipeThreshold 属性 [#585](https://github.com/taroify/taroify/pull/585) [@Pilotager](https://github.com/Pilotager)

### v0.1.0-alpha.7

`2023-07-13`

**Feature**

- 统一了所有组件的主色调，所有组件均采用蓝色作为主色调 [#578](https://github.com/taroify/taroify/pull/578) [@Pilotager](https://github.com/Pilotager)
- 完善了主题变量的类型定义，`ConfigProviderThemeVars` 类型 [#579](https://github.com/taroify/taroify/pull/579) [@Pilotager](https://github.com/Pilotager)

### v0.1.0-alpha.6

`2023-07-09`

**New Component**

- 新增 RollingText 组件 [#574](https://github.com/taroify/taroify/pull/574) [@Pilotager](https://github.com/Pilotager)

**Bug Fixes**

- Tab
  - 修复 Tab 中 `ellipsis` 属性样式问题 [#576](https://github.com/taroify/taroify/pull/576)
- Collapse
  - 修复 Collapse 折叠面板无法全部关闭问题 [#576](https://github.com/taroify/taroify/pull/576)

### v0.1.0-alpha.5

`2023-07-06`

**Bug Fixes**

- Tag
  - 修复 Tag 组件圆角属性不生效问题 [#570](https://github.com/taroify/taroify/pull/570) [@Pilotager](https://github.com/Pilotager)
- NavBar
  - 修复 NavBar 层级导致的被覆盖问题 [#571](https://github.com/taroify/taroify/pull/571) [@Pilotager](https://github.com/Pilotager)
- Skeleton
  - 修改 Skeleton 文档问题 [#557](https://github.com/taroify/taroify/pull/557) [@Youmeng](https://github.com/youmengme)
- IndexList
  - 修复 IndexList 组件首次点击右侧快捷跳转问题 [#572](https://github.com/taroify/taroify/pull/572) [@Pilotager](https://github.com/Pilotager)
- Form
  - Input 校验未通过时，placeholder 颜色优化 [#503](https://github.com/taroify/taroify/issues/503)

### v0.1.0-alpha.4

`2023-06-30`

**New Component**

- 新增 BackTop 组件 [#568](https://github.com/taroify/taroify/pull/568) [@Pilotager](https://github.com/Pilotager)

### v0.1.0-alpha.3

`2023-06-26`

**New Component**

- 新增 FloatingPanel 组件 [#564](https://github.com/taroify/taroify/pull/564) [@Pilotager](https://github.com/Pilotager)

### v0.1.0-alpha.1

`2022-06-26`

**Bug Fixes**

- Icons
  - 修复在飞书小程序图标不显示的问题 [#511](https://github.com/taroify/taroify/issues/511) [#519](https://github.com/taroify/taroify/issues/519) [#520](https://github.com/taroify/taroify/pull/520)

### v0.1.0-alpha.0

`2022-06-21`

**Feature**

- 更新 @tarojs/\* 版本至 3.4.10 [#a2864f3](https://github.com/taroify/taroify/commit/a2864f319b0eddde8006444a6a41be3a0e78b07a) [#9a2d5eb](https://github.com/taroify/taroify/commit/9a2d5ebc19d466902952d98ab749eaa7613ce1ff) [#b722781](https://github.com/taroify/taroify/commit/b722781d3a58a294d43065aea8e6bf12691d1fc4)

**Bug Fixes**

- 修复 safe-area.scss 样式未导入的问题 [#493](https://github.com/taroify/taroify/pull/493) [@peng](https://github.com/pengcu)
- SwipeCell
  - 修复 catch move 的问题 [#495](https://github.com/taroify/taroify/pull/495) [@Kyle](https://github.com/jhxxs)
- Loading
  - 修复 SCSS 样式编译警告的问题 [#497](https://github.com/taroify/taroify/pull/497) [@Fen QIN](https://github.com/umcai)
- Button
  - 更新 shape 属性文档不一致的问题 [#512](https://github.com/taroify/taroify/pull/512) [@Kuntang Huang](https://github.com/kunkuntang)

### v0.0.29-alpha.9

`2022-05-30`

**Bug Fixes**

- Cascader
  - 修复没用触发 onSelect 事件的问题 [#484](https://github.com/taroify/taroify/pull/484)
- Avatar
  - 修复没用按需加载 Image 样式的问题 [#480](https://github.com/taroify/taroify/pull/480) [@ShibaPipi](https://github.com/ShibaPipi)

### v0.0.29-alpha.8

`2022-04-27`

**Feature**

- CSS Vars
  - 优化全部组件的 CSS Vars 文档 [#392](https://github.com/taroify/taroify/issues/392)

**Bug Fixes**

- Swiper
  - 修复切换存在白屏的问题 [#472](https://github.com/taroify/taroify/issues/472) [#474](https://github.com/taroify/taroify/pull/474) [@Laotree](https://github.com/Laotree)

### v0.0.29-alpha.7

`2022-04-12`

**Bug Fixes**

- Swiper
  - 修复 targetOffset 为 0 的问题 [#461](https://github.com/taroify/taroify/pull/461)
- Tabs
  - 修复开启滑动，无法滚动页面的问题 [#463](https://github.com/taroify/taroify/pull/463)

### v0.0.29-alpha.6

`2022-04-09`

**Breaking Changes**

- Search
  - 将 shape="round" 属性重命名为 shape="rounded" [#444](https://github.com/taroify/taroify/issues/444) [#458](https://github.com/taroify/taroify/pull/458)
- Dialog
  - 将 shape="round" 属性重命名为 shape="rounded" [#456](https://github.com/taroify/taroify/issues/456) [#457](https://github.com/taroify/taroify/pull/457)

### v0.0.29-alpha.5

`2022-04-06`

**Feature**

- Progress
  - 导出 ProgressProps 类型 [#437](https://github.com/taroify/taroify/pull/437) [@bingtsingw](https://github.com/bingtsingw)

**Bug Fixes**

- NoticeBar
  - 修复 rect 为 undefined [#438](https://github.com/taroify/taroify/pull/438)

**Breaking Changes**

- PasswordInput
  - 删除 error 属性 [#440](https://github.com/taroify/taroify/issues/440)
  - 将 info 属性重命名为 feedback [#440](https://github.com/taroify/taroify/issues/440)
- Search
  - 将 shape="round" 属性重命名为 shape="circular" [#444](https://github.com/taroify/taroify/issues/444)
- Stepper
  - 将 shape="round" 属性重命名为 shape="circular" [#449](https://github.com/taroify/taroify/issues/449)

### v0.0.29-alpha.4

`2022-04-01`

**Bug Fixes**

- DropdownMenu
  - 修复弹出抖动两次的问题 [#426](https://github.com/taroify/taroify/issues/426) [#436](https://github.com/taroify/taroify/pull/436)

### v0.0.29-alpha.3

`2022-03-29`

**Feature**

- Textarea
  - 导出 TextareaProps 类型 [#425](https://github.com/taroify/taroify/pull/425) [@bingtsingw](https://github.com/bingtsingw)

**Bug Fixes**

- Popup
  - 修复弹出抖动两次的问题 [#404](https://github.com/taroify/taroify/issues/404) [#431](https://github.com/taroify/taroify/pull/431)
- styles
  - 删除重复 $text-link-color 变量 [#427](https://github.com/taroify/taroify/pull/427) [@Yorksh1re](https://github.com/Yorksh1re)

### v0.0.29-alpha.2

`2022-03-23`

**Bug Fixes**

- Button
  - 修复微信端不能编译 SCSS 样式的问题 [#422](https://github.com/taroify/taroify/issues/422) [#423](https://github.com/taroify/taroify/pull/423)

### v0.0.29-alpha.1

`2022-03-22`

**Bug Fixes**

- Tabbar
  - 修复 FixedView 组件样式未导入的问题 [#419](https://github.com/taroify/taroify/pull/419)
  - 修复 placeholder=\{false} 无作用的问题 [#420](https://github.com/taroify/taroify/pull/420)
- Navbar
  - 修复 FixedView 组件样式未导入的问题 [#419](https://github.com/taroify/taroify/pull/419)
  - 修复 placeholder=\{false} 无作用的问题 [#420](https://github.com/taroify/taroify/pull/420)
- ActionBar
  - 修复 placeholder=\{false} 无作用的问题 [#420](https://github.com/taroify/taroify/pull/420)

### v0.0.29-alpha.0

`2022-03-22`

**New Component**

- 新增 Button.Group 组件 [#414](https://github.com/taroify/taroify/issues/414) [#416](https://github.com/taroify/taroify/pull/416)
- 新增 FixedView 组件 [#413](https://github.com/taroify/taroify/issues/413) [#417](https://github.com/taroify/taroify/pull/417)

**Feature**

- Tabbar
  - 新增 safeArea 属性 [#417](https://github.com/taroify/taroify/pull/417) [#418](https://github.com/taroify/taroify/pull/418)
- Navbar
  - 新增 safeArea 属性 [#417](https://github.com/taroify/taroify/pull/417) [#418](https://github.com/taroify/taroify/pull/418)
- ActionBar
  - 新增 safeArea 属性 [#417](https://github.com/taroify/taroify/pull/417) [#418](https://github.com/taroify/taroify/pull/418)

### v0.0.28-alpha.1

`2022-03-16`

**Bug Fixes**

- Countdown
  - 修复监听 onChange 事件时，获得 value 不正确的问题 [#403](https://github.com/taroify/taroify/pull/403)
- List
  - 修复重复加载（onLoad）的问题 [#406](https://github.com/taroify/taroify/pull/406)

### v0.0.28-alpha.0

`2022-03-11`

**New Component**

- 新增 Timeline 组件 [#395](https://github.com/taroify/taroify/pull/395) [@coderYarn](https://github.com/coderYarn)

**Bug Fixes**

- Form
  - 修复使用校验函数返回值处理错误的问题 [#400](https://github.com/taroify/taroify/pull/400)
- Picker
  - 修复滑动结束后不更新列值的问题 [#401](https://github.com/taroify/taroify/pull/401)

### v0.0.27-alpha.6

`2022-02-28`

**Feature**

- List
  - 新增 loading, hasMore 函数返回值类型 [#385](https://github.com/taroify/taroify/pull/385)

**Bug Fixes**

- @taroify/core/index.scss
  - 修复没有导入 ButtonBase 组件样式的问题 [#389](https://github.com/taroify/taroify/pull/389)
- List
  - 修复 loading 赋值的问题 [#390](https://github.com/taroify/taroify/pull/390)
- DropdownMenu
  - 修复当初始化页面滑动时，获得 rect 为 undefined 的问题 [#391](https://github.com/taroify/taroify/pull/391)

### v0.0.27-alpha.5

`2022-02-22`

**Bug Fixes**

- ancestorCustomWrapper
  - 修复嵌套在 Block 组件内不能查询元素的问题 [#370](https://github.com/taroify/taroify/pull/370) [@ThomasTrainset](https://github.com/xdoer)
- Image
  - 修复 onLoad, onError 未实现的问题 [#372](https://github.com/taroify/taroify/pull/372) [@yifeishu-com](https://github.com/yifeishu-com)
- DatetimePicker
  - 修复快速滑动时，快速点击 onConfirm 获取值不正确问题 [#373](https://github.com/taroify/taroify/issues/373) [#380](https://github.com/taroify/taroify/pull/380)
- Picker
  - 修复 options 为空时，导致 valueOptions 为 undefined 的问题 [#375](https://github.com/taroify/taroify/issues/375) [#378](https://github.com/taroify/taroify/pull/378)
- ActionBar.IconButton
  - 修复 badge 导入路径的问题 [#376](https://github.com/taroify/taroify/issues/376) [#377](https://github.com/taroify/taroify/pull/377)

### v0.0.27-alpha.4

`2022-02-18`

**Bug Fixes**

- useForm
  - 修复 defaultValues 被覆盖的问题 [#368](https://github.com/taroify/taroify/pull/368)

### v0.0.27-alpha.3

`2022-02-18`

### v0.0.27-alpha.2

`2022-02-17`

**Bug Fixes**

- useForm
  - 修复调用重置（reset）时，获取 onValuesChange 事件的 allValues 形参不正确的问题 [#367](https://github.com/taroify/taroify/pull/367)

### v0.0.27-alpha.1

`2022-02-17`

**Feature**

- ellipsis
  - 合并 multi-ellipsis 为 ellipsis [#343](https://github.com/taroify/taroify/pull/343) [@yifeishu-com](https://github.com/yifeishu-com)
- Docs
  - 完善开发指南 [#347](https://github.com/taroify/taroify/pull/347) [@Yang](https://github.com/programmer-yang)
- addUnitPx
  - 新增 rpx 转换 px 的支持 [#361](https://github.com/taroify/taroify/pull/361) [@BluesCurry](https://github.com/bluescurry)
- SwipeCell
  - 新增 beforeClose 方法 [#363](https://github.com/taroify/taroify/pull/363)

**Bug Fixes**

- useForm
  - 修复设置 values 无反应的问题 [#356](https://github.com/taroify/taroify/pull/356)
- Form
  - 修复通过 ref 调用 reset() 不能更新视图的问题 [#358](https://github.com/taroify/taroify/pull/358)
  - 修复通过 ref 调用 reset() 不能触发 onReset 事件的问题 [#358](https://github.com/taroify/taroify/pull/358)
- SwipeCell
  - 修复点击滑动按钮不能自动关闭的问题 [#363](https://github.com/taroify/taroify/pull/363)

### v0.0.27-alpha.0

`2022-02-11`

**New Component**

- 新增 @taroify/commerce 包 [#84](https://github.com/taroify/taroify/issues/84)
- 新增 ActionBar 组件 [#341](https://github.com/taroify/taroify/pull/341)

**Bug Fixes**

- Tabs
  - 修复切换标签页会触发两次 onChange 事件的问题 [#336](https://github.com/taroify/taroify/issues/336) [#339](https://github.com/taroify/taroify/pull/339)
- Skeleton
  - 修复设置动画无效果的问题 [#334](https://github.com/taroify/taroify/pull/334)

### v0.0.26-alpha.6

`2022-02-08`

**Bug Fixes**

- Badge
  - 修复独立模式 fixed 的问题 [#331](https://github.com/taroify/taroify/pull/331)
- Button
  - 修复 loading 为 false 时，不能显示图标的问题 [#332](https://github.com/taroify/taroify/pull/332) [@yifeishu-com](https://github.com/yifeishu-com)

### v0.0.26-alpha.5

`2022-01-28`

**Feature**

- ShareSheet.Option
  - 新增 value 属性 [#328](https://github.com/taroify/taroify/pull/328)

### v0.0.26-alpha.4

`2022-01-28`

**Bug Fixes**

- Stepper
  - 修复获取手动输入值不正确的问题 [#326](https://github.com/taroify/taroify/pull/326)
- Popup
  - 修复固定定位（fixed position）和动画（translate3d）联用的问题 [#327](https://github.com/taroify/taroify/pull/327)

### v0.0.26-alpha.3

`2022-01-28`

**Bug Fixes**

- Input
  - 修复字号（font-size）、行高（line-height）继承父元素样式的问题 [#325](https://github.com/taroify/taroify/pull/325)
  - 修复清除按钮点击无效果的问题 [#320](https://github.com/taroify/taroify/pull/320)
- Textarea
  - 修复字号（font-size）、行高（line-height）继承父元素样式的问题 [#324](https://github.com/taroify/taroify/pull/324)
- Form
  - 修复非表单环境下设置空字符串的问题 [#323](https://github.com/taroify/taroify/pull/323)
  - 修复嵌套 Input 组件不能自定义颜色的问题 [#323](https://github.com/taroify/taroify/pull/323)

### v0.0.26-alpha.2

`2022-01-27`

**Bug Fixes**

- ShareSheet
  - 修复 image 样式被覆盖的问题 [#316](https://github.com/taroify/taroify/pull/316)
- Textarea
  - 修复设置 value 无效的问题 [#315](https://github.com/taroify/taroify/pull/315)

### v0.0.26-alpha.1

`2022-01-26`

**Feature**

- Form
  - 补全 FormInstance 类型 [#311](https://github.com/taroify/taroify/pull/311)

**Bug Fixes**

- useHeight
  - 修复 rect 为 undefined 的问题 [#312](https://github.com/taroify/taroify/pull/312)

### v0.0.26-alpha.0

`2022-01-26`

**New Component**

- 新增 Textarea 组件 [#297](https://github.com/taroify/taroify/pull/297)

**Feature**

- Field
  - 优化 label, feedback 属性 [#310](https://github.com/taroify/taroify/issues/310) [#299](https://github.com/taroify/taroify/pull/299) [@coderYarn](https://github.com/coderYarn)

**Bug Fixes**

- Avatar
  - 修复 className 无法传入的问题 [#308](https://github.com/taroify/taroify/pull/308) [@coderYarn](https://github.com/coderYarn)
- Input
  - 修复独立于 Form 组件，无法赋值的问题 [#298](https://github.com/taroify/taroify/pull/298)
- Button
  - 修复加载（loading）状态下还可以提交表单的问题 [#306](https://github.com/taroify/taroify/pull/306)
- Grid.Item
  - 修复 badge 字号样式问题 [#309](https://github.com/taroify/taroify/pull/309)
- Tabbar.Item
  - 修复 badge 字号样式问题 [#309](https://github.com/taroify/taroify/pull/309)

### v0.0.25-alpha.1

`2022-01-24`

**Feature**

- IndexList
  - 新增 stickyOffsetTop 字符串（string）类型 [#287](https://github.com/taroify/taroify/pull/287) [@bluescurry](https://github.com/bluescurry)
- ActionSheet
  - 新增按钮（Button）相关属性 [#292](https://github.com/taroify/taroify/pull/292)

**Bug Fixes**

- Picker
  - 修复当子元素（children）改变时，索引（index）未更新的问题 [#289](https://github.com/taroify/taroify/pull/289)

### v0.0.25-alpha.0

`2022-01-20`

**New Component**

- 新增 Avatar 组件 [#233](https://github.com/taroify/taroify/issues/233) [#248](https://github.com/taroify/taroify/pull/248) [@coderYarn](https://github.com/coderYarn)
- 新增 AreaPicker 组件 [#77](https://github.com/taroify/taroify/issues/77) [#264](https://github.com/taroify/taroify/pull/272) [#264](https://github.com/taroify/taroify/pull/272)

**Feature**

- IndexList.Anchor
  - 新增全部属性 [#282](https://github.com/taroify/taroify/pull/282) [@bluescurry](https://github.com/bluescurry)
- Picker
  - 新增 onChange 事件返回 column 对象 [#269](https://github.com/taroify/taroify/blob/1b80d78ed8bd0150b83c1485a3a5b692975ce7d9/packages/core/src/picker/picker-columns.tsx#L37)
- SwipeCell
  - 优化微信小程序端的滑动动画效果 [#265](https://github.com/taroify/taroify/pull/265)

**Bug Fixes**

- Toast
  - 修复页面切换返回后不能打开的问题 [#283](https://github.com/taroify/taroify/issues/283) [#284](https://github.com/taroify/taroify/pull/284)
- Notify
  - 修复页面切换返回后不能打开的问题 [#283](https://github.com/taroify/taroify/issues/283) [#284](https://github.com/taroify/taroify/pull/284)
- Dialog
  - 修复页面切换返回后不能打开的问题 [#283](https://github.com/taroify/taroify/issues/283) [#284](https://github.com/taroify/taroify/pull/284)
- Empty
  - 修复内部图片样式被覆盖的问题 [#268](https://github.com/taroify/taroify/issues/268) [#271](https://github.com/taroify/taroify/pull/271)

### v0.0.24-alpha.1

`2022-01-13`

**Feature**

- Form
  - 新增 onValuesChange 属性 [#258](https://github.com/taroify/taroify/issues/258) [#261](https://github.com/taroify/taroify/pull/261)

**Bug Fixes**

- Toast
  - 修复通过命令式调用重复打开的问题 [#259](https://github.com/taroify/taroify/issues/259) [#260](https://github.com/taroify/taroify/pull/260)
- Notify
  - 修复通过命令式调用重复打开的问题 [#259](https://github.com/taroify/taroify/issues/259) [#260](https://github.com/taroify/taroify/pull/260)
- Dialog
  - 修复通过命令式调用重复打开的问题 [#259](https://github.com/taroify/taroify/issues/259) [#260](https://github.com/taroify/taroify/pull/260)

### v0.0.24-alpha.0

`2022-01-12`

**Feature**

- Uploader
  - 新增 removable 属性 [#243](https://github.com/taroify/taroify/issues/243) [#256](https://github.com/taroify/taroify/pull/256)
- Picker
  - 监听返回完整的选项（Option）对象 [#239](https://github.com/taroify/taroify/issues/239) [#242](https://github.com/taroify/taroify/pull/242)

**Bug Fixes**

- Style
  - 修复 multi-ellipsis 无法省略的问题 [#245](https://github.com/taroify/taroify/pull/245)
- DatetimePicker
  - 修复设置 defaultValue 无效的问题 [#238](https://github.com/taroify/taroify/pull/238) [@Brain777777](https://github.com/Brain777777)
  - 修复 2 月存在 31 天的问题 [#240](https://github.com/taroify/taroify/issues/240) [#254](https://github.com/taroify/taroify/pull/254)

### v0.0.23-alpha.1

`2022-01-04`

**Bug Fixes**

- Field
  - 修复嵌套 Input 组件不能赋值 value 的问题 [#235](https://github.com/taroify/taroify/issues/235)

### v0.0.23-alpha.0

`2022-01-04`

**New Component**

- 新增 Space 组件 [#228](https://github.com/taroify/taroify/pull/228) [@coderYarn](https://github.com/coderYarn)

**Feature**

- ActionSheet.Action
  - 新增 value 属性 [#229](https://github.com/taroify/taroify/pull/229) [@coderYarn](https://github.com/coderYarn)

**Bug Fixes**

- Checkbox.Group
  - 修复设置 value 为空数组时，Checkbox 组件的 checked 不为 false 的问题 [#231](https://github.com/taroify/taroify/pull/231)

### v0.0.22-alpha.1

`2022-01-01`

**Feature**

- DatetimePicker
  - 新增 date-minute 类型（年月日时分） [#211](https://github.com/taroify/taroify/issues/211) [#227](https://github.com/taroify/taroify/pull/227)

**Bug Fixes**

- Input
  - 修复 readonly 状态下 placeholder 颜色为 --text-color-3 的问题 [#218](https://github.com/taroify/taroify/pull/218)

### v0.0.22-alpha.0

`2022-01-01`

**New Component**

- 新增 Form 组件 [#118](https://github.com/taroify/taroify/issues/118) [#224](https://github.com/taroify/taroify/pull/224)

**Feature**

- Cell
  - 设置 icon 和 rightIcon 属性时，仅为图标组件添加单元格图标样式 [#214](https://github.com/taroify/taroify/issues/214) [#225](https://github.com/taroify/taroify/pull/225)
- Field
  - 新增 feedbackAlign 属性 [#224](https://github.com/taroify/taroify/pull/224)
  - 新增 feedbackStatus 属性 [#224](https://github.com/taroify/taroify/pull/224)
- Search
  - 新增 inputColor 属性 [#224](https://github.com/taroify/taroify/pull/224)
  - 新增 feedbackAlign 属性 [#224](https://github.com/taroify/taroify/pull/224)
  - 新增 feedbackStatus 属性 [#224](https://github.com/taroify/taroify/pull/224)

**Breaking Changes**

- Field
  - 删除 Input 属性 [#224](https://github.com/taroify/taroify/pull/224)
  - 将 message 属性重命名为 feedback [#224](https://github.com/taroify/taroify/pull/224)
- Search
  - 将 message 属性重命名为 feedback [#224](https://github.com/taroify/taroify/pull/224)

**Bug Fixes**

- Tabs
  - 修复 swipeable 不支持 lazyRender 的问题 [#218](https://github.com/taroify/taroify/pull/218)

### v0.0.21-alpha.1

`2021-12-22`

**Feature**

- Countdown
  - 新增单符号（D, H, m, s）格式 [#206](https://github.com/taroify/taroify/issues/206) [#208](https://github.com/taroify/taroify/pull/208)

**Bug Fixes**

- Countdown
  - 修复 value 无法更新的问题 [#205](https://github.com/taroify/taroify/issues/205) [#208](https://github.com/taroify/taroify/pull/208)
- SafeArea
  - 修复 ios11 兼容性 constant(safe-area-inset-\*) 的问题 [#199](https://github.com/taroify/taroify/pull/199) [@Brain777777](https://github.com/Brain777777)

### v0.0.21-alpha.0

`2021-12-16`

**New Component**

- 新增 SafeArea 组件 [#195](https://github.com/taroify/taroify/pull/195)

**Feature**

- Badge
  - 新增 position 属性 [#196](https://github.com/taroify/taroify/pull/196)
- Button
  - 新增 loading.size 属性 [#192](https://github.com/taroify/taroify/pull/192) [@zjwshisb](https://github.com/zjwshisb)
- ShareSheet.Option
  - 新增 openType 属性 [#194](https://github.com/taroify/taroify/pull/194) [@kunkuntang](https://github.com/kunkuntang)

**Bug Fixes**

- Badge
  - 修复 content toString 的问题 [#196](https://github.com/taroify/taroify/pull/196)

### v0.0.20-alpha.5

`2021-12-15`

**Bug Fixes**

- DatetimePicker
  - 修复 clampDate 和 useValue 的问题 [#190](https://github.com/taroify/taroify/pull/190)

### v0.0.20-alpha.4

`2021-12-15`

**Feature**

- SwipeCell
  - 新增 defaultOpen 和 open 属性 [#172](https://github.com/taroify/taroify/issues/172) [#186](https://github.com/taroify/taroify/pull/186)

**Bug Fixes**

- Badge
  - 修复 content=\{0} 时，直接渲染 0 的问题 [#184](https://github.com/taroify/taroify/pull/184) [@zjwshisb](https://github.com/zjwshisb)
- Field
  - 修复 H5 设置 inputAlign 为 right 无效的问题 [#182](https://github.com/taroify/taroify/pull/182) [@zjwshisb](https://github.com/zjwshisb)
- Picker
  - 修复监听 onChange 事件为旧值的问题 [#189](https://github.com/taroify/taroify/pull/189)
- DatetimePicker
  - 修复默认值为 undefined 的问题 [#188](https://github.com/taroify/taroify/pull/188)

**Breaking Changes**

- Countdown
  - 将 useCountDown() 和 CountDown 合并在一起 [#176](https://github.com/taroify/taroify/pull/176) [@Brain777777](https://github.com/Brain777777)
  - 将 CountDown 重命名为 Countdown [#179](https://github.com/taroify/taroify/pull/179)
  - 将 current 属性重命名为 value [#179](https://github.com/taroify/taroify/pull/179)
  - 将 millisecond 属性重命名为 interval=\{1} [#179](https://github.com/taroify/taroify/pull/179)
  - 将 onFinish 事件重命名为 onComplete [#179](https://github.com/taroify/taroify/pull/179)

### v0.0.20-alpha.3

`2021-12-11`

**Feature**

- Styles
  - 新增赋值 $hd 默认变量 [#173](https://github.com/taroify/taroify/issues/173) [#174](https://github.com/taroify/taroify/pull/174)

### v0.0.20-alpha.2

`2021-12-09`

**Bug Fixes**

- Pagination
  - 修复页码出现负数的问题 [#171](https://github.com/taroify/taroify/pull/171) [@zjwshisb](https://github.com/zjwshisb)

### v0.0.20-alpha.1

`2021-12-09`

**Bug Fixes**

- Dialog
  - 修复点击确认按钮导致自动关闭 [#170](https://github.com/taroify/taroify/issues/170) [#169](https://github.com/taroify/taroify/pull/169)

### v0.0.20-alpha.0

`2021-12-08`

**Feature**

- Popup
  - 新增 defaultOpen 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Toast
  - 新增 defaultOpen 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Cascader
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Calendar
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Checkbox
  - 新增 defaultChecked 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- DatetimePicker
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Picker
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Radio
  - 新增 defaultChecked 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Rate
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Slider
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Stepper
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Switch
  - 新增 defaultChecked 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Uploader
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- ActionSheet
  - 新增 defaultOpen 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Dialog
  - 新增 defaultOpen 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- DropdownMenu
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Notify
  - 新增 defaultOpen 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Backdrop
  - 新增 defaultOpen 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- ShareSheet
  - 新增 defaultOpen 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Collapse
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Collapse
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Steps
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Swiper
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Sidebar
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Tabs
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- Tabbar
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)
- TreeSelect
  - 新增 defaultValue 属性 [#86](https://github.com/taroify/taroify/issues/86) [#165](https://github.com/taroify/taroify/pull/165)

### v0.0.19-alpha.3

`2021-12-04`

**Feature**

- NavBar
  - 新增 fixed & placeholder 属性 [#159](https://github.com/taroify/taroify/pull/159)

**Bug Fixes**

- multi-ellipsis
  - 修复多行文本不省略的问题 [#160](https://github.com/taroify/taroify/pull/160)

### v0.0.19-alpha.2

`2021-12-03`

**Bug Fixes**

- PullRefresh
  - 修复嵌套在 CustomWrapper 中不能触发 onRefresh 的问题 [#156](https://github.com/taroify/taroify/pull/156)
- NumberKeyboard
  - 修复 Transition 组件未嵌套在真实元素上，而不能隐藏的的问题 [#154](https://github.com/taroify/taroify/pull/154)

**Breaking Changes**

- PasswordInput
  - 将 focused 属性重命名为 focus 属性 [#155](https://github.com/taroify/taroify/pull/155)

### v0.0.19-alpha.1

`2021-12-02`

**Feature**

- Transition
  - 新增 appear 、mountOnEnter 属性 [#148](https://github.com/taroify/taroify/pull/148)

**Bug Fixes**

- createNodesRef
  - 修复获得嵌套在 CustomWrapper 内的 NodesRef 为 undefined 的问题 [#143](https://github.com/taroify/taroify/pull/143) [@wowhy](https://github.com/wowhy)
- Circle
  - 修复重复获得 CanvasContext 导致无法初始化渲染的问题 [#145](https://github.com/taroify/taroify/issues/145) [#146](https://github.com/taroify/taroify/issues/146)
- Uploader
  - 修复在多选（multiple）模式下，不能显示上传的本地图片的问题 [#152](https://github.com/taroify/taroify/issues/152) [#151](https://github.com/taroify/taroify/pull/151)

**Performance**

- Backdrop
  - 使用 Transition 组件代替 css transition [#150](https://github.com/taroify/taroify/issues/150) [#149](https://github.com/taroify/taroify/issues/149)

### v0.0.19-alpha.0

`2021-11-26`

**Refactor**

- Swiper
  - 重构 Swiper 组件，增加 value 属性 [#120](https://github.com/taroify/taroify/issues/120) [#137](https://github.com/taroify/taroify/pull/137)

**Bug Fixes**

- Circle
  - 修复在低版本的小程序中不渲染的问题 [#139](https://github.com/taroify/taroify/issues/139) [#140](https://github.com/taroify/taroify/pull/140)

### v0.0.18-alpha.9

`2021-11-22`

**Feature**

- Icons
  - 修复在采用导入全部样式的方式时，存在图标样式被覆盖的问题 [#134](https://github.com/taroify/taroify/issues/134) [#135](https://github.com/taroify/taroify/issues/135)

### v0.0.18-alpha.8

`2021-11-19`

**Feature**

- Empty
  - 新增 children 属性 [#131](https://github.com/taroify/taroify/issues/131) [#132](https://github.com/taroify/taroify/pull/132)

### v0.0.18-alpha.7

`2021-11-19`

### v0.0.18-alpha.6

`2021-11-19`

**Bug Fixes**

- PullRefresh
  - 修复在小程序中 overflow 超出 100% 时，不能滚动下拉的问题 [#129](https://github.com/taroify/taroify/issues/129) [#130](https://github.com/taroify/taroify/issues/130)

### v0.0.18-alpha.5

`2021-11-17`

**Bug Fixes**

- Circle
  - 修复在 useReady 里获得 CanvasNode 为 undefined 的问题 [#127](https://github.com/taroify/taroify/issues/127) [#128](https://github.com/taroify/taroify/issues/128)

### v0.0.18-alpha.4

`2021-11-17`

**Bug Fixes**

- Field
  - 修复 calc(var(--padding-xs, #\{$padding-xs}) \* -1) 的问题 [#121](https://github.com/taroify/taroify/issues/121) [#126](https://github.com/taroify/taroify/issues/126)
- TreeSelect
  - 修复 calc(var(--padding-xs, #\{$padding-xs}) \* -1) 的问题 [#122](https://github.com/taroify/taroify/issues/122) [#124](https://github.com/taroify/taroify/issues/124)
- Slider
  - 修复 calc(var(--padding-xs, #\{$padding-xs}) \* -1) 的问题 [#123](https://github.com/taroify/taroify/issues/123) [#125](https://github.com/taroify/taroify/issues/125)

### v0.0.18-alpha.3

`2021-11-15`

**Feature**

- Uploader
  - 补全 Uploader.Image 属性 [#113](https://github.com/taroify/taroify/issues/113) [#117](https://github.com/taroify/taroify/pull/117)
- Icons
  - 补全 Icons 属性 [#113](https://github.com/taroify/taroify/issues/113) [#115](https://github.com/taroify/taroify/pull/115)

**Bug Fixes**

- List
  - 修复重复执行 onLoad 事件的问题 [#112](https://github.com/taroify/taroify/issues/112) [#116](https://github.com/taroify/taroify/pull/116)

### v0.0.18-alpha.2

`2021-11-14`

**Performance**

- 优化 Demo 示例项目打包体积 [#83](https://github.com/taroify/taroify/pull/83) [@Ace Han](https://github.com/ace-han)

**Bug Fixes**

- Flex
  - 修复 Flex.Item 缺少 children 属性的问题 [#110](https://github.com/taroify/taroify/issues/110) [#111](https://github.com/taroify/taroify/pull/111)

### v0.0.18-alpha.1

`2021-11-14`

**Feature**

- 新增 @taroify/hooks 包 [#109](https://github.com/taroify/taroify/issues/109)

### v0.0.18-alpha.0

`2021-11-14`

**New Component**

- 新增 Cascader 组件 [#96](https://github.com/taroify/taroify/issues/96) [#106](https://github.com/taroify/taroify/pull/106)

**Bug Fixes**

- Transition
  - 修复设置 in 属性默认为 true 时不执行动画的问题 [#100](https://github.com/taroify/taroify/issues/100) [#101](https://github.com/taroify/taroify/issues/101)
- Field
  - 修复 maxlength 默认为 -1 时，导致数字或整数无法输入的问题 [#99](https://github.com/taroify/taroify/issues/99) [#102](https://github.com/taroify/taroify/issues/102) [#105](https://github.com/taroify/taroify/pull/105)

**Breaking Changes**

- Flex
  - 将 Row & Col 合并成 Flex 组件 [#103](https://github.com/taroify/taroify/issues/103) [#104](https://github.com/taroify/taroify/pull/104)

### v0.0.17-alpha.4

`2021-11-11`

**Bug Fixes**

- Sticky
  - 删除多余的 `console.log()` 打印 [#97](https://github.com/taroify/taroify/issues/97) [#98](https://github.com/taroify/taroify/pull/98)

### v0.0.17-alpha.3

`2021-11-11`

**Bug Fixes**

- Dialog
  - 修复在未按需加载内部使用 Button 组件样式的问题 [#90](https://github.com/taroify/taroify/issues/90) [#93](https://github.com/taroify/taroify/pull/93)
- Collapse
  - 修复因继承自 StandardProps 接口，而导致 value 为 undefined 的问题 [#89](https://github.com/taroify/taroify/issues/89) [#94](https://github.com/taroify/taroify/pull/94)

**Breaking Changes**

- PullRefresh
  - 将判断 reachTop 的逻辑移动到组件外部 [#92](https://github.com/taroify/taroify/issues/92) [#95](https://github.com/taroify/taroify/pull/95)

### v0.0.17-alpha.2

`2021-11-05`

**Feature**

- Toast
  - 新增命令式调用 `Toast.close()`、`Toast.setDefaultOptions()`、`Toast.resetDefaultOptions()` 方法 [#78](https://github.com/taroify/taroify/issues/78)
- Notify
  - 新增命令式调用 `Notify.close()`、`Notify.setDefaultOptions()`、`Notify.resetDefaultOptions()` 方法 [#71](https://github.com/taroify/taroify/issues/71)
- Dialog
  - 新增命令式调用 `Dialog.close()`、`Dialog.setDefaultOptions()`、`Dialog.resetDefaultOptions()` 方法 [#71](https://github.com/taroify/taroify/issues/71)

**Bug Fixes**

- Image
  - 修复因 `display: none` 导致重复加载的问题 [#79](https://github.com/taroify/taroify/pull/79) [@Pingren](https://github.com/Pingren)
- ShareSheet
  - 修复 ShareSheet.Option 在小程序上存在垂直展示的问题 [#82](https://github.com/taroify/taroify/issues/82)
- PullRefresh
  - 修复在小程序真机下拉刷新时存在卡帧的问题 [#74](https://github.com/taroify/taroify/issues/74)

### v0.0.17-alpha.1

`2021-11-04`

**Bug Fixes**

- Stepper
  - 修复第一次点击无反应的问题 [#76](https://github.com/taroify/taroify/issues/76)

### v0.0.17-alpha.0

`2021-11-03`

**Feature**

- Search
  - 新增 focus 属性 [#73](https://github.com/taroify/taroify/issues/73)
- Toast
  - 新增命令式调用 `Toast.open()`、`Toast.loading()`、`Toast.success()`、`Toast.fail()` 方法 [#71](https://github.com/taroify/taroify/issues/71) [#69](https://github.com/taroify/taroify/issues/69)
- Notify
  - 新增命令式调用 `Notify.open()` 方法 [#71](https://github.com/taroify/taroify/issues/71) [#69](https://github.com/taroify/taroify/issues/69)
- Dialog
  - 新增命令式调用 `Dialog.open()`、`Dialog.alert()`、`Dialog.confirm()` 方法 [#71](https://github.com/taroify/taroify/issues/71) [#69](https://github.com/taroify/taroify/issues/69)

**Bug Fixes**

- DatetimePicker
  - 修复在改变 value 导致缺少 columns 的问题 [#75](https://github.com/taroify/taroify/issues/75)
- Popup
  - 修复在编译打包后因背景板（Backdrop）叠加显示在依赖 Popup 组件之上的问题 [#72](https://github.com/taroify/taroify/issues/72)
- Search
  - 修复设置 autoFocus 属性无效的问题 [#73](https://github.com/taroify/taroify/issues/73)

### v0.0.16-alpha.3

`2021-11-01`

**Bug Fixes**

- List
  - 修复因 children 改变未触发 onLoad 事件的问题 [#70](https://github.com/taroify/taroify/issues/70)

### v0.0.16-alpha.2

`2021-11-01`

**Bug Fixes**

- Sticky
  - 修复因 offsetTop, offsetBottom 未显示解构而导致的设置属性错误的问题 [#68](https://github.com/taroify/taroify/issues/68)

### v0.0.16-alpha.1

`2021-11-01`

**Bug Fixes**

- 修复`@taroify/icons`样式问题 [#67](https://github.com/taroify/taroify/issues/67)

### v0.0.16-alpha.0

`2021-10-31`

**New Component**

- 新增 Calendar 组件 [#66](https://github.com/taroify/taroify/issues/66)

**Feature**

- 提供完全属性集，为所有组件的属性继承自 StandardProps 接口 [#65](https://github.com/taroify/taroify/issues/65)
- 使用 useMounted 代替 useReady 钩子 [#62](https://github.com/taroify/taroify/issues/62)
- @taroify/icons 增强自动导入图标样式 [#63](https://github.com/taroify/taroify/issues/63)

### v0.0.15-alpha.12

`2021-10-26`

**Breaking Changes**

- Cell.Group
  - title 属性的类型调整为 ReactNode [#60](https://github.com/taroify/taroify/issues/60)

### v0.0.15-alpha.11

`2021-10-25`

**Bug Fixes**

- Popup
  - 修复导入`@taroify/~icons`的问题 [#59](https://github.com/taroify/taroify/issues/59)

### v0.0.15-alpha.10

`2021-10-25`

**Feature**

- Tabs
  - 新增 TabsSticky 属性，用以设置 Tabs.sticky 属性 [#58](https://github.com/taroify/taroify/issues/58)

**Breaking Changes**

- Sticky
  - 使用 offsetTop, offsetBottom 属性代替 \{ top, bottom } 属性 [#57](https://github.com/taroify/taroify/issues/57)

### v0.0.15-alpha.9

`2021-10-25`

**Bug Fixes**

- Button
  - 修复文本按钮存在边框的问题 [#55](https://github.com/taroify/taroify/issues/55)

**Breaking Changes**

- Button
  - 删除 color 自定义属性，使用 CSS className 和 style 代替 color 属性 [#56](https://github.com/taroify/taroify/issues/56)

### v0.0.15-alpha.8

`2021-10-24`

**Feature**

- Sticky
  - 新增 onScroll 事件 [#51](https://github.com/taroify/taroify/issues/51)
- Image
  - 新增 onClick 事件 [#54](https://github.com/taroify/taroify/issues/54)

**Bug Fixes**

- Tabs
  - 修复设置 sticky 无法切换 Tab 的问题 [#52](https://github.com/taroify/taroify/issues/52)
- Styles
  - 修复 tap-highlight-color 默认为淡蓝的问题 [#54](https://github.com/taroify/taroify/issues/53)

### v0.0.15-alpha.7

`2021-10-22`

**Feature**

- 使用 esm 作为默认打包方式 [#50](https://github.com/taroify/taroify/issues/50)

### v0.0.15-alpha.6

`2021-10-22`

**Feature**

- Toast
  - 新增 position 属性 [#49](https://github.com/taroify/taroify/issues/49)

### v0.0.15-alpha.5

`2021-10-22`

**Bug Fixes**

- Transition
  - 修复 DOM 在 enter 之前已挂载的问题 [#48](https://github.com/taroify/taroify/issues/48)

### v0.0.15-alpha.4

`2021-10-21`

**Feature**

- Tag
  - 新增 onClick 事件 [#46](https://github.com/taroify/taroify/issues/46)

**Breaking Changes**

- Tag
  - 删除 textColor 属性，使用 CSS className 和 style 代替 textColor 属性 [#47](https://github.com/taroify/taroify/issues/47)

### v0.0.15-alpha.3

`2021-10-20`

**Feature**

- Uploader.Image
  - 新增 mode, alt, round 属性 [#45](https://github.com/taroify/taroify/issues/45)

### v0.0.15-alpha.2

`2021-10-19`

**Bug Fixes**

- Transition
  - 修复因设置 unmountOnExit 属性，而导致小程序渲染错乱的问题 [#42](https://github.com/taroify/taroify/issues/42)

### v0.0.15-alpha.1

`2021-10-18`

**Feature**

- Tabs
  - 新增 bottomBar 的 css 变量 [#40](https://github.com/taroify/taroify/issues/40)

### v0.0.15-alpha.0

`2021-10-16`

**New Component**

- 新增 ConfigProvider 组件 [#39](https://github.com/taroify/taroify/issues/39)

### v0.0.14-alpha.2

`2021-10-13`

**Bug Fixes**

- SwipeCell
  - 修复动画卡顿和 rightRect 为空的问题 [#37](https://github.com/taroify/taroify/issues/37)

### v0.0.14-alpha.1

`2021-10-11`

**Bug Fixes**

- Tabbar
  - 修复图标为空时，Badge 组件未清理的问题 [#35](https://github.com/taroify/taroify/issues/35)

### v0.0.14-alpha.0

`2021-10-11`

**Breaking Changes**

- DropdownMenu
  - activeKey 属性重命名为 value [#34](https://github.com/taroify/taroify/issues/34)
- Collapse
  - activeKey 属性重命名为 value [#34](https://github.com/taroify/taroify/issues/34)
- Sidebar
  - activeKey 属性重命名为 value [#34](https://github.com/taroify/taroify/issues/34)
- TreeSelect
  - activeTab 属性重命名为 tabValue [#34](https://github.com/taroify/taroify/issues/34)
  - activeValue 属性重命名为 value [#34](https://github.com/taroify/taroify/issues/34)

### v0.0.13-alpha.0

`2021-10-09`

**Feature**

- 完善 css var 自定义主题 [#23](https://github.com/taroify/taroify/issues/23)
- 新增所有的 vant 图标 [#30](https://github.com/taroify/taroify/issues/30)

### v0.0.12-alpha.18

`2021-09-30`

**Bug Fixes**

- Button
  - 修复细边框样式模糊问题 [#29](https://github.com/taroify/taroify/issues/29)

### v0.0.12-alpha.17

`2021-09-27`

**Bug Fixes**

- Tabs
  - 修复滑动切换时 Tab 没有效果的问题 [#28](https://github.com/taroify/taroify/issues/28)

### v0.0.12-alpha.16

`2021-09-27`

**Feature**

- Tabs.TabPane
  - 新增 value 属性 [#26](https://github.com/taroify/taroify/issues/26)

**Bug Fixes**

- Button
  - 修复 disabled 为 true 时，依然可以点击的问题 [#27](https://github.com/taroify/taroify/issues/27)

**Breaking Changes**

- Tabs
  - activeKey 属性重命名为 value [#26](https://github.com/taroify/taroify/issues/26)

### v0.0.12-alpha.15

`2021-09-27`

**Bug Fixes**

- Tabs
  - 修复在微信小程序获得 navRect 为空的问题 [#19](https://github.com/taroify/taroify/pull/19)

### v0.0.12-alpha.14

`2021-09-26`

**Feature**

- @taroify/icons
  - 在使用 @taroify/core 组件时，自动导入图标样式 [#24](https://github.com/taroify/taroify/issues/24)

### v0.0.12-alpha.13

`2021-09-26`

**Bug Fixes**

- NoticeBar
  - 修复动态渲染时，useReady 不执行的问题 [#20](https://github.com/taroify/taroify/pull/20)

### v0.0.12-alpha.12

`2021-09-23`

**Bug Fixes**

- Sheet
  - 修复按需导入样式的问题 [#18](https://github.com/taroify/taroify/issues/18)
- Tabs
  - 修复 navOffset 为 null 导致报错的问题 [#17](https://github.com/taroify/taroify/pull/17)

### v0.0.12-alpha.11

`2021-09-23`

**Bug Fixes**

- Divider
  - 修复 className 放置错误问题 [#16](https://github.com/taroify/taroify/pull/16)

### v0.0.12-alpha.10

`2021-09-22`

**Feature**

- 所有组件新增 className 属性 [#15](https://github.com/taroify/taroify/issues/15)

### v0.0.12-alpha.9

`2021-09-22`

### v0.0.12-alpha.8

`2021-09-22`

**Feature**

- Field
  - 新增 name 属性 [#11](https://github.com/taroify/taroify/issues/11)

**Bug Fixes**

- Import on demand
  - 修复重复导入样式的问题 [#13](https://github.com/taroify/taroify/issues/13)
- NoticeBar
  - 修复 NoticeBar 全局样式引入问题 [#14](https://github.com/taroify/taroify/issues/14)

### v0.0.12-alpha.7

`2021-09-09`

### v0.0.12-alpha.6

`2021-09-09`

**Bug Fixes**

- NumberKeyboard
  - 修复 classNames 导入方式不正确的问题 [#10](https://github.com/taroify/taroify/issues/10)

### v0.0.12-alpha.5

`2021-09-08`

**Feature**

- Navbar
  - title 提升为 ReactNode 类型 [#7](https://github.com/taroify/taroify/issues/7)
- Sticky
  - 新增 onChange 事件 [#6](https://github.com/taroify/taroify/issues/6)

**Breaking Change**

- Tabbar
  - 重命名 Tabbar.Item 为 Tabbar.TabItem [#8](https://github.com/taroify/taroify/issues/8)

### v0.0.12-alpha.4

`2021-09-04`

**Feature**

- Button
  - 新增小程序属性 [#2](https://github.com/taroify/taroify/issues/2)
- Tabbar
  - 新增 fixed 属性 [#5](https://github.com/taroify/taroify/issues/5)
  - Tabbar：新增 placeholder 属性 [#5](https://github.com/taroify/taroify/issues/5)
  - Tabbar：新增 bordered 属性 [#5](https://github.com/taroify/taroify/issues/5)
  - Tabbar.Item：新增 badge 属性 [#5](https://github.com/taroify/taroify/issues/5)

### v0.0.12-alpha.3

`2021-09-03`

### v0.0.12-alpha.2

`2021-09-03`

**Bug Fixes**

- List：修复 nextTick 在微信小程序不执行的问题 [#3](https://github.com/taroify/taroify/issues/3)

### v0.0.12-alpha.1

`2021-08-31`

**Feature**

- Search：新增 icon 属性
- Navbar：新增 NavLeft onClick 事件
- Navbar：新增 NavRight onClick 事件
- Navbar：使用 NavLeft.children 代替 NavLeft.text
- Navbar：使用 NavRight.children 代替 NavRight.text

**Bug Fixes**

- Tabs：修复 设置 sticky 时 container 为 undefined 的问题

### v0.0.12-alpha.0

`2021-08-25`

**New Component**

- 新增 Field 组件
- 新增 Search 组件

**Feature**

- Cell.Group: 新增 inset 属性

### v0.0.11-alpha.0

`2021-08-18`

**New Component**

- 新增 NumberKeyboard 组件
- 新增 Uploader 组件

**Feature**

- Tabs: 新增 animated 属性
- Tabs: 新增 swipeable 属性

### v0.0.10-alpha.0

`2021-07-30`

**New Component**

- 新增 Checkbox 组件
- 新增 Radio 组件
- 新增 PasswordInput 组件

### v0.0.9-alpha.0

`2021-07-26`

**New Component**

- 新增 Rate 组件
- 新增 Slider 组件

### v0.0.8-alpha.0

`2021-07-22`

**New Component**

- 新增 Stepper 组件
- 新增 Switch 组件

### v0.0.7-alpha.0

`2021-07-21`

**New Component**

- 新增 DropdownMenu 组件
- 新增 PullRefresh 组件
- 新增 Circle 组件
- 新增 List 组件
- 新增 IndexList 组件

### v0.0.6-alpha.0

`2021-06-21`

**New Component**

- 新增 SwipeCell 组件
- 新增 Collapse 组件
- 新增 CountDown 组件
- 新增 NoticeBar 组件
- 新增 Skeleton 组件
- 新增 Steps 组件
- 新增 TreeSelect 组件

### v0.0.5-alpha.0

`2021-05-21`

**New Component**

- 新增 Notify 组件
- 新增 Progress 组件
- 新增 Sticky 组件
- 新增 Swiper 组件
- 新增 Pagination 组件

**Breaking Changes**

- Cell：重命名 subtitle 属性为 brief
- Toast：重命名 placement 属性为 position

### v0.0.4-alpha.0

`2021-05-07`

**New Component**

- 新增 ActionSheet 组件
- 新增 Dialog 组件
- 新增 ShareSheet 组件

**Breaking Changes**

- Cell.Group：重命名 CellGroup 组件为 Cell.Group
- Popup：去除 backdrop 属性，将 backdrop 属性设计为 Popup.Backdrop 组件

**Bug Fixes**

- Popup：修复点击关闭图标无反应的问题

### v0.0.3-alpha.0

`2021-04-30`

**New Component**

- 新增 Badge 组件
- 新增 Tag 组件
- 新增 Grid 组件
- 新增 Navbar 组件
- 新增 Sidebar 组件
- 新增 Tabs 组件
- 新增 Tabbar 组件

**Breaking Changes**

- Cell：label 属性重命名为 title
- Cell：description 属性重命名为 subtitle

**Bug Fixes**

- 修复使用 babel-plugin-import 无法导入依赖组件样式问题

### v0.0.1-alpha.0

`2021-04-19`

**New Component**

- 新增 Backdrop 组件
- 新增 Button 组件
- 新增 Cell 组件
- 新增 CellGroup 组件
- 新增 Col 组件
- 新增 Image 组件
- 新增 Loading 组件
- 新增 Popup 组件
- 新增 Row 组件
- 新增 Toast 组件
- 新增 Transition 组件



---
url: https://taroify.com/components/button/index.md
---

# Button 按钮

### 介绍

按钮用于触发一个操作，如提交表单。

### 引入

```jsx
import { Button } from "@taroify/core"
```

## 代码演示

### 按钮颜色

按钮支持 `default`、`primary`、`info`、`success`、`warning`、`danger` 六种颜色，默认为 `default`。

```jsx
<Button color="primary">主要按钮</Button>
<Button color="info">信息按钮</Button>
<Button color="success">成功按钮</Button>
<Button color="warning">警告按钮</Button>
<Button color="danger">危险按钮</Button>
<Button color="default">默认按钮</Button>
```

### 文本按钮

通过 `variant="text"` 属性将按钮设置为文本按钮。

```jsx
<Button variant="text" color="primary">主要按钮</Button>
<Button variant="text" color="info">信息按钮</Button>
<Button variant="text" color="success">成功按钮</Button>
<Button variant="text" color="warning">警告按钮</Button>
<Button variant="text" color="danger">危险按钮</Button>
<Button variant="text" color="default">默认按钮</Button>
```

### 轮廓按钮

通过 `variant="outlined"` 属性将按钮设置为轮廓按钮。

```jsx
<Button variant="outlined" color="primary">主要按钮</Button>
<Button variant="outlined" color="info">信息按钮</Button>
<Button variant="outlined" color="success">成功按钮</Button>
<Button variant="outlined" color="warning">警告按钮</Button>
<Button variant="outlined" color="danger">危险按钮</Button>
<Button variant="outlined" color="default">默认按钮</Button>
```

### 细边框

设置 `hairline` 属性可以展示 0.5px 的细边框。

```jsx
<Button variant="outlined" color="primary" hairline>主要按钮</Button>
<Button variant="outlined" color="info" hairline>信息按钮</Button>
<Button variant="outlined" color="success" hairline>成功按钮</Button>
<Button variant="outlined" color="warning" hairline>警告按钮</Button>
<Button variant="outlined" color="danger" hairline>危险按钮</Button>
<Button variant="outlined" color="default" hairline>默认按钮</Button>
```

### 禁用状态

通过 `disabled` 属性来禁用按钮，禁用状态下按钮不可点击。

```jsx
<Button variant="contained" color="primary" disabled>主要按钮</Button>
<Button variant="contained" color="info" disabled>信息按钮</Button>
<Button variant="contained" color="success" disabled>成功按钮</Button>
<Button variant="contained" color="warning" disabled>警告按钮</Button>
<Button variant="contained" color="danger" disabled>危险按钮</Button>
<Button variant="contained" color="default" disabled>默认按钮</Button>
```

### 加载状态

通过 `loading` 属性设置按钮为加载状态，可以通过 `{ type: "spinner" }` 设置加载类型。加载时会隐藏 `icon` 属性传入的业务图标；通过 `loadingText` 可以单独设置加载文案，不传时保留原按钮内容。

```tsx
<Button color="success" loading />
<Button color="success" loading={{ type: "spinner" }} />
<Button color="primary" loading loadingText="加载中...">提交</Button>
```

### 按钮形状

通过 `shape="square"` 设置方形按钮，通过 `shape="round"` 设置圆形按钮。

```jsx
<Button variant="contained" color="primary" shape="square">方形按钮</Button>
<Button variant="contained" color="primary" shape="round">圆形按钮</Button>
```

### 图标按钮

通过 `icon` 属性设置按钮图标，支持任意 React 节点。仅包含图标的按钮应通过 `ariaLabel` 提供用于无障碍阅读的名称。

```jsx
<Button variant="contained" color="primary" icon={<DoneOutlined />} ariaLabel="完成" />
<Button variant="contained" color="primary" icon={<DoneOutlined />}>主要按钮</Button>
<Button variant="outlined" color="primary" icon={<DoneOutlined />} iconPosition="right">轮廓按钮</Button>
```

### 无障碍阅读

`ariaLabel` 用于为屏幕阅读器等辅助工具提供按钮名称，不会改变按钮的视觉效果。普通文本按钮会尝试从内容中自动提取名称；图标按钮没有可提取的文字，应显式设置 `ariaLabel`。

```jsx
<Button icon={<ShopOutlined />} ariaLabel="购物车" />

<Button.Group ariaLabel="分页操作">
  <Button>上一页</Button>
  <Button>下一页</Button>
</Button.Group>
```

`Button.Group` 默认声明为 `group` 语义，帮助屏幕阅读器识别一组相关操作。具体支持情况取决于目标 Taro 平台。

### 按钮尺寸

支持 `large`、`medium`、`small`、`mini` 四种尺寸，默认为 `medium`。

```jsx
<Button color="primary" size="large">大号按钮</Button>
<Button color="primary" size="medium">普通按钮</Button>
<Button color="primary" size="small">小型按钮</Button>
<Button color="primary" size="mini">迷你按钮</Button>
```

### 块级元素

按钮在默认情况下为行内块级元素，通过 `block` 属性可以将按钮的元素类型设置为块级元素。

```jsx
<Button color="primary" block>块级按钮</Button>
```

### 自定义颜色

通过 `color` 属性可以自定义按钮颜色。渐变色适用于 `contained` 按钮。

```tsx
<Button color="#7232dd">单色按钮</Button>
<Button variant="outlined" color="#7232dd">轮廓按钮</Button>
<Button color="linear-gradient(to right, #ff6034, #ee0a24)">渐变色按钮</Button>
```

### 微信开放能力

Button 继承了 Taro 原生 Button 的属性，可以通过 `openType` 使用微信小程序开放能力。JSX 中需要使用驼峰写法，例如原生小程序的 `open-type`、`bindgetphonenumber` 分别写为 `openType`、`onGetPhoneNumber`。

```tsx
<Button
  openType="getPhoneNumber"
  onGetPhoneNumber={(event) => {
    console.log(event.detail.code)
  }}
>
  获取手机号
</Button>

<Button openType="contact">联系客服</Button>

<Button
  openType="chooseAvatar"
  onChooseAvatar={(event) => {
    console.log(event.detail.avatarUrl)
  }}
>
  选择头像
</Button>

<Button openType="share">分享</Button>
```

开放能力的可用范围、参数和回调由目标小程序平台决定，H5 等不支持对应能力的平台不会生效，具体请参考 [Taro Button 文档](https://docs.taro.zone/docs/components/forms/button)。

### 按钮组

```tsx
<Button.Group variant="contained" color="primary" shape="round">
  <Button> <ArrowLeft /> 上一步</Button>
  <Button> <Replay /> 刷新</Button>
  <Button>下一步 <Arrow /></Button>
</Button.Group>

<Button.Group variant="outlined" shape="round" size="small">
  <Button> <ArrowLeft /> 上一步</Button>
  <Button><Replay /> 刷新</Button>
  <Button>下一步 <Arrow /></Button>
</Button.Group>

<Button.Group variant="text" color="primary" shape="round">
  <Button> <ArrowLeft /> 上一步</Button>
  <Button> <Replay /> 刷新</Button>
  <Button>下一步 <Arrow /></Button>
</Button.Group>
```

## API

### Props

| 参数                               | 说明                                                                                    | 类型                                                                              | 默认值         |
| -------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------- |
| variant                          | 按钮变种，可选值为 `contained` `text` `outlined`                                               | _string_                                                                        | `contained` |
| color <Tag tag="v1.0.1" />       | 预设颜色或任意 CSS 颜色，预设值为 `default` `primary` `info` `success` `warning` `danger`           | _string_                                                                        | `default`   |
| size                             | 尺寸，可选值为 `large` `small` `mini`                                                        | _string_                                                                        | `medium`    |
| shape                            | 按钮形状，可选值为 `square` `round`                                                            | _string_                                                                        | -           |
| icon                             | 按钮图标                                                                                  | _ReactNode_                                                                     | -           |
| iconPosition                     | 图标展示位置，可选值为 `right`                                                                   | _string_                                                                        | `left`      |
| formType                         | 原生 button 标签的 type 属性                                                                 | _string_                                                                        | `button`    |
| block                            | 是否为块级元素                                                                               | _boolean_                                                                       | `false`     |
| disabled                         | 是否禁用按钮                                                                                | _boolean_                                                                       | `false`     |
| hairline                         | 是否使用 0.5px 边框                                                                         | _boolean_                                                                       | `false`     |
| loading                          | 是否显示为加载状态或自定义加载图标                                                                     | _boolean \| [LoadingProps](/components/loading/index.md#props) \| ReactElement_ | `false`     |
| loadingText <Tag tag="v1.0.1" /> | 加载状态文案                                                                                | _ReactNode_                                                                     | -           |
| ariaLabel <Tag tag="v1.0.1" />   | 用于无障碍阅读的按钮名称，图标按钮建议显式设置                                                               | _string_                                                                        | 自动从内容提取     |
| openType                         | 小程序开放能力，取值和相关事件请参考 [Taro Button](https://docs.taro.zone/docs/components/forms/button) | _string_                                                                        | -           |
| children                         | 按钮内容                                                                                  | _ReactNode_                                                                     | -           |

除上述属性外，Button 还支持 Taro 原生 Button 的开放能力参数及事件，例如 `onGetPhoneNumber`、`onContact`、`onChooseAvatar` 和 `onOpenSetting`。

### Button.Group Props

| 参数                             | 说明                                      | 类型        | 默认值         |
| ------------------------------ | --------------------------------------- | --------- | ----------- |
| variant                        | 按钮变种，可选值为 `contained` `text` `outlined` | _string_  | `contained` |
| color <Tag tag="v1.0.1" />     | 预设颜色或任意 CSS 颜色                          | _string_  | `default`   |
| size                           | 尺寸，可选值为 `large` `small` `mini`          | _string_  | `medium`    |
| shape                          | 按钮形状，可选值为 `round`                       | _string_  | -           |
| block                          | 是否为块级元素                                 | _boolean_ | -           |
| disabled                       | 是否禁用按钮                                  | _boolean_ | -           |
| hairline                       | 是否使用 0.5px 边框                           | _boolean_ | -           |
| ariaLabel <Tag tag="v1.0.1" /> | 用于无障碍阅读的按钮组名称                           | _string_  | -           |
| role <Tag tag="v1.0.1" />      | 用于无障碍阅读的按钮组语义角色                         | _string_  | `group`     |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                                         | 默认值                                      | 描述 |
| ---------------------------------------------------------- | ---------------------------------------- | -- |
| --button-line-height                                       | _1.2_                                    | -  |
| --button-border-width                                      | _var(--border-width-base)_               | -  |
| --button-border-radius                                     | _var(--border-radius-sm)_                | -  |
| --button-border-radius-max                                 | _var(--border-radius-max)_               | -  |
| --button-transition-duration                               | _var(--animation-duration-fast)_         | -  |
| --button-active-opacity <Tag tag="v1.0.1" />               | _0.1_                                    | -  |
| --button-disabled-opacity                                  | _var(--disabled-opacity)_                | -  |
| --button-outlined-background-color <Tag tag="v1.0.1" />    | _var(--background-color-2)_              | -  |
| --button-focus-visible-outline <Tag tag="v1.0.1" />        | _2px \* $hd solid var(--primary-color)_  | -  |
| --button-focus-visible-outline-offset <Tag tag="v1.0.1" /> | _2px \* $hd_                             | -  |
| --button-icon-size <Tag tag="v1.0.1" />                    | _1.2em_                                  | -  |
| --button-content-gap <Tag tag="v1.0.1" />                  | _var(--padding-base)_                    | -  |
| --button-loading-icon-size                                 | _20px \* $hd_                            | -  |
| --button-height-mini                                       | _24px \* $hd_                            | -  |
| --button-padding-mini                                      | _0 var(--padding-base)_                  | -  |
| --button-font-size-mini                                    | _var(--font-size-xs)_                    | -  |
| --button-height-small                                      | _32px \* $hd_                            | -  |
| --button-padding-small                                     | _0 var(--padding-xs)_                    | -  |
| --button-font-size-small                                   | _var(--font-size-sm)_                    | -  |
| --button-height-medium                                     | _44px \* $hd_                            | -  |
| --button-padding-medium                                    | _0 var(--padding-md)_                    | -  |
| --button-font-size-medium                                  | _var(--font-size-md)_                    | -  |
| --button-height-large                                      | _50px \* $hd_                            | -  |
| --button-font-size-large                                   | _var(--font-size-lg)_                    | -  |
| --button-default-color                                     | _var(--text-color)_                      | -  |
| --button-default-background-color                          | _var(--background-color-2)_              | -  |
| --button-default-border-color                              | _var(--border-color)_                    | -  |
| --button-primary-color                                     | _var(--white)_                           | -  |
| --button-primary-background-color                          | _var(--primary-color)_                   | -  |
| --button-primary-border-color                              | _var(--button-primary-background-color)_ | -  |
| --button-info-color                                        | _var(--white)_                           | -  |
| --button-info-background-color                             | _var(--info-color)_                      | -  |
| --button-info-border-color                                 | _var(--button-info-background-color)_    | -  |
| --button-success-color                                     | _var(--white)_                           | -  |
| --button-success-background-color                          | _var(--success-color)_                   | -  |
| --button-success-border-color                              | _var(--button-success-background-color)_ | -  |
| --button-warning-color                                     | _var(--white)_                           | -  |
| --button-warning-background-color                          | _var(--warning-color)_                   | -  |
| --button-warning-border-color                              | _var(--button-warning-background-color)_ | -  |
| --button-danger-color                                      | _var(--white)_                           | -  |
| --button-danger-background-color                           | _var(--danger-color)_                    | -  |
| --button-danger-border-color                               | _var(--button-danger-background-color)_  | -  |



---
url: https://taroify.com/components/cell/index.md
---

# Cell 单元格

### 介绍

单元格为列表中的单个展示项。

### 引入

```tsx
import { Cell } from "@taroify/core"
```

## 代码演示

### 基础用法

`Cell` 可以单独使用，也可以与 `Cell.Group` 搭配使用，`Cell.Group` 可以为 `Cell` 提供上下外边框。

```tsx
<Cell title="单元格">内容</Cell>
<Cell title="单元格" brief="描述信息">内容</Cell>
```

### 卡片风格

通过 `Cell.Group` 的 `inset` 属性，可以将单元格转换为圆角卡片风格。卡片模式不会显示上下外边框。

```tsx
<Cell.Group inset>
  <Cell title="单元格">内容</Cell>
  <Cell title="单元格">内容</Cell>
</Cell.Group>
```

### 单元格大小

通过 `size` 属性可以控制单元格的大小。

```tsx
<Cell title="单元格">内容</Cell>
<Cell title="单元格" brief="描述信息" size="large">内容</Cell>
```

### 展示图标

通过 `icon` 属性在标题左侧展示图标。

```tsx
<Cell icon={<LocationOutlined />} title="单元格">
  内容
</Cell>
```

### 只设置内容

只设置 `children` 时，内容会靠左对齐。

```tsx
<Cell>内容</Cell>
```

### 展示箭头

设置 `isLink` 属性后会在单元格右侧展示箭头，并且可以通过 `arrowDirection` 控制箭头方向。

```tsx
<Cell title="单元格" isLink />
<Cell title="单元格" isLink children="内容" />
<Cell title="单元格" isLink arrowDirection="down" children="内容" />
```

### 页面导航 v1.0.1
使用 `Cell.Link` 可以通过 Taro `Navigator` 完成页面跳转。`Cell.Link` 默认展示右侧箭头并开启点击反馈。

```tsx
<Cell.Link title="订单详情" url="/pages/order/detail/index">
  查看
</Cell.Link>
<Cell.Link title="返回上一页" openType="navigateBack" />
```

### 额外内容 v1.0.1
通过 `extra` 属性可以在右侧图标之后放置额外内容。

```tsx
<Cell title="消息通知" isLink extra={<Switch checked />}>
  已开启
</Cell>
```

### 分组标题

通过 `Cell.Group` 的 `title` 属性可以指定分组标题。

```tsx
<Cell.Group title="分组 1">
  <Cell title="单元格">内容</Cell>
</Cell.Group>
<Cell.Group title="分组 2">
  <Cell title="单元格">内容</Cell>
</Cell.Group>
```

### 对齐方式

通过 `align` 属性可以改变 `Cell` 的左右内容的对齐方式。

```tsx
<Cell title="单元格" brief="align start" size="large" align="start">内容</Cell>
<Cell title="单元格" brief="align center" size="large" align="center">内容</Cell>
<Cell title="单元格" brief="align end" size="large" align="end">内容</Cell>
```

## 升级提示

- `Cell.Group` 的标题和内容容器现在是同级节点，传入的原生 View 属性会作用于内容容器。
- `Cell.Group` 在 `inset` 模式下不再显示上下外边框。
- `Cell` 显式设置的 `clickable` 优先于 `isLink` 和 `Cell.Group clickable`。
- `icon` 和 `rightIcon` 会被统一的布局节点包裹，自定义图标会自动获得标准间距和对齐。
- `size="large"` 现在会正确应用大尺寸描述文字样式。

## API

### Cell.Group Props

| 参数        | 说明            | 类型          | 默认值     |
| --------- | ------------- | ----------- | ------- |
| title     | 分组标题          | _ReactNode_ | `-`     |
| inset     | 是否展示为圆角卡片风格   | _boolean_   | `false` |
| bordered  | 是否显示非卡片模式的外边框 | _boolean_   | `true`  |
| clickable | 是否为子单元格开启点击反馈 | _boolean_   | `false` |

### Cell Props

| 参数                         | 说明                                                     | 类型              | 默认值      |
| -------------------------- | ------------------------------------------------------ | --------------- | -------- |
| title                      | 左侧标题                                                   | _ReactNode_     | `-`      |
| children                   | 右侧内容                                                   | _ReactNode_     | `-`      |
| brief                      | 标题下方的描述信息                                              | _ReactNode_     | `-`      |
| size <Tag tag="v1.0.1" />  | 单元格大小，可选值为 `normal` `large`，`medium` 已废弃               | _string_        | `normal` |
| icon                       | 左侧[图标](/components/icon.md)或[图片](/components/image.md) | _ReactNode_     | `-`      |
| rightIcon                  | 右侧自定义图标                                                | _ReactNode_     | `-`      |
| extra <Tag tag="v1.0.1" /> | 右侧图标之后的额外内容                                            | _ReactNode_     | `-`      |
| bordered                   | 是否显示内边框                                                | _boolean_       | `true`   |
| clickable                  | 是否开启点击反馈，显式值优先于分组和链接状态                                 | _boolean_       | `-`      |
| isLink                     | 是否展示右侧箭头并开启点击反馈                                        | _boolean_       | `false`  |
| arrowDirection             | 箭头方向，可选值为 `left` `right` `up` `down`                   | _string_        | `right`  |
| required                   | 是否显示表单必填星号                                             | _boolean_       | `false`  |
| align                      | 对齐方式，可选值为 `start` `center` `end`                       | _string_        | `-`      |
| titleStyle                 | 左侧标题额外样式                                               | _CSSProperties_ | `-`      |
| titleClass                 | 左侧标题额外类名                                               | _string_        | `-`      |
| valueClass                 | 右侧内容额外类名                                               | _string_        | `-`      |
| briefClass                 | 标题下方的描述信息额外类名                                          | _string_        | `-`      |

`Cell` 还继承了 Taro `View` 的原生属性。

### Cell.Link Props v1.0.1
`Cell.Link` 支持 Cell 内容与样式属性，并继承 Taro `Navigator` 的 `url`、`openType`、`target` 等原生属性。`isLink` 和 `clickable` 的默认值均为 `true`。

### Cell Events

| 事件名     | 说明       | 回调参数                 |
| ------- | -------- | -------------------- |
| onClick | 点击单元格时触发 | _event: ITouchEvent_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                                 | 默认值                                                                       | 描述 |
| -------------------------------------------------- | ------------------------------------------------------------------------- | -- |
| --cell-font-size                                   | _var(--font-size-md)_                                                     | -  |
| --cell-line-height                                 | _24px \* $hd_                                                             | -  |
| --cell-color                                       | _var(--text-color)_                                                       | -  |
| --cell-background-color                            | _var(--background-color-2)_                                               | -  |
| --cell-border-color                                | _var(--border-color)_                                                     | -  |
| --cell-value-color                                 | _var(--gray-6)_                                                           | -  |
| --cell-value-font-size <Tag tag="v1.0.1" />        | _inherit_                                                                 | -  |
| --cell-active-color                                | _var(--active-color)_                                                     | -  |
| --cell-required-color                              | _var(--danger-color)_                                                     | -  |
| --cell-required-padding-right                      | _2px \* $hd_                                                              | -  |
| --cell-icon-size                                   | _16px \* $hd_                                                             | -  |
| --cell-left-icon-margin-right <Tag tag="v1.0.1" /> | _4px \* $hd_                                                              | -  |
| --cell-right-icon-margin-left <Tag tag="v1.0.1" /> | _4px \* $hd_                                                              | -  |
| --cell-right-icon-color <Tag tag="v1.0.1" />       | _var(--cell-value-color)_                                                 | -  |
| --cell-extra-margin-left <Tag tag="v1.0.1" />      | _var(--padding-base)_                                                     | -  |
| --cell-icon-margin-left <Tag tag="待废弃" />          | _4px \* $hd_                                                              | -  |
| --cell-right-icon-margin-right <Tag tag="待废弃" />   | _4px \* $hd_                                                              | -  |
| --cell-brief-margin-top                            | _var(--padding-base)_                                                     | -  |
| --cell-brief-font-size                             | _var(--font-size-sm)_                                                     | -  |
| --cell-brief-line-height                           | _var(--line-height-sm)_                                                   | -  |
| --cell-brief-color                                 | _var(--gray-6)_                                                           | -  |
| --cell-vertical-padding                            | _10px \* $hd_                                                             | -  |
| --cell-horizontal-padding                          | _var(--padding-md)_                                                       | -  |
| --cell-vertical-padding-large                      | _var(--padding-sm)_                                                       | -  |
| --cell-title-font-size-large                       | _var(--font-size-lg)_                                                     | -  |
| --cell-brief-font-size-large <Tag tag="v1.0.1" />  | _var(--font-size-md)_                                                     | -  |
| --cell-value-font-size-large <Tag tag="v1.0.1" />  | _inherit_                                                                 | -  |
| --cell-subtitle-font-size-large <Tag tag="待废弃" />  | _var(--font-size-md)_                                                     | -  |
| --cell-group-background-color                      | _var(--background-color-2)_                                               | -  |
| --cell-group-title-color                           | _var(--gray-6)_                                                           | -  |
| --cell-group-title-padding                         | _var(--padding-md) var(--padding-md) var(--padding-xs)_                   | -  |
| --cell-group-title-font-size                       | _var(--font-size-md)_                                                     | -  |
| --cell-group-title-line-height                     | _16px \* $hd_                                                             | -  |
| --cell-group-inset-padding                         | _0 var(--padding-md)_                                                     | -  |
| --cell-group-inset-border-radius                   | _var(--border-radius-lg)_                                                 | -  |
| --cell-group-inset-title-padding                   | _var(--padding-md) var(--padding-md) var(--padding-xs) var(--padding-xl)_ | -  |



---
url: https://taroify.com/components/config-provider/index.md
---

# ConfigProvider 全局配置

### 介绍

用于配置 Taroify 组件的主题样式。

### 引入

```tsx
import { ConfigProvider } from "@taroify/core";
```

## 定制主题

### 介绍

Taroify 组件通过丰富的 [CSS 变量](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties) 来组织样式，通过覆盖这些 CSS
变量，可以实现**定制主题、动态切换主题**等效果。

#### 示例

以 Button 组件为例，查看组件的样式，可以看到 `.taroify-button--primary` 类名上存在以下变量：

```scss
.taroify-button--primary {
  color: var(--button-primary-color);
  background-color: var(--button-primary-background-color);
}
```

### 自定义 CSS 变量

#### 通过 CSS 覆盖

你可以直接在代码中覆盖这些 CSS 变量，Button 组件的样式会随之发生改变：

```css
/* 添加这段样式后，Primary Button 会变成红色 */
:root {
    --button-primary-background-color: red;
}
```

> 注意：小程序不存在 `:root` 元素，只能在 `page` 根元素里覆盖 CSS 变量。

#### 通过 ConfigProvider 覆盖

`ConfigProvider` 组件提供了覆盖 CSS 变量的能力，你需要在根节点包裹一个 `ConfigProvider` 组件，并通过 `theme` 属性来配置一些主题变量。

```tsx
function CustomThemeVars() {
  const [rate, setRate] = useState(4)
  const [slider, setSlider] = useState(50)

  return (
    <ConfigProvider
      theme={{
        rateIconFullColor: "#07c160",
        sliderTrackHeight: "4px",
        sliderButtonWidth: "20px",
        sliderButtonHeight: "20px",
        sliderActiveBackgroundColor: "#07c160",
        buttonPrimaryBorderColor: "#07c160",
        buttonPrimaryBackgroundColor: "#07c160",
      }}
    >
      <Field label="评分">
        <Rate allowHalf value={rate} onChange={setRate} />
      </Field>
      <Field label="滑块">
        <Slider value={slider} onChange={setSlider} />
      </Field>
      <View style={{ margin: "16px" }}>
        <Button shape="round" block color="primary">
          提交
        </Button>
      </View>
    </ConfigProvider>
  )
}

```

> 注意：ConfigProvider 仅影响它的子组件的样式，不影响全局 root 节点。在小程序中 ConfigProvider 不能放置在 `app.ts` 文件里，因为 `app.ts` 文件不能渲染任何内容。

#### 暗色模式

将 `themeMode` 设置为 `dark`，可以启用内置的暗色主题。`theme` 中的自定义变量会覆盖暗色主题的默认变量。

```tsx
<ConfigProvider
  themeMode="dark"
  theme={{
    primaryColor: "#4d9fff",
  }}
>
  <App />
</ConfigProvider>
```

如果需要跟随微信系统主题，应在应用配置中启用 `darkmode` 和 `themeLocation`，然后通过 `Taro.onThemeChange` 更新 `themeMode`：

```tsx
const [themeMode, setThemeMode] = useState<ConfigProviderTheme>("light")

useEffect(() => {
  const listener = ({ theme }) => setThemeMode(theme)
  Taro.onThemeChange(listener)
  return () => Taro.offThemeChange(listener)
}, [])

return <ConfigProvider themeMode={themeMode}>{children}</ConfigProvider>
```

#### 在 TypeScript 中使用

在 TypeScript 中定义 themeVars 时，建议使用 Taroify 提供的 ConfigProviderThemeVars 类型，可以提供完善的类型提示：

```ts
import type { ConfigProviderThemeVars } from '@taroify/core';

const themeVars: ConfigProviderThemeVars = {
  rateIconFullColor: "#07c160",
  sliderTrackHeight: "4px",
  sliderActiveBackgroundColor: "#07c160",
  buttonPrimaryBorderColor: "#07c160",
  buttonPrimaryBackgroundColor: "#07c160",
};
```

### 基础变量

Taroify 中的 CSS 变量分为 **基础变量** 和 **组件变量**。组件变量会继承基础变量，因此在修改基础变量后，会影响所有相关的组件。

#### 变量列表

下面是所有的基础变量：

```scss
// Color Palette
--black: #000;
--white: #fff;
--gray-1: #f7f8fa;
--gray-2: #f2f3f5;
--gray-3: #ebedf0;
--gray-4: #dcdee0;
--gray-5: #c8c9cc;
--gray-6: #969799;
--gray-7: #646566;
--gray-8: #323233;
--red: #ee0a24;
--blue: #1989fa;
--orange: #ff976a;
--orange-dark: #ed6a0c;
--orange-light: #fffbe8;
--green: #07c160;

// Gradient Colors
--gradient-red: linear-gradient(to right, #ff6034, #ee0a24);
--gradient-orange: linear-gradient(to right, #ffd01e, #ff8917);

// Component Colors
--primary-color: var(--blue);
--success-color: var(--green);
--danger-color: var(--red);
--warning-color: var(--orange);
--text-color: var(--gray-8);
--text-color-2: var(--gray-6);
--text-color-3: var(--gray-5);
--active-color: var(--gray-2);
--active-opacity: 0.7;
--disabled-opacity: 0.5;
--background-color: var(--gray-1);
--background-color-2: var(--white);
--background-color-light: var(--background-color-2);
--text-link-color: #576b95;

// Padding
--padding-base: 4px;
--padding-xs: 8px;
--padding-sm: 12px;
--padding-md: 16px;
--padding-lg: 24px;
--padding-xl: 32px;

// Font
--font-size-xs: 10px;
--font-size-sm: 12px;
--font-size-md: 14px;
--font-size-lg: 16px;
--font-weight-bold: 500;
--line-height-xs: 14px;
--line-height-sm: 18px;
--line-height-md: 20px;
--line-height-lg: 22px;
--base-font-family: -apple-system, BlinkMacSystemFont, 'Helvetica Neue',
  Helvetica, Segoe UI, Arial, Roboto, 'PingFang SC', 'miui', 'Hiragino Sans GB',
  'Microsoft Yahei', sans-serif;
--price-integer-font-family: Avenir-Heavy, PingFang SC, Helvetica Neue,
  Arial, sans-serif;

// Animation
--animation-duration-base: 0.3s;
--animation-duration-fast: 0.2s;
--animation-timing-function-enter: ease-out;
--animation-timing-function-leave: ease-in;

// Border
--border-color: var(--gray-3);
--border-width-base: 1px;
--border-radius-sm: 2px;
--border-radius-md: 4px;
--border-radius-lg: 8px;
--border-radius-max: 999px;
```

你可以在各个组件文档底部的表格中查看组件变量。

## API

### Props

| 参数                             | 说明                | 类型                        | 默认值   |
| ------------------------------ | ----------------- | ------------------------- | ----- |
| theme                          | 自定义主题变量，优先级高于内置主题 | _ConfigProviderThemeVars_ | -     |
| themeMode <Tag tag="v1.0.0" /> | 主题模式              | _light \| dark_           | light |



---
url: https://taroify.com/components/icon/index.md
---

# Icon 图标

### 介绍

基于字体的图标集，可以通过 Icon 组件使用，也可以在其他组件中通过 `icon` 属性引用。

### 引入

```tsx
import { ChatOutlined } from "@taroify/icons"
```

## 代码演示

### 基础用法

通过导入的方式引用需要使用的图标，Taroify 内置了一套 Vant 图标库（见右侧示例），可以直接复制对应的名称来使用。

```tsx
<ChatOutlined />
```

### 图片图标

通过 `src` 属性可以将图片作为图标，图片尺寸会跟随图标的 `size` 属性。

```tsx
import { Icon } from "@taroify/icons"

<Icon src="https://example.com/icon.png" />
<Icon src="https://example.com/icon.png" size={40} />
```

### 徽标提示

与 Badge 组件组合使用，会在图标右上角展示相应的徽标。

```tsx
<Badge dot>
  <ChatOutlined />
</Badge>

<Badge content="9">
  <ChatOutlined />
</Badge>

<Badge content={100} max={99}>
  <ChatOutlined />
</Badge>
```

### 图标颜色

通过 `style` 属性来设置图标的颜色。

```tsx
<CartOutlined style={{ color: "#1989fa" }} />
<FireOutlined style={{ color: "#ee0a24" }} />
```

### 图标大小

通过 `size` 属性来设置图标的尺寸大小，可以指定任意 CSS 单位。

```tsx
<!-- 不指定单位，默认使用 px -->
<ChatOutlined size="40" />
<!-- 指定使用 rem 单位 -->
<ChatOutlined size="3rem" />
```

### 自定义图标

如果需要在现有 Icon 的基础上使用更多图标，可以引入第三方 iconfont 对应的字体文件和 CSS 文件，之后就可以在 Icon 组件中直接使用。

请升级 `taroify` 到 >= `v0.3.0-alpha.0` 版本来使用该特性。

```css
/* 引入第三方或自定义的字体图标样式 */
@font-face {
  font-family: "my-icon";
  src: url("./my-icon.ttf") format("truetype");
}

.my-icon {
  font-family: "my-icon";
}

.my-icon-extra::before {
  content: "\e626";
}
```

```tsx
import { Icon } from "@taroify/icons"
<!-- 通过 classPrefix 指定类名为 my-icon -->
<Icon classPrefix="my-icon" name="extra" />
```

## API

### Props

| 参数          | 说明                             | 类型                 | 默认值        |
| ----------- | ------------------------------ | ------------------ | ---------- |
| color       | 图标颜色                           | _string_           | `inherit`  |
| size        | 图标大小，如 `20px` `2em`，默认单位为 `px` | _number \| string_ | `inherit`  |
| src         | 图片图标地址                         | _string_           | -          |
| classPrefix | 类名前缀，用于使用自定义图标                 | _string_           | `van-icon` |

### Events

| 事件名     | 说明      | 回调参数                 |
| ------- | ------- | -------------------- |
| onClick | 点击图标时触发 | _event: ITouchEvent_ |



---
url: https://taroify.com/components/image/index.md
---

# Image 图片

### 介绍

增强版的 taro Image 组件，提供多种图片填充模式，支持图片懒加载、加载中提示、加载失败提示。

### 引入

```tsx
import { Image } from "@taroify/core"
```

## 代码演示

### 基础用法

基础用法与 Taro `Image`
 组件一致，支持 `webp`
、`fadeIn`
、`showMenuByLongpress`

等原生图片属性，也可以设置 H5 的 `imgProps`
。

通过 `width`
 和 `height`
 设置图片大小，若未指定，会从 style 中读取`width`
,`height`
属性。

`width`
、`height`
 和 `radius`
 为 number 时，会经过 `pxTransform`
 转换。
```tsx
<Image width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />
```

### 填充模式

通过 `mode` 属性可以设置图片填充模式，可选值见下方表格。

```tsx
<Image width={200} height={200} mode="scaleToFill" src="https://img.yzcdn.cn/vant/cat.jpeg" />
```

### 圆形图片

通过 `shape="circle"` 设置圆形图片，可以配合 `mode` 属性展示不同的填充效果。

```tsx
<Image shape="circle" mode="scaleToFill" width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />
<Image shape="circle" mode="aspectFit" width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />
<Image shape="circle" mode="aspectFill" width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />
```

### 圆角图片 v1.0.2
通过 `shape="rounded"` 设置默认圆角，通过 `radius` 属性自定义圆角大小。

```tsx
<Image shape="rounded" width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />
<Image radius={24} width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />
```

### 图片懒加载

设置 `lazyLoad` 属性来开启图片懒加载。

```tsx
<Image lazyLoad width={200} height={200} src="https://img.yzcdn.cn/vant/cat.jpeg" />
```

### 加载中提示

通过 `placeholder` 设置加载中提示。设置为 `true` 时使用默认图标，也可以传入文本或自定义节点。

```tsx
import { Photo } from "@taroify/icons"

<Image width={200} height={200} src="image.png" placeholder />
<Image width={200} height={200} src="image.png" placeholder="加载中..." />
<Image width={200} height={200} src="image.png" placeholder={<Photo />} />
```

### 加载失败提示

通过 `fallback` 设置加载失败提示。设置为 `true` 时使用默认图标，也可以传入文本或自定义节点。

```tsx
import { PhotoFail } from "@taroify/icons"

<Image width={200} height={200} src="error" fallback />
<Image width={200} height={200} src="error" fallback="加载失败" />
<Image width={200} height={200} src="error" fallback={<PhotoFail />} />
```

## API

### Props

| 参数                          | 说明                               | 类型                     | 默认值           |
| --------------------------- | -------------------------------- | ---------------------- | ------------- |
| src                         | 图片链接                             | _string_               | -             |
| mode                        | 图片填充模式                           | _ImageMode_            | `scaleToFill` |
| alt                         | 替代文本                             | _string_               | -             |
| width                       | 宽度                               | _string \| number_     | -             |
| height                      | 高度                               | _string \| number_     | -             |
| shape                       | 图片形状 `square` `rounded` `circle` | _ImageShape_           | -             |
| radius <Tag tag="v1.0.2" /> | 圆角大小                             | _string \| number_     | -             |
| lazyLoad                    | 是否开启图片懒加载                        | _boolean_              | `false`       |
| placeholder                 | 加载中提示                            | _boolean \| ReactNode_ | `false`       |
| fallback                    | 加载失败提示                           | _boolean \| ReactNode_ | `false`       |

### Modes

| 名称          | 含义                                                                 |
| ----------- | ------------------------------------------------------------------ |
| scaleToFill | 缩放模式，不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素                             |
| aspectFit   | 缩放模式，保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。                    |
| aspectFill  | 缩放模式，保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。 |
| widthFix    | 缩放模式，宽度不变，高度自动变化，保持原图宽高比不变                                         |
| heightFix   | 缩放模式，高度不变，宽度自动变化，保持原图宽高比不变                                         |
| top         | 裁剪模式，不缩放图片，只显示图片的顶部区域                                              |
| bottom      | 裁剪模式，不缩放图片，只显示图片的底部区域                                              |
| center      | 裁剪模式，不缩放图片，只显示图片的中间区域                                              |
| left        | 裁剪模式，不缩放图片，只显示图片的左边区域                                              |
| right       | 裁剪模式，不缩放图片，只显示图片的右边区域                                              |
| topLeft     | 裁剪模式，不缩放图片，只显示图片的左上边区域                                             |
| topRight    | 裁剪模式，不缩放图片，只显示图片的右上边区域                                             |
| bottomLeft  | 裁剪模式，不缩放图片，只显示图片的左下边区域                                             |
| bottomRight | 裁剪模式，不缩放图片，只显示图片的右下边区域                                             |

### Events

| 事件名     | 说明        | 回调参数                     |
| ------- | --------- | ------------------------ |
| onClick | 点击图片时触发   | _event: ITouchEvent_     |
| onLoad  | 图片加载完毕时触发 | _event: ImageLoadEvent_  |
| onError | 图片加载失败时触发 | _event: ImageErrorEvent_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                   | 默认值                       | 描述 |
| ------------------------------------ | ------------------------- | -- |
| --image-placeholder-color            | _var(var(--gray-6)_       | -  |
| --image-placeholder-font-size        | _var(--font-size-md)_     | -  |
| --image-placeholder-icon-size        | _32px \* $hd_             | -  |
| --image-placeholder-icon-color       | _var(--gray-4)_           | -  |
| --image-placeholder-background-color | _var(--background-color)_ | -  |



---
url: https://taroify.com/components/flex/index.md
---

# Flex 布局

### 介绍

`Flex` 组件是 CSS `flex` 布局的一个封装。

### 引入

```tsx
import { Flex } from "@taroify/core"
```

## 代码演示

### 基础用法

`Flex` 组件提供了 `24列栅格`，通过在 `Flex.Item` 上添加 `span` 属性设置列所占的宽度百分比。此外，添加 `offset` 属性可以设置列的偏移宽度，计算方式与 span 相同。

```tsx
<Flex>
  <Flex.Item span={8}>span: 8</Flex.Item>
  <Flex.Item span={8}>span: 8</Flex.Item>
  <Flex.Item span={8}>span: 8</Flex.Item>
</Flex>

<Flex>
  <Flex.Item span={4}>span: 4</Flex.Item>
  <Flex.Item span={10} offset={4}>
    offset: 4, span: 10
  </Flex.Item>
</Flex>

<Flex>
  <Flex.Item offset={12} span={12}>
    offset: 12, span: 12
  </Flex.Item>
</Flex>
```

### 设置列元素间距

通过 `gutter` 属性可以设置列元素之间的间距，默认间距为 0。

```tsx
<Flex gutter={20}>
  <Flex.Item span={8}>span: 8</Flex.Item>
  <Flex.Item span={8}>span: 8</Flex.Item>
  <Flex.Item span={8}>span: 8</Flex.Item>
</Flex>
```

### 垂直间距 v1.0.2
通过数组形式设置 `[水平间距, 垂直间距]`。`Flex` 默认不换行，使用垂直间距时需要同时设置 `wrap="wrap"`。

```tsx
<Flex gutter={[20, 20]} wrap="wrap">
  <Flex.Item span={12}>span: 12</Flex.Item>
  <Flex.Item span={12}>span: 12</Flex.Item>
  <Flex.Item span={12}>span: 12</Flex.Item>
  <Flex.Item span={12}>span: 12</Flex.Item>
</Flex>
```

### 对齐方式

通过 `justify` 属性可以设置主轴上内容的对齐方式，等价于 flex 布局中的 `justify-content` 属性。

```tsx
<!-- 居中 -->
<Flex justify="center">
  <Flex.Item span={6}>span: 6</Flex.Item>
  <Flex.Item span={6}>span: 6</Flex.Item>
  <Flex.Item span={6}>span: 6</Flex.Item>
</Flex>

<!-- 右对齐 -->
<Flex justify="end">
  <Flex.Item span={6}>span: 6</Flex.Item>
  <Flex.Item span={6}>span: 6</Flex.Item>
  <Flex.Item span={6}>span: 6</Flex.Item>
</Flex>

<!-- 两端对齐 -->
<Flex justify="space-between">
  <Flex.Item span={6}>span: 6</Flex.Item>
  <Flex.Item span={6}>span: 6</Flex.Item>
  <Flex.Item span={6}>span: 6</Flex.Item>
</Flex>

<!-- 每个元素的两侧间隔相等 -->
<Flex justify="space-around">
  <Flex.Item span={6}>span: 6</Flex.Item>
  <Flex.Item span={6}>span: 6</Flex.Item>
  <Flex.Item span={6}>span: 6</Flex.Item>
</Flex>
```

## API

### Flex Props

| 参数        | 说明                                                                 | 类型                                                          | 默认值      |
| --------- | ------------------------------------------------------------------ | ----------------------------------------------------------- | -------- |
| gutter    | 列元素之间的间距，数组第一项为水平间距、第二项为垂直间距（单位为 px）                               | _number \| string \| \[number \| string, number \| string]_ | -        |
| direction | 项目定位方向，可选值为 `row` `row-reverse` `column` `column-reverse`          | _FlexDirection_                                             | `row`    |
| wrap      | 子元素的换行方式，可选值为 `nowrap` `wrap` `wrap-reverse`                       | _FlexWrap_                                                  | `nowrap` |
| justify   | 主轴对齐方式，可选值为 `start` `end` `center` `space-around` `space-between`  | _FlexJustify_                                               | `start`  |
| align     | 交叉轴对齐方式，可选值为 `start` `center` `end` `baseline` `stretch` `initial` | _FlexAlign_                                                 | `start`  |

### Flex.Item Props

| 参数     | 说明      | 类型                 | 默认值 |
| ------ | ------- | ------------------ | --- |
| span   | 列元素宽度   | _number \| string_ | -   |
| offset | 列元素偏移距离 | _number \| string_ | -   |

### 类型定义

组件导出以下类型定义：

```tsx
import type {
  FlexAlign,
  FlexDirection,
  FlexGutter,
  FlexGutterValue,
  FlexItemProps,
  FlexJustify,
  FlexProps,
  FlexWrap,
} from "@taroify/core"
```



---
url: https://taroify.com/components/popup/index.md
---

# Popup 弹出层

### 介绍

弹出层容器，用于展示弹窗、信息提示等内容，支持多个弹出层叠加展示。

### 引入

```tsx
import { Popup } from "@taroify/core"
```

## 代码演示

### 基础用法

通过 `open` 控制弹出层是否展示。

```tsx
const [open, setOpen] = useState(false)

<Popup open={open} onClose={setOpen}>
  内容
</Popup>
```

### 弹出位置

通过 `placement` 属性设置弹出位置，默认居中弹出，可以设置为 `top`、`bottom`、`left`、`right`。

```tsx
<Popup defaultOpen placement="top" style={{ height: "30%" }} />
```

### 关闭图标 v1.0.2
设置 `closeable` 属性后，会在弹出层的右上角显示关闭图标。通过 `closeIcon` 自定义图标，通过 `closeIconPlacement` 设置图标位置。

```tsx
<Popup
  defaultOpen
  closeable
  closeIcon={<Close />}
  closeIconPlacement="bottom-right"
  placement="bottom"
  style={{ height: "30%" }}
/>
```

也可以使用 `Popup.Close` 自定义关闭图标。

```tsx
<Popup defaultOpen placement="bottom" style={{ height: "30%" }}>
  <Popup.Close>
    <Close />
  </Popup.Close>
</Popup>
```

### 遮罩层 v1.0.2
通过 `backdrop` 隐藏遮罩层，或传入对象配置遮罩层属性。`closeOnClickBackdrop` 用于控制点击遮罩层时是否关闭弹出层。

```tsx
<Popup open backdrop={false} />

<Popup
  open
  backdrop={{
    style: {
      backgroundColor: "rgba(0, 0, 0, 0.7)",
    },
  }}
  closeOnClickBackdrop={false}
/>
```

### 关闭前回调 v1.0.2
通过 `beforeClose` 属性可以在关闭前执行同步或异步逻辑，返回 `true` 时关闭，返回其他值或 Promise 被拒绝时保持打开。

```tsx
import type { PopupCloseAction } from "@taroify/core"

function beforeClose(action: PopupCloseAction) {
  return new Promise<boolean>((resolve) => {
    setTimeout(() => resolve(action === "close"), 1000)
  })
}

<Popup open closeable beforeClose={beforeClose} />
```

### 销毁内容 v1.0.2
默认情况下，弹出层关闭后内容仍会保留。设置 `destroyOnClose` 后，内容会在离场动画结束后卸载。

```tsx
<Popup open={open} destroyOnClose>
  <HeavyContent />
</Popup>
```

### 圆角弹窗

设置 `rounded` 属性后，弹窗会根据弹出位置添加不同的圆角样式。

```tsx
<Popup open rounded style={{ padding: "64px" }}>
  内容
</Popup>

<Popup open rounded placement="bottom" style={{ height: "30%" }} />
```

### 禁止滚动穿透

```tsx
<Popup lock>
  <View>无法滑动</View>
</Popup>
```

如果需要内容支持溢出滚动，则需要包裹一层 `ScrollView` 组件。

```tsx
<Popup lock>
  <ScrollView scrollY>可以滑动</ScrollView>
</Popup>
```

## API

### Popup Props

| 参数                                        | 说明                                                              | 类型                                                           | 默认值                 |
| ----------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------ | ------------------- |
| defaultOpen                               | 默认是否显示弹出层                                                       | _boolean_                                                    | `false`             |
| open                                      | 是否显示弹出层                                                         | _boolean_                                                    | `false`             |
| placement                                 | 弹出位置，可选值为 `top` `bottom` `right` `left` `center`                | _PopupPlacement_                                             | `center`            |
| duration                                  | 动画时长，单位毫秒                                                       | _number_                                                     | `300`               |
| rounded                                   | 是否显示圆角                                                          | _boolean_                                                    | `false`             |
| lock                                      | 是否锁定背景滚动                                                        | _boolean_                                                    | `true`              |
| backdrop <Tag tag="v1.0.2" />             | 是否显示遮罩层，或传入遮罩层配置                                                | _boolean \| Omit\<PopupBackdropProps, "open">_               | `true`              |
| closeOnClickBackdrop <Tag tag="v1.0.2" /> | 点击遮罩层时是否关闭弹出层                                                   | _boolean_                                                    | `true`              |
| closeable <Tag tag="v1.0.2" />            | 是否显示关闭图标                                                        | _boolean_                                                    | `false`             |
| closeIcon <Tag tag="v1.0.2" />            | 自定义关闭图标                                                         | _ReactNode_                                                  | `<Cross />`         |
| closeIconPlacement <Tag tag="v1.0.2" />   | 关闭图标位置，可选值为 `top-left` `top-right` `bottom-left` `bottom-right` | _PopupClosePlacement_                                        | `top-right`         |
| beforeClose <Tag tag="v1.0.2" />          | 关闭前的回调函数，返回 `true` 时关闭                                          | _(action: PopupCloseAction) => boolean \| Promise\<boolean>_ | -                   |
| destroyOnClose <Tag tag="v1.0.2" />       | 关闭后是否卸载弹出层内容                                                    | _boolean_                                                    | `false`             |
| mountOnEnter                              | 首次打开时是否挂载弹出层内容                                                  | _boolean_                                                    | `true`              |
| transitionAppear                          | 首次挂载且已打开时是否执行入场动画                                               | _boolean_                                                    | `true`              |
| transition <Tag tag="v1.0.2" />           | 动画名称                                                            | _string_                                                     | 根据 `placement` 自动设置 |
| transitionTimeout <Tag tag="v1.0.2" />    | 动画超时时间，单位毫秒                                                     | _PopupTransitionTimeout_                                     | `duration`          |
| transaction <Tag tag="待废弃" />             | 请使用 `transition`                                                | _string_                                                     | -                   |
| transactionTimeout <Tag tag="待废弃" />      | 请使用 `transitionTimeout`                                         | _PopupTransitionTimeout_                                     | -                   |

动画相关参数继承自 `Transition` 组件，详细属性参见：[Transition 组件](/components/style/index.md#动画)。

| Popup 参数            | Transition 对应参数 |
| ------------------- | --------------- |
| mountOnEnter        | mountOnEnter    |
| transition          | name            |
| transitionAppear    | appear          |
| transitionTimeout   | timeout         |
| onTransitionEnter   | onEnter         |
| onTransitionEntered | onEntered       |
| onTransitionExit    | onExit          |
| onTransitionExited  | onExited        |

### Popup.Backdrop Props

| 参数        | 说明            | 类型              | 默认值    |
| --------- | ------------- | --------------- | ------ |
| className | 遮罩层类名         | _string_        | -      |
| style     | 遮罩层样式         | _CSSProperties_ | -      |
| open      | 是否显示遮罩层       | _boolean_       | `true` |
| closeable | 点击遮罩层后是否关闭弹出层 | _boolean_       | `true` |
| duration  | 动画时长，单位毫秒     | _number_        | `300`  |
| lock      | 是否锁定背景滚动      | _boolean_       | `true` |

### Popup.Close Props

| 参数                           | 说明                                                              | 类型                             | 默认值         |
| ---------------------------- | --------------------------------------------------------------- | ------------------------------ | ----------- |
| placement                    | 关闭图标位置，可选值为 `top-left` `top-right` `bottom-left` `bottom-right` | _PopupClosePlacement_          | `top-right` |
| children                     | 图标内容                                                            | _ReactNode_                    | `<Cross />` |
| onClick <Tag tag="v1.0.2" /> | 点击关闭图标时触发                                                       | _(event: ITouchEvent) => void_ | -           |

### Events

| 事件名                           | 说明              | 回调参数                 |
| ----------------------------- | --------------- | -------------------- |
| onClick                       | 点击弹出层时触发        | _event: ITouchEvent_ |
| onOpen <Tag tag="v1.0.2" />   | 打开弹出层且入场动画开始时触发 | -                    |
| onOpened <Tag tag="v1.0.2" /> | 入场动画结束时触发       | -                    |
| onClose                       | 关闭弹出层时触发        | _opened: boolean_    |
| onClosed <Tag tag="v1.0.2" /> | 离场动画结束时触发       | -                    |

### 类型定义

组件相关类型可从 `@taroify/core` 直接导入：

```tsx
import type {
  PopupBackdropProps,
  PopupCloseAction,
  PopupClosePlacement,
  PopupCloseProps,
  PopupPlacement,
  PopupProps,
  PopupThemeVars,
  PopupTransitionTimeout,
} from "@taroify/core"
```

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                              | 默认值                              | 描述 |
| ------------------------------- | -------------------------------- | -- |
| --popup-z-index                 | _1010_                           | -  |
| --popup-background-color        | _var(--background-color-light)_  | -  |
| --popup-animation-duration      | _var(--animation-duration-base)_ | -  |
| --popup-rounded-border-radius   | _16px \* $hd_                    | -  |
| --popup-close-icon-z-index      | _1_                              | -  |
| --popup-close-icon-size         | _22px \* $hd_                    | -  |
| --popup-close-icon-color        | _var(--gray-5)_                  | -  |
| --popup-close-icon-active-color | _var(--gray-6)_                  | -  |
| --popup-close-icon-margin       | _16px \* $hd_                    | -  |



---
url: https://taroify.com/components/style/index.md
---

# 内置样式

### 介绍

Taroify 中默认包含了一些常用样式，可以直接通过 className 的方式使用。

### 文字省略

当文本内容长度超过容器最大宽度时，自动省略多余的文本。

```jsx
<!-- 最多显示一行 -->
<View className="taroify-ellipsis">这是一段最多显示一行的文字，多余的内容会被省略</View>

<!-- 最多显示两行 -->
<View className="taroify-ellipsis--l2">
  这是一段最多显示两行的文字，多余的内容会被省略
</View>

<!-- 最多显示三行 -->
<View className="taroify-ellipsis--l3">
  这是一段最多显示三行的文字，多余的内容会被省略
</View>
```

### 1px 边框

为元素添加 Retina 屏幕下的 1px 边框（即 hairline），基于伪类 transform 实现。

```jsx
<!-- 上边框 -->
<View className="taroify-hairline--top"></View>

<!-- 下边框 -->
<View className="taroify-hairline--bottom"></View>

<!-- 左边框 -->
<View className="taroify-hairline--left"></View>

<!-- 右边框 -->
<View className="taroify-hairline--right"></View>

<!-- 上下边框 -->
<View className="taroify-hairline--top-bottom"></View>

<!-- 全边框 -->
<View className="taroify-hairline--surround"></View>
```

### 触摸反馈

为元素添加触碰反馈效果，触碰后，元素的透明度会降低。

```tsx
<View className="taroify-haptics-feedback"></View>
```

为元素添加触碰反馈效果，触碰后，元素的背景色会改变。

```tsx
<View className="taroify-click-feedback"></View>
```

### 动画

可以通过 `Transition` 组件使用内置的动画

```jsx
<!-- 淡入 -->
<Transition in={visible} name="fade">
  <View>Fade</View>
</Transition>

<!-- 上滑进入 -->
<Transition in={visible} name="slide-up">
  <View>Slide Up</View>
</Transition>

<!-- 下滑进入 -->
<Transition in={visible} name="slide-down">
  <View>Slide Down</View>
</Transition>

<!-- 左滑进入 -->
<Transition in={visible} name="slide-left">
  <View>Slide Left</View>
</Transition>

<!-- 右滑进入 -->
<Transition in={visible} name="slide-right">
  <View>Slide Right</View>
</Transition>
```

Transition来源于 `react-transition-group` 的 `CSSTransition`,详情请查看其[文档](https://reactcommunity.org/react-transition-group/css-transition)

```tsx
interface TransitionProps {
  name?: TransitionName | string
  in?: boolean
  appear?: boolean
  mountOnEnter?: boolean
  unmountOnExit?: boolean
  timeout?: number | { appear?: number; enter?: number; exit?: number }
  children?: ReactNode
  onEnter?: EnterHandler<HTMLElement>
  onEntering?: EnterHandler<HTMLElement>
  onEntered?: EnterHandler<HTMLElement>
  onExit?: ExitHandler<HTMLElement>
  onExiting?: ExitHandler<HTMLElement>
  onExited?: ExitHandler<HTMLElement>
}
```



---
url: https://taroify.com/components/toast/index.md
---

# Toast 轻提示

### 介绍

在页面中间弹出黑色半透明提示，用于消息通知、加载提示、操作结果提示等场景。

### 函数调用

版本 >= `v0.6.0-alpha.0`可以直接调用。低版本需要手动在页面（page）里挂载一个 Toast 组件并指定 id 为 `toast`。

```tsx
import { Cell, Toast } from "@taroify/core"

function ImperativeToast() {
  return (
    <>
      {/* <Toast id="toast" /> */}
      <Cell title="函数调用" clickable isLink onClick={() => Toast.open("文字提示")} />
    </>
  )
}
```

### 组件调用

```tsx
import { Cell, Toast } from "@taroify/core"

function BasicToast() {
  const [open, setOpen] = useState(false)

  return (
    <>
      <Toast open={open} onClose={setOpen}>
        文字提示
      </Toast>
      <Cell title="基础用法" clickable onClick={() => setOpen(true)} />
    </>
  )
}
```

## 代码演示

### 加载提示

使用 `type="loading"` 方法展示加载提示。

```ts
Toast.open({ type: "loading", message: "加载中..." })}
```

```tsx
<Toast open type="loading">
  加载中...
</Toast>
```

### 成功/失败提示

使用 `type="success"` 展示成功提示，使用 `type="fail"` 展示失败提示。

```ts
Toast.open({ type: "success", message: "成功文案" })
Toast.open({ type: "fail", message: "失败文案" })
```

```tsx
<Toast open type="success">成功文案</Toast>
<Toast open type="fail">失败文案</Toast>
```

### 自定义图标

通过 `icon` 选项可以自定义图标，支持传入[图标名称](/components/icon.md)或图片链接。

```ts
Toast.open({ message: "自定义图标", icon: <LikeOutlined /> })
Toast.open({
  message: "自定义图片",
  icon: (
    <Image
      style={{
        width: "40px",
        height: "40px",
      }}
      src="https://img01.yzcdn.cn/vant/logo.png"
    />
  ),
})
```

```tsx
<Toast open icon={<LikeOutlined />}>自定义图标</Toast>
<Toast
  open
  icon={<Image style={{ width: "1em", height: "1em" }}
  src="https://img01.yzcdn.cn/vant/logo.png" />}
>
  自定义图片
</Toast>
<Toast open icon={<Loading />}>加载中...</Toast>
```

### 自定义位置

Toast 默认渲染在屏幕正中位置，通过 `position` 属性可以控制 Toast 展示的位置。

```ts
Toast.open({
  position: "top",
  message: "顶部展示",
})
Toast.open({
  position: "bottom",
  message: "顶部展示",
})
```

```tsx
<Toast open position="top">顶部展示</Toast>
<Toast open position="bottom">底部展示</Toast>
```

### 多例模式

Toast 默认采用单例模式，即同一时间只会存在一个 Toast。通过调用 `Toast.allowMultiple(true)` 可以在页面中同时存在多个 Toast 实例。

```tsx
import { Cell, Toast } from "@taroify/core"

function MultipleToast() {
  return (
    <>
      <Cell 
        title="允许多个实例" 
        clickable 
        isLink 
        onClick={() => {
          Toast.allowMultiple(true)
          // 同时展示多个 Toast
          Toast.success("成功提示")
          setTimeout(() => {
            Toast.fail("失败提示")
          }, 1000)
        }} 
      />
    </>
  )
}
```

### 关闭特定 Toast 实例

在多例模式下，`Toast.open()`、`Toast.success()`、`Toast.fail()` 和 `Toast.loading()` 方法会返回一个唯一标识符，可以使用该标识符来关闭特定的 Toast 实例。

```tsx
import { Cell, Toast } from "@taroify/core"

function MultipleToastClose() {
  return (
    <>
      <Cell 
        title="关闭特定 Toast 实例" 
        clickable 
        isLink 
        onClick={() => {
          // 启用多例模式
          Toast.allowMultiple(true)
          
          // 创建并保存 Toast 实例标识符
          const toast1 = Toast.success("成功提示")
          const toast2 = Toast.loading("加载中...")
          
          // 3秒后只关闭成功提示，保留加载提示
          setTimeout(() => {
            // 直接使用 close 方法关闭特定的 Toast
            if (toast1) {
              Toast.close(toast1)
            }
          }, 3000)
        }} 
      />
    </>
  )
}
```

## API

### Props

| 参数          | 说明                                             | 类型                         | 默认值      |
| ----------- | ---------------------------------------------- | -------------------------- | -------- |
| defaultOpen | 默认是否显示弹出层                                      | _boolean_                  | `false`  |
| open        | 是否显示弹出层                                        | _boolean_                  | `false`  |
| type        | 提示类型，可选值为 `loading` `success`<br>`fail` `html` | _string_                   | `text`   |
| icon        | 自定义图标，支持传入[图标名称](/components/icon.md)或图片链接     | _ReactNode_                | -        |
| position    | 弹出位置，可选值为 `top` `bottom`                       | _string_                   | `center` |
| duration    | 动画时长，单位毫秒，值为 0 时，toast 不会消失                    | _number \| string_         | `3000`   |
| backdrop    | 是否显示遮罩层                                        | _boolean_                  | `false`  |
| children    | 文本内容                                           | _ReactNode_                | -        |
| onClose     | 关闭时的回调函数                                       | _(open : boolean) => void_ | -        |

### Options

| 参数       | 说明                                                             | 类型                         | 默认值      |
| -------- | -------------------------------------------------------------- | -------------------------- | -------- |
| selector | 自定义节点选择器                                                       | _string_                   | `toast`  |
| type     | 提示类型，可选值为 `loading` `success`<br>`fail` `html`                 | _string_                   | `text`   |
| icon     | 自定义图标，支持传入[图标](/components/icon.md)或[图片](/components/image.md) | _ReactNode_                | -        |
| position | 弹出位置，可选值为 `top` `bottom`                                       | _string_                   | `center` |
| duration | 动画时长，单位毫秒，值为 0 时，toast 不会消失                                    | _number \| string_         | `3000`   |
| backdrop | 是否显示遮罩层                                                        | _boolean_                  | `false`  |
| message  | 文本内容                                                           | _ReactNode_                | -        |
| onClose  | 关闭时的回调函数                                                       | _(open : boolean) => void_ | -        |

### 方法

| 方法名                 | 参数                   | 返回值                   | 介绍                             |
| ------------------- | -------------------- | --------------------- | ------------------------------ |
| Toast.open          | _options \| message_ | _string \| undefined_ | 展示提示，返回 Toast 实例标识符            |
| Toast.loading       | _options \| message_ | _string \| undefined_ | 展示加载提示，返回 Toast 实例标识符          |
| Toast.success       | _options \| message_ | _string \| undefined_ | 展示成功提示，返回 Toast 实例标识符          |
| Toast.fail          | _options \| message_ | _string \| undefined_ | 展示失败提示，返回 Toast 实例标识符          |
| Toast.close         | _selector? \| id?_   | -                     | 关闭提示，不传参时关闭所有提示，传入实例标识符时关闭指定提示 |
| Toast.allowMultiple | _boolean_            | -                     | 允许同时存在多个 Toast 提示，默认为 `false`  |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                               | 默认值                                   | 描述 |
| -------------------------------- | ------------------------------------- | -- |
| --toast-width                    | _88px \* $hd_                         | -  |
| --toast-width                    | _88px \* $hd_                         | -  |
| --toast-min-height               | _88px \* $hd_                         | -  |
| --toast-max-width                | _70%_                                 | -  |
| --toast-padding                  | _var(--padding-md)_                   | -  |
| --toast-font-size                | _var(--font-size-md)_                 | -  |
| --toast-line-height              | _var(--line-height-md)_               | -  |
| --toast-color                    | _var(--white)_                        | -  |
| --toast-background-color         | _rgba(var(--black-rgb), $alpha: 0.7)_ | -  |
| --toast-border-radius            | _var(--border-radius-lg)_             | -  |
| --toast-transition-duration      | _var(--animation-duration-fast)_      | -  |
| --toast-icon-font-size           | _36px \* $hd_                         | -  |
| --toast-icon-color               | _var(--white)_                        | -  |
| --toast-loading-padding          | _3px \* $hd_                          | -  |
| --toast-loading-color            | _var(--white)_                        | -  |
| --toast-text-min-width           | _96px \* $hd_                         | -  |
| --toast-text-padding             | _var(--padding-xs) var(--padding-sm)_ | -  |
| --toast-position-distance        | _20%_                                 | -  |
| --toast-position-top-distance    | _var(--toast-position-distance)_      | -  |
| --toast-position-bottom-distance | _var(--toast-position-distance)_      | -  |



---
url: https://taroify.com/components/space/index.md
---

# Space 间距

### 介绍

设置组件之间的间距。

### 引入

```tsx
import { Button, Space } from "@taroify/core"
```

## 代码演示

### 基础用法

```tsx
<Space>
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
</Space>
```

### 垂直

```tsx
<Block title="垂直">
  <Space direction="vertical" fill>
    <Button color="primary" block>
      主要按钮
    </Button>
    <Button color="primary" block>
      主要按钮
    </Button>
    <Button color="primary" block>
      主要按钮
    </Button>
  </Space>
</Block>
```

### 间距

```tsx
<Space size="large">
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
</Space>
```

### 自定义间距

通过 `size` 设置间距。传入数字时会通过 Taro 的尺寸转换处理；也可以传入带单位的字符串、CSS 变量，或者使用数组分别设置 `[水平间距, 垂直间距]`。

```tsx
<Space size={16}>
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
</Space>
<Space size="32px">
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
</Space>
<Space size="var(--space-gap)">
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
</Space>
<Space size={[16, "32px"]}>
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
</Space>
```

### 分隔符 v1.0.2
通过 `separator` 在相邻子元素之间设置分隔内容。

```tsx
<Space separator="|">
  <Button variant="text" color="primary">编辑</Button>
  <Button variant="text" color="primary">删除</Button>
  <Button variant="text" color="primary">更多</Button>
</Space>
```

### 居中

```tsx
<Space justify="center">
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
</Space>
```

### 不换行

```tsx
<Space wrap="nowrap">
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
  <Button color="primary">主要按钮</Button>
</Space>
```

## API

### Props

| 参数                             | 说明                                                                | 类型               | 默认值          |
| ------------------------------ | ----------------------------------------------------------------- | ---------------- | ------------ |
| direction                      | 排列方向，可选值为 `horizontal` `vertical`                                 | _SpaceDirection_ | `horizontal` |
| size                           | 间距大小，数组依次表示水平和垂直间距                                                | _SpaceSize_      | `small`      |
| wrap                           | 子元素的换行方式，可选值为 `nowrap` `wrap` `wrap-reverse`                      | _SpaceWrap_      | `wrap`       |
| justify                        | 主轴对齐方式，可选值为 `start` `end` `center` `space-around` `space-between` | _SpaceJustify_   | `start`      |
| align                          | 交叉轴对齐方式，可选值为 `start` `center` `end` `baseline` `stretch`          | _SpaceAlign_     | `start`      |
| fill                           | 是否填充整个父元素                                                         | _boolean_        | `false`      |
| separator <Tag tag="v1.0.2" /> | 相邻子元素之间的分隔内容                                                      | _ReactNode_      | -            |

### 类型定义

组件导出以下类型定义：

```ts
import type {
  SpaceAlign,
  SpaceDirection,
  SpaceJustify,
  SpaceProps,
  SpaceSize,
  SpaceSizePreset,
  SpaceSizeValue,
  SpaceThemeVars,
  SpaceWrap,
} from "@taroify/core"
```

`SpaceSize` 支持预设尺寸、数字、带单位的字符串、CSS 变量，以及由这些值组成的数组：

```ts
type SpaceSize =
  | "mini"
  | "small"
  | "medium"
  | "large"
  | number
  | string
  | [number | string, (number | string)?]
```

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                 | 默认值                            | 描述 |
| ---------------------------------- | ------------------------------ | -- |
| --space-item-gap-mini              | _var(--padding-xs)_            | -  |
| --space-item-gap-small             | _var(--padding-sm)_            | -  |
| --space-item-gap-medium            | _var(--padding-md)_            | -  |
| --space-item-gap-large             | _var(--padding-lg)_            | -  |
| --space-item-vertical-gap-mini     | _var(--space-item-gap-mini)_   | -  |
| --space-item-vertical-gap-small    | _var(--space-item-gap-small)_  | -  |
| --space-item-vertical-gap-medium   | _var(--space-item-gap-medium)_ | -  |
| --space-item-vertical-gap-large    | _var(--space-item-gap-large)_  | -  |
| --space-item-horizontal-gap-mini   | _var(--space-item-gap-mini)_   | -  |
| --space-item-horizontal-gap-small  | _var(--space-item-gap-small)_  | -  |
| --space-item-horizontal-gap-medium | _var(--space-item-gap-medium)_ | -  |
| --space-item-horizontal-gap-large  | _var(--space-item-gap-large)_  | -  |



---
url: https://taroify.com/components/safe-area/index.md
---

# SafeArea 安全区

### 介绍

用于将其内容放置在视口的安全区域中。

### 引入

```tsx
import { SafeArea } from "@taroify/core"
```

## 代码演示

### 基础用法

```tsx
<SafeArea position="top" />
<View>{lorem.generateParagraphs(10)}</View>
<SafeArea position="bottom" />
```

## API

### SafeArea Props

| 参数            | 说明                         | 类型        | 默认值     |
| ------------- | -------------------------- | --------- | ------- |
| position      | 安全区的位置，可选值为 `top` `bottom` | _string_  | -       |
| nativeSafeTop | 是否启用顶部安全区域原生属性             | _boolean_ | `false` |



---
url: https://taroify.com/components/fixed-view/index.md
---

# FixedView 固定视图

### 介绍

用于固定在顶部或底部的视图。

## 代码演示

### 基础用法

```tsx
<FixedView position="top">固定在顶部</FixedView>
<FixedView position="bottom">固定在底部</FixedView>
```

## API

### Props

| 参数            | 说明                        | 类型        | 默认值     |
| ------------- | ------------------------- | --------- | ------- |
| position      | 固定位置，可选值 `top` `bottom`   | _string_  | -       |
| safeArea      | 安全区域，可选值 `top` `bottom`   | _string_  | -       |
| nativeSafeTop | 是否启用顶部安全区域原生属性            | _boolean_ | `false` |
| placeholder   | 固定在底部时，是否在标签位置生成一个等高的占位元素 | _boolean_ | -       |



---
url: https://taroify.com/components/cascader/index.md
---

# Cascader 级联选择

### 介绍

级联选择框，用于多层级数据的选择，典型场景为省市区选择。

### 引入

```tsx
import { Cascader } from "@taroify/core"
```

## 代码演示

### 基础用法

级联选择组件可以搭配 Field 和 Popup 组件使用，示例如下：

```tsx
import { Cascader, Field, Popup } from "@taroify/core"
import { ArrowRight } from "@taroify/icons"
import { useState } from "react"

const dept = [
  {
    label: "研发中心",
    value: "1",
    children: [
      {
        label: "产线1",
        value: "1-1",
        children: [
          {
            label: "研发",
            value: "1-1-1",
          },
          {
            label: "测试",
            value: "1-1-2",
          },
          {
            label: "产品",
            value: "1-1-3",
          },
        ],
      },
      {
        label: "产线2",
        value: "1-2",
      },
    ],
  },
  {
    label: "客户中心",
    value: "2",
    children: [
      {
        label: "客服",
        value: "2-1",
      },
      {
        label: "销售",
        value: "2-2",
      },
    ],
  },
]

function BasicCascader() {
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState<string[]>([])
  const [fieldValue, setFieldValue] = useState("")
  return (
    <>
      <Field label="选项值" isLink onClick={() => setOpen(true)}>
        <Input readonly placeholder="请选择部门" value={fieldValue} />
      </Field>
      <Popup open={open} rounded placement="bottom" onClose={setOpen}>
        <Popup.Close />
        <Cascader
          options={dept}
          value={value}
          title="请选择部门"
          placeholder="请选择"
          onSelect={setValue}
          onChange={(_values_, options) => {
            setOpen(false)
            setFieldValue(options.map((item) => item.children).join("/"))
          }}
        />
      </Popup>
    </>
  )
}
```

### 自定义颜色

通过 CSS 变量来设置选中状态的高亮颜色。

```tsx
<Cascader className="custom-color" />
```

```scss
.custom-color {
  --tabs-active-color: red;
  --cascader-active-color: red;
}
```

### 标题栏与关闭按钮 v1.0.3
设置 `closeable` 后展示关闭按钮，点击时触发 `onClose`。通过 `closeIcon` 可以自定义关闭图标；通过
`showHeader={false}` 可以隐藏整个标题栏。

```tsx
import { Cross } from "@taroify/icons"

<Cascader
  title="请选择部门"
  closeable
  closeIcon={<Cross />}
  onClose={() => setOpen(false)}
/>

<Cascader options={dept} showHeader={false} />
```

### 异步加载选项

通过 loadData 返回下一级的选项，返回空数组\[]时结束触发 onChange

```tsx
export const dynamic = [
  {
    label: "产品",
    value: "1",
  },
  {
    label: "测试",
    value: "2",
  },
  {
    label: "研发",
    value: "3",
  },
]

function DynamicCascader() {
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState<string[]>([])
  const [fieldValue, setFieldValue] = useState("")
  return (
    <>
      <Field label="选项值" isLink onClick={() => setOpen(true)}>
        <Input readonly placeholder="请选择" value={fieldValue} />
      </Field>
      <Popup open={open} rounded placement="bottom" onClose={setOpen}>
        <Popup.Close />
        <Cascader
          options={dynamic}
          loadData={(_values_) => {
            const len = _values_.length
            return new Promise((resolve) => {
              resolve(
                len > 3
                  ? []
                  : [
                      { label: `动态${len}-1`, value: Math.random() },
                      { label: `动态${len}-2`, value: Math.random() },
                    ],
              )
            })
          }}
          title="请选择"
          swipeable
          value={value}
          onSelect={setValue}
          onChange={(_values_, options) => {
            setOpen(false)
            setFieldValue(options.map((item) => item.children).join("/"))
          }}
        />
      </Popup>
    </>
  )
}
```

> Tips: 数据量大时，可关闭 animated，swipeable，避免卡顿

### 自定义选项内容 v1.0.3
数据模式下可以通过 `renderOption` 自定义选项内容，通过 `renderOptionsTop` 和
`renderOptionsBottom` 在每一级选项的上方、下方插入内容。回调中的 `option` 和 `options`
均为传入的原始数据。

```tsx
import { View } from "@tarojs/components"

<Cascader
  options={dept}
  renderOption={({ option, selected, tabIndex }) => (
    <View className={selected ? "option-active" : undefined}>
      {tabIndex + 1}. {option.label}
    </View>
  )}
  renderOptionsTop={({ options, tabIndex }) => (
    <View className="level-tip">
      第 {tabIndex + 1} 级，共 {options.length} 项
    </View>
  )}
  renderOptionsBottom={({ tabIndex }) => (
    <View className="level-tip">已展示第 {tabIndex + 1} 级全部选项</View>
  )}
/>
```

### 自动定位选中项 v1.0.3
设置 `autoScrollToSelected` 后，切换标签时会自动将该级已选中的选项滚动到可视区域。该功能默认关闭，
不会改变已有页面的滚动行为。使用较长的同级选项列表可以直观看到定位效果。

```tsx
<Cascader
  options={dept}
  defaultValue={["1", "1-1", "1-1-1"]}
  autoScrollToSelected
/>
```

### 自定义字段名

```tsx
const fieldNames = {
  label: "name",
  value: "code",
  children: "data",
}
function CustomFieldCascader() {
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState<string[]>([])
  const [fieldValue, setFieldValue] = useState("")
  return (
    <>
      <Field label="选项值" isLink onClick={() => setOpen(true)}>
        <Input readonly placeholder="请选择地区" value={fieldValue} />
      </Field>
      <Popup open={open} rounded placement="bottom" onClose={setOpen}>
        <Popup.Close />
        <Cascader
          options={customArea}
          fieldNames={fieldNames}
          value={value}
          title="请选择地区"
          placeholder="请选择"
          onSelect={setValue}
          onChange={(_values_, options) => {
            setOpen(false)
            setFieldValue(options.map((item) => item.children).join("/"))
          }}
        />
      </Popup>
    </>
  )
}
```

### 手动控制 DOM

可以通过 `Cascader.Header`, `Cascader.Tab`, `Cascader.Option`，配合 `useCascader` 自己控制 DOM

```tsx
import { Cascader, Field, Popup } from "@taroify/core"
import { ArrowRight } from "@taroify/icons"
import { useState } from "react"
import { useCascader } from "@taroify/hooks"

function BasicCascader() {
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState<string[]>([])
  const [fieldValue, setFieldValue] = useState("")
  const { columns } = useCascader({ value, depth: 3, options: area })
  return (
    <>
      <Field label="选项值" isLink onClick={() => setOpen(true)}>
        <Input readonly placeholder="请选择地区" value={fieldValue} />
      </Field>
      <Popup open={open} rounded placement="bottom" onClose={setOpen}>
        <Popup.Close />
        <Cascader
          value={value}
          onSelect={setValue}
          onChange={(_values_, options) => {
            setOpen(false)
            setFieldValue(options.map((item) => item.children).join("/"))
          }}
        >
          <Cascader.Header>请选择所在地区</Cascader.Header>
          {columns.map((options, index) => (
            <Cascader.Tab key={index}>
              {options.map((option) => (
                <Cascader.Option key={option.value} value={option.value}>
                  {option.label}
                </Cascader.Option>
              ))}
            </Cascader.Tab>
          ))}
        </Cascader>
      </Popup>
    </>
  )
}
```

通过改变 selected.children，同样可以动态加载选项

```tsx
const onSelect = (_value) => {
  const level = _value.length - 1
  const selected = columns[level].find((item) => item.value === _value[level])
  if (selected && level < depth - 1) {
    selected.children = [
      { label: `动态${level}-1`, value: Math.random() },
      { label: `动态${level}-2`, value: Math.random() },
    ]
  }

  setValue(_value)
}
```

## API

### Cascader Props

| 参数                                        | 说明                                | 类型                                                                         | 默认值                                                        |
| ----------------------------------------- | --------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------- |
| value                                     | 选中项的值                             | _string\[]_                                                                | -                                                          |
| placeholder                               | 未选中时的提示文案                         | _ReactNode_                                                                | `请选择`                                                      |
| title                                     | 顶部标题                              | _ReactNode_                                                                | -                                                          |
| showHeader <Tag tag="v1.0.3" />           | 是否显示标题栏，未设置时根据标题、Header 或关闭按钮自动判断 | _boolean_                                                                  | -                                                          |
| closeable <Tag tag="v1.0.3" />            | 是否显示关闭按钮                          | _boolean_                                                                  | `false`                                                    |
| closeIcon <Tag tag="v1.0.3" />            | 自定义关闭图标                           | _ReactNode_                                                                | `<Cross />`                                                |
| swipeable                                 | 是否开启手势左右滑动切换                      | _boolean_                                                                  | `false`                                                    |
| animated                                  | 是否开启动过渡动画                         | _boolean_                                                                  | `true`                                                     |
| options                                   | 可选项数据源                            | _CascaderDataOption\[]_                                                    | `[]`                                                       |
| loadData                                  | 动态加载数据                            | _(values: string\[], options: CascaderEventOption\[]) => Promise\<any\[]>_ | -                                                          |
| fieldNames                                | 自定义 options 结构中的字段                | _CascaderFieldNames_                                                       | `{ label: 'label', value: 'value', children: 'children' }` |
| ellipsis                                  | 是否省略过长的标题文字                       | _boolean_                                                                  | `true`                                                     |
| autoScrollToSelected <Tag tag="v1.0.3" /> | 切换标签时是否自动定位该级选中项                  | _boolean_                                                                  | `false`                                                    |
| renderOption <Tag tag="v1.0.3" />         | 自定义数据模式下的选项内容                     | _(props: CascaderOptionRenderProps) => ReactNode_                          | -                                                          |
| renderOptionsTop <Tag tag="v1.0.3" />     | 自定义每级选项列表上方内容                     | _(props: CascaderOptionsRenderProps) => ReactNode_                         | -                                                          |
| renderOptionsBottom <Tag tag="v1.0.3" />  | 自定义每级选项列表下方内容                     | _(props: CascaderOptionsRenderProps) => ReactNode_                         | -                                                          |

### Cascader Events

| 事件                           | 说明          | 回调参数                                              |
| ---------------------------- | ----------- | ------------------------------------------------- |
| onSelect                     | 选中项变化时触发    | _values: any\[], options: CascaderEventOption\[]_ |
| onChange                     | 全部选项选择完成后触发 | _values: any\[], options: CascaderEventOption\[]_ |
| onTabClick                   | 点击标签时触发     | _event: Tabs.TabEvent_                            |
| onClose <Tag tag="v1.0.3" /> | 点击关闭按钮时触发   | _event: ITouchEvent_                              |

### Cascader.Header Props

| 参数       | 说明   | 类型         | 默认值 |
| -------- | ---- | ---------- | --- |
| children | 头部内容 | _ReactNoe_ | -   |

### Cascader.Tab Props

| 参数       | 说明    | 类型         | 默认值 |
| -------- | ----- | ---------- | --- |
| children | 子选项列表 | _ReactNoe_ | -   |

### Cascader.Option Props

| 参数       | 说明         | 类型                 | 默认值     |
| -------- | ---------- | ------------------ | ------- |
| children | 选项内容（必填）   | _ReactNoe_         | -       |
| value    | 选项对应的值（必填） | _string \| number_ | -       |
| disabled | 是否禁用选项     | _boolean_          | `false` |

### 类型定义

通过`@taroify/core/cascader`导入类型

```tsx
import type {
  CascaderDataOption,
  CascaderEventOption,
  CascaderFieldNames,
  CascaderOptionRenderProps,
  CascaderOptionsRenderProps,
} from "@taroify/core/cascader"
```

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                               | 默认值                             | 描述 |
| ------------------------------------------------ | ------------------------------- | -- |
| --cascader-active-color                          | _var(--blue, $blue)_            | -  |
| --cascader-header-height                         | _48px \* $hd_                   | -  |
| --cascader-header-padding                        | _0 var(--padding-md)_           | -  |
| --cascader-header-font-size                      | _var(--font-size-lg)_           | -  |
| --cascader-header-font-weight                    | _var(--font-weight-bold)_       | -  |
| --cascader-header-line-height                    | _20px \* $hd_                   | -  |
| --cascader-close-icon-size <Tag tag="v1.0.3" />  | _22px \* $hd_                   | -  |
| --cascader-close-icon-color <Tag tag="v1.0.3" /> | _var(--gray-5)_                 | -  |
| --cascader-tabs-height                           | _48px \* $hd_                   | -  |
| --cascader-tab-font-weight                       | _var(--font-weight-bold)_       | -  |
| --cascader-tab-color                             | _var(--text-color)_             | -  |
| --cascader-inactive-tab-color                    | _var(--gray-6)_                 | -  |
| --cascader-options-height                        | _384px \* $hd_                  | -  |
| --cascader-option-padding                        | _10px \* $hd var(--padding-md)_ | -  |
| --cascader-option-font-size                      | _var(--font-size-md)_           | -  |
| --cascader-option-line-height                    | _var(--line-height-md)_         | -  |
| --cascader-option-active-background-color        | _var(--active-color)_           | -  |
| --cascader-disabled-option-color                 | _var(--gray-5)_                 | -  |
| --cascader-active-option-color                   | _var(--cascader-active-color)_  | -  |
| --cascader-active-option-font-weight             | _var(--font-weight-bold)_       | -  |
| --cascader-active-icon-font-size                 | _18px \* $hd_                   | -  |



---
url: https://taroify.com/components/calendar/index.md
---

# Calendar 日历

### 介绍

日历组件用于选择日期或日期区间。如要以弹层形式展示， 请使用 poppable，不要手动嵌套

### 引入

```tsx
import { Calendar } from "@taroify/core"
```

## 代码演示

### 选择单个日期

下面演示了结合单元格来使用日历组件的用法，日期选择完成后会触发 `onConfirm` 事件。

```tsx
function formatFullDate(date?: Date) {
  if (date) {
    return `${date.getFullYear()}/${formatDate(date)}`
  }
}

function SingleCalendar() {
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState<Date>()
  const [formatValue, setFormatValue] = useState<string>()

  return (
    <>
      <Cell title="选择单个日期" isLink children={formatValue} onClick={() => setOpen(true)} />
      <Calendar
        type="single"
        value={value}
        poppable
        showPopup={open}
        onClose={setOpen}
        onChange={setValue}
        onConfirm={(newValue) => {
          setOpen(false)
          setFormatValue(formatFullDate(newValue))
        }}
      ></Calendar>
    </>
  )
}
```

### 选择多个日期

设置 `type` 为 `multiple` 后可以选择多个日期，此时 `onConfirm` 事件处理 value 数组结构，数组包含若干个选中的日期。

```tsx
function formatMultiple(dates: Date[]) {
  if (dates.length) {
    return `选择了 ${dates.length} 个日期`
  }
}

function MultipleCalendar() {
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState<Date[]>()
  const [formatValue, setFormatValue] = useState<string>()

  return (
    <>
      <Cell title="选择多个日期" isLink children={formatValue} onClick={() => setOpen(true)} />
      <Calendar
        type="multiple"
        value={value}
        poppable
        showPopup={open}
        onClose={setOpen}
        onChange={setValue}
        onConfirm={(newValue) => {
          setFormatValue(formatMultiple(newValue))
          setOpen(false)
        }}
      ></Calendar>
    </>
  )
}
```

### 选择日期区间

设置 `type` 为 `range` 后可以选择日期区间，此时 `onConfirm` 事件处理 value 数组结构，数组第一项为开始时间，第二项为结束时间。

```tsx
function formatRange(dateRange: Date[]) {
  if (dateRange.length) {
    const [start, end] = dateRange
    return `${formatDate(start)} - ${formatDate(end)}`
  }
}

function RangeCalendar() {
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState<Date[]>()
  const [formatValue, setFormatValue] = useState<string>()

  return (
    <>
      <Cell title="选择日期区间" isLink children={formatValue} onClick={() => setOpen(true)} />
      <Calendar
        type="range"
        value={value}
        onChange={setValue}
        poppable
        showPopup={open}
        onClose={setOpen}
        onConfirm={(newValue) => {
          setFormatValue(formatRange(newValue))
          setOpen(false)
        }}
      ></Calendar>
    </>
  )
}
```

### 快捷选择

将 `showConfirm` 设置为 `false` 可以隐藏确认按钮，这种情况下选择完成后会立即触发 confirm 事件。

```tsx
function SingleQuicklyCalendar() {
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState<Date>()
  const [formatValue, setFormatValue] = useState<string>()

  return (
    <>
      <Cell title="选择单个日期" isLink children={formatValue} onClick={() => setOpen(true)} />
      <Calendar
        type="single"
        value={value}
        onChange={setValue}
        poppable
        showPopup={open}
        showConfirm={false}
        onClose={setOpen}
        onConfirm={(newValue) => {
          setFormatValue(formatFullDate(newValue))
          setOpen(false)
        }}
      />
    </>
  )
}
```

### 自定义颜色

通过 `css` 可以自定义日历的颜色，对选中日期和底部按钮生效。

```tsx
<Calendar style={{ "--calendar-active-color": "red" }} />
```

### 自定义日期范围

通过 `min` 和 `max` 定义日历的范围。

```tsx
function CustomRangeCalendar() {
  const [minDate] = useState(new Date(2010, 0, 1))
  const [maxDate] = useState(new Date(2010, 0, 31))
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState<Date[]>()
  const [formatValue, setFormatValue] = useState<string>()

  return (
    <>
      <Cell title="自定义日期范围" isLink children={formatValue} onClick={() => setOpen(true)} />
      <Calendar
        type="range"
        min={minDate}
        max={maxDate}
        value={value}
        onChange={setValue}
        poppable
        showPopup={open}
        onClose={setOpen}
        onConfirm={(newValue) => {
          setFormatValue(formatRange(newValue))
          setOpen(false)
        }}
      ></Calendar>
    </>
  )
}
```

### 自定义按钮文字

通过 `confirmText` 设置按钮文字，通过 `confirmDisabledText` 设置按钮禁用时的文字。

```tsx
function CustomConfirmCalendar() {
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState<Date[]>()
  const [formatValue, setFormatValue] = useState<string>()

  return (
    <>
      <Cell title="自定义按钮" isLink children={formatValue} onClick={() => setOpen(true)} />
      <Calendar
        type="range"
        value={value}
        onChange={(newValue) => {
          setValue(newValue)
        }}
        poppable
        showPopup={open}
        confirmDisabledText="请选择结束时间"
        onClose={setOpen}
        onConfirm={(newValue) => {
          setFormatValue(formatRange(newValue))
          setOpen(false)
        }}
      ></Calendar>
    </>
  )
}
```

### 自定义日期文案

通过传入 `formatter` 函数来对日历上每一格的内容进行格式化。

```tsx
const dayFormatter = (day: Calendar.DayObject) => {
  if (!day.value) {
    return day
  }

  const month = day.value.getMonth() + 1
  const date = day.value.getDate()

  if (month === 5) {
    if (date === 1) {
      day.top = "劳动节"
    } else if (date === 4) {
      day.top = "青年节"
    } else if (date === 11) {
      day.children = "今天"
    }
  }

  if (day.type === "start") {
    day.bottom = "入店"
  } else if (day.type === "end") {
    day.bottom = "离店"
  } else if (day.type === "active") {
    day.bottom = "入店/离店"
  }

  return day
}

function CustomDayCalendar() {
  const [open, setOpen] = useState(false)
  const [minDate] = useState(new Date(2010, 4, 1))
  const [maxDate] = useState(new Date(2010, 4, 31))
  const [value, setValue] = useState<Date[]>()
  const [formatValue, setFormatValue] = useState<string>()

  return (
    <>
      <Cell title="自定义日期文案" isLink children={formatValue} onClick={() => setOpen(true)} />
      <Calendar
        type="range"
        min={minDate}
        max={maxDate}
        formatter={dayFormatter}
        value={value}
        onChange={setValue}
        poppable
        showPopup={open}
        onClose={setOpen}
        onConfirm={(newValue) => {
          setFormatValue(formatRange(newValue))
          setOpen(false)
        }}
      ></Calendar>
    </>
  )
}
```

### 自定义弹出位置

通过 `placement` 属性自定义弹出层的弹出位置，可选值为 `top`、`left`、`right`。

```tsx
function CustomPositionCalendar() {
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState<Date>()
  const [formatValue, setFormatValue] = useState<string>()

  return (
    <>
      <Cell title="自定义弹出位置" isLink children={formatValue} onClick={() => setOpen(true)} />
      <Calendar
        popupPlacement="right"
        type="single"
        value={value}
        onChange={setValue}
        poppable
        showPopup={open}
        onClose={setOpen}
        onConfirm={(newValue) => {
          setFormatValue(formatFullDate(newValue))
          setOpen(false)
        }}
      ></Calendar>
    </>
  )
}
```

### 自定义周起始日

通过 `firstDayOfWeek` 属性设置一周从哪天开始。

```tsx
function CustomFirstDayOfWeekCalendar() {
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState<Date>()
  const [formatValue, setFormatValue] = useState<string>()

  return (
    <>
      <Cell title="自定义周起始日" isLink children={formatValue} onClick={() => setOpen(true)} />
      <Calendar
        popupCloseIcon={false}
        popupRounded={false}
        type="single"
        value={value}
        onChange={setValue}
        poppable
        showPopup={open}
        onClose={setOpen}
        firstDayOfWeek={1}
        onConfirm={(newValue) => {
          setFormatValue(formatFullDate(newValue))
          setOpen(false)
        }}
      ></Calendar>
    </>
  )
}
```

### 平铺展示

将 `poppable` 设置为 `false`，日历会直接展示在页面内，而不是以弹层的形式出现。

```tsx
function TiledCalendar() {
  const [minDate] = useState(new Date(2012, 1, 10))
  const [maxDate] = useState(new Date(2012, 10, 20))
  const [value, setValue] = useState<Date>()
  return (
    <Calendar
      style={{ height: "500px" }}
      title="日历"
      min={minDate}
      max={maxDate}
      value={value}
      onChange={setValue}
    />
  )
}
```

### 手动控制 Footer DOM

通过 `Calendar.Footer` `Calendar.Button` 手动控制 Footer DOM。

```tsx
function CustomConfirmCalendar() {
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState<Date[]>()
  const [confirm, setConfirm] = useState("请选择结束时间")
  const [formatValue, setFormatValue] = useState<string>()

  return (
    <>
      <Cell title="自定义按钮" isLink children={formatValue} onClick={() => setOpen(true)} />
      <Calendar
        type="range"
        value={value}
        onChange={(newValue) => {
          setValue(newValue)
          setConfirm(newValue.length === 2 ? "完成" : "请选择结束时间")
        }}
        poppable
        showPopup={open}
        onClose={setOpen}
        onConfirm={(newValue) => {
          setFormatValue(formatRange(newValue))
          setOpen(false)
        }}
      >
        <Calendar.Footer>
          <Calendar.Button type="confirm">{confirm}</Calendar.Button>
        </Calendar.Footer>
      </Calendar>
    </>
  )
}
```

## API

### Props

| 参数                  | 说明                                                                      | 类型                                                | 默认值                                                           |
| ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------- |
| type                | 选择类型:<br>`single` 表示选择单个日期，<br>`multiple` 表示选择多个日期，<br>`range` 表示选择日期区间 | _string_                                          | `single`                                                      |
| defaultValue        | 默认选中的日期，`type` 为 `multiple` 或 `range` 时为数组，传入 `null` 表示默认不选择            | _Date \| Date\[] \| null_                         | 今天                                                            |
| value               | 选中的日期，`type` 为 `multiple` 或 `range` 时为数组，传入 `null` 表示默认不选择              | _Date \| Date\[] \| null_                         | 今天                                                            |
| formatter           | 日期格式化函数                                                                 | _(day: Calendar.DayObject) => Calendar.DayObject_ | -                                                             |
| title               | 日历标题                                                                    | _ReactNode_                                       | `日期选择`                                                        |
| showSubtitle        | 是否展示日历副标题（年月）                                                           | _boolean_                                         | `true`                                                        |
| subtitle            | 自定义日历副标题                                                                | _ReactNode\|((date: Date) => ReactNode)_          | (date) => \`$\{date.getFullYear()}年$\{date.getMonth() + 1}月\` |
| watermark           | 是否显示月份背景水印                                                              | _boolean_                                         | `true`                                                        |
| min                 | 可选择的最小日期                                                                | _Date_                                            | 当前日期                                                          |
| max                 | 可选择的最大日期                                                                | _Date_                                            | 当前日期的六个月后                                                     |
| poppable            | 是否以弹层的形式展示日历                                                            | _boolean_                                         | `false`                                                       |
| showPopup           | 是否显示日历弹窗, poppable: true 时生效                                            | _boolean_                                         | `false`                                                       |
| popupPlacement      | 弹出位置，可选值为 `left` `right` `top` , poppable: true 时生效                     | _string_                                          | `bottom`                                                      |
| popupRound          | 是否显示圆角弹窗, poppable: true 时生效                                            | _boolean_                                         | `true`                                                        |
| popupCloseIcon      | 弹框是否显示关闭图标, poppable: true 时生效                                          | _boolean_                                         | `true`                                                        |
| readonly            | 是否为只读状态，只读状态下不能选择日期                                                     | _boolean_                                         | `false`                                                       |
| showConfirm         | 是否展示确认按钮                                                                | _boolean_                                         | `true`                                                        |
| confirmText         | 确认按钮的文字                                                                 | _ReactNode_                                       | `确认`                                                          |
| confirmDisabledText | 确认按钮处于禁用状态时的文字                                                          | _ReactNode_                                       | `确认`                                                          |
| firstDayOfWeek      | 设置周起始日                                                                  | _0-6_                                             | `0`                                                           |

### Calendar.DayObject 数据结构

日历中的每个日期都对应一个 Day 对象，通过`formatter`属性可以自定义 Day 对象的内容

| 键名        | 说明                                                   | 类型       |
| --------- | ---------------------------------------------------- | -------- |
| value     | 日期对应的 Date 对象                                        | _Date_   |
| type      | 日期类型，可选值为 `active` `start` `middle` `end` `disabled` | _string_ |
| children  | 中间显示的文字                                              | _string_ |
| top       | 上方的提示信息                                              | _string_ |
| bottom    | 下方的提示信息                                              | _string_ |
| className | 额外类名                                                 | _string_ |

### Events

| 事件名       | 说明                                            | 回调参数                     |
| --------- | --------------------------------------------- | ------------------------ |
| onChange  | 点击并选中任意日期时触发                                  | _value: Date \| Date\[]_ |
| onConfirm | 日期选择完成后触发，若使用 `Calendar.Button` 组件，则点击确认按钮后触发 | _value: Date \| Date\[]_ |
| onClose   | 关闭弹层时出发                                       | _visible: boolean_       |

### Calendar.Footer Props

| 参数       | 说明   | 类型         | 默认值 |
| -------- | ---- | ---------- | --- |
| children | 底部内容 | _ReactNoe_ | -   |

### Calendar.Button Props

| 参数                  | 说明             | 类型          | 默认值       |
| ------------------- | -------------- | ----------- | --------- |
| children            | 按钮内容           | _ReactNoe_  | 确认        |
| type                | 按钮类型           | _confirm_   | `confirm` |
| confirmText         | 确认按钮的文字        | _ReactNode_ | -         |
| confirmDisabledText | 确认按钮处于禁用状态时的文字 | _ReactNode_ | -         |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                         | 默认值                                                  | 描述 |
| ------------------------------------------ | ---------------------------------------------------- | -- |
| --calendar-active-color                    | _var(--blue, $blue)_                                 | -  |
| --calendar-background-color                | _var(--white)_                                       | -  |
| --calendar-header-box-shadow               | _0 2px \* $hd 10px \* $hd rgba(125, 126, 128, 0.16)_ | -  |
| --calendar-header-title-height             | _44px \* $hd_                                        | -  |
| --calendar-header-title-font-size          | _var(--font-size-lg)_                                | -  |
| --calendar-header-subtitle-font-size       | _var(--font-size-md)_                                | -  |
| --calendar-weekdays-height                 | _30px \* $hd_                                        | -  |
| --calendar-weekdays-font-size              | _var(--font-size-sm)_                                | -  |
| --calendar-month-title-font-size           | _var(--font-size-md)_                                | -  |
| --calendar-month-watermark-color           | _rgba(242, 243, 245, 0.8)_                           | -  |
| --calendar-month-watermark-font-size       | _160px \* $hd_                                       | -  |
| --calendar-range-edge-color                | _var(--white)_                                       | -  |
| --calendar-range-edge-background-color     | _var(--calendar-active-color)_                       | -  |
| --calendar-range-middle-color              | _var(--calendar-active-color)_                       | -  |
| --calendar-range-middle-background-opacity | _0.1_                                                | -  |
| --calendar-day-height                      | _64px \* $hd_                                        | -  |
| --calendar-day-font-size                   | _var(--font-size-lg)_                                | -  |
| --calendar-day-disabled-color              | _var(--gray-5)_                                      | -  |
| --calendar-active-day-size                 | _54px \* $hd_                                        | -  |
| --calendar-active-day-color                | _var(--white)_                                       | -  |
| --calendar-active-day-background-color     | _var(--calendar-active-color)_                       | -  |
| --calendar-active-day-border-radius        | _var(--border-radius-md)_                            | -  |
| --calendar-day-info-font-size              | _var(--font-size-xs)_                                | -  |
| --calendar-day-info-line-height            | _var(--line-height-xs)_                              | -  |
| --calendar-confirm-button-height           | _36px \* $hd_                                        | -  |
| --calendar-confirm-button-margin           | _7px \* $hd 0_                                       | -  |
| --calendar-confirm-button-color            | _var(--calendar-active-color)_                       | -  |
| --calendar-footer-padding                  | _0 var(--padding-md)_                                | -  |



---
url: https://taroify.com/components/checkbox/index.md
---

# Checkbox 复选框

### 介绍

在一组备选项中进行多选。

### 引入

```tsx
import { Checkbox } from "@taroify/core"
```

## 代码演示

### 基础用法

通过 `checked` 绑定复选框的勾选状态。

```tsx
<Checkbox>复选框</Checkbox>
```

### 禁用状态

通过设置 `disabled` 属性可以禁用复选框。

```tsx
<Checkbox disabled checked={false}>复选框</Checkbox>
<Checkbox disabled checked>复选框</Checkbox>
```

### 自定义形状

将 `shape` 属性设置为 `square`，复选框的形状会变成方形。

```tsx
<Checkbox shape="square">自定义形状</Checkbox>
```

### 按钮形状

将 `shape` 属性设置为 `button`，复选框会变成适合规格选择等场景的按钮。按钮形状下，`icon` 和 `size` 属性不生效。

```tsx
<Checkbox.Group defaultValue={["a"]} direction="horizontal">
  <Checkbox name="a" shape="button">复选框 a</Checkbox>
  <Checkbox name="b" shape="button">复选框 b</Checkbox>
</Checkbox.Group>
```

### 自定义颜色

通过 `css` 设置选中状态的图标颜色。

```tsx
<Checkbox className="custom-color">
  自定义颜色
</Checkbox>
```

```scss
.custom-color {
  --checkbox-checked-icon-border-color: #ee0a24;
  --checkbox-checked-icon-background-color: #ee0a24;
}
```

### 自定义大小

通过 `size` 属性可以自定义图标的大小。

```tsx
<Checkbox size={24}>自定义大小</Checkbox>
```

### 自定义图标

通过 `icon` 属性自定义图标。

```tsx
function CheckboxWithCustomIcon() {
  const [value, setValue] = useState(false)

  return (
    <Checkbox
      icon={
        <Image
          src={`https://img.yzcdn.cn/vant/user-${value ? "active" : "inactive"}.png`}
          style={{
            width: "25px",
            height: "20px",
          }}
        />
      }
      checked={value}
      onChange={setValue}
    >
      自定义图标
    </Checkbox>
  )
}
```

### 复选框组

复选框可以与复选框组一起使用，复选框组通过 `value` 数组绑定复选框的勾选状态。

```tsx
<Checkbox.Group>
  <Checkbox name="a">复选框 a</Checkbox>
  <Checkbox name="b">复选框 b</Checkbox>
</Checkbox.Group>
```

### 水平排列

将 `direction` 属性设置为 `horizontal` 后，复选框组会变成水平排列。

```tsx
<Checkbox.Group direction="horizontal">
  <Checkbox name="a">复选框 a</Checkbox>
  <Checkbox name="b">复选框 b</Checkbox>
</Checkbox.Group>
```

### 限制最大可选数

通过 `max` 属性可以限制复选框组的最大可选数。

```tsx
<Checkbox.Group max={2}>
  <Checkbox name="a">复选框 a</Checkbox>
  <Checkbox name="b">复选框 b</Checkbox>
  <Checkbox name="c">复选框 c</Checkbox>
</Checkbox.Group>
```

### 搭配单元格组件使用

此时你需要再引入 `Cell` 和 `Cell.Group` 组件，并通过 `Checkbox` 实例上的 toggle 方法触发切换。

```tsx
<Checkbox.Group max={2}>
  <Cell.Group clickable>
    <Cell title="复选框 a">
      <Checkbox name="a" />
    </Cell>
    <Cell title="复选框 b">
      <Checkbox name="b" />
    </Cell>
  </Cell.Group>
</Checkbox.Group>
```

## API

### Checkbox Props

| 参数                         | 说明                        | 类型                 | 默认值     |
| -------------------------- | ------------------------- | ------------------ | ------- |
| defaultChecked             | 默认是否为选中状态                 | _boolean_          | `false` |
| checked                    | 是否为选中状态                   | _boolean_          | `false` |
| name                       | 标识符                       | _any_              | -       |
| shape <Tag tag="v1.0.0" /> | 形状，可选值为 `square` `button` | _string_           | `round` |
| disabled                   | 是否禁用复选框                   | _boolean_          | `false` |
| size                       | 图标大小，默认单位为 `px`           | _number \| string_ | `20px`  |

### CheckboxGroup Props

| 参数           | 说明                     | 类型                 | 默认值        |
| ------------ | ---------------------- | ------------------ | ---------- |
| defaultValue | 默认所有选中项的标识符            | _any\[]_           | -          |
| value        | 所有选中项的标识符              | _any\[]_           | -          |
| disabled     | 是否禁用所有复选框              | _boolean_          | `false`    |
| max          | 最大可选数，`0` 为无限制         | _number \| string_ | `0`        |
| direction    | 排列方向，可选值为 `horizontal` | _string_           | `vertical` |
| size         | 所有复选框的图标大小，默认单位为 `px`  | _number \| string_ | `20px`     |

### Checkbox Events

| 事件名      | 说明           | 回调参数               |
| -------- | ------------ | ------------------ |
| onChange | 当绑定值变化时触发的事件 | _checked: boolean_ |

### CheckboxGroup Events

| 事件名      | 说明           | 回调参数            |
| -------- | ------------ | --------------- |
| onChange | 当绑定值变化时触发的事件 | _names: any\[]_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                                              | 默认值                                       | 描述 |
| --------------------------------------------------------------- | ----------------------------------------- | -- |
| --checkbox-size                                                 | _20px \* $hd_                             | -  |
| --checkbox-font-size                                            | _var(--font-size-lg)_                     | -  |
| --checkbox-border-color                                         | _var(--gray-5)_                           | -  |
| --checkbox-transition-duration                                  | _var(--animation-duration-fast)_          | -  |
| --checkbox-gap                                                  | _var(--padding-sm)_                       | -  |
| --checkbox-label-margin                                         | _var(--padding-xs)_                       | -  |
| --checkbox-label-color                                          | _var(--text-color)_                       | -  |
| --checkbox-label-line-height                                    | _var(--checkbox-size)_                    | -  |
| --checkbox-disabled-label-color                                 | _var(--gray-5)_                           | -  |
| --checkbox-icon-font-size                                       | _var(--checkbox-size)_                    | -  |
| --checkbox-checked-icon-color                                   | _var(--white)_                            | -  |
| --checkbox-checked-icon-border-color                            | _var(--primary-color)_                    | -  |
| --checkbox-checked-icon-background-color                        | _var(--primary-color)_                    | -  |
| --checkbox-disabled-icon-color                                  | _var(--gray-5)_                           | -  |
| --checkbox-disabled-icon-border-color                           | _var(--gray-5)_                           | -  |
| --checkbox-disabled-icon-background-color                       | _var(--border-color)_                     | -  |
| --checkbox-button-padding <Tag tag="v1.0.0" />                  | _5px \* $hd 18px \* $hd_                  | -  |
| --checkbox-button-border-radius <Tag tag="v1.0.0" />            | _var(--border-radius-max)_                | -  |
| --checkbox-button-color <Tag tag="v1.0.0" />                    | _var(--text-color)_                       | -  |
| --checkbox-button-background-color <Tag tag="v1.0.0" />         | _var(--gray-1)_                           | -  |
| --checkbox-button-border-color <Tag tag="v1.0.0" />             | _var(--checkbox-button-background-color)_ | -  |
| --checkbox-button-checked-color <Tag tag="v1.0.0" />            | _var(--primary-color)_                    | -  |
| --checkbox-button-checked-background-color <Tag tag="v1.0.0" /> | _var(--white)_                            | -  |
| --checkbox-button-checked-border-color <Tag tag="v1.0.0" />     | _var(--primary-color)_                    | -  |
| --checkbox-button-disabled-opacity <Tag tag="v1.0.0" />         | _var(--disabled-opacity)_                 | -  |



---
url: https://taroify.com/components/field/index.md
---

# Field 输入框

### 介绍

用户可以在文本框内输入或编辑文字。

### 引入

```tsx
import { Field } from "@taroify/core"
```

## 代码演示

### 基础用法

可以通过 `value` 设置输入框的值，通过 `placeholder` 设置占位提示文字，通过 `onChange` 事件获得改变的值。

```tsx
import { Cell, Field, Input } from "@taroify/core"

function BasicField() {
  const [value, setValue] = useState("")
  return (
    <Cell.Group inset>
      <Field label="文本">
        <Input placeholder="请输入文本" value={value} onChange={(e) => setValue(e.detail.value)} />
      </Field>
    </Cell.Group>
  )
}
```

### 自定义类型

根据 `type` 属性定义不同类型的输入框，默认值为 `text`。

```tsx
import { Cell, Field, Input } from "@taroify/core"

function CustomField() {
  const [text, setText] = useState("")
  const [idcard, setIdcard] = useState("")
  const [number, setNumber] = useState("")
  const [digit, setDigit] = useState("")
  const [password, setPassword] = useState("")
  return (
    <Cell.Group inset>
      <Field label="文本">
        <Input placeholder="请输入文本" value={text} onChange={(e) => setText(e.detail.value)} />
      </Field>
      <Field label="身份证号">
        <Input
          type="idcard"
          placeholder="请输入身份证号"
          value={idcard}
          onChange={(e) => setIdcard(e.detail.value)}
        />
      </Field>
      <Field label="整数">
        <Input
          type="number"
          placeholder="请输入整数"
          value={number}
          onChange={(e) => setNumber(e.detail.value)}
        />
      </Field>
      <Field label="数字">
        <Input
          type="digit"
          placeholder="请输入数字（支持小数）"
          value={digit}
          onChange={(e) => setDigit(e.detail.value)}
        />
      </Field>
      <Field label="密码">
        <Input
          password
          placeholder="请输入密码"
          value={password}
          onChange={(e) => setPassword(e.detail.value)}
        />
      </Field>
    </Cell.Group>
  )
}
```

### 禁用输入框

通过 `readonly` 将输入框设置为只读状态，通过 `disabled` 将输入框设置为禁用状态。

```tsx
import { Cell, Field, Input } from "@taroify/core"

function DisabledField() {
  return (
    <Cell.Group inset>
      <Field label="文本">
        <Input placeholder="输入框只读" readonly />
      </Field>
      <Field label="文本">
        <Input placeholder="输入框已禁用" disabled />
      </Field>
    </Cell.Group>
  )
}
```

### 显示图标

通过 `icon` 和 `rightIcon` 配置输入框两侧的图标，通过设置 `clearable` 在输入过程中展示清除图标。

```tsx
import { Cell, Field, Input } from "@taroify/core"

function IconField() {
  return (
    <Cell.Group inset>
      <Field label="文本" icon={<SmileOutlined />} rightIcon={<WarningOutlined />}>
        <Input placeholder="显示图标" />
      </Field>
      <Field label="文本" icon={<MusicOutlined />}>
        <Input placeholder="显示清除图标" clearable />
      </Field>
    </Cell.Group>
  )
}
```

### 错误提示

设置 `required` 属性表示这是一个必填项，可以配合 `Input` 或 `Field.Feedback` 组件显示对应的错误提示。

```tsx
import { Cell, Field, Input } from "@taroify/core"

function ErrorField() {
  return (
    <Cell.Group inset>
      <Field label="用户名" required>
        <Input placeholder="请输入用户名" color="danger" />
      </Field>
      <Field
        required
        label="手机号"
        feedback={<Field.Feedback status="invalid">手机号格式错误</Field.Feedback>}
      >
        <Input placeholder="请输入手机号" />
      </Field>
    </Cell.Group>
  )
}
```

### 插入按钮

通过 `Button` 可以在输入框尾部插入按钮。

```tsx
import { Cell, Field, Input } from "@taroify/core"

function ButtonField() {
  return (
    <Cell.Group inset>
      <Field align="center" label="短信验证码">
        <Input placeholder="请输入短信验证码" />
        <Button size="small" color="primary">
          发送验证码
        </Button>
      </Field>
    </Cell.Group>
  )
}
```

### 高度自适应

对于 Textarea 组件，可以通过 `autoHeight` 属性设置高度自适应。

```tsx
import { Cell, Field, Textarea } from "@taroify/core"
import { getEnv } from "@tarojs/taro"
const env = getEnv();
function FieldWithTextarea() {
  return (
    <Cell.Group inset style={{ "--textarea-line-height": env === "WEB" ? "1.2rem" : "1" }}>
      <Field align="start" label="留言">
        <Textarea autoHeight placeholder="请输入留言" />
      </Field>
    </Cell.Group>
  )
}
```

> Tips: 微信placeholder不支持line-height

### 显示字数统计

设置 `limit` 属性后会在底部显示字数统计。

```tsx
import { Cell, Field, Textarea } from "@taroify/core"
import { getEnv } from "@tarojs/taro"
const env = getEnv();
function FieldWithTextareaLimit() {
  return (
    <Cell.Group inset style={{ "--textarea-line-height": env === "WEB" ? "1.2rem" : "1" }}>
      <Field align="start" label="留言">
        <Textarea style={{ height: "48px" }} limit={50} placeholder="请输入留言" />
      </Field>
    </Cell.Group>
  )
}
```

### 输入框内容对齐

通过 Input 组件的 `align` 属性可以设置输入框内容的对齐方式，可选值为 `center`、`right`。

```tsx
import { Cell, Field, Input } from "@taroify/core"

function FieldWithInputAlign() {
  return (
    <Cell.Group inset>
      <Field label="文本">
        <Input align="left" placeholder="输入框内容左对齐" />
      </Field>
      <Field label="文本">
        <Input align="center" placeholder="输入框内容居中对齐" />
      </Field>
      <Field label="文本">
        <Input align="right" placeholder="输入框内容右对齐" />
      </Field>
    </Cell.Group>
  )
}
```

### 标签（Field.Label）和反馈（Field.Feedback）

使用 `label` 和 `feedback` 属性的对象或元素表示法，提供全部属性。

```tsx
import { Cell, Field, Input } from "@taroify/core"

function FieldWithVaraintLabel() {
  return (
    <Cell.Group inset>
      <Field label="文本">
        <Input placeholder="请输入文本" />
      </Field>
      <Field label={{ children: "文本" }}>
        <Input placeholder="请输入文本" />
      </Field>
      <Field label={<Field.Label>文本</Field.Label>}>
        <Input placeholder="请输入文本" />
      </Field>
    </Cell.Group>
  )
}
```

## API

### Props

| 参数       | 说明          | 类型                                                                                            | 默认值 |
| -------- | ----------- | --------------------------------------------------------------------------------------------- | --- |
| label    | 左侧文本        | _string \| [FormLabelProps](/components/form/index.md#formlabel-props) \| ReactElement_       | -   |
| feedback | 提示文案，为空时不展示 | _string \| [FormFeedbackProps](/components/form/index.md#formfeedback-props) \| ReactElement_ | -   |

> 属性继承自 Form.Item 组件，更多属性参见：[Form.Item 组件](/components/form/index.md#formitem-props)



---
url: https://taroify.com/components/form/index.md
---

# Form 表单

### 介绍

用于数据录入、校验，支持输入框、单选框、复选框、文件上传等类型。

### 引入

```tsx
import { Form } from "@taroify/core"
```

## 代码演示

### 基础用法

在表单中，每个 `Form.Item` 代表一个表单项

```tsx
function BasicForm() {
  const onSubmit = (event: BaseEventOrig<FormProps.onSubmitEventDetail>) => {
    Toast.open(JSON.stringify(event.detail.value))
  }

  return (
    <Form onSubmit={onSubmit}>
      <Toast id="toast" />
      <Cell.Group inset>
        <Form.Item name="username" rules={[{ required: true, message: "请填写用户名" }]}>
          <Form.Label>用户名</Form.Label>
          <Form.Control>
            <Input placeholder="用户名" />
          </Form.Control>
        </Form.Item>
        <Form.Item name="password" rules={[{ required: true, message: "请填写密码" }]}>
          <Form.Label>密码</Form.Label>
          <Form.Control>
            <Input password placeholder="密码" />
          </Form.Control>
        </Form.Item>
        <Field
          name="text"
          label={{ align: "left", children: "文本" }}
          rules={[{ required: true, message: "请填写文本" }]}
        >
          <Input placeholder="请输入文本" />
        </Field>
      </Cell.Group>
      <View style={{ margin: "16px" }}>
        <Button shape="round" block color="primary" formType="submit">
          提交
        </Button>
      </View>
    </Form>
  )
}
```

使用`Field`组件

```tsx
function BasicForm() {
  const onSubmit = (event: BaseEventOrig<FormProps.onSubmitEventDetail>) => {
    Toast.open(JSON.stringify(event.detail.value))
  }

  return (
    <Form onSubmit={onSubmit}>
      <Toast id="toast" />
      <Cell.Group inset>
        <Field label="用户名" name="username" rules={[{ required: true, message: "请填写用户名" }]}>
          <Input placeholder="用户名" />
        </Field>
        <Field label="密码" name="password" rules={[{ required: true, message: "请填写密码" }]}>
          <Input password placeholder="密码" />
        </Field>
      </Cell.Group>
      <View style={{ margin: "16px" }}>
        <Button shape="round" block color="primary" formType="submit">
          提交
        </Button>
      </View>
    </Form>
  )
}
```

### 校验规则

通过 `rules` 定义表单校验规则，所有可用字段见[下方表格](#rule-%E6%95%B0%E6%8D%AE%E7%BB%93%E6%9E%84)。

```tsx
function FormWithRules() {
  const asyncValidator = (val: any) =>
    new Promise<boolean>((resolve) => {
      Toast.loading("验证中...")

      setTimeout(() => {
        Toast.close("toast")
        resolve(/\d{6}/.test(val))
      }, 1000)
    })

  function onValidate(errors: FormValidError[]) {
    Toast.open({
      style: {
        textAlign: "left",
      },
      message: JSON.stringify(errors, undefined, 2),
    })
  }

  return (
    <Form defaultValues={{ validatorMessage: "abc" }} onValidate={onValidate}>
      <Toast id="toast" />
      <Cell.Group inset>
        <Field
          label="文本"
          name="pattern"
          rules={[{ pattern: /\d{6}/, message: "请输入正确内容" }]}
        >
          <Input placeholder="正则校验" />
        </Field>
        <Field
          label="文本"
          name="validator"
          rules={[{ validator: (val) => /1\d{10}/.test(val), message: "请输入正确内容" }]}
        >
          <Input placeholder="函数校验" />
        </Field>
        <Field
          label="文本"
          name="validatorMessage"
          rules={[{ validator: (val) => `${val ?? ""} 不合法，请重新输入` }]}
        >
          <Input placeholder="校验函数返回错误提示" />
        </Field>
        <Field
          label="文本"
          name="asyncValidator"
          rules={[{ validator: asyncValidator, message: "请输入正确内容" }]}
        >
          <Input placeholder="异步函数校验" />
        </Field>
      </Cell.Group>
      <View style={{ margin: "16px" }}>
        <Button shape="round" block color="primary" formType="submit">
          提交
        </Button>
      </View>
    </Form>
  )
}
```

### 禁用表单

设置 `disabled` 后，会为 `Form` 内部的 `taroify` 组件 `Input`, `Textarea`, `Checkbox`, `Switch`, `Checkbox.Group`, `Radio.Group`, `Rate`, `Slider`, `Stepper`, `Uploader` 设置 `disabled` <br>

form 设置 disabled 后，也可以单独为表单项和组件设置 disabled=\{false}, 优先级：表单 \< 表单项 \< 组件

### 表单项类型 - 开关

在表单中使用 [Switch 组件](/components/switch.md)。

```tsx
<Field label="开关" name="switch">
  <Switch size={20} />
</Field>
```

### 表单项类型 - 复选框

在表单中使用 [Checkbox 组件](/components/checkbox.md)。

```tsx
<Field label="复选框" name="checkbox">
  <Checkbox shape="square" />
</Field>
<Field label="复选框组" name="checkboxGroup">
  <Checkbox.Group direction="horizontal">
    <Checkbox name="1" shape="square">
      复选框 1
    </Checkbox>
    <Checkbox name="2" shape="square">
      复选框 2
    </Checkbox>
  </Checkbox.Group>
</Field>
```

### 表单项类型 - 单选框

在表单中使用 [Radio 组件](/components/radio.md)。

```tsx
<Field label="单选框" name="radio">
  <Radio.Group direction="horizontal">
    <Radio name="1">单选框 1</Radio>
    <Radio name="2">单选框 2</Radio>
  </Radio.Group>
</Field>
```

### 表单项类型 - 步进器

在表单中使用 [Stepper 组件](/components/stepper.md)。

```tsx
<Field label="步进器" name="stepper">
  <Stepper />
</Field>
```

### 表单项类型 - 评分

在表单中使用 [Rate 组件](/components/rate.md)。

```tsx
<Field label="评分" name="rate">
  <Rate />
</Field>
```

### 表单项类型 - 滑块

在表单中使用 [Slider 组件](/components/slider.md)。

```tsx
<Field label="滑块" name="slider">
  <Slider />
</Field>
```

### 表单项类型 - 文件上传

在表单中使用 [Uploader 组件](/components/uploader.md)。

```tsx
function UploaderField() {
  const itemRef = useRef<FormItemInstance>()

  function onUpload() {
    chooseImage({
      count: 1,
      sizeType: ["original", "compressed"],
      sourceType: ["album", "camera"],
    }).then(({ tempFiles }) => {
      itemRef.current?.setValue([
        ...(itemRef.current?.getValue() ? [...itemRef.current?.getValue()] : []),
        {
          url: tempFiles[0].path,
          type: tempFiles[0].type,
          name: tempFiles[0].originalFileObj?.name,
        },
      ])
    })
  }

  return (
    <Field label="文件上传" ref={itemRef} name="uploader">
      <Uploader multiple maxFiles={2} onUpload={onUpload} />
    </Field>
  )
}
```

### 表单项类型 - 选择器

在表单中使用 [Picker 组件](/components/picker.md)。

```tsx
function PickerField() {
  const itemRef = useRef<FormItemInstance>()
  const [open, setOpen] = useState(false)
  const columns = useMemo(
    () => [
      { label: "杭州", value: "Hangzhou" },
      { label: "宁波", value: "Ningbo" },
      { label: "温州", value: "Wenzhou" },
      { label: "绍兴", value: "Shaoxing" },
      { label: "湖州", value: "Huzhou" },
    ],
    [],
  )

  return (
    <>
      <Field label="选择器" ref={itemRef} name="picker" clickable isLink>
        <Input readonly placeholder="点击选择城市" onClick={() => setOpen(true)} />
      </Field>
      <Popup open={open} rounded placement="bottom" onClose={setOpen}>
        <Picker
          title="选择城市"
          columns={columns}
          onCancel={() => setOpen(false)}
          onConfirm={(newValue) => {
            itemRef.current?.setValue(newValue)
            setOpen(false)
          }}
        ></Picker>
      </Popup>
    </>
  )
}
```

### 表单项类型 - 时间选择器

在表单中使用 [DatetimePicker 组件](/components/datetime-picker.md)。

```tsx
function DatetimePickerField() {
  const itemRef = useRef<FormItemInstance>()
  const [open, setOpen] = useState(false)

  const formatDate = (date: any) => {
    if (date) {
      const hours = _.padStart(_.toString(date?.getHours()), 2, "0")
      const minutes = _.padStart(_.toString(date?.getMinutes()), 2, "0")
      return `${hours}:${minutes}`
    }
  }

  return (
    <>
      <Field label="时间选择" ref={itemRef} name="datetimePicker" clickable isLink>
        {(controller) => (
          <Input
            value={formatDate(controller.value)}
            disabled={controller.disabled}
            readonly
            placeholder="点击选择时间"
            onClick={() => setOpen(true)}
          />
        )}
      </Field>
      <Popup open={open} rounded placement="bottom" onClose={setOpen}>
        <DatetimePicker
          type="hour-minute"
          onCancel={() => setOpen(false)}
          onConfirm={(newValue) => {
            itemRef.current?.setValue(newValue)
            setOpen(false)
          }}
        ></DatetimePicker>
      </Popup>
    </>
  )
}
```

### 表单项类型 - 日历

在表单中使用 [Calendar 组件](/components/calendar.md)。

```tsx
function CalendarField() {
  const itemRef = useRef<FormItemInstance>()
  const [open, setOpen] = useState(false)

  const formatDate = (date: any) => {
    if (date) {
      const months = _.padStart(_.toString(date?.getMonth() + 1), 2, "0")
      const days = _.padStart(_.toString(date?.getDate()), 2, "0")
      return `${months}-${days}`
    }
  }

  return (
    <>
      <Field label="日历" ref={itemRef} name="calendar" clickable isLink>
        {(controller) => (
          <Input
            value={formatDate(controller.value)}
            disabled={controller.disabled}
            readonly
            placeholder="点击选择日期"
            onClick={() => setOpen(true)}
          />
        )}
      </Field>
      <Calendar
        type="single"
        poppable
        showPopup={open}
        onCancel={() => setOpen(false)}
        onConfirm={(newValue) => {
          itemRef.current?.setValue(newValue)
          setOpen(false)
        }}
      ></Calendar>
    </>
  )
}
```

### 动态增减表单项

通过 Form.List 动态增减表单项 `v0.1.1-alpha.3`

```tsx
function DynamicForm() {
  const ref = useRef<FormInstance>(null)
  const onManual = () => {
    ref.current?.setValues({
      contacts: [
        { name: "小红", phone: "10000" },
        { name: "小绿", phone: "10086" },
      ],
    })
  }
  return (
    <Form
      ref={ref}
      onSubmit={(e) => {
        Toast.open(JSON.stringify(e.detail.value, undefined, 2))
      }}
    >
      <Form.List name="contacts" defaultValue={[{ name: "小明", phone: "10086" }]}>
        {(fields, { add, remove }) => (
          <Cell.Group inset>
            {fields.map((field, idx) => (
              <Fragment key={field.key}>
                <Field label="姓名" name={`${field.name}.name`} key={`${field.key}.name`}>
                  {({ value, onChange }) => (
                    <>
                      <Input
                        placeholder="请输入姓名"
                        value={value}
                        onChange={(e) => {
                          onChange?.(e.detail.value)
                        }}
                      />
                      <View
                        style={{ flexShrink: 0 }}
                        onClick={() => {
                          remove(idx)
                        }}
                      >
                        删除
                      </View>
                    </>
                  )}
                </Field>
                <Field
                  label="电话"
                  name={`${field.name}.phone`}
                  key={`${field.key}.phone`}
                  rules={[{ required: true, message: "必填" }]}
                >
                  <Input placeholder="请输入电话" />
                </Field>
              </Fragment>
            ))}
            <Button variant="text" color="primary" onClick={() => add({})}>
              添加联系人
            </Button>
          </Cell.Group>
        )}
      </Form.List>
      <View style={{ margin: "16px" }}>
        <Button shape="round" block color="primary" formType="submit">
          提交
        </Button>
        <Button style={{ marginTop: "16px" }} shape="round" block color="info" onClick={onManual}>
          手动
        </Button>
        <Button style={{ marginTop: "16px" }} shape="round" block color="warning" formType="reset">
          重置
        </Button>
      </View>
    </Form>
  )
}
```

### 依赖与自动更新

通过 dependencies 自动触发校验

```tsx
function DependenciesDemo() {
  const formRef = useRef<FormInstance>()
  const onSubmit = (event: BaseEventOrig<FormProps.onSubmitEventDetail>) => {
    Toast.open(JSON.stringify(event.detail.value))
  }

  return (
    <Form ref={formRef} onSubmit={onSubmit} validateTrigger="onChange">
      <Toast id="toast" />
      <Cell.Group inset>
        <Form.Item name="username" rules={[{ required: true, message: "请输入用户名" }]}>
          <Form.Label>用户名</Form.Label>
          <Form.Control>
            <Input placeholder="用户名" />
          </Form.Control>
        </Form.Item>
        <Form.Item name="password" rules={[{ required: true, message: "请输入密码" }]}>
          <Form.Label>密码</Form.Label>
          <Form.Control>
            <Input placeholder="密码" />
          </Form.Control>
        </Form.Item>
        <Form.Item
          name="confirmPassword"
          dependencies={["password"]}
          rules={[
            { required: true, message: "请再次输入密码" },
            {
              validator: (val) => {
                return formRef.current?.getValues<any>()?.password === val ? true : "密码不一致"
              },
            },
          ]}
        >
          <Form.Label>确认密码</Form.Label>
          <Form.Control>
            <Input placeholder="确认密码" />
          </Form.Control>
        </Form.Item>
      </Cell.Group>
      <View style={{ margin: "16px" }}>
        <Button shape="round" block color="primary" formType="submit">
          提交
        </Button>
      </View>
    </Form>
  )
}
```

通过 shouldUpdate 和 noStyle 触发重新渲染, Form.Item 里包裹的子组件必须由函数返回，否则 shouldUpdate 不会起作用, Field 暂不支持

```tsx
function ShouldUpdateDemo() {
  const formRef = useRef<FormInstance>()
  return (
    <Form
      ref={formRef}
      onSubmit={(e) => {
        Toast.open(JSON.stringify(e.detail.value, undefined, 2))
      }}
    >
      <Toast id="toast" />
      <Cell.Group inset>
        <Form.Item name="type">
          <Form.Label>复选框</Form.Label>
          <Form.Control>
            <Checkbox shape="square" />
          </Form.Control>
        </Form.Item>
        <Form.Item name="radio">
          <Form.Label>单选框</Form.Label>
          <Form.Control>
            <Radio.Group direction="horizontal">
              <Radio name="1">单选框 1</Radio>
              <Radio name="2">单选框 2</Radio>
            </Radio.Group>
          </Form.Control>
        </Form.Item>
        <Form.Item noStyle shouldUpdate={(prev, cur) => prev.type !== cur.type}>
          {() => {
            const type = formRef.current?.getValues<any>()?.type
            if (type) {
              return (
                <Form.Item name="a1">
                  <Form.Label>复选框选中</Form.Label>
                  <Form.Control>
                    <Input />
                  </Form.Control>
                </Form.Item>
              )
            } else {
              return (
                <>
                  <Form.Item name="a2">
                    <Form.Label>复选框未选中</Form.Label>
                    <Form.Control>
                      <Input />
                    </Form.Control>
                  </Form.Item>
                  <Form.Item name="a3">
                    <Form.Label>复选框未选中</Form.Label>
                    <Form.Control>
                      <Input />
                    </Form.Control>
                  </Form.Item>
                </>
              )
            }
          }}
        </Form.Item>
        <Form.Item noStyle shouldUpdate={(prev, cur) => prev.radio !== cur.radio}>
          {() => (
            <Field name="cc" label={`单选框${formRef.current?.getValues<any>()?.radio}`}>
              <Input placeholder={`结果${JSON.stringify(formRef.current?.getValues<any>())}`} />
            </Field>
          )}
        </Form.Item>
      </Cell.Group>
      <View style={{ margin: "16px" }}>
        <Button shape="round" block color="primary" formType="submit">
          提交
        </Button>
      </View>
    </Form>
  )
}
```

## API

### Form Props

| 参数              | 说明                                       | 类型        | 默认值      |
| --------------- | ---------------------------------------- | --------- | -------- |
| defaultValues   | 表单默认值                                    | _object_  |          |
| labelAlign      | 表单项 label 对齐方式，可选值为 `center` `right`     | _string_  | `left`   |
| controlAlign    | 表单项 control 对齐方式，可选值为 `center` `right`   | _string_  | `left`   |
| validateTrigger | 表单校验触发时机，可选值为 `onChange`、`onSubmit`，详见下表 | _string_  | `onBlur` |
| colon           | 是否在 label 后面添加冒号                         | _boolean_ | `false`  |
| disabled        | 是否禁用表单                                   | _boolean_ | `false`  |

### Form Events

| 事件名            | 说明            | 回调参数                                                   |
| -------------- | ------------- | ------------------------------------------------------ |
| onSubmit       | 提交表单且验证通过后触发  | _event: BaseEventOrig\<FormProps.onSubmitEventDetail>_ |
| onReset        | 重置表单后触发       | _event: BaseEventOrig_                                 |
| onValidate     | 提交表单且验证不通过后触发 | _errors: \{ name: string, errors: string\[] }\[]_      |
| onValuesChange | 字段值更新后触发      | _changedValues: object, allValues: object_             |

### Form Methods

通过 ref 可以获取到 Form 实例并调用实例方法。

| 方法名       | 说明                                 | 参数                           | 返回值                 |
| --------- | ---------------------------------- | ---------------------------- | ------------------- |
| setValues | 设置表单值(浅合并)                         | _object_                     | -                   |
| getValues | 获得表单值，支持传入 `name` 来获得单个或部分表单项      | _name?: string \| string\[]_ | _object_            |
| setErrors | 设置表单验证错误信息(浅合并)                    | _FormValidError\[]_          | _void_              |
| getErrors | 获得表单验证错误信息，支持传入 `name` 来获得单个或部分表单项 | _name?: string \| string\[]_ | _FormValidError\[]_ |
| validate  | 验证表单，支持传入 `name` 来验证单个或部分表单项       | _name?: string \| string\[]_ | _Promise_           |
| submit    | 提交表单，与点击提交按钮的效果等价                  | -                            | -                   |
| reset     | 重置表单                               | -                            | _void_              |

### validateTrigger 可选值

通过 `validateTrigger` 属性可以自定义表单校验的触发时机。

| 值        | 描述                 |
| -------- | ------------------ |
| onSubmit | 仅在提交表单时触发校验        |
| onBlur   | 在提交表单和输入框失焦时触发校验   |
| onChange | 在提交表单和输入框内容变化时触发校验 |

### Form.Item Props

| 参数           | 说明                    | 类型                                            | 默认值     |
| ------------ | --------------------- | --------------------------------------------- | ------- |
| name         | 表单项名称，提交表单的标识符        | _string_                                      | -       |
| defaultValue | 表单项默认值                | _any_                                         | -       |
| required     | 是否显示表单必填星号            | _boolean_                                     | `false` |
| rules        | 表单校验规则                | _FormRule\[]_                                 | -       |
| dependencies | 当依赖的字段值改变时，触发自身的校验    | _string\[]_                                   | -       |
| shouldUpdate | 当值为 true 时，触发当前区域重新渲染 | _boolean\|(prevValues, curValues) => boolean_ | -       |
| noStyle      | 直接渲染 children         | boolean                                       | -       |

> 属性继承自 Cell 组件，更多属性参见：[Cell 组件](/components/cell/index.md#cell-props)

### Rule 数据结构

使用 Form.Item 的 `rules` 属性可以定义校验规则，可选属性如下：

| 键名            | 说明                                             | 类型                                              |
| ------------- | ---------------------------------------------- | ----------------------------------------------- |
| required      | 是否为必选字段，当值为空字符串、空数组、`undefined`、`null` 时，校验不通过 | _boolean_                                       |
| message       | 错误提示文案                                         | _string \| (value, rule) => string_             |
| validator     | 通过函数进行校验                                       | _(value, rule) => boolean \| string \| Promise_ |
| validateFirst | 当某一规则校验不通过时，是否停止剩下的规则的校验。                      | _boolean_                                       |
| pattern       | 通过正则表达式进行校验                                    | _RegExp_                                        |
| trigger       | 本项规则的触发时机，可选值为 `onChange`、`onBlur`             | _string_                                        |
| formatter     | 格式化函数，将表单项的值转换后进行校验                            | _(value, rule) => any_                          |

### Form.Label Props

| 参数    | 说明                         | 类型        | 默认值     |
| ----- | -------------------------- | --------- | ------- |
| align | 对齐方式，可选值为 `center` `right` | _string_  | `left`  |
| colon | 是否在 label 后面添加冒号           | _boolean_ | `false` |

### Form.Feedback Props

| 参数     | 说明                                    | 类型       | 默认值    |
| ------ | ------------------------------------- | -------- | ------ |
| align  | 对齐方式，可选值为 `center` `right`            | _string_ | `left` |
| status | 反馈状态，可选值为 `valid` `warning` `invalid` | _string_ | -      |

### Form.Control Props

| 参数       | 说明                         | 类型                                                          | 默认值    |
| -------- | -------------------------- | ----------------------------------------------------------- | ------ |
| align    | 对齐方式，可选值为 `center` `right` | _string_                                                    | `left` |
| children | 内容                         | _ReactNode\|((controller: FormController<V>) => ReactNode)_ | --     |

```tsx
interface FormController<V> {
  value?: V // 当前表单项值
  validateStatus?: FormValidateStatus // 当前表单项验证状态
  disabled?: boolean // 当前表单项是否禁用

  onChange?(value: V): void // 改变当前表单项值

  onBlur?(value: V): void // 触发onBlur当前表单项校验
}
```

> Tips: 使用 onBlur 触发表单验证，自定义表单项时，要手动调用 onBlur，才能触发校验

### Form.List

| 参数           | 说明             | 类型                                                                                      |
| ------------ | -------------- | --------------------------------------------------------------------------------------- |
| children     | 渲染函数           | _(fields: \{ key: string, name: string }\[], operation: \{ add, remove }) => ReactNode_ |
| name         | 表单项名称，提交表单的标识符 | _string_                                                                                |
| defaultValue | 表单项默认值         | _any_                                                                                   |

### 类型定义

通过`@taroify/core/form`导入组件类型：

```tsx
import { FormRule, FormItemInstance, FormListInstance, FormInstance } from "@taroify/core/form"
```

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                 | 默认值                       | 描述 |
| ---------------------------------- | ------------------------- | -- |
| form-label-width                   | _6.2em_                   | -  |
| form-label-color                   | _var(--gray-7)_           | -  |
| form-label-margin-right            | _var(--padding-sm)_       | -  |
| form-label-disabled-color          | _var(--gray-5)_           | -  |
| form-item-icon-size                | _16px \* $hd_             | -  |
| form-item-right-icon-color         | _var(--gray-6)_           | -  |
| form-item-right-icon-padding       | _0 var(--padding-xs)_     | -  |
| form-item-right-icon-margin-right  | _-8px \* $hd_             | -  |
| form-item-right-button-margin-left | _var(--padding-xs)_       | -  |
| form-control-color                 | _var(--text-color)_       | -  |
| form-control-min-height            | _var(--cell-line-height)_ | -  |
| form-feedback-font-size            | _var(--font-size-sm)_     | -  |
| form-feedback-valid-color          | _var(--success-color)_    | -  |
| form-feedback-warning-color        | _var(--warning-color)_    | -  |
| form-feedback-invalid-color        | _var(--danger-color)_     | -  |



---
url: https://taroify.com/components/datetime-picker/index.md
---

# DatetimePicker 时间选择

### 介绍

时间选择器，支持日期、年月、时分秒等维度，通常与[弹出层](/components/popup.md)组件配合使用。

### 引入

```tsx
import { DatetimePicker } from "@taroify/core"
```

## 代码演示

### 选择年月日

DatetimePicker 通过 type 属性来定义需要选择的时间类型，type 为 `date` 表示选择年月日。通过 min 和 max 属性可以确定可选的时间范围。

```tsx
function DatePicker() {
  const [minDate] = useState(new Date(2021, 9, 14))
  const [maxDate] = useState(new Date(2023, 11, 12))
  const [defaultValue] = useState(new Date(2021, 9, 14))
  const [value, setValue] = useState(new Date(2022, 10, 14))
  return (
    <DatetimePicker
      type="date"
      min={minDate}
      max={maxDate}
      defaultValue={defaultValue}
      value={value}
      onChange={setValue}
    >
      <DatetimePicker.Toolbar>
        <DatetimePicker.Button>取消</DatetimePicker.Button>
        <DatetimePicker.Title>选择年月日</DatetimePicker.Title>
        <DatetimePicker.Button>确认</DatetimePicker.Button>
      </DatetimePicker.Toolbar>
    </DatetimePicker>
  )
}
```

### 选择年月

将 type 设置为 `year-month` 即可选择年份和月份。通过传入 `formatter` 函数，可以对选项文字进行格式化处理。

```tsx
function YearMonthPicker() {
  const [minDate] = useState(new Date(2020, 0, 1))
  const [maxDate] = useState(new Date(2025, 10, 1))
  const [defaultValue] = useState(new Date(2021, 0, 17))

  return (
    <DatetimePicker
      type="year-month"
      min={minDate}
      max={maxDate}
      defaultValue={defaultValue}
      formatter={(type, val) => {
        if (type === "year") {
          return `${val}年`
        }
        if (type === "month") {
          return `${val}月`
        }
        return val
      }}
    >
      <DatetimePicker.Toolbar>
        <DatetimePicker.Button>取消</DatetimePicker.Button>
        <DatetimePicker.Title>选择年月</DatetimePicker.Title>
        <DatetimePicker.Button>确认</DatetimePicker.Button>
      </DatetimePicker.Toolbar>
    </DatetimePicker>
  )
}
```

### 选择月日

将 type 设置为 `month-day` 即可选择月份和日期。

```tsx
function MonthDayPicker() {
  const [minDate] = useState(new Date(2020, 0, 1))
  const [maxDate] = useState(new Date(2025, 10, 1))
  const [defaultValue] = useState(new Date(2021, 0, 17))

  return (
    <DatetimePicker
      type="month-day"
      min={minDate}
      max={maxDate}
      defaultValue={defaultValue}
      formatter={(type, val) => {
        if (type === "month") {
          return `${val}月`
        }
        if (type === "day") {
          return `${val}日`
        }
        return val
      }}
    >
      <DatetimePicker.Toolbar>
        <DatetimePicker.Button>取消</DatetimePicker.Button>
        <DatetimePicker.Title>选择年月</DatetimePicker.Title>
        <DatetimePicker.Button>确认</DatetimePicker.Button>
      </DatetimePicker.Toolbar>
    </DatetimePicker>
  )
}
```

### 选择时间

将 type 设置为 `time` 即可选择时间（时、分、秒）。

```tsx
function TimePicker() {
  const [minDate] = useState(new Date(2020, 0, 1, 10, 0, 0))
  const [maxDate] = useState(new Date(2020, 0, 1, 20, 59, 59))
  const [defaultValue] = useState(new Date(2020, 0, 1, 12, 0, 0))

  return (
    <DatetimePicker type="time" min={minDate} max={maxDate} defaultValue={defaultValue}>
      <DatetimePicker.Toolbar>
        <DatetimePicker.Button>取消</DatetimePicker.Button>
        <DatetimePicker.Title>选择时间</DatetimePicker.Title>
        <DatetimePicker.Button>确认</DatetimePicker.Button>
      </DatetimePicker.Toolbar>
    </DatetimePicker>
  )
}
```

### 选择完整时间

将 type 设置为 `datetime` 即可选择完整时间，包括年月日时分秒。

```tsx
function DateTimePicker() {
  const [minDate] = useState(new Date(2020, 0, 1, 10, 0, 0))
  const [maxDate] = useState(new Date(2025, 10, 1, 20, 59, 59))
  const [defaultValue] = useState(new Date(2021, 2, 3, 12, 12, 12))

  return (
    <DatetimePicker type="datetime" min={minDate} max={maxDate} defaultValue={defaultValue}>
      <DatetimePicker.Toolbar>
        <DatetimePicker.Button>取消</DatetimePicker.Button>
        <DatetimePicker.Title>选择完整时间</DatetimePicker.Title>
        <DatetimePicker.Button>确认</DatetimePicker.Button>
      </DatetimePicker.Toolbar>
    </DatetimePicker>
  )
}
```

### 选择年月日小时

将 type 设置为 `date-hour` 即可选择日期和小时，包括年月日和小时。

```tsx
function DateHourPicker() {
  const [minDate] = useState(new Date(2020, 0, 1, 0))
  const [maxDate] = useState(new Date(2025, 10, 1, 23))
  const [defaultValue] = useState(new Date())

  return (
    <DatetimePicker type="date-hour" min={minDate} max={maxDate} defaultValue={defaultValue}>
      <DatetimePicker.Toolbar>
        <DatetimePicker.Button>取消</DatetimePicker.Button>
        <DatetimePicker.Title>选择年月日小时</DatetimePicker.Title>
        <DatetimePicker.Button>确认</DatetimePicker.Button>
      </DatetimePicker.Toolbar>
    </DatetimePicker>
  )
}
```

### 选择年月日时分

将 type 设置为 `date-minute` 即可选择日期和时分，包括年月日时分。

```tsx
function DateMinutePicker() {
  const [minDate] = useState(new Date(2020, 0, 1, 0, 0))
  const [maxDate] = useState(new Date(2025, 10, 1, 23, 59))
  const [defaultValue] = useState(new Date())

  return (
    <DatetimePicker type="date-minute" min={minDate} max={maxDate} defaultValue={defaultValue}>
      <DatetimePicker.Toolbar>
        <DatetimePicker.Button>取消</DatetimePicker.Button>
        <DatetimePicker.Title>选择年月日时分</DatetimePicker.Title>
        <DatetimePicker.Button>确认</DatetimePicker.Button>
      </DatetimePicker.Toolbar>
    </DatetimePicker>
  )
}
```

### 选项过滤器

通过传入 `filter` 函数，可以对选项数组进行过滤，实现自定义时间间隔。

```tsx
function TimePickerWithFilter() {
  const [minDate] = useState(new Date(2020, 0, 1, 0, 0, 0))
  const [maxDate] = useState(new Date(2020, 0, 1, 23, 59, 59))
  const [defaultValue] = useState(new Date(2020, 0, 1, 12, 0, 0))

  return (
    <DatetimePicker
      type="time"
      min={minDate}
      max={maxDate}
      defaultValue={defaultValue}
      filter={(type, options) => {
        if (type === "minute") {
          return options.filter((option) => Number(option) % 5 === 0)
        }
        return options
      }}
    >
      <DatetimePicker.Toolbar>
        <DatetimePicker.Button>取消</DatetimePicker.Button>
        <DatetimePicker.Title>选项过滤器</DatetimePicker.Title>
        <DatetimePicker.Button>确认</DatetimePicker.Button>
      </DatetimePicker.Toolbar>
    </DatetimePicker>
  )
}
```

### 自定义列排序

```tsx
function DatePickerWithFields() {
  const [minDate] = useState(new Date(2020, 0, 1))
  const [maxDate] = useState(new Date(2025, 10, 1))
  const [defaultValue] = useState(new Date(2021, 0, 17))
  return (
    <DatetimePicker
      type="date"
      fields={["month", "day", "year"]}
      defaultValue={defaultValue}
      min={minDate}
      max={maxDate}
      formatter={(type, val) => {
        if (type === "year") {
          return val + "年"
        }
        if (type === "month") {
          return val + "月"
        }
        if (type === "day") {
          return val + "日"
        }
        return val
      }}
    >
      <DatetimePicker.Toolbar>
        <DatetimePicker.Button>取消</DatetimePicker.Button>
        <DatetimePicker.Title>自定义列排序</DatetimePicker.Title>
        <DatetimePicker.Button>确认</DatetimePicker.Button>
      </DatetimePicker.Toolbar>
    </DatetimePicker>
  )
}
```

## API

### Props

| 参数           | 说明                                                                                            | 类型                                               | 默认值        |
| ------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------- |
| type         | 时间类型，可选值为 `date` `time` <br> `year-month` `month-day` `date-hour` `date-minute` `hour-minute` | _string_                                         | `datetime` |
| defaultValue | 默认选中的时间                                                                                       | _Date_                                           | -          |
| value        | 选中的时间                                                                                         | _Date_                                           | -          |
| min          | 可选的最小时间，精确到秒                                                                                  | _Date_                                           | 十年前        |
| max          | 可选的最大时间，精确到秒                                                                                  | _Date_                                           | 十年后        |
| filter       | 选项过滤函数                                                                                        | _(type: string, values: string\[]) => string\[]_ | -          |
| formatter    | 选项格式化函数                                                                                       | _(type: string, value: string) => string_        | -          |
| fields       | 自定义列排序数组, 子项可选值为<br> `year` `month` `day` `hour` `minute`                                     | _string\[]_                                      | -          |
| loading      | 是否显示加载状态                                                                                      | _boolean_                                        | `false`    |
| readonly     | 是否为只读状态，只读状态下无法切换选项                                                                           | _boolean_                                        | `false`    |
| siblingCount | 可见的选项相邻个数                                                                                     | _number_                                         | `3`        |

### Events

| 事件名       | 说明           | 回调参数        |
| --------- | ------------ | ----------- |
| onChange  | 当值变化时触发的事件   | value: Date |
| onConfirm | 点击完成按钮时触发的事件 | value: Date |
| onCancel  | 点击取消按钮时触发的事件 | value: Date |

## 常见问题

### 设置 min 或 max 后出现页面卡死的情况？

请注意不要在模板中直接使用类似`min="new Date()"`的写法，这样会导致每次渲染组件时传入一个新的 Date 对象，而传入新的数据会触发下一次渲染，从而陷入死循环。

正确的做法是将`date`作为一个数据定义在`useState`或者`useRef`函数中。

### 在 iOS 系统上初始化组件失败？

如果你遇到了在 iOS 上无法渲染组件的问题，请确认在创建 Date 对象时没有使用`new Date('2020-01-01')`这样的写法，iOS 不支持以中划线分隔的日期格式，正确写法是`new Date('2020/01/01')`
。

对此问题的详细解释：[stackoverflow](https://stackoverflow.com/questions/13363673/javascript-date-is-invalid-on-ios)。

### 是否有年份或月份选择器？

如果仅需要选择年份或者月份，建议直接使用 [Picker](/components/picker.md) 组件。



---
url: https://taroify.com/components/number-keyboard/index.md
---

# NumberKeyboard 数字键盘

### 介绍

虚拟数字键盘，可以配合[密码输入框组件](/components/password-input/index.md)或自定义的输入框组件使用。

### 引入

```tsx
import { NumberKeyboard } from "@taroify/core";
```

## 代码演示

### 默认样式

数字键盘提供了 `onKeyPress`、`onBackspace`、`onHide` 事件，分别对应输入内容、删除内容和隐藏键盘。

```tsx
function BasicNumberKeyboard(props: KeyboardProps) {
  const { keyboard, onKeyboard, onKeyPress } = props
  return (
    <>
      <Cell
        clickable
        title="弹出默认键盘"
        isLink
        onClick={() => onKeyboard?.("basic")}
      />
      <NumberKeyboard
        open={keyboard === "basic"}
        onKeyPress={onKeyPress}
        onHide={() => onKeyboard?.("")}
      />
    </>
  )
}
```

> 点击键盘以外的区域时，键盘会自动收起，通过阻止元素上的 touchstart 事件冒泡可以避免键盘收起。

### 带右侧栏的键盘

使用 `NumberKeyboard.Sidebar` 子组件可以用来展示键盘的右侧栏，常用于输入金额的场景。

```tsx
function SidebarNumberKeyboard(props: KeyboardProps) {
  const { keyboard, onKeyboard, onKeyPress } = props
  return (
    <>
      <Cell
        clickable
        title="弹出带右侧栏的键盘"
        isLink
        onClick={() => onKeyboard?.("sidebar")}
      />
      <NumberKeyboard
        open={keyboard === "sidebar"}
        extraKey={[undefined, "."]}
        onKeyPress={onKeyPress}
        onHide={() => onKeyboard?.("")}
      >
        <NumberKeyboard.Sidebar>
          <NumberKeyboard.Key size="large" code="backspace" />
          <NumberKeyboard.Key size="large" code="keyboard-hide" color="blue">
            完成
          </NumberKeyboard.Key>
        </NumberKeyboard.Sidebar>
      </NumberKeyboard>
    </>
  )
}

```

### 身份证号键盘

通过 `extraKey` 属性可以设置左下角按键内容，比如需要输入身份证号时，可以将 `extraKey` 设置为 `X`。

```tsx
function IdCardNumberKeyboard(props: KeyboardProps) {
  const { keyboard, onKeyboard, onKeyPress } = props
  return (
    <>
      <Cell
        clickable
        title="弹出身份证号键盘"
        isLink
        onClick={() => onKeyboard?.("idCard")}
      />
      <NumberKeyboard
        open={keyboard === "idcard"}
        extraKey="X"
        onKeyPress={onKeyPress}
        onHide={() => onKeyboard?.("")}
      >
        <NumberKeyboard.Header>
          <NumberKeyboard.Button>完成</NumberKeyboard.Button>
        </NumberKeyboard.Header>
      </NumberKeyboard>
    </>
  )
}
```

### 键盘标题

通过 `title` 属性可以设置键盘标题。

```tsx
function TitleNumberKeyboard(props: KeyboardProps) {
  const { keyboard, onKeyboard, onKeyPress } = props
  return (
    <>
      <Cell
        clickable
        title="弹出身份证号键盘"
        isLink
        onClick={() => onKeyboard?.("title")}
      />
      <NumberKeyboard
        open={keyboard === "title"}
        title="键盘标题"
        extraKey="."
        onKeyPress={onKeyPress}
        onHide={() => onKeyboard?.("")}
      >
        <NumberKeyboard.Header>
          <NumberKeyboard.Button>完成</NumberKeyboard.Button>
        </NumberKeyboard.Header>
      </NumberKeyboard>
    </>
  )
}
```

### 配置多个按键

将 `extraKey` 配置成数组，可以实现配置多个按键。

```tsx
function NumberKeyboardWithKeys(props: KeyboardProps) {
  const { keyboard, onKeyboard, onKeyPress } = props
  return (
    <>
      <Cell
        clickable
        title="弹出配置多个按键的键盘"
        isLink
        onClick={() => onKeyboard?.("keys")}
      />
      <NumberKeyboard
        open={keyboard === "keys"}
        extraKey={["00", "."]}
        onKeyPress={onKeyPress}
        onHide={() => onKeyboard?.("")}
      >
        <NumberKeyboard.Sidebar>
          <NumberKeyboard.Key size="large" code="backspace" />
          <NumberKeyboard.Key size="large" code="keyboard-hide" color="blue">
            完成
          </NumberKeyboard.Key>
        </NumberKeyboard.Sidebar>
      </NumberKeyboard>
    </>
  )
}
```

### 随机数字键盘

通过 `random` 属性可以随机排序数字键盘，常用于安全等级较高的场景。

```tsx
function RandomNumberKeyboard(props: KeyboardProps) {
  const { keyboard, onKeyboard, onKeyPress } = props
  return (
    <>
      <Cell
        clickable
        title="弹出配置随机数字的键盘"
        isLink
        onClick={() => onKeyboard?.("random")}
      />
      <NumberKeyboard
        open={keyboard === "random"}
        random
        onKeyPress={onKeyPress}
        onHide={() => onKeyboard?.("")}
      />
    </>
  )
}
```

## API

### NumberKeyboard Props

| 参数         | 说明            | 类型                                     | 默认值     |
| ---------- | ------------- | -------------------------------------- | ------- |
| value      | 当前输入值         | _string_                               | -       |
| open       | 是否显示键盘        | _boolean_                              | -       |
| title      | 键盘标题          | _string_                               | -       |
| maxlength  | 输入值最大长度       | _number \| string_                     | -       |
| transition | 是否开启过场动画      | _boolean_                              | `true`  |
| extraKey   | 底部额外按键的内容     | _ReactNode \| \[ReactNode, ReactNode]_ | `''`    |
| random     | 是否将通过随机顺序展示按键 | _boolean_                              | `false` |

### NumberKeyboard Events

| 事件名         | 说明        | 回调参数      |
| ----------- | --------- | --------- |
| onChange    | 点击按键时触发   | key: 按键内容 |
| onBackspace | 点击删除键时触发  | -         |
| onHide      | 点击关闭按钮时触发 | -         |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                          | 默认值                                         | 描述 |
| ------------------------------------------- | ------------------------------------------- | -- |
| number-keyboard-z-index                     | _100_                                       | -  |
| number-keyboard-background-color            | _var(--gray-2)_                             | -  |
| number-keyboard-with-title-border-radius    | _20px \* $hd 20px \* $hd 0 0_               | -  |
| number-keyboard-header-color                | _var(--gray-7)_                             | -  |
| number-keyboard-header-padding-top          | _6px \* $hd_                                | -  |
| number-keyboard-header-height               | _34px \* $hd_                               | -  |
| number-keyboard-header-font-size            | _var(--font-size-lg)_                       | -  |
| number-keyboard-key-height                  | _48px \* $hd_                               | -  |
| number-keyboard-key-font-size               | _28px \* $hd_                               | -  |
| number-keyboard-key-background-color        | _var(--white, $white)_                      | -  |
| number-keyboard-key-border-radius           | _var(--border-radius-lg)_                   | -  |
| number-keyboard-key-line-height             | _1.5_                                       | -  |
| number-keyboard-key-active-background-color | _var(--gray-3)_                             | -  |
| number-keyboard-key-active-opacity          | _var(--active-opacity)_                     | -  |
| number-keyboard-large-key-font-size         | _var(--font-size-lg)_                       | -  |
| number-keyboard-hide-padding                | _0 var(--padding-md)_                       | -  |
| number-keyboard-hide-font-size              | _24px \* $hd_                               | -  |
| number-keyboard-hide-color                  | _var(--text-link-color)_                    | -  |
| number-keyboard-hide-active-opacity         | _var(--number-keyboard-key-active-opacity)_ | -  |
| number-keyboard-backspace-font-size         | _22px \* $hd_                               | -  |
| number-keyboard-button-color                | _var(--white)_                              | -  |
| number-keyboard-button-background-color     | _var(--primary-color)_                      | -  |



---
url: https://taroify.com/components/password-input/index.md
---

# PasswordInput 密码输入框

### 介绍

带网格的输入框组件，可以用于输入密码、短信验证码等场景，通常与[数字键盘](/components/number-keyboard/index.md)组件配合使用。

### 引入

```tsx
import { PasswordInput } from "@taroify/core";
```

## 代码演示

### 基础用法

搭配数字键盘组件来实现密码输入功能。

```tsx
function BasicPasswordInput() {
  const [open, setOpen] = useState(false)
  const [value, setValue] = useState("123")

  return (
    <>
      <PasswordInput focus value={value} onFocus={() => setOpen(true)} />
      <NumberKeyboard
        open={open}
        onKeyPress={(key) => setValue(value + key)}
        onBackspace={() => setValue(value.substring(0, value.length - 1))}
        onHide={() => setOpen(false)}
      />
    </>
  )
}
```

### 自定义长度

通过 `length` 属性来设置密码长度。

```tsx
<PasswordInput length={6} value="123" />
```

### 格子间距

通过 `gutter` 属性来设置格子之间的间距。

```tsx
<PasswordInput gutter={10} value="123" />
```

### 明文展示

将 `mask` 设置为 `false` 可以明文展示输入的内容，适用于短信验证码等场景。

```tsx
<PasswordInput mask={false} value="123" />
```

### 提示信息

通过 `feedback` 属性设置提示信息，例如当输入六位时提示密码错误。

```tsx
<PasswordInput feedback="密码为 6 位数字" value="123" />
<PasswordInput feedback={{ color: "danger", children: "密码为 6 位数字" }} value="123" />
<PasswordInput feedback={<PasswordInput.Feedback color="danger" children="密码为 6 位数字" />} value="123" />
```

## API

### PasswordInput Props

| 参数       | 说明                                  | 类型                                                        | 默认值     |
| -------- | ----------------------------------- | --------------------------------------------------------- | ------- |
| value    | 密码值                                 | _string_                                                  | `''`    |
| length   | 密码最大长度                              | _number \| string_                                        | `6`     |
| gutter   | 输入框格子之间的间距，如 `20px` `2em`，默认单位为`px` | _number \| string_                                        | `0`     |
| mask     | 是否隐藏密码内容                            | _boolean_                                                 | `true`  |
| focus    | 是否聚焦，聚焦时会显示光标                       | _boolean_                                                 | `false` |
| feedback | 输入框下方文字提示                           | _ReactText \| PasswordInputFeedbackProps \| ReactElement_ | -       |

### PasswordInput Events

| 事件名     | 说明       | 回调参数 |
| ------- | -------- | ---- |
| onFocus | 输入框聚焦时触发 | -    |

### PasswordInput.Feedback Props

| 参数    | 说明                                                      | 类型       | 默认值 |
| ----- | ------------------------------------------------------- | -------- | --- |
| color | 颜色，可选值为 `primary` `info` `success`  `warning`  `danger` | _string_ | -   |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                       | 默认值                               | 描述 |
| ---------------------------------------- | --------------------------------- | -- |
| password-input-height                    | _50px \* $hd_                     | -  |
| password-input-margin                    | _0 var(--padding-md)_             | -  |
| password-input-border-radius             | _6px \* $hd_                      | -  |
| password-input-item-font-size            | _20px \* $hd_                     | -  |
| password-input-item-background-color     | _var(--white)_                    | -  |
| password-input-mask-size                 | _10px \* $hd_                     | -  |
| password-input-mask-width                | _var(--password-input-mask-size)_ | -  |
| password-input-mask-height               | _var(--password-input-mask-size)_ | -  |
| password-input-mask-color                | _var(--black)_                    | -  |
| password-input-cursor-color              | _var(--text-color)_               | -  |
| password-input-cursor-width              | _1px \* $hd_                      | -  |
| password-input-cursor-height             | _40%_                             | -  |
| password-input-cursor-animation-duration | _1s_                              | -  |
| password-input-feedback-margin-top       | _var(--padding-md)_               | -  |
| password-input-feedback-font-size        | _var(--font-size-md)_             | -  |
| password-input-feedback-color            | _var(--gray-6)_                   | -  |
| password-input-feedback-primary-color    | _var(--primary-color)_            | -  |
| password-input-feedback-info-color       | _var(--info-color)_               | -  |
| password-input-feedback-success-color    | _var(--success-color)_            | -  |
| password-input-feedback-warning-color    | _var(--warning-color)_            | -  |
| password-input-feedback-danger-color     | _var(--danger-color)_             | -  |



---
url: https://taroify.com/components/picker/index.md
---

# Picker 选择器

### 介绍

提供多个选项集合供用户选择，支持单列选择和多列级联，通常与[弹出层](/components/popup/index.md)组件配合使用。

### 引入

```tsx
import { Picker } from "@taroify/core"
```

## 代码演示

### 基础用法

```tsx
function BasicPicker() {
  const columns = useMemo(
    () => [
      { label: "杭州", value: "Hangzhou" },
      { label: "宁波", value: "Ningbo" },
      { label: "温州", value: "Wenzhou" },
      { label: "绍兴", value: "Shaoxing" },
      { label: "湖州", value: "Huzhou" },
    ],
    [],
  )

  return (
    <>
      <Toast id="toast" />
      <Picker
        title="标题"
        columns={columns}
        onChange={(value) => Toast.open(`当前值：${value}`)}
        onConfirm={(value) => Toast.open(`当前值：${value}`)}
      ></Picker>
    </>
  )
}
```

### 默认选中项

通过 `defaultValue` 属性设置初始选中项的值。

```tsx
function DefaultPicker() {
  const columns = useMemo(
    () => [
      { label: "杭州", value: "Hangzhou" },
      { label: "宁波", value: "Ningbo" },
      { label: "温州", value: "Wenzhou" },
      { label: "绍兴", value: "Shaoxing" },
      { label: "湖州", value: "Huzhou" },
    ],
    [],
  )
  return (
    <>
      <Toast id="toast" />
      <Picker
        defaultValue="Wenzhou"
        title="标题"
        columns={columns}
        onChange={(value) => Toast.open(`当前值：${value}`)}
        onConfirm={(value) => Toast.open(`当前值：${value}`)}
      ></Picker>
    </>
  )
}
```

### 多列选择

```tsx
function PickerWithMultiColumns() {
  const columns = useMemo(
    () => [
      [
        { label: "周一", value: "Monday" },
        { label: "周二", value: "Tuesday" },
        { label: "周三", value: "Wednesday" },
        { label: "周四", value: "Thursday" },
        { label: "周五", value: "Friday" },
      ],
      [
        { label: "上午", value: "morning" },
        { label: "下午", value: "afternoon" },
        { label: "晚上", value: "evening" },
      ],
    ],
    [],
  )
  return (
    <>
      <Toast id="toast" />
      <Picker
        defaultValue={["Monday", "evening"]}
        title="标题"
        columns={columns}
        onChange={(value) => Toast.open(`当前值：${value}`)}
        onConfirm={(value) => Toast.open(`当前值：${value}`)}
      ></Picker>
    </>
  )
}
```

### 禁用选项

通过设置 `disabled` 来禁用该选项。

```tsx
function DisabledPicker() {
  const columns = useMemo(
    () => [
      { label: "杭州", value: "Hangzhou" },
      { label: "宁波", value: "Ningbo" },
      { label: "温州", value: "Wenzhou", disabled: true },
      { label: "绍兴", value: "Shaoxing" },
      { label: "湖州", value: "Huzhou" },
    ],
    [],
  )
  return (
    <Picker
      columns={columns}
      onChange={(value) => Toast.open(`当前值：${value}`)}
      onConfirm={(value) => Toast.open(`当前值：${value}`)}
    ></Picker>
  )
}
```

> Tips: 通过设置 confirmText="",cancelText=""不显示顶部栏

### 加载状态

若选择器数据是异步获取的，可以通过 `loading` 属性显示加载提示。

```tsx
function LoadingPicker() {
  const columns = useMemo(
    () => [
      { label: "杭州", value: "Hangzhou" },
      { label: "宁波", value: "Ningbo" },
      { label: "温州", value: "Wenzhou" },
      { label: "绍兴", value: "Shaoxing" },
      { label: "湖州", value: "Huzhou" },
    ],
    [],
  )

  return (
    <>
      <Toast id="toast" />
      <Picker
        loading
        title="标题"
        columns={columns}
        onChange={(value) => Toast.open(`当前值：${value}`)}
        onConfirm={(value) => Toast.open(`当前值：${value}`)}
      ></Picker>
    </>
  )
}
```

### 搭配弹出层使用

在实际场景中，Picker 通常作为用于辅助表单填写，可以搭配 Popup 和 Field 实现该效果。

```tsx
function PickerPopup() {
  const [value, setValue] = useState("")
  const [openPicker, setOpenPicker] = useState(false)
  const columns = useMemo(
    () => [
      { label: "杭州", value: "Hangzhou" },
      { label: "宁波", value: "Ningbo" },
      { label: "温州", value: "Wenzhou" },
      { label: "绍兴", value: "Shaoxing" },
      { label: "湖州", value: "Huzhou" },
    ],
    [],
  )
  return (
    <>
      <Field label="城市" isLink onClick={() => setOpenPicker(true)}>
        <Input readonly placeholder="选择城市" value={value} />
      </Field>
      <Popup open={openPicker} rounded placement="bottom" onClose={setOpenPicker}>
        <Popup.Backdrop />
        <Picker
          title="搭配弹出层使用"
          cancelText="取消"
          confirmText="确认"
          columns={columns}
          onCancel={() => setOpenPicker(false)}
          onConfirm={(values) => {
            setValue(values as string)
            setOpenPicker(false)
          }}
        ></Picker>
      </Popup>
    </>
  )
}
```

### 手动控制 DOM

通过 `Picker.Toolbar` `Picker.Title` `Picker.Button` `Picker.Column` `Picker.Option` 手动控制 DOM 渲染

```tsx
function ManualPicker() {
  return (
    <>
      <Toast id="toast" />
      <Picker
        onChange={(value) => Toast.open(`当前值：${value}`)}
        onConfirm={(value) => Toast.open(`当前值：${value}`)}
      >
        <Picker.Toolbar>
          <Picker.Button>取消</Picker.Button>
          <Picker.Title>标题</Picker.Title>
          <Picker.Button>确认</Picker.Button>
        </Picker.Toolbar>
        <Picker.Column>
          <Picker.Option>周一</Picker.Option>
          <Picker.Option>周二</Picker.Option>
          <Picker.Option>周三</Picker.Option>
          <Picker.Option>周四</Picker.Option>
          <Picker.Option>周五</Picker.Option>
        </Picker.Column>
        <Picker.Column>
          <Picker.Option>上午</Picker.Option>
          <Picker.Option>下午</Picker.Option>
          <Picker.Option>晚上</Picker.Option>
        </Picker.Column>
      </Picker>
    </>
  )
}
```

## API

### Picker Props

| 参数                | 说明                                            | 类型                                              | 默认值                               |
| ----------------- | --------------------------------------------- | ----------------------------------------------- | --------------------------------- |
| defaultValue      | 默认选中的值                                        | _string \| string\[]_                           | -                                 |
| value             | 选中的值                                          | _string \| string\[]_                           | -                                 |
| title             | 顶部栏标题                                         | _ReactNode_                                     | -                                 |
| confirmText       | 确认按钮文字                                        | _ReactNode_                                     | `确认`                              |
| cancelText        | 取消按钮文字                                        | _ReactNode_                                     | `取消`                              |
| columns           | 对象数组，配置每一列显示的数据                               | _PickerOptionData\[] \| PickerOptionData\[]\[]_ | -                                 |
| columnsFieldNames | 自定义 columns 结构中的字段                            | _\{label?: string,value?: string}_              | `{label: "label",value: "value"}` |
| loading           | 是否显示加载状态                                      | _boolean_                                       | `false`                           |
| readonly          | 是否为只读状态，只读状态下无法切换选项                           | _boolean_                                       | `false`                           |
| siblingCount      | 可见的选项相邻个数                                     | _number_                                        | `3`                               |
| optionHeight      | 选项高度，支持 `px` `vw` `vh` `rem` `rpx` 单位，默认 `px` | _number\|string_                                | `44`                              |

### Picker Events

当选择器有多列时，事件回调参数会返回数组。

| 事件名       | 说明        | 回调参数                                         |
| --------- | --------- | -------------------------------------------- |
| onConfirm | 点击完成按钮时触发 | 单列：选中值，选中值对应的选项对象<br>多列：所有列选中值，所有列选中值对应的选项对象 |
| onCancel  | 点击取消按钮时触发 | 单列：选中值，选中值对应的选项对象<br>多列：所有列选中值，所有列选中值对应的选项对象 |
| onChange  | 选项改变时触发   | 单列：选中值，选中值对应的选项对象<br>多列：所有列选中值，当前列对应的选项对象    |

### Picker.Toolbar Props

| 参数       | 说明   | 类型         | 默认值 |
| -------- | ---- | ---------- | --- |
| children | 头部内容 | _ReactNoe_ | -   |

### Picker.Title Props

| 参数       | 说明    | 类型         | 默认值 |
| -------- | ----- | ---------- | --- |
| children | 顶部栏标题 | _ReactNoe_ | -   |

### Picker.Button Props

| 参数       | 说明   | 类型                      | 默认值 |
| -------- | ---- | ----------------------- | --- |
| children | 按钮内容 | _ReactNoe_              | -   |
| type     | 按钮类型 | _"cancel" \| "confirm"_ | -   |

### Picker.Column Props

| 参数       | 说明   | 类型         | 默认值 |
| -------- | ---- | ---------- | --- |
| children | 一列选项 | _ReactNoe_ | -   |

### Picker.Option Props

| 参数       | 说明     | 类型         | 默认值     |
| -------- | ------ | ---------- | ------- |
| children | 选项内容   | _ReactNoe_ | -       |
| value    | 选项对应的值 | _string_   | -       |
| label    | 选项内容   | _ReactNoe_ | -       |
| disabled | 是否禁用选项 | _boolean_  | `false` |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                         | 默认值                                       | 描述 |
| ------------------------------------------ | ----------------------------------------- | -- |
| --picker-background-color                  | _var(--white)_                            | -  |
| --picker-toolbar-height                    | _44px \* $hd_                             | -  |
| --picker-title-font-size                   | _var(--font-size-lg)_                     | -  |
| --picker-title-line-height                 | _var(--line-height-md)_                   | -  |
| --picker-action-padding                    | _0 var(--padding-md)_                     | -  |
| --picker-action-font-size                  | _var(--font-size-md)_                     | -  |
| --picker-confirm-action-color              | _var(--text-link-color)_                  | -  |
| --picker-cancel-action-color               | _var(--gray-6)_                           | -  |
| --picker-swipe-transition-duration         | _800ms_                                   | -  |
| --picker-column-transition-zero-duration   | _0_                                       | -  |
| --picker-column-transition-switch-duration | _200ms_                                   | -  |
| --picker-column-transition-duration        | _var(--picker-swipe-transition-duration)_ | -  |
| --picker-option-color                      | _var(--black)_                            | -  |
| --picker-option-padding                    | _0 var(--padding-base)_                   | -  |
| --picker-option-font-size                  | _var(--font-size-lg)_                     | -  |
| --picker-option-disabled-opacity           | _0.3_                                     | -  |
| --picker-loading-icon-color                | _var(--primary-color)_                    | -  |
| --picker-loading-mask-color                | _rgba(255, 255, 255, 0.9)_                | -  |



---
url: https://taroify.com/components/area-picker/index.md
---

# AreaPicker 省市区选择

### 介绍

省市区三级联动选择，通常与[弹出层](/components/popup.md)组件配合使用。

### 引入

```tsx
import { AreaPicker } from "@taroify/core"
```

## 代码演示

### 基础用法

初始化省市区组件时，需要通过 `areaList` 属性传入省市区数据。

```tsx
<AreaPicker areaList={areaList} />
```

### areaList 格式

areaList 为对象结构，包含 `province_list`、`city_list`、`county_list` 三个 key。

每项以地区码作为 key，省市区名字作为 value。地区码为 6 位数字，前两位代表省份，中间两位代表城市，后两位代表区县，以 0 补足 6 位。比如北京的地区码为 `11`，以 0 补足 6 位，为 `110000`。

示例数据如下：

```js
const areaList = {
  province_list: {
    110000: "北京市",
    120000: "天津市",
  },
  city_list: {
    110100: "北京市",
    120100: "天津市",
  },
  county_list: {
    110101: "东城区",
    110102: "西城区",
    // ....
  },
}
```

### @vant/area-data

Vant 官方提供了一份默认的省市区数据，可以通过 [@vant/area-data](https://github.com/youzan/vant/tree/dev/packages/vant-area-data) 引入：

```bash
# 通过 npm
npm i @vant/area-data

# 通过 yarn
yarn add @vant/area-data

# 通过 pnpm
pnpm add @vant/area-data
```

```tsx
import { areaList } from "@vant/area-data"
```

### 选中省市区

通过 `defaultValue` 设置默认值

通过 `value` `onChange` 控制选中

```tsx
<AreaPicker areaList={areaList} defaultValue={["330000", "330300", "330305"]} />
```

### 配置显示列

可以通过 `depth` 属性配置省市区显示的列数，默认情况下会显示省市区，当你设置为 `2`，则只会显示省市选择。

```tsx
<AreaPicker depth={2} areaList={areaList} />
```

### 手动控制 DOM

初始化省市区组件时，需要通过 `AreaPicker.Columns` 子组件传入省市区数据。

```tsx
import { AreaPicker } from "@taroify/core"
import { areaList } from "@vant/area-data"

function BasicAreaPicker() {
  return (
    <AreaPicker>
      <AreaPicker.Toolbar>
        <AreaPicker.Button>取消</AreaPicker.Button>
        <AreaPicker.Title>标题</AreaPicker.Title>
        <AreaPicker.Button>确认</AreaPicker.Button>
      </AreaPicker.Toolbar>
      <AreaPicker.Columns children={areaList} />
    </AreaPicker>
  )
}
```

## API

### Props

| 参数           | 说明                                            | 类型               | 默认值     |
| ------------ | --------------------------------------------- | ---------------- | ------- |
| defaultValue | 默认选中的值                                        | _string\[]_      | -       |
| value        | 选中的值                                          | _string\[]_      | -       |
| areaList     | 省市区数据                                         | _object_         | -       |
| depth        | 显示列数，3-省市区，2-省市，1-省                           | _string_         | `3`     |
| title        | 顶部栏标题                                         | _ReactNode_      | -       |
| confirmText  | 确认按钮文字                                        | _ReactNode_      | `确认`    |
| cancelText   | 取消按钮文字                                        | _ReactNode_      | `取消`    |
| loading      | 是否显示加载状态                                      | _boolean_        | `false` |
| readonly     | 是否为只读状态，只读状态下无法切换选项                           | _boolean_        | `false` |
| siblingCount | 可见的选项相邻个数                                     | _number_         | `3`     |
| optionHeight | 选项高度，支持 `px` `vw` `vh` `rem` `rpx` 单位，默认 `px` | _number\|string_ | `44`    |

### Events

| 事件        | 说明        | 回调参数                                                                        |
| --------- | --------- | --------------------------------------------------------------------------- |
| onConfirm | 点击完成按钮时触发 | _values: string\[], options: PickerOptionObject\[]_                         |
| onCancel  | 点击取消按钮时触发 | _values: string\[], options: PickerOptionObject\[]_                         |
| onChange  | 选项改变时触发   | _values: string\[], option: PickerOptionObject, column: PickerOptionObject_ |



---
url: https://taroify.com/components/radio/index.md
---

# Radio 单选框

### 介绍

在一组备选项中进行单选。

### 引入

```tsx
import { Radio } from "@taroify/core";
```

## 代码演示

### 基础用法

通过 `value` 绑定值当前选中项的 name。

```tsx
<Radio.Group defaultValue="1">
  <Radio name="1">单选框 1</Radio>
  <Radio name="2">单选框 2</Radio>
</Radio.Group>
```

### 水平排列

将 `direction` 属性设置为 `horizontal` 后，单选框组会变成水平排列。

```tsx
<Radio.Group defaultValue="1" direction="horizontal">
  <Radio name="1">单选框 1</Radio>
  <Radio name="2">单选框 2</Radio>
</Radio.Group>
```

### 禁用状态

通过 `disabled` 属性禁止选项切换，在 `Radio` 上设置 `disabled` 可以禁用单个选项。

```tsx
<Radio.Group defaultValue="1" disabled>
  <Radio name="1">单选框 1</Radio>
  <Radio name="2">单选框 2</Radio>
</Radio.Group>
```

### 自定义形状

将 `shape` 属性设置为 `square`，单选框的形状会变成方形。

```tsx
<Radio.Group defaultValue="1">
  <Radio name="1" shape="square">
    单选框 1
  </Radio>
  <Radio name="2" shape="square">
    单选框 2
  </Radio>
</Radio.Group>
```

### 按钮形状

将 `shape` 属性设置为 `button`，单选框会变成适合规格选择等场景的按钮。按钮形状下，`icon` 和 `size` 属性不生效。

```tsx
<Radio.Group defaultValue="a" direction="horizontal">
  <Radio name="a" shape="button">单选框 a</Radio>
  <Radio name="b" shape="button">单选框 b</Radio>
</Radio.Group>
```

### 自定义颜色

通过 `css` 属性设置选中状态的图标颜色。

```tsx
<Radio.Group className="custom-color" defaultValue="1">
  <Radio name="1">单选框 1</Radio>
  <Radio name="2">单选框 2</Radio>
</Radio.Group>
```

```scss
.custom-color {
  --radio-checked-icon-background-color: #ee0a24;
  --radio-checked-icon-border-color: #ee0a24;
}
```

### 自定义大小

通过 `size` 属性可以自定义图标的大小。

```tsx
<Radio.Group defaultValue="1" size={24}>
  <Radio name="1">单选框 1</Radio>
  <Radio name="2">单选框 2</Radio>
</Radio.Group>
```

### 自定义图标

通过 `icon` 属性自定义图标。

```tsx
function CustomIconRadio() {
  const [value, setValue] = useState("1")
  return (
    <Radio.Group value={value} onChange={setValue}>
      <Radio
        name="1"
        icon={
          <Image
            src={`https://img.yzcdn.cn/vant/user-${value === "1" ? "active" : "inactive"}.png`}
            style={{
              width: "25px",
              height: "20px",
            }}
          />
        }
      >
        单选框 1
      </Radio>
      <Radio
        name="2"
        icon={
          <Image
            src={`https://img.yzcdn.cn/vant/user-${value === "2" ? "active" : "inactive"}.png`}
            style={{
              width: "25px",
              height: "20px",
            }}
          />
        }
      >
        单选框 1
      </Radio>
    </Radio.Group>
  )
}
```

### 与 Cell 组件一起使用

此时你需要再引入 `Cell` 和 `Cell.Group` 组件。

```tsx
<Radio.Group defaultValue="1">
  <Cell.Group clickable>
    <Cell title="单选框 1">
      <Radio name="1" />
    </Cell>
    <Cell title="单选框 2">
      <Radio name="2" />
    </Cell>
  </Cell.Group>
</Radio.Group>
```

## API

### Radio Props

| 参数                         | 说明                        | 类型                 | 默认值     |
| -------------------------- | ------------------------- | ------------------ | ------- |
| name                       | 标识符                       | _any_              | -       |
| shape <Tag tag="v1.0.0" /> | 形状，可选值为 `square` `button` | _string_           | `round` |
| disabled                   | 是否为禁用状态                   | _boolean_          | `false` |
| size                       | 图标大小，默认单位为`px`            | _number \| string_ | `20px`  |

### Radio.Group Props

| 参数           | 说明                    | 类型                 | 默认值        |
| ------------ | --------------------- | ------------------ | ---------- |
| defaultValue | 默认选中项的标识符             | _any_              | -          |
| value        | 当前选中项的标识符             | _any_              | -          |
| disabled     | 是否禁用所有单选框             | _boolean_          | `false`    |
| direction    | 排列方向，可选值为`horizontal` | _string_           | `vertical` |
| size         | 所有单选框的图标大小，默认单位为`px`  | _number \| string_ | `20px`     |

### Radio.Group Events

| 事件名      | 说明           | 回调参数           |
| -------- | ------------ | -------------- |
| onChange | 当绑定值变化时触发的事件 | _name: string_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                                           | 默认值                                    | 描述 |
| ------------------------------------------------------------ | -------------------------------------- | -- |
| --radio-size                                                 | _20px \* $hd_                          | -  |
| --radio-font-size                                            | _var(--font-size-lg)_                  | -  |
| --radio-border-color                                         | _var(--gray-5)_                        | -  |
| --radio-transition-duration                                  | _var(--animation-duration-fast)_       | -  |
| --radio-gap                                                  | _var(--padding-sm)_                    | -  |
| --radio-label-margin                                         | _var(--padding-xs)_                    | -  |
| --radio-label-color                                          | _var(--text-color)_                    | -  |
| --radio-label-line-height                                    | _var(--radio-size)_                    | -  |
| --radio-disabled-label-color                                 | _var(--gray-5)_                        | -  |
| --radio-icon-font-size                                       | _var(--radio-size)_                    | -  |
| --radio-checked-icon-color                                   | _var(--white)_                         | -  |
| --radio-checked-icon-border-color                            | _var(--primary-color)_                 | -  |
| --radio-checked-icon-background-color                        | _var(--primary-color)_                 | -  |
| --radio-disabled-icon-color                                  | _var(--gray-5)_                        | -  |
| --radio-disabled-icon-border-color                           | _var(--gray-5)_                        | -  |
| --radio-disabled-icon-background-color                       | _var(--border-color)_                  | -  |
| --radio-button-padding <Tag tag="v1.0.0" />                  | _5px \* $hd 18px \* $hd_               | -  |
| --radio-button-border-radius <Tag tag="v1.0.0" />            | _var(--border-radius-max)_             | -  |
| --radio-button-color <Tag tag="v1.0.0" />                    | _var(--text-color)_                    | -  |
| --radio-button-background-color <Tag tag="v1.0.0" />         | _var(--gray-1)_                        | -  |
| --radio-button-border-color <Tag tag="v1.0.0" />             | _var(--radio-button-background-color)_ | -  |
| --radio-button-checked-color <Tag tag="v1.0.0" />            | _var(--primary-color)_                 | -  |
| --radio-button-checked-background-color <Tag tag="v1.0.0" /> | _var(--white)_                         | -  |
| --radio-button-checked-border-color <Tag tag="v1.0.0" />     | _var(--primary-color)_                 | -  |
| --radio-button-disabled-opacity <Tag tag="v1.0.0" />         | _var(--disabled-opacity)_              | -  |



---
url: https://taroify.com/components/rate/index.md
---

# Rate 评分

### 介绍

用于对事物进行评级操作。

### 引入

```tsx
import { Rate } from "@taroify/core"
```

## 代码演示

### 基础用法

通过 `value` 来绑定当前评分值。

```tsx
<Rate value={3} />
```

### 自定义图标

通过 `fullIcon` 属性设置选中时的图标，`voidIcon` 属性设置未选中时的图标。

```tsx
<Rate defaultValue={3} icon={<Like />} emptyIcon={<LikeOutlined />} />
```

### 自定义样式

通过 `size` 属性设置图标大小，`css` 设置选中时的颜色，`emptyIcon` 设置未选中时的颜色。

```tsx
 <Rate className="custom-color" defaultValue={3} allowHalf size={25} emptyIcon={<Star />} />
```

```scss
.custom-color {
  --rate-icon-empty-color: #eee;
  --rate-icon-full-color: #ffd21e;
}
```

### 半星

设置 `allowHalf` 属性后可以选中半星。

```tsx
<Rate defaultValue={3} allowHalf />
```

### 自定义数量

通过 `count` 属性设置评分总数。

```tsx
<Rate defaultValue={3} count={6} />
```

### 禁用状态

通过 `disabled` 属性来禁用评分。

```tsx
<Rate defaultValue={3} disabled />
```

### 只读状态

通过 `readonly` 属性将评分设置为只读状态。

```tsx
<Rate defaultValue={3} readonly />
```

### 只读状态显示小数

设置 `readonly` 和 `allowHalf` 属性后，Rate 组件可以展示任意小数结果。

```tsx
<Rate defaultValue={3.3} readonly allowHalf />
```

## API

### Props

| 参数           | 说明                  | 类型                 | 默认值                |
| ------------ | ------------------- | ------------------ | ------------------ |
| defaultValue | 默认当前分值              | _number_           | -                  |
| value        | 当前分值                | _number_           | -                  |
| count        | 图标总数                | _number \| string_ | `5`                |
| size         | 图标大小，默认单位为`px`      | _number \| string_ | `20px`             |
| gutter       | 图标间距，默认单位为`px`      | _number \| string_ | `4px`              |
| icon         | 选中时的图标              | _string_           | `<Star />`         |
| emptyIcon    | 未选中时的图标             | _string_           | `<StarOutlined />` |
| allowHalf    | 是否允许半选              | _boolean_          | `false`            |
| readonly     | 是否为只读状态，只读状态下无法修改评分 | _boolean_          | `false`            |
| disabled     | 是否禁用评分              | _boolean_          | `false`            |
| touchable    | 是否可以通过滑动手势选择评分      | _boolean_          | `true`             |

### Events

| 事件名      | 说明           | 回调参数            |
| -------- | ------------ | --------------- |
| onChange | 当前分值变化时触发的事件 | _value :number_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                       | 默认值                   | 描述 |
| ------------------------ | --------------------- | -- |
| rate-icon-size           | _20px \* $hd_         | -  |
| rate-icon-gutter         | _var(--padding-base)_ | -  |
| rate-icon-empty-color    | _var(--gray-5)_       | -  |
| rate-icon-full-color     | _var(--danger-color)_ | -  |
| rate-icon-disabled-color | _var(--gray-5)_       | -  |



---
url: https://taroify.com/components/search/index.md
---

# Search 搜索

### 介绍

用于搜索场景的输入框组件。

### 引入

```tsx
import { Search } from "@taroify/core"
```

## 代码演示

### 基础用法

`value` 用于控制搜索框中的文字，`onChange` 可以获得改变的值。

```tsx
function BasicSearch() {
  const [value, setValue] = useState("")
  return (
    <Search
      value={value}
      placeholder="请输入搜索关键词"
      onChange={(e) => setValue(e.detail.value)}
    />
  )
}
```

### 事件监听

Search 组件提供了 `onSearch` 和 `onCancel` 事件，`onSearch` 事件在点击键盘上的搜索/回车按钮后触发，`onCancel` 事件在点击搜索框右侧取消按钮时触发。

```tsx
function SearchWithEvents() {
  const [value, setValue] = useState("")
  const [open, setOpen] = useState(false)

  return (
    <>
      <Toast open={open} onClose={() => setOpen(false)}>
        取消
      </Toast>
      <Search
        value={value}
        placeholder="请输入搜索关键词"
        action
        onChange={(e) => setValue(e.detail.value)}
        onCancel={() => setOpen(true)}
      />
    </>
  )
}
```

### 搜索框内容对齐

通过 `inputAlign` 属性设置搜索框内容的对齐方式，可选值为 `center`、`right`。

```tsx
function InputCenterSearch() {
  const [value, setValue] = useState("")
  return (
    <Search
      value={value}
      placeholder="请输入搜索关键词"
      inputAlign="center"
      onChange={(e) => setValue(e.detail.value)}
    />
  )
}
```

### 禁用搜索框

通过 `disabled` 属性禁用搜索框。

```tsx
<Search disabled placeholder="请输入搜索关键词" />
```

### 自定义背景色

通过 `className` 属性可以设置搜索框外部的背景色，通过 `shape="rounded"` 属性设置搜索框的形状。

```tsx
<Search className="background" shape="rounded" disabled placeholder="请输入搜索关键词" />
```

```scss
.background {
  --search-background-color: #4fc08d;
}
```

### 自定义按钮

使用 `action` 插槽可以自定义右侧按钮的内容。使用插槽后，`cancel` 事件将不再触发。

```tsx
function CustomSearch() {
  const [value, setValue] = useState("")
  const [open, setOpen] = useState(false)
  return (
    <>
      <Toast open={open} onClose={() => setOpen(false)}>
        搜索
      </Toast>
      <Search
        value={value}
        label="地址"
        placeholder="请输入搜索关键词"
        action={<View onClick={() => setOpen(true)}>搜索</View>}
        onChange={(e) => setValue(e.detail.value)}
      />
    </>
  )
}
```

## API

### Props

| 参数           | 说明                                                         | 类型                                                                                            | 默认值          |
| ------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------ |
| label        | 搜索框左侧文本                                                    | _string_                                                                                      | -            |
| shape        | 搜索框形状，可选值为 `square` `rounded`                              | _string_                                                                                      | -            |
| maxlength    | 输入的最大字符数                                                   | _number \| string_                                                                            | -            |
| placeholder  | 占位提示文字                                                     | _string_                                                                                      | -            |
| autoFocus    | 自动聚焦，iOS 系统不支持该属性                                          | _boolean_                                                                                     | `false`      |
| focus        | 获取焦点                                                       | _boolean_                                                                                     | `false`      |
| disabled     | 是否禁用输入框                                                    | _boolean_                                                                                     | `false`      |
| readonly     | 是否将输入框设为只读状态，只读状态下无法输入内容                                   | _boolean_                                                                                     | `false`      |
| icon         | 输入框左侧图标                                                    | _ReactNode_                                                                                   | `<Search />` |
| rightIcon    | 输入框右侧图标                                                    | _ReactNode_                                                                                   | -            |
| action       | 是否在搜索框右侧显示取消按钮                                             | _boolean \| ReactNode_                                                                        | `false`      |
| inputAlign   | 输入框内容对齐方式，可选值为 `center` `right`                            | _string_                                                                                      | `left`       |
| inputColor   | 输入框内容颜色，可选值为 `primary` `info` `success` `warning` `danger` | _string_                                                                                      | -            |
| clearable    | 是否启用清除图标，点击清除图标后会清空输入框                                     | _boolean_                                                                                     | `true`       |
| clearIcon    | 清除图标                                                       | _string_                                                                                      | `<Clear />`  |
| clearTrigger | 显示清除图标的时机，`always` 表示输入框不为空时展示，<br>`focus` 表示输入框聚焦且不为空时展示  | _string_                                                                                      | `focus`      |
| feedback     | 提示文案，为空时不展示                                                | _string \| [FormFeedbackProps](/components/form/index.md#formfeedback-props) \| ReactElement_ | -            |
| enableNative | 使用原生键盘（仅支付宝小程序）                                            | _boolean_                                                                                     | `true`       |

### Events

| 事件名      | 说明         | 回调参数                                                      |
| -------- | ---------- | --------------------------------------------------------- |
| onSearch | 确定搜索时触发    | _event: BaseEventOrig\<InputProps.inputValueEventDetail>_ |
| onChange | 输入框内容变化时触发 | _event: BaseEventOrig\<InputProps.inputEventDetail>_      |
| onFocus  | 输入框获得焦点时触发 | _event: BaseEventOrig\<InputProps.inputForceEventDetail>_ |
| onBlur   | 输入框失去焦点时触发 | _event: BaseEventOrig\<InputProps.inputForceEventDetail>_ |
| onClear  | 点击清除按钮后触发  | _event: event: ITouchEvent_                               |
| onCancel | 点击取消按钮时触发  | _event: event: ITouchEvent_                               |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                      | 默认值                                         | 描述 |
| --------------------------------------- | ------------------------------------------- | -- |
| --search-padding                        | _10px \* $hd var(--padding-sm)_             | -  |
| --search-background-color               | _var(--white)_                              | -  |
| --search-content-padding-left           | _var(--padding-sm)_                         | -  |
| --search-content-background-color       | _var(--gray-1)_                             | -  |
| --search-content-border-radius          | _var(--border-radius-sm)_                   | -  |
| --search-content-square-border-radius   | _0_                                         | -  |
| --search-content-rounded-border-radius  | _var(--border-radius-max)_                  | -  |
| --search-input-height                   | _34px \* $hd_                               | -  |
| --search-label-padding                  | _0 5px \* $hd_                              | -  |
| --search-label-color                    | _var(--text-color)_                         | -  |
| --search-label-font-size                | _var(--font-size-md)_                       | -  |
| --search-label-line-height              | _var(--search-input-height)_                | -  |
| --search-field-padding                  | _5px \* $hd var(--padding-xs) 5px \* $hd 0_ | -  |
| --search-left-icon-color                | _var(--gray-6)_                             | -  |
| --search-action-padding                 | _0 var(--padding-xs)_                       | -  |
| --search-action-color                   | _var(--text-color)_                         | -  |
| --search-action-line-height             | _var(--search-input-height)_                | -  |
| --search-action-font-size               | _var(--font-size-md)_                       | -  |
| --search-action-active-background-color | _var(--active-color)_                       | -  |



---
url: https://taroify.com/components/slider/index.md
---

# Slider 滑块

### 介绍

滑动输入条，用于在给定的范围内选择一个值。

### 引入

```tsx
import { Slider } from "@taroify/core"
```

## 代码演示

### 基础用法

```tsx
<Slider defaultValue={50} />
```

### 双滑块

添加 `range` 属性就可以开启双滑块模式，确保 `value` 的值是一个数组。

```tsx
<Slider range defaultValue={[20, 60]} />
```

### 指定选择范围

```tsx
<Slider min={-50} max={50} defaultValue={0} />
```

### 禁用

```tsx
<Slider disabled defaultValue={50} />
```

### 指定步长

```tsx
<Slider step={10} defaultValue={50} />
```

### 自定义样式

```tsx
<Slider className="custom-color" size={4} defaultValue={50} />
```

```scss
.custom-color {
  --slider-active-background-color: #ee0a24;
}
```

### 自定义按钮

```tsx
function StyledThumbSlider() {
  const [value, setValue] = useState(50)
  return (
    <Slider className="custom-color" value={value} onChange={setValue}>
      <Slider.Thumb>
        <View className="custom-thumb">{value}</View>
      </Slider.Thumb>
    </Slider>
  )
}
```

```scss
.custom-color {
  --slider-active-background-color: #ee0a24;
}

.custom-thumb {
  width: 26px * 2;
  color: #fff;
  font-size: 10px * 2;
  line-height: 18px * 2;
  text-align: center;
  background-color: var(--slider-active-background-color);
  border-radius: 100px * 2;
}
```

### 垂直方向

设置 `orientation="vertical"` 属性后，滑块会垂直展示，且高度为 100% 父元素高度。

```tsx
<Slider orientation="vertical" defaultValue={50} />
<Slider
  style={{ marginLeft: "100px" }}
  range
  orientation="vertical"
  defaultValue={[20, 60]}
/>
```

## API

### Slider Props

| 参数           | 说明                        | 类型                            | 默认值          |
| ------------ | ------------------------- | ----------------------------- | ------------ |
| defaultValue | 当前进度百分比，在双滑块模式下为数组格式      | _number \| \[number, number]_ | `0`          |
| value        | 当前进度百分比，在双滑块模式下为数组格式      | _number \| \[number, number]_ | `0`          |
| max          | 最大值                       | _number \| string_            | `100`        |
| min          | 最小值                       | _number \| string_            | `0`          |
| step         | 步长                        | _number \| string_            | `1`          |
| size         | 进度条高度，默认单位为 `px`          | _number \| string_            | `2px`        |
| range        | 是否开启双滑块模式                 | _boolean_                     | `false`      |
| disabled     | 是否禁用滑块                    | _boolean_                     | `false`      |
| readonly     | 是否为只读状态，只读状态下无法修改滑块的值     | _boolean_                     | `false`      |
| orientation  | 滑块按钮展示方向，`vertical` 为垂直展示 | _SliderOrientation_           | `horizontal` |

### Slider.Thumb Props

| 参数   | 说明                | 类型                 | 默认值    |
| ---- | ----------------- | ------------------ | ------ |
| size | 滑块按钮大小，默认单位为 `px` | _number \| string_ | `24px` |

### Slider Events

| 事件名      | 说明           | 回调参数            |
| -------- | ------------ | --------------- |
| onChange | 进度变化且结束拖动后触发 | _value: number_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                 | 默认值                                          | 描述 |
| ---------------------------------- | -------------------------------------------- | -- |
| --slider-border-radius             | _var(--border-radius-max)_                   | -  |
| --slider-active-background-color   | _var(--blue)_                                | -  |
| --slider-inactive-background-color | _var(--gray-3)_                              | -  |
| --slider-disabled-opacity          | _var(--disabled-opacity)_                    | -  |
| --slider-track-height              | _2px \* $hd_                                 | -  |
| --slider-track-transition-duration | _var(--animation-duration-fast)_             | -  |
| --slider-thumb-width               | _24px \* $hd_                                | -  |
| --slider-thumb-height              | _24px \* $hd_                                | -  |
| --slider-thumb-border-radius       | _50%_                                        | -  |
| --slider-thumb-background-color    | _var(--white)_                               | -  |
| --slider-thumb-box-shadow          | _0 1px \* $hd 2px \* $hd rgba(0, 0, 0, 0.5)_ | -  |



---
url: https://taroify.com/components/signature/index.md
---

# Signature 签名

### 介绍

用于签名场景的组件，基于 Canvas 实现。

请升级 `taroify` 到 >= `v0.1.1-alpha.2` 版本来使用该组件。

### 引入

```ts
import { Signature } from "@taroify/core"
```

## 代码演示

### 基础用法

Canvas 实例提供两个方法

- `getImage`
  - `image`：签名对应的图片，为 base64 字符串格式。若签名为空，则返回空字符串。
  - `canvas`：Canvas 元素。
- `clear`：清空

```tsx
import { Signature, SignatureInstance, Flex, Button } from "@taroify/core"

function BasicSignature() {
  const ref = useRef<SignatureInstance>(null)
  return (
    <>
      <Signature ref={ref} />
      <Flex justify="end">
        <Button
          size="small"
          onClick={() => {
            ref.current?.clear()
          }}
          style={{ marginRight: "1rem" }}
        >
          取消
        </Button>
        <Button
          size="small"
          color="primary"
          onClick={() => {
            console.log(ref.current?.getImage())
          }}
        >
          确认
        </Button>
      </Flex>
    </>
  )
}
```

### 自定义颜色

通过 `penColor` 来自定义笔触颜色。

```tsx
<Signature penColor="#ff0000" />
```

### 自定义线宽

通过 `lineWidth` 来自定义线条宽度。

```tsx
<Signature lineWidth={6} />
```

### 自定义背景颜色

通过 `backgroundColor` 来自定义背景颜色。

```tsx
<Signature backgroundColor="#eee" />
```

## API

### Signature Props

| 参数              | 说明        | 类型       | 默认值              |
| --------------- | --------- | -------- | ---------------- |
| type            | 导出图片类型    | _string_ | `png`            |
| penColor        | 笔触颜色，默认黑色 | _string_ | `#000`           |
| lineWidth       | 线条宽度      | _number_ | `3`              |
| backgroundColor | 背景颜色      | _string_ | -                |
| canvasId        | canvas id | _string_ | `taroify-canvas` |

### Signature Events

| 事件名       | 说明      | 回调参数 |
| --------- | ------- | ---- |
| onStart   | 开始签名时触发 | -    |
| onEnd     | 结束签名时触发 | -    |
| onSigning | 签名过程中触发 | -    |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                             | 默认值                         | 描述     |
| ------------------------------ | --------------------------- | ------ |
| --signature-padding            | _var(--van-padding-xs)_     | -      |
| --signature-content-height     | _200px_                     | 画布高度   |
| --signature-content-background | _var(--background-color-2)_ | 画布背景色  |
| --signature-content-border     | _1px dotted #dadada_        | 画布边框样式 |
| --signature-border-radius      | _8px_                       | 画布圆角   |



---
url: https://taroify.com/components/stepper/index.md
---

# Stepper 步进器

### 介绍

步进器由增加按钮、减少按钮和输入框组成，用于在一定范围内输入、调整数字。

### 引入

```tsx
import { Stepper } from "@taroify/core"
```

## 代码演示

### 基础用法

```tsx
<Stepper />
```

### 步长设置

通过 `step` 属性设置每次点击增加或减少按钮时变化的值，默认为 `1`。

```tsx
<Stepper step={2} />
```

### 限制输入范围

通过 `min` 和 `max` 属性限制输入值的范围。

```tsx
<Stepper min={5} max={8} />
```

### 禁用状态

通过设置 `disabled` 属性来禁用步进器，禁用状态下无法点击按钮或修改输入框。

```tsx
<Stepper disabled />
```

### 禁用输入框

通过设置 `Stepper.Input` 组件的 `disabled` 属性来禁用输入框，此时按钮仍然可以点击。

```tsx
<Stepper>
  <Stepper.Button />
  <Stepper.Input disabled />
  <Stepper.Button />
</Stepper>
```

### 固定小数位数

通过设置 `precision` 属性可以保留固定的小数位数。

```tsx
<Stepper precision={2} />
```

### 自定义大小

通过 `Stepper.Input` 组件的 `width` 属性设置输入框宽度，通过 `size` 属性设置按钮大小和输入框高度。

```tsx
<Stepper size="32">
  <Stepper.Button />
  <Stepper.Input disabled width="40" />
  <Stepper.Button />
</Stepper>
```

### 圆角风格

将 `shape` 设置为 `circular` 来展示圆角风格的步进器。

```tsx
<Stepper shape="circular" size="22" />
```

## API

### Stepper Props

| 参数           | 说明                            | 类型                 | 默认值       |
| ------------ | ----------------------------- | ------------------ | --------- |
| defaultValue | 默认输入的值                        | _number \| string_ | -         |
| value        | 当前输入的值                        | _number \| string_ | -         |
| min          | 最小值                           | _number \| string_ | `1`       |
| max          | 最大值                           | _number \| string_ | -         |
| step         | 步长，每次点击时改变的值                  | _number \| string_ | `1`       |
| size         | 按钮大小以及输入框高度，默认单位为 `px`        | _number \| string_ | `28px`    |
| precision    | 固定显示的小数位数                     | _number \| string_ | -         |
| shape        | 样式风格，可选值为 `square` `circular` | _string_           | `rounded` |
| placeholder  | 输入框占位提示文字                     | _string_           | -         |
| disabled     | 是否禁用步进器                       | _boolean_          | `false`   |
| longPress    | 是否开启长按手势                      | _boolean_          | `true`    |

### Stepper.Input Props

| 参数       | 说明               | 类型                 | 默认值     |
| -------- | ---------------- | ------------------ | ------- |
| width    | 输入框宽度，默认单位为 `px` | _number \| string_ | `32px`  |
| disabled | 是否禁用输入框          | _boolean_          | `false` |
| cursor   | 指定 focus 时的光标位置  | _number_           | -       |

### Stepper.Button Props

| 参数       | 说明     | 类型        | 默认值     |
| -------- | ------ | --------- | ------- |
| disabled | 是否禁用按钮 | _boolean_ | `false` |

### Events

| 事件名      | 说明           | 回调参数            |
| -------- | ------------ | --------------- |
| onChange | 当绑定值变化时触发的事件 | _value: string_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                                  | 默认值                                           | 描述 |
| --------------------------------------------------- | --------------------------------------------- | -- |
| --stepper-active-background-color                   | _#e8e8e8_                                     | -  |
| --stepper-background-color                          | _var(--active-color)_                         | -  |
| --stepper-input-width                               | _32px \* $hd_                                 | -  |
| --stepper-input-height                              | _28px \* $hd_                                 | -  |
| --stepper-input-margin                              | _0 2px \* $hd_                                | -  |
| --stepper-input-font-size                           | _var(--font-size-md)_                         | -  |
| --stepper-input-line-height                         | _normal_                                      | -  |
| --stepper-input-color                               | _var(--text-color)_                           | -  |
| --stepper-input-background-color                    | _var(--stepper-background-color)_             | -  |
| --stepper-input-disabled-color                      | _var(--gray-5)_                               | -  |
| --stepper-input-disabled-background-color           | _var(--active-color)_                         | -  |
| --stepper-button-icon-color                         | _var(--text-color)_                           | -  |
| --stepper-button-disabled-color                     | _var(--gray-5)_                               | -  |
| --stepper-button-disabled-background-color          | _var(--background-color)_                     | -  |
| --stepper-rounded-button-border-radius              | _var(--border-radius-md)_                     | -  |
| --stepper-rounded-decrease-button-border-radius     | _var(--stepper-rounded-button-border-radius)_ | -  |
| --stepper-rounded-increase-button-border-radius     | _var(--stepper-rounded-button-border-radius)_ | -  |
| --stepper-circular-decrease-button-color            | _var(--danger-color)_                         | -  |
| --stepper-circular-decrease-button-background-color | _var(--white)_                                | -  |
| --stepper-circular-decrease-button-border-color     | _var(--danger-color)_                         | -  |
| --stepper-circular-increase-button-color            | _var(--white)_                                | -  |
| --stepper-circular-increase-button-background-color | _var(--blue, $blue)_                          | -  |



---
url: https://taroify.com/components/switch/index.md
---

# Switch 开关

### 介绍

用于在打开和关闭状态之间进行切换。

### 引入

```tsx
import { Switch } from "@taroify/core"
```

## 代码演示

### 基础用法

通过 `checked` 绑定开关的选中状态，`true` 表示开，`false` 表示关。

```tsx
<Switch />
```

### 禁用状态

通过 `disabled` 属性来禁用开关，禁用状态下开关不可点击。

```tsx
<Switch disabled />
```

### 加载状态

通过 `loading` 属性设置开关为加载状态，加载状态下开关不可点击。

```tsx
<Switch loading />
```

### 自定义大小

通过 `size` 属性自定义开关的大小。

```tsx
<Switch size="24" />
```

### 自定义颜色

通过 `css` 设置打开与关闭时的背景色。

```tsx
<Switch className="custom-color" />
```

```scss
.custom-color {
  --switch-background-color: #dcdee0;
  --switch-checked-color: #ee0a24;
}
```

### 搭配单元格使用

```tsx
<Cell align="center" title="标题" extra={<Switch size="24" />} />
```

## API

### Props

| 参数             | 说明             | 类型                 | 默认值     |
| -------------- | -------------- | ------------------ | ------- |
| defaultChecked | 默认开关选中状态       | _boolean_          | `false` |
| checked        | 开关选中状态         | _boolean_          | `false` |
| loading        | 是否为加载状态        | _boolean_          | `false` |
| disabled       | 是否为禁用状态        | _boolean_          | `false` |
| size           | 开关尺寸，默认单位为`px` | _number \| string_ | `30px`  |

### Events

| 事件名      | 说明        | 回调参数             |
| -------- | --------- | ---------------- |
| onChange | 开关状态切换时触发 | _value: boolean_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                              | 默认值                                                                                                                                                    | 描述 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -- |
| switch-size                     | _30px \* $hd_                                                                                                                                          | -  |
| switch-font-size                | _var(--switch-size)_                                                                                                                                   | -  |
| switch-width                    | _2em_                                                                                                                                                  | -  |
| switch-height                   | _1em_                                                                                                                                                  | -  |
| switch-border                   | _var(--border-width-base) solid rgba(0, 0, 0, 0.1)_                                                                                                    | -  |
| switch-background-color         | _var(--white)_                                                                                                                                         | -  |
| switch-transition-duration      | _var(--animation-duration-base)_                                                                                                                       | -  |
| switch-node-size                | _1em_                                                                                                                                                  | -  |
| switch-node-width               | _var(--switch-node-size)_                                                                                                                              | -  |
| switch-node-height              | _var(--switch-node-size)_                                                                                                                              | -  |
| switch-node-translate-x         | _translateX(calc(var(--switch-width) - var(--switch-node-size)))_                                                                                      | -  |
| switch-node-background-color    | _var(--white)_                                                                                                                                         | -  |
| switch-node-box-shadow          | _0 3px \* $hd 1px \* $hd 0 rgba(0, 0, 0, 0.05), <br/>0 2px \* $hd 2px \* $hd 0 rgba(0, 0, 0, 0.1),<br/> 0 3px \* $hd 3px \* $hd 0 rgba(0, 0, 0, 0.05)_ | -  |
| switch-checked-color            | _var(var(--primary-color)_                                                                                                                             | -  |
| switch-checked-background-color | _var(--switch-checked-color)_                                                                                                                          | -  |
| switch-loading-color            | _var(--switch-checked-color)_                                                                                                                          | -  |
| switch-disabled-opacity         | _var(--disabled-opacity)_                                                                                                                              | -  |



---
url: https://taroify.com/components/uploader/index.md
---

# Uploader 文件上传

### 介绍

用于将本地的图片或文件上传至服务器，并在上传过程中展示预览图。目前 Uploader 组件不包含将文件上传至服务器的接口逻辑，该步骤需要自行实现。

### 引入

```tsx
import { Uploader } from "taroify/core"
```

## 代码演示

### 基础用法

文件上传触发 `onUpload` 事件，获取到对应的 `file` 对象。

```tsx
function BasicUploader() {
  const [file, setFile] = useState<Uploader.File>()

  function onUpload() {
    chooseImage({
      count: 1,
      sizeType: ["original", "compressed"],
      sourceType: ["album", "camera"],
    }).then(({ tempFiles }) => {
      setFile({
        url: tempFiles[0].path,
        type: tempFiles[0].type,
        name: tempFiles[0].originalFileObj?.name,
      })
    })
  }

  return <Uploader value={file} onUpload={onUpload} onChange={setFile} />
}
```

### 文件预览

通过 `value` 属性可以绑定已经上传的文件列表，并展示文件列表的预览图。

```tsx
function PreviewUploader() {
  const [files, setFiles] = useState<Uploader.File[]>([
    {
      url: "https://img01.yzcdn.cn/vant/leaf.jpg",
    },
    {
      url: "https://img.yzcdn.cn/vant/tree.jpg",
    },
  ])

  function onUpload() {
    chooseImage({
      count: 1,
      sizeType: ["original", "compressed"],
      sourceType: ["album", "camera"],
    }).then(({ tempFiles }) => {
      setFiles([
        ...files,
        ...tempFiles.map(({ path, type, originalFileObj }) => ({
          type,
          url: path,
          name: originalFileObj?.name,
        })),
      ])
    })
  }

  return <Uploader value={files} multiple onUpload={onUpload} onChange={setFiles} />
}
```

### 上传状态

通过 `status` 属性可以标识上传状态，`uploading` 表示上传中，`failed` 表示上传失败，`completed` 表示上传完成。

```tsx
function UploaderWithStatus() {
  const [files, setFiles] = useState<Uploader.File[]>([
    {
      url: "https://img01.yzcdn.cn/vant/leaf.jpg",
      status: "uploading",
      message: "上传中...",
    },
    {
      url: "https://img01.yzcdn.cn/vant/tree.jpg",
      status: "failed",
      message: "上传失败",
    },
  ])

  function onUpload() {
    chooseImage({
      count: 1,
      sizeType: ["original", "compressed"],
      sourceType: ["album", "camera"],
    }).then(({ tempFiles }) => {
      setFiles([
        ...files,
        ...tempFiles.map(({ path, type, originalFileObj }) => ({
          type,
          url: path,
          name: originalFileObj?.name,
        })),
      ])
    })
  }

  return <Uploader value={files} multiple onUpload={onUpload} onChange={setFiles} />
}
```

### 限制上传数量

通过 `maxFiles` 属性可以限制上传文件的数量，上传数量达到限制后，会自动隐藏上传区域。

```tsx
function MaxFilesUploader() {
  const [files, setFiles] = useState<Uploader.File[]>([])

  function onUpload() {
    chooseImage({
      count: 1,
      sizeType: ["original", "compressed"],
      sourceType: ["album", "camera"],
    }).then(({ tempFiles }) => {
      setFiles([
        ...files,
        ...tempFiles.map(({ path, type, originalFileObj }) => ({
          type,
          url: path,
          name: originalFileObj?.name,
        })),
      ])
    })
  }

  return <Uploader value={files} multiple maxFiles={2} onUpload={onUpload} onChange={setFiles} />
}
```

### 自定义上传样式

通过children可以自定义上传区域的样式。

```tsx
function CustomUploader() {
  const [files, setFiles] = useState<Uploader.File[]>([])
  function onUpload() {
    chooseImage({
      count: 1,
      sizeType: ["original", "compressed"],
      sourceType: ["album", "camera"],
    }).then(({ tempFiles }) => {
      setFiles([
        ...files,
        ...tempFiles.map(({ path, type, originalFileObj }) => ({
          type,
          url: path,
          name: originalFileObj?.name,
        })),
      ])
    })
  }
  return (
    <Uploader multiple value={files} onChange={setFiles} onUpload={onUpload}>
      <Button icon={<Plus />} color="primary">
        上传文件
      </Button>
    </Uploader>
  )
}
```

### 自定义上传列表项

通过自定义 `itemrender` 控制每个上传区块

```tsx
function CustomPreviewUploader() {
  const [files, setFiles] = useState<Uploader.File[]>([
    {
      url: "https://img01.yzcdn.cn/vant/leaf.jpg",
    },
  ])

  function onUpload() {
    chooseImage({
      sizeType: ["original", "compressed"],
      sourceType: ["album", "camera"],
    }).then(({ tempFiles }) => {
      setFiles([
        ...files,
        ...tempFiles.map(({ path, type, originalFileObj }) => ({
          type,
          url: path,
          name: originalFileObj?.name,
        })),
      ])
    })
  }

  const itemRender = ({ file }: { file: Uploader.File }) => {
    return (
      <Uploader.Image
        key={file.url}
        url={file.url}
        name={file.name}
        type={file.type}
        onRemove={() => setFiles(files.filter((item) => item !== file))}
      >
        <View className="preview-cover taroify-ellipsis">图片名称</View>
      </Uploader.Image>
    )
  }

  return (
    <Uploader
      value={files}
      multiple
      onUpload={onUpload}
      onChange={setFiles}
      itemRender={itemRender}
    />
  )
}
```

```scss
.preview-cover {
  position: absolute;
  bottom: 0;
  box-sizing: border-box;
  width: 100%;
  padding: 4px * 2;
  color: #fff;
  font-size: 12px * 2;
  text-align: center;
  background: rgba(0, 0, 0, 0.3);
}
```

### 禁用文件上传

通过 `disabled` 属性禁用文件上传。

```tsx
<Uploader disabled />
```

## API

### Props

| 参数           | 说明                   | 类型                 | 默认值     |
| ------------ | -------------------- | ------------------ | ------- |
| defaultValue | 默认已上传的文件列表           | _UploadFile\[]_    | -       |
| value        | 已上传的文件列表             | _UploadFile\[]_    | -       |
| name         | 标识符，可以在回调函数的第二项参数中获取 | _number \| string_ | -       |
| multiple     | 是否开启图片多选，部分安卓机型不支持   | _boolean_          | `false` |
| disabled     | 是否禁用文件上传             | _boolean_          | `false` |
| readonly     | 是否将上传区域设置为只读状态       | _boolean_          | `false` |
| removable    | 是否展示删除按钮             | _boolean_          | `true`  |
| maxFiles     | 文件上传数量限制             | _number \| string_ | -       |

### Events

| 事件名      | 说明           | 回调参数                                |
| -------- | ------------ | ----------------------------------- |
| onUpload | 点击上传区域时触发    | _event: ITouchEvent_                |
| onChange | 已上传图片列表改变后触发 | _file: UploadFile \| UploadFile\[]_ |

### UploadFile

| 参数        | 说明                                 | 类型        |
| --------- | ---------------------------------- | --------- |
| url       | 下载地址                               | _string_  |
| type      | 文件类型(包含image时显示图标,其他显示)            | _string_  |
| name      | 文件名称                               | _string_  |
| removable | 是否可删除                              | _boolean_ |
| status    | 上传状态（uploading\|failed\|completed） | _string_  |
| message   | uploading\|failed 状态时文字提示          | _string_  |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                        | 默认值                                       | 描述 |
| ----------------------------------------- | ----------------------------------------- | -- |
| --uploader-size                           | _80px \* $hd_                             | -  |
| --uploader-disabled-opacity               | _var(--disabled-opacity)_                 | -  |
| --uploader-upload-size                    | _var(--uploader-size)_                    | -  |
| --uploader-upload-width                   | _var(--uploader-upload-size)_             | -  |
| --uploader-upload-height                  | _var(--uploader-upload-size)_             | -  |
| --uploader-upload-margin                  | _0 var(--padding-xs) var(--padding-xs) 0_ | -  |
| --uploader-upload-background-color        | _var(--gray-1)_                           | -  |
| --uploader-upload-active-background-color | _var(--active-color)_                     | -  |
| --uploader-upload-icon-color              | _var(--gray-4)_                           | -  |
| --uploader-upload-icon-font-size          | _24px \* $hd_                             | -  |
| --uploader-upload-text-margin-top         | _var(--padding-xs)_                       | -  |
| --uploader-upload-text-color              | _var(--gray-6)_                           | -  |
| --uploader-upload-text-font-size          | _var(--font-size-sm)_                     | -  |
| --uploader-preview-margin                 | _0 var(--padding-xs) var(--padding-xs) 0_ | -  |
| --uploader-preview-image-size             | _var(--uploader-size)_                    | -  |
| --uploader-preview-image-width            | _var(--uploader-preview-image-size)_      | -  |
| --uploader-preview-image-height           | _var(--uploader-preview-image-size)_      | -  |
| --uploader-remove-size                    | _14px \* $hd_                             | -  |
| --uploader-remove-width                   | _var(--uploader-remove-size)_             | -  |
| --uploader-remove-height                  | _var(--uploader-remove-size)_             | -  |
| --uploader-remove-background-color        | _rgba(0, 0, 0, 0.7)_                      | -  |
| --uploader-remove-border-radius           | _0 0 0 12px \* $hd_                       | -  |
| --uploader-remove-icon-font-size          | _16px \* $hd_                             | -  |
| --uploader-remove-icon-color              | _var(--white)_                            | -  |
| --uploader-file-size                      | _var(--uploader-size)_                    | -  |
| --uploader-file-width                     | _var(--uploader-file-size)_               | -  |
| --uploader-file-height                    | _var(--uploader-file-size)_               | -  |
| --uploader-file-background-color          | _var(--background-color)_                 | -  |
| --uploader-file-icon-font-size            | _20px \* $hd_                             | -  |
| --uploader-file-icon-color                | _var(--gray-7)_                           | -  |
| --uploader-file-name-padding              | _0 var(--padding-base)_                   | -  |
| --uploader-file-name-margin-top           | _var(--padding-xs)_                       | -  |
| --uploader-file-name-font-size            | _var(--font-size-sm)_                     | -  |
| --uploader-file-name-color                | _var(--gray-7)_                           | -  |
| --uploader-mask-color                     | _var(--white)_                            | -  |
| --uploader-mask-background-color          | _rgba(50, 50, 51, 0.88)_                  | -  |
| --uploader-mask-icon-size                 | _22px \* $hd_                             | -  |
| --uploader-mask-message-margin-top        | _6px \* $hd_                              | -  |
| --uploader-mask-message-padding           | _0 var(--padding-base)_                   | -  |
| --uploader-mask-message-font-size         | _var(--font-size-sm)_                     | -  |
| --uploader-mask-message-line-height       | _var(--line-height-xs)_                   | -  |
| --uploader-loading-icon-size              | _22px \* $hd_                             | -  |
| --uploader-loading-icon-width             | _var(--uploader-loading-icon-size)_       | -  |
| --uploader-loading-icon-height            | _var(--uploader-loading-icon-size)_       | -  |
| --uploader-loading-icon-color             | _var(--white)_                            | -  |



---
url: https://taroify.com/components/action-sheet/index.md
---

# ActionSheet 动作面板

### 介绍

底部弹起的模态面板，包含与当前情境相关的多个选项。

### 引入

```tsx
import { ActionSheet } from "@taroify/core"
```

## 代码演示

### 基础用法

```tsx
function BasicActionSheet() {
  const [open, setOpen] = useState(false)
  const actions = useMemo(
    () => [
      { name: "选项一", value: "1" },
      { name: "选项二", value: "2" },
      { name: "选项三", value: "3" },
    ],
    [],
  )
  return (
    <>
      <Cell clickable isLink title="基础用法" onClick={() => setOpen(true)} />
      <ActionSheet
        actions={actions}
        open={open}
        onSelect={() => setOpen(false)}
        onClose={setOpen}
      />
    </>
  )
}
```

### 展示取消按钮

添加`cancelText`后，会在底部展示取消按钮，点击后关闭当前面板并触发 `onCancel` 事件。

```tsx
function ActionSheetWithCancel() {
  const [open, setOpen] = useState(false)
  const actions = useMemo(
    () => [
      { name: "选项一", value: "1" },
      { name: "选项二", value: "2" },
      { name: "选项三", value: "3" },
    ],
    [],
  )
  return (
    <>
      <Cell clickable isLink title="展示取消按钮" onClick={() => setOpen(true)} />
      <ActionSheet
        cancelText="取消"
        actions={actions}
        open={open}
        onSelect={() => setOpen(false)}
        onCancel={() => setOpen(false)}
        onClose={setOpen}
      />
    </>
  )
}
```

### 展示描述信息

通过 `description` 和 `subname` 添加描述信息

```tsx
function ActionSheetWithDescription() {
  const [open, setOpen] = useState(false)
  const actions = useMemo(
    () => [
      { name: "选项一", value: "1", subname: "这是一段描述信息" },
      { name: "选项二", value: "2" },
      { name: "选项三", value: "3" },
    ],
    [],
  )
  return (
    <>
      <Cell clickable title="展示描述信息" isLink onClick={() => setOpen(true)} />
      <ActionSheet
        description="这是一段描述信息"
        cancelText="取消"
        actions={actions}
        open={open}
        onSelect={() => setOpen(false)}
        onCancel={() => setOpen(false)}
        onClose={setOpen}
      />
    </>
  )
}
```

### 选项状态

通过 `loading` 和 `disabled` 将选项设置为加载状态或禁用状态，通过 `style`，`className` 修改样式

```tsx
function ActionSheetWithStatuses() {
  const [open, setOpen] = useState(false)
  const actions = useMemo(
    () => [
      { name: "选项一", value: "1", style: { color: "#ee0a24" } },
      { name: "选项二", value: "2", disabled: true },
      { name: "选项三", value: "3", loading: true },
    ],
    [],
  )
  return (
    <>
      <Cell clickable title="选项状态" isLink onClick={() => setOpen(true)} />
      <ActionSheet
        actions={actions}
        cancelText="取消"
        open={open}
        onSelect={() => setOpen(false)}
        onCancel={() => setOpen(false)}
        onClose={setOpen}
      />
    </>
  )
}
```

### 手动控制 DOM

使用 `ActionSheet.Button` 组件后，会在底部展示取消按钮，点击后关闭当前面板并触发 `onCancel` 事件。<br>
使用`ActionSheet.Action`组件添加选项， 通过 `loading` 和 `disabled` 将选项设置为加载状态或禁用状态 <br>
通过 `ActionSheet.Header` 组件可以在菜单顶部显示描述信息，通过选项的 `ActionSheet.Action.children` 属性可以在 `Action` 文字的下侧展示描述信息。

```tsx
function ActionSheetWithStatuses() {
  const [open, setOpen] = useState(true)
  return (
    <ActionSheet open={open} onSelect={() => setOpen(false)} onClose={setOpen}>
      <ActionSheet.Action value="1" style={{ color: "#ee0a24" }} name="着色选项" />
      <ActionSheet.Action value="2" disabled name="禁止选项" />
      <ActionSheet.Action value="3" loading name="选项三" />
      <ActionSheet.Button onClick={() => setOpen(false)}>取消</ActionSheet.Button>
    </ActionSheet>
  )
}
```

## API

### ActionSheet Props

| 参数          | 说明                         | 类型                           | 默认值      |
| ----------- | -------------------------- | ---------------------------- | -------- |
| defaultOpen | 默认是否显示动作面板                 | _boolean_                    | `false`  |
| open        | 是否显示动作面板                   | _boolean_                    | `false`  |
| description | 选项上方的描述信息                  | _ReactNode_                  | -        |
| cancelText  | 取消按钮文字                     | _ReactNode_                  | -        |
| actions     | 面板选项列表                     | _ActionSheetActionObject\[]_ | -        |
| className   | 样式类名                       | _string_                     | -        |
| style       | 样式对象                       | _CSSProperties_              | -        |
| rounded     | 是否为圆角                      | _string_                     | -        |
| safeArea    | 安全区的位置，可选值为 `top` `bottom` | _string_                     | `bottom` |

### ActionSheetActionObject 数据结构

| 参数        | 说明      | 类型          |
| --------- | ------- | ----------- |
| name      | 标题      | _ReactNode_ |
| subname   | 二级标题    | _ReactNode_ |
| disabled  | 是否为禁用状态 | _boolean_   |
| loading   | 是否为加载状态 | _boolean_   |
| value     | 值       | _any_       |
| style     |         |             |
| className |         |             |

### ActionSheet.Backdrop Props

| 参数        | 说明        | 类型                 | 默认值    |
| --------- | --------- | ------------------ | ------ |
| className | 样式类名      | _string_           | -      |
| style     | 样式对象      | _CSSProperties_    | -      |
| duration  | 动画时长，单位毫秒 | _number \| string_ | `300`  |
| closeable | 点击是否可以关闭  | _boolean_          | `true` |

### ActionSheet.Header Props

| 参数        | 说明   | 类型              | 默认值 |
| --------- | ---- | --------------- | --- |
| className | 样式类名 | _string_        | -   |
| style     | 样式对象 | _CSSProperties_ | -   |
| title     | 标题   | _string_        | -   |
| children  | 描述信息 | _string_        | -   |

### ActionSheet.Action Props

| 参数        | 说明      | 类型              | 默认值 |
| --------- | ------- | --------------- | --- |
| className | 样式类名    | _string_        | -   |
| style     | 样式对象    | _CSSProperties_ | -   |
| name      | 标题      | _string_        | -   |
| value     | 选项值     | _string_        | -   |
| disabled  | 是否为禁用状态 | _boolean_       | -   |
| loading   | 是否为加载状态 | _boolean_       | -   |
| children  | 描述信息    | _string_        | -   |

### ActionSheet.Button Props

| 参数        | 说明                 | 类型              | 默认值      |
| --------- | ------------------ | --------------- | -------- |
| className | 按钮类名               | _string_        | -        |
| style     | 按钮样式               | _CSSProperties_ | -        |
| type      | 按钮类型，可选值为 `cancel` | _string_        | `button` |
| children  | 按钮内容               | _string_        | -        |

### ActionSheet Events

| 事件名      | 说明                   | 回调参数                             |
| -------- | -------------------- | -------------------------------- |
| onSelect | 点击选项时触发，禁用或加载状态下不会触发 | _event: ActionSheet.ActionEvent_ |
| onCancel | 点击取消按钮时触发            | -                                |
| onClose  | 关闭面板时触发              | -                                |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                        | 默认值                     | 描述 |
| ----------------------------------------- | ----------------------- | -- |
| --action-sheet-description-padding-bottom | _var(--padding-md)_     | -  |
| --action-sheet-subname-margin-top         | _var(--padding-xs)_     | -  |
| --action-sheet-subname-color              | _var(--gray-6)_         | -  |
| --action-sheet-subname-font-size          | _var(--font-size-sm)_   | -  |
| --action-sheet-subname-line-height        | _var(--line-height-sm)_ | -  |



---
url: https://taroify.com/components/dialog/index.md
---

# Dialog 弹出框

### 介绍

弹出模态框，常用于消息提示、消息确认，或在当前页面内完成特定的交互操作，支持函数调用和组件调用两种方式。

### 函数调用

版本 >= `v0.6.0-alpha.0`可以直接调用。低版本需要手动在页面（page）里挂载一个 Dialog 组件并指定 id 为 `dialog`。

```tsx
function ImperativeDialog() {
  return (
    <>
      {/* <Dialog id="dialog" /> */}
      <Cell
        title="提示弹窗"
        clickable
        bordered
        isLink
        onClick={() =>
          Dialog.alert({ title: "标题", message: "代码是写出来给人看的，附带能在机器上运行" })
        }
      />
    </>
  )
}
```

### 组件调用

通过组件组合的方式调用 Dialog。

```tsx
<Dialog
  open
  title="标题"
  message="代码是写出来给人看的，附带能在机器上运行"
  messageAlign="left"
  confirm="ok"
  cancel="cancel"
  onConfirm={() => console.log("confirm")}
  onCancel={() => console.log("cancel")}
/>
```

```tsx
function TextDialog() {
  const [open, setOpen] = useState(false)
  return (
    <>
      <Cell title="提示弹窗" clickable bordered isLink onClick={() => setOpen(true)} />
      <Dialog open={open} onClose={setOpen}>
        <Dialog.Header>标题</Dialog.Header>
        <Dialog.Content>代码是写出来给人看的，附带能在机器上运行</Dialog.Content>
        <Dialog.Actions>
          <Button onClick={() => setOpen(false)}>取消</Button>
          <Button onClick={() => setOpen(false)}>确认</Button>
        </Dialog.Actions>
      </Dialog>
    </>
  )
}
```

## 代码演示

### 消息提示

用于提示一些消息，只包含一个确认按钮。

```ts
Dialog.alert("生命远不止连轴转和忙到极限，人类的体验远比这辽阔、丰富得多。")
```

```tsx
function BasicDialog() {
  const [open, setOpen] = useState(false)
  return (
    <>
      <Cell title="提示弹窗" clickable bordered isLink onClick={() => setOpen(true)} />
      <Dialog open={open} onClose={setOpen}>
        <Dialog.Header>标题</Dialog.Header>
        <Dialog.Content>代码是写出来给人看的，附带能在机器上运行</Dialog.Content>
        <Dialog.Actions>
          <Button onClick={() => setOpen(false)}>确认</Button>
        </Dialog.Actions>
      </Dialog>
    </>
  )
}
```

### 消息确认

用于确认消息，包含取消和确认按钮。

```ts
Dialog.confirm({ title: "标题", message: "代码是写出来给人看的，附带能在机器上运行" })
```

```tsx
function ConfirmDialog() {
  const [open, setOpen] = useState(false)
  return (
    <>
      <Cell title="确认弹窗" clickable bordered isLink onClick={() => setOpen(true)} />
      <Dialog open={open} onClose={setOpen}>
        <Dialog.Header>标题</Dialog.Header>
        <Dialog.Content>代码是写出来给人看的，附带能在机器上运行</Dialog.Content>
        <Dialog.Actions>
          <Button onClick={() => setOpen(false)}>取消</Button>
          <Button onClick={() => setOpen(false)}>确认</Button>
        </Dialog.Actions>
      </Dialog>
    </>
  )
}
```

### 圆角按钮风格

设置 `theme` 为 `rounded` 可以展示圆角按钮风格的弹窗

```ts
Dialog.confirm({
  theme: "rounded",
  title: "标题",
  message: "代码是写出来给人看的，附带能在机器上运行",
})
```

将 `actions.variant ` 选项设置为 `rounded` 可以展示圆角按钮风格的弹窗。

```tsx
function RoundedDialog() {
  const [open, setOpen] = useState(false)
  return (
    <>
      <Cell title="提示弹窗" clickable bordered isLink onClick={() => setOpen(true)} />
      <Dialog open={open} onClose={setOpen}>
        <Dialog.Header>标题</Dialog.Header>
        <Dialog.Content>代码是写出来给人看的，附带能在机器上运行</Dialog.Content>
        <Dialog.Actions variant="rounded">
          <Button onClick={() => setOpen(false)}>取消</Button>
          <Button onClick={() => setOpen(false)}>确认</Button>
        </Dialog.Actions>
      </Dialog>
    </>
  )
}
```

### 异步关闭

```tsx
function AsyncCloseDialog() {
  return (
    <>
      <Cell
        title="异步关闭"
        clickable
        bordered
        isLink
        onClick={() =>
          Dialog.confirm({
            title: "标题",
            message: "如果解决方法是丑陋的，那就肯定还有更好的解决方法，只是还没有发现而已。",
            async onBeforeClose(action) {
              return new Promise((resolve) => {
                setTimeout(() => {
                  // action !== 'confirm'  拦截取消操作
                  resolve(action === "confirm")
                }, 1000)
              })
            },
            onCancel() {
              console.log("cancel")
            },
            onConfirm() {
              console.log("confirm")
            },
          })
        }
      />
    </>
  )
}
```

## API

### Dialog Props

| 参数           | 说明                         | 类型                                             | 默认值      |
| ------------ | -------------------------- | ---------------------------------------------- | -------- |
| defaultOpen  | 默认是否显示弹窗                   | _boolean_                                      | -        |
| open         | 是否显示弹窗                     | _boolean_                                      | -        |
| children     | 组件内容                       | _ReactNode_                                    | -        |
| backdrop     | 遮罩层相关配置                    | _boolean \| Omit\<PopupBackdropProps, "open">_ | -        |
| title        | 标题                         | _ReactNode_                                    | -        |
| message      | 文本内容，支持通过 `\n` 换行          | _ReactNode_                                    | -        |
| messageAlign | 内容对齐方式，可选值为 `left` `right` | _string_                                       | `center` |
| confirm      | 确认按钮                       | _string \| ButtonProps_                        | -        |
| cancel       | 取消按钮                       | _string \| ButtonProps_                        | -        |

### Dialog Event

| 事件名       | 说明      | 回调参数 |
| --------- | ------- | ---- |
| onConfirm | 点击确认时触发 | -    |
| onCancel  | 点击取消时触发 | -    |

### Dialog.Header Props

| 参数       | 说明   | 类型          | 默认值 |
| -------- | ---- | ----------- | --- |
| children | 标题内容 | _ReactNode_ | -   |

### Dialog.Content Props

| 参数       | 说明                         | 类型          | 默认值      |
| -------- | -------------------------- | ----------- | -------- |
| align    | 文本对齐方式，可选值为 `left` `right` | _string_    | `center` |
| children | 文本内容                       | _ReactNode_ | -        |

### Dialog.Actions Props

| 参数       | 说明                  | 类型          | 默认值       |
| -------- | ------------------- | ----------- | --------- |
| variant  | 样式风格，可选值为 `rounded` | _string_    | `default` |
| children | 按钮内容                | _ReactNode_ | -         |

### Dialog Options

| 参数           | 说明                         | 类型                                             | 默认值      |
| ------------ | -------------------------- | ---------------------------------------------- | -------- |
| selector     | 自定义节点选择器                   | _string_                                       | `toast`  |
| className    | 自定义类名                      | _string_                                       | -        |
| style        | 自定义样式                      | _CSSProperties_                                | -        |
| title        | 标题                         | _ReactNode_                                    | -        |
| message      | 文本内容，支持通过 `\n` 换行          | _ReactNode_                                    | -        |
| messageAlign | 内容对齐方式，可选值为 `left` `right` | _string_                                       | `center` |
| backdrop     | 遮罩层相关配置                    | _boolean \| Omit\<PopupBackdropProps, "open">_ | -        |
| confirm      | 确认按钮                       | _string \| ButtonProps_                        | -        |
| cancel       | 取消按钮                       | _string \| ButtonProps_                        | -        |
| onConfirm    | 确认事件                       | _() => void_                                   | -        |
| onCancel     | 取消事件                       | _() => void_                                   | -        |

### Dialog Methods

| 方法名            | 参数                   | 返回值 | 介绍       |
| -------------- | -------------------- | --- | -------- |
| Dialog.open    | _options \| message_ | -   | 展示弹窗     |
| Dialog.alert   | _options \| message_ | -   | 展示消息提示弹窗 |
| Dialog.confirm | _options \| message_ | -   | 展示消息确认弹窗 |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                               | 默认值                                                     | 描述 |
| ------------------------------------------------ | ------------------------------------------------------- | -- |
| --dialog-width                                   | _320px \* $hd_                                          | -  |
| --dialog-small-screen-width                      | _90%_                                                   | -  |
| --dialog-font-size                               | _var(--font-size-lg)_                                   | -  |
| --dialog-transition                              | _var(--animation-duration-base)_                        | -  |
| --dialog-border-radius                           | _16px \* $hd_                                           | -  |
| --dialog-background-color                        | _var(--white)_                                          | -  |
| --dialog-header-font-weight                      | _var(--font-weight-bold)_                               | -  |
| --dialog-header-line-height                      | _24px \* $hd_                                           | -  |
| --dialog-header-padding-top                      | _26px \* $hd_                                           | -  |
| --dialog-header-isolated-padding                 | _var(--padding-lg) 0_                                   | -  |
| --dialog-message-padding                         | _26px \* $hd var(--padding-lg)_                         | -  |
| --dialog-message-font-size                       | _var(--font-size-md)_                                   | -  |
| --dialog-message-line-height                     | _var(--line-height-md)_                                 | -  |
| --dialog-message-font-weight                     | _var(--dialog-message-font-weight)_                     | -  |
| --dialog-message-max-height                      | _60vh_                                                  | -  |
| --dialog-has-title-message-color                 | _var(--gray-7)_                                         | -  |
| --dialog-has-title-message-padding-top           | _var(--padding-xs)_                                     | -  |
| --dialog-has-title-message-font-weight           | _var(--dialog-has-title-message-font-weight)_           | -  |
| --dialog-button-height                           | _48px \* $hd_                                           | -  |
| --dialog-confirm-button-color                    | _var(--primary-color)_                                  | -  |
| --dialog-footer-rounded-padding                  | _var(--padding-xs) var(--padding-lg) var(--padding-md)_ | -  |
| --dialog-rounded-button-active-color             | _var(--white)_                                          | -  |
| --dialog-rounded-button-font-size                | _var(--font-size-md)_                                   | -  |
| --dialog-rounded-button-height                   | _36px \* $hd_                                           | -  |
| --dialog-rounded-button-border-radius            | _var(--border-radius-max)_                              | -  |
| --dialog-rounded-confirm-button-background-color | _var(--gradient-red)_                                   | -  |
| --dialog-rounded-cancel-button-background-color  | _var(--gradient-orange)_                                | -  |



---
url: https://taroify.com/components/dropdown-menu/index.md
---

# DropdownMenu 下拉菜单

### 介绍

向下弹出的菜单列表。

### 引入

```tsx
import { DropdownMenu } from "@taroify/core"
```

## 代码演示

### 基础用法

```tsx
import { DropdownMenu } from "@taroify/core"

function BasicDropdownMenu() {
  const [options] = useState([
    { title: "默认排序", value: 0 },
    { title: "好评排序", value: 1 },
    { title: "销量排序", value: 2 },
  ])
  return (
    <DropdownMenu>
      <DropdownMenu.Item>
        <DropdownMenu.Option value={0}>全部商品</DropdownMenu.Option>
        <DropdownMenu.Option value={1}>新款商品</DropdownMenu.Option>
        <DropdownMenu.Option value={2}>活动商品</DropdownMenu.Option>
      </DropdownMenu.Item>
      <DropdownMenu.Item options={options} />
    </DropdownMenu>
  )
}
```

### 自定义菜单内容

可以通过 `DropdownMenu.Item` 组件自定义内容。

```tsx
import { DropdownMenu } from "@taroify/core"
import { Key } from "react"

function DropdownMenuWithCustomContent() {
  const [value, setValue] = useState<Key | false>()
  const [option1, setOption1] = useState(0)
  const [switch1, setSwitch1] = useState(true)
  const [switch2, setSwitch2] = useState(false)
  const [options] = useState([
    {
      title: (
        <View>
          默认<View>排序</View>
        </View>
      ),
      value: 0,
    },
    { title: "好评排序", value: 1 },
    { title: "销量排序", value: 2 },
  ])
  return (
    <DropdownMenu value={value} onChange={setValue}>
      <DropdownMenu.Item
        value={option1}
        onChange={setOption1}
        options={options}
      ></DropdownMenu.Item>
      <DropdownMenu.Item title="筛选">
        <Cell title="包邮" align="center">
          <Switch size="24" checked={switch1} onChange={setSwitch1} />
        </Cell>
        <Cell title="团购" align="center">
          <Switch size="24" checked={switch2} onChange={setSwitch2} />
        </Cell>
        <View style="padding: 5px 16px;">
          <Button color="danger" block shape="round" onClick={() => setValue(false)}>
            确认
          </Button>
        </View>
      </DropdownMenu.Item>
    </DropdownMenu>
  )
}
```

### 自定义选中态颜色

通过 `css` 可以自定义菜单标题和选项的选中态颜色。

```tsx
import { DropdownMenu } from "@taroify/core"

function DropdownMenuWithCustomColor() {
  return (
    <DropdownMenu className="custom-color">
      <DropdownMenu.Item>
        <DropdownMenu.Option value={0}>全部商品</DropdownMenu.Option>
        <DropdownMenu.Option value={1}>新款商品</DropdownMenu.Option>
        <DropdownMenu.Option value={2}>活动商品</DropdownMenu.Option>
      </DropdownMenu.Item>
      <DropdownMenu.Item>
        <DropdownMenu.Option value={0}>默认排序</DropdownMenu.Option>
        <DropdownMenu.Option value={1}>好评排序</DropdownMenu.Option>
        <DropdownMenu.Option value={2}>销量排序</DropdownMenu.Option>
      </DropdownMenu.Item>
    </DropdownMenu>
  )
}
```

```scss
.custom-color {
  --dropdown-menu-title-active-color: #1989fa;
  --dropdown-menu-option-active-color: #1989fa;
}
```

### 向上展开

将 `direction` 属性值设置为 `up`，菜单即可向上展开。

```tsx
import { DropdownMenu } from "@taroify/core"

function UpDropdownMenu() {
  return (
    <DropdownMenu direction="up">
      <DropdownMenu.Item>
        <DropdownMenu.Option value={0}>全部商品</DropdownMenu.Option>
        <DropdownMenu.Option value={1}>新款商品</DropdownMenu.Option>
        <DropdownMenu.Option value={2}>活动商品</DropdownMenu.Option>
      </DropdownMenu.Item>
      <DropdownMenu.Item>
        <DropdownMenu.Option value={0}>默认排序</DropdownMenu.Option>
        <DropdownMenu.Option value={1}>好评排序</DropdownMenu.Option>
        <DropdownMenu.Option value={2}>销量排序</DropdownMenu.Option>
      </DropdownMenu.Item>
    </DropdownMenu>
  )
}
```

### 禁用菜单

```tsx
import { DropdownMenu } from "@taroify/core"

function DisabledDropdownMenu() {
  return (
    <DropdownMenu>
      <DropdownMenu.Item disabled>
        <DropdownMenu.Option value={0}>全部商品</DropdownMenu.Option>
        <DropdownMenu.Option value={1}>新款商品</DropdownMenu.Option>
        <DropdownMenu.Option value={2}>活动商品</DropdownMenu.Option>
      </DropdownMenu.Item>
      <DropdownMenu.Item disabled>
        <DropdownMenu.Option value={0}>默认排序</DropdownMenu.Option>
        <DropdownMenu.Option value={1}>好评排序</DropdownMenu.Option>
        <DropdownMenu.Option value={2}>销量排序</DropdownMenu.Option>
      </DropdownMenu.Item>
    </DropdownMenu>
  )
}
```

### 阻止滑动穿透

在 h5 上设置 lock 即可阻止滑动穿透 \
若要在微信小程序上支持，还需下面两项设置 \
1.设置滑动容器高度(--dropdown-menu-item-content-max-height)，不设置超长时无法滑动 \
2.当下拉展开时，禁用外层滑动(通过 PageMeta，或者你包裹的滑动容器)，不设置无法阻止下拉反方向的滑动

```tsx
function BasicDropdownMenu() {
  const [options] = useState(
    [
      { title: "默认排序", value: 0 },
      { title: "好评排序", value: 1 },
      { title: "销量排序", value: 2 },
    ].concat(Array.from({ length: 20 }, (_, i) => ({ title: "选项" + i, value: 3 + i }))),
  )
  const [opened, setOpened] = useState(false)
  const getScrollHeight = useCallback((len) => {
    return len < 5 ? len * 46 : 5 * 46
  }, [])
  return (
    <>
      <PageMeta pageStyle={opened ? "overflow: hidden;" : ""} />
      <DropdownMenu>
        {/* @ts-ignore */}
        <DropdownMenu.Item
          style={{ "--dropdown-menu-item-content-max-height": getScrollHeight(23) + "px" }}
          options={options}
          lock
          onOpen={() => setOpened(true)}
          onClose={() => setOpened(false)}
        />
        {/* @ts-ignore */}
        <DropdownMenu.Item
          style={{ "--dropdown-menu-item-content-max-height": getScrollHeight(4) + "px" }}
          lock
          onOpen={() => setOpened(true)}
          onClose={() => setOpened(false)}
        >
          <DropdownMenu.Option value={0}>全部商品</DropdownMenu.Option>
          <DropdownMenu.Option value={1}>新款商品</DropdownMenu.Option>
          <DropdownMenu.Option value={2}>活动商品</DropdownMenu.Option>
          <DropdownMenu.Option value={3}>活动商品2</DropdownMenu.Option>
        </DropdownMenu.Item>
      </DropdownMenu>
    </>
  )
}
```

## API

### DropdownMenu Props

| 参数           | 说明                        | 类型       | 默认值     |
| ------------ | ------------------------- | -------- | ------- |
| direction    | 菜单展开方向，可选值为`up`           | _string_ | `down`  |
| backdropType | 背景板位置，可选值 `inner` `outer` | _string_ | `inner` |

### DropdownMenu.Item Props

| 参数           | 说明             | 类型                            | 默认值     |
| ------------ | -------------- | ----------------------------- | ------- |
| defaultValue | 默认选中项对应的 value | _any_                         | -       |
| value        | 当前选中项对应的 value | _any_                         | -       |
| title        | 菜单项标题          | _string_                      | 当前选中项文字 |
| disabled     | 是否禁用菜单         | _boolean_                     | `false` |
| lock         | 是否锁定背景滚动       | _boolean_                     | `false` |
| options      | 选项数组           | 同下方 DropdownMenu.Option Props | -       |

### DropdownMenu.Item Events

| 事件名      | 说明                 | 回调参数         |
| -------- | ------------------ | ------------ |
| onChange | 点击选项导致 value 变化时触发 | _value: any_ |
| onOpen   | 打开菜单栏时触发           | -            |
| onClose  | 关闭菜单栏时触发           | -            |
| onOpened | 打开菜单栏且动画结束后触发      | -            |
| onClosed | 关闭菜单栏且动画结束后触发      | -            |

### DropdownMenu.Option Props

| 键名    | 说明                                                     | 类型          |
| ----- | ------------------------------------------------------ | ----------- |
| value | 标识符                                                    | _any_       |
| icon  | 左侧[图标](/components/icon.md)或[图片](/components/image.md) | _ReactNode_ |
| title | 展示 DropdownMenu 选中的 title 内容                           | _ReactNode_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                              | 默认值                                                  | 描述 |
| ----------------------------------------------- | ---------------------------------------------------- | -- |
| --dropdown-menu-height                          | _48px \* $hd_                                        | -  |
| --dropdown-menu-background-color                | _var(--white)_                                       | -  |
| --dropdown-menu-z-index                         | _11_                                                 | -  |
| --dropdown-menu-box-shadow                      | _0 2px \* $hd 12px \* $hd rgba(100, 101, 102, 0.12)_ | -  |
| --dropdown-menu-title-font-size                 | _15px \* $hd_                                        | -  |
| --dropdown-menu-title-color                     | _var(--text-color)_                                  | -  |
| --dropdown-menu-title-padding                   | _0 var(--padding-xs)_                                | -  |
| --dropdown-menu-title-line-height               | _var(--line-height-lg)_                              | -  |
| --dropdown-menu-title-active-opacity            | _var(--active-opacity)_                              | -  |
| --dropdown-menu-title-active-color              | _var(--danger-color)_                                | -  |
| --dropdown-menu-title-disabled-color            | _var(--gray-6)_                                      | -  |
| --dropdown-menu-item-z-index                    | _calc(var(--dropdown-menu-z-index) - 1)_             | -  |
| --dropdown-menu-item-content-max-height         | _80%_                                                | -  |
| --dropdown-menu-item-content-animation-duration | _var(--animation-duration-fast)_                     | -  |
| --dropdown-menu-option-active-color             | _var(--danger-color)_                                | -  |



---
url: https://taroify.com/components/floating-panel/index.md
---

# FloatingPanel 浮动面板

### 介绍

浮动在页面底部的面板，可以上下拖动来浏览内容，常用于提供额外的功能或信息。

请升级 `taroify` 到 >= `v0.1.0-alpha.3` 版本来使用该组件。

### 引入

```tsx
import { FloatingPanel } from "@taroify/core"
```

## 代码演示

### 基础用法

FloatingPanel 的默认高度为 `100px`，用户可以拖动来展开面板，使高度达到 `60%` 的屏幕高度。

```tsx
<FloatingPanel>
  <Cell.Group>
    <Cell>1</Cell>
    <Cell>2</Cell>
    <Cell>3</Cell>
    <Cell>4</Cell>
    <Cell>5</Cell>
    <Cell>6</Cell>
    <Cell>7</Cell>
    <Cell>8</Cell>
    <Cell>9</Cell>
    <Cell>10</Cell>
    <Cell>11</Cell>
    <Cell>12</Cell>
    <Cell>13</Cell>
  </Cell.Group>
</FloatingPanel>
```

### 自定义锚点

你可以通过 `anchors` 属性来设置 FloatingPanel 的锚点位置，并通过 `height` 来控制当前面板的显示高度。
比如，使面板的高度在 `100px`、40% 屏幕高度和 70% 屏幕高度三个位置停靠：

```tsx
function CustomAnchors() {
  const windowHeight = useMemo(() => getWindowInfo().windowHeight, [])

  const anchors = useMemo(
    () => [200, Math.round(0.4 * windowHeight), Math.round(0.7 * windowHeight)],
    [windowHeight],
  )

  return (
    <FloatingPanel anchors={anchors} height={anchors[0]}>
      <Cell.Group>
        <Cell>1</Cell>
        <Cell>2</Cell>
        <Cell>3</Cell>
        <Cell>4</Cell>
        <Cell>5</Cell>
        <Cell>6</Cell>
        <Cell>7</Cell>
        <Cell>8</Cell>
        <Cell>9</Cell>
        <Cell>10</Cell>
        <Cell>11</Cell>
        <Cell>12</Cell>
        <Cell>13</Cell>
      </Cell.Group>
    </FloatingPanel>
  )
}
```

### 仅头部拖拽

默认情况下，FloatingPanel 的头部区域和内容区域都可以被拖拽，你可以通过 `contentDraggable` 属性来禁用内容区域的拖拽。

```tsx
function HeadDragOnly() {
  return (
    <FloatingPanel contentDraggable={false}>
      <Cell.Group>
        <Cell>1</Cell>
        <Cell>2</Cell>
        <Cell>3</Cell>
        <Cell>4</Cell>
        <Cell>5</Cell>
        <Cell>6</Cell>
        <Cell>7</Cell>
        <Cell>8</Cell>
        <Cell>9</Cell>
        <Cell>10</Cell>
        <Cell>11</Cell>
        <Cell>12</Cell>
        <Cell>13</Cell>
      </Cell.Group>
    </FloatingPanel>
  )
}
```

### 监听拖拽

通过 `onDragStart`、`onDragging` 和 `onDragEnd` 可以监听面板的拖拽过程。事件参数中的 `height` 表示当前面板高度，其中 `onDragEnd` 返回吸附到锚点后的最终高度。

```tsx
<FloatingPanel
  onDragStart={({ height }) => {
    console.log("drag start", height)
  }}
  onDragging={({ height }) => {
    console.log("dragging", height)
  }}
  onDragEnd={({ height }) => {
    console.log("drag end", height)
  }}
>
  <Cell.Group>
    <Cell>内容</Cell>
  </Cell.Group>
</FloatingPanel>
```

### 手动设置高度

通过 `ref` 可以获取到 FloatingPanel 的实例，调用 `setHeight` 方法可以手动设置 FloatingPanel 的高度。

```tsx
function CustomHeight() {
  const floatingPanelRef = useRef<any>()
  const resetHeight = () => {
    floatingPanelRef.current?.setHeight(100)
  }

  return (<>
  <Button color="default" onClick={resetHeight}>重置高度</Button>
  <FloatingPanel ref={floatingPanelRef}>
    <Cell.Group>
      <Cell>1</Cell>
      <Cell>2</Cell>
      <Cell>3</Cell>
      <Cell>4</Cell>
      <Cell>5</Cell>
      <Cell>6</Cell>
      <Cell>7</Cell>
      <Cell>8</Cell>
      <Cell>9</Cell>
      <Cell>10</Cell>
      <Cell>11</Cell>
      <Cell>12</Cell>
      <Cell>13</Cell>
    </Cell.Group>
  </FloatingPanel>
</>)
}
```

## API

### Flex Props

| 参数                                 | 说明                      | 类型                                 | 默认值                              |
| ---------------------------------- | ----------------------- | ---------------------------------- | -------------------------------- |
| height                             | 当前面板的显示高度               | _number_                           | `0`                              |
| anchors                            | 设置自定义锚点, 单位 `px`        | _number\[]_                        | `[100, window.innerWidth * 0.6]` |
| duration                           | 动画时长，单位秒，设置为 0 可以禁用动画   | _number_                           | `0.3`                            |
| contentDraggable                   | 允许拖拽内容容器                | _boolean_                          | `true`                           |
| safeAreaInsetBottom                | 是否开启底部安全区适配             | _boolean_                          | `true`                           |
| safeAreaProps <Tag tag="v1.0.0" /> | 底部安全区属性（不包含 `position`） | _Omit\<SafeAreaProps, "position">_ | -                                |

### Events

| 事件名                              | 说明              | 回调参数                  |
| -------------------------------- | --------------- | --------------------- |
| onDragStart <Tag tag="v1.0.0" /> | 面板开始拖拽时触发       | _\{ height: number }_ |
| onDragging <Tag tag="v1.0.0" />  | 面板拖拽过程中持续触发     | _\{ height: number }_ |
| onDragEnd <Tag tag="v1.0.0" />   | 面板结束拖拽并吸附到锚点后触发 | _\{ height: number }_ |

### 方法

通过 ref 可以获取到 FloatingPanel 实例并调用实例方法。

| 方法名       | 说明     | 参数       | 返回值 |
| --------- | ------ | -------- | --- |
| setHieght | 设置面板高度 | _number_ | -   |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                                         | 默认值                                | 描述 |
| ---------------------------------------------------------- | ---------------------------------- | -- |
| --floating-panel-z-index                                   | _1010_                             | -  |
| --floating-panel-rounded-border-radius                     | _16px \* $hd_                      | -  |
| --floating-panel-header-height                             | _60px_                             | -  |
| --floating-panel-bar-height                                | _6px_                              | -  |
| --floating-panel-bar-width                                 | _40px_                             | -  |
| --floating-panel-bar-color                                 | _var(--gray-5, $gray-5)_           | -  |
| --floating-panel-background                                | _var(--background-color-light)_    | -  |
| --floating-panel-safe-area-background <Tag tag="v1.0.0" /> | _var(--floating-panel-background)_ | -  |



---
url: https://taroify.com/components/floating-bubble/index.md
---

# FloatingBubble 浮动气泡

### 介绍

悬浮在页面边缘的可点击气泡。

请升级 `taroify` 到 >= `v0.1.1-alpha.1` 版本来使用该组件。

### 引入

```tsx
import { FloatingBubble } from "@taroify/core"
```

## 代码演示

### 基础用法

浮动气泡默认展示在右下角，并允许在 y 轴方向上下拖拽，你可以通过 `icon` 属性设置气泡的图标。

```tsx
function BasicFloatingBubble() {
  const onClick = () => {
    showToast({
      title: "点击气泡",
      icon: "none",
      duration: 1000,
    })
  }

  return <FloatingBubble icon={<ChatOutlined />} onClick={onClick} />
}
```

### 自由拖拽和磁吸

允许 x 和 y 轴方向拖拽，吸附到 x 轴方向最近一边。

```tsx
function CustomFloatingBubble() {
  const onOffsetChange = (x: number, y: number) => {
    showToast({
      title: `x: ${x.toFixed(0)}, y: ${y.toFixed(0)}`,
      icon: "none",
      duration: 1000,
    })
  }

  return (
    <FloatingBubble
      axis="xy"
      magnetic="x"
      icon={<ChatOutlined />}
      onOffsetChange={onOffsetChange}
    />
  )
}
```

## API

### Flex Props

| 参数       | 说明                                                     | 类型                           | 默认值       |
| -------- | ------------------------------------------------------ | ---------------------------- | --------- |
| offset   | 控制气泡位置                                                 | OffsetType                   | `默认右下角坐标` |
| axis     | 拖拽的方向，`xy` 代表自由拖拽，`lock` 代表禁止拖拽                        | _x_ \| _y_ \| _xy_ \| _lock_ | `y`       |
| magnetic | 自动磁吸的方向                                                | _x_ \| _y_                   | `-`       |
| icon     | 左侧[图标](/components/icon.md)或[图片](/components/image.md) | _ReactNode_                  | `-`       |
| gap      | 气泡与窗口的最小间距，单位为 `px`                                    | _Number_                     | `48`      |

### Events

| 事件名            | 说明             | 回调参数                   |
| -------------- | -------------- | ---------------------- |
| onClick        | 点击组件时触发        | _ITouchEvent_          |
| onOffsetChange | 由用户拖拽导致位置改变后触发 | _x: string, y: string_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                              | 默认值                    | 描述 |
| ------------------------------- | ---------------------- | -- |
| --floating-bubble-size          | _96px_                 | -  |
| --floating-bubble-initial-gap   | _48px_                 | -  |
| --floating-bubble-background    | _var(--blue, $blue)_   | -  |
| --floating-bubble-color         | _var(--white, $white)_ | -  |
| --floating-bubble-border-radius | _999px_                | -  |
| --floating-bubble-z-index       | _999_                  | -  |
| --floating-bubble-duratio       | _0.3s_                 | -  |
| --floating-bubble-icon-size     | _56px_                 | -  |



---
url: https://taroify.com/components/tour/index.md
---

# Tour 引导

### 介绍

用于分步引导用户了解产品功能，支持目标区域高亮、气泡定位和自定义内容。

### 引入

```tsx
import { Tour } from "@taroify/core"
```

## 代码演示

### 基础用法

通过 `list` 配置目标元素和引导内容。字符串类型的 `target` 会按元素 `id` 查找，也可以传入 React Ref。

```tsx
import { useState } from "react"
import { Button, Cell, Tour } from "@taroify/core"

function BasicTour() {
  const [open, setOpen] = useState(false)

  return (
    <>
      <Cell title="功能引导">
        <Button id="tour-basic-target" size="small" onClick={() => setOpen(true)}>
          开始
        </Button>
      </Cell>
      <Tour
        open={open}
        type="tile"
        placement="bottom-end"
        list={[
          {
            target: "tour-basic-target",
            content: "点击这里可以开始体验新功能",
          },
        ]}
        onClose={() => setOpen(false)}
      />
    </>
  )
}
```

### 步骤引导

`step` 类型会展示当前进度和上一步、下一步、完成按钮。每一步都可以单独设置气泡位置。

```tsx
const steps = [
  {
    target: "tour-step-1",
    content: "这里是首页入口",
  },
  {
    target: "tour-step-2",
    content: "在这里查看全部分类",
  },
  {
    target: "tour-step-3",
    content: "最后进入个人中心",
    placement: "top-end",
  },
]

<Tour
  open={open}
  title="功能介绍"
  list={steps}
  placement="top-start"
  onChange={(current) => console.log(current)}
  onClose={() => setOpen(false)}
/>
```

### 设置遮罩和偏移

`offset` 控制高亮区域相对于目标元素的纵向、横向扩展距离；`popoverOffset` 和 `arrowOffset` 可以单独调整每一步的气泡。

```tsx
<Tour
  open={open}
  maskWidth={60}
  maskHeight={50}
  offset={[8, 8]}
  list={[
    {
      target: "tour-offset-target",
      content: "自定义高亮和气泡偏移",
      popoverOffset: [20, 16],
      arrowOffset: -20,
    },
  ]}
  onClose={() => setOpen(false)}
/>
```

### 自定义内容

传入 `children` 可以完全自定义气泡内容。

```tsx
<Tour
  open={open}
  type="tile"
  list={[{ target: "tour-custom-target" }]}
  closeOnOverlayClick={false}
  onClose={() => setOpen(false)}
>
  <View className="custom-tour-content">
    <View>欢迎体验全新功能</View>
    <View onClick={() => setOpen(false)}>知道了</View>
  </View>
</Tour>
```

## API

### Props

| 参数                  | 说明             | 类型                        | 默认值       |
| ------------------- | -------------- | ------------------------- | --------- |
| defaultOpen         | 默认是否展示引导       | _boolean_                 | `false`   |
| open                | 是否展示引导         | _boolean_                 | `false`   |
| type                | 引导类型           | _step \| tile_            | `step`    |
| list                | 引导步骤           | _TourStep\[]_             | `[]`      |
| placement           | 气泡位置           | _TourPlacement_           | `bottom`  |
| offset              | 高亮区域纵向、横向扩展距离  | _\[number, number]_       | `[8, 10]` |
| mask                | 是否显示遮罩         | _boolean_                 | `true`    |
| maskWidth           | 高亮区域宽度         | _number \| string_        | 目标宽度      |
| maskHeight          | 高亮区域高度         | _number \| string_        | 目标高度      |
| title               | 标题，设置后同时展示关闭按钮 | _ReactNode_               | `-`       |
| next                | 下一步按钮内容        | _ReactNode_               | `下一步`     |
| prev                | 上一步按钮内容        | _ReactNode_               | `上一步`     |
| complete            | 完成按钮内容         | _ReactNode_               | `完成`      |
| showPrev            | 是否展示上一步按钮      | _boolean_                 | `true`    |
| closeOnOverlayClick | 是否在点击遮罩后关闭     | _boolean_                 | `true`    |
| lock                | 是否禁止背景滚动       | _boolean_                 | `true`    |
| children            | 自定义气泡内容        | _ReactNode_               | `-`       |
| onClose             | 引导关闭时触发        | _(opened, event) => void_ | `-`       |
| onChange            | 切换步骤时触发        | _(current) => void_       | `-`       |

### TourStep

| 参数            | 说明                                   | 类型                  | 默认值       |
| ------------- | ------------------------------------ | ------------------- | --------- |
| target        | 目标元素的 `id`、CSS 选择器、DOM 元素或 React Ref | _TourTarget_        | `-`       |
| content       | 引导内容                                 | _ReactNode_         | `-`       |
| placement     | 当前步骤的气泡位置                            | _TourPlacement_     | `-`       |
| popoverOffset | 气泡在交叉轴、主轴方向的偏移量                      | _\[number, number]_ | `[0, 12]` |
| arrowOffset   | 箭头在交叉轴方向的偏移量                         | _number_            | `0`       |

### TourPlacement

`top`、`top-start`、`top-end`、`bottom`、`bottom-start`、`bottom-end`、`left`、`left-start`、`left-end`、`right`、`right-start`、`right-end`。

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                              | 默认值                              | 描述     |
| ------------------------------- | -------------------------------- | ------ |
| --tour-z-index                  | _1100_                           | 层级     |
| --tour-mask-color               | _rgba(0, 0, 0, 0.7)_             | 遮罩颜色   |
| --tour-mask-border-radius       | _var(--border-radius-lg)_        | 高亮区域圆角 |
| --tour-popover-min-width        | _280px_                          | 气泡最小宽度 |
| --tour-popover-max-width        | _calc(100vw - 64px)_             | 气泡最大宽度 |
| --tour-popover-padding          | _24px_                           | 气泡内边距  |
| --tour-popover-color            | _var(--text-color)_              | 气泡文字颜色 |
| --tour-popover-background-color | _var(--background-color-2)_      | 气泡背景色  |
| --tour-popover-border-radius    | _var(--border-radius-md)_        | 气泡圆角   |
| --tour-popover-box-shadow       | _0 8px 32px rgba(0, 0, 0, 0.12)_ | 气泡阴影   |
| --tour-arrow-size               | _12px_                           | 箭头大小   |
| --tour-content-font-size        | _var(--font-size-md)_            | 内容字号   |
| --tour-content-line-height      | _var(--line-height-md)_          | 内容行高   |
| --tour-footer-margin-top        | _24px_                           | 底部上边距  |
| --tour-button-gap               | _12px_                           | 按钮间距   |
| --tour-button-padding           | _6px 16px_                       | 按钮内边距  |
| --tour-button-font-size         | _var(--font-size-sm)_            | 按钮字号   |
| --tour-button-border-radius     | _var(--border-radius-sm)_        | 按钮圆角   |



---
url: https://taroify.com/components/loading/index.md
---

# Loading 加载

### 介绍

加载图标，用于表示加载中的过渡状态。

### 引入

```tsx
import { Loading } from "@taroify/core"
```

## 代码演示

### 加载类型

通过 `type` 属性可以设置加载图标的类型，默认为 `circular`，可选值为 `spinner`。

```tsx
<Loading />
<Loading type="spinner" />
```

### 自定义颜色

通过 `css` 设置加载图标的颜色。

```tsx
<Loading />
<Loading type="spinner" />
```

```scss
.custom-color {
  color: #1989fa;
  
  .taroify-loading__text {
    color: #1989fa;
  }
}
```

### 自定义大小

通过 `size` 属性设置加载图标的大小，默认单位为 `px`。

```tsx
<Loading size="24px" />
<Loading type="spinner" size="24px" />
```

### 加载文案

可以使用默认插槽在图标的右侧插入加载文案。

```tsx
<Loading size="24px">加载中...</Loading>
```

### 垂直排列

设置 `vertical` 属性后，图标和文案会垂直排列。

```tsx
<Loading size="24px" direction="vertical">加载中...</Loading>
```

### 自定义文案颜色

通过 `css` 设置加载文案的颜色。

```tsx
<!-- 可修改文案和加载图标的颜色 -->
<Loading className="custom-color" />

<!-- 只修改文案颜色 -->
<Loading className="custom-text-color" />
```

```scss
.custom-text-color {
  .taroify-loading__text {
    color: #1989fa;
  }
}
```

## API

### Props

| 参数        | 说明                     | 类型                 | 默认值        |
| --------- | ---------------------- | ------------------ | ---------- |
| type      | 类型，可选值为 `spinner`      | _string_           | `circular` |
| size      | 加载图标大小，默认单位为 `px`      | _number \| string_ | `30px`     |
| direction | 排列方向，可选值为 `horizontal` | _string_           | `vertical` |
| children  | 加载文案                   | _ReactNode_        | -          |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                              | 默认值                   | 描述 |
| ------------------------------- | --------------------- | -- |
| --loading-color                 | _var(--gray-5)_       | -  |
| --loading-size                  | _30px \* $hd_         | -  |
| --loading-animation-duration    | _0.8s_                | -  |
| --loading-circular-border-width | _1px \* $hd_          | -  |
| --loading-text-color            | _var(--gray-6)_       | -  |
| --loading-text-font-size        | _var(--font-size-md)_ | -  |
| --loading-text-line-height      | _20px \* $hd_         | -  |



---
url: https://taroify.com/components/notify/index.md
---

# Notify 消息提示

### 介绍

在页面顶部展示消息提示，支持函数调用和组件调用两种方式。

### 函数调用

版本 >= `v0.6.0-alpha.0`可以直接调用。低版本需要手动在页面（page）里挂载一个 Notify 组件并指定 id 为 `notify`。

```tsx
import { Cell, Notify } from "@taroify/core"

function ImperativeNotify() {
  return (
    <>
      {/* <Notify id="notify" /> */}
      <Cell title="函数调用" clickable isLink onClick={() => Notify.open("通知内容")} />
    </>
  )
}
```

### 组件调用

```tsx
import { Cell, Notify } from "@taroify/core"

function BasicNotify() {
  const [open, setOpen] = useState(false)

  return (
    <>
      <Notify open={open} onClose={setOpen}>
        通知内容
      </Notify>
      <Cell title="基础用法" clickable onClick={() => setOpen(true)} />
    </>
  )
}
```

## 代码演示

### 基础用法

```ts
Notify.open("通知内容")
```

```tsx
<Notify id="notify" open>
  通知内容
</Notify>
```

### 通知颜色

预设 `primary`、`success`、`warning`、`danger` 四种通知颜色，默认为 `danger`。

```ts
Notify.open({ type: "primary", message: "通知内容" })
Notify.open({ type: "success", message: "通知内容" })
Notify.open({ type: "danger", message: "通知内容" })
Notify.open({ type: "warning", message: "通知内容" })
```

```tsx
<Notify open type="primary">通知内容</Notify>
<Notify open type="success">通知内容</Notify>
<Notify open type="danger">通知内容</Notify>
<Notify open type="warning">通知内容</Notify>
```

### 自定义通知

自定义消息通知的颜色和展示时长。

```ts
Notify.open({
  color: "#ad0000",
  background: "#ffe1e1",
  message: "自定义颜色",
})
Notify.open({
  duration: 1000,
  message: "自定义时长",
})
```

```tsx
<Notify open style={{ color: "#ad0000", background: "#ffe1e1" }}>自定义颜色</Notify>
<Notify open duration={1000}>自定义时长</Notify>
```

## API

### Props

| 参数          | 说明                                    | 类型                         | 默认值      |
| ----------- | ------------------------------------- | -------------------------- | -------- |
| className   | 自定义类名                                 | _string_                   | -        |
| style       | 组件样式                                  | _CSSProperties_            | -        |
| defaultOpen | 默认是否显示消息提示                            | _boolean_                  | -        |
| open        | 是否显示消息提示                              | _boolean_                  | -        |
| type        | 类型，可选值为 `primary` `success` `warning` | _string_                   | `danger` |
| color       | 字体颜色                                  | _string_                   | -        |
| background  | 背景颜色                                  | _string_                   | -        |
| duration    | 展示时长(ms)，值为 0 时，notify 不会消失           | _number_                   | `3000`   |
| children    | 展示文案，支持通过`\n`换行                       | _ReactNode_                | -        |
| onClose     | 关闭时的回调函数                              | _(open : boolean) => void_ | -        |

### Options

| 参数        | 说明                                    | 类型                         | 默认值      |
| --------- | ------------------------------------- | -------------------------- | -------- |
| selector  | 自定义节点选择器                              | _string_                   | `notify` |
| className | 自定义类名                                 | _string_                   | -        |
| style     | 组件样式                                  | _CSSProperties_            | -        |
| color     | 类型，可选值为 `primary` `success` `warning` | _string_                   | `danger` |
| duration  | 展示时长(ms)，值为 0 时，notify 不会消失           | _number_                   | `3000`   |
| message   | 展示文案，支持通过`\n`换行                       | _ReactNode_                | -        |
| onClose   | 关闭时的回调函数                              | _(open : boolean) => void_ | -        |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                | 默认值                                   | 描述 |
| --------------------------------- | ------------------------------------- | -- |
| --notify-color                    | _var(--white)_                        | -  |
| --notify-padding                  | _var(--padding-xs) var(--padding-md)_ | -  |
| --notify-font-size                | _var(--font-size-md)_                 | -  |
| --notify-line-height              | _var(--line-height-md)_               | -  |
| --notify-primary-background-color | _var(--primary-color)_                | -  |
| --notify-success-background-color | _var(--success-color)_                | -  |
| --notify-warning-background-color | _var(--warning-color)_                | -  |
| --notify-danger-background-color  | _var(--danger-color)_                 | -  |



---
url: https://taroify.com/components/backdrop/index.md
---

# Backdrop 背景板

### 介绍

创建一个背景幕，用于强调特定的页面元素，并阻止用户进行其他操作。

### 引入

```jsx
import { Backdrop } from "@taroify/core"
```

## 代码演示

### 基础用法

```jsx
import { Backdrop, Button } from "@taroify/core"

function BackdropExample() {
  const [open, setOpen] = useState(false)
  return (
    <>
      <Button onClick={() => setOpen(true)}>显示背景板</Button>
      <Backdrop open={open} closeable onClose={() => setOpen(false)} />
    </>
  )
}
```

### 嵌入内容

通过 children 可以在背景板上嵌入任意内容。

```jsx
import { Backdrop, Button } from "@taroify/core"

function BackdropExample() {
  const [open, setOpen] = useState(false)
  return (
    <>
      <Button onClick={() => setOpen(true)}>嵌入内容</Button>
      <Backdrop open={open} closeable onClose={() => setOpen(false)}>
        <View className="content-wrapper">
          <View className="content-block" />
        </View>
      </Backdrop>
    </>
  )
}
```

```scss
.content-wrapper {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100%;
}

.content-block {
  width: 60px * 2;
  height: 60px * 2;
  background-color: #fff;
}
```

## API

### Props

| 参数          | 说明           | 类型          | 默认值     |
| ----------- | ------------ | ----------- | ------- |
| className   | 自定义类名        | _string_    | -       |
| children    | 用于在遮罩层上方嵌入内容 | _ReactNode_ | -       |
| defaultOpen | 是否默认展示遮罩层    | _boolean_   | `false` |
| open        | 是否展示遮罩层      | _boolean_   | `false` |
| duration    | 动画时长，单位毫秒    | _number_    | `300`   |
| lock        | 是否锁定背景滚动     | _boolean_   | `true`  |
| closeable   | 点击遮罩层时是否关闭   | _boolean_   | `false` |

### Event

| 事件      | 说明    | 回调参数 |
| ------- | ----- | ---- |
| onClick | 点击时触发 | -    |
| onClose | 关闭时触发 | -    |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                          | 默认值                  | 描述 |
| --------------------------- | -------------------- | -- |
| --backdrop-z-index          | _1000_               | -  |
| --backdrop-background-color | _rgba(0, 0, 0, 0.7)_ | -  |



---
url: https://taroify.com/components/pull-refresh/index.md
---

# PullRefresh 下拉刷新

### 介绍

用于提供下拉刷新的交互操作。

### 引入

```tsx
import { PullRefresh } from "@taroify/core"
```

## 代码演示

### 基础用法

下拉刷新时会触发 `onRefresh` 事件，在事件的回调函数中可以进行同步或异步操作，操作完成后将 `loading` 设置为 `false`，表示加载完成。

```tsx
function BasicPullRefresh() {
  const [loading, setLoading] = useState(false)
  const [counter, setCounter] = useState(0)
  const [reachTop, setReachTop] = useState(true)

  usePageScroll(({ scrollTop }) => setReachTop(scrollTop === 0))

  return (
    <PullRefresh
      loading={loading}
      reachTop={reachTop}
      onRefresh={() => {
        setLoading(true)
        setTimeout(() => {
          setCounter(counter + 1)
          setLoading(false)
        }, 1000)
      }}
    >
      <View className="pull-text">{counter ? "刷新次数：" + counter : "下拉试试"}</View>
    </PullRefresh>
  )
}
```

> Tips：在 PullRefresh 组件内部采用 Selector API 获得父滚动元素的 scrollTop 值会带来下拉卡顿的性能问题。因此需要在 PullRefresh 组件外部判断 scrollTop 值，在页面中使用 usePageScroll() 钩子获得 scrollTop 值，在 ScrollView 组件内监听 onScroll 事件获得 scrollTop 值。
> 固定高度的 List 可以开启 `pullRefresh` 自动同步滚动位置，具体用法请参考
> [List 下拉刷新](/components/list/index.md#固定高度)。

### 完成提示

通过 `PullRefresh.Completed` 可以设置刷新成功后的顶部提示文案。

```tsx
function CompletedPullRefresh() {
  const [loading, setLoading] = useState(false)
  const [counter, setCounter] = useState(0)
  const [reachTop, setReachTop] = useState(true)

  usePageScroll(({ scrollTop }) => setReachTop(scrollTop === 0))

  return (
    <PullRefresh
      loading={loading}
      reachTop={reachTop}
      onRefresh={() => {
        setLoading(true)
        setTimeout(() => {
          setLoading(false)
          setCounter(counter + 1)
        }, 1000)
      }}
    >
      <PullRefresh.Completed>刷新成功</PullRefresh.Completed>
      <View className="pull-text">{counter ? "刷新次数：" + counter : "下拉试试"}</View>
    </PullRefresh>
  )
}
```

### 自定义提示

通过子组件可以自定义下拉刷新过程中的提示内容。

```tsx
function CustomPullRefresh() {
  const [loading, setLoading] = useState(false)
  const [counter, setCounter] = useState(0)
  const [reachTop, setReachTop] = useState(true)

  usePageScroll(({ scrollTop }) => setReachTop(scrollTop === 0))

  return (
    <PullRefresh
      loading={loading}
      headHeight={80}
      reachTop={reachTop}
      onRefresh={() => {
        setLoading(true)
        setTimeout(() => {
          setCounter(counter + 1)
          setLoading(false)
        }, 1000)
      }}
    >
      <PullRefresh.Pulling>
        {({ distance = 0 }) => (
          <Image
            className="doge"
            style={{ transform: `scale(${distance / 80})` }}
            src="https://img.yzcdn.cn/vant/doge.png"
          />
        )}
      </PullRefresh.Pulling>
      <PullRefresh.Loosing>
        <Image className="doge" src="https://img.yzcdn.cn/vant/doge.png" />
      </PullRefresh.Loosing>
      <PullRefresh.Loading>
        <Image className="doge" src="https://img.yzcdn.cn/vant/doge-fire.jpg" />
      </PullRefresh.Loading>
      <View className="pull-text">{counter ? "刷新次数：" + counter : "下拉试试"}</View>
    </PullRefresh>
  )
}
```

```scss
.doge {
  width: 140px * 2;
  height: 72px * 2;
  margin-top: 8px * 2;
  border-radius: 4px * 2;
}
```

### 搭配 ScrollView

可搭配 ScrollView 组件

```tsx
function BasicPullRefresh() {
  const [loading, setLoading] = useState(false)
  const [counter, setCounter] = useState(0)
  const [reachTop, setReachTop] = useState(true)

  usePageScroll(({ scrollTop }) => setReachTop(scrollTop === 0))

  return (
    <ScrollView scrollY>
      <PullRefresh
        loading={loading}
        reachTop={reachTop}
        onRefresh={() => {
          setLoading(true)
          setTimeout(() => {
            setCounter(counter + 1)
            setLoading(false)
          }, 1000)
        }}
      >
        <View className="pull-text">{counter ? "刷新次数：" + counter : "下拉试试"}</View>
      </PullRefresh>
    </ScrollView>
  )
}
```

## API

### Props

| 参数           | 说明        | 类型                 | 默认值               |
| ------------ | --------- | ------------------ | ----------------- |
| loading      | 是否处于加载中状态 | _boolean_          | -                 |
| duration     | 动画时长      | _number \| string_ | `300`             |
| headHeight   | 顶部内容高度    | _number \| string_ | `50`              |
| reachTop     | 是否处于顶部下拉  | _boolean_          | `true`            |
| pullDistance | 触发下拉刷新的距离 | _number \| string_ | 与 `headHeight` 一致 |
| disabled     | 是否禁用下拉刷新  | _boolean_          | `false`           |

### Events

| 事件名       | 说明      | 回调参数 |
| --------- | ------- | ---- |
| onRefresh | 下拉刷新时触发 | -    |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                 | 默认值                                     | 描述 |
| ---------------------------------- | --------------------------------------- | -- |
| --pull-refresh-head-height         | _50px \* $hd_                           | -  |
| --pull-refresh-head-line-height    | _var(--pull-refresh-head-height)_       | -  |
| --pull-refresh-head-font-size      | _var(--font-size-md)_                   | -  |
| --pull-refresh-head-color          | _var(--gray-6)_                         | -  |
| --pull-refresh-loading-icon-size   | _16px \* $hd_                           | -  |
| --pull-refresh-loading-icon-width  | _var(--pull-refresh-loading-icon-size)_ | -  |
| --pull-refresh-loading-icon-height | _var(--pull-refresh-loading-icon-size)_ | -  |



---
url: https://taroify.com/components/share-sheet/index.md
---

# ShareSheet 分享面板

### 介绍

底部弹起的分享面板，用于展示各分享渠道对应的操作按钮，不含具体的分享逻辑。

### 引入

```tsx
import { ShareSheet } from "@taroify/core"
```

## 代码演示

### 基础用法

分享面板通过 `ShareSheet.Option` 组件来定义分享选项。

```tsx
import { ShareSheet } from "@taroify/core"

function BasicShareSheet() {
  const [open, setOpen] = useState(true)
  return (
    <ShareSheet open={open} onSelect={() => setOpen(false)} onClose={setOpen}>
      <ShareSheet.Header title="立即分享给好友" />
      <ShareSheet.Options>
        <ShareSheet.Option icon="wechat" name="微信" />
        <ShareSheet.Option icon="wechat-moments" name="朋友圈" />
        <ShareSheet.Option icon="weibo" name="微博" />
        <ShareSheet.Option icon="qq" name="QQ" />
      </ShareSheet.Options>
      <ShareSheet.Button type="cancel">取消</ShareSheet.Button>
    </ShareSheet>
  )
}
```

### 展示多行选项

当分享选项的数量较多时，可以将 `options` 定义为数组嵌套的格式，每个子数组会作为一行选项展示。

```tsx
import { ShareSheet } from "@taroify/core"

function MultilineShareSheet() {
  const [open, setOpen] = useState(true)
  return (
    <ShareSheet open={open} onSelect={() => setOpen(false)} onClose={setOpen}>
      <ShareSheet.Header title="立即分享给好友" />
      <ShareSheet.Options>
        <ShareSheet.Option icon="wechat" name="微信" />
        <ShareSheet.Option icon="wechat-moments" name="朋友圈" />
        <ShareSheet.Option icon="weibo" name="微博" />
        <ShareSheet.Option icon="qq" name="QQ" />
      </ShareSheet.Options>
      <ShareSheet.Options>
        <ShareSheet.Option icon="link" name="复制链接" />
        <ShareSheet.Option icon="poster" name="分享海报" />
        <ShareSheet.Option icon="qrcode" name="二维码" />
        <ShareSheet.Option icon="weapp-qrcode" name="小程序码" />
      </ShareSheet.Options>
      <ShareSheet.Button type="cancel">取消</ShareSheet.Button>
    </ShareSheet>
  )
}
```

### 自定义图标

除了使用内置的几种图标外，可以直接在 `icon` 中传入 Image 组件来使用自定义的图标。

```tsx
import { Image, ShareSheet } from "@taroify/core"

function CustomShareSheet() {
  const [open, setOpen] = useState(true)
  return (
    <ShareSheet open={open} onSelect={() => setOpen(false)} onClose={setOpen}>
      <ShareSheet.Options>
        <ShareSheet.Option
          icon={<Image src="https://img.yzcdn.cn/vant/custom-icon-fire.png" />}
          name="名称"
        />
        <ShareSheet.Option
          icon={<Image src="https://img.yzcdn.cn/vant/custom-icon-light.png" />}
          name="名称"
        />
        <ShareSheet.Option
          icon={<Image src="https://img.yzcdn.cn/vant/custom-icon-water.png" />}
          name="名称"
        />
      </ShareSheet.Options>
      <ShareSheet.Button type="cancel">取消</ShareSheet.Button>
    </ShareSheet>
  )
}
```

### 展示描述信息

通过 `description` 属性可以设置标题下方的描述文字, 在 `options` 内设置 `description` 属性可以添加分享选项描述。

```tsx
import { ShareSheet } from "@taroify/core"

function ShareSheetWithDescription() {
  const [open, setOpen] = useState(true)
  return (
    <ShareSheet open={open} onSelect={() => setOpen(false)} onClose={setOpen}>
      <ShareSheet.Header title="立即分享给好友">描述信息</ShareSheet.Header>
      <ShareSheet.Options>
        <ShareSheet.Option icon="wechat" name="微信" />
        <ShareSheet.Option icon="weibo" name="微博" />
        <ShareSheet.Option icon="link" name="复制链接" description="描述信息" />
        <ShareSheet.Option icon="poster" name="分享海报" />
        <ShareSheet.Option icon="qrcode" name="二维码" />
      </ShareSheet.Options>
      <ShareSheet.Button type="cancel">取消</ShareSheet.Button>
    </ShareSheet>
  )
}
```

## API

### ShareSheet Props

| 参数          | 说明         | 类型              | 默认值     |
| ----------- | ---------- | --------------- | ------- |
| defaultOpen | 默认是否显示动作面板 | _boolean_       | `false` |
| open        | 是否显示动作面板   | _boolean_       | `false` |
| className   | 样式类名       | _string_        | -       |
| style       | 样式对象       | _CSSProperties_ | -       |
| rounded     | 是否为圆角      | _string_        | -       |

### ShareSheet.Backdrop Props

| 参数        | 说明        | 类型                 | 默认值    |
| --------- | --------- | ------------------ | ------ |
| className | 样式类名      | _string_           | -      |
| style     | 样式对象      | _CSSProperties_    | -      |
| duration  | 动画时长，单位毫秒 | _number \| string_ | `300`  |
| closeable | 点击是否可以关闭  | _boolean_          | `true` |

### ShareSheet.Header Props

| 参数        | 说明   | 类型              | 默认值 |
| --------- | ---- | --------------- | --- |
| className | 样式类名 | _string_        | -   |
| style     | 样式对象 | _CSSProperties_ | -   |
| title     | 标题   | _string_        | -   |
| children  | 描述信息 | _string_        | -   |

### ShareSheet.Option Props

| 参数          | 说明                                                                                                                                                                        | 类型       | 默认值 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --- |
| className   | 分享选项类名                                                                                                                                                                    | _string_ | -   |
| name        | 分享渠道名称                                                                                                                                                                    | _string_ | -   |
| value       | 选项值                                                                                                                                                                       | _string_ | -   |
| description | 分享选项描述                                                                                                                                                                    | _string_ | -   |
| icon        | 图标，可选值为 `wechat` `weibo` `qq` `link` `qrcode` `poster`<br/>`weapp-qrcode` `wechat-moments`，支持传入 Image 组件                                                                  | _string_ | -   |
| openType    | 微信开放能力，可选值为 `contact` `contactShare` `share`<br/>`getRealnameAuthInfo` `getAuthorize` `getPhoneNumber`<br/>`getUserInfo` `lifestyle` `launchApp` `openSetting` `feedback` | _string_ | -   |

### Events

| 事件名      | 说明        | 回调参数                            |
| -------- | --------- | ------------------------------- |
| onSelect | 点击分享选项时触发 | _event: ShareSheet.OptionEvent_ |
| onCancel | 点击取消按钮时触发 | -                               |
| onClose  | 关闭面板时触发   | -                               |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                         | 默认值                                                       | 描述 |
| ------------------------------------------ | --------------------------------------------------------- | -- |
| --share-sheet-description-font-size        | _var(--font-size-sm)_                                     | -  |
| --share-sheet-options-padding              | _var(--padding-md) 0 var(--padding-md) var(--padding-xs)_ | -  |
| --share-sheet-option-icon-margin           | _0 var(--padding-md)_                                     | -  |
| --share-sheet-option-icon-size             | _48px \* $hd_                                             | -  |
| --share-sheet-option-icon-width            | _var(--share-sheet-option-icon-size)_                     | -  |
| --share-sheet-option-icon-height           | _var(--share-sheet-option-icon-size)_                     | -  |
| --share-sheet-option-icon-font-size        | _var(--share-sheet-option-icon-size)_                     | -  |
| --share-sheet-option-name-padding          | _0 var(--padding-base)_                                   | -  |
| --share-sheet-option-name-margin-top       | _var(--padding-xs)_                                       | -  |
| --share-sheet-option-name-color            | _var(--gray-7)_                                           | -  |
| --share-sheet-option-name-font-size        | _var(--font-size-sm)_                                     | -  |
| --share-sheet-option-name-line-height      | _1.4_                                                     | -  |
| --share-sheet-option-description-padding   | _0 var(--padding-base)_                                   | -  |
| --share-sheet-option-description-color     | _var(--gray-5)_                                           | -  |
| --share-sheet-option-description-font-size | _var(--font-size-sm)_                                     | -  |

## 常见问题

### 如何实现分享逻辑？

在不同的 App 或浏览器中，存在各式各样的分享接口或分享方式，因此 ShareSheet 组件不提供具体的分享逻辑，需要开发者根据业务场景自行实现。

#### 微信内分享

由于微信未提供分享相关的 API，需要引导用户点击右上角进行分享。

#### App 内分享

可以通过 JSBridge 调用原生应用的 SDK 进行分享。

#### 分享海报或二维码

可以通过 [Popup](/components/popup/index.md) 组件以弹层的形式展示图片，然后引导用户保存图片进行分享。



---
url: https://taroify.com/components/swipe-cell/index.md
---

# SwipeCell 滑动单元格

### 介绍

可以左右滑动来展示操作按钮的单元格组件。

### 引入

```tsx
import { SwipeCell } from "@taroify/core"
```

## 代码演示

### 基础用法

`SwipeCell` 组件提供了 `SwipeCell.Actions` 组件，用于定义两侧滑动区域的内容。

```tsx
<SwipeCell>
  <SwipeCell.Actions side="left">
    <Button variant="contained" shape="square" color="primary">选择</Button>
  </SwipeCell.Actions>
  <Cell bordered={false} title="单元格">
    内容
  </Cell>
  <SwipeCell.Actions side="right">
    <Button variant="contained" shape="square" color="danger">删除</Button>
    <Button variant="contained" shape="square" color="primary">收藏</Button>
  </SwipeCell.Actions>
</SwipeCell>
```

### 自定义内容

`SwipeCell` 可以嵌套任意内容，比如嵌套一个商品卡片。

```tsx
<SwipeCell className="custom-swipe-cell">
  <View className="custom-card">
    <Image className="custom-card__thumb" src="https://img01.yzcdn.cn/vant/ipad.jpeg" />
    <View className="custom-card__content">
      <View className="custom-card__title">商品标题</View>
    </View>
  </View>
  <SwipeCell.Actions side="right">
    <Button variant="contained" shape="square" color="danger">
      删除
    </Button>
    <Button variant="contained" shape="square" color="primary">
      收藏
    </Button>
  </SwipeCell.Actions>
</SwipeCell>
```

```scss
.custom-swipe-cell {

  .taroify-swipe-cell__actions {
    .taroify-button {
      height: 100%;
    }
  }

  .custom-card {
    background: #fff;
    position: relative;
    box-sizing: border-box;
    padding: 8px * 2 16px * 2;
    color: #323233;
    font-size: 12px;
    display: flex;

    &__thumb {
      position: relative;
      flex: none;
      width: 88px * 2;
      height: 88px * 2;
      margin-right: 8px * 2;
    }
  }
}

```

## API

### Props

| 参数              | 说明                                       | 类型                                       | 默认值     |
| --------------- | ---------------------------------------- | ---------------------------------------- | ------- |
| defaultOpen     | 默认是否打开滑动单元格，可选值：`left` `right` `outside` | _string_                                 | -       |
| open            | 是否打开滑动单元格，可选值：`left` `right` `outside`   | _string_                                 | -       |
| beforeClose     | 关闭前的回调函数，返回 `false` 可阻止关闭，支持返回 Promise   | _(args) => boolean \| Promise\<boolean>_ | -       |
| disabled        | 是否禁用滑动                                   | _boolean_                                | `false` |
| stopPropagation | 是否阻止滑动事件冒泡                               | _boolean_                                | `false` |
| catchMove       | 是否捕获触摸移动事件                               | _boolean_                                | `false` |

### Events

| 事件名     | 说明    | 回调参数                                                 |
| ------- | ----- | ---------------------------------------------------- |
| onOpen  | 打开时触发 | _position: 'left' \| 'right'_                        |
| onClose | 关闭时触发 | _position: 'left' \| 'right' \| 'cell' \| 'outside'_ |



---
url: https://taroify.com/components/avatar/index.md
---

# Avatar 头像

### 介绍

显示用户头像、首字母或备用图标。

### 引入

```ts
import { Avatar } from "@taroify/core"
```

## 代码演示

### 基础用法

设置 `style` 可以修改,背景颜色

```tsx
<Avatar>P</Avatar>
<Avatar style={{ background: "green" }}>N</Avatar>
<Avatar style={{ background: "pink" }}>HP</Avatar>
```

### 尺寸

设置 `size` 属性后，可以选择四个大小。

```tsx
<Avatar src="https://joesch.moe/api/v1/random" size="mini" />
<Avatar src="https://joesch.moe/api/v1/random" size="small" />
<Avatar src="https://joesch.moe/api/v1/random" size="medium" />
<Avatar src="https://joesch.moe/api/v1/random" size="large" />
```

### 形状

通过 `variant` 属性来设置形状。

```tsx
<Avatar src="https://joesch.moe/api/v1/random" />
<Avatar src="https://joesch.moe/api/v1/random" shape="square" />
<Avatar src="https://joesch.moe/api/v1/random" shape="rounded" />
```

### 群组

最多显示5个。

```tsx
<Avatar.Group total={24}>
  <Avatar src="https://joesch.moe/api/v1/random" />
  <Avatar src="https://joesch.moe/api/v1/random" />
  <Avatar src="https://joesch.moe/api/v1/random" />
  <Avatar src="https://joesch.moe/api/v1/random" />
  <Avatar src="https://joesch.moe/api/v1/random" />
  <Avatar src="https://joesch.moe/api/v1/random" />
</Avatar.Group>
```

### 最大

通过 `max` 属性最大可展示数量,最多显示5个。

```tsx
<Avatar.Group max={3}>
  <Avatar src="https://joesch.moe/api/v1/random" />
  <Avatar src="https://joesch.moe/api/v1/random" />
  <Avatar src="https://joesch.moe/api/v1/random" />
  <Avatar src="https://joesch.moe/api/v1/random" />
  <Avatar src="https://joesch.moe/api/v1/random" />
  <Avatar src="https://joesch.moe/api/v1/random" />
</Avatar.Group>
```

### 图标

```tsx
<Avatar style={{ background: "red" }}>
  <Cross />
</Avatar>
<Avatar style={{ background: "pink" }}>
  <LocationOutlined />
</Avatar>
<Avatar style={{ background: "green" }}>
  <SettingOutlined />
</Avatar>
```

### 徽章

```tsx
<Badge className="avatar-dot" dot position="bottom-right">
  <Avatar src="https://joesch.moe/api/v1/random" />
</Badge>
<Badge
  className="avatar-avatar"
  content={<Avatar src="https://joesch.moe/api/v1/random" />}
  position="bottom-right"
>
  <Avatar src="https://joesch.moe/api/v1/random" />
</Badge>
```

```scss
.avatar-dot {
  bottom: 2px * 2;
  right: 6px * 2,
}

.avatar-avatar {
  --badge-background-color: transparent;
  --badge-padding: 0;
  --badge-size: 12px * 2;
  --avatar-size: var(--badge-size);
  bottom: 2px * 2;
  right: 6px * 2,
}
```

## API

### Avatar Props

| 参数    | 说明                                      | 类型       | 默认值      |
| ----- | --------------------------------------- | -------- | -------- |
| src   | 传入图片的链接,传入之后嵌套内容不展示                     | _string_ | -        |
| alt   | 图片不显示时的文本内容                             | _string_ | -        |
| shape | 形状，可选值为 `square` `rounded` `circle`     | _string_ | `circle` |
| size  | 大小，可选值为 `mini` `small` `medium` `large` | _string_ | `medium` |

### Avatar.Group Props

| 参数      | 说明                                  | 类型       | 默认值      |
| ------- | ----------------------------------- | -------- | -------- |
| shape   | 形状，可选值为 `square` `rounded` `circle` | _string_ | `circle` |
| spacing | 间距，可选值为 `small` `medium` `large`    | _string_ | `medium` |
| limit   | 显示的最大头像个数                           | _number_ | -        |
| total   | 头像总数。用于计算额外头像的数量。                   | _string_ | -        |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                            | 默认值                                            | 描述 |
| ----------------------------- | ---------------------------------------------- | -- |
| --avatar-color                | _var(--white)_                                 | -  |
| --avatar-background-color     | _var(--gray-5)_                                | -  |
| --avatar-border-color         | _var(--white)_                                 | -  |
| --avatar-border-width         | _2PX_                                          | -  |
| --avatar-font-weight          | _var(--font-weight-bold)_                      | -  |
| --avatar-font-family          | _Roboto, Helvetica, Arial, sans-serif_         | -  |
| --avatar-font-size-mini       | _var(--avatar-font-size, var(--font-size-xs))_ | -  |
| --avatar-font-size-small      | _var(--avatar-font-size, var(--font-size-sm))_ | -  |
| --avatar-font-size-medium     | _var(--avatar-font-size, var(--font-size-md))_ | -  |
| --avatar-font-size-large      | _var(--avatar-font-size, var(--font-size-lg))_ | -  |
| --avatar-border-radius-mini   | _var(--avatar-border-radius, 2px \* $hd)_      | -  |
| --avatar-border-radius-small  | _var(--avatar-border-radius, 4px \* $hd)_      | -  |
| --avatar-border-radius-medium | _var(--avatar-border-radius, 5px \* $hd)_      | -  |
| --avatar-border-radius-large  | _var(--avatar-border-radius, 6px \* $hd)_      | -  |
| --avatar-size-mini            | _var(--avatar-size, 16px \* $hd)_              | -  |
| --avatar-size-small           | _var(--avatar-size, 26px \* $hd)_              | -  |
| --avatar-size-medium          | _var(--avatar-size, 38px \* $hd)_              | -  |
| --avatar-size-large           | _var(--avatar-size, 56px \* $hd)_              | -  |
| --avatar-spacing-mini         | _var(--avatar-spacing, var(--padding-xs))_     | -  |
| --avatar-spacing-small        | _var(--avatar-spacing, var(--padding-sm))_     | -  |
| --avatar-spacing-medium       | _var(--avatar-spacing, var(--padding-md))_     | -  |
| --avatar-spacing-large        | _var(--avatar-spacing, var(--padding-lg))_     | -  |



---
url: https://taroify.com/components/badge/index.md
---

# Badge 徽标

### 介绍

在右上角展示徽标数字或小红点。

请升级 `taroify` 到 >= `v0.3.0-alpha.0` 版本来使用该组件。

### 引入

```ts
import { Badge } from "@taroify/core"
```

## 代码演示

### 基础用法

设置 `content` 属性后，Badge 会在子元素的右上角显示对应的徽标，也可以通过 `dot` 来显示小红点。

```tsx
<Badge content={5}>
  <View className="badge-block" />
</Badge>
<Badge content="10">
  <View className="badge-block" />
</Badge>
<Badge content="Hot">
  <View className="badge-block" />
</Badge>
<Badge dot>
  <View className="badge-block" />
</Badge>
```

```scss
.badge-block {
  width: 40px * 2;
  height: 40px * 2;
  background: #f2f3f5ff;
  border-radius: 4px * 2;
}
```

### 最大值

设置 `max` 属性后，当 `content` 的数值超过最大值时，会自动显示为 `{max}+`。

```tsx
<Badge content={10} max={9}>
  <View className="badge-block" />
</Badge>
<Badge content={21} max={20}>
  <View className="badge-block" />
</Badge>
<Badge content={100} max={99}>
  <View className="badge-block" />
</Badge>
```

### 自定义颜色

通过 `color` 属性来设置徽标的颜色。

```tsx
<Badge className="custom-color" content={5}>
  <View className="badge-block" />
</Badge>
<Badge className="custom-color" content={10}>
  <View className="badge-block" />
</Badge>
<Badge className="custom-color" content="Hot">
  <View className="badge-block" />
</Badge>
<Badge className="custom-color" dot>
  <View className="badge-block" />
</Badge>
```

```scss
.custom-color {
  --badge-background-color: red;
}
```

### 自定义徽标内容

通过 `content` 属性可以自定义徽标的内容，比如插入一个图标。

```tsx
<Badge content={<Success className="badge-icon" />}>
  <View className="badge-block" />
</Badge>
<Badge content={<Cross className="badge-icon" />}>
  <View className="badge-block" />
</Badge>
<Badge content={<Down className="badge-icon" />}>
  <View className="badge-block" />
</Badge>
```

```scss
.badge-icon {
  display: block;
  margin-left: 0;
  font-size: 10px * 2;
  line-height: 16px * 2;
}
```

### 自定义徽标位置

通过 `position` 属性来设置徽标的位置。

```tsx
<Badge content={10} position="top-left">
  <View className="badge-block" />
</Badge>
<Badge content={10} position="top-right">
  <View className="badge-block" />
</Badge>
<Badge content={10} position="bottom-left">
  <View className="badge-block" />
</Badge>
<Badge content={10} position="bottom-right">
  <View className="badge-block" />
</Badge>
```

### 独立展示

当 Badge 没有子元素时，会作为一个独立的元素进行展示。

```tsx
<Badge content="20" />
<Badge content={100} max={99} />
```

## API

### Props

| 参数       | 说明                                                | 类型                 | 默认值         |
| -------- | ------------------------------------------------- | ------------------ | ----------- |
| content  | 徽标内容                                              | _ReactNode_        | -           |
| dot      | 是否展示为小红点                                          | _boolean_          | `false`     |
| max      | 最大值，超过最大值会显示 `{max}+`，仅当 content 为数字时有效           | _number \| string_ | -           |
| position | 徽标位置，可选值为 `top-left` `bottom-left` `bottom-right` | _string_           | `top-right` |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                       | 默认值                                                     | 描述 |
| ------------------------ | ------------------------------------------------------- | -- |
| --badge-size             | _16px \* $hd_                                           | -  |
| --badge-color            | _var(--white)_                                          | -  |
| --badge-padding          | _0 3px \* $hd_                                          | -  |
| --badge-font-family      | _-apple-system-font, helvetica neue, arial, sans-serif_ | -  |
| --badge-font-size        | _var(--font-size-sm)_                                   | -  |
| --badge-font-weight      | _var(--font-weight-bold)_                               | -  |
| --badge-border-width     | _var(--border-width-base)_                              | -  |
| --badge-border-color     | _var(--white)_                                          | -  |
| --badge-border-radius    | _var(--border-radius-max)_                              | -  |
| --badge-background-color | _var(--red)_                                            | -  |
| --badge-dot-color        | _var(--badge-background-color)_                         | -  |
| --badge-dot-size         | _8PX_                                                   | -  |



---
url: https://taroify.com/components/circle/index.md
---

# Circle 环形进度条

### 介绍

圆环形的进度条组件，支持进度渐变动画。

### 引入

```tsx
import { Circle } from "@taroify/core"
```

## 代码演示

### 基础用法

`percent` 属性表示进度条的进度，监听 `onChange` 事件可以获得动画过程中的实时进度。

```tsx
function BasicCircle({ percent }: PercentProps) {
  const [currentPercent, setCurrentPercent] = useState(70)

  return (
    <Circle percent={currentPercent} onChange={setCurrentPercent}>
      {currentPercent.toFixed(0)}%
    </Circle>
  )
}
```

### 宽度定制

通过 `strokeWidth` 属性来控制进度条宽度。

```tsx
<Circle percent={70} strokeWidth={60}>
  宽度定制
</Circle>
```

### 颜色定制

通过 `color` 属性来控制进度条颜色，`layerColor` 属性来控制轨道颜色。

```tsx
<Circle percent={70} color="#ee0a24" layerColor="#ebedf0">
  颜色定制
</Circle>
```

### 渐变色

`color` 属性支持传入对象格式来定义渐变色。

```tsx
<Circle
  percent={70}
  color={{
    "0%": "#3fecff",
    "100%": "#6149f6",
  }}
>
  渐变色
</Circle>
```

### 逆时针方向

将 `clockwise` 设置为 `false`，进度会从逆时针方向开始。

```tsx
<Circle percent={70} clockwise={false} color="#07c160">
  逆时针方向
</Circle>
```

### 大小定制

通过 `size` 属性设置圆环直径。

```tsx
<Circle percent={70} size={120} color="#7232dd">
  大小定制
</Circle>
```

## API

### Props

| 参数            | 说明                                        | 类型                 | 默认值       |
| ------------- | ----------------------------------------- | ------------------ | --------- |
| percent       | 当前进度                                      | _number_           | -         |
| size          | 圆环直径，默认单位为 `px`                           | _string_           | `100px`   |
| color         | 进度条颜色，传入对象格式可以定义渐变色                       | _string \| object_ | `#1989fa` |
| layerColor    | 轨道颜色                                      | _string_           | `white`   |
| fill          | 填充颜色                                      | _string_           | `none`    |
| speed         | 动画速度（单位为 rate/s）                          | _number_           | `0`       |
| strokeWidth   | 进度条宽度                                     | _number_           | `40`      |
| strokeLinecap | 进度条端点的形状，可选值为 `sqaure` `butt` `round`     | _string_           | `round`   |
| clockwise     | 是否顺时针增加                                   | _boolean_          | `true`    |
| startPosition | 进度起始位置，可选值为 `left` `right` `top` `bottom` | _string_           | `top`     |
| children      | 文字                                        | _ReactNode_        | -         |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                        | 默认值                       | 描述 |
| ------------------------- | ------------------------- | -- |
| --circle-size             | _100px \* $hd_            | -  |
| --circle-width            | _var(--circle-size)_      | -  |
| --circle-height           | _var(--circle-size)_      | -  |
| --circle-color            | _var(--primary-color)_    | -  |
| --circle-hover-stroke     | _var(--circle-color)_     | -  |
| --circle-layer-stroke     | _var(--white)_            | -  |
| --circle-text-padding     | _0 var(--padding-base)_   | -  |
| --circle-text-color       | _var(--text-color)_       | -  |
| --circle-text-font-weight | _var(--font-weight-bold)_ | -  |
| --circle-text-font-size   | _var(--font-size-md)_     | -  |
| --circle-text-line-height | _var(--line-height-md)_   | -  |



---
url: https://taroify.com/components/collapse/index.md
---

# Collapse 折叠面板

### 介绍

将一组内容放置在多个折叠面板中，点击面板的标题可以展开或收缩其内容。

### 引入

```tsx
import { Collapse } from "@taroify/core"
```

## 代码演示

### 基础用法

通过 `value` 控制展开的面板列表，`value` 为数组格式。

```tsx
function BasicCollapse() {
  const [value, setValue] = useState([0])
  return (
    <Collapse value={value} onChange={setValue}>
      <Collapse.Item title="标题1">代码是写出来给人看的，附带能在机器上运行</Collapse.Item>
      <Collapse.Item title="标题2">代码是写出来给人看的，附带能在机器上运行</Collapse.Item>
      <Collapse.Item title="标题3">代码是写出来给人看的，附带能在机器上运行</Collapse.Item>
    </Collapse>
  )
}
```

### 手风琴

通过 `accordion` 可以设置为手风琴模式，最多展开一个面板，此时 `value` 为字符串格式。

```tsx
function AccordionCollapse() {
  const [value, setValue] = useState(0)
  return (
    <Collapse accordion value={value} onChange={setValue}>
      <Collapse.Item title="标题1">代码是写出来给人看的，附带能在机器上运行</Collapse.Item>
      <Collapse.Item title="标题2">代码是写出来给人看的，附带能在机器上运行</Collapse.Item>
      <Collapse.Item title="标题3">代码是写出来给人看的，附带能在机器上运行</Collapse.Item>
    </Collapse>
  )
}
```

### 只读状态和禁用状态

通过 `clickable=false` 属性禁止显示反馈动画，通过 `disabled` 属性来禁用单个面板。

```tsx
function CollapseWithDisabledWithReadonly() {
  return (
    <Collapse defaultValue={[0]}>
      <Collapse.Item title="正常状态">代码是写出来给人看的，附带能在机器上运行</Collapse.Item>
      <Collapse.Item title="只读状态" clickable={false}>
        代码是写出来给人看的，附带能在机器上运行
      </Collapse.Item>
      <Collapse.Item title="禁用状态" disabled>
        代码是写出来给人看的，附带能在机器上运行
      </Collapse.Item>
    </Collapse>
  )
}
```

### 自定义标题内容

通过 `title` 属性可以自定义标题栏的内容。

```tsx
function CustomCollapse() {
  return (
    <Collapse defaultValue={[0]}>
      <Collapse.Item
        className="custom-collapse-item1"
        title={
          <>
            标题1
            <QuestionOutlined />
          </>
        }
      >
        代码是写出来给人看的，附带能在机器上运行
      </Collapse.Item>
      <Collapse.Item icon={<ShopOutlined />} title="标题2" extra="内容" clickable={false}>
        代码是写出来给人看的，附带能在机器上运行
      </Collapse.Item>
    </Collapse>
  )
}
```

## API

### Collapse Props

| 参数           | 说明            | 类型                                                         | 默认值     |
| ------------ | ------------- | ---------------------------------------------------------- | ------- |
| defaultValue | 默认展开面板的 value | 手风琴模式：_number \| string_<br>非手风琴模式：_(number \| string)\[]_ | -       |
| value        | 当前展开面板的 value | 手风琴模式：_number \| string_<br>非手风琴模式：_(number \| string)\[]_ | -       |
| accordion    | 是否开启手风琴模式     | _boolean_                                                  | `false` |
| bordered     | 是否显示外边框       | _boolean_                                                  | `true`  |

### Collapse Events

| 事件名      | 说明      | 回调参数         |
| -------- | ------- | ------------ |
| onChange | 切换面板时触发 | _value: any_ |

### Collapse.Item Props

| 参数         | 说明                                                        | 类型                 | 默认值     |
| ---------- | --------------------------------------------------------- | ------------------ | ------- |
| value      | 唯一标识符，默认为索引值                                              | _number \| string_ | `index` |
| icon       | 标题栏左侧[图标](/components/icon.md)或[图片](/components/image.md) | _ReactNode_        | -       |
| expandIcon | 标题栏右侧[图标](/components/icon.md)或[图片](/components/image.md) | _ReactNode_        | -       |
| size       | 标题栏大小，可选值为 `large`                                        | _string_           | -       |
| title      | 标题栏左侧内容                                                   | _number \| string_ | -       |
| extra      | 标题栏右侧内容                                                   | _number \| string_ | -       |
| brief      | 标题栏描述信息                                                   | _number \| string_ | -       |
| bordered   | 是否显示内边框                                                   | _boolean_          | `true`  |
| clickable  | 是否开启点击反馈                                                  | _boolean_          | `true`  |
| disabled   | 是否禁用面板                                                    | _boolean_          | `false` |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                       | 默认值                                   | 描述 |
| ---------------------------------------- | ------------------------------------- | -- |
| --collapse-item-title-disabled-color     | _var(--gray-5)_                       | -  |
| --collapse-item-transition-duration      | _var(--animation-duration-base)_      | -  |
| --collapse-item-content-padding          | _var(--padding-sm) var(--padding-md)_ | -  |
| --collapse-item-content-font-size        | _var(--font-size-md)_                 | -  |
| --collapse-item-content-line-height      | _1.5_                                 | -  |
| --collapse-item-content-color            | _var(--gray-6)_                       | -  |
| --collapse-item-content-background-color | _var(--white)_                        | -  |



---
url: https://taroify.com/components/countdown/index.md
---

# Countdown 倒计时

### 介绍

用于实时展示倒计时数值，支持毫秒精度。

### 引入

```tsx
import { Countdown } from "@taroify/core"
```

## 代码演示

### 基础用法

`value` 属性表示倒计时总时长，单位为毫秒。

```tsx
<Countdown value={30 * 60 * 60 * 1000} />
```

### 自定义格式

通过 `format` 属性设置倒计时文本的内容。

```tsx
<Countdown value={30 * 60 * 60 * 1000} format="DD 天 HH 时 mm 分 ss 秒" />
```

### 毫秒级渲染

倒计时默认每秒渲染一次，设置 `interval` 属性可以开启毫秒级渲染。

```tsx
<Countdown interval={1} value={30 * 60 * 60 * 1000} format="HH:mm:ss:SS" />
```

### 自定义样式

通过 `children` 自定义倒计时的样式，`current` 对象格式见下方表格。

```tsx
<Countdown value={30 * 60 * 60 * 1000}>
  {(current) => (
    <>
      <View className="block">{current.hours}</View>
      <View className="colon">:</View>
      <View className="block">{current.minutes}</View>
      <View className="colon">:</View>
      <View className="block">{current.seconds}</View>
    </>
  )}
</Countdown>
```

```scss
.colon {
  display: inline-block;
  margin: 0 4px * 2;
  color: #ee0a24;
}

.block {
  display: inline-block;
  width: 22px * 2;
  color: #fff;
  font-size: 12px * 2;
  text-align: center;
  background-color: #ee0a24;
  border-radius: 4px * 2;
}
```

### 手动控制

通过 useCountdown 获取返回值后，可以调用 `start`、`pause`、`stop`、`restart` 方法。

```tsx
function CountdownWithManualControl() {
  const countRef = useRef<CountdownInstance>(null)
  return (
    <>
      <Toast id="toast" />
      <Countdown
        className="manual-control"
        ref={countRef}
        value={30 * 1000}
        format="ss:SSS"
        onComplete={() => Toast.open("倒计时结束")}
      />
      <Grid columns={3} clickable>
        <Grid.Item
          icon={<PlayCircleOutlined />}
          text="开始"
          onClick={() => countRef.current?.start()}
        />
        <Grid.Item
          icon={<PauseCircleOutlined />}
          text="暂停"
          onClick={() => countRef.current?.pause()}
        />
        <Grid.Item icon={<Replay />} text="重置" onClick={() => countRef.current?.restart()} />
      </Grid>
    </>
  )
}
```

## API

### Props

| 参数         | 说明           | 类型                                   | 默认值        |
| ---------- | ------------ | ------------------------------------ | ---------- |
| value      | 倒计时时长，单位毫秒   | _number_                             | `0`        |
| format     | 时间格式         | _string_                             | `HH:mm:ss` |
| autostart  | 是否自动开始倒计时    | _boolean_                            | `true`     |
| interval   | 倒计时渲染间隔，单位毫秒 | _number_                             | `1000`     |
| onChange   | 倒计时变化时触发     | _(currentTime: CurrentTime) => void_ | -          |
| onComplete | 倒计时结束时触发     | _() => void_                         | -          |

### format 格式

| 格式  | 说明      |
| --- | ------- |
| DD  | 天数      |
| HH  | 小时      |
| mm  | 分钟      |
| ss  | 秒数      |
| S   | 毫秒（1 位） |
| SS  | 毫秒（2 位） |
| SSS | 毫秒（3 位） |

### CurrentTime 格式

| 名称           | 说明          | 类型       |
| ------------ | ----------- | -------- |
| total        | 剩余总时间（单位毫秒） | _number_ |
| days         | 剩余天数        | _number_ |
| hours        | 剩余小时        | _number_ |
| minutes      | 剩余分钟        | _number_ |
| seconds      | 剩余秒数        | _number_ |
| milliseconds | 剩余毫秒        | _number_ |

### 方法

通过 ref 可以获取到 Countdown 实例并调用实例方法。

| 方法名     | 说明                                       | 参数 | 返回值 |
| ------- | ---------------------------------------- | -- | --- |
| start   | 开始倒计时                                    | -  | -   |
| pause   | 暂停倒计时                                    | -  | -   |
| reset   | 重设倒计时，若 `autostart` 为 `true`，重设后会自动开始倒计时 | -  | -   |
| restart | 重启倒计时                                    | -  | -   |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                      | 默认值                     | 描述 |
| ----------------------- | ----------------------- | -- |
| --countdown-color       | _var(--text-color)_     | -  |
| --countdown-font-size   | _var(--font-size-md)_   | -  |
| --countdown-line-height | _var(--line-height-md)_ | -  |



---
url: https://taroify.com/components/divider/index.md
---

# Divider 分割线

### 介绍

用于将内容分隔为多个区域。

### 引入

```ts
import { Divider } from "@taroify/core"
```

## 代码演示

### 基础用法

默认渲染一条水平分割线。

```tsx
<Divider />
```

### 展示文字

通过插槽在可以分割线中间插入内容。

```tsx
<Divider>文本</Divider>
```

### 内容位置

通过 `orientation` 指定内容所在位置。

```tsx
<Divider>
  <Divider.Text orientation="left">文字</Divider.Text>
</Divider>
<Divider>
  <Divider.Text orientation="right">文字</Divider.Text>
</Divider>
```

### 虚线

添加 `dashed` 属性使分割线渲染为虚线。

```tsx
<Divider dashed>文本</Divider>
```

### 自定义样式

可以使用 `className` 属性，也可以直接通过 `style` 属性设置分割线的样式。

```tsx
<Divider style={{ color: "#1989fa", borderColor: "#1989fa", padding: "0 16px" }}>
  文本
</Divider>
```

### 垂直

添加 `type` 属性使分割线垂直展示。

```tsx
<Divider type='vertical'>文本</Divider>
<Divider type='vertical' dashed>文本</Divider>
<Divider type='vertical' dashed hairline>文本</Divider>
<Divider type="vertical" style={{ color: "#1989fa", borderColor: "#1989fa" }}>
  文本
</Divider>
```

## API

### Divider Props

| 参数       | 说明           | 类型                       | 默认值          |
| -------- | ------------ | ------------------------ | ------------ |
| dashed   | 是否使用虚线       | _boolean_                | `false`      |
| hairline | 是否使用 0.5px 线 | _boolean_                | `true`       |
| type     | 水平还是垂直类型     | _horizontal \| vertical_ | `horizontal` |

### Divider.Text Props

| 参数          | 说明                       | 类型       | 默认值      |
| ----------- | ------------------------ | -------- | -------- |
| orientation | 内容位置，可选值为 `left` `right` | _string_ | `center` |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                            | 默认值                            | 描述 |
| ----------------------------- | ------------------------------ | -- |
| --divider-margin              | _var(--padding-md) 0_          | -  |
| --divider-vertical-padding    | _0 var(--padding-xs)_          | -  |
| --divider-color               | _var(--gray-6)_                | -  |
| --divider-font-size           | _var(--font-size-md)_          | -  |
| --divider-line-height         | _24px \* $hd_                  | -  |
| --divider-border-color        | _var(--border-color)_          | -  |
| --divider-border-width        | _var(--border-width-base) 0 0_ | -  |
| --divider-content-padding     | _var(--padding-md)_            | -  |
| --divider-content-left-width  | _10%_                          | -  |
| --divider-content-right-width | _10%_                          | -  |



---
url: https://taroify.com/components/empty/index.md
---

# Empty 空状态

### 介绍

空状态时的占位提示。

### 引入

```ts
import { Empty } from "@taroify/core"
```

## 代码演示

### 基础用法

```tsx
<Empty>
  <Empty.Image />
  <Empty.Description>描述文字</Empty.Description>
</Empty>
```

### 图片类型

Empty 组件内置了多种占位图片类型，可以在不同业务场景下使用。

```tsx
<!-- 通用错误 -->
<Empty>
  <Empty.Image src="error" />
  <Empty.Description>描述文字</Empty.Description>
</Empty>
<!-- 网络错误 -->
<Empty>
  <Empty.Image src="network" />
  <Empty.Description>描述文字</Empty.Description>
</Empty>
<!-- 搜索提示 -->
<Empty>
  <Empty.Image src="search" />
  <Empty.Description>描述文字</Empty.Description>
</Empty>
```

### 自定义图片

需要自定义图片时，可以在 image 属性中传入任意图片 URL。

```tsx
<Empty>
  <Empty.Image
    className="custom-empty__image"
    src="https://img.yzcdn.cn/vant/custom-empty-image.png"
  />
  <Empty.Description>描述文字</Empty.Description>
</Empty>
```

```scss
.custom-empty__image {
  width: 90px * 2;
  height: 90px * 2;
}
```

### 底部内容

通过默认插槽可以在 Empty 组件的下方插入内容。

```tsx
<Empty>
  <Empty.Image />
  <Empty.Description>描述文字</Empty.Description>
  <Button shape="round" color="danger" className="bottom-button">
    按钮
  </Button>
</Empty>
```

```scss
.bottom-button {
  margin-top: 24px * 2;
  width: 160px * 2;
  height: 40px * 2;
}
```

## API

### Empty Props

| 参数       | 说明 | 类型          | 默认值 |
| -------- | -- | ----------- | --- |
| children | 内容 | _ReactNode_ | -   |

### Empty.Image Props

| 参数    | 说明                                              | 类型              | 默认值       |
| ----- | ----------------------------------------------- | --------------- | --------- |
| style | 图片样式                                            | _CSSProperties_ | -         |
| src   | 图片类型，可选值为 `error` `network` `search`，支持传入图片 URL | _string_        | `default` |

### Empty.Description Props

| 参数       | 说明        | 类型          | 默认值 |
| -------- | --------- | ----------- | --- |
| children | 图片下方的描述文字 | _ReactNode_ | -   |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                              | 默认值                       | 描述 |
| ------------------------------- | ------------------------- | -- |
| --empty-padding                 | _var(--padding-xl) 0_     | -  |
| --empty-image-size              | _160px \* $hd_            | -  |
| --empty-image-width             | _var(--empty-image-size)_ | -  |
| --empty-image-height            | _var(--empty-image-size)_ | -  |
| --empty-description-margin-top  | _var(--padding-md)_       | -  |
| --empty-description-padding     | _0 60px \* $hd_           | -  |
| --empty-description-color       | _var(--gray-6)_           | -  |
| --empty-description-font-size   | _var(--font-size-md)_     | -  |
| --empty-description-line-height | _var(--line-height-md)_   | -  |



---
url: https://taroify.com/components/notice-bar/index.md
---

# NoticeBar 通知栏

### 介绍

用于循环播放展示一组消息通知。

### 引入

```tsx
import { NoticeBar } from "@taroify/core"
```

## 代码演示

### 基础用法

通过 `children` 属性设置通知栏的内容，通过 `NoticeBar.Icon` 组件设置通知栏左侧的图标。

```tsx
<NoticeBar scrollable>
  <NoticeBar.Icon>
    <VolumeOutlined />
  </NoticeBar.Icon>
  在代码阅读过程中人们说脏话的频率是衡量代码质量的唯一标准。
</NoticeBar>
```

### 滚动播放

通知栏的内容长度溢出时会自动开启滚动播放，通过 `scrollable` 属性可以控制该行为。

```tsx
<!-- 文字较短时，通过设置 scrollable 属性开启滚动播放 -->
<van-notice-bar scrollable text="技术是开发它的人的共同灵魂。" />
<NoticeBar scrollable>技术是开发它的人的共同灵魂。</NoticeBar>
<!-- 文字较长时，通过禁用 scrollable 属性关闭滚动播放 -->
<NoticeBar scrollable={false}>
  在代码阅读过程中人们说脏话的频率是衡量代码质量的唯一标准。
</NoticeBar>
```

### 多行展示

文字较长时，可以通过设置 `wordwrap` 属性来开启多行展示。

```tsx
<NoticeBar wordwrap scrollable={false}>
  在代码阅读过程中人们说脏话的频率是衡量代码质量的唯一标准。
</NoticeBar>
```

### 通知栏模式

通过 `NoticeBar.Action` 组件可以显示不同的通知栏模式。

```tsx
<NoticeBar scrollable={false}>
  技术是开发它的人的共同灵魂。
  <NoticeBar.Action>
    <Cross />
  </NoticeBar.Action>
</NoticeBar>
<WhiteSpace />
<NoticeBar scrollable={false}>
  技术是开发它的人的共同灵魂。
  <NoticeBar.Action>
    <ArrowRight />
  </NoticeBar.Action>
</NoticeBar>
```

### 自定义样式

通过 `style` 属性设置文本颜色和背景色。

```tsx
<NoticeBar style={{ color: "#1989fa", background: "#ecf9ff" }}>
  <NoticeBar.Icon>
    <InfoOutlined />
  </NoticeBar.Icon>
  技术是开发它的人的共同灵魂。
</NoticeBar>
```

### 垂直滚动

搭配 NoticeBar 和 Swiper 组件可以实现垂直滚动的效果。

```tsx
<NoticeBar>
  <NoticeBar.Icon>
    <VolumeOutlined />
  </NoticeBar.Icon>
  <Swiper className="notice-swiper" direction="vertical" autoplay={3000}>
    <Swiper.Item>内容 1</Swiper.Item>
    <Swiper.Item>内容 2</Swiper.Item>
    <Swiper.Item>内容 3</Swiper.Item>
  </Swiper>
</NoticeBar>
```

```scss
.notice-swiper {
  height: 40px * 2;
  line-height: 40px * 2;
}
```

## API

### Props

| 参数         | 说明                   | 类型                 | 默认值     |
| ---------- | -------------------- | ------------------ | ------- |
| className  | 通知栏自定义类名             | _string_           | -       |
| style      | 通知栏自定义样式             | _CSSProperties_    | -       |
| children   | 通知文本内容               | _ReactNode_        | -       |
| delay      | 动画延迟时间 (ms)          | _number \| string_ | `1000`  |
| speed      | 滚动速率 (px/s)          | _number \| string_ | `60`    |
| scrollable | 是否开启滚动播放，内容长度溢出时默认开启 | _boolean_          | `false` |
| wordwrap   | 是否开启文本换行，只在禁用滚动时生效   | _boolean_          | `false` |

### Events

| 事件名      | 说明             | 回调参数                |
| -------- | -------------- | ------------------- |
| onClick  | 点击通知栏时触发       | _event: MouseEvent_ |
| onReplay | 每当滚动栏重新开始滚动时触发 | -                   |

### 方法

通过 ref 可以获取到 NoticeBar 实例并调用实例方法

| 方法名   | 说明         | 参数 | 返回值 |
| ----- | ---------- | -- | --- |
| reset | 重置通知栏到初始状态 | -  | -   |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                            | 默认值                                   | 描述 |
| ----------------------------- | ------------------------------------- | -- |
| --notice-bar-height           | _40px \* $hd_                         | -  |
| --notice-bar-padding          | _0 var(--padding-md)_                 | -  |
| --notice-bar-wordwrap-padding | _var(--padding-xs) var(--padding-md)_ | -  |
| --notice-bar-color            | _var(--orange-dark)_                  | -  |
| --notice-bar-font-size        | _var(--font-size-md)_                 | -  |
| --notice-bar-line-height      | _24px \* $hd_                         | -  |
| --notice-bar-background-color | _var(--orange-light)_                 | -  |
| --notice-bar-icon-size        | _16px \* $hd_                         | -  |
| --notice-bar-icon-min-width   | _24px \* $hd_                         | -  |



---
url: https://taroify.com/components/list/index.md
---

# List 列表

### 介绍

瀑布流滚动加载，用于展示长列表，当列表即将滚动到底部时，会触发事件并加载更多列表项。

### 引入

```tsx
import { List } from "@taroify/core"
```

## 代码演示

### 基础用法

List 组件通过 `loading` 和 `hasMore` 两个变量控制加载状态，当组件滚动到底部时，会触发 `load` 事件并将 `loading` 设置成 `true`
。此时可以发起异步操作并更新数据，数据更新完毕后，将 `loading` 设置成 `false` 即可。若数据已全部加载完毕，则直接将 `hasMore` 设置成 `false` 即可。

```tsx
function BasicList() {
  const [hasMore, setHasMore] = useState(true)
  const [list, setList] = useState<string[]>([])
  const [loading, setLoading] = useState(false)
  return (
    <List
      loading={loading}
      hasMore={hasMore}
      onLoad={() => {
        setLoading(true)
        setTimeout(() => {
          for (let i = 0; i < 10; i++) {
            const text = list.length + 1
            list.push(text < 10 ? "0" + text : String(text))
          }
          setList([...list])
          setHasMore(list.length < 40)
          setLoading(false)
        }, 1000)
      }}
    >
      {
        //
        list.map((item) => (
          <Cell key={item}>{item}</Cell>
        ))
      }
      <List.Placeholder>
        {loading && <Loading>加载中...</Loading>}
        {!hasMore && "没有更多了"}
      </List.Placeholder>
    </List>
  )
}
```

> Tips: 在 Tabs 里使用，通过设置 `disabled={tabKey !== activeTabKey}`，避免其他 tab 里的 List 也触发了滑动

### 固定高度

设置 fixedHeight，通过 class 或者 style 指定容器高度

```tsx
function FixedHeightList() {
  const [hasMore, setHasMore] = useState(true)
  const [list, setList] = useState<string[]>([])
  const [loading, setLoading] = useState(false)
  const ref = useRef<ListInstance>(null)

  return (
    <>
      <List
        ref={ref}
        loading={loading}
        hasMore={hasMore}
        fixedHeight
        style={{ height: "300px" }}
        onLoad={() => {
          setLoading(true)
          setTimeout(() => {
            for (let i = 0; i < 10; i++) {
              const text = list.length + 1
              list.push(text < 10 ? "0" + text : String(text))
            }
            setList([...list])
            setHasMore(list.length < 40)
            setLoading(false)
          }, 1000)
        }}
      >
        {
          //
          list.map((item) => (
            <Cell key={item}>{item}</Cell>
          ))
        }
        <List.Placeholder>
          {loading && <Loading>加载中...</Loading>}
          {!hasMore && "没有更多了"}
        </List.Placeholder>
      </List>
    </>
  )
}
```

### 错误提示

若列表数据加载失败，将 `error` 设置成 `true` 即可显示错误提示，用户点击错误提示后会重新触发 load 事件。

```tsx
function ErrorList() {
  const [hasMore, setHasMore] = useState(true)
  const [list, setList] = useState<string[]>([])
  const [loading, setLoading] = useState(false)
  const [error, setError] = useState(false)

  return (
    <List
      loading={loading}
      hasMore={hasMore}
      onLoad={() => {
        setLoading(true)
        setTimeout(() => {
          for (let i = 0; i < 10; i++) {
            const text = list.length + 1
            list.push(text < 10 ? "0" + text : String(text))
          }
          const newList = [...list]

          setHasMore(!(newList.length <= 10 || newList.length >= 40))
          setError(newList.length <= 10)
          setList(newList)
          setLoading(false)
        }, 1000)
      }}
    >
      {list.map((item) => (
        <Cell key={item}>{item}</Cell>
      ))}
      <List.Placeholder
        onClick={() => {
          if (error) {
            setHasMore(true)
            setError(false)
          }
        }}
      >
        {loading && <Loading>加载中...</Loading>}
        {error && "请求失败，点击重新加载"}
        {!error && !hasMore && "没有更多了"}
      </List.Placeholder>
    </List>
  )
}
```

### 下拉刷新

List 组件可以与 [PullRefresh](/components/pull-refresh/index.md) 组件结合使用，实现下拉刷新的效果。

```tsx
function PullRefreshList() {
  const [hasMore, setHasMore] = useState(true)
  const [list, setList] = useState<string[]>([])
  const [loading, setLoading] = useState(false)
  const refreshingRef = useRef(false)
  const [reachTop, setReachTop] = useState(true)

  usePageScroll(({ scrollTop: aScrollTop }) => {
    setReachTop(aScrollTop === 0)
  })

  const onLoad = () => {
    setLoading(true)
    const newList = refreshingRef.current ? [] : list
    setTimeout(() => {
      refreshingRef.current = false
      for (let i = 0; i < 10; i++) {
        const text = newList.length + 1
        newList.push(text < 10 ? "0" + text : String(text))
      }
      setList(newList)
      setLoading(false)
      setHasMore(newList.length < 40)
    }, 1000)
  }

  function onRefresh() {
    refreshingRef.current = true
    setLoading(false)
    onLoad()
  }

  return (
    <List loading={loading} hasMore={hasMore} onLoad={onLoad}>
      <PullRefresh loading={refreshingRef.current} reachTop={reachTop} onRefresh={onRefresh}>
        {list.map((item) => (
          <Cell key={item}>{item}</Cell>
        ))}
        {!refreshingRef.current && (
          <List.Placeholder>
            {loading && <Loading>加载中...</Loading>}
            {!hasMore && "没有更多了"}
          </List.Placeholder>
        )}
      </PullRefresh>
    </List>
  )
}
```

#### 固定高度

固定高度的 List 使用 ScrollView 作为滚动容器。将 `PullRefresh` 放在 List 外层，并开启
`pullRefresh`，List 会根据滚动位置自动判断是否到达顶部，无需手动维护 `reachTop`。

```tsx
function FixedHeightPullRefreshList() {
  const [refreshing, setRefreshing] = useState(false)

  return (
    <PullRefresh
      loading={refreshing}
      onRefresh={() => {
        setRefreshing(true)
        setTimeout(() => setRefreshing(false), 1000)
      }}
    >
      <List fixedHeight pullRefresh style={{ height: 300 }}>
        {list.map((item) => (
          <Cell key={item}>{item}</Cell>
        ))}
      </List>
    </PullRefresh>
  )
}
```

如果显式设置了 `PullRefresh` 的 `reachTop`，仍以该值为准。

## API

### Props

| 参数                               | 说明                                | 类型        | 默认值     |
| -------------------------------- | --------------------------------- | --------- | ------- |
| fixedHeight                      | 是否固定高度                            | _boolean_ | `false` |
| pullRefresh <Tag tag="v1.0.0" /> | 固定高度时自动同步下拉刷新的顶部状态                | _boolean_ | `false` |
| loading                          | 是否处于加载状态，加载过程中不触发 `onLoad` 事件     | _boolean_ | `false` |
| hasMore                          | 是否已加载完成，加载完成后不再触发 `onLoad` 事件     | _boolean_ | `false` |
| offset                           | 滚动条与底部距离小于 offset 时触发 `onLoad` 事件 | _number_  | `100`   |
| immediateCheck                   | 是否在初始化时立即执行滚动位置检查                 | _boolean_ | `true`  |
| disabled                         | 是否禁用滚动加载                          | _boolean_ | `false` |
| direction                        | 滚动触发加载的方向，可选值为 `up`               | _string_  | `down`  |
| ~~scrollTop~~                    | 距离顶部的滚动距离                         | _number_  | `0`     |

### Events

| 事件名           | 说明                    | 回调参数 |
| ------------- | --------------------- | ---- |
| onLoad        | 滚动条与底部距离小于 offset 时触发 | -    |
| ~~onLoading~~ | 内部 loading 改变时触发      | -    |
| onScroll      | 滚动时触发                 | e    |

### 方法

通过 ref 可以获取到 List 实例并调用实例方法

| 方法名   | 说明                             | 参数 | 返回值 |
| ----- | ------------------------------ | -- | --- |
| check | 检查当前的滚动位置，若已滚动至底部，则会触发 load 事件 | -  | -   |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                         | 默认值                             | 描述 |
| -------------------------- | ------------------------------- | -- |
| --list-text-color          | _var(--gray-6)_                 | -  |
| --list-text-font-size      | _var(--font-size-md)_           | -  |
| --list-text-line-height    | _50px \* $hd_                   | -  |
| --list-loading-icon-size   | _16px \* $hd_                   | -  |
| --list-loading-icon-width  | _var(--list-loading-icon-size)_ | -  |
| --list-loading-icon-height | _var(--list-loading-icon-size)_ | -  |

## 常见问题

### List 的运行机制是什么？

- 当设置 fixedHeight 为 false 时会监听页面滚动事件(usePageScroll)
- 当设置 fixedHeight 为 true 时会监听滚动容器的滚动事件(onScroll)
  当列表底部与可视区域的距离小于 `offset` 时，List 会触发一次 load 事件。

### 为什么 List 初始化后会立即触发 load 事件？

List 初始化后会触发一次 load 事件，用于加载第一屏的数据，这个特性可以通过 `hasMore={false}` 属性关闭。

### 为什么会连续触发 load 事件？

如果一次请求加载的数据条数较少，导致列表内容无法铺满当前屏幕，List 会继续触发 load 事件，直到内容铺满屏幕或数据全部加载完成。因此你需要调整每次获取的数据条数，理想情况下每次请求获取的数据条数应能够填满一屏高度。

### loading 和 hasMore 分别是什么含义？

`List` 有以下三种状态，理解这些状态有助于你正确地使用 `List` 组件：

- 非加载中，`loading` 为 `false`，此时会根据列表滚动位置判断是否触发 `onLoad` 事件（列表内容不足一屏幕时，会直接触发）
- 加载中，`loading` 为 `true`，表示正在发送异步请求，此时不会触发 `onLoad` 事件
- 加载完成，`hasMore` 为 `false`，此时不会触发 `onLoad` 事件

在每次请求完毕后，需要手动将 `loading` 设置为 `false`，表示加载结束

### 使用 float 布局后一直触发加载？

若 List 的内容使用了 float 布局，可以在容器上添加 `taroify-clearfix` 类名来清除浮动，使得 List 能正确判断元素位置

```tsx
<List>
  <View class="taroify-clearfix">
    <View class="float-item" />
    <View class="float-item" />
    <View class="float-item" />
  </View>
</List>
```

### 在 html、body 上设置 overflow 后一直触发加载？

如果在 html 和 body 标签上设置了 `overflow-x: hidden` 样式，会导致 List 一直触发加载。

```css
html,
body {
  overflow-x: hidden;
}
```

这个问题的原因是当元素设置了 `overflow-x: hidden` 样式时，该元素的 `overflow-y` 会被浏览器设置为 `auto`，而不是默认值 `visible`，导致 List
无法正确地判断滚动容器。解决方法是去除该样式，或者在 html 和 body 标签上添加 `height: 100%` 样式。

### direction 属性设置为 up 后一直触发加载？

设置 `direction` 属性为 up 后，当滚动条处于页面顶部时，就会触发 List 组件的加载。

因此在使用该属性时，建议在每次数据加载完成后，将滚动条滚动至页面底部或非顶部的位置。



---
url: https://taroify.com/components/progress/index.md
---

# Progress 进度条

### 介绍

用于展示操作的当前进度。

### 引入

```tsx
import { Progress } from "@taroify/core"
```

## 代码演示

### 基础用法

进度条默认为蓝色，使用 `percentage` 属性来设置当前进度。

```tsx
<Progress percent={50} />
```

### 线条粗细

通过 `stroke-width` 可以设置进度条的粗细。

```tsx
<Progress percent={50} strokeWidth={8} />
```

### 置灰

设置 `inactive` 属性后进度条将置灰。

```tsx
<Progress percent={50} inactive />
```

### 样式定制

可以使用 `pivot-text` 属性自定义文字，`color` 属性自定义进度条颜色。

```tsx
<Progress className="custom-color1" percent={25} />
<Progress className="custom-color2" percent={50} />
<Progress className="custom-color3" percent={75} />
```

```scss
.custom-color1 {
  &:not(.taroify-progress--inactive) {
    .taroify-progress__portion {
      background: #f2826a;
    }
  }
}

.custom-color2 {
  &:not(.taroify-progress--inactive) {
    .taroify-progress__portion {
      background: #ee0a24;
    }
  }
}

.custom-color3 {
  &:not(.taroify-progress--inactive) {
    .taroify-progress__portion {
      background: linear-gradient(to right, #be99ff, #7232dd) _ | - |;
    }
  }
}
```

## API

### Props

| 参数          | 说明              | 类型                     | 默认值       |
| ----------- | --------------- | ---------------------- | --------- |
| percent     | 进度百分比           | _number \| string_     | `0`       |
| strokeWidth | 进度条粗细，默认单位为`px` | _number \| string_     | `4px`     |
| color       | 进度条颜色           | _string_               | `primary` |
| inactive    | 是否置灰            | _boolean_              | `false`   |
| label       | 进度文字            | _boolean \| ReactNode_ | `true`    |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                          | 默认值                      | 描述 |
| ------------------------------------------- | ------------------------ | -- |
| --progress-height                           | _14px \* $hd_            | -  |
| --progress-border-radius                    | _var(--progress-height)_ | -  |
| --progress-background-color                 | _var(--gray-3)_          | -  |
| --progress-portion-color                    | _var(--white)_           | -  |
| --progress-portion-font-size                | _var(--font-size-xs)_    | -  |
| --progress-inactive-background-color        | _#cacaca_                | -  |
| --progress-portion-primary-background-color | _var(--primary-color)_   | -  |
| --progress-portion-info-background-color    | _var(--info-color)_      | -  |
| --progress-portion-success-background-color | _var(--success-color)_   | -  |
| --progress-portion-warning-background-color | _var(--warning-color)_   | -  |
| --progress-portion-danger-background-color  | _var(--danger-color)_    | -  |



---
url: https://taroify.com/components/rolling-text/index.md
---

# RollingText 翻滚文本动效

### 介绍

文本翻滚动效，可以翻滚数字和其他类型文本。

请升级 `taroify` 到 >= `v0.1.0-alpha.6` 版本来使用该组件。

### 引入

```tsx
import { RollingText } from "@taroify/core"
```

## 代码演示

### 基础用法

你可以通过 `startNum` 设置起始数值，`targetNum` 设置目标数值。RollingText 组件会自动开始动画，从起始数值翻滚到目标数值。

```tsx
<RollingText startNum={0} targetNum={123} />
```

### 设置翻滚方向

你可以通过 `direction` 属性设置数字的翻滚方向，默认为向下翻滚，设置为 `up` 即可向上翻滚。

```tsx
<RollingText startNum={0} targetNum={432} direction="up" />
```

### 设置各数位停止顺序

你可以通过 `stopOrder` 属性设置动画各个数位的停止先后顺序。默认先停止高位，设置为 `rtl` 可以先从个位停止。

```tsx
<RollingText startNum={0} targetNum={54321} stopOrder="rtl" />
```

### 翻转非数字内容

你可以使用 `textList` 属性设置非数字内容的翻转。组件会从数组的第一项翻转到最后一项，请确保数组长度大于等于 2，以及每一项的长度一致。

```javascript
const textList = ["aaaaa", "bbbbb", "ccccc", "ddddd", "eeeee", "fffff", "ggggg"]
```

```tsx
<RollingText textList={textList} duration={1} />
```

### 自定义样式

RollingText 组件提供了一些 CSS 变量，你可以覆盖这些变量来自定义样式，也可以直接修改组件的样式。此外，你还可以通过 `height` 属性设置数字高度。

```tsx
<RollingText className="my-rolling-text" height={54} startNum={12345} targetNum={54321} />
```

```css
.my-rolling-text {
  --rolling-text-background: #1989fa;
  --rolling-text-color: white;
  --rolling-text-font-size: 48px;
  --rolling-text-gap: 12px;
  --rolling-text-item-border-radius: 10px;
  --rolling-text-item-width: 80px;
}
```

### 手动控制

通过 ref 获取到组件实例后，你可以调用 `start`、`reset` 方法，`start` 方法用于开始动画，`reset` 方法用于重置动画。

```tsx
import { useRef } from "react"
import { View } from "@tarojs/components"
import { RollingText, Button } from "@taroify/core"
import type { RollingTextRef } from "@taroify/core/rolling-text"

function HandRollingText() {
  const ref = useRef<RollingTextRef>()

  const start = () => {
    ref.current?.start()
  }

  const reset = () => {
    ref.current?.reset()
  }

  return (
    <View>
      <RollingText
        ref={ref}
        className="my-rolling-text"
        height={54}
        startNum={0}
        targetNum={54321}
        autoStart={false}
      />
      <View className="rolling-text-btn">
        <Button color="primary" onClick={start}>
          开始
        </Button>
        <Button color="primary" className="rolling-text-right" onClick={reset}>
          重置
        </Button>
      </View>
    </View>
  )
}
```

## API

### Props

| 参数        | 说明                            | 类型          | 默认值    |
| :-------- | ----------------------------- | ----------- | ------ |
| startNum  | 起始数值                          | _number_    | `0`    |
| targetNum | 目标数值                          | _number_    | `-`    |
| textList  | 内容数组，用于翻转非数字内                 | _string\[]_ | `[]`   |
| duration  | 动画时长，单位为秒                     | _number_    | `2`    |
| direction | 文本翻滚方向，值为 `down` 和 `up`       | _string_    | `down` |
| autoStart | 是否自动开始动画                      | _boolean_   | `true` |
| stopOrder | 各个数位动画停止先后顺序，值为 `ltr` 和 `rtl` | _string_    | `ltr`  |
| height    | 数字高度，单位为 `px`                 | _number_    | `40`   |

### 方法

通过 `ref` 可以获取到 RollingText 实例并调用实例方法

| 方法名   | 说明   | 参数 | 返回值 |
| :---- | ---- | -- | --- |
| start | 开始动画 | \_ | -   |
| reset | 重置动画 | \_ | -   |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                | 默认值       | 描述       |
| --------------------------------- | --------- | -------- |
| --rolling-text-background         | _inherit_ | 单个数位背景色  |
| --rolling-text-color              | _#323233_ | 数字颜色     |
| --rolling-text-font-size          | _28px_    | 字体大小     |
| --rolling-text-gap                | _0px_     | 数位之间的间隔  |
| --rolling-text-item-width         | _30px_    | 单个数位宽度   |
| --rolling-text-item-border-radius | _0px_     | 单个数位边框圆角 |



---
url: https://taroify.com/components/skeleton/index.md
---

# Skeleton 骨架屏

### 介绍

用于在内容加载过程中展示一组占位图形。

### 引入

```tsx
import { Skeleton } from "@taroify/core"
```

## 代码演示

### 基础用法

通过 `title` 属性显示标题占位图，通过 `row` 属性配置占位段落行数。

```tsx
<Skeleton title row={3} />
```

### 显示头像

通过 `avatar` 属性显示头像占位图。

```tsx
<Skeleton title avatar row={3} />
```

### 展示子组件

将 `loading` 属性设置成 `false` 表示内容加载完成，此时会隐藏占位图，并显示 `Skeleton` 的子组件。

```tsx
<Skeleton title avatar row={3} loading={loading}>
  <View>实际内容</View>
</Skeleton>
```

### 自定义展示内容

通过 `template` 属性完成自定义内容的展示。

```tsx
const template = () => {
  return (
    <View
      style={{ display: "flex", width: "100%" }}
    >
      <Skeleton.Image />
      <View
        style={{ flex: 1, marginLeft: 16 }}
      >
        <Skeleton.Paragraph rowWidth="60%" />
        <Skeleton.Paragraph />
        <Skeleton.Paragraph />
        <Skeleton.Paragraph />
        <Skeleton.Paragraph />
        <Skeleton.Paragraph />
      </View>
    </View>
  )
}

<Skeleton template={template}/>
```

## API

### Props

| 参数          | 说明                          | 类型                                          | 默认值     |
| ----------- | --------------------------- | ------------------------------------------- | ------- |
| row         | 段落占位图行数                     | _number \| string_                          | `0`     |
| rowWidth    | 段落占位图宽度，可传数组来设置每一行的宽度       | _number \| string \| (number \| string)\[]_ | `100%`  |
| title       | 是否显示标题占位图                   | _boolean_                                   | `false` |
| avatar      | 是否显示头像占位图                   | _boolean_                                   | `false` |
| loading     | 是否显示骨架屏，传 `false` 时会展示子组件内容 | _boolean_                                   | `true`  |
| animate     | 是否开启动画                      | _boolean_                                   | `true`  |
| round       | 是否将标题和段落显示为圆角风格             | _boolean_                                   | `false` |
| titleWidth  | 标题占位图宽度                     | _number \| string_                          | `40%`   |
| avatarSize  | 头像占位图大小                     | _number \| string_                          | `32px`  |
| avatarShape | 头像占位图形状，可选值为 `square`       | _square \| round_                           | `round` |
| template    | 骨架屏自定义                      | _ReactNode_                                 | `-`     |

### Skeleton.Paragraph Props

| 参数       | 说明           | 类型                 | 默认值     |
| -------- | ------------ | ------------------ | ------- |
| round    | 是否将段落显示为圆角风格 | _boolean_          | `false` |
| rowWidth | 段落占位图宽度      | _number \| string_ | `100%`  |

### Skeleton.Title Props

| 参数         | 说明           | 类型                 | 默认值     |
| ---------- | ------------ | ------------------ | ------- |
| round      | 是否将段落显示为圆角风格 | _boolean_          | `false` |
| titleWidth | 标题占位图宽度      | _number \| string_ | `100%`  |

### Skeleton.Avatar Props

| 参数          | 说明                    | 类型                 | 默认值     |
| ----------- | --------------------- | ------------------ | ------- |
| avatarSize  | 头像占位图大小               | _number \| string_ | `32px`  |
| avatarShape | 头像占位图形状，可选值为 `square` | _square \| round_  | `round` |

### Skeleton.Image Props

| 参数         | 说明                    | 类型                 | 默认值     |
| ---------- | --------------------- | ------------------ | ------- |
| imageSize  | 图片占位图大小               | _number \| string_ | `32px`  |
| imageShape | 图片占位图形状，可选值为 `square` | _square \| round_  | `round` |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                              | 默认值                   | 描述 |
| ------------------------------- | --------------------- | -- |
| --skeleton-avatar-size          | _32px \* $hd_         | -  |
| --skeleton-avatar-background    | _var(--active-color)_ | -  |
| --skeleton-duration             | _1.2s_                | -  |
| --skeleton-paragraph-height     | _16px \* $hd_         | -  |
| --skeleton-paragraph-background | _var(--active-color)_ | -  |
| --skeleton-title-width          | _40%_                 | -  |
| --skeleton-paragraph-margin-top | _var(--padding-xs)_   | -  |
| --skeleton-image-size           | _96px \* $hd_         | -  |
| --skeleton-image-radius         | _24px \* $hd_         | -  |



---
url: https://taroify.com/components/steps/index.md
---

# Steps 步骤条

### 介绍

用于展示操作流程的各个环节，让用户了解当前的操作在整体流程中的位置。

### 引入

```tsx
import { Steps } from "@taroify/core"
```

## 代码演示

### 基础用法

`value` 属性表示当前步骤的索引，从 0 起计。

```tsx
<Steps value={0}>
  <Steps.Step>买家下单</Steps.Step>
  <Steps.Step>商家接单</Steps.Step>
  <Steps.Step>买家提货</Steps.Step>
  <Steps.Step>交易完成</Steps.Step>
</Steps>
```

### 下方标签

可以通过 alternativeLabel 属性来设置下方标签展示方式

```tsx
<Steps defaultValue={0} alternativeLabel>
  <Steps.Step>买家下单</Steps.Step>
  <Steps.Step>商家接单</Steps.Step>
  <Steps.Step>买家提货</Steps.Step>
  <Steps.Step>交易完成</Steps.Step>
</Steps>
```

### 自定义样式

可以通过 `css` 设置激活状态下的颜色。

```tsx
<Steps className="custom-color" defaultValue={0}>
  <Steps.Step icon={<ArrowRight />}>买家下单</Steps.Step>
  <Steps.Step icon={<ArrowRight />}>商家接单</Steps.Step>
  <Steps.Step icon={<ArrowRight />}>买家提货</Steps.Step>
  <Steps.Step icon={<ArrowRight />}>交易完成</Steps.Step>
</Steps>
```

```scss
.custom-color {
  .taroify-step--completed {
    .taroify-step__icon {
      color: #38f;
    }

    .taroify-step__line,
    .taroify-step__circle {
      background-color: #38f;
    }
  }

  .taroify-step--active {
    .taroify-step__label,
    .taroify-step__icon {
      color: #38f;
    }

    .taroify-step__circle {
      background-color: #38f;
    }
  }
}
```

### 竖向步骤条

可以通过设置 `direction` 属性来改变步骤条的显示方向。

```tsx
<Steps defaultValue={0} direction="vertical">
  <Steps.Step>
    <View>【城市】物流状态2</View>
    <View>2016-07-12 12:40</View>
  </Steps.Step>
  <Steps.Step>
    <View>【城市】物流状态1</View>
    <View>2016-07-11 10:00</View>
  </Steps.Step>
  <Steps.Step>
    <View>【城市】物流状态</View>
    <View>2016-07-10 12:00</View>
  </Steps.Step>
  <Steps.Step>
    <View>快件已发货</View>
    <View>2016-07-10 09:30</View>
  </Steps.Step>
</Steps>
```

## API

### Steps Props

| 参数           | 说明                    | 类型                 | 默认值          |
| ------------ | --------------------- | ------------------ | ------------ |
| defaultValue | 默认步骤对应的索引值            | _number \| string_ | `0`          |
| value        | 当前步骤对应的索引值            | _number \| string_ | `0`          |
| direction    | 步骤条方向，可选值为 `vertical` | _string_           | `horizontal` |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                     | 默认值                                     | 描述 |
| -------------------------------------- | --------------------------------------- | -- |
| --steps-background-color               | _var(var(--whit)_                       | -  |
| --steps-horizontal-padding             | _10px \* $hd 0_                         | -  |
| --steps-vertical-padding               | _0 0 0 var(--padding-xl)_               | -  |
| --step-color                           | _var(--gray-6)_                         | -  |
| --step-active-color                    | _var(--green)_                          | -  |
| --step-process-color                   | _var(--text-color)_                     | -  |
| --step-font-size                       | _var(--font-size-md)_                   | -  |
| --step-icon-font-size                  | _12px \* $hd_                           | -  |
| --step-line-background-color           | _var(--border-color)_                   | -  |
| --step-line-transition-duration        | _var(--animation-duration-base)_        | -  |
| --step-completed-color                 | _var(--text-color)_                     | -  |
| --step-completed-line-background-color | _var(--green)_                          | -  |
| --step-circle-size                     | _5PX_                                   | -  |
| --step-circle-width                    | _var(--step-circle-size)_               | -  |
| --step-circle-height                   | _var(--step-circle-size)_               | -  |
| --step-circle-margin                   | _3px \* $hd_                            | -  |
| --step-circle-background-color         | _var(--gray-6)_                         | -  |
| --step-circle-border-radius            | _50%_                                   | -  |
| --step-horizontal-title-font-size      | _var(--font-size-sm)_                   | -  |
| --step-vertical-line-height            | _var(--line-height-sm)_                 | -  |
| --step-vertical-padding                | _10px \* $hd 10px \* $hd 10px \* $hd 0_ | -  |



---
url: https://taroify.com/components/sticky/index.md
---

# Sticky 粘性布局

### 介绍

Sticky 组件与 CSS 中 `position: sticky` 属性实现的效果一致，当组件在屏幕范围内时，会按照正常的布局排列，当组件滚出屏幕范围时，始终会固定在屏幕顶部。

### 引入

```tsx
import { Sticky } from "@taroify/core"
```

## 代码演示

### 基础用法

将内容包裹在 `Sticky` 组件内即可。

```tsx
<Sticky>
  <Button color="primary">吸底距离</Button>
</Sticky>
```

### 吸顶距离

通过 `offsetTop` 属性可以设置组件在吸顶时与顶部的距离。

```tsx
<Sticky offsetTop={100}>
  <Button color="primary">吸顶距离</Button>
</Sticky>
```

### 指定容器

通过 `container` 属性可以指定组件的容器，页面滚动时，组件会始终保持在容器范围内，当组件即将超出容器底部时，会固定在容器的底部。

```tsx
function StickyWithContainer() {
  const container = useRef()
  return (
    <View ref={container}>
      <Sticky container={container}>
        <Button color="warning">指定容器</Button>
      </Sticky>
    </View>
  )
}
```

### 吸底距离

将 `position` 设置为 `bottom` 可以让组件吸附在底部。通过 `offsetBottom` 属性可以设置组件在吸底时与底部的距离。

```tsx
<Sticky position="bottom" offsetBottom={50}>
  <Button color="primary">吸底距离</Button>
</Sticky>
```

## API

### Props

| 参数           | 说明                                           | 类型                 | 默认值   |
| ------------ | -------------------------------------------- | ------------------ | ----- |
| position     | 吸附位置，可选值为 `bottom`                           | _string_           | `top` |
| offsetTop    | 吸顶时与顶部的距离，支持 `px` `vw` `vh` `rem` 单位，默认 `px` | _number \| string_ | `0`   |
| offsetBottom | 吸底时与底部的距离，支持 `px` `vw` `vh` `rem` 单位，默认 `px` | _number \| string_ | `0`   |
| container    | 容器对应的 HTML 节点                                | _Element_          | -     |

### Events

| 事件名      | 说明         | 回调参数             |
| -------- | ---------- | ---------------- |
| onChange | 当吸顶状态改变时触发 | _fixed: boolean_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称               | 默认值  | 描述 |
| ---------------- | ---- | -- |
| --sticky-z-index | _99_ | -  |



---
url: https://taroify.com/components/swiper/index.md
---

# Swiper 轮播

### 介绍

用于循环播放一组图片或内容。

### 引入

```tsx
import { Swiper } from "@taroify/core"
```

## 代码演示

### 基础用法

每个 Swipe.Item 代表一张轮播卡片，可以通过 `autoplay` 属性设置自动轮播的间隔。

```tsx
function BasicSwiper() {
  return (
    <Swiper className="basic-swiper" autoplay={4000}>
      <Swiper.Indicator />
      <Swiper.Item>1</Swiper.Item>
      <Swiper.Item>2</Swiper.Item>
      <Swiper.Item>3</Swiper.Item>
      <Swiper.Item>4</Swiper.Item>
    </Swiper>
  )
}
```

```scss
.basic-swiper {
  .taroify-swiper-item {
    color: #fff;
    font-size: 20px * 2;
    background: #39a9ed;
    display: flex;
    justify-content: center;
    align-items: center;
  }
}
```

### 懒加载

当 Swiper 中含有图片时，可以通过 `lazyRender` 属性来开启懒加载模式。在懒加载模式下，只会渲染当前页和下一页。

```tsx
function ImageSwiper() {
  return (
    <Swiper className="image-swiper" lazyRender autoplay={4000}>
      <Swiper.Indicator />
      <Swiper.Item>
        <Image className="image" src="https://img01.yzcdn.cn/vant/apple-1.jpg" />
      </Swiper.Item>
      <Swiper.Item>
        <Image className="image" src="https://img01.yzcdn.cn/vant/apple-2.jpg" />
      </Swiper.Item>
      <Swiper.Item>
        <Image className="image" src="https://img01.yzcdn.cn/vant/apple-3.jpg" />
      </Swiper.Item>
      <Swiper.Item>
        <Image className="image" src="https://img01.yzcdn.cn/vant/apple-4.jpg" />
      </Swiper.Item>
    </Swiper>
  )
}
```

```scss
.image-swiper {
  .image {
    display: block;
    box-sizing: border-box;
    width: 100%;
    height: 240px * 2;
    padding: 30px * 2 60px * 2;
    background: #fff;
    pointer-events: none;
  }
}
```

### 监听 change 事件

在每一页轮播结束后，会触发 `change` 事件。

```tsx
function SwiperWithOnChange() {
  return (
    <>
      <Toast id="toast" />
      <Swiper
        className="onchange-swiper"
        onChange={(value) => Toast.open(`当前 Swipe 索引：${value}`)}
      >
        <Swiper.Indicator />
        <Swiper.Item>1</Swiper.Item>
        <Swiper.Item>2</Swiper.Item>
        <Swiper.Item>3</Swiper.Item>
        <Swiper.Item>4</Swiper.Item>
      </Swiper>
    </>
  )
}
```

### 纵向滚动

设置 `vertical` 属性后滑块会纵向排列，此时需要指定滑块容器的高度。

```tsx
<Swiper className="vertical-swiper" direction="vertical">
  <Swiper.Item>1</Swiper.Item>
  <Swiper.Item>2</Swiper.Item>
  <Swiper.Item>3</Swiper.Item>
  <Swiper.Item>4</Swiper.Item>
</Swiper>
```

```scss
.vertical-swiper {
  .taroify-swiper-item {
    color: #fff;
    font-size: 20px * 2;
    background: #39a9ed;
    display: flex;
    justify-content: center;
    align-items: center;
  }
}
```

### 自定义滑块大小

滑块默认宽度为 `100%`，可以通过 `width` 属性设置单个滑块的宽度。纵向滚动模式下，可以通过 `height` 属性设置单个滑块的高度。

```tsx
function SwiperWithCustomWidth() {
  return (
    <Swiper loop={false} width={300}>
      <Swiper.Indicator />
      <Swiper.Item>1</Swiper.Item>
      <Swiper.Item>2</Swiper.Item>
      <Swiper.Item>3</Swiper.Item>
      <Swiper.Item>4</Swiper.Item>
    </Swiper>
  )
}
```

> 目前不支持在循环滚动模式下自定义滑块大小，因此需要将 loop 设置为 false。

### 自定义指示器

通过 `Swiper.Indicator` 组件可以自定义指示器的样式。

```tsx
function SwiperWithCustomIndicator() {
  const [value, setValue] = useState(0)

  return (
    <Swiper autoplay={4000} onChange={setValue}>
      <Swiper.Item>1</Swiper.Item>
      <Swiper.Item>2</Swiper.Item>
      <Swiper.Item>3</Swiper.Item>
      <Swiper.Item>4</Swiper.Item>
      <Swiper.Indicator className="custom-indicator">{value + 1}/4</Swiper.Indicator>
    </Swiper>
  )
}
```

```scss
.custom-indicator {
  position: absolute;
  right: 5px * 2;
  bottom: 5px * 2;
  padding: 2px * 2 5px * 2;
  font-size: 12px * 2;
  color: #ffffff;
  background: rgba(0, 0, 0, 0.1)_ | - |
}
```

## API

### Swiper Props

| 参数              | 说明                   | 类型        | 默认值          |
| --------------- | -------------------- | --------- | ------------ |
| defaultValue    | 默认位置索引值              | _number_  | `0`          |
| value           | 位置索引值                | _number_  | `0`          |
| autoplay        | 自动轮播间隔，单位为 ms        | _number_  | -            |
| duration        | 动画时长，单位为 ms          | _number_  | `500`        |
| width           | 滑块宽度，单位为 `px`        | _number_  | `auto`       |
| height          | 滑块高度，单位为 `px`        | _number_  | `auto`       |
| direction       | 轮播方向，可选值为 `vertical` | _string_  | `horizontal` |
| touchable       | 是否可以通过手势滑动           | _boolean_ | `true`       |
| lazyRender      | 是否延迟渲染未展示的轮播         | _boolean_ | `false`      |
| stopPropagation | 是否阻止滑动事件冒泡           | _boolean_ | `true`       |

### Swiper Events

| 事件名      | 说明         | 回调参数              |
| -------- | ---------- | ----------------- |
| onChange | 每一页轮播结束后触发 | _(index: number)_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                         | 默认值                              | 描述 |
| ------------------------------------------ | -------------------------------- | -- |
| --swiper-indicators-margin                 | _var(--padding-sm)_              | -  |
| --swiper-indicator-size                    | _6px \* $hd_                     | -  |
| --swiper-indicator-width                   | _var(--swiper-indicator-size)_   | -  |
| --swiper-indicator-height                  | _var(--swiper-indicator-size)_   | -  |
| --swiper-indicator-opacity                 | _0.3_                            | -  |
| --swiper-indicator-background-color        | _var(--border-color)_            | -  |
| --swiper-indicator-transition-duration     | _var(--animation-duration-fast)_ | -  |
| --swiper-indicator-active-opacity          | _1_                              | -  |
| --swiper-indicator-active-background-color | _var(--blue)_                    | -  |



---
url: https://taroify.com/components/tag/index.md
---

# Tag 标签

### 介绍

用于标记关键词和概括主要内容。

### 引入

```ts
import { Tag } from "@taroify/core"
```

## 代码演示

### 基础用法

通过 `color` 属性控制标签颜色。

```tsx
<Tag>标签</Tag>
<Tag color="primary">标签</Tag>
<Tag color="info">标签</Tag>
<Tag color="success">标签</Tag>
<Tag color="warning">标签</Tag>
<Tag color="danger">标签</Tag>
```

### 空心样式

设置 `variant="outlined"` 属性设置为空心样式。

```tsx
<Tag color="primary" variant="outlined">
  标签
</Tag>
```

### 圆角样式

通过 `shape="rounded"` 设置为圆角样式。

```tsx
<Tag color="primary" shape="rounded">
  标签
</Tag>
```

### 右侧圆角样式

通过 `shape="roundedRight"` 设置为圆角样式。

```tsx
<Tag color="primary" shape="roundedRight">
  标签
</Tag>
```

### 左侧圆角样式

通过 `shape="roundedLeft"` 设置为圆角样式。

```tsx
<Tag color="primary" shape="roundedLeft">
  标签
</Tag>
```

### 可关闭标签

添加 `closeable` 属性表示标签是可关闭的，关闭标签时会触发 `onClose` 事件，在 `onClose` 事件中可以执行隐藏标签的逻辑。

```tsx
function CloseTag() {
  const [visible, setVisible] = useState(true)
  return (
    <>
      {visible && (
        <Tag color="primary" size="medium" closeable onClose={() => setVisible(false)}>
          标签
        </Tag>
      )}
    </>
  )
}
```

### 标签大小

通过 `size` 属性调整标签大小。

```tsx
<Tag color="primary" children="标签" />
<Tag color="primary" size="medium" children="标签" />
<Tag color="primary" size="large" children="标签" />
```

### 自定义颜色

通过 `color` 和 `textColor` 属性设置标签颜色。

```tsx
<Tag style={{ backgroundColor: "#7232dd" }} children="标签" />
<Tag style={{ backgroundColor: "#ffe1e1", color: "#ad0000" }} children="标签" />
<Tag style={{ color: "#7232dd" }} variant="outlined" children="标签" />
```

## API

### Props

| 参数        | 说明                                                    | 类型        | 默认值       |
| --------- | ----------------------------------------------------- | --------- | --------- |
| size      | 大小，可选值为 `large` `medium`                              | _string_  | -         |
| color     | 类型，可选值为 `primary` `info` `success` `danger` `warning` | _string_  | `default` |
| shape     | 形状，可选值为 `rounded` `roundedRight` `roundedLeft`        | _string_  | `square`  |
| closeable | 是否为可关闭标签                                              | _boolean_ | `false`   |

### Events

| 事件名     | 说明      | 回调参数                 |
| ------- | ------- | -------------------- |
| onClick | 点击时触发   | _event: ITouchEvent_ |
| onClose | 关闭标签时触发 | _event: ITouchEvent_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                 | 默认值                                                                     | 描述 |
| ---------------------------------- | ----------------------------------------------------------------------- | -- |
| --tag-padding                      | _var(0 var(--padding-base))_                                            | -  |
| --tag-color                        | _var(--white)_                                                          | -  |
| --tag-font-size                    | _var(--font-size-sm)_                                                   | -  |
| --tag-border-radius                | _2px \* $hd_                                                            | -  |
| --tag-line-height                  | _16px \* $hd_                                                           | -  |
| --tag-medium-padding               | _2px \* $hd 6px \* $hd_                                                 | -  |
| --tag-large-padding                | _var(--padding-base) var(--padding-xs)_                                 | -  |
| --tag-large-border-radius          | _var(--border-radius-md)_                                               | -  |
| --tag-large-font-size              | _var(--font-size-md)_                                                   | -  |
| --tag-rounded-border-radius        | _var(--border-radius-max)_                                              | -  |
| --tag-rounded-right-padding        | _var(--tag-rounded-right-padding, 0 (6px \* $hd) 0 var(--padding-base)_ | -  |
| --tag-rounded-left-padding         | _var(--tag-rounded-left-padding, 0 var(--padding-base) 0 (6px \* $hd))_ | -  |
| --tag-rounded-right-medium-padding | _2px \* $hd 8px \* $hd 2px \* $hd 6px \* $hd_                           | -  |
| --tag-rounded-left-medium-padding  | _2px \* $hd 6px \* $hd 2px \* $hd 8px \* $hd_                           | -  |
| --tag-rounded-right-large-padding  | _var(--padding-base) 6px \* $hd var(--padding-base) var(--padding-xs)_  | -  |
| --tag-rounded-left-large-padding   | _var(--padding-base) var(--padding-xs) var(--padding-base) 6px \* $hd_  | -  |
| --tag-default-color                | _var(--gray-6)_                                                         | -  |
| --tag-default-background-color     | _var(--gray-6)_                                                         | -  |
| --tag-primary-color                | _var(--primary-color)_                                                  | -  |
| --tag-primary-background-color     | _var(--primary-color)_                                                  | -  |
| --tag-info-color                   | _var(--info-color)_                                                     | -  |
| --tag-info-background-color        | _var(--info-color)_                                                     | -  |
| --tag-success-color                | _var(--success-color)_                                                  | -  |
| --tag-success-background-color     | _var(--success-color)_                                                  | -  |
| --tag-warning-color                | _var(--warning-color)_                                                  | -  |
| --tag-warning-background-color     | _var(--warning-color)_                                                  | -  |
| --tag-danger-color                 | _var(--danger-color)_                                                   | -  |
| --tag-danger-background-color      | _var(--danger-color)_                                                   | -  |
| --tag-outlined-background-color    | _var(--white)_                                                          | -  |
| --tag-border-color                 | _var(--tag-border-color, currentColor)_                                 | -  |



---
url: https://taroify.com/components/text-ellipsis/index.md
---

# TextEllipsis 文本省略

### 介绍

对长文本进行省略，支持展开/收起。

请升级 `taroify` 到 >= `v0.1.1-alpha.9` 版本来使用该组件。

### 引入

```tsx
import { TextEllipsis } from "@taroify/core"
```

## 代码演示

### 基础用法

默认展示 `1` 行，超过 `1` 行显示省略号。

```tsx
<TextEllipsis content="慢慢来，不要急，生活给你出了难题，可也终有一天会给出答案。" />
```

### 展开/收起

超过行数支持展开/收起。

```tsx
<TextEllipsis
  content="似水流年是一个人所有的一切，只有这个东西，才真正归你所有。其余的一切，都是片刻的欢娱和不幸，转眼间就已跑到那似水流年里去了。"
  expandText="展开"
  collapseText="收起"
/>
```

### 自定义展示行数

通过设置 `rows` 限制展示行数。

```tsx
<TextEllipsis
  content="那一天我二十一岁，在我一生的黄金时代。我有好多奢望。我想爱，想吃，还想在一瞬间变成天上半明半暗的云。后来我才知道，生活就是个缓慢受锤的过程，人一天天老下去，奢望也一天天消失，最后变得像挨了锤的牛一样。可是我过二十一岁生日时没有预见到这一点。我觉得自己会永远生猛下去，什么也锤不了我。"
  rows={2}
  expandText="展开"
  collapseText="收起"
/>
```

### 自定义省略位置

通过设置 `position` 控制省略位置。

- 头部省略：

```tsx
<TextEllipsis
  content="那一天我二十一岁，在我一生的黄金时代。我有好多奢望。我想爱，想吃，还想在一瞬间变成天上半明半暗的云。后来我才知道，生活就是个缓慢受锤的过程，人一天天老下去，奢望也一天天消失，最后变得像挨了锤的牛一样。可是我过二十一岁生日时没有预见到这一点。我觉得自己会永远生猛下去，什么也锤不了我。"
  position="start"
  rows={3}
  expandText="展开"
  collapseText="收起"
/>
```

- 中部省略：

```tsx
<TextEllipsis
  content="那一天我二十一岁，在我一生的黄金时代。我有好多奢望。我想爱，想吃，还想在一瞬间变成天上半明半暗的云。后来我才知道，生活就是个缓慢受锤的过程，人一天天老下去，奢望也一天天消失，最后变得像挨了锤的牛一样。可是我过二十一岁生日时没有预见到这一点。我觉得自己会永远生猛下去，什么也锤不了我。"
  position="middle"
  rows={3}
  expandText="展开"
  collapseText="收起"
/>
```

### 手动控制

通过 ref 可以获取到 TextEllipsis 实例并调用实例方法

```tsx
const wrapRef = useRef<TextEllipsisInstance>(null);

const onClick = () => {
  wrapRef.current?.toggle(true)
}

return (
  <Block variant="card" title="方法调用">
    <TextEllipsis ref={wrapRef} content="那一天我二十一岁，在我一生的黄金时代。我有好多奢望。我想爱，想吃，还想在一瞬间变成天上半明半暗的云。后来我才知道，生活就是个缓慢受锤的过程，人一天天老下去，奢望也一天天消失，最后变得像挨了锤的牛一样。可是我过二十一岁生日时没有预见到这一点。我觉得自己会永远生猛下去，什么也锤不了我。" position="start" rows={3} expandText="展开" collapseText="收起" />
    <Button onClick={onClick}>展开</Button>
  </Block>
)
```

## API

### Props

| 参数           | 说明                         | 类型                 | 默认值     |
| ------------ | -------------------------- | ------------------ | ------- |
| rows         | 展示的行数                      | _number \| string_ | `1`     |
| content      | 需要展示的文本                    | _string_           | -       |
| expandText   | 展开操作的文案                    | _string_           | -       |
| collapseText | 收起操作的文案                    | _string_           | -       |
| dots         | 省略号的文本内容                   | _string_           | `'...'` |
| position     | 省略位置，可选值为 `start` `middle` | _string_           | `'end'` |

### Events

| 事件名           | 说明         | 回调参数                |
| ------------- | ---------- | ------------------- |
| onClickAction | 点击展开/收起时触发 | _expanded: boolean_ |

### 方法

通过 `ref` 可以获取到 TextEllipsis 实例并调用实例方法

| 方法名    | 说明                                    | 参数                   | 返回值 |
| :----- | ------------------------------------- | -------------------- | --- |
| toggle | 切换文本的展开状态，传 true 为展开，false 为收起，不传参为切换 | _expanded?: boolean_ | -   |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                 | 默认值             | 描述      |
| ---------------------------------- | --------------- | ------- |
| --text-ellipsis-font-size          | _14px \* $hd_   | 文本字体大小  |
| --text-ellipsis-content-font-color | _var(--gray-8)_ | 文本字体颜色  |
| --text-ellipsis-line-height        | _1.6_           | 文本的行高   |
| --text-ellipsis-action-color       | _var(--blue)_   | 操作按钮的颜色 |



---
url: https://taroify.com/components/timeline/index.md
---

# Timeline 时间轴

### 介绍

按时间顺序来展示了一系列的事件。

### 引入

```ts
import { Timeline } from "@taroify/core"
```

## 代码演示

### 基础用法

一个基本的时间轴，显示事件列表。

```tsx
function RightTimeline() {
  return (
    <Timeline position="right">
      <Timeline.Item>Eat</Timeline.Item>
      <Timeline.Item>Code</Timeline.Item>
      <Timeline.Item>Sleep</Timeline.Item>
    </Timeline>
  )
}
```

### 左侧用法

时间轴的主要内容可以被放置在相对时间轴的左侧。

```tsx
function LeftTimeline() {
  return (
    <Timeline position="left">
      <Timeline.Item>Eat</Timeline.Item>
      <Timeline.Item>Code</Timeline.Item>
      <Timeline.Item>Sleep</Timeline.Item>
    </Timeline>
  )
}
```

### 交替用法

时间轴可以显示在事件的两侧。

```tsx
function AlternateTimeline() {
  return (
    <Timeline position="alternate">
      <Timeline.Item>Eat</Timeline.Item>
      <Timeline.Item>Code</Timeline.Item>
      <Timeline.Item>Sleep</Timeline.Item>
      <Timeline.Item>Repeat</Timeline.Item>
    </Timeline>
  )
}
```

### 描边用法

可以自定义圆点的变种和颜色。

```tsx
function OutlinedTimeline() {
  return (
    <Timeline position="alternate">
      <Timeline.Item dot={{ variant: "outlined" }}>Eat</Timeline.Item>
      <Timeline.Item dot={{ variant: "outlined", color: "primary" }}>Code</Timeline.Item>
      <Timeline.Item dot={{ variant: "outlined", color: "danger" }}>Sleep</Timeline.Item>
      <Timeline.Item dot={{ variant: "outlined" }}>Repeat</Timeline.Item>
    </Timeline>
  )
}
```

### 自定义用法

可以自定义整个时间轴。

```tsx
function CustomTimeline() {
  return (
    <Timeline>
      <Timeline.Item>
        <Timeline.Content align="center">9:30 am</Timeline.Content>
        <Timeline.Separator>
          <Timeline.Connector />
          <Timeline.Dot>
            <FireOutlined size="24" />
          </Timeline.Dot>
          <Timeline.Connector />
        </Timeline.Separator>
        <Timeline.Content direction="column" align="start">
          <View className="timeline-title">Eat</View>
          <View>Because you need strength</View>
        </Timeline.Content>
      </Timeline.Item>
      <Timeline.Item>
        <Timeline.Content direction="column" align="end">
          <View className="timeline-title">Code</View>
          <View>awesome</View>
        </Timeline.Content>
        <Timeline.Separator>
          <Timeline.Connector />
          <Timeline.Dot color="primary">
            <StarOutlined size="24" />
          </Timeline.Dot>
          <Timeline.Connector />
        </Timeline.Separator>
        <Timeline.Content align="center">10:00 am</Timeline.Content>
      </Timeline.Item>
      <Timeline.Item>
        <Timeline.Content />
        <Timeline.Separator>
          <Timeline.Connector />
          <Timeline.Dot variant="outlined" color="primary">
            <GemOutlined size="24" />
          </Timeline.Dot>
          <Timeline.Connector />
        </Timeline.Separator>
        <Timeline.Content direction="column" align="start">
          <View className="timeline-title">Sleep</View>
          <View>Because you need rest</View>
        </Timeline.Content>
      </Timeline.Item>
      <Timeline.Item>
        <Timeline.Content direction="column" align="end">
          <View className="timeline-title">Repeat</View>
          <View>you love!</View>
        </Timeline.Content>
        <Timeline.Separator>
          <Timeline.Connector />
          <Timeline.Dot color="danger">
            <SmileOutlined size="24" />
          </Timeline.Dot>
          <Timeline.Connector />
        </Timeline.Separator>
      </Timeline.Item>
    </Timeline>
  )
}
```

```scss
.timeline-title {
  font-size: 24px * 2;
}
```

## API

### Timeline Props

| 参数       | 说明                                                       | 类型       | 默认值 |
| -------- | -------------------------------------------------------- | -------- | --- |
| position | 位置布局，可选值为 `left` `right` `alternate` `alternate-reverse` | _string_ | -   |

### Timeline.Item Props

| 参数  | 说明 | 类型                              | 默认值 |
| --- | -- | ------------------------------- | --- |
| dot | 圆点 | _ReactNode \| TimelineDotProps_ | -   |

### Timeline.Dot Props

| 参数      | 说明                                                      | 类型       | 默认值       |
| ------- | ------------------------------------------------------- | -------- | --------- |
| variant | 圆点变体，可选值为 `outlined`                                    | _string_ | `filled`  |
| color   | 圆点颜色，可选值为 `primary` `info` `success` `warning` `danger` | _string_ | `default` |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                       | 默认值                                      | 描述 |
| ---------------------------------------- | ---------------------------------------- | -- |
| --timeline-color                         | _var(--white)_                           | -  |
| --timeline-background-color              | _var(--gray-5)_                          | -  |
| --timeline-border-color                  | _var(--white)_                           | -  |
| --timeline-border-width                  | _2px \* $hd_                             | -  |
| --timeline-font-weight                   | _var(--font-weight-bold)_                | -  |
| --timeline-font-size                     | _var(--font-size-md)_                    | -  |
| --timeline-min-height                    | _70px \* $hd_                            | -  |
| --timeline-content-padding               | _0 16px \* $hd_                          | -  |
| --timeline-connector-border-color        | _var(--gray-5)_                          | -  |
| --timeline-connector-border-width        | _2PX_                                    | -  |
| --timeline-connector-border-style        | _solid_                                  | -  |
| --timeline-top-connector-border-color    | _var(--timeline-connector-border-color)_ | -  |
| --timeline-top-connector-border-width    | _var(--timeline-connector-border-width)_ | -  |
| --timeline-top-connector-border-style    | _var(--timeline-connector-border-style)_ | -  |
| --timeline-bottom-connector-border-color | _var(--timeline-connector-border-color)_ | -  |
| --timeline-bottom-connector-border-width | _var(--timeline-connector-border-width)_ | -  |
| --timeline-bottom-connector-border-style | _var(--timeline-connector-border-style)_ | -  |
| --timeline-dot-size                      | _12px \* $hd_                            | -  |
| --timeline-dot-margin                    | _6px \* $hd 0_                           | -  |
| --timeline-dot-padding                   | _4PX_                                    | -  |
| --timeline-dot-border-width              | _2PX_                                    | -  |
| --timeline-dot-default-color             | _var(--gray-5)_                          | -  |
| --timeline-dot-primary-color             | _var(--primary-color)_                   | -  |
| --timeline-dot-info-color                | _var(--info-color)_                      | -  |
| --timeline-dot-success-color             | _var(--success-color)_                   | -  |
| --timeline-dot-warning-color             | _var(--warning-color)_                   | -  |
| --timeline-dot-danger-color              | _var(--danger-color)_                    | -  |



---
url: https://taroify.com/components/watermark/index.md
---

# Watermark 水印

### 介绍

在页面上添加特定的文字或图案作为水印，可用于防止信息盗用。

请升级 `taroify` 到 >= `v0.1.1-alpha.11` 版本来使用该组件。

### 引入

```tsx
import { Watermark } from "@taroify/core"
```

## 代码演示

### 文字水印

通过 `content` 属性来设置水印的文字。

```tsx
<Watermark content="Taroify" />
```

### 图片水印

通过 `image` 属性来设置水印图片，并使用 `opacity` 来调整水印的整体透明度。

```tsx
<Watermark image="https://fastly.jsdelivr.net/npm/@vant/assets/vant-watermark.png" opacity={0.2} />
```

### 自定义间隔

通过 `gapX` 和 `gapY` 属性来控制多个重复水印之间的间隔。

```tsx
<Watermark
  image="https://fastly.jsdelivr.net/npm/@vant/assets/vant-watermark.png"
  gapX={30}
  gapY={10}
  opacity={0.2}
/>
```

### 自定义倾斜角度

通过 `rotate` 属性来控制水印的倾斜角度，默认值为`-11`。

```tsx
<Watermark
  image="https://fastly.jsdelivr.net/npm/@vant/assets/vant-watermark.png"
  rotate={22}
  opacity={0.2}
/>
```

### 显示范围

通过 `fullPage` 属性来控制水印的显示范围。

```tsx
<Watermark
  image="https://fastly.jsdelivr.net/npm/@vant/assets/vant-watermark.png"
  opacity={0.2}
  fullPage
/>
```

## API

### Props

| 参数        | 说明                                  | 类型                 | 默认值       |
| --------- | ----------------------------------- | ------------------ | --------- |
| width     | 水印宽度                                | _number_           | `80`      |
| height    | 水印高度                                | _number_           | `80`      |
| zIndex    | 水印的 z-index                         | _number \| string_ | `100`     |
| content   | 文字水印的内容                             | _string_           | -         |
| image     | 图片水印的内容，如果与 `content` 同时传入，优先使用图片水印 | _string_           | -         |
| rotate    | 水印的旋转角度                             | _number_           | `-11`     |
| fullPage  | 水印是否全屏显示                            | _boolean_          | `false`   |
| gapX      | 水印之间的水平间隔                           | _number_           | `20`      |
| gapY      | 水印之间的垂直间隔                           | _number_           | `20`      |
| textColor | 文字水印的颜色                             | _string_           | `#dcdee0` |
| textSize  | 文字水印的大小                             | _number_           | `20`      |
| opacity   | 水印的透明度                              | _number_           | -         |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/components/config-provider.md)。

| 名称                  | 默认值   | 描述              |
| ------------------- | ----- | --------------- |
| --watermark-z-index | _100_ | 根节点的 z-index 层级 |



---
url: https://taroify.com/components/grid/index.md
---

# Grid 宫格

### 介绍

宫格可以在水平方向上把页面分隔成等宽度的区块，用于展示内容或进行页面导航。

### 引入

```ts
import { Grid } from "@taroify/core"
```

## 代码演示

### 基础用法

通过 `icon` 属性设置格子内的图标，`text` 属性设置文字内容。

```tsx
<Grid>
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
</Grid>
```

### 自定义列数

默认一行展示四个格子，可以通过 `columns` 自定义列数。

```tsx
<Grid columns={3}>
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
</Grid>
```

### 自定义内容

通过插槽可以自定义格子展示的内容。

```tsx
<Grid columns={3} bordered={false}>
  <Grid.Item>
    <Image className="grid-image" src="https://img.yzcdn.cn/vant/apple-1.jpg" />
  </Grid.Item>
  <Grid.Item>
    <Image className="grid-image" src="https://img.yzcdn.cn/vant/apple-2.jpg" />
  </Grid.Item>
  <Grid.Item>
    <Image className="grid-image" src="https://img.yzcdn.cn/vant/apple-3.jpg" />
  </Grid.Item>
</Grid>
```

```scss
.grid-image {
  width: 100%;
  height: 100%;
}
```

### 正方形格子

设置 `square` 属性后，格子的高度会和宽度保持一致。

```tsx
<Grid columns={4} square>
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
</Grid>
```

### 格子间距

通过 `gutter` 属性设置格子之间的距离。

```tsx
<Grid columns={4} gutter={10}>
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
</Grid>
```

### 内容横排

将 `direction` 属性设置为 `horizontal`，可以让宫格的内容呈横向排列。

```tsx
<Grid columns={3} direction="horizontal">
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
  <Grid.Item icon={<PhotoOutlined />} text="文字" />
</Grid>
```

### 徽标提示

设置 `badge=true` 属性后，会在图标右上角展示一个小红点。设置 `badge` 属性后，会在图标右上角展示相应的徽标。

```tsx
<Grid columns={2}>
  <Grid.Item icon={<HomeOutlined />} badge text="文字" />
  <Grid.Item icon={<Search />} badge={<Badge content={100} max={99} />} text="文字" />
</Grid>
```

## API

### Grid Props

| 参数        | 说明                          | 类型                 | 默认值        |
| --------- | --------------------------- | ------------------ | ---------- |
| columns   | 列数                          | _number \| string_ | `4`        |
| iconSize  | 图标大小，默认单位为`px`              | _number \| string_ | `28px`     |
| gutter    | 格子之间的间距，默认单位为`px`           | _number \| string_ | `0`        |
| bordered  | 是否显示边框                      | _boolean_          | `true`     |
| centered  | 是否将格子内容居中显示                 | _boolean_          | `true`     |
| square    | 是否将格子固定为正方形                 | _boolean_          | `false`    |
| clickable | 是否开启格子点击反馈                  | _boolean_          | `false`    |
| direction | 格子内容排列的方向，可选值为 `horizontal` | _string_           | `vertical` |

### Grid.Item Props

| 参数    | 说明                                                   | 类型                                                  | 默认值 |
| ----- | ---------------------------------------------------- | --------------------------------------------------- | --- |
| text  | 文字                                                   | _string_                                            | -   |
| icon  | [图标](/components/icon.md)或[图片](/components/image.md) | _ReactNode_                                         | -   |
| badge | 图标上徽标的内容                                             | _boolean \| number \| string \| Badge \| ReactNode_ | -   |

### Grid.Item Events

| 事件名     | 说明      | 回调参数                |
| ------- | ------- | ------------------- |
| onClick | 点击格子时触发 | _event: MouseEvent_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                   | 默认值                                   | 描述 |
| ------------------------------------ | ------------------------------------- | -- |
| --grid-item-content-padding          | _var(--padding-md) var(--padding-xs)_ | -  |
| --grid-item-content-background-color | _var(--white)_                        | -  |
| --grid-item-content-active-color     | _var(--active-color)_                 | -  |
| --grid-item-icon-font-size           | _28px \* $hd_                         | -  |
| --grid-item-text-color               | _var(--gray-7)_                       | -  |
| --grid-item-text-font-size           | _var(--font-size-sm)_                 | -  |



---
url: https://taroify.com/components/index-list/index.md
---

# IndexList 索引栏

### 介绍

用于列表的索引分类显示和快速定位。

### 引入

```tsx
import { IndexList } from "@taroify/core"
```

## 代码演示

### 基础用法

点击索引栏时，会自动跳转到对应的 `IndexList.Anchor` 锚点位置。

```tsx
function BasicIndexList() {
  const indexList: string[] = []
  const charCodeOfA = "A".charCodeAt(0)

  for (let i = 0; i < 26; i++) {
    indexList.push(String.fromCharCode(charCodeOfA + i))
  }

  return (
    <IndexList>
      {_.map(indexList, (index) => {
        return (
          <Fragment key={index}>
            <IndexList.Anchor index={index} />
            <Cell title="文本" />
            <Cell title="文本" />
            <Cell title="文本" />
          </Fragment>
        )
      })}
    </IndexList>
  )
}
```

### 自定义索引列表

```tsx
function CustomIndexList() {
  const customIndexList = [1, 2, 3, 4, 5, 6, 8, 9, 10]

  return (
    <IndexList>
      {_.map(customIndexList, (index) => {
        return (
          <Fragment key={index}>
            <IndexList.Anchor index={index}>标题{index}</IndexList.Anchor>
            <Cell title="文本" />
            <Cell title="文本" />
            <Cell title="文本" />
          </Fragment>
        )
      })}
    </IndexList>
  )
}
```

### 配合弹窗使用

当在弹窗内使用时，请传入 `inner` 属性以便于组件知道是在底部弹窗内，用于启用 `ScrollView`。如果自定义了弹窗弹出动画时间，请手动设置 `delay` 属性，值为动画时长。

```tsx
function PopupIndexBar() {
  const [open, setOpen] = useState(false)

  const indexList: string[] = []
  const charCodeOfA = "A".charCodeAt(0)

  for (let i = 0; i < 26; i++) {
    indexList.push(String.fromCharCode(charCodeOfA + i))
  }

  return (
    <>
      <Button onClick={() => setOpen(true)}>打开弹窗</Button>
      <Popup
        open={open}
        style={{ height: "80%" }}
        placement="bottom"
        rounded
        onClose={() => setOpen(false)}
      >
        <Popup.Close />
        <View className="index-list-demo_wrap">
          <IndexList inner delay={300}>
            {_.map(indexList, (index) => {
              return (
                <Fragment key={index}>
                  <IndexList.Anchor index={index} />
                  <Cell title="文本" />
                  <Cell title="文本" />
                  <Cell title="文本" />
                </Fragment>
              )
            })}
          </IndexList>
        </View>
      </Popup>
    </>
  )
}
```

## API

### IndexList Props

| 参数              | 说明                               | 类型                 | 默认值                                  |
| --------------- | -------------------------------- | ------------------ | ------------------------------------ |
| sticky          | 是否开启锚点自动吸顶                       | _boolean_          | `true`                               |
| stickyOffsetTop | 锚点自动吸顶时与顶部的距离                    | _number \| string_ | `0`                                  |
| inner           | 是否是底部弹窗内使用                       | _boolean_          | `false`                              |
| delay           | inner 为 `true`，并且自定义了弹窗弹出动画时长时设置 | _number_           | inner 为 true 时候是 `300`，false 时候是 `0` |
| showSidebar     | 是否显示索引                           | _boolean_          | `true`                               |

### IndexList Events

| 事件名      | 说明       | 回调参数                                        |
| -------- | -------- | ------------------------------------------- |
| onChange | 索引位变化时触发 | _current: number, anchor: number \| string_ |

### IndexList Method

通过 `ref` 可以获取到 IndexList 实例并调用实例方法

| 方法名      | 说明     | 参数    | 返回值 |
| :------- | ------ | ----- | --- |
| scrollTo | 跳转指定位置 | index | -   |

### IndexList.Anchor Props

| 参数       | 说明   | 类型                 | 默认值 |
| -------- | ---- | ------------------ | --- |
| index    | 索引字符 | _number \| string_ | -   |
| children | 索引内容 | _ReactNode_        | -   |

### IndexList Events

| 事件名      | 说明             | 回调参数                      |
| -------- | -------------- | ------------------------- |
| onSelect | 点击索引栏的字符时触发    | _index: number \| string_ |
| onChange | 当前高亮的索引字符变化时触发 | _index: number \| string_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                     | 默认值                                      | 描述 |
| -------------------------------------- | ---------------------------------------- | -- |
| --index-list-sidebar-z-index           | _2_                                      | -  |
| --index-list-index-font-size           | _var(--font-size-xs)_                    | -  |
| --index-list-index-line-height         | _var(--line-height-xs)_                  | -  |
| --index-list-index-font-weight         | _var(--font-weight-bold)_                | -  |
| --index-list-index-padding             | _0 var(--padding-xs 0 var(--padding-md)_ | -  |
| --index-list-index-active-color        | _var(--danger-color)_                    | -  |
| --index-anchor-z-index                 | _1_                                      | -  |
| --index-anchor-padding                 | _0 var(--padding-md)_                    | -  |
| --index-anchor-color                   | _var(--text-color)_                      | -  |
| --index-anchor-font-weight             | _var(--font-weight-bold)_                | -  |
| --index-anchor-font-size               | _var(--font-size-md)_                    | -  |
| --index-anchor-line-height             | _32px \* $hd_                            | -  |
| --index-anchor-background-color        | _transparent_                            | -  |
| --index-anchor-sticky-color            | _var(--danger-color)_                    | -  |
| --index-anchor-sticky-background-color | _var(--white)_                           | -  |



---
url: https://taroify.com/components/navbar/index.md
---

# Navbar 导航栏

### 介绍

为页面提供导航功能，常用于页面顶部。

### 引入

```tsx
import { Navbar } from "@taroify/core"
```

## 代码演示

### 基础用法

```tsx
<Navbar title="标题" />
```

### 返回上级

```tsx
<Navbar title="标题">
  <Navbar.NavLeft onClick={onClick}>返回</Navbar.NavLeft>
  <Navbar.NavRight>按钮</Navbar.NavRight>
</Navbar>
```

### 使用 NavLeft 和 NavRight

```tsx
<Navbar>
  <Navbar.NavLeft>返回</Navbar.NavLeft>
  <Navbar.Title>标题</Navbar.Title>
  <Navbar.NavRight icon={<Search />} />
</Navbar>
```

## API

### Navbar Props

| 参数            | 说明                                        | 类型        | 默认值     |
| ------------- | ----------------------------------------- | --------- | ------- |
| title         | 标题                                        | _string_  | `''`    |
| bordered      | 是否显示下边框                                   | _boolean_ | `false` |
| fixed         | 是否固定在顶部                                   | _boolean_ | `false` |
| safeArea      | 安全区域，可选值 `top` `bottom`，仅在`fixed=true`时有效 | _string_  | -       |
| nativeSafeTop | 是否启用顶部安全区域原生属性                            | _boolean_ | `false` |
| placeholder   | 固定在顶部时，是否在标签位置生成一个等高的占位元素                 | _boolean_ | `false` |

### Navbar.NavLeft Props

| 参数       | 说明   | 类型          | 默认值 |
| -------- | ---- | ----------- | --- |
| icon     | 左侧图标 | _Icon_      | -   |
| children | 左侧文案 | _ReactNode_ | -   |

### Navbar.NavRight Props

| 参数       | 说明   | 类型          | 默认值 |
| -------- | ---- | ----------- | --- |
| icon     | 右侧图标 | _Icon_      | -   |
| children | 右侧文案 | _ReactNode_ | -   |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                         | 默认值                       | 描述 |
| -------------------------- | ------------------------- | -- |
| --navbar-z-index           | _1_                       | -  |
| --navbar-height            | _46px \* $hd_             | -  |
| --navbar-line-height       | _var(--line-height-lg)_   | -  |
| --navbar-background-color  | _var(--white)_            | -  |
| --navbar-icon-margin-right | _var(--padding-base)_     | -  |
| --navbar-icon-font-size    | _16px \* $hd_             | -  |
| --navbar-icon-color        | _var(--blue)_             | -  |
| --navbar-text-color        | _var(--blue)_             | -  |
| --navbar-title-font-size   | _var(--font-size-lg)_     | -  |
| --navbar-title-font-weight | _var(--font-weight-bold)_ | -  |
| --navbar-title-color       | _var(--text-color)_       | -  |



---
url: https://taroify.com/components/pagination/index.md
---

# Pagination 分页

### 介绍

数据量过多时，采用分页的形式将数据分隔，每次只加载一个页面。

### 引入

```js
import { Pagination } from "@taroify/core"
```

## 代码演示

### 基础用法

通过 `current` 来绑定当前页码。

```tsx
export default function BasicPagination() {
  const [current, setCurrent] = useState<number>(1)
  return <Pagination current={current} count={10} onChange={(page) => setCurrent(page)} />
}
```

### 简单模式

将 `mode` 设置为 `simple` 来切换到简单模式，此时分页器不会展示具体的页码按钮。

```tsx
export default function BasicPagination() {
  const [current, setCurrent] = useState<number>(1)
  return (
    <Pagination current={current} count={10} mode="simple" onChange={(page) => setCurrent(page)} />
  )
}
```

### 显示省略号

设置 `Pagination.Item.type` 为 `start-ellipsis` 或者 `end-ellipsis` 展示省略号按钮，点击后可以快速跳转。

```tsx
function PaginationWithEllipses() {
  const [current, setCurrent] = useState<number>(1)
  return (
    <Pagination current={current} siblingCount={1} count={13} onChange={(page) => setCurrent(page)}>
      <Pagination.Item type="start-ellipsis" />
      <Pagination.Item type="end-ellipsis" />
    </Pagination>
  )
}
```

### 自定义按钮

通过 `Pagination.Item` 组件来自定义分页按钮的内容。

```tsx
function PaginationWithCustomButton() {
  const [current, setCurrent] = useState<number>(1)
  return (
    <Pagination current={current} count={6} onChange={(page) => setCurrent(page)}>
      <Pagination.Item type="previous">
        <ArrowLeft />
      </Pagination.Item>
      <Pagination.Item type="next">
        <ArrowRight />
      </Pagination.Item>
    </Pagination>
  )
}
```

## API

### Props

| 参数           | 说明               | 类型       | 默认值   |
| ------------ | ---------------- | -------- | ----- |
| current      | 当前页码             | _number_ | -     |
| mode         | 显示模式，可选值为 simple | _string_ | multi |
| prevText     | 上一页按钮文字          | _string_ | 上一页   |
| nextText     | 下一页按钮文字          | _string_ | 下一页   |
| siblingCount | 当前页码两侧显示的数字个数    | _number_ | `2`   |
| count        | 总页数              | _number_ | -     |

### Events

| 事件名      | 说明      | 回调参数 |
| -------- | ------- | ---- |
| onChange | 页码改变时触发 | -    |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                          | 默认值                            | 描述 |
| ------------------------------------------- | ------------------------------ | -- |
| --pagination-height                         | _40px \* $hd_                  | -  |
| --pagination-font-size                      | _var(--font-size-md)_          | -  |
| --pagination-background-color               | _var(--white)_                 | -  |
| --pagination-item-min-width                 | _36px \* $hd_                  | -  |
| --pagination-item-color                     | _var(--blue)_                  | -  |
| --pagination-item-active-color              | _var(--white)_                 | -  |
| --pagination-item-active-background-color   | _var(--pagination-item-color)_ | -  |
| --pagination-item-disabled-color            | _var(--gray-7)_                | -  |
| --pagination-item-disabled-background-color | _var(--background-color)_      | -  |
| --pagination-item-disabled-opacity          | _var(--disabled-opacity)_      | -  |
| --pagination-button-padding                 | _0 var(--padding-base)_        | -  |
| --pagination-desc-color                     | _var(--gray-7)_                | -  |



---
url: https://taroify.com/components/sidebar/index.md
---

# Sidebar 侧边导航

### 介绍

垂直展示的导航栏，用于在不同的内容区域之间进行切换。

### 引入

```ts
import { Sidebar } from "@taroify/core"
```

## 代码演示

### 基础用法

```tsx
<Sidebar>
  <Sidebar.Tab>标签名</Sidebar.Tab>
  <Sidebar.Tab>标签名</Sidebar.Tab>
  <Sidebar.Tab>标签名</Sidebar.Tab>
</Sidebar>
```

### 徽标提示

设置 `badge` 属性后，会在右上角展示相应的徽标。

```tsx
<Sidebar>
  <Sidebar.Tab badge>标签名</Sidebar.Tab>
  <Sidebar.Tab badge="5">标签名</Sidebar.Tab>
  <Sidebar.Tab badge={<Badge position="bottom-right" max={99} content={100} />}>标签名</Sidebar.Tab>
</Sidebar>
```

### 禁用选项

通过 `disabled` 属性禁用选项。

```tsx
<Sidebar>
  <Sidebar.Tab>标签名</Sidebar.Tab>
  <Sidebar.Tab disabled>标签名</Sidebar.Tab>
  <Sidebar.Tab>标签名</Sidebar.Tab>
</Sidebar>
```

### 监听切换事件

设置 `onChange` 方法来监听切换导航项时的事件。

```tsx
import { Sidebar } from "@taroify/core"

function EventSidebar() {
  return (
    <>
      <Toast id="toast" />
      <Sidebar onChange={(newValue, { children }: Sidebar.TabObject) => Toast.open(children)}>
        <Sidebar.Tab>标签名 1</Sidebar.Tab>
        <Sidebar.Tab>标签名 2</Sidebar.Tab>
        <Sidebar.Tab>标签名 3</Sidebar.Tab>
      </Sidebar>
    </>
  )
}
```

## API

### Sidebar Props

| 参数           | 说明       | 类型                 | 默认值 |
| ------------ | -------- | ------------------ | --- |
| defaultValue | 默认导航项的索引 | _number \| string_ | `0` |
| value        | 当前导航项的索引 | _number \| string_ | `0` |

### Sidebar Events

| 事件名      | 说明       | 回调参数                                 |
| -------- | -------- | ------------------------------------ |
| onChange | 切换导航项时触发 | _value: any, tab: Sidebar.TabObject_ |

### Sidebar.Tab Props

| 参数       | 说明       | 类型                                                  | 默认值     |
| -------- | -------- | --------------------------------------------------- | ------- |
| disabled | 是否禁用该项   | _boolean_                                           | `false` |
| children | 内容       | _ReactNode_                                         | -       |
| badge    | 图标上徽标的内容 | _boolean \| number \| string \| Badge \| ReactNode_ | -       |

### Sidebar.Tab Events

| 事件名     | 说明    | 回调参数                 |
| ------- | ----- | -------------------- |
| onClick | 点击时触发 | _event: ITouchEvent_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                           | 默认值                                   | 描述 |
| -------------------------------------------- | ------------------------------------- | -- |
| --sidebar-width                              | _80px \* $hd_                         | -  |
| --sidebar-disabled-color                     | _var(--gray-5)_                       | -  |
| --sidebar-tab-font-size                      | _var(--font-size-md)_                 | -  |
| --sidebar-tab-line-height                    | _var(--line-height-md)_               | -  |
| --sidebar-tab-color                          | _var(--text-color)_                   | -  |
| --sidebar-tab-padding                        | _20px \* $hd var(--padding-sm)_       | -  |
| --sidebar-tab-background-color               | _var(--background-color)_             | -  |
| --sidebar-tab-active-background-color        | _var(--active-color)_                 | -  |
| --sidebar-tab-active-font-weight             | _var(--font-weight-bold)_             | -  |
| --sidebar-tab-active-color                   | _var(--text-color)_                   | -  |
| --sidebar-tab-active-border-width            | _4px \* $hd_                          | -  |
| --sidebar-tab-active-border-height           | _16px \* $hd_                         | -  |
| --sidebar-tab-active-border-color            | _var(--red)_                          | -  |
| --sidebar-tab-active-active-background-color | _var(--white)_                        | -  |
| --sidebar-tab-disabled-color                 | _var(--sidebar-disabled-color)_       | -  |
| --sidebar-tab-disabled-background-color      | _var(--sidebar-tab-background-color)_ | -  |



---
url: https://taroify.com/components/tabs/index.md
---

# Tabs 标签页

### 介绍

选项卡组件，用于在不同的内容区域之间进行切换。

### 引入

```ts
import { Tabs } from "@taroify/core"
```

## 代码演示

### 基础用法

通过 `value` 绑定当前激活标签对应的索引值，默认情况下启用第一个标签。

```tsx
import { Tabs } from "@taroify/core"

function BasicTabs() {
  const [value, setValue] = useState(0)
  return (
    <Tabs value={value} onChange={setValue}>
      <Tabs.TabPanel title="标签 1">内容 1</Tabs.TabPanel>
      <Tabs.TabPanel title="标签 2">内容 2</Tabs.TabPanel>
      <Tabs.TabPanel title="标签 3">内容 3</Tabs.TabPanel>
      <Tabs.TabPanel title="标签 4">内容 4</Tabs.TabPanel>
    </Tabs>
  )
}
```

### 徽标用法

```tsx
import { Tabs } from "@taroify/core"

function BadgeTabs() {
  return (
    <Tabs>
      <Tabs.TabPanel title="标签 1" dot>
        内容 1
      </Tabs.TabPanel>
      <Tabs.TabPanel title="标签 2" badge={8}>
        内容 2
      </Tabs.TabPanel>
      <Tabs.TabPanel title="标签 3" badge="Hot">
        内容 3
      </Tabs.TabPanel>
      <Tabs.TabPanel title="标签 4" badge={<Success className="badge-icon" />}>
        内容 4
      </Tabs.TabPanel>
    </Tabs>
  )
}
```

```scss
.badge-icon {
  display: block;
  margin-left: 0;
  font-size: 10px * $hd;
  line-height: 16px * $hd;
  margin-right: 0;
}
```

### 通过标识匹配

在 `Tabs.TabPanel` 标签指定 `value` 属性的情况下，`Tabs.defaultValue` 的值为当前标签的 `value`。

```tsx
<Tabs defaultValue="a">
  <Tabs.TabPanel value="a" title="标签 1">
    内容 1
  </Tabs.TabPanel>
  <Tabs.TabPanel value="b" title="标签 2">
    内容 2
  </Tabs.TabPanel>
  <Tabs.TabPanel value="c" title="标签 3">
    内容 3
  </Tabs.TabPanel>
  <Tabs.TabPanel value="d" title="标签 4">
    内容 4
  </Tabs.TabPanel>
</Tabs>
```

### 标签栏滚动

标签数量超过 5 个时，标签栏可以在水平方向上滚动，切换时会自动将当前标签居中。

```tsx
<Tabs>
  <Tabs.TabPanel title="标签 1">内容 1</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 2">内容 2</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 3">内容 3</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 4">内容 4</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 5">内容 5</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 6">内容 6</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 7">内容 7</Tabs.TabPanel>
</Tabs>
```

### 禁用标签

设置 `disabled` 属性即可禁用标签，如果需要监听禁用标签的点击事件，可以在 `Tabs` 上监听`onClick` 事件。

```tsx
<Tabs>
  <Tabs.TabPanel title="标签 1">内容 1</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 2" disabled>
    内容 2
  </Tabs.TabPanel>
  <Tabs.TabPanel title="标签 3">内容 3</Tabs.TabPanel>
</Tabs>
```

### 样式风格

`Tabs` 支持两种样式风格：`line` 和`card`，默认为 `line` 样式，可以通过 `theme` 属性切换样式风格。

```tsx
<Tabs theme="card">
  <Tabs.TabPanel title="标签 1">内容 1</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 2">内容 2</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 3">内容 3</Tabs.TabPanel>
</Tabs>
```

### 点击事件

可以在 `Tabs` 上绑定 `onTabClick` 事件，事件传参为标签对应的标识符和标题。

```tsx
import { Tabs, Toast } from "@taroify/core"

function TabsWithTabClick() {
  return (
    <>
      <Toast id="toast" />
      <Tabs onTabClick={({ title }) => Toast.open(title)}>
        <Tabs.TabPanel title="标签 1">内容 1</Tabs.TabPanel>
        <Tabs.TabPanel title="标签 2">内容 2</Tabs.TabPanel>
        <Tabs.TabPanel title="标签 3">内容 3</Tabs.TabPanel>
      </Tabs>
      <Toast id="toast" />
    </>
  )
}
```

### 粘性布局

通过 `sticky` 属性可以开启粘性布局，粘性布局下，标签页滚动到顶部时会自动吸顶。

```tsx
<Tabs sticky>
  <Tabs.TabPanel title="标签 1">内容 1</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 2">内容 2</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 3">内容 3</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 4">内容 4</Tabs.TabPanel>
</Tabs>
```

### 自定义标签

通过 `title` 插槽可以自定义标签内容。

```tsx
import { Tabs } from "@taroify/core"
import { MoreOutlined } from "@taroify/icons"

function TabsWithCustomTitle() {
  return (
    <Tabs>
      <Tabs.TabPanel
        title={
          <>
            <MoreOutlined /> 标签 1
          </>
        }
      >
        内容 1
      </Tabs.TabPanel>
      <Tabs.TabPanel
        title={
          <>
            <MoreOutlined /> 标签 2
          </>
        }
      >
        内容 2
      </Tabs.TabPanel>
      <Tabs.TabPanel
        title={
          <>
            <MoreOutlined /> 标签 3
          </>
        }
      >
        内容 3
      </Tabs.TabPanel>
    </Tabs>
  )
}
```

```scss
.taroify-icon {
  margin-right: 5px * 2;
  vertical-align: -2px * 2;
}
```

### 切换动画

通过 `animated` 属性可以开启切换标签内容时的转场动画。

```tsx
<Tabs animated>
  <Tabs.TabPanel title="标签 1">内容 1</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 2">内容 2</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 3">内容 3</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 4">内容 4</Tabs.TabPanel>
</Tabs>
```

### 滑动切换

通过 `swipeable` 属性可以开启滑动切换标签页。

```tsx
<Tabs animated swipeable>
  <Tabs.TabPanel title="标签 1">内容 1</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 2">内容 2</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 3">内容 3</Tabs.TabPanel>
  <Tabs.TabPanel title="标签 4">内容 4</Tabs.TabPanel>
</Tabs>
```

## API

### Tabs Props

| 参数             | 说明                              | 类型                                                  | 默认值     |
| -------------- | ------------------------------- | --------------------------------------------------- | ------- |
| defaultValue   | 绑定默认选中标签的标识符                    | _number \| string_                                  | `0`     |
| value          | 绑定当前选中标签的标识符                    | _number \| string_                                  | `0`     |
| theme          | 样式风格类型，可选值为 `card`              | _string_                                            | `line`  |
| duration       | 动画时间，单位毫秒                       | _number \| string_                                  | `300`   |
| animated       | 是否开启切换标签内容时的转场动画                | _boolean_                                           | `false` |
| bordered       | 是否显示标签栏外边框，仅在 `type="line"` 时有效 | _boolean_                                           | `false` |
| ellipsis       | 是否省略过长的标题文字                     | _boolean_                                           | `true`  |
| sticky         | 是否使用粘性定位布局                      | _boolean \| \{ offsetTop }_                         | `false` |
| shrink         | 是否使用收缩布局                        | _booleans_                                          | `false` |
| swipeable      | 是否开启手势左右滑动切换                    | _boolean_                                           | `false` |
| swipeThreshold | 滚动阈值，标签数量超过阈值且总宽度超过标签栏宽度时开始横向滚动 | _number_                                            | `5`     |
| lazyRender     | 是否延迟渲染未展示的选项卡                   | _boolean_                                           | `false` |
| dot            | 是否展示为小红点                        | _boolean_                                           | `false` |
| badge          | 图标上徽标的内容                        | _boolean \| number \| string \| Badge \| ReactNode_ | -       |

### Tabs.Pane Props

| 参数       | 说明         | 类型                 | 默认值     |
| -------- | ---------- | ------------------ | ------- |
| value    | 标签值，作为匹配的值 | _number \| string_ | 标签的索引值  |
| title    | 标题         | _ReactNode_        | -       |
| disabled | 是否禁用标签     | _boolean_          | `false` |
| children | 标签面板内容     | _ReactNode_        | -       |

### Tabs Events

| 事件名        | 说明           | 回调参数                                |
| ---------- | ------------ | ----------------------------------- |
| onTabClick | 点击标签时触发      | _event : Tabs.TabEvent_             |
| onChange   | 当前激活的标签改变时触发 | _value: any, event : Tabs.TabEvent_ |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                           | 默认值                                             | 描述 |
| ---------------------------- | ----------------------------------------------- | -- |
| --tabs-active-color          | _var(--danger-color)_                           | -  |
| --tabs-wrap-height           | _44px \* $hd_                                   | -  |
| --tabs-card-height           | _30px \* $hd_                                   | -  |
| --tabs-card-margin           | _0 var(--padding-md)_                           | -  |
| --tabs-card-border-width     | _var(--border-width-base, $border-width-base))_ | -  |
| --tabs-card-border-color     | _var(--tabs-active-color)_                      | -  |
| --tabs-card-border-radius    | _var(--border-radius-sm)_                       | -  |
| --tabs-nav-background-color  | _var(--white)_                                  | -  |
| --tabs-line-width            | _40px \* $hd_                                   | -  |
| --tabs-line-height           | _3px \* $hd_                                    | -  |
| --tabs-line-border-radius    | _var(--tabs-line-height)_                       | -  |
| --tabs-line-background-color | _var(--tabs-active-color)_                      | -  |
| --tab-color                  | _var(--gray-7)_                                 | -  |
| --tab-padding                | _0 var(--padding-base)_                         | -  |
| --tab-font-size              | _var(--font-size-md)_                           | -  |
| --tab-line-height            | _var(--line-height-md)_                         | -  |
| --tab-active-color           | _var(--text-color)_                             | -  |
| --tab-active-font-weight     | _var(--font-weight-bold)_                       | -  |
| --tab-disabled-color         | _var(--gray-5)_                                 | -  |



---
url: https://taroify.com/components/tabbar/index.md
---

# Tabbar 标签栏

### 介绍

底部导航栏，用于在不同页面之间进行切换。

### 引入

```ts
import { Tabbar } from "@taroify/core"
```

## 代码演示

### 基础用法

```tsx
import { Tabbar } from "@taroify/core"
import { FriendsOutlined, HomeOutlined, Search, SettingOutlined } from "@taroify/icons"

function BasicTabbar() {
  return (
    <Tabbar>
      <Tabbar.TabItem icon={<HomeOutlined />}>标签</Tabbar.TabItem>
      <Tabbar.TabItem icon={<Search />}>标签</Tabbar.TabItem>
      <Tabbar.TabItem icon={<FriendsOutlined />}>标签</Tabbar.TabItem>
      <Tabbar.TabItem icon={<SettingOutlined />}>标签</Tabbar.TabItem>
    </Tabbar>
  )
}

```

### 通过标识匹配

在标签 `Tabbar.TabItem` 指定 `value` 属性的情况下，`value` 的值为当前标签的 `value`。

```tsx
import { Tabbar } from "@taroify/core"
import { FriendsOutlined, HomeOutlined, Search, SettingOutlined } from "@taroify/icons"

function KeyTabbar() {
  return (
    <Tabbar defaultValue="1">
      <Tabbar.TabItem value="1" icon={<HomeOutlined />}>
        标签
      </Tabbar.TabItem>
      <Tabbar.TabItem value="2" icon={<Search />}>
        标签
      </Tabbar.TabItem>
      <Tabbar.TabItem value="3" icon={<FriendsOutlined />}>
        标签
      </Tabbar.TabItem>
      <Tabbar.TabItem value="4" icon={<SettingOutlined />}>
        标签
      </Tabbar.TabItem>
    </Tabbar>
  )
}
```

### 徽标提示

设置 `badge` 属性为 `true` 后，会在图标右上角展示一个小红点；设置 `badge` 属性为 `number` 后，会在图标右上角展示相应的徽标。

```tsx
import { Badge, Tabbar } from "@taroify/core"
import { FriendsOutlined, HomeOutlined, Search, SettingOutlined } from "@taroify/icons"

function BadgeTabbar() {
  return (
    <Tabbar>
      <Tabbar.TabItem icon={<HomeOutlined />}>标签</Tabbar.TabItem>
      <Tabbar.TabItem badge icon={<Search />}>
        标签
      </Tabbar.TabItem>
      <Tabbar.TabItem badge="5" icon={<FriendsOutlined />}>
        标签
      </Tabbar.TabItem>
      <Tabbar.TabItem badge={<Badge content={100} max={99} />} icon={<SettingOutlined />}>
        标签
      </Tabbar.TabItem>
    </Tabbar>
  )
}
```

### 自定义颜色

通过 css 设置设置选中或未选择标签的颜色。

```tsx
import { Tabbar } from "@taroify/core"
import { FriendsOutlined, HomeOutlined, Search, SettingOutlined } from "@taroify/icons"

function TabbarWithCustomColor() {
  return (
    <Tabbar className="custom-color">
      <Tabbar.TabItem icon={<HomeOutlined />}>标签</Tabbar.TabItem>
      <Tabbar.TabItem icon={<Search />}>标签</Tabbar.TabItem>
      <Tabbar.TabItem icon={<FriendsOutlined />}>标签</Tabbar.TabItem>
      <Tabbar.TabItem icon={<SettingOutlined />}>标签</Tabbar.TabItem>
    </Tabbar>
  )
}
```

```scss
.custom-color {
  --tabbar-item-color: #000;
  --tabbar-item-active-color: #ee0a24;
}
```

## API

### Tabbar Props

| 参数           | 说明                                        | 类型        | 默认值     |
| ------------ | ----------------------------------------- | --------- | ------- |
| defaultValue | 默认选中标签的标识或索引值                             | _any_     | `0`     |
| value        | 当前选中标签的标识或索引值                             | _any_     | `0`     |
| bordered     | 是否显示外边框                                   | _boolean_ | `false` |
| fixed        | 是否固定在底部                                   | _boolean_ | `false` |
| safeArea     | 安全区域，可选值 `top` `bottom`，仅在`fixed=true`时有效 | _string_  | -       |
| placeholder  | 固定在底部时，是否在标签位置生成一个等高的占位元素                 | _boolean_ | `false` |

### Tabbar Events

| 事件名      | 说明      | 回调参数         |
| -------- | ------- | ------------ |
| onChange | 切换标签时触发 | _value: any_ |

### Tabbar.TabItem Props

| 参数       | 说明                                                   | 类型                                                  | 默认值 |
| -------- | ---------------------------------------------------- | --------------------------------------------------- | --- |
| value    | 标签值，作为匹配的标识符                                         | _any_                                               | -   |
| icon     | [图标](/components/icon.md)或[图片](/components/image.md) | _ReactNode_                                         | -   |
| badge    | 图标上徽标的内容                                             | _boolean \| number \| string \| Badge \| ReactNode_ | -   |
| children | 标签名                                                  | _ReactNode_                                         | -   |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                    | 默认值                   | 描述 |
| ------------------------------------- | --------------------- | -- |
| --tabbar-height                       | _50px \* $hd_         | -  |
| --tabbar-z-index                      | _1_                   | -  |
| --tabbar-background-color             | _var(--white)_        | -  |
| --tabbar-item-font-size               | _var(--font-size-sm)_ | -  |
| --tabbar-item-color                   | _var(--gray-7)_       | -  |
| --tabbar-item-line-height             | _1_                   | -  |
| --tabbar-item-icon-size               | _22px \* $hd_         | -  |
| --tabbar-item-margin-bottom           | _4px \* $hd_          | -  |
| --tabbar-item-active-color            | _var(--blue)_         | -  |
| --tabbar-item-active-background-color | _var(--white)_        | -  |



---
url: https://taroify.com/components/tree-select/index.md
---

# TreeSelect 分类选择

### 介绍

用于从一组相关联的数据集合中进行选择。

### 引入

```tsx
import { TreeSelect } from "@taroify/core"
```

## 代码演示

### 单选模式

`tabValue` 表示左侧高亮选项的索引，`value` 表示右侧高亮选项的 value。

```tsx
import { TreeSelect } from "@taroify/core"

function RadioTreeSelect() {
  const [tabValue, setTabValue] = useState(0)
  const [value, setValue] = useState(0)

  return (
    <TreeSelect tabValue={tabValue} value={value} onTabChange={setTabValue} onChange={setValue}>
      <TreeSelect.Tab title="浙江">
        <TreeSelect.Option value={0}>杭州</TreeSelect.Option>
        <TreeSelect.Option value={1}>温州</TreeSelect.Option>
        <TreeSelect.Option value={2} disabled>
          宁波
        </TreeSelect.Option>
        <TreeSelect.Option value={3}>义乌</TreeSelect.Option>
      </TreeSelect.Tab>
      <TreeSelect.Tab title="江苏">
        <TreeSelect.Option value={4}>南京</TreeSelect.Option>
        <TreeSelect.Option value={5}>无锡</TreeSelect.Option>
        <TreeSelect.Option value={6}>徐州</TreeSelect.Option>
        <TreeSelect.Option value={7}>苏州</TreeSelect.Option>
      </TreeSelect.Tab>
      <TreeSelect.Tab title="福建" disabled>
        <TreeSelect.Option value={8}>泉州</TreeSelect.Option>
        <TreeSelect.Option value={9}>厦门</TreeSelect.Option>
      </TreeSelect.Tab>
    </TreeSelect>
  )
}
```

### 多选模式

`value` 为数组格式时，可以选中多个右侧选项。

```tsx
import { TreeSelect } from "@taroify/core"

function MultiselectTreeSelect() {
  const [tabValue, setTabValue] = useState(0)
  const [value, setValue] = useState([0, 1])

  return (
    <TreeSelect tabValue={tabValue} value={value} onTabChange={setTabValue} onChange={setValue}>
      <TreeSelect.Tab title="浙江">
        <TreeSelect.Option value={0}>杭州</TreeSelect.Option>
        <TreeSelect.Option value={1}>温州</TreeSelect.Option>
        <TreeSelect.Option value={2} disabled>
          宁波
        </TreeSelect.Option>
        <TreeSelect.Option value={3}>义乌</TreeSelect.Option>
      </TreeSelect.Tab>
      <TreeSelect.Tab title="江苏">
        <TreeSelect.Option value={4}>南京</TreeSelect.Option>
        <TreeSelect.Option value={5}>无锡</TreeSelect.Option>
        <TreeSelect.Option value={6}>徐州</TreeSelect.Option>
        <TreeSelect.Option value={7}>苏州</TreeSelect.Option>
      </TreeSelect.Tab>
      <TreeSelect.Tab title="福建" disabled>
        <TreeSelect.Option value={8}>泉州</TreeSelect.Option>
        <TreeSelect.Option value={9}>厦门</TreeSelect.Option>
      </TreeSelect.Tab>
    </TreeSelect>
  )
}
```

### 自定义内容

可以通过 `TreeSelect.Tab` 组件自定义右侧区域的内容。

```tsx
import { TreeSelect } from "@taroify/core"

function TreeSelectWithCustomContent() {
  const [tabValue, setTabValue] = useState(0)

  return (
    <TreeSelect tabValue={tabValue} onTabChange={setTabValue}>
      <TreeSelect.Tab title="分组 1">
        <Image src="https://img.yzcdn.cn/vant/apple-1.jpg" />
      </TreeSelect.Tab>
      <TreeSelect.Tab title="分组 2">
        <Image src="https://img.yzcdn.cn/vant/apple-2.jpg" />
      </TreeSelect.Tab>
    </TreeSelect>
  )
}
```

### 徽标提示

设置 `badge` 属性后，会在图标右上角展示相应的徽标。

```tsx
import { TreeSelect } from "@taroify/core"

function BadgeTreeSelect() {
  const [tabValue, setTabValue] = useState(0)
  const [value, setValue] = useState(0)

  return (
    <TreeSelect tabValue={tabValue} value={value} onTabChange={setTabValue} onChange={setValue}>
      <TreeSelect.Tab badge title="浙江">
        <TreeSelect.Option value={0}>杭州</TreeSelect.Option>
        <TreeSelect.Option value={1}>温州</TreeSelect.Option>
        <TreeSelect.Option value={2} disabled>
          宁波
        </TreeSelect.Option>
        <TreeSelect.Option value={3}>义乌</TreeSelect.Option>
      </TreeSelect.Tab>
      <TreeSelect.Tab badge="5" title="江苏">
        <TreeSelect.Option value={4}>南京</TreeSelect.Option>
        <TreeSelect.Option value={5}>无锡</TreeSelect.Option>
        <TreeSelect.Option value={6}>徐州</TreeSelect.Option>
        <TreeSelect.Option value={7}>苏州</TreeSelect.Option>
      </TreeSelect.Tab>
      <TreeSelect.Tab title="福建" disabled>
        <TreeSelect.Option value={8}>泉州</TreeSelect.Option>
        <TreeSelect.Option value={9}>厦门</TreeSelect.Option>n
      </TreeSelect.Tab>
    </TreeSelect>
  )
}
```

## API

### Props

| 参数              | 说明                    | 类型                                             | 默认值           |
| --------------- | --------------------- | ---------------------------------------------- | ------------- |
| defaultTabValue | 左侧默认选中项的索引            | _number \| string_                             | `0`           |
| tabValue        | 左侧选中项的索引              | _number \| string_                             | `0`           |
| defaultValue    | 右侧默认选中项的 value，支持传入数组 | _number \| string \|<br>(number \| string)\[]_ | `0`           |
| value           | 右侧选中项的 value，支持传入数组   | _number \| string \|<br>(number \| string)\[]_ | `0`           |
| max             | 右侧项最大选中个数             | _number \| string_                             | `Infinity`    |
| activeIcon      | 自定义右侧栏选中状态的图标         | _ReactNode_                                    | `<Success />` |

### Events

| 事件名         | 说明         | 回调参数                                          |
| ----------- | ---------- | --------------------------------------------- |
| onTabChange | 点击左侧导航时触发  | _value: any, tabObject: TreeSelect.TabObject_ |
| onChange    | 点击右侧选择项时触发 | _any \| any\[]_                               |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                           | 默认值                                 | 描述 |
| -------------------------------------------- | ----------------------------------- | -- |
| --tree-select-font-size                      | _var(--font-size-md)_               | -  |
| --tree-select-sidebar-background-color       | _var(--background-color)_           | -  |
| --tree-select-content-background-color       | _var(--white)_                      | -  |
| --tree-select-tab-padding                    | _14px \* $hd var(--padding-sm)_     | -  |
| --tree-select-option-padding                 | _0 32px \* $hd 0 var(--padding-md)_ | -  |
| --tree-select-option-font-weight             | _var(--font-weight-bold)_           | -  |
| --tree-select-option-line-height             | _48px \* $hd_                       | -  |
| --tree-select-option-active-color            | _var(--danger-color)_               | -  |
| --tree-select-option-active-background-color | _var(--active-color)_               | -  |
| --tree-select-option-disabled-color          | _var(--gray-5)_                     | -  |
| --tree-select-option-icon-active-right       | _var(--padding-md, $padding-md)_    | -  |
| --tree-select-option-icon-active-font-size   | _16px \* $hd_                       | -  |



---
url: https://taroify.com/components/back-top/index.md
---

# BackTop 回到顶部

### 介绍

返回页面顶部的操作按钮。

请升级 `taroify` 到 >= `0.1.0-alpha.4` 版本来使用该组件。

### 引入

```tsx
import { BackTop } from "@taroify/core"
```

## 代码演示

### 基础用法

请滚动右侧的示例页面，当页面滚动 200px 时，右下角会出现返回顶部按钮。

```tsx
const list = [...Array(50).keys()]
;<View>
  <Cell.Group>
    {arr.map((v) => {
      return <Cell key={v}>{v}</Cell>
    })}
  </Cell.Group>
  <BackTop />
</View>
```

### 自定义位置

通过 right 和 bottom 属性来设置组件距离右侧和底部的位置。

```tsx
function CustomContent) {
  const list = [...Array(50).keys()];

  return (
    <View>
      <Cell.Group>
        {list.map((v) => {
          return (
            <Cell key={v}>{v}</Cell>
          )
        })}
      </Cell.Group>
      <BackTop />
    </View>
  )
}
```

### 自定义内容

使用 `children` 来自定义组件展示的内容。

```tsx
function CustomContent() {
  const list = [...Array(50).keys()]

  return (
    <View>
      <Cell.Group>
        {list.map((v) => {
          return <Cell key={v}>{v}</Cell>
        })}
      </Cell.Group>
      <BackTop>返回顶部</BackTop>
    </View>
  )
}
```

```css
.custom-back-top {
  width: 160px;
  font-size: 28px;
  text-align: center;
}
```

### 瞬间滚动

当设置 `immediate` 属性后，页面滚动的过程不再有过渡效果，而是瞬间滚动到顶部。

```tsx
function SetImmediate() {
  const list = [...Array(50).keys()]

  return (
    <View>
      <Cell.Group>
        {list.map((v) => {
          return <Cell key={v}>{v}</Cell>
        })}
      </Cell.Group>
      <BackTop immediate />
    </View>
  )
}
```

## API

### Props

| 参数        | 说明                   | 类型                 | 默认值     |
| --------- | -------------------- | ------------------ | ------- |
| right     | 距离页面右侧的距离，默认单位为 `px` | _number \| string_ | `30`    |
| bottom    | 距离页面底部的距离，默认单位为 `px` | _number \| string_ | `40`    |
| offset    | 滚动高度达到此参数值时才显示组件     | _number_           | `200`   |
| immediate | 是否瞬间滚动到顶部            | _boolean_          | `false` |
| zIndex    | 设置组件的 z-index 层级     | _number_           | `100`   |

### Event

| 事件      | 说明      | 回调参数                |
| ------- | ------- | ------------------- |
| onClick | 点击组件时触发 | _event:ITouchEvent_ |

### 注意

非 `H5` 项目需要显式调用 `onClick`

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                    | 默认值                  | 描述 |
| --------------------- | -------------------- | -- |
| --back-top-size       | _80px_               | -  |
| --back-top-icon-size  | _40px_               | -  |
| --back-top-right      | _60px_               | -  |
| --back-top-bottom     | _80px_               | -  |
| --back-top-z-index    | _100_                | -  |
| --back-top-text-color | _#fff_               | -  |
| --back-top-background | _var(--blue, $blue)_ | -  |



---
url: https://taroify.com/components/fixed-nav/index.md
---

# FixedNav 悬浮导航

### 介绍

伸缩式交互，用于快捷导航

请升级 `taroify` 到 >= `v0.1.2-alpha.0` 版本来使用该组件。

### 引入

```tsx
import { FixedNav } from "@taroify/core"
```

## 代码演示

### 基础用法

```tsx
const list = [
  {
    id: 1,
    text: "首页",
    icon: <WapHomeOutlined />,
  },
  {
    id: 2,
    text: "分类",
    icon: <AppsOutlined />,
  },
  {
    id: 3,
    text: "购物车",
    num: 2,
    icon: <ShoppingCartOutlined />,
  },
  {
    id: 4,
    text: "我的",
    icon: <UserOutlined />,
  },
]

const App = () => {
  const [open, setOpen] = useState(false)

  return <FixedNav open={open} onChange={setOpen} data={list} position={{ top: "150px" }} />
}
```

### 位置在左侧

```tsx
const list = [
  {
    id: 1,
    text: "首页",
    icon: <WapHomeOutlined />,
  },
  {
    id: 2,
    text: "分类",
    icon: <AppsOutlined />,
  },
  {
    id: 3,
    text: "购物车",
    num: 2,
    icon: <ShoppingCartOutlined />,
  },
  {
    id: 4,
    text: "我的",
    icon: <UserOutlined />,
  },
]

const App = () => {
  const [open, setOpen] = useState(false)

  return (
    <FixedNav
      open={open2}
      onChange={setOpen2}
      data={list}
      type="left"
      backdrop={false}
      position={{ top: "300px" }}
    />
  )
}
```

### 自定义内容

```tsx
const CustomerFixedNav = () => {
  const [open, setOpen] = useState(false)

  return (
    <FixedNav
      open={open}
      onChange={setOpen}
      type="left"
      backdrop={false}
      position={{ top: "400px" }}
      content={
        <>
          <GiftOutlined color="#FFF" />
          <span className="fixed-nav-text">{open ? "开" : "关"}</span>
        </>
      }
    >
      <ul className="taroify-fixed-nav_content customer">
        <li className="taroify-fixed-nav_content_item">我</li>
        <li className="taroify-fixed-nav_content_item">是</li>
        <li className="taroify-fixed-nav_content_item">自</li>
        <li className="taroify-fixed-nav_content_item">定</li>
        <li className="taroify-fixed-nav_content_item">义</li>
      </ul>
    </FixedNav>
  )
}
```

```scss
.fixed-nav-demo {
  .fixed-nav-text {
    color: #fff;
    line-height: 26px;
    width: 48px;
    font-size: 24px;
  }

  .taroify-fixed-nav_content {
    &.customer {
      border-radius: 0 50px 50px 0;
      margin: 0;
      padding-left: 160px;
      padding-right: 40px;
      right: auto;
    }

    &_item {
      align-items: center;
      color: #1a1a1a;
      display: flex;
      flex: 1;
      flex-direction: column;
      flex-shrink: 0;
      height: 100%;
      justify-content: center;
      min-width: 100px;
      position: relative;
      font-size: 28px;
    }
  }
}
```

## API

### Flex Props

| 参数           | 说明       | 类型                 | 默认值                             |
| ------------ | -------- | ------------------ | ------------------------------- |
| open         | 是否打开     | _boolean_          | `false`                         |
| data         | 悬浮导航内数据  | _FixedNavItem\[]_  | `[]`                            |
| backdrop     | 是否显示遮罩层  | _boolean_          | `true`                          |
| activeText   | 收起按钮文案   | _string_           | `收起导航`                          |
| inactiveText | 展开按钮文案   | _string_           | `快速导航`                          |
| type         | 悬浮导航方向   | _left \| right_    | `right`                         |
| position     | 悬浮导航垂直位置 | _FixedNavPosition_ | `{top: 'auto', bottom: 'auto'}` |
| content      | 自定义按钮    | _ReactNode_        | `-`                             |

### Events

| 事件名      | 说明       | 回调参数             |
| -------- | -------- | ---------------- |
| onChange | 展开收起按钮回调 | _value: boolean_ |
| onClick  | 选择之后触发   | _item_           |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                            | 默认值                      | 描述 |
| ----------------------------- | ------------------------ | -- |
| --fixed-nav-z-index           | _1010_                   | -  |
| --fixed-nav-z-content-index   | _1009_                   | -  |
| --fixed-nav-button-background | _var(--blue, $blue)_     | -  |
| --fixed-nav-button-font-size  | _12px \* $hd_            | -  |
| --fixed-nav-background-color  | _var(--white, $white)_   | -  |
| --fixed-nav-color             | _var(--gray-8, $gray-8)_ | -  |



---
url: https://taroify.com/components/action-bar/index.md
---

# ActionBar 动作栏

### 介绍

用于为页面相关操作提供便捷交互。

### 引入

```tsx
import { ActionBar } from "@taroify/commerce"
```

## 代码演示

### 基础用法

```tsx
import { ActionBar } from "@taroify/commerce"
import { CartOutlined, ChatOutlined, ShopOutlined } from "@taroify/icons"
import { Text } from "@tarojs/components"

function BasicActionBar() {
  return (
    <ActionBar>
      <ActionBar.IconButton>
        <ChatOutlined />
        <Text>客服</Text>
      </ActionBar.IconButton>
      <ActionBar.IconButton>
        <CartOutlined />
        <Text>购物车</Text>
      </ActionBar.IconButton>
      <ActionBar.IconButton>
        <ShopOutlined />
        <Text>店铺</Text>
      </ActionBar.IconButton>
      <ActionBar.Button>立即购买</ActionBar.Button>
    </ActionBar>
  )
}
```

### 徽标提示

在 ActionBar.IconButton 组件上设置 `badge` 属性后，会在图标右上角展示一个小红点；设置 `badge` 属性后，会在图标右上角展示相应的徽标。

```tsx
import { ActionBar } from "@taroify/commerce"
import { CartOutlined, ChatOutlined, ShopOutlined } from "@taroify/icons"
import { Text } from "@tarojs/components"

function ActionBarWithBadges() {
  return (
    <ActionBar>
      <ActionBar.IconButton badge>
        <ChatOutlined />
        <Text>客服</Text>
      </ActionBar.IconButton>
      <ActionBar.IconButton badge="5">
        <CartOutlined />
        <Text>购物车</Text>
      </ActionBar.IconButton>
      <ActionBar.IconButton badge="12">
        <ShopOutlined />
        <Text>店铺</Text>
      </ActionBar.IconButton>
      <ActionBar.ButtonGroup>
        <ActionBar.Button color="warning">加入购物车</ActionBar.Button>
        <ActionBar.Button color="danger">立即购买</ActionBar.Button>
      </ActionBar.ButtonGroup>
    </ActionBar>
  )
}
```

### 自定义图标颜色

通过设置图标的 `color` 属性可以自定义图标的颜色。

```tsx
import { ActionBar } from "@taroify/commerce"
import { CartOutlined, ChatOutlined, Star } from "@taroify/icons"
import { Text } from "@tarojs/components"

function ActionBarWithCustomIconButton() {
  return (
    <ActionBar>
      <ActionBar.IconButton>
        <ChatOutlined color="#ee0a24" />
        <Text>客服</Text>
      </ActionBar.IconButton>
      <ActionBar.IconButton>
        <CartOutlined />
        <Text>购物车</Text>
      </ActionBar.IconButton>
      <ActionBar.IconButton>
        <Star color="#ff5000" />
        <Text>已收藏</Text>
      </ActionBar.IconButton>
      <ActionBar.ButtonGroup>
        <ActionBar.Button color="danger">加入购物车</ActionBar.Button>
        <ActionBar.Button color="warning">立即购买</ActionBar.Button>
      </ActionBar.ButtonGroup>
    </ActionBar>
  )
}
```

### 自定义按钮颜色

通过 ActionBar.Button 的 `style` 属性可以自定义按钮的颜色，支持传入 `linear-gradient` 渐变色。

```tsx
import { ActionBar } from "@taroify/commerce"
import { CartOutlined, ChatOutlined } from "@taroify/icons"
import { Text } from "@tarojs/components"

function ActionBarWithCustomButton() {
  return (
    <ActionBar>
      <ActionBar.IconButton>
        <ChatOutlined />
        <Text>客服</Text>
      </ActionBar.IconButton>
      <ActionBar.IconButton>
        <CartOutlined />
        <Text>购物车</Text>
      </ActionBar.IconButton>
      <ActionBar.ButtonGroup>
        <ActionBar.Button style={{ background: "#be99ff" }}>加入购物车</ActionBar.Button>
        <ActionBar.Button style={{ background: "#7232dd" }}>立即购买</ActionBar.Button>
      </ActionBar.ButtonGroup>
    </ActionBar>
  )
}
```

## API

### ActionBar Props

| 参数          | 说明                        | 类型        | 默认值     |
| ----------- | ------------------------- | --------- | ------- |
| fixed       | 是否固定在底部                   | _boolean_ | `false` |
| safeArea    | 安全区域，可选值 `top` `bottom`   | _string_  | -       |
| placeholder | 固定在底部时，是否在标签位置生成一个等高的占位元素 | _boolean_ | `false` |

### ActionBar.ButtonGroup Props

| 参数    | 说明                 | 类型       | 默认值     |
| ----- | ------------------ | -------- | ------- |
| flex  | 列元素宽度              | _number_ | -       |
| shape | 按钮形状,可选值为 `square` | _string_ | `round` |

### ActionBar.Button Props

| 参数       | 说明                                                     | 类型                                                              | 默认值      |
| -------- | ------------------------------------------------------ | --------------------------------------------------------------- | -------- |
| shape    | 按钮形状,可选值为 `square`                                     | _string_                                                        | `round`  |
| color    | 按钮颜色,可选值为 `primary` `info` `success` `warning`         | _string_                                                        | `danger` |
| icon     | 左侧[图标](/components/icon.md)或[图片](/components/image.md) | _ReactNode_                                                     | -        |
| disabled | 是否禁用按钮                                                 | _boolean_                                                       | `false`  |
| loading  | 是否显示为加载状态                                              | _boolean \| [LoadingProps](/components/loading/index.md#props)_ | `false`  |

### ActionBar.IconButton Props

| 参数    | 说明   | 类型                                                             | 默认值 |
| ----- | ---- | -------------------------------------------------------------- | --- |
| badge | 徽标内容 | _boolean \| number \| string \| [Badge](/components/badge.md)_ | -   |

## 主题定制

### 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider](/components/config-provider/index.md) 组件。

| 名称                                      | 默认值                            | 描述 |
| --------------------------------------- | ------------------------------ | -- |
| --action-bar-color                      | _var(--gray-6)_                | -  |
| --action-bar-height                     | _50px \* $hd_                  | -  |
| --action-bar-background                 | _var(--action-bar-background)_ | -  |
| --action-bar-button-height              | _40px \* $hd_                  | -  |
| --action-bar-button-color               | _var(--white)_                 | -  |
| --action-bar-button-font-size           | _var(--font-size-md)_          | -  |
| --action-bar-button-gradient-red        | _var(--gradient-red)_          | -  |
| --action-bar-button-gradient-orange     | _var(--gradient-orange)_       | -  |
| --action-bar-button-border-radius-md    | _var(--border-radius-md)_      | -  |
| --action-bar-button-border-radius-max   | _var(--border-radius-max)_     | -  |
| --action-bar-icon-button-color          | _var(--gray-7)_                | -  |
| --action-bar-icon-button-font-size      | _var(--font-size-xs)_          | -  |
| --action-bar-icon-button-width          | _48px \* $hd_                  | -  |
| --action-bar-icon-button-height         | _100%_                         | -  |
| --action-bar-icon-button-icon-font-size | _18px \* $hd_                  | -  |



---
url: https://taroify.com/hooks/index.md
---

# @taroify/hooks

### 介绍

Taroify 内置了一组 hooks，对于安装了 `@taroify/core` 的项目，可以直接使用这些 hooks 进行开发。

### 示例

下面是一个 Taroify Hooks 的用法示例，我们从 `@taroify/hooks` 这个包中引入 `useCascader` 方法，然后进行调用，即可获取得一个级联对象。

```ts
import { useCascader } from "@taroify/hooks";
import area from "./area"

const [value, setValue] = useState<string[]>([])
const { columns } = useCascader({ value, depth: 3, options: area })

console.log(columns); // -> options[]
```

### API 列表

下面是 `@taroify/hooks` 对外提供的所有 Hooks，点击名称可以查看详细介绍：

| 名称                                          | 描述          |
| ------------------------------------------- | ----------- |
| [useCascader](/hooks/use-cascader/index.md) | 监听点击元素外部的事件 |



---
url: https://taroify.com/hooks/use-cascader/index.md
---

# useCascader

### 介绍

用于创建级联操作对象。

## 代码演示

### 基本用法

```tsx
import { useCascader } from "@taroify/hooks"
import area from "./area"

const [value, setValue] = useState<string[]>([])
const { columns } = useCascader({ value, depth: 3, options: area })

console.log(columns); // -> options[]
```

```ts
// area
export default [
  {
    label: "浙江省",
    value: "330000",
    children: [
      {
        label: "杭州市",
        value: "330100",
        children: [
          {
            label: "上城区",
            value: "330102",
          },
          {
            label: "下城区",
            value: "330103",
          },
          {
            label: "江干区",
            value: "330104",
          },
        ],
      },
      {
        label: "宁波市",
        value: "330200",
        children: [
          {
            label: "海曙区",
            value: "330203",
          },
          {
            label: "江北区",
            value: "330205",
          },
          {
            label: "北仑区",
            value: "330206",
          },
        ],
      },
      {
        label: "温州市",
        value: "330300",
        children: [
          {
            label: "鹿城区",
            value: "330302",
          },
          {
            label: "龙湾区",
            value: "330303",
          },
          {
            label: "瓯海区",
            value: "330304",
          },
        ],
      },
    ],
  },
]
```

## API

### 类型定义

```ts
interface CascaderColumn {
  value?: any
  label?: ReactNode
  disabled?: boolean
}

interface CascaderOption extends CascaderColumn {
  children?: CascaderOption[]
}

interface UseCascaderOptions {
  value?: any[]
  depth?: number
  options: CascaderOption[]
}

interface CascaderObject {
  columns: CascaderOption[][]
}

function useCascader(options: UseCascaderOptions): CascaderObject
```

### 参数

| 参数      | 说明  | 类型                   | 默认值 |
| ------- | --- | -------------------- | --- |
| options | 配置项 | _UseCascaderOptions_ | 见下表 |

### UseCascaderOptions

| 参数      | 说明            | 类型                  | 默认值 |
| ------- | ------------- | ------------------- | --- |
| value   | 选中的级联 value 值 | _any\[]_            | -   |
| depth   | 级联深度          | _number_            | `0` |
| options | 级联项数组         | _CascaderOption\[]_ | -   |



---
url: https://taroify.com/agents/index.md
---

# For Agents

本页面为 AI 编程 Agent 提供一段可直接使用的提示词，并说明如何通过 Agent Skill、CLI、
MCP 和 LLMs.txt 获取准确的 Taroify 组件知识。

## 复制这段 Prompt

将下面的内容复制到 Agent 对话、项目规则或自动化流程中：

```text
你正在为 Taro React 项目使用 Taroify。你训练数据中的组件 API、事件、子组件和主题变量
可能与当前版本不同。在编写或修改代码前，请先阅读
https://taroify.com/agents/index.md
以及
https://raw.githubusercontent.com/mallfoundry/taroify/main/packages/cli/skills/taroify/SKILL.md，
查询真实 API 和示例，不要猜测组件用法。

如果可以安装 Agent Skill，请运行：
npm install -D @taroify/cli
npx skills add ./node_modules/@taroify/cli/skills/taroify

如果存在 taroify_* MCP 工具，请优先使用 MCP；否则使用 Taroify CLI，并在程序化查询时
添加 --format json。
```

## Agent 可以获得什么

### Agent Skill — 工作流与约束

`@taroify/cli` 随包提供 Taroify Agent Skill。它会要求 Agent 在写代码前搜索组件、检查
Props 和子组件、读取示例，并在定制样式前查询公开主题变量。

```bash
npm install -D @taroify/cli
npx skills add ./node_modules/@taroify/cli/skills/taroify
```

Skill 支持 Claude Code、Cursor、VS Code、Codex 等兼容 Agent Skills 的工具。完整的
Skill 内容可以在
[GitHub](https://raw.githubusercontent.com/mallfoundry/taroify/main/packages/cli/skills/taroify/SKILL.md)
查看。

### CLI — 离线组件知识

[Taroify CLI](/cli/index.md) 将组件、Hooks、API、示例、完整 Demo 页面和主题变量随 npm 包分发，
查询时不需要网络或 API Key。

```bash
npx -y @taroify/cli search 上传 --format json
npx -y @taroify/cli info Button.Group --format json
npx -y @taroify/cli demo Button --full --format json
npx -y @taroify/cli token Button --format json
```

### MCP Server — IDE 集成

[Taroify MCP](/mcp/index.md) 将同一份离线 Catalog 暴露为六个只读工具，并提供文档、Demo
Resources 和任务 Prompts。支持 MCP 的 Agent 可以自动查询所需内容，不必由用户手动执行命令。

```json
{
  "mcpServers": {
    "taroify": {
      "command": "npx",
      "args": ["-y", "@taroify/cli", "mcp"]
    }
  }
}
```

### LLMs.txt — 在线 Markdown 文档

无法安装 Skill 或 MCP 时，可以直接把官网 Markdown 文档提供给 Agent。

| 文件                                                          | 说明                   |
| ----------------------------------------------------------- | -------------------- |
| [llms.txt](https://taroify.com/llms.txt)                    | 官网文档索引，适合先定位相关页面     |
| [llms-full.txt](https://taroify.com/llms-full.txt)          | 完整官网文档，适合离线索引或全局分析   |
| [Button 文档](https://taroify.com/components/button/index.md) | 单个组件的介绍、示例、API 和主题变量 |

更多读取方式请参考 [LLMs.txt 文档](/llms/index.md)。

## 推荐工作流

Agent 编写 Taroify 代码时，建议按以下顺序工作：

1. 不确定组件名称时，按使用场景执行 `search` 或按分类执行 `list`。
2. 编码前使用 `info` 确认 Props、事件、子组件和引入方式。
3. 使用 `demo` 获取最小示例；需要完整 imports 和页面上下文时添加 `--full`。
4. 只有结构化 API 和示例不足时，才使用 `doc` 读取完整文档。
5. 定制样式前使用 `token` 查询 `ConfigProvider` key 和 CSS 变量。

使用 MCP 时，对应调用 `taroify_search`、`taroify_list`、`taroify_info`、
`taroify_demo`、`taroify_doc` 和 `taroify_token`。

## 使用约束

- 不要猜测 Taroify 组件名、Props、枚举值、事件或子组件。
- 区分 Taroify Props 与继承的 Taro 原生能力；平台支持由目标 Taro 适配器决定。
- 只从 `@taroify/core`、`@taroify/icons`、`@taroify/hooks` 或
  `@taroify/commerce` 的公开入口引入。
- 优先使用 `ConfigProvider` 配置或公开 CSS 变量，不依赖内部选择器和硬编码组件值。
- 示例采用 Taro React 语义；除非目标明确为 H5，否则不要替换为 Web 专用 DOM 元素。



---
url: https://taroify.com/llms/index.md
---

# LLMs.txt

Taroify 为 AI 编码助手提供结构化的 Markdown 文档入口。你可以先通过 `llms.txt` 了解官网内容，再按需读取组件、Hooks 或指南页面，避免从完整 HTML 中提取正文。遵循 [llms.txt 规范](https://llmstxt.org/)。

## 可用资源

| 资源   | 地址                                                          | 用途                          |
| ---- | ----------------------------------------------------------- | --------------------------- |
| 文档索引 | [llms.txt](https://taroify.com/llms.txt)                    | 按官网导航列出页面标题、摘要和 Markdown 地址 |
| 完整文档 | [llms-full.txt](https://taroify.com/llms-full.txt)          | 在单个文件中提供全部官网文档，适合离线索引或全局分析  |
| 单页文档 | [Button 文档](https://taroify.com/components/button/index.md) | 只读取一个组件的介绍、示例、API 和主题变量     |

每个官网文档页面都有对应的 Markdown 文件。例如：

```text
https://taroify.com/quickstart/index.md
https://taroify.com/components/form/index.md
https://taroify.com/hooks/use-cascader/index.md
```

## 推荐读取方式

为了减少无关上下文，建议 AI 工具按以下顺序读取：

1. 先读取 `llms.txt`，确定与任务相关的指南、组件或 Hook。
2. 根据索引读取一个或多个单页 `.md` 文档。
3. 只有在离线建立知识库、跨组件分析或无法按需抓取时，才读取 `llms-full.txt`。

例如，让 AI 使用 Taroify 编写页面时可以提供以下指令：

```text
先阅读 https://taroify.com/llms.txt，
再按需读取其中的组件 Markdown 文档。
请只使用文档中存在的 Taroify 组件、Props、事件和主题变量，
为 Taro React 项目生成代码。
```

查询单个组件时可以直接指定页面：

```text
阅读 https://taroify.com/components/button/index.md，
根据文档说明使用 Taroify Button 完成提交按钮和加载状态。
```

## 在 AI 工具中使用

只要 AI 工具能够读取 URL，就可以把 `llms.txt` 地址直接放入提示词。对于支持文档知识源
或持久规则的工具，也可以将同一地址保存为项目级文档入口。

需要避免每次手动提供 URL 时，可以将下面的规则加入项目的 Agent 指令：

```text
阅读 `https://taroify.com/llms.txt` 并理解 Taroify 组件库，
在编写 Taroify 代码时使用这些知识。
```



---
url: https://taroify.com/cli/index.md
---

# Taroify CLI

`@taroify/cli` 是面向开发者和 AI 编码助手的离线组件知识 CLI。它将 Taroify
组件、Hooks、API、示例、完整 Demo 页面和主题变量随 npm 包分发，查询时不需要网络或
API Key。

发布包将结构化元数据、Markdown 文档与 Demo 源码分别存放在 `data/meta.json`、
`data/docs/` 和 `data/demos/`，查询时按需读取；CLI 和 MCP 不请求官网或外部接口。

## 直接查询组件

推荐通过 `npx` 使用，无需全局安装：

```bash
npx -y @taroify/cli list
npx -y @taroify/cli search 上传
npx -y @taroify/cli info Button
```

也可以全局安装：

```bash
npm install -g @taroify/cli
taroify info Button
```

CLI 需要 Node.js 18.18 或更高版本。

## 按场景搜索

不知道组件名称时，可以使用中文场景词搜索完整文档：

```bash
taroify search 上传
taroify search 地址选择
taroify search 下拉刷新 --limit 5
```

也可以按分类、包或条目类型浏览：

```bash
taroify list --category form
taroify list --package @taroify/commerce
taroify list --kind hook
```

## 查询 API

`info` 返回组件的引入方式、Props、子组件 API、事件、实例方法、示例列表和主题变量数量：

```bash
taroify info Button
taroify info Button.Group
taroify info useCascader
```

组件名称大小写不敏感。未命中时会返回拼写建议：

```bash
taroify info Buttn
# 你是否想找：Button
```

## 获取示例

省略示例名时列出文档中的全部代码片段：

```bash
taroify demo Button
taroify demo Button demo1
```

需要 import、页面结构和所有演示上下文时，获取仓库中的完整 Taro 页面：

```bash
taroify demo Button --full
```

## 查询文档与主题变量

```bash
taroify doc Calendar
taroify token
taroify token Button
```

`token` 同时返回 CSS 变量、对应的 `ConfigProvider` key、默认值和说明。主题定制时应优先
使用这些公开变量。

## 全局参数

| 参数                          | 说明                                      | 默认值    |
| --------------------------- | --------------------------------------- | ------ |
| `--format, -f <text\|json>` | 设置查询命令的输出格式；AI Agent 和自动化脚本应优先使用 `json` | `text` |
| `--help, -h`                | 显示 CLI 或子命令的帮助信息                        | -      |
| `--version, -v`             | 打印 CLI 版本号                              | -      |

当前离线 Catalog 仅包含中文文档，因此暂不支持 `--lang, -l <zh|en>`。`search` 子命令中的
`-l` 是 `--limit` 的缩写，用于限制搜索结果数量。

## 命令参考

| 命令                                       | 作用                          |
| ---------------------------------------- | --------------------------- |
| `list [--category] [--package] [--kind]` | 列出组件、指南与 Hooks              |
| `search <query> [-l, --limit]`           | 搜索名称、分类、包和完整文档              |
| `info <entry>`                           | 查询结构化 API，支持 `Button.Group` |
| `doc <entry>`                            | 返回完整中文 Markdown 文档          |
| `demo <entry> [name]`                    | 列出或获取文档代码片段                 |
| `demo <entry> --full`                    | 返回完整 Taro Demo 页面           |
| `token [entry]`                          | 查询全局或组件级主题变量                |
| `mcp`                                    | 启动 stdio MCP Server         |

AI Agent 和自动化脚本应使用 JSON：

```bash
taroify info Button --format json
```

成功响应：

```json
{
  "ok": true,
  "data": {}
}
```

失败响应会使用非零退出码，并返回稳定错误码和可选建议：

```json
{
  "ok": false,
  "error": {
    "code": "COMPONENT_NOT_FOUND",
    "message": "未找到 Taroify 条目「Buttn」。",
    "suggestions": ["Button"]
  }
}
```

## 安装 Agent Skill

CLI 随包提供 Taroify Agent Skill，约束 Agent 在编写组件代码前查询真实 API 和示例：

```bash
npm install -D @taroify/cli
npx skills add ./node_modules/@taroify/cli/skills/taroify
```

Skill 支持 Claude Code、Cursor、VS Code、Codex 等兼容 Agent Skills 的工具。

## 接入 MCP

需要让 IDE 自动调用 Taroify 查询工具时，继续阅读 [MCP 配置](/mcp/index.md)。



---
url: https://taroify.com/mcp/index.md
---

# Taroify MCP

Taroify MCP 通过 `@taroify/cli` 的只读 stdio Server，将与 CLI 相同的离线 Catalog
提供给 Claude Code、Cursor、VS Code、Codex 等 AI 编码工具。

MCP 不读取当前项目文件、不访问外部网络，也不执行修改操作。

## 配置客户端

Claude Code、Cursor 和 VS Code 可以使用以下配置：

```json
{
  "mcpServers": {
    "taroify": {
      "command": "npx",
      "args": ["-y", "@taroify/cli", "mcp"]
    }
  }
}
```

Codex 在 `~/.codex/config.toml` 中配置：

```toml
[mcp_servers.taroify]
command = "npx"
args = ["-y", "@taroify/cli", "mcp"]
```

重新启动客户端后，可以让 Agent 执行类似任务：

- “查一下 Taroify Button.Group 的 Props”
- “搜索适合文件上传的组件并生成 Taro 页面”
- “读取 Calendar 的完整文档”
- “用公开主题变量修改 Button 的主色和圆角”

## 可用工具

| 工具               | 作用                      |
| ---------------- | ----------------------- |
| `taroify_list`   | 按分类、包或类型列出组件、指南与 Hooks  |
| `taroify_search` | 按名称、分类和完整文档搜索           |
| `taroify_info`   | 获取组件、子组件或 Hook 的结构化 API |
| `taroify_doc`    | 获取完整中文 Markdown 文档      |
| `taroify_demo`   | 列出/获取示例，或返回完整 Demo 页面   |
| `taroify_token`  | 查询全局或组件级主题变量            |

工具返回与 CLI `--format json` 一致的 `ok/data` 或 `ok/error` 结构。所有工具都声明为
只读、幂等和封闭世界查询。

## Resources

MCP 客户端可以枚举并读取以下资源：

- `taroify://catalog`：Catalog 版本、统计和分类摘要
- `taroify://tokens/global`：全局主题变量
- `taroify://entries/{entry}/doc`：指定条目的 Markdown 文档
- `taroify://entries/{entry}/demo/{name}`：指定代码示例

服务同时发布文档与 Demo 的 Resource Template，支持客户端按需发现。

## Prompts

| Prompt                   | 作用                          |
| ------------------------ | --------------------------- |
| `taroify-expert`         | 组件选型、API 查询、排错和主题定制         |
| `taroify-page-generator` | 查询真实组件知识后生成完整 Taro React 页面 |

两个 Prompt 都要求 Agent 先查后写，并区分 Taroify Props 与 Taro 原生平台能力。

## 从 `@taroify/mcp` 迁移

旧配置仍可以继续运行独立的 `@taroify/mcp`：

```json
{
  "mcpServers": {
    "@taroify/mcp": {
      "command": "npx",
      "args": ["-y", "@taroify/mcp"]
    }
  }
}
```

新项目建议切换到 `@taroify/cli mcp`。CLI、命令行查询、MCP、Resources 和 Agent Skill
共用主仓库构建的同一份 Catalog，可以避免独立数据快照与组件版本不同步。



---
url: https://taroify.com/index.md
---

# Taroify

> 轻量、可靠的小程序端 Taro React UI 组件库

面向多端应用的高质量组件与工具，提供完整类型提示、主题定制和一致的交互体验。

`pnpm add @taroify/core`