# 蜂群UI组件文档
> 适用蜂群业务UI组件库
- [蜂群UI组件文档](https://newtest-fq-ui.ifengqun.com/index.md)
## markdown-page
You don't need React to write simple standalone pages.
- [Markdown page example](https://newtest-fq-ui.ifengqun.com/markdown-page.md): You don't need React to write simple standalone pages.
## docs
### components-pro
- [GoodsCard 组件](https://newtest-fq-ui.ifengqun.com/docs/components-pro/GoodsCard 商品卡片.md): 介绍
- [Price 价格](https://newtest-fq-ui.ifengqun.com/docs/components-pro/Price 价格.md): 介绍
- [Search 组件](https://newtest-fq-ui.ifengqun.com/docs/components-pro/Search 搜索框.md): 介绍
- [VideoPlayer 视频播放器](https://newtest-fq-ui.ifengqun.com/docs/components-pro/VideoPlayer 视频播放器.md): 介绍
### components
- [Button 组件](https://newtest-fq-ui.ifengqun.com/docs/components/basic/Button 按钮.md): 介绍
- [Gird 栅格](https://newtest-fq-ui.ifengqun.com/docs/components/basic/Grid 栅格.md): 介绍
- [Icon 组件](https://newtest-fq-ui.ifengqun.com/docs/components/basic/Icon 图标.md): 介绍
- [SpriteIcon 组件](https://newtest-fq-ui.ifengqun.com/docs/components/basic/SpriteIcon 精灵图.md): 介绍
- [Typo 组件](https://newtest-fq-ui.ifengqun.com/docs/components/basic/Typo 字体.md): 介绍
- [Checkbox 多选框](https://newtest-fq-ui.ifengqun.com/docs/components/form/Checkbox 复选框.md): 介绍
- [FQForm 表单](https://newtest-fq-ui.ifengqun.com/docs/components/form/FQForm 表单.md): 介绍
- [Input 输入框(新版)](https://newtest-fq-ui.ifengqun.com/docs/components/form/Input 输入框.md): 用于接收用户文本、数字等内容输入，支持多种场景和样式扩展。
- [Radio 单选框](https://newtest-fq-ui.ifengqun.com/docs/components/form/Radio 单选框.md): 介绍
- [Stepper 步进器](https://newtest-fq-ui.ifengqun.com/docs/components/form/Stepper 步进器.md): 用于在一定范围内输入、调整数字，支持数量增减、禁用、步长、边框/无边框、Din字体等多种功能。
- [Switch 开关](https://newtest-fq-ui.ifengqun.com/docs/components/form/Switch 开关.md): 介绍
- [TextArea 输入框（新版）](https://newtest-fq-ui.ifengqun.com/docs/components/form/TextArea 输入框.md): 用于多行文本输入，支持字数统计、自动高度、错误提示、无边框等多种场景。
- [Badge 徽标数](https://newtest-fq-ui.ifengqun.com/docs/components/presentation/Badge 徽标数.md): 介绍
- [Card 组件](https://newtest-fq-ui.ifengqun.com/docs/components/presentation/Card 卡片.md): 介绍
- [Tag 标签](https://newtest-fq-ui.ifengqun.com/docs/components/presentation/Tag 标签.md): 介绍
- [FQWaterMark 水印组件](https://newtest-fq-ui.ifengqun.com/docs/components/reaction/FQWaterMark 水印.md): 介绍
- [Modal 组件](https://newtest-fq-ui.ifengqun.com/docs/components/reaction/Modal 对话框.md): 介绍
- [NoticeBar 组件](https://newtest-fq-ui.ifengqun.com/docs/components/reaction/NoticeBar 信息通知栏.md): 介绍
### guide
- [主题定制](https://newtest-fq-ui.ifengqun.com/docs/guide/主题定制.md): 介绍
- [快速上手](https://newtest-fq-ui.ifengqun.com/docs/guide/快速上手.md): 使用前准备
- [色彩](https://newtest-fq-ui.ifengqun.com/docs/guide/色彩.md): 色彩体系主要定义了设计中的基础色板。
---
# Full Documentation Content
# Markdown page example
You don't need React to write simple standalone pages.
---
# GoodsCard 组件
## 介绍[](#介绍 "介绍的直接链接")
商品卡片，常见于首页、搜索页，用于展示单个商品信息，包括商品图片、商品价格等。
> 👉🏻 [项目组件使用备注](https://txckvfwee45.feishu.cn/sheets/Fz7ss7dmwhPliNt9ygycQxp7nYb)
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQGoodsCard } from '@fq/fq-weapp-ui-pro';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui-pro/dist/styles/components/goods-card.scss';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
}
/>
```
```
}
/>
```
```
}
/>
```
### 自定义排行榜标签 & 促销标签[](#自定义排行榜标签--促销标签 "自定义排行榜标签 & 促销标签的直接链接")
```
{
console.log('排行榜点击');
}}
/>
```
### 自定义促销相关描述[](#自定义促销相关描述 "自定义促销相关描述的直接链接")
```
```
### 自定义营销标签[](#自定义营销标签 "自定义营销标签的直接链接")
```
}
/>
```
### 自定义营销标签-会员价[](#自定义营销标签-会员价 "自定义营销标签-会员价的直接链接")
#### 非会员[](#非会员 "非会员的直接链接")
```
}
/>
#### 会员
}
/>
```
### 售罄卡片[](#售罄卡片 "售罄卡片的直接链接")
```
```
## API[](#api "API的直接链接")
### 属性[](#属性 "属性的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------- |
| badgeNum | 左上角序号 | number | - | |
| coupon | 优惠券 | `FQCardCoupon[]` | - | `v0.6.0` 旧 `string[]` / `[string, string][]` 格式已移除 |
| formatOriginalPrice | 格式化原价(仅在垂直布局大卡片时生效) | `(originalPrice: string \| number) => string \| number` | `最低到手¥xxx起` | `v0.2.7` |
| goodsBadge | 商品徽章 | ReactNode | - | `v0.2.7` |
| goodsName | 商品名称 | string | - | |
| goodsNameLine | 商品名称行数，默认2，即2行省略 | `number` / `string` | 2 | |
| goodsNameOverflow | 商品名称溢出方式 | `ellipsis` / `clip` | `clip` | |
| isMember | 是否会员，只有设置了showMemberLabel才生效 | boolean | `false` | |
| isNoStock | 是否无库存 | boolean | `false` | |
| isNoStock | 是否无库存 | boolean | `false` | |
| marketingLabel | 营销标签 | `{ labelText?: string, labelImage?: string, dateText?: string, salesVolume?: string }` | - | |
| marketingLabelProps | 营销标签配置 | `{ bgUrl?: string }` | - | |
| niceRate | 惊艳度 | `number` / `string` | - | |
| originalPrice | 原价 | `number` / `string` | - | |
| price | 价格 | `number` / `string` | - | |
| priceAfterText | 价格后的文案 | string | - | `v0.2.7` 中已移除 |
| priceProps | 价格配置，[price]() props | `Omit` | - | `v0.2.7` |
| promoLabelProps | 促销标签配置 | `{ bgColor?: string; color?: string; icon?: string }` | - | |
| promoLabelText | 促销标签文案 | string | - | |
| rankingLabelText | 排名信息 | string | - | |
| reviewCount | 评价数量 | `number` / `string` | - | |
| salesVolume | 销量 | `number` / `string` | - | |
| sellingPoint | 卖点 | string | - | |
| customMarketingText | 自定义营销文案（如果已有的销量那一行不满足样式，可使用当前参数） | string | - | |
| showMarketingLabel | 是否显示营销标签 | boolean | `false` | |
| showPromoLabel | 是否显示促销标签 | boolean | `false` | |
| showRankingLabel | 是否显示排名 | boolean | `false` | |
| showMemberLabel | 是否显示会员标签 | boolean | `false` | |
| onRankingLabelClick | rankingLabel 点击事件 | `() => void` | - | |
| vipPrice | 会员价文案, 只有设置了showMemberLabel，并且isMember=false才展示 | `string` | - | |
更多配置参考\[FQCard]\(../components/presentation/Card 卡片.mdx)。
### FQCardCoupon[](#fqcardcoupon "FQCardCoupon的直接链接")
优惠券类型，`v0.3.0` 新增。
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ----------- | -------------- | ------------- | ------ | ---- |
| prefix | 优惠券前缀 | string | - | |
| prefixStyle | 优惠券前缀样式 | CSSProperties | - | |
| text | 优惠券文案 | string | - | |
| style | 优惠券样式 | CSSProperties | - | |
> 从使用者角度，传入的方式相比之前的复杂了；但因业务扩展，这种方式可以更好扩展卡片优惠券标签的样式。如：直播间小绿车-直播间专享优惠券。
### 插槽[](#插槽 "插槽的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ---------- | ---------------------- | --------- | ------ | -------- |
| goodsBadge | 商品徽章 | ReactNode | - | `v0.2.7` |
| priceSlot | 原有 FQCard price 插槽 | ReactNode | - | `v0.5.1` |
其余与\[FQCard]\(../components/presentation/Card 卡片.mdx)插槽一致，传入时将覆盖原位置预插入的元素。
### GoodsCard.ComposeButton[](#goodscardcomposebutton "GoodsCard.ComposeButton的直接链接")
卡片组合购物按钮组件，常用于商品大卡片。
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------ | ----------- | ---- |
| buyBtnProps | 购买按钮 [button]() props | object | - | |
| buyText | 购买按钮文本 | ReactNode | '购买' | |
| cartBtnProps | 购物车按钮 [button]() props | object | - | |
| cartText | 购物车按钮文本 | ReactNode | `` | |
| disabled | 按钮禁用 | boolean | false | |
| onAddCart | 点击购物车按钮时回调 | `(event: ITouchEvent) => void` | - | |
| onBuy | 点击购买按钮时回调 | `(event: ITouchEvent) => void` | - | |
| onClick | 点击按钮时回调 | `(event: ITouchEvent) => void` | - | |
### GoodsCard.PlusButton[](#goodscardplusbutton "GoodsCard.PlusButton的直接链接")
卡片按钮组件，常用于商品小卡片。
属性和事件和 `FQButton` 一致，更多配置参考 [Button 组件]()。
## FAQ[](#faq "FAQ的直接链接")
**如果卡片右下方的按钮，预设的两种按键 `GoodsCard.ComposeButton`、 `GoodsCard.PlusButton` 满足不了业务场景时，如何自定义按钮？**
你可以通过 `actionArea` 传入自定义组件来定义。
**假设营销标签模块、或促销相关描述的布局已经和 `FQGoodsCard` 差异比较大时？**
你可以通过传入 `FQCard` 相关的插槽，进行覆盖 `FQGoodsCard` 预插入内容，因为 `FQGoodsCard` 继承至 `FQCard`。
**假设 `salesVolume` 销量、 `niceRate` 惊艳度的文案样式已经不能满足业务场景，如何自定义文案和样式？**
你可以通过 `customMarketingText` 传入自定义组件来定义。
---
# Price 价格
## 介绍[](#介绍 "介绍的直接链接")
价格组件，用于展示商品价格信息。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQPrice } from '@fq/fq-weapp-ui-pro';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui-pro/dist/styles/components/price.scss';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
```
### 修改symbol符号 & 位置[](#修改symbol符号--位置 "修改symbol符号 & 位置的直接链接")
```
```
### 设置原价[](#设置原价 "设置原价的直接链接")
```
```
### 显示后缀文案[](#显示后缀文案 "显示后缀文案的直接链接")
```
```
### 设置价格颜色[](#设置价格颜色 "设置价格颜色的直接链接")
```
```
### 设置价格字重[](#设置价格字重 "设置价格字重的直接链接")
```
```
### 价格后缀-文案[](#价格后缀-文案 "价格后缀-文案的直接链接")
```
```
### 价格后缀-图片[](#价格后缀-图片 "价格后缀-图片的直接链接")
```
```
### 完整价格展示[](#完整价格展示 "完整价格展示的直接链接")
```
```
## API[](#api "API的直接链接")
### 属性[](#属性 "属性的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| -------------- | ------------------------------ | ------------------------------------------------------------------------------ | ---------- | -------- |
| classNames | 配置价格内置模块的 className | `Record` | - | `v0.6.0` |
| colors | 配置价格内置模块的 color | `Record` | - | `v0.6.0` |
| originalPrice | 设置原始价格 | `number` / `string` | - | |
| price | 设置价格 | `number` / `string` | - | |
| priceAfter | 设置价格后文案 | string | - | |
| priceBefore | 设置价格前文案 | string | - | |
| size | 设置价格大小，以主价格大小为准 | `28` / `32` / `36` / `40` / `48` / `56` / `64` / `80` | `36` | |
| showSuffixText | 是否显示后缀文案（起） | boolean | `false` | |
| symbol | 符号类型 | string | `￥` | |
| symbolPosition | 设置符号显示在价格前或者后 | `'before'` / `'after'` | `'before'` | |
| styles | 配置价格内置模块的 style | `Record` | - | `v0.6.0` |
| weight | 设置价格字重 | `'light'` / `'normal'` / `'medium'` / `'bold'` / `300` / `400` / `500` / `700` | `500` | `v0.6.0` |
### SemanticDOM[](#semanticdom "SemanticDOM的直接链接")
| 参数 | 说明 |
| ------------- | ---------- |
| originalPrice | 原价 |
| priceBefore | 价格前文案 |
| priceAfter | 价格后文案 |
| price | 价格 |
| suffixText | 后缀文案 |
---
# Search 组件
## 介绍[](#介绍 "介绍的直接链接")
通用业务搜索栏组件，常用于页面的顶部搜索，也可以与导航栏组合使用.
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQSearch } from '@fq/fq-weapp-ui-pro';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui-pro/dist/styles/components/search.scss';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
```
### 小号搜索框[](#小号搜索框 "小号搜索框的直接链接")
```
```
### 固定宽度[](#固定宽度 "固定宽度的直接链接")
```
```
### 受控组件[](#受控组件 "受控组件的直接链接")
```
```
### 带图标组合使用[](#带图标组合使用 "带图标组合使用的直接链接")
```
```
### 搜索按钮颜色[](#搜索按钮颜色 "搜索按钮颜色的直接链接")
```
```
### 不带搜索按钮和清除按钮[](#不带搜索按钮和清除按钮 "不带搜索按钮和清除按钮的直接链接")
```
```
### 禁用[](#禁用 "禁用的直接链接")
```
```
## API[](#api "API的直接链接")
### 属性[](#属性 "属性的直接链接")
| 参数名 | 类型 | 默认值 | 说明 |
| ------------------ | ------------------------- | ----------- | ------------------------------------------------------------- |
| `value` | `string` | - | 当前值 |
| `ref` | `Ref` | - | 当前input的ref实例 |
| `size` | `SizeType` | `'default'` | 搜索栏大小 \['default', 'small']，如果有width，height，则失效 |
| `width` | \`string | number\` | `'default'` |
| `height` | \`string | number\` | `'default'` |
| `onSearch` | `(value: string) => void` | - | 搜索回调 |
| `onInput` | `(value: string) => void` | - | 输入回调 |
| `onConfirm` | `(value: string) => void` | - | 回车/键盘搜索后的回调 |
| `showSearchButton` | `boolean` | `true` | 是否展示右侧搜索按钮 |
| `autoFocus` | `boolean` | `false` | 自动聚焦 |
| `allowClear` | `boolean` | `true` | 展示清除按钮 |
| `loading` | `boolean` | `false` | 加载中状态 |
| `confirmText` | `string` | `'搜索'` | 搜索按钮文本 |
| `disabled` | `boolean` | `false` | 禁用 |
| `bordered` | `boolean` | `true` | 边框 |
| `enterButton` | `React.ReactNode` | - | 搜索按钮 |
| `enterButtonType` | `string` | `'default'` | 搜索按钮类型 'default' |
| `defaultPrefixCls` | `string` | - | 默认前缀类名 |
| `focusPrefixCls` | `string` | - | 焦点前缀类名 |
| `placeholder` | `string` | - | 占位符 |
| `searchButtonText` | `string` | - | 搜索按钮文案 |
| `addonBeforeIcon` | `React.ReactNode` | - | 展示左侧放大镜搜索图标 |
| `inputProps` | `Object` | `{}` | Input 扩展方法, 参考微信Input文档 |
---
# VideoPlayer 视频播放器
### 介绍[](#介绍 "介绍的直接链接")
* 支持横竖屏布局与组件级全屏（不打断播放进度）
* 长按倍速播放以及长按下拉倍速锁定 (长按触发倍速播放，长按下拉触发倍速锁)
* 沉浸式模式（双指捏合进入/退出，隐藏控件/进度条/弹幕）
* 自定义控制条（按钮显隐、插槽扩展、自定义渲染）
* 进度条预览（分片小窗、时间范围提示、实时时间）
* 拖拽小窗分片预览能力 (拖拽进度条能实时显示当前视频的切片)
* 上次观看记录（10%\~90% 区间节流存储，自动恢复并气泡提示）
* 弹幕能力（顶/中/底三栏，密度/速度可配，随倍速/播放状态同步，可动态发送）
* 震动反馈（捏合/长按倍速进入与恢复的轻/重震）
### 安装与引入[](#安装与引入 "安装与引入的直接链接")
```
import FQVideoPlayer from '@fq/fq-weapp-ui-pro';
```
按需样式（按需引入时需要）：
```
import '@fq/fq-weapp-ui-pro/dist/styles/components/video-player.scss';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
```
### 横屏模式 + 组件级全屏[](#横屏模式--组件级全屏 "横屏模式 + 组件级全屏的直接链接")
```
```
### 进度条预览（小窗 + 时间范围）[](#进度条预览小窗--时间范围 "进度条预览（小窗 + 时间范围）的直接链接")
```
```
### 自定义控制条（扩展按钮 / 完全自定义）[](#自定义控制条扩展按钮--完全自定义 "自定义控制条（扩展按钮 / 完全自定义）的直接链接")
```
const extraButtons = [
console.log('collect')}>收藏,
console.log('download')}>下载,
];
(...)
}}
/>
```
### 上次观看（自动记录/恢复）[](#上次观看自动记录恢复 "上次观看（自动记录/恢复）的直接链接")
```
```
### 手势与沉浸式[](#手势与沉浸式 "手势与沉浸式的直接链接")
```
```
### 弹幕（静态 + 动态发送）[](#弹幕静态--动态发送 "弹幕（静态 + 动态发送）的直接链接")
```
const ref = useRef(null);
// 运行时发送
ref.current?.sendBarrage?.({ text: '这是一条新弹幕' });
```
## API[](#api "API的直接链接")
### FQVideoPlayer Props[](#fqvideoplayer-props "FQVideoPlayer Props的直接链接")
| 参数名 | 类型 | 默认值 | 说明 |
| ------------------------ | --------------------------------------------------- | --------- | ------------------------------------------------------------------- |
| `width` | `number` | - | 组件宽（用于方向预判，可选） |
| `height` | `number` | - | 组件高（用于方向预判，可选） |
| `src` | `string` | 必填 | 视频地址 |
| `cover` | `string` | - | 自定义封面（组件层渲染，支持 `coverFit`） |
| `coverFit` | `'cover' \| 'contain'` | `contain` | 封面适配方式 |
| `muted` | `boolean` | `false` | 静音 |
| `controls` | `boolean \| ControlsOptions` | `true` | 控制条：`false` 隐藏；对象启用自定义按钮与插槽 |
| `autoplay` | `boolean` | `false` | 自动播放 |
| `loop` | `boolean` | `false` | 循环播放；同时驱动弹幕循环 |
| `initialTime` | `number` | `0` | 初始起播秒数（不自动播放时仅 seek，不播放） |
| `objectFit` | `'contain' \| 'fill' \| 'cover'` | `contain` | 视频铺放模式 |
| `className` | `string` | - | 容器类名 |
| `styles` | `FQVideoPlayerStyles` | - | 统一样式（`root/movableArea/movableView/video/bar/controls/cover`） |
| `barrage` | `boolean \| BarrageOptions` | `false` | 弹幕开关/配置（`true` 使用默认） |
| `showSliderRealtimeInfo` | `boolean` | `true` | 进度条两侧实时时间（左：当前，右：剩余） |
| `slider` | `boolean \| SliderOptions` | `true` | 进度条开关与配置（对象时需提供 `size`） |
| `orientation` | `Orientation` | `auto` | `auto/portrait/landscape`（内部自动/强制方向） |
| `layoutPreset` | `'default' \| 'compact' \| 'spacious'` | `default` | 预留布局预设 |
| `enableProgressGesture` | `boolean` | `false` | 是否开启进度滑动手势（保留） |
| `enablePinchGesture` | `boolean` | `true` | 是否开启双指捏合沉浸式切换 |
| `lastWatch` | `boolean \| LastWatchOptions` | `false` | 上次观看：开关/配置 |
| `onClose` | `Function: void` | - | 关闭按钮回调：竖屏全屏视频场景向外层触发 |
| `onPlay` | `Function: void` | - | 播放事件 |
| `onPause` | `Function: void` | - | 暂停事件 |
| `onEnded` | `Function: void` | - | 结束事件（会清理 lastWatch 缓存） |
| `onError` | `(err: ErrorMsg) => void` | - | 统一错误（结构化 `ErrorMsg`） |
| `onTimeUpdate` | `Function: void` | - | 进度更新 |
| `onWaiting` | `Function: void` | - | 缓冲中 |
| `onLoadedMetadata` | `Function: void` | - | 元数据就绪（内部会做方向与初始进度同步） |
| `onOrientationChange` | `(o: Orientation) => void` | - | 布局方向变化回调 |
| `onPreloadNextVideo` | `(id: string) => void` | - | 缓冲>10% 时触发预加载下一段 |
| `onPlayBackRate` | `(rate: number, type: 'manual' \| 'touch') => void` | - | 倍速变更回调 |
| `onScaleChange` | `(isScale: boolean) => void` | - | 缩放进入/退出状态（沉浸式手势） |
| `onDoubleTap` | `(e) => void` | - | 双击事件 |
| `videoId` | `string` | - | 自定义视频实例标识（选择器） |
| `pageId` | `string \| number` | - | 页面标识（事件总线隔离） |
### ControlsOptions[](#controlsoptions "ControlsOptions的直接链接")
| 属性 | 类型 | 默认值 | 说明 |
| ------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `renderLeft` | `React.ReactNode` | `默认关闭按钮` | 左侧区域插槽（竖屏时展示，横屏隐藏）。返回节点替换默认关闭按钮。 |
| `renderExtraRight` | `React.ReactNode` | `-` | 最右侧额外区域插槽。 |
| `buttons` | `{ menu?: boolean; play?: boolean; mute?: boolean; rate?: boolean; fullScreen?: boolean; }` | `{ menu:true, play:true, mute:true, rate:true, fullScreen:false }` | 基础按钮显隐配置。全屏按钮需显式开启。 |
| `extraButtons` | `React.ReactNode[]` | `[]` | 自定义按钮数组，插入在内置按钮之后，支持直接传节点。非法子类型（对象/函数/布尔）会被安全忽略。 |
| `renderButtons` | \`React.ReactNode | (ctx) => React.ReactNode\` | `-` |
子项：`buttons`
| 键 | 类型 | 默认值 | 说明 |
| ------------ | --------- | ------- | -------------------------------------------- |
| `menu` | `boolean` | `true` | 显示“更多/菜单”按钮 |
| `play` | `boolean` | `true` | 显示“播放/暂停”按钮 |
| `mute` | `boolean` | `true` | 显示“静音/取消静音”按钮 |
| `rate` | `boolean` | `true` | 显示“倍速”按钮（循环 0.5x→1x→1.25x→1.5x→2x） |
| `fullScreen` | `boolean` | `false` | 显示“全屏”按钮（仅横屏布局生效） |
提示：全屏按钮仅在横屏布局下展示有效（内部已有 `isLandscape` 判断），且需 `fullScreen: true`。
### SliderOptions[](#slideroptions "SliderOptions的直接链接")
| 属性 | 类型 | 默认值 | 说明 |
| ---------------------- | --------------------------------------------------- | ------- | ------------------------------------------------------------------------------ |
| `size` | `'large' \| 'middle' \| 'small'` | 必填 | 进度条尺寸。 |
| `showRealtimeTimeInfo` | `boolean` | `true` | 是否在进度条两侧显示实时时间（左：当前，右：剩余）。 |
| `showTimeRange` | `boolean` | `true` | 拖拽中是否在顶部显示 `time-range` 提示文本。 |
| `enablePreview` | `boolean` | `false` | 是否启用拖拽预览小窗（若同时使用旧 props `enablePreviewSnapshots` 也会启用）。 |
| `previewOptions` | `{ snapshot: string; time: number }[]` | `-` | 预览分片配置，time 为该切片代表的出现秒数。 |
| `previewThrottleMs` | `number` | `200` | 预览小窗图片更新的节流间隔（毫秒）。 |
| `styles` | `{ wrapper?; track?; buffer?; handle?; realtime? }` | `-` | 进度条各部件的内联样式定制。 |
说明：横屏时预览小窗按 16:9 呈现，竖屏按 9:16 呈现。
### LastWatchOptions[](#lastwatchoptions "LastWatchOptions的直接链接")
| 属性 | 类型 | 默认值 | 说明 |
| --------------- | -------- | ------ | -------------------------------------- |
| `throttleMs` | `number` | `4000` | 节流写入本地缓存的最小间隔（毫秒）。 |
| `minResumeSec` | `number` | `5` | 最小可恢复的播放秒数（不足不记录）。 |
| `ignoreTailSec` | `number` | `2` | 距离视频结尾的忽略秒数（过近不恢复）。 |
| `startPercent` | `number` | `10` | 参与记录/恢复的起始百分比（含）。 |
| `endPercent` | `number` | `90` | 参与记录/恢复的结束百分比（含）。 |
策略：仅在区间内（10%\~90%）且间隔到达节流阈值时写入；超出区间或播放结束会清理缓存。
### BarrageOptions（弹幕）[](#barrageoptions弹幕 "BarrageOptions（弹幕）的直接链接")
| 属性 | 类型 | 默认值 | 说明 |
| --------------- | ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `enabled` | `boolean` | `false` | 是否启用弹幕显示。 |
| `density` | `{ top?: number; middle?: number; bottom?: number }` | `-` | 顶/中/底三区各自的行数（密度）。 |
| `speedPxPerSec` | `number` | `-` | 基础速度（px/s），会随 `playbackRate` 同步变更。 |
| `data` | `BarrageItem[]` | `-` | 静态数据源，`BarrageItem` 包含 `id/text/avatar?/zone?/time`。未提供 zone 时内部会稳定分配车道。 |
| `styles` | `React.CSSProperties` | `-` | 弹幕容器样式。 |
| `className` | `string` | `-` | 弹幕容器自定义类名。 |
`BarrageItem` 结构：`{ id: string|number; text: string; avatar?: string; zone?: 'top'|'middle'|'bottom'; time: number }`
### Ref 能力（FQVideoPlayerRef）[](#ref-能力fqvideoplayerref "Ref 能力（FQVideoPlayerRef）的直接链接")
| 方法 | 签名 | 说明 |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `play` | `(): Promise` | 播放。 |
| `pause` | `(): Promise` | 暂停。 |
| `seek` | `(time: number): Promise` | 跳转到指定秒。 |
| `setPlaybackRate` | `(rate: number): Promise` | 设置倍速，手动来源会重置锁条与锁定态。 |
| `mute` | `(): void` | 静音。 |
| `unmute` | `(): void` | 取消静音。 |
| `setMuted` | `(muted: boolean): void` | 显式设置静音开关。 |
| `enterFullscreen` | `(): void` | 组件级全屏（仅横屏布局下进入；已全屏则无效）。 |
| `exitFullscreen` | `(): void` | 退出组件级全屏。 |
| `toggleFullscreen` | `(): void` | 切换组件级全屏（横屏进入/退出）。 |
| `sendBarrage` | BarrageItem | 发送一条新弹幕，立即出现在当前时间窗口。 |
| `getState` | `(): { playing; loading; muted; playbackRate; immersive; currentTimeSeconds; totalDurationSeconds; bufferPercent; orientation; isFullscreen; }` | 获取当前内部状态快照。 |
## 常见问题[](#常见问题 "常见问题的直接链接")
* 全屏按钮为什么不显示？
* 需设置 `controls.buttons.fullScreen = true`，且仅在横屏布局下显示。
* 预览小窗横屏显示有白边？
* 已在横屏使用 16:9 尺寸，竖屏 9:16；请确保传入的切片图本身也是对应比例。
* 上次观看为何未恢复？
* 小于 `startPercent` 或超过 `endPercent`（或接近结尾 `ignoreTailSec`）不会恢复；首次播放不足 `minResumeSec` 也不会记录。
---
# Button 组件
## 介绍[](#介绍 "介绍的直接链接")
按钮用于开始一个即时操作。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQButton } from '@fq/fq-weapp-ui';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui/dist/styles/components/button.scss';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
按钮
```
### 颜色和变体、禁用、加载中状态[](#颜色和变体禁用加载中状态 "颜色和变体、禁用、加载中状态的直接链接")
```
Solid
Solid
Outlined
Filled
Solid
Outlined
Filled
```
### 按钮形状[](#按钮形状 "按钮形状的直接链接")
```
default
A
round
```
### 按钮文本加粗[](#按钮文本加粗 "按钮文本加粗的直接链接")
```
加粗 true = 600
加粗 100
加粗 200
加粗 300
加粗 400
加粗 500
加粗 600
加粗 700
加粗 800
加粗 900
```
### Block按钮[](#block按钮 "Block按钮的直接链接")
```
Solid
Outlined
Filled
```
## API[](#api "API的直接链接")
支持小程序原生 [Button](https://developers.weixin.qq.com/miniprogram/dev/component/button.html) 组件的所有属性，并额外扩展以下属性
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------- | --------- | ------- |
| block | 将按钮宽度调整为其父宽度的选项 | boolean | `false` | |
| bold | 设置按钮文本加粗，默认 false。也可传入数字表示加粗程度 | boolean \| `100` \| `200` \| `300` \| `400` \| `500` \| `600` \| `700` \| `800` \| `900` | `false` | v0.15.0 |
| color | 设置按钮的颜色 | `default` \| `primary` \| `primary-gradient` | `primary` | |
| disabled | 设置按钮失效状态 | boolean | `false` | |
| icon | 设置按钮的图标组件 | React.ReactNode | - | |
| iconPosition | 设置按钮图标组件的位置 | `start` \| `end` | `start` | |
| disabled | 设置按钮失效状态 | boolean | `false` | |
| loading | 设置按钮的载入状态 | boolean | `false` | |
| size | 设置按钮的大小 | `xl` \| `lg` \| `md` \| `sm` \| `xs` \| `xxs` | `md` | |
| shape | 设置按钮的形状 | `default` \| `circle` \| `round` | `default` | |
| variant | 设置按钮的变体 | `outlined` \| `solid` \| `filled` | `solid` | |
## FAQ[](#faq "FAQ的直接链接")
### 在 FQButton 组件传递 `Show` 组件时，可能存在于期望结果不一致的情况？[](#在-fqbutton-组件传递-show-组件时可能存在于期望结果不一致的情况 "在-fqbutton-组件传递-show-组件时可能存在于期望结果不一致的情况的直接链接")
假设有这样一段代码
```
fallback} style={{ flexDirection: 'column' }}>
<>
show
show2
```
期望的渲染结果是：
```
```
因为在 `FQButton` 组件中，会判断 `children` 是否为 `string` 或 `React.Fragment`，如果是，则会包裹多一层 ``，主要是为了处理 iconPosition 的对 `children` 的影响。
但实际渲染结果是：
```
```
原因在于 `Show` 组件的 `type` 是函数，而不是 `string` 或 `React.Fragment`，因此没有进行额外的包裹。
虽然结果是你想要的，是按上下排列的，但间距会变大，因为是 `FQButton` 组件的 `gap` 属性影响了（主要是为了处理 icon 与 `children` 的间距）。
不建议通过修改 `gap` 来达到预期， 正确处理方式如下：
```
fallback}>
show
show2
```
---
# Gird 栅格
## 介绍[](#介绍 "介绍的直接链接")
24 栅格系统。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQCol, FQRow } from '@fq/fq-weapp-ui';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui/dist/styles/components/row.scss';
import '@fq/fq-weapp-ui/dist/styles/components/col.scss';
```
### 基础栅格[](#基础栅格 "基础栅格的直接链接")
```
col
col
col
col
col
col
col
col
col
col
```
### 区块间隔[](#区块间隔 "区块间隔的直接链接")
```
col
col
col
col
col
col
col
col
col
col
col
col
```
### 左右偏移[](#左右偏移 "左右偏移的直接链接")
```
col-8
col-8
col-6 col-offset-6
col-6 col-offset-6
col-12 col-offset-6
```
### 排版[](#排版 "排版的直接链接")
```
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
```
### 对齐[](#对齐 "对齐的直接链接")
```
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
col-4
```
### Flex填充[](#flex填充 "Flex填充的直接链接")
```
2 / 5
3 / 5
100rpx
Fill Rest
1 1 200rpx
0 1 300rpx
none
auto with no-wrap
```
## API[](#api "API的直接链接")
### Row[](#row "Row的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------- | ---- |
| align | 垂直对齐方式 | `top` \| `middle` \| `bottom` \| `stretch` | `top` | |
| gutter | 栅格间隔，可以写成像素值或者使用数组形式同时设置 `[水平间距, 垂直间距]` | number \| array | 0 | |
| justify | 水平排列方式 | `start` \| `end` \| `center` \| `space-around` \| `space-between` \| `space-evenly` | `start` | |
| wrap | 是否自动换行 | `boolean` / `number` | `true` | |
### Col[](#col "Col的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ------ | ------------------------------------------- | ---------------- | ------ | ---- |
| flex | flex 布局属性 | string \| number | - | |
| offset | 栅格左侧的间隔格数，间隔内不可以有栅格 | number | 0 | |
| order | 栅格顺序 | number | 0 | |
| pull | 栅格向左移动格数 | number | 0 | |
| push | 栅格向右移动格数 | number | 0 | |
| span | 栅格占位格数，为 0 时相当于 `display: none` | number | 0 | |
---
# Icon 组件
## 介绍[](#介绍 "介绍的直接链接")
Icon小图标组件
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
// 1. 引入
import { Icon } from 'fq-mall-taro-components';
// 2. 设置icon对应的定义
public static IconTypes = {
}
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
```
### 修改颜色与大小用法[](#修改颜色与大小用法 "修改颜色与大小用法的直接链接")
```
```
### 修改样式名[](#修改样式名 "修改样式名的直接链接")
```
```
### 增加点击事件[](#增加点击事件 "增加点击事件的直接链接")
```
{}} className='xxx' value={Icon.IconTypes.back1} size='20' color={'#cccccc'} />
```
## API[](#api "API的直接链接")
### 属性[](#属性 "属性的直接链接")
| 参数 | 说明 | 类型 | 默认值 |
| ----------- | ----------------- | ------------------------------------------ | --------- |
| value | 对应iconfont的值 | string | - |
| customStyle | 自定义style, 可选 | string \| React.CSSProperties \| undefined | - |
| className | class样式, 可选 | string | - |
| prefixClass | 样式, 可选 | string | 'fq-icon' |
### 方法[](#方法 "方法的直接链接")
| 函数名 | 说明 | 参数 |
| ------- | ---------- | ---- |
| onClick | 点击时触发 | - |
---
# SpriteIcon 组件
## 介绍[](#介绍 "介绍的直接链接")
精灵图图标组件
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
// 1. 引入
import {
FQSpriteIcon,
FQSpriteIconProps,
SpriteIconProps,
} from "@fq/fq-weapp-ui";
```
### 基础封装[](#基础封装 "基础封装的直接链接")
```
// 1. 引入精灵图配置
import { coordinates } from '../../../sprites/outputs/icons/coordinates';
const coordinatesFilesData = {
icons: coordinates,
};
// 2. 结合精灵图使用
const SpriteIconContainer = ({
coordinatesFiles,
module,
name,
size = 0,
width,
height,
className,
style,
onClick,
}: FQSpriteIconProps) => (
);
const SpriteIcon = ({
module = "icons",
name,
size = 0,
width,
height,
className,
style,
onClick,
}: SpriteIconProps) => (
);
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
import { SpriteIcon } from "@/component/SpriteIcon";
```
### 项目调取[](#项目调取 "项目调取的直接链接")
width、height宽高不等
```
```
### 项目调取，size[](#项目调取size "项目调取，size的直接链接")
宽高相等
```
```
## API[](#api "API的直接链接")
### 属性[](#属性 "属性的直接链接")
| 参数 | 说明 | 类型 | 默认值 |
| ---------------- | ---------------- | ------------------------------------------ | ------- |
| coordinatesFiles | 图标坐标文件 | Record\ | - |
| module | 图标模块名 | string | 'icons' |
| name | 要显示的图标名称 | string | - |
| size | 图标的大小 | number | 0 |
| width | 图标的宽度 | number \| undefined | - |
| height | 图标的高度 | number \| undefined | - |
| className | 自定义类名 | string | - |
| style | 自定义样式 | string \| React.CSSProperties \| undefined | - |
### 方法[](#方法 "方法的直接链接")
| 函数名 | 说明 | 参数 |
| ------- | ---------- | ---- |
| onClick | 点击时触发 | - |
---
# Typo 组件
## 介绍[](#介绍 "介绍的直接链接")
字体组件用于展示文本内容。分别有 `FQText`、`FQTitle`、`FQNumeral` 组件。
## Title 组件[](#title-组件 "Title 组件的直接链接")
### 介绍[](#介绍-1 "介绍的直接链接")
标题组件用于展示页面标题。
### 用法[](#用法 "用法的直接链接")
#### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQTitle } from '@fq/fq-weapp-ui';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui/dist/styles/components/title.scss';
```
#### 基础用法[](#基础用法 "基础用法的直接链接")
```
加粗
```
## Text 组件[](#text-组件 "Text 组件的直接链接")
### 介绍[](#介绍-2 "介绍的直接链接")
文本组件用于展示文本内容。
### 用法[](#用法-1 "用法的直接链接")
#### 基本引入[](#基本引入-1 "基本引入的直接链接")
```
import { FQText } from '@fq/fq-weapp-ui';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui/dist/styles/components/text.scss';
```
#### 基础用法[](#基础用法-1 "基础用法的直接链接")
```
加粗
```
## Numberal 组件[](#numberal-组件 "Numberal 组件的直接链接")
### 介绍[](#介绍-3 "介绍的直接链接")
数字组件用于展示数字内容。
### 用法[](#用法-2 "用法的直接链接")
#### 基本引入[](#基本引入-2 "基本引入的直接链接")
```
import { FQNumeral } from '@fq/fq-weapp-ui';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui/dist/styles/components/numberal.scss';
```
#### 基础用法[](#基础用法-2 "基础用法的直接链接")
```
```
## API[](#api "API的直接链接")
### Title 属性[](#title-属性 "Title 属性的直接链接")
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
| --------- | -------------- | ------------------- | ------------------------------------------------------------------ | ------- |
| level | 标题级别 | number | `1` / `2` / `3` / `4` / `5` / `6` / `7` | `1` |
| bold | 是否加粗 | boolean | - | `false` |
| ellipsis | 是否显示省略号 | boolean / number | `true`: 1行溢出省略 / `false`: 不溢出省略 / `number`: 溢出省略行数 | `false` |
| className | 标题样式类名 | string | - | - |
| style | 标题样式 | React.CSSProperties | - | - |
### Text 属性[](#text-属性 "Text 属性的直接链接")
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
| ---------- | -------------------- | --------------------- | ---------------------------------------------------------------------------------------- | ------- |
| size | 字体大小 | number | `20` / `22` / `24` / `26` / `28` | `24` |
| bold | 是否加粗 | boolean | - | `false` |
| userSelect | 用户是否可以选中文本 | boolean | - | `false` |
| space | 显示连续空格 | Taro.TextProps.TSpace | `ensp(中文字符空格一半大小)` / `emsp(中文字符空格大小)` / `nbsp(根据字体设置的空格大小)` | - |
| decode | 是否解码 | boolean | - | `false` |
| className | 文本样式类名 | string | - | - |
| style | 文本样式 | React.CSSProperties | - | - |
### Numberal 属性[](#numberal-属性 "Numberal 属性的直接链接")
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
| ----------- | -------------- | ------------------- | ------------------------------------------------------------------- | -------- |
| value | 数字内容 | string / number | - | - |
| type | 数字类型 | string | `delete` / `normal` | `normal` |
| size | 字体大小 | number | `24` / `28` / `32` / `36` / `40` / `44` / `48` / `56` / `64` / `80` | `24` |
| bold | 是否加粗 | boolean | - | `false` |
| prefix | 前缀插槽 | ReactNode | - | - |
| suffix | 后缀插槽 | ReactNode | - | - |
| thousands | 是否显示千分位 | boolean | - | `false` |
| showDecimal | 是否显示小数点 | boolean | - | `false` |
| decimal | 小数点位数 | number | - | `2` |
| className | 文本样式类名 | string | - | - |
| style | 文本样式 | React.CSSProperties | - | - |
---
# Checkbox 多选框
## 介绍[](#介绍 "介绍的直接链接")
收集用户的多项选择。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQCheckbox } from '@fq/fq-weapp-ui';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui/dist/styles/components/checkbox.scss';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
Checkbox
```
### 不可用[](#不可用 "不可用的直接链接")
```
```
### 受控的 Checkbox[](#受控的-checkbox "受控的 Checkbox的直接链接")
```
const [checked, setChecked] = useState(false);
const [disabled, setDisabled] = useState(false);
{ `${checked ? 'Checked' : 'Unchecked'}-${disabled ? 'Disabled' : 'Enabled'}` }
```
### Checkbox 组[](#checkbox-组 "Checkbox 组的直接链接")
```
const plainOptions = ['Apple', 'Pear', 'Orange'];
const options = [
{
label: 'Apple',
value: 'Apple',
disabled: true,
className: 'label-1',
onChange: (val, e) => console.log(val, e),
},
{
label: 'Pear',
value: 'Pear',
className: 'label-2',
onChange: (val, e) => console.log(val, e),
},
{
label: 'Orange',
value: 'Orange',
className: 'label-3',
onChange: (val, e) => console.log(val, e),
},
];
```
### 自定义布局[](#自定义布局 "自定义布局的直接链接")
```
A
B
C
D
E
```
## API[](#api "API的直接链接")
### 属性[](#属性 "属性的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| -------------- | ---------------- | ---------------------------------------------- | ------ | ---- |
| checked | 指定当前是否选中 | boolean | false | |
| defaultChecked | 初始是否选中 | boolean | false | |
| disabled | 是否禁用 | boolean | false | |
| onChange | 变化时回调函数 | function(val: boolean, e: CheckboxChangeEvent) | - | |
### Checkbox.Group[](#checkboxgroup "Checkbox.Group的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ------------ | -------------------- | ---------------------------------------------------------------------------- | ------ | ---- |
| defaultValue | 默认选中的选项 | (string \| number)\[] | \[] | |
| disabled | 整组失效 | boolean | false | |
| options | 以配置形式设置子元素 | `string[]` \| `number[]` \| Array<[CheckboxOptionType](#checkboxoptiontype)> | - | |
| value | 指定选中的选项 | (string \| number \| boolean)\[] | \[] | |
| onChange | 选项变化时的回调函数 | function(checkedValue: any\[]) | - | |
### CheckboxOptionType[](#checkboxoptiontype "CheckboxOptionType的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| --------- | -------------- | ---------------------------------------------- | ------ | ---- |
| label | 选项的 label | ReactNode | - | |
| value | 选项的值 | any | - | |
| style | 选项的样式 | `React.CSSProperties` | - | |
| className | 选项的类名 | string | - | |
| disabled | 选项失效状态 | boolean | false | |
| onChange | 变化时回调函数 | function(val: boolean, e: CheckboxChangeEvent) | - | |
---
# FQForm 表单
## 介绍[](#介绍 "介绍的直接链接")
高性能表单控件，自带数据域管理。包含数据录入、校验以及对应样式。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQForm } from '@fq/fq-weapp-ui';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui/dist/styles/components/form.scss';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
// 输入控件
```
### 基础使用[](#基础使用 "基础使用的直接链接")
```
提交
```
### 表单布局[](#表单布局 "表单布局的直接链接")
```
提交
```
### 表单混合布局[](#表单混合布局 "表单混合布局的直接链接")
```
```
### 表单变体[](#表单变体 "表单变体的直接链接")
```
提交
```
## API[](#api "API的直接链接")
### `Form`[](#form "form的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| -------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------- | ---- |
| initialValues | 表单默认值，只有初始化以及重置时生效 | object | - | |
| bordered | 是否显示表单项边框 | boolean | true | |
| form | 经 Form.useForm() 创建的 form 控制实例，不提供时会自动创建 | [FormInstance](#forminstance) | - | |
| disabled | 设置表单组件禁用 | boolean | false | |
| layout | 表单布局 | `'horizontal'` \| `'vertical'` | `'horizontal'` | |
| labelAlign | label 标签的文本对齐方式 | `'left'` \| `'right'` | `'left'` | |
| labelWrap | 标签是否换行 | boolean | false | |
| labelCol | label 标签布局 | [object]() | - | |
| variant | 表单内控件变体 | `'outlined'` \| `'borderless'` | `'borderless'` | |
| wrapperCol | 需要为输入控件设置布局样式时，使用该属性，用法同 labelCol | [object]() | - | |
| wrapperAlign | 输入控件方式 | `'left'` \| `'right'` | `'left'` | |
| onValuesChange | 字段值更新时触发回调事件 | `function(changedValues, allValues)` | - | |
| onFieldsChange | 字段更新时触发回调事件，暂未实现 | `function(changedFields, allFields)` | - | |
| onFinish | 提交表单且数据验证成功后回调事件 | `function(values)` | - | |
| onFinishFailed | 提交表单且数据验证失败后回调事件 | `function({ values, errorFields, outOfDate })` | - | |
### `Form.Item`[](#formitem "formitem的直接链接")
表单字段组件，用于数据双向绑定、校验、布局等。
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------- | ---- |
| bordered | 是否显示表单项边框，默认 `true` | boolean | `true` | |
| extra | 额外的提示信息，和 help 类似，当需要错误信息和提示文案同时出现时，可以使用这个。 | ReactNode | - | |
| help | 提示信息，如不设置，则会根据校验规则自动生成 | ReactNode | - | |
| label | label 标签的文本 | ReactNode | - | |
| labelAlign | label 标签的文本对齐方式, 默认值为 `left` | `left` \| `right` | `left` | |
| labelWrap | 标签是否换行，默认 `false` | boolean | `false` | |
| labelCol | label 标签布局，同 `` 组件 | [object]() | - | |
| name | 字段路径数组 | [NamePath](#namepath) | - | |
| noStyle | 为 true 时不带样式，作为纯字段控件使用。 | boolean | `false` | |
| required | 必填样式设置。 | boolean | `false` | |
| rules | 校验规则，设置字段的校验逻辑 | [Rule](#rule)\[] | - | |
| valuePropName | 子节点的值的属性。注意：Switch、Checkbox 的 valuePropName 应该是 checked，否则无法获取这个两个组件的值。 | string | `value` | |
| wrapperCol | 需要为输入控件设置布局样式时，使用该属性，用法同 labelCol | [object]() | - | |
| wrapperAlign | 输入控件方式，默认值为 `left` | `left` \| `right` | `left` | |
| layout | 表单项布局 | `horizontal` \| `vertical` | - | |
### FormInstance[](#forminstance "FormInstance的直接链接")
| 名称 | 说明 | 类型 | 版本 |
| -------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------- | ---- |
| getFieldValue | 获取对应字段名的值 | `(name: NamePath) => any` | |
| getFieldsValue | 获取一组字段名对应的值，会按照对应结构返回。默认返回现存字段值，当调用 `getFieldsValue()` 时返回所有值 | `(nameList?: NamePath[]) => any` | |
| resetFields | 重置一组字段到 `initialValues` | `() => void` | |
| setFieldValue | 设置表单的值（该值将直接传入 form store 中并且重置错误信息） | `(name: NamePath, value: any) => void` | |
| setFieldsValue | 设置表单的值（该值将直接传入 form store 中并且重置错误信息） | `(values) => void` | |
| validateFields | 触发表单验证 | `(nameList?: NamePath[]) => Promise` | |
### Interface[](#interface "Interface的直接链接")
#### NamePath[](#namepath "NamePath的直接链接")
`string | number | (string | number)[]`
#### Rule[](#rule "Rule的直接链接")
| 参数 | 说明 | 类型 | 版本 |
| --------- | --------------------------------------------------------------------------------------------- | -------------------------- | ---- |
| len | string 类型时为字符串长度；number 类型时为确定数字； array 类型时为数组长度 | number | |
| max | 必须设置 type：string 类型为字符串最大长度；number 类型时为最大值；array 类型时为数组最大长度 | number | |
| message | 错误信息，不设置时会通过模板自动生成 | string | |
| min | 必须设置 type：string 类型为字符串最小长度；number 类型时为最小值；array 类型时为数组最小长度 | number | |
| required | 是否为必选字段 | - | |
| transform | 将字段值转换成目标值后进行校验 | - | |
| type | 类型，常见有 `string` \| `number` \| `boolean`。 | string | |
| validator | 自定义校验，接收 Promise 作为返回值。 | `(rule, value) => Promise` | |
---
# Input 输入框(新版)
用于接收用户文本、数字等内容输入，支持多种场景和样式扩展。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQInputNew } from '@fq/fq-weapp-ui';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
```
### 非受控默认值[](#非受控默认值 "非受控默认值的直接链接")
```
```
### 非受控数字输入（失焦自动校正）[](#非受控数字输入失焦自动校正 "非受控数字输入（失焦自动校正）的直接链接")
```
```
### 禁用状态[](#禁用状态 "禁用状态的直接链接")
```
```
### 带清除按钮[](#带清除按钮 "带清除按钮的直接链接")
```
```
### 前置/后置标签[](#前置后置标签 "前置/后置标签的直接链接")
```
```
### 错误提示[](#错误提示 "错误提示的直接链接")
```
```
### 注释说明[](#注释说明 "注释说明的直接链接")
```
```
### 非全屏宽度[](#非全屏宽度 "非全屏宽度的直接链接")
```
```
### 错误提示、注释居右展示[](#错误提示注释居右展示 "错误提示、注释居右展示的直接链接")
```
```
### 无边框样式[](#无边框样式 "无边框样式的直接链接")
```
```
***
## 属性说明[](#属性说明 "属性说明的直接链接")
FQInputNew 继承了 [Taro InputProps](https://docs.taro.zone/docs/components/forms/input) 的全部属性，以下为 **FQInputNewProps** 对 InputProps 的补充或修改，按功能分类：
### 基础属性[](#基础属性 "基础属性的直接链接")
| 属性 | 说明 | 类型 | 默认值 |
| ------------ | ------------------------ | ------- | ------ |
| defaultValue | 输入框默认值 | string | '' |
| value | 输入框当前值 | string | - |
| placeholder | 占位符 | string | - |
| type | 输入框类型 | string | 'text' |
| maxLength | 输入内容最大长度 | number | - |
| disabled | 是否禁用 | boolean | false |
| status | 自定义状态，可选 'error' | string | - |
### 内容与交互[](#内容与交互 "内容与交互的直接链接")
| 属性 | 说明 | 类型 | 默认值 |
| ---------------------- | -------------------------------------- | ---------- | ------ |
| allowClear | 是否显示清除按钮 | boolean | false |
| onlyShowClearWhenFocus | 仅输入框聚焦时显示清除按钮 | boolean | false |
| onClear | 清除按钮点击时的回调 | () => void | - |
| onChange | 输入内容变化时的回调（等价于 onInput） | function | - |
### 前后缀与标签[](#前后缀与标签 "前后缀与标签的直接链接")
| 属性 | 说明 | 类型 | 默认值 |
| ----------- | ------------------------------------------ | --------- | ------ |
| prefix | 输入框前缀内容（自定义节点） | ReactNode | - |
| suffix | 输入框后缀内容（自定义节点） | ReactNode | - |
| addonBefore | 前置标签（variant 不为 borderless 时显示） | ReactNode | - |
| addonAfter | 后置标签（variant 不为 borderless 时显示） | ReactNode | - |
### 状态与样式[](#状态与样式 "状态与样式的直接链接")
| 属性 | 说明 | 类型 | 默认值 |
| ----------- | ---------------------------- | ------------------------------------------------------------------------------------------------- | ---------- |
| error | 错误提示内容，输入框下方展示 | string | - |
| description | 注释说明，输入框下方展示 | string | - |
| variant | 边框样式 | 'outlined' \| 'borderless' | 'outlined' |
| width | 输入框宽度 | number \| string | 100%/111px |
| size | 输入框尺寸 | 'default' \| 'small' | 'default' |
| align | 输入框内容对齐方式 | 'left' \| 'right' （有边框时，文本固定左对齐，此时align参数传值无效；无边框时，文本根据配置对齐） | 'left' |
| className | 自定义样式类名 | string | - |
| style | 自定义样式 | CSSProperties | - |
### 数值限制（仅 type 为 number 时生效）[](#数值限制仅-type-为-number-时生效 "数值限制（仅 type 为 number 时生效）的直接链接")
| 属性 | 说明 | 类型 | 默认值 |
| ---- | ------ | ------ | ------ |
| max | 最大值 | number | - |
| min | 最小值 | number | - |
***
**未修改的 InputProps 属性**（如 value、placeholder、disabled、type、name、onFocus、onBlur 等），请参考 [TaroInput 组件文档](https://docs.taro.zone/docs/components/forms/input)。
补充说明：
* `value` + `onChange` 为受控模式。
* 不传 `value` 时为非受控模式，可通过 `defaultValue` 指定初始值。
***
---
# Radio 单选框
## 介绍[](#介绍 "介绍的直接链接")
用于在多个备选项中选中单个状态。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQRadio } from '@fq/fq-weapp-ui';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui/dist/styles/components/radio.scss';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
Radio
```
### 不可用[](#不可用 "不可用的直接链接")
```
```
### Radio.Group 组[](#radiogroup-组 "Radio.Group 组的直接链接")
```
const plainOptions = ['Apple', 'Pear', 'Orange'];
const options = [
{
label: 'Apple',
value: 'Apple',
disabled: true,
className: 'label-1',
onChange: (val, e) => console.log(val, e),
},
{
label: 'Pear',
value: 'Pear',
className: 'label-2',
onChange: (val, e) => console.log(val, e),
},
{
label: 'Orange',
value: 'Orange',
className: 'label-3',
onChange: (val, e) => console.log(val, e),
},
];
```
### Radio.Group 垂直[](#radiogroup-垂直 "Radio.Group 垂直的直接链接")
```
const options = ['Apple', 'Pear', 'Orange'];
```
## API[](#api "API的直接链接")
### 属性[](#属性 "属性的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| -------------- | ---------------- | ------------------------------------------- | ------ | ---- |
| checked | 指定当前是否选中 | boolean | false | |
| defaultChecked | 初始是否选中 | boolean | false | |
| disabled | 是否禁用 | boolean | false | |
| onChange | 变化时回调函数 | function(val: boolean, e: RadioChangeEvent) | - | |
### Radio.Group[](#radiogroup "Radio.Group的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---- |
| defaultValue | 默认选中的值 | any | - | |
| disabled | 禁选所有子单选器 | boolean | false | |
| options | 以配置形式设置子元素 | `string[]` \| `number[]` \| Array<[RadioOptionType]()> | - | |
| value | 用于设置当前选中的值 | any | - | |
| onChange | 选项变化时的回调函数 | function(checkedValue: any) | - | |
### RadioOptionType[](#radiooptiontype "RadioOptionType的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| --------- | ------------------ | ------------------------------------------- | ------ | ---- |
| label | 选项的 label | ReactNode | - | |
| value | 选项的值 | any | - | |
| style | 选项的样式 | `React.CSSProperties` | - | |
| className | 选项的类名 | string | - | |
| disabled | 选项失效状态 | boolean | false | |
| onChange | 选项变化时回调函数 | function(val: boolean, e: RadioChangeEvent) | - | |
---
# Stepper 步进器
用于在一定范围内输入、调整数字，支持数量增减、禁用、步长、边框/无边框、Din字体等多种功能。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQStepper } from '@fq/fq-weapp-ui';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
console.log(val)} />
```
### 非受控用法[](#非受控用法 "非受控用法的直接链接")
```
console.log(val)} />
```
### 展开形态[](#展开形态 "展开形态的直接链接")
```
console.log(val)} />
```
### 禁用状态[](#禁用状态 "禁用状态的直接链接")
```
```
### 边界限制[](#边界限制 "边界限制的直接链接")
```
```
### 步长设置[](#步长设置 "步长设置的直接链接")
```
```
### 无边框样式[](#无边框样式 "无边框样式的直接链接")
```
```
### 自定义尺寸[](#自定义尺寸 "自定义尺寸的直接链接")
```
```
### 自定义占位符[](#自定义占位符 "自定义占位符的直接链接")
```
```
### 事件监听[](#事件监听 "事件监听的直接链接")
```
const max = 5;
const min = -2;
console.log(value)}
max={max}
min={min}
onBlur={e => {
console.log('onBlur event:', e);
setValue(false);
}}
onFocus={e => {
console.log('onFocus event:', e);
setValue(true);
}}
onIncrement={(_, val) => {
console.log('onIncrement new value', val)
if (val > max) {
alert('超过最大值提示文案');
return false;
}
return true;
}}
onDecrement={(_, val) => {
console.log('onDecrement new value', val)
if (val < min) {
alert('超过最小值提示文案');
return false;
}
return true;
}}
onInputMax={val => {
console.log('onInputMax event:', val);
}}
/>
```
***
## 属性说明[](#属性说明 "属性说明的直接链接")
### 基础属性[](#基础属性 "基础属性的直接链接")
| 属性 | 说明 | 类型 | 默认值 |
| ------------ | -------------------------------- | -------------------------- | -------- |
| value | 当前数值（受控） | number | - |
| defaultValue | 默认数值（非受控） | number | min(1) |
| min | 最小值 | number | 1 |
| max | 最大值 | number | +∞ |
| step | 步长 | number | 1 |
| disabled | 是否禁用 | boolean | false |
| expanded | 是否展开（增减形态） | boolean | false |
| expandable | 是否允许从数量显示切换为增减形态 | boolean | true |
| buttonSize | 按钮大小 | string \| number | 26px |
| fontSize | 字体大小 | string \| number | 13px |
| inputWidth | 输入框宽度 | string \| number | 36px |
| variant | 形态变体 | 'outlined' \| 'borderless' | outlined |
| placeholder | 输入框占位符 | string | - |
| style | 自定义样式 | CSSProperties | - |
| className | 自定义样式类名 | string | - |
说明：
* 尺寸类属性支持 `number` 和带单位字符串。`number` 会按 `px` 处理；字符串支持 `px/rpx` 等常见单位。
* `variant` 为 `outlined` 时，组件使用边框效果；`borderless` 时按钮为独立浅灰块，中央数字无边框。
### 事件属性[](#事件属性 "事件属性的直接链接")
| 属性 | 说明 | 类型 | 默认值 |
| ----------- | ----------------------------------------- | -------------------------------------------------- | ------ |
| onChange | 数值变化时回调（确认/失焦/按钮） | (value: number) => void | - |
| onFocus | 输入框获得焦点时回调 | InputProps\['onFocus'] | - |
| onBlur | 输入框失去焦点时回调 | InputProps\['onBlur'] | - |
| onInput | 输入框值改变时的回调 | (value: number) => void | - |
| onInputMax | 输入框输入到达最大值时触发 | (value: number) => void | - |
| onDecrement | 点击减小按钮时触发，返回 false 阻止值变化 | (e: ITouchEvent, value: number) => boolean \| void | - |
| onIncrement | 点击增加按钮时触发，返回 false 阻止值变化 | (e: ITouchEvent, value: number) => boolean \| void | - |
***
## 交互说明[](#交互说明 "交互说明的直接链接")
* 受控模式：传入 `value`，组件值由外部状态驱动。
* 非受控模式：不传 `value`，可通过 `defaultValue` 指定初始值，后续由组件内部维护。
* 输入阶段：仅在点击键盘的确认按钮/失焦或点击按钮时提交并触发 `onChange`。
* `onDecrement`/`onIncrement` 支持返回 `false`，可阻止步进器数值变化。
***
---
# Switch 开关
## 介绍[](#介绍 "介绍的直接链接")
使用开关切换两种状态之间。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQSwitch } from '@fq/fq-weapp-ui';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui/dist/styles/components/switch.scss';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
```
### 不可用[](#不可用 "不可用的直接链接")
```
```
### 文字和图标[](#文字和图标 "文字和图标的直接链接")
```
```
### 大小[](#大小 "大小的直接链接")
```
```
## API[](#api "API的直接链接")
### 属性[](#属性 "属性的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ----------------- | -------------------------------------------- | ---------------------------------------------- | --------- | ---- |
| checked | 指定当前是否选中 | boolean | false | |
| checkedChildren | 选中时的内容 | ReactNode | - | |
| defaultChecked | 初始是否选中 | boolean | false | |
| defaultValue | defaultChecked 的别名 | boolean | - | |
| disabled | 是否禁用 | boolean | false | |
| size | 开关大小，可选值 `large`, `default`, `small` | string | `default` | |
| unCheckedChildren | 非选中时的内容 | ReactNode | - | |
| value | checked 的别名 | boolean | - | |
| onChange | 变化时回调函数 | function(checked: boolean, event: ITouchEvent) | - | |
| onClick | 点击时的回调函数 | function(checked: boolean, event: ITouchEvent) | - | |
---
# TextArea 输入框（新版）
用于多行文本输入，支持字数统计、自动高度、错误提示、无边框等多种场景。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQTextareaNew } from '@fq/fq-weapp-ui';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
```
### 非受控用法[](#非受控用法 "非受控用法的直接链接")
```
console.log(e.detail?.value)}
/>
```
### 受控用法[](#受控用法 "受控用法的直接链接")
```
```
### 显示字数[](#显示字数 "显示字数的直接链接")
```
```
### 字数长度限制[](#字数长度限制 "字数长度限制的直接链接")
```
```
### 字数长度限制并截断[](#字数长度限制并截断 "字数长度限制并截断的直接链接")
```
```
### 禁用[](#禁用 "禁用的直接链接")
```
```
### 错误信息[](#错误信息 "错误信息的直接链接")
```
```
### 无边框样式[](#无边框样式 "无边框样式的直接链接")
```
```
### 根据内容自动增高[](#根据内容自动增高 "根据内容自动增高的直接链接")
```
```
### 指定显示行数[](#指定显示行数 "指定显示行数的直接链接")
```
```
***
## 属性说明[](#属性说明 "属性说明的直接链接")
FQTextareaNew 继承了 [Taro TextareaNewProps](https://docs.taro.zone/docs/components/forms/textarea) 的全部属性，以下为 **FQTextareaNewProps** 对 TextareaProps 的补充或修改，按功能分类：
### 基础属性[](#基础属性 "基础属性的直接链接")
| 属性 | 说明 | 类型 | 默认值 |
| ----------------- | ------------------------------------------------------------------ | ------- | ------ |
| value | 输入框当前值（受控） | string | - |
| defaultValue | 输入框默认值 | string | '' |
| maxLength | 最大输入长度，超出后不再允许输入（覆盖 TaroTextarea 的 maxlength） | number | - |
| truncateMaxLength | 达到最大长度后是否禁止继续输入 | boolean | false |
| status | 自定义状态，可选 'error' | string | - |
### 内容与交互[](#内容与交互 "内容与交互的直接链接")
| 属性 | 说明 | 类型 | 默认值 |
| --------- | ------------------------------------------------------ | ------------------------------------------- | ------ |
| showCount | 是否显示字数统计，或自定义渲染字数统计 | boolean \| (length, maxLength) => ReactNode | false |
| onChange | 输入内容变化时的回调（等价于 TaroTextarea 的 onInput） | function | - |
### 状态与样式[](#状态与样式 "状态与样式的直接链接")
| 属性 | 说明 | 类型 | 默认值 |
| --------- | ---------------------------- | -------------------------- | ---------- |
| error | 错误提示内容，输入框下方展示 | string | - |
| variant | 边框样式 | 'outlined' \| 'borderless' | 'outlined' |
| className | 自定义样式类名 | string | - |
| style | 自定义样式 | CSSProperties | - |
### 行数与高度[](#行数与高度 "行数与高度的直接链接")
| 属性 | 说明 | 类型 | 默认值 |
| ---------- | ------------------------------------------------ | ------- | ------ |
| rows | 指定显示行数，固定高度为 rows \* 行高 | number | - |
| autoHeight | 内容变化时自动增高（TaroTextarea 的 autoHeight） | boolean | false |
***
**未修改的 TextareaProps 属性**（如 value、placeholder、disabled、name、onFocus、onBlur 等），请参考 [TaroTextarea 组件文档](https://docs.taro.zone/docs/components/forms/textarea)。
补充说明：
* 受控模式：传入 `value`，由外部状态驱动展示值。
* 非受控模式：不传 `value`，通过 `defaultValue` 指定初始值，后续由组件内部维护。
---
# Badge 徽标数
## 介绍[](#介绍 "介绍的直接链接")
图标右上角的圆形徽标数字。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQBadge } from '@fq/fq-weapp-ui';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui/dist/styles/components/badge.scss';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
}
>
```
### 独立使用[](#独立使用 "独立使用的直接链接")
```
```
### 封顶数字[](#封顶数字 "封顶数字的直接链接")
```
```
### 自定义位置偏移[](#自定义位置偏移 "自定义位置偏移的直接链接")
```
```
### 变体[](#变体 "变体的直接链接")
```
```
### 自定义颜色[](#自定义颜色 "自定义颜色的直接链接")
```
```
## API[](#api "API的直接链接")
### 基础属性[](#基础属性 "基础属性的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ------------- | ------------------------------------------------------------------------------------ | ------------------------------------ | ------- | ---- |
| color | 自定义颜色 | string | - | |
| count | 展示的数字 | ReactNode | - | |
| dot | 不展示数字，只有一个小红点 | boolean | `false` | |
| offset | 设置状态点的位置偏移，格式为 `[left, top]`，表示状态点距默认位置左侧、上方的偏移量。 | `[number, number]` | - | |
| overflowCount | 展示封顶的数字值 | number | 99 | |
| showZero | 当数值为 0 时，是否展示 Badge | boolean | false | |
| styles | 语义化结构 style | `Record` | - | |
| type | 徽标类型 | `solid` / `outlined` | `solid` | |
### SemanticDOM[](#semanticdom "SemanticDOM的直接链接")
| 参数 | 说明 |
| --------- | ---------- |
| root | 根节点 |
| indicator | 指示器节点 |
---
# Card 组件
## 介绍[](#介绍 "介绍的直接链接")
基础卡片，一般利用基础卡片框架构造更为复杂、符合多场景的卡片等。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQCard } from '@fq/fq-weapp-ui';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui/dist/styles/components/card.scss';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
```
### 卡片圆角 & 图片圆角[](#卡片圆角--图片圆角 "卡片圆角 & 图片圆角的直接链接")
```
```
```
```
```
```
### 标题显示行数 & 溢出方式[](#标题显示行数--溢出方式 "标题显示行数 & 溢出方式的直接链接")
```
```
### 布局插槽展示[](#布局插槽展示 "布局插槽展示的直接链接")
```
imageBadge}
imageUrl='https://stantic.ifengqun.com/front/fq-oms-extsys/upload/1d0dc847a0cd20135a65f50e4949a3c4.jpg?x-oss-process=image/format,webp/interlace,1'
title='4袋减61元【通过远方120项检测 升级版卤大猪耳朵(熟食)】短期不含防腐剂 配料表干净 鲜果现摘榨 10袋/盒'
titleLine={2}
header={header}
promoHeader={promoHeader}
promoDescription={promoDescription}
infoFooter={infoFooter}
price={price}
actionArea={actionArea}
footer={footer}
/>
```
## API[](#api "API的直接链接")
### 属性[](#属性 "属性的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -------- | -------- |
| classNames | 配置卡片内置模块的 className | `Record` | - | |
| imageUrl | 封面地址 | string | `''` | |
| imageProps | 设置 `Image` props，可选值参考[微信image文档](https://developers.weixin.qq.com/miniprogram/dev/component/image.html) | ImageProps | - | |
| imageRound | 封面是否为圆角 | `boolean` / `number` | `true` | `v0.2.7` |
| label | 标题左侧标签，目前为标签图片的 Url 数组 | `string[]` | - | |
| layout | 卡片布局方式 | `column` / `row` | `row` | |
| round | 是否为圆角卡片 | `boolean` / `number` | `true` | `v0.2.7` |
| size | 卡片大小，仅 layout 为 `column` 时生效 | `large` / `middle` / `small` | `middle` | |
| styles | 配置卡片内置模块的 style | `Record` | - | |
| title | 标题 | string | - | |
| titleLine | 标题行数，默认2，即2行省略 | `number` / `string` | 2 | |
| titleOverflow | 标题超出省略方式 | `ellipsis` / `clip` | `clip` | |
### 插槽[](#插槽 "插槽的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ---------------- | -------------------- | --------- | ------ | -------- |
| actionArea | 自定义右下角操作区域 | ReactNode | - | |
| footer | 自定义脚部内容 | ReactNode | - | |
| header | 自定义头部内容 | ReactNode | - | |
| imageBadge | 自定义图片徽章 | ReactNode | - | |
| infoFooter | 自定义内容区脚部内容 | ReactNode | - | |
| price | 自定义价格 | ReactNode | - | |
| promoDescription | 自定义促销描述内容 | ReactNode | - | |
| promoHeader | 自定义促销头部内容 | ReactNode | - | |
| shopDescription | 自定义店铺介绍内容 | ReactNode | - | `v0.6.0` |
### SemanticDOM[](#semanticdom "SemanticDOM的直接链接")
| 参数 | 说明 |
| --------- | ---------------- |
| body | 设置卡片内容区域 |
| cover | 设置封面 |
| container | 设置容器区域 |
| header | 设置头部区域 |
| footer | 设置脚部区域 |
| title | 设置卡片标题 |
---
# Tag 标签
## 介绍[](#介绍 "介绍的直接链接")
用于标记和分类的标签。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQTag } from '@fq/fq-weapp-ui';
```
组件依赖的样式文件（仅按需引用时需要）
```
import '@fq/fq-weapp-ui/dist/styles/components/tag.scss';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
标签内容
标签内容
标签内容
```
### 边框模式[](#边框模式 "边框模式的直接链接")
```
标签内容
标签内容
```
### 圆角模式&自定义圆角[](#圆角模式自定义圆角 "圆角模式&自定义圆角的直接链接")
```
标签内容
标签内容
标签内容
标签内容
```
### 自定义图标[](#自定义图标 "自定义图标的直接链接")
```
}>标签内容
```
### 多彩标签[](#多彩标签 "多彩标签的直接链接")
```
green
red
orange
green
red
orange
自定义颜色
```
### 图片模式[](#图片模式 "图片模式的直接链接")
```
```
## API[](#api "API的直接链接")
### 基础属性[](#基础属性 "基础属性的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ------- | --------------------------------------------------- | ------------------------------ | -------- | ---- |
| size | 设置标签大小 | `large` / `middle` / `small` | `middle` | |
| type | 设置标签类型，`text` 为文本标签，`image` 为图片标签 | `text` / `image` | `text` | |
| onClick | 点击事件 | `(event: ITouchEvent) => void` | - | |
### `type='text'`属性[](#typetext属性 "typetext属性的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| --------------- | ---------------------- | -------------------- | ------- | ---- |
| backgroundColor | 设置背景颜色 | string | - | |
| borderColor | 设置边框颜色 | string | - | |
| bordered | 是否显示边框 | boolean | `false` | |
| color | 设置文字颜色 | string | - | |
| icon | 设置图标 | ReactNode | - | |
| round | 是否为圆角或自定义圆角 | `boolean` / `number` | `false` | |
### `type='image'`属性[](#typeimage属性 "typeimage属性的直接链接")
| 参数 | 说明 | 类型 | 默认值 | 版本 |
| ---- | ------------ | ------ | ------ | ---- |
| url | 设置图片地址 | string | - | |
---
# FQWaterMark 水印组件
## 介绍[](#介绍 "介绍的直接链接")
水印的主要作用包括版权保护、防伪鉴别、品牌宣传和安全隐私保护。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
import { FQWaterMark } from '@fq/fq-weapp-ui';
```
### 基础用法[](#基础用法 "基础用法的直接链接")
#### 单行水印[](#单行水印 "单行水印的直接链接")
```
```
#### 多行水印[](#多行水印 "多行水印的直接链接")
```
```
#### 水印颜色[](#水印颜色 "水印颜色的直接链接")
```
```
## API[](#api "API的直接链接")
### 属性[](#属性 "属性的直接链接")
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
| ------- | ------------------------ | ------------------ | ------ | ---------------- |
| content | 水印内容，传数组表示多行 | string / string\[] | | |
| color | 水印颜色 | string | | rgba(0,0,0,0.06) |
---
# Modal 组件
## 介绍[](#介绍 "介绍的直接链接")
提供一个简单的 `Modal` 框，用于展示弹窗内容。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
// 1. 引入
import { FQModal } from "@fq/fq-weapp-ui";
```
组件依赖的样式文件（仅按需引用时需要）
```
import "@fq/fq-weapp-ui/dist/styles/components/modal.scss";
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
xxx
```
## API[](#api "API的直接链接")
### 属性[](#属性 "属性的直接链接")
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
| -------------- | -------------------------------------------- | ------------------- | ------ | ------ |
| visible | 是否显示模态框 | boolean | - | - |
| canCloseByMask | 点击蒙层是否允许关闭 | boolean | - | false |
| unCoverNavBar | 是否覆盖导航栏 | boolean | - | false |
| innerClassName | 内部容器类名 | string | - | - |
| className | 模态框样式类名 | string | - | - |
| maskClassName | 蒙层样式类名 | string | - | - |
| style | 模态框样式 | React.CSSProperties | - | - |
| childrenStyle | 模态框内容样式 | React.CSSProperties | - | - |
| addTop | 顶部偏移量 | number | - | 0 |
| catchMove | 是否阻止滑动穿透 | boolean | - | false |
| noRendering | 是否执行预渲染，用于提前渲染模态框内部的内容 | boolean | - | false |
### 方法[](#方法 "方法的直接链接")
| 函数名 | 说明 | 参数 |
| ------- | -------------- | ---- |
| onClose | 模态框关闭事件 | - |
---
# NoticeBar 组件
## 介绍[](#介绍 "介绍的直接链接")
提供一个简单的 `NoticeBar` 框，用于展示信息通知栏。
## 用法[](#用法 "用法的直接链接")
### 基本引入[](#基本引入 "基本引入的直接链接")
```
// 1. 引入
import { FQNoticeBar } from "@fq/fq-weapp-ui";
```
组件依赖的样式文件（仅按需引用时需要）
```
import "@fq/fq-weapp-ui/dist/styles/components/notice-bar.scss";
```
### 基础用法[](#基础用法 "基础用法的直接链接")
```
```
### 支持跳转[](#支持跳转 "支持跳转的直接链接")
```
```
### 支持关闭[](#支持关闭 "支持关闭的直接链接")
```
```
### 有按钮[](#有按钮 "有按钮的直接链接")
```
```
### 按钮+关闭[](#按钮关闭 "按钮+关闭的直接链接")
```
```
### 跑马灯[](#跑马灯 "跑马灯的直接链接")
```
```
### 信息通知栏-多行文本[](#信息通知栏-多行文本 "信息通知栏-多行文本的直接链接")
```
// 换行
// 有标题
// 有标题+按钮
```
## API[](#api "API的直接链接")
### 属性[](#属性 "属性的直接链接")
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
| --------------- | --------------------------------------------------- | ------------------- | ----------------------- | ------- |
| content | 通知文本内容 | string | - | - |
| type | 基本样式类型 | string | error、success、warning | warning |
| basicStyles | 基础类型样式 | React.CSSProperties | - | - |
| leftIcon | 左侧图标名称 | ReactNode | - | - |
| showLink | 显示连接箭头icon | boolean | - | false |
| buttonProps | 传入的按钮属性 | FQButtonProps | - | - |
| closeable | 是否显示关闭按钮 | boolean | - | false |
| wrapable | 是否开启文本换行 | boolean | - | false |
| scrollable | 是否开启滚动播放，null 表示根据内容是否溢出自动判断 | boolean \| null | - | null |
| delay | 滚动延迟时间（秒） | number | - | 1 |
| speed | 滚动速度 | number | - | 50 |
| loop | 循环滚动次数 0 表示无限循环 | number | - | 0 |
| headerTitle | 标题文案 | string | - | - |
| className | 自定义样式类名 | string | - | - |
| parentClassName | 小程序查询节点的父级类名（复杂嵌套场景使用） | string | - | - |
### 方法[](#方法 "方法的直接链接")
| 函数名 | 说明 | 参数 |
| ----------- | -------------------- | ---- |
| onClick | 点击整个栏目回调事件 | - |
| onLinkClick | 链接回调事件 | - |
| onClose | 关闭回调闭事件 | - |
---
# 主题定制
## 介绍[](#介绍 "介绍的直接链接")
`@fq/fq-weapp-ui` 只有一套默认的颜色氛围，主要分为主题色、中性色、家族色3类，其中主题色是整个产品的主色调，中性色是辅助色调，家族色是一些特殊的色调，比如警告色、危险色、价格色、省钱卡专用色等。目前支持自定义主题的方式是 `SCSS 变量覆盖` 的方式，后续会支持更多的自定义方式。
### SCSS 变量覆盖[](#scss-变量覆盖 "SCSS 变量覆盖的直接链接")
`@fq/fq-weapp-ui` 的样式是基于 `SCSS` 编写的，所以可以直接在项目中改变样式变量。
新建一个主题样式文件，例如 `custom-variables.scss`，并写入以下内容：
```
// 主题色
$color-primary: #ff0000;
// 中性色
$bg-color-base: #666666;
// 家族色
$color-family-green: #52C41B;
@import '~@fq/fq-weapp-ui/dist/styles/components/sprite-icon/index.scss';
```
> 覆写的变量，需要在引入 `@fq/fq-weapp-ui` 默认样式之前引入，[默认主题变量命名](https://git.ifengqun.com/fq-front/fq-weapp-ui/-/tree/master/packages/fq-weapp-ui/src/styles/variables/default.scss)
之后在项目的入口文件中引入以上的样式文件即可（无需重复引入组件的默认样式）
```
/* app.ts */
import './custom-variables.scss'
```
### SCSS MIXINS[](#scss-mixins "SCSS MIXINS的直接链接")
`@fq/fq-weapp-ui` 提供一些常用的样式MIXIN，方便开发者使用，具体可以查看 [MIXINS](https://git.ifengqun.com/fq-front/fq-weapp-ui/-/blob/master/packages/fq-weapp-ui/src/styles/mixins/index.scss)
---
# 快速上手
## 使用前准备[](#使用前准备 "使用前准备的直接链接")
在使用 `@fq/fq-weapp-ui` 之前，你需要先安装 `@fq/fq-weapp-ui`，并引入样式。
### 配置npm私有源[](#配置npm私有源 "配置npm私有源的直接链接")
```
npm config set registry http://npm.ifengqun.com:4873/
```
这里推荐使用 nrm 来管理 npm 源，可以通过以下命令安装 nrm：
```
npm install -g nrm
```
然后通过以下命令添加私有源：
```
nrm add fengqun http://npm.ifengqun.com:4873/
```
最后使用私有源：
```
nrm use fengqun
```
### 安装[](#安装 "安装的直接链接")
```
# 使用 npm 安装
npm install -S @fq/fq-weapp-ui
# 使用 yarn 安装
yarn add @fq/fq-weapp-ui
# 使用 pnpm 安装
pnpm install -S @fq/fq-weapp-ui
```
## 基础用法[](#基础用法 "基础用法的直接链接")
### 引入所需组件[](#引入所需组件 "引入所需组件的直接链接")
在代码中`import`需要的组件
```
// page.tsx
import {
FQSpriteIcon,
FQSpriteIconProps,
SpriteIconProps,
} from "@fq/fq-weapp-ui";
// 除了引入所需的组件，还需要手动引入组件样式
// app.ts
import '@fq/fq-weapp-ui/dist/styles/index.scss';
```
### 引入组件样式的三种方式[](#引入组件样式的三种方式 "引入组件样式的三种方式的直接链接")
1. 全局引入（TS中）：在入口文件引入`@fq/fq-weapp-ui`样式文件
```
// app.ts
import '@fq/fq-weapp-ui/dist/styles/index.scss';
```
2. 全局引入（SCSS中）：在需要使用组件的文件中引入`@fq/fq-weapp-ui`样式文件
```
// app.scss
@import '~@fq/fq-weapp-ui/dist/styles/index.scss';
```
3. 按需引入：在页面样式或全局样式中 `import` 需要的组件样式
```
// page.scss
@import '~@fq/fq-weapp-ui/dist/styles/components/sprite-icon/index.scss';
```
> 具体的组件样式文件请查看 [组件样式列表](https://git.ifengqun.com/fq-front/fq-weapp-ui/-/tree/master/packages/fq-weapp-ui/src/styles/components)
## 体验[](#体验 "体验的直接链接")
使用微信扫一扫体验 `小程序` 组件示例
---
# 色彩
色彩体系主要定义了设计中的基础色板。
## 使用[](#使用 "使用的直接链接")
```
/* fq-mall 项目中已在 app.scss 全局引入，无需手动引入此文件 */
@import '~@fq/fq-weapp-ui/dist/styles/variables/default';
.xxx {
color: $color-primary;
}
```
## 基础色板[](#基础色板 "基础色板的直接链接")
主色系
$color-primary#00B68F
$color-primary-border#CCF0E9
$color-primary-disabled#78CDBA
$color-primary-bg#EBFAF6
$color-primary-gradientlinear-gradient(90deg, #38DA7D 3%, #02B0AA 100%)
绿色系
$color-family-green#52C41A
$color-family-green-bg#F6FFED
$color-family-green-border#D9F7BE
$color-family-green-hover#73D13D
$color-family-green-active#389E0D
蓝色系
$color-family-blue#1677FF
$color-family-blue-bg#E6F7FF
$color-family-blue-border#BAE7FF
$color-family-blue-hover#4096FF
$color-family-blue-active#096DD9
红色系
$color-family-red#FF4D4F
$color-family-red-bg#FFF1F0
$color-family-red-border#FFCCC7
$color-family-red-hover#FF7875
$color-family-red-active#D92D33
$color-family-red-gradientlinear-gradient(135deg, #FD4A39 0%, #FD397E 100%)
$color-family-red-price#FA2B19
$color-family-red-savings#FE3659
橙色系
$color-family-orange#FF8F16
$color-family-orange-light#FF6A00
$color-family-orange-dark#AC5300
$color-family-orange-price#64380B
$color-family-orange-bg#FFF7E6
$color-family-orange-border#FFE7BA
$color-family-orange-hover#FFA940
$color-family-orange-active#D46B08
$color-family-orange-gradientlinear-gradient(180deg, #FFDB66 0%, #FF6040 100%)
$color-family-orange-diagonal-gradientlinear-gradient(141deg, #FC0 -1%, #FF4D00 117%)
黄色系
$color-family-yellow#FFD321
$color-family-yellow-bg#FFF6D3
$color-family-yellow-gradientlinear-gradient(180deg, #FFE56F 0%, #FFD300 100%)
紫色系
$color-family-purple#722ED1
$color-family-purple-bg#F9F0FF
$color-family-purple-border#EFDBFF
$color-family-purple-gradientlinear-gradient(138deg, #9067F4 0%, #6328F3 100%)
## 功能色板[](#功能色板 "功能色板的直接链接")
文本色系
$text-color-base#333
$text-color-base-weak#666
$text-color-secondary#999
$text-color-disabled#BFBFBF
$text-color-white#fff
背景色系
$bg-color#FFF
$bg-color-base#F7F8F9
$bg-color-light#F5F5F5
$bg-color-lighter#EEE
边框色系
$border-color#E6E6E6
$border-color-dark#DDD
---