---
url: haaaaaaaaaaaaa-uni.cn/CHANGELOG.md
---
# Changelog

## 0.0.74

### Patch Changes

* 修复 Live Photo 长按交互与小程序 swiper 手势冲突的问题。

## 0.0.73

### Patch Changes

* 今天买了杯奶茶，喝完发现吸管比奶茶更有存在感。

## 0.0.72

### Patch Changes

* a4d7625: 修复发布流程和 web-types 构建兼容性，发布 `0.0.72`。

## 0.0.71

### Patch Changes

* 4f477bf: 迁移到 Changesets 发布流程，并清理旧的 Changelogen 发布脚本与无效的 CI 发布步骤。

## v0.0.70

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.68...v0.0.70)

### 🚀 Enhancements

* **livephoto:** Add indicator loading animation & code cleanup ([ee4d57b](https://github.com/iceywu/uni-ui-plus/commit/ee4d57b))
* Livephoto loading animation, docs sync, CI fixes & code cleanup ([83c71e5](https://github.com/iceywu/uni-ui-plus/commit/83c71e5))

### 🩹 Fixes

* 结构调整 ([881ff9b](https://github.com/iceywu/uni-ui-plus/commit/881ff9b))
* 格式化调整 ([5b75718](https://github.com/iceywu/uni-ui-plus/commit/5b75718))
* 优化变量 ([cf5fb69](https://github.com/iceywu/uni-ui-plus/commit/cf5fb69))
* Add shebang to husky hooks for Windows compatibility ([36e3155](https://github.com/iceywu/uni-ui-plus/commit/36e3155))
* Add @vue/test-utils dep, remove broken composable tests ([24d4b73](https://github.com/iceywu/uni-ui-plus/commit/24d4b73))
* 优化构建 ([5f81ff8](https://github.com/iceywu/uni-ui-plus/commit/5f81ff8))
* Lint fixes and VPIframe use relative demo URL for production ([53fbaab](https://github.com/iceywu/uni-ui-plus/commit/53fbaab))

### 📖 Documentation

* Update README and installation guides ([834c108](https://github.com/iceywu/uni-ui-plus/commit/834c108))

### 🏡 Chore

* Release v0.0.68 ([21f6687](https://github.com/iceywu/uni-ui-plus/commit/21f6687))
* **release:** V0.0.69 ([bc978bd](https://github.com/iceywu/uni-ui-plus/commit/bc978bd))
* **release:** 更新版本至 v0.0.69，更新变更日志 ([2a86e16](https://github.com/iceywu/uni-ui-plus/commit/2a86e16))
* 更新版本至 v0.0.69 ([9846672](https://github.com/iceywu/uni-ui-plus/commit/9846672))
* Upgrade deps, clean up unused code, optimize component library design ([0c363c4](https://github.com/iceywu/uni-ui-plus/commit/0c363c4))
* Regenerate pnpm-lock.yaml ([a47dc68](https://github.com/iceywu/uni-ui-plus/commit/a47dc68))
* Add LICENSE file ([cf56355](https://github.com/iceywu/uni-ui-plus/commit/cf56355))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))
* Icey Wu ([@IceyWu](https://github.com/IceyWu))

## v0.0.69

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.68...v0.0.69)

### 🏡 Chore

* Release v0.0.68 ([21f6687](https://github.com/iceywu/uni-ui-plus/commit/21f6687))

### ❤️ Contributors

* IceyWu <3128006406@qq.com>

## v0.0.67

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.66...v0.0.67)

### 🚀 Enhancements

* Add swiper component with customizable features and navigation ([13d656a](https://github.com/iceywu/uni-ui-plus/commit/13d656a))
* \[List] 添加自动重置下拉刷新状态的功能，优化列表组件的使用体验 ([4f222b5](https://github.com/iceywu/uni-ui-plus/commit/4f222b5))

### 🩹 Fixes

* Refactor SCSS imports to use @use and @forward syntax ([99f89ff](https://github.com/iceywu/uni-ui-plus/commit/99f89ff))

### 📖 Documentation

* \[livephoto]修正自定义图片内容参数的格式说明 ([bda858b](https://github.com/iceywu/uni-ui-plus/commit/bda858b))

### 🏡 Chore

* **release:** 更新版本至 v0.0.67，更新变更日志 ([7185549](https://github.com/iceywu/uni-ui-plus/commit/7185549))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))

## v0.0.66

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.65...v0.0.66)

### 🏡 Chore

* **release:** 更新版本至 v0.0.66，更新变更日志 ([00df583](https://github.com/iceywu/uni-ui-plus/commit/00df583))

### 🎨 Styles

* 优化组件样式，统一类名命名规则，调整样式结构 ([ff04ecd](https://github.com/iceywu/uni-ui-plus/commit/ff04ecd))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))

## v0.0.65

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.64...v0.0.65)

### 🏡 Chore

* **release:** 更新版本至 v0.0.64，更新变更日志 ([a16c4e5](https://github.com/iceywu/uni-ui-plus/commit/a16c4e5))

### 🎨 Styles

* \[skeleton] 优化@include顺序 ([c1402de](https://github.com/iceywu/uni-ui-plus/commit/c1402de))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))

## v0.0.64

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.63...v0.0.64)

### 🩹 Fixes

* 移除重复的背景样式定义，优化样式代码 ([95629fa](https://github.com/iceywu/uni-ui-plus/commit/95629fa))

### 🏡 Chore

* Release v0.0.63 ([82cf858](https://github.com/iceywu/uni-ui-plus/commit/82cf858))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))

## v0.0.63

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.62...v0.0.63)

### 🚀 Enhancements

* **LivePhoto组件**: 新增图片插槽支持，允许完全自定义图片内容
* **LivePhoto组件**: 新增展示模式 `displayOnly`，仅显示图片和指示器，不支持视频交互
* **LivePhoto组件**: 新增指示器位置自定义功能，支持 `indicatorLeft` 和 `indicatorTop` 属性
* 更新 LivePhoto 组件示例页面，展示新功能的使用方法

### 📚 Documentation

* 新增 LivePhoto 组件功能更新说明文档
* 更新 API 文档，添加新增属性的说明

### ❤️ Contributors

* IceyWu ([@iceywu](https://github.com/iceywu))

## v0.0.62

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.61...v0.0.62)

### 🚀 Enhancements

* 更新 LivePhoto 组件样式导入方式，使用 @use 替代 @import ([d8b644d](https://github.com/iceywu/uni-ui-plus/commit/d8b644d))
* 更新 Algolia 搜索配置，添加应用 ID、API 密钥和索引名称 ([decbdeb](https://github.com/iceywu/uni-ui-plus/commit/decbdeb))

### 🏡 Chore

* 发布 v0.0.62 版本 ([95101e2](https://github.com/iceywu/uni-ui-plus/commit/95101e2))

### ❤️ Contributors

* IceyWu ([@iceywu](https://github.com/iceywu))

## v0.0.61

* 添加 LivePhoto 组件及其文档，支持视频和图片的长按播放功能 ([ddc62ed](https://github.com/iceywu/uni-ui-plus/commit/ddc62ed))
* Add LivePhoto component and enhance documentation ([cbfacd0](https://github.com/iceywu/uni-ui-plus/commit/cbfacd0))
* 更新 LivePhoto 组件的指示器样式，添加纯 CSS 图标支持 ([7379731](https://github.com/iceywu/uni-ui-plus/commit/7379731))

## v0.0.60

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.58...v0.0.60)

### 🚀 Enhancements

* Add waterfall component and its documentation ([ad02340](https://github.com/iceywu/uni-ui-plus/commit/ad02340))
* 更新瀑布流组件，添加自定义图片源获取方法及相关示例 ([b97e5c5](https://github.com/iceywu/uni-ui-plus/commit/b97e5c5))

### 🏡 Chore

* 更新版本号至 0.0.58，并更新变更日志 ([1bcc154](https://github.com/iceywu/uni-ui-plus/commit/1bcc154))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))

## v0.0.59

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.58...v0.0.59)

### 🏡 Chore

* 更新版本号至 0.0.58，并更新变更日志 ([1bcc154](https://github.com/iceywu/uni-ui-plus/commit/1bcc154))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))

## v0.0.58

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.57...v0.0.58)

### 🚀 Enhancements

* Add empty state component and integrate into the application ([9faab16](https://github.com/iceywu/uni-ui-plus/commit/9faab16))
* 更新列表组件，添加虚拟列表功能及美化自定义分段器 ([f930646](https://github.com/iceywu/uni-ui-plus/commit/f930646))

### 🏡 Chore

* 更新版本号至 0.0.57 ([1e0f419](https://github.com/iceywu/uni-ui-plus/commit/1e0f419))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))

## v0.0.57

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.56...v0.0.57)

### 🚀 Enhancements

* 添加骨架屏组件及相关文档，更新图片组件功能 ([5c3ce36](https://github.com/iceywu/uni-ui-plus/commit/5c3ce36))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))

## v0.0.56

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.55...v0.0.56)

### 🩹 Fixes

* Update info ([b23c7db](https://github.com/iceywu/uni-ui-plus/commit/b23c7db))
* Update info ([e9bc010](https://github.com/iceywu/uni-ui-plus/commit/e9bc010))

### 🏡 Chore

* 更新变更日志，添加 v0.0.55 版本信息 ([f182844](https://github.com/iceywu/uni-ui-plus/commit/f182844))
* 更新版本号至 0.0.55 ([a725cf0](https://github.com/iceywu/uni-ui-plus/commit/a725cf0))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))

## v0.0.55

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.54...v0.0.55)

### 🩹 Fixes

* 将样式导入方式从 @import 更改为 @use ([c2ce9a7](https://github.com/iceywu/uni-ui-plus/commit/c2ce9a7))

### 🏡 Chore

* 结构重构 ([9f798c6](https://github.com/iceywu/uni-ui-plus/commit/9f798c6))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))

## v0.0.54

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.53...v0.0.54)

## v0.0.55

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.54...v0.0.55)

## v0.0.53

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.52...v0.0.53)

### 🚀 Enhancements

* 添加虚拟列表支持，优化列表组件性能和样式 ([66c6c50](https://github.com/iceywu/uni-ui-plus/commit/66c6c50))
* 更新 .gitignore 和 eslint 配置以忽略 playground 目录 ([afb9088](https://github.com/iceywu/uni-ui-plus/commit/afb9088))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))

## v0.0.52

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.5...v0.0.52)

### 🚀 Enhancements

* 添加 minHeight 属性支持到图像组件的样式计算 ([9668a00](https://github.com/iceywu/uni-ui-plus/commit/9668a00))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))

## v0.0.5

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.4...v0.0.5)

### 🚀 Enhancements

* 添加图像组件及相关样式，更新依赖项 ([c1ad286](https://github.com/iceywu/uni-ui-plus/commit/c1ad286))
* 添加 utils 函数，更新 image 组件的 props 和样式 ([815972b](https://github.com/iceywu/uni-ui-plus/commit/815972b))

### 🏡 Chore

* Refactor code structure for improved readability and maintainability ([d419088](https://github.com/iceywu/uni-ui-plus/commit/d419088))

### ❤️ Contributors

* IceyWu ([@Life-Palette](https://github.com/Life-Palette))

## v0.0.4

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.3...v0.0.4)

### 🚀 Enhancements

* Initialize playground with basic structure and configuration ([baf54ce](https://github.com/iceywu/uni-ui-plus/commit/baf54ce))
* \[components] add Skeleton Components ([e3157ef](https://github.com/iceywu/uni-ui-plus/commit/e3157ef))

### 🩹 Fixes

* 修复.gitignore中dist目录的忽略规则 ([a1bc7a8](https://github.com/iceywu/uni-ui-plus/commit/a1bc7a8))

### 🏡 Chore

* **release:** V0.0.3 ([c453a1a](https://github.com/iceywu/uni-ui-plus/commit/c453a1a))

### ❤️ Contributors

* IceyWu ([@Life-Palette](http://github.com/Life-Palette))

## v0.0.3

[compare changes](https://github.com/iceywu/uni-ui-plus/compare/v0.0.2...v0.0.3)

### 🩹 Fixes

* 修复Resolver引入方式异常 ([1c3ff75](https://github.com/iceywu/uni-ui-plus/commit/1c3ff75))

### 🏡 Chore

* Update version ([33cd64a](https://github.com/iceywu/uni-ui-plus/commit/33cd64a))

### ❤️ Contributors

* IceyWu ([@Life-Palette](http://github.com/Life-Palette))

## v0.0.2

---

---
url: haaaaaaaaaaaaa-uni.cn/component/config-provider.md
---
# ConfigProvider 全局配置

用于为组件提供主题模式和主题变量配置。

## 深色模式

```html
<up-config-provider theme="dark">
  <up-empty description="暂无数据" />
</up-config-provider>
```

## 自定义主题变量

```html
<up-config-provider :theme-vars="{ emptyDescriptionColor: '#999999' }">
  <up-empty description="暂无数据" />
</up-config-provider>
```

## Attributes

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| theme | 主题风格 | `'light' \| 'dark'` | `'light'` |
| theme-vars | 自定义主题变量 | `ConfigProviderThemeVars` | `{}` |

## Slots

| 名称 | 说明 |
| --- | --- |
| default | 组件内容 |

## 类型定义

`ConfigProviderThemeVars` 包含基础色、空状态、骨架屏、轮播图和轮播指示器的主题变量。

---

---
url: haaaaaaaaaaaaa-uni.cn/component/empty.md
---
# Empty 空状态

用于展示页面或数据为空时的占位提示。

## 基本用法

最简单的用法，展示默认的空状态图片和描述。

```vue
<template>
  <up-empty description="无数据" />
</template>
```

## 不同图片类型

通过 `image` 属性切换不同的空状态图片类型，可选值有 `empty`、`error`、`network`，也支持自定义图片 URL。

```vue
<template>
  <up-empty image="empty" description="无内容" />
  <up-empty image="error" description="加载失败/错误" />
  <up-empty image="network" description="无网络" />
</template>
```

## 自定义图片

通过传入图片 URL 自定义展示图片。

```vue
<template>
  <up-empty
    description="描述文字"
    image="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg"
  />
</template>
```

## 自定义内容

通过默认插槽可自定义底部内容，如添加按钮等。

```vue
<template>
  <up-empty image="error" description="加载失败">
    <div style="margin-top: 10px">
      <button icon="refresh" type="primary">重试</button>
    </div>
  </up-empty>
</template>
```

## 图片大小

通过 `imageSize` 属性自定义图片大小，单位为 px。

```vue
<template>
  <up-empty imageSize="120" description="自定义图片大小" />
</template>
```

## Attributes

| 参数         | 说明                                         | 类型                                         | 默认值    |
| ------------ | -------------------------------------------- | -------------------------------------------- | --------- |
| image        | 图片类型，可选值为 `empty`、`error`、`network`，或图片 URL | string                                       | 'empty'   |
| imageSize    | 图片大小，单位为 px                           | number | string                             | -         |
| description  | 图片下方的描述文字                            | string                                       | -         |
| customStyle  | 自定义样式                                   | object | string                             | -         |

## Events

| 事件名称 | 说明         | 参数 |
| -------- | ------------ | ---- |
| click    | 点击空状态时触发 | -    |

## Slots

| 名称         | 说明             |
| ------------ | ---------------- |
| image        | 自定义图片内容   |
| description  | 自定义描述内容   |
| default      | 图片下方自定义内容 |

## 外部样式类

| 类名         | 说明       |
| ------------ | ---------- |
| custom-class | 根节点样式 |

## 示例

更多用法请参考 `src/subPages/empty/Index.vue` 示例页面。

---

---
url: haaaaaaaaaaaaa-uni.cn/component/img.md
---
# Img 图片

增强版的 img 标签，支持多种图片填充模式、懒加载、加载占位、自定义加载/失败内容、圆角/圆形、滤镜、图片预览等功能。

## 基本用法

基础用法与原生 image 标签一致，可以设置 `src` 、 `width` 、`height` 等原生属性。

```vue
<up-image
  src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg"
  width="120"
  height="120"
/>
```

## 延时加载

通过 `delay` 属性设置图片加载延迟（单位 ms）。

```vue
<up-image
  src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg"
  width="120"
  height="120"
  :delay="2000"
/>
```

## 预加载占位图

通过 `placeholder-src` 属性设置加载中的占位图片。

```vue
<up-image
  src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg"
  placeholder-src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg?x-oss-process=image/resize,p_50"
  width="120"
  height="120"
  :delay="2000"
/>
```

## 图片加载滤镜

通过 `filter` 属性设置加载过程中的图片模糊效果。

```vue
<up-image
  src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg"
  placeholder-src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg?x-oss-process=image/resize,p_50"
  width="120"
  height="120"
  :delay="40000"
  :filter="30"
/>
```

## 自定义圆角

通过 `radius` 属性自定义圆角大小，或通过 `round` 属性设置为圆形。

```vue
<up-image
  src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg"
  width="120"
  height="120"
  :radius="8"
/>
<up-image
  src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg"
  width="100"
  height="100"
  round
/>
```

## 填充模式

通过 `mode` 属性设置图片填充方式，支持多种小程序原生模式。

```vue
<up-image
  src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg"
  width="120"
  height="120"
  mode="center"
/>
```

可选值：`scaleToFill`、`aspectFit`、`aspectFill`、`heightFix`、`widthFix`、`top left`、`top right`、`bottom left`、`bottom right`、`right`、`left`、`center`、`bottom`、`top`。

## 懒加载

通过 `lazy-load` 属性开启图片懒加载（默认开启）。

```vue
<up-image
  src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg"
  width="120"
  height="120"
  :lazy-load="true"
/>
```

## 图片预览

通过 `enable-preview` 属性支持点击图片预览，底层调用 `uni.previewImage`。

```vue
<up-image
  src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg"
  width="100"
  height="100"
  :enable-preview="true"
/>
```

可通过 `preview-src` 指定预览的图片地址。

```vue
<up-image
  src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example1.jpg"
  preview-src="https://oss-console-img-demo-cn-hangzhou-3az.oss-cn-hangzhou.aliyuncs.com/example2.jpg"
  width="100"
  height="100"
  :enable-preview="true"
/>
```

## 自定义插槽

可通过 `loading` 和 `error` 插槽自定义加载中和加载失败时的内容。

```vue
<up-image :src="src" width="120" height="120" :delay="40000">
  <template #loading>
    <view class="custom-loading">加载中自定义</view>
  </template>
</up-image>

<up-image src="1" width="120" height="120" radius="8">
  <template #error>
    <view class="custom-error">加载异常自定义</view>
  </template>
</up-image>
```

## Attributes

| 参数                   | 说明                                               | 类型            | 可选值                                                                                                                                                                             | 默认值        | 最低版本 |
| ---------------------- | -------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------- |
| src                    | 图片链接                                           | string          | -                                                                                                                                                                                  | -             | -        |
| width                  | 宽度，默认单位为 px                                | number / string | -                                                                                                                                                                                  | -             | -        |
| height                 | 高度，默认单位为 px                                | number / string | -                                                                                                                                                                                  | -             | -        |
| mode                   | 填充模式                                           | ImageMode       | 'top left' / 'top right' / 'bottom left' / 'bottom right' / 'right' / 'left' / 'center' / 'bottom' / 'top' / 'heightFix' / 'widthFix' / 'aspectFill' / 'aspectFit' / 'scaleToFill' | 'scaleToFill' | -        |
| round                  | 是否显示为圆形                                     | boolean         | -                                                                                                                                                                                  | false         | -        |
| radius                 | 圆角大小，默认单位为 px                            | number / string | -                                                                                                                                                                                  | -             | -        |
| delay                  | 图片加载延迟，单位 ms                              | number          | -                                                                                                                                                                                  | 0             | -        |
| placeholder-src        | 加载中占位图片                                     | string          | -                                                                                                                                                                                  | -             | -        |
| filter                 | 加载中滤镜模糊值，单位 px                          | number / string | -                                                                                                                                                                                  | -             | -        |
| min-height             | 最小高度，默认 200rpx                              | number / string | -                                                                                                                                                                                  | 200rpx        | -        |
| lazy-load              | 是否开启懒加载                                     | boolean         | -                                                                                                                                                                                  | true          | -        |
| custom-style           | 自定义样式                                         | string          | -                                                                                                                                                                                  | ''            | -        |
| custom-class           | 根节点自定义类名                                   | string          | -                                                                                                                                                                                  | ''            | -        |
| enable-preview         | 是否支持点击预览                                   | boolean         | -                                                                                                                                                                                  | false         | -        |
| preview-src            | 预览图片链接                                       | string          | -                                                                                                                                                                                  | -             | -        |
| loading-text           | 加载中提示文字                                     | string          | -                                                                                                                                                                                  | '加载中...'   | 0.0.70   |
| error-text             | 加载失败提示文字                                   | string          | -                                                                                                                                                                                  | '加载异常'    | 0.0.70   |

## Events

| 事件名称 | 说明                 | 参数                        | 最低版本 |
| -------- | -------------------- | --------------------------- | -------- |
| click    | 点击事件             | (event: MouseEvent) => void | -        |
| load     | 当图片载入完毕时触发 | `{height, width}`           | -        |
| error    | 当错误发生时触发     | `{errMsg}`                  | -        |

## Slots

| 名称    | 说明               | 最低版本 |
| ------- | ------------------ | -------- |
| loading | 图片加载时展示     | -         |
| error   | 图片加载失败后展示 | -         |

## 外部样式类

| 类名         | 说明                 | 最低版本 |
| ------------ | -------------------- | -------- |
| custom-class | 根节点样式           | -        |
| custom-image | image 外部自定义样式 | -        |

## 示例

更多用法请参考 `src/subPages/img/Index.vue` 示例页面。

---

---
url: haaaaaaaaaaaaa-uni.cn/component/list.md
---
# List 列表

增强版的列表组件，支持虚拟列表、下拉刷新、上拉加载、骨架屏、空状态等多种功能，适用于大数据量场景。

## 基本用法

最基础的列表用法，支持通过 `v-model:list-obj` 双向绑定列表数据对象。

```vue
<script setup>
import { onMounted } from 'vue'
import { get, list, sleep } from '@iceywu/utils'
import { useRequest } from 'vue-hooks-pure'
// 模拟api
async function getTestApi(params) {
  await sleep(500)
  const { page = 0, size = 10, maxPage = 3 } = params
  const baseSize = page * size
  const data = list(0, size - 1, (index) => {
    const element = baseSize + index
    return {
      id: element,
      cover: `https://picsum.photos/id/${element}/200/300`,
      title: `title ${element}`,
      desc: `desc ${element}`
    }
  })
  return {
    code: 200,
    msg: '查询成功',
    result: {
      content: data,
      last: page + 1 === maxPage,
      total: 100
    }
  }
}

const {
  onRefresh,
  onLoad: onLoadMore,
  result
} = useRequest(getTestApi, {
  target: 'list',
  loadingDelay: 300,
  getVal: (res) => {
    const list = get(res, 'result.content', [])
    return list
  },
    listOptions: {
      defaultPageKey: 'page',
      defaultSizeKey: 'size',
      defaultDataKey: 'list',
      defaultPage: -1,
      getTotal: (data) => {
        const total = get(data, 'result.total', 0)
        return total
      }
    }
})
onMounted(() => {
  onRefresh()
})
</script>

<template>
  <view class="h-50vh">
    <up-list
      v-model:list-obj="result"
      :scroll-view-props="{
        refresherEnabled: true,
        scrollY: true
      }"
      @on-load="onLoadMore"
      @on-refresh="onRefresh"
    >
      <template #default="{ data: { list } }">
        <view v-for="(item, index) in list" :key="index" class="mb-4 flex">
          <image :src="item.cover" class="h-20 w-20" mode="widthFix" />
          <view>{{ item.title }}</view>
        </view>
      </template>
    </up-list>
  </view>
</template>
```

刷新完成后组件会在列表数据更新时自动重置 `refresher-triggered` 状态，因此常规场景不再需要手动调用 `stopRefresh`。若需要完全自定义刷新流程，可将 `auto-set-triggered` 设为 `false` 后自行控制。

## 虚拟列表

通过 `virtual-list-props.enabled` 开启虚拟列表，适合大数据量渲染，提升性能。你可以通过 `v-model:list-obj` 绑定虚拟列表的数据对象，并设置 `virtual-list-props` 的高度和每项高度。

```vue
<script setup>
import { ref, onMounted } from 'vue'
import { list } from '@iceywu/utils'

const virtualListObj = ref({
  loading: false,
  finished: false,
  refreshing: false,
  list: []
})

onMounted(() => {
  // 生成虚拟列表数据
  virtualListObj.value.list = list(0, 10000, (index) => ({
    id: index,
    cover: `https://picsum.photos/id/${index}/200/300`,
    title: `title ${index}`,
    desc: `desc ${index}`
  }))
})
</script>

<template>
  <up-list
    v-model:list-obj="virtualListObj"
    :scroll-view-props="{
      refresherEnabled: false,
      scrollY: true
    }"
    :virtual-list-props="{
      enabled: true,
      itemHeight: 120,
      containerHeight: 500
    }"
  >
    <template #default="{ item, index }">
      <view class="list-item-box" :key="item.id">
        <image :src="item.cover" class="cover" mode="aspectFill" />
        <view class="content">
          <view class="title">{{ item.title }}</view>
          <view class="desc">{{ item.desc }}</view>
        </view>
      </view>
    </template>
  </up-list>
</template>
```

* `virtual-list-props.itemHeight`：每项的高度（单位 px），需与实际渲染项高度一致。
* `virtual-list-props.containerHeight`：虚拟列表容器高度（单位 px），建议根据页面实际布局设置。
* 虚拟列表插槽参数为 `{ item, index }`，直接渲染每一项内容。

你可以参考 `src/subPages/list/Index.vue` 获取更多虚拟列表的完整用法和样式。

## 下拉刷新与上拉加载

组件内置下拉刷新和上拉加载，分别通过 `@on-refresh` 和 `@on-load` 事件触发。

```vue
<up-list
  v-model:list-obj="result"
  :scroll-view-props="{
    refresherEnabled: true,
    scrollY: true
  }"
  @on-refresh="onRefresh"
  @on-load="onLoadMore"
>
  <template #default="{ data: { list } }">
    <!-- 列表内容 -->
  </template>
</up-list>
```

### 禁用下拉刷新

如需禁用下拉刷新功能，可通过 `scroll-view-props` 的 `refresherEnabled` 属性控制：

```vue
<up-list
  v-model:list-obj="result"
  :scroll-view-props="{
    refresherEnabled: false,  // 禁用下拉刷新
    scrollY: true
  }"
  @on-load="onLoadMore"
>
  <template #default="{ data: { list } }">
    <!-- 列表内容 -->
  </template>
</up-list>
```

## 空状态与骨架屏

支持自定义空状态和 loading 骨架屏。

```vue
<up-list v-model:list-obj="result">
  <template #empty>
    <view>暂无数据</view>
  </template>
  <template #loading>
    <up-skeleton :num="3" />
  </template>
</up-list>
```

## Attributes

| 参数                 | 说明                                                                                    | 类型    | 默认值    |
| -------------------- | --------------------------------------------------------------------------------------- | ------- | --------- |
| is-need-h-full       | 是否需要设置高度为全屏                                                                  | boolean | true      |
| is-need-empty        | 是否需要显示空状态                                                                      | boolean | true      |
| is-need-empty-center | 空状态是否居中显示                                                                      | boolean | true      |
| is-need-empty-pb     | 空状态是否需要底部内边距                                                                | boolean | true      |
| empty-top            | 空状态顶部内边距                                                                        | string  | -         |
| empty-obj            | 空状态对象                                                                              | object  | -         |
| list-obj             | 列表数据对象，包含 loading/finished/list 等                                             | 见 demo | -（必填） |
| auto-set-triggered   | 列表数据更新后是否自动重置下拉刷新状态                                                 | boolean | true      |
| skeleton-obj         | 骨架屏配置                                                                              | 见 demo | 见 demo   |
| scroll-view-props    | scroll-view 属性（[参考文档](https://uniapp.dcloud.net.cn/component/scroll-view.html)） | 见 demo | 见 demo   |
| virtual-list-props   | 虚拟列表配置                                                                            | 见 dem  | 见 demo   |
| is-list-mode         | 是否启用默认列表模式（非虚拟列表时有效）                                                | boolean | false     |

## Events

| 事件名称       | 说明           | 参数                                  |
| -------------- | -------------- | ------------------------------------- |
| update:listObj | 列表数据变更   | (data: ListObj)                       |
| onRefresh      | 下拉刷新       | -                                     |
| onLoad         | 上拉加载       | -                                     |
| onPulling      | 下拉过程中触发 | (event: ScrollViewOnRefresherpulling) |
| onScroll       | 滚动时触发     | (event: ScrollViewOnScrollEvent)      |

## Slots

| 名称    | 说明         |
| ------- | ------------ |
| default | 列表内容     |
| empty   | 空状态内容   |
| loading | 加载中骨架屏 |

## 外部样式类

| 类名         | 说明       |
| ------------ | ---------- |
| custom-class | 根节点样式 |

## 示例

更多用法请参考 `src/subPages/list/Index.vue` 示例页面。

---

---
url: haaaaaaaaaaaaa-uni.cn/component/livephoto.md
---
# LivePhoto 实况照片

基于 video 和 image 实现的实况照片组件，支持长按播放视频、自动播放、自定义样式、事件监听等功能。用户可以通过长按图片来播放对应的视频内容，模拟 iOS Live Photo 的效果。

## 基本用法

基础用法需要提供视频源和静态图片源。

```vue
<up-live-photo
  video-src="https://sample-videos.com/zip/10/mp4/SampleVideo_360x240_1mb.mp4"
  src="https://picsum.photos/400/300?random=1"
  width="300"
  height="200"
  radius="12"
/>
```

## 自定义圆角

通过 `radius` 属性设置自定义圆角大小。

```vue
<up-live-photo
  video-src="https://sample-videos.com/zip/10/mp4/SampleVideo_360x240_1mb.mp4"
  src="https://picsum.photos/400/300?random=1"
  width="300"
  height="200"
  :radius="20"
/>
```

## 自动播放

通过 `autoplay` 属性启用自动播放模式，视频会自动开始播放，播放结束后仍可手动交互。

```vue
<up-live-photo
  video-src="https://sample-videos.com/zip/10/mp4/SampleVideo_360x240_1mb.mp4"
  src="https://picsum.photos/400/300?random=1"
  width="300"
  height="200"
  radius="12"
  :autoplay="true"
/>
```

## 隐藏指示器

通过 `show-indicator` 属性控制指示器的显示。

```vue
<up-live-photo
  video-src="https://sample-videos.com/zip/10/mp4/SampleVideo_360x240_1mb.mp4"
  src="https://picsum.photos/400/300?random=1"
  width="300"
  height="200"
  radius="12"
  :show-indicator="false"
/>
```

## 展示模式

通过 `display-only` 属性启用展示模式，只显示图片和指示器，不支持视频交互。

```vue
<up-live-photo
  video-src="https://sample-videos.com/zip/10/mp4/SampleVideo_360x240_1mb.mp4"
  src="https://picsum.photos/400/300?random=1"
  width="300"
  height="200"
  radius="12"
  :display-only="true"
/>
```

## 自定义指示器位置

通过 `indicator-left` 和 `indicator-top` 属性自定义指示器的位置。

```vue
<up-live-photo
  video-src="https://sample-videos.com/zip/10/mp4/SampleVideo_360x240_1mb.mp4"
  src="https://picsum.photos/400/300?random=1"
  width="300"
  height="200"
  radius="12"
  indicator-left="50"
  indicator-top="30"
/>
```

## 自定义图片插槽

使用 `image` 插槽自定义图片内容，可以添加覆盖层、特效等自定义元素。

```vue
<up-live-photo
  video-src="https://sample-videos.com/zip/10/mp4/SampleVideo_360x240_1mb.mp4"
  src="https://picsum.photos/400/300?random=1"
  width="300"
  height="200"
  radius="12"
>
  <template #image="{ src }">
    <view class="custom-image-container">
      <image :src="src" mode="aspectFill" class="custom-image" />
      <view class="custom-overlay">
        <text>自定义覆盖内容</text>
      </view>
    </view>
  </template>
</up-live-photo>
```

## 事件监听

支持监听长按开始/结束、视频播放/暂停等事件。

```vue
<up-live-photo
  video-src="https://sample-videos.com/zip/10/mp4/SampleVideo_360x240_1mb.mp4"
  src="https://picsum.photos/400/300?random=1"
  width="300"
  height="200"
  radius="12"
  @press-start="onPressStart"
  @press-end="onPressEnd"
  @video-play="onVideoPlay"
  @video-pause="onVideoPause"
  @video-loaded="onVideoLoaded"
  @video-progress="onVideoProgress"
/>
```

## 组件方法

可以通过组件实例调用相关方法。

```vue
<template>
  <up-live-photo
    ref="livePhotoRef"
    video-src="https://sample-videos.com/zip/10/mp4/SampleVideo_360x240_1mb.mp4"
    src="https://picsum.photos/400/300?random=1"
    width="300"
    height="200"
    radius="12"
  />
  <button @click="stopVideo">停止播放</button>
  <button @click="checkIsPlaying">检查播放状态</button>
  <button @click="resetComponent">重置组件</button>
</template>

<script setup>
import { ref } from 'vue'

const livePhotoRef = ref()

function stopVideo() {
  livePhotoRef.value.stopVideo()
}

function checkIsPlaying() {
  const isPlaying = livePhotoRef.value.isPlaying()
  console.log('播放状态:', isPlaying)
}

function resetComponent() {
  livePhotoRef.value.reset()
}
</script>
```

## Attributes

> **注意**：LivePhoto 组件继承了 Image 组件的所有属性，因此支持 Image 组件的所有配置选项。

### LivePhoto 特有属性

| 参数              | 说明                     | 类型               | 默认值           | 可选值 |
|-------------------|--------------------------|-------------------|------------------|--------|
| video-src         | 视频源地址（必填）       | string            | -                | -      |
| show-indicator    | 是否显示Live Photo指示器 | boolean           | true             | -      |
| autoplay          | 是否自动播放             | boolean           | false            | -      |
| enable-vibration  | 是否启用振动反馈         | boolean           | true             | -      |
| muted             | 是否静音播放             | boolean           | true             | -      |
| show-mute-button  | 是否显示静音控制按钮     | boolean           | true             | -      |
| display-only      | 是否仅展示模式           | boolean           | false            | -      |
| indicator-left    | 指示器距左边距离         | string | number  | '20rpx'          | -      |
| indicator-top     | 指示器距顶部距离         | string | number  | '20rpx'          | -      |
| long-press-delay  | 长按触发延迟时间（ms），用于区分短按（点击）与长按 | number | 150 | -      |

### 继承自 Image 组件的属性

| 参数              | 说明                     | 类型               | 默认值           | 可选值 |
|-------------------|--------------------------|-------------------|------------------|--------|
| src               | 静态图片源地址（必填）   | string            | -                | -      |
| width             | 组件宽度                 | number | string  | -                | -      |
| height            | 组件高度                 | number | string  | -                | -      |
| mode              | 图片填充模式             | ImageMode         | 'scaleToFill'    | 见 Image 组件 |
| radius            | 圆角大小                 | number | string  | 0                | -      |
| round             | 是否为圆形               | boolean           | false            | -      |
| delay             | 加载延迟时间（ms）       | number            | 0                | -      |
| min-height        | 最小高度                 | number | string  | '200rpx'         | -      |
| lazy-load         | 是否懒加载图片           | boolean           | true             | -      |
| placeholder-src   | 占位图片地址             | string            | ''               | -      |
| filter            | 图片滤镜模糊值           | number | string  | ''               | -      |
| enable-preview    | 是否启用图片预览（LivePhoto 默认禁用） | boolean | false | -      |
| preview-src       | 预览图片地址             | string            | ''               | -      |
| custom-style      | 自定义样式               | string            | ''               | -      |
| custom-class      | 自定义类名               | string            | ''               | -      |

> 更多 Image 组件属性请参考 [Image 组件文档](./img.md)

## Slots

| 插槽名 | 说明           | 参数                          |
|--------|----------------|-------------------------------|
| image  | 自定义图片内容 | `{ src: string, imageProps: object }` |
| loading| 自定义加载状态 | -                             |
| error  | 自定义错误状态 | -                             |

## Events

| 事件名          | 说明           | 回调参数           |
|----------------|----------------|-------------------|
| video-play     | 视频开始播放   | -                 |
| video-pause    | 视频暂停播放   | -                 |
| press-start    | 开始长按       | -                 |
| press-end      | 结束长按       | -                 |
| video-ended    | 视频播放结束   | -                 |
| video-loaded   | 视频加载完成   | -                 |
| video-progress | 视频加载进度   | progress: number  |
| load           | 图片加载成功   | event             |
| error          | 图片加载失败   | event             |
| click          | 图片点击事件   | event             |

## Methods

| 方法名      | 说明           | 参数 | 返回值  |
|------------|----------------|------|---------|
| stopVideo  | 停止视频播放   | -    | -       |
| toggleMute | 切换静音状态   | -    | -       |
| isPlaying  | 是否正在播放   | -    | boolean |
| isMuted    | 是否静音       | -    | boolean |

## 注意事项

1. 组件需要同时提供 `video-src` 和 `src` 属性
2. 视频建议使用较短的循环视频，以获得更好的 Live Photo 效果
3. 在小程序平台，视频播放可能受到平台限制
4. 建议为视频和图片提供相同的宽高比，以保证显示效果
5. 组件支持振动反馈，但在某些平台可能不可用

## 外部样式类

| 类名         | 说明       |
| ------------ | ---------- |
| custom-class | 根节点样式 |

## 示例

更多用法请参考 `src/subPages/livephoto/Index.vue` 示例页面。

---

---
url: haaaaaaaaaaaaa-uni.cn/component/skeleton.md
---
# Skeleton 骨架屏

用于内容加载时的占位，提升页面加载体验。

## 基本用法

最简单的骨架屏用法：

```vue
<template>
  <up-skeleton />
</template>
```

## 动画效果

通过 `animate` 属性控制骨架屏是否显示动画效果，通常与加载状态联动。

```vue
<template>
  <up-skeleton :animate="isShowLoading" />
</template>

<script setup>
import { ref } from 'vue'
const isShowLoading = ref(false)
</script>
```

## 头像骨架

通过 `type="avatar"` 显示头像骨架，可设置 `avatarSize` 和 `avatarShape`。

```vue
<template>
  <up-skeleton type="avatar" :avatarSize="80" avatarShape="circle" />
</template>
```

## 标题行数

通过 `rows` 属性设置骨架屏的行数。

```vue
<template>
  <up-skeleton :rows="1" />
</template>
```

## 标题宽度

通过 `titleWidth` 属性设置标题宽度。

```vue
<template>
  <up-skeleton titleWidth="50%" />
</template>
```

## Attributes

| 参数         | 说明         | 类型              | 默认值    |
| ------------ | ------------ | ----------------- | --------- |
| type         | 骨架屏类型   | string            | 'title'   |
| loading      | 是否显示骨架 | boolean           | true      |
| animate      | 是否显示动画 | boolean           | true      |
| avatarShape  | 头像形状     | string            | 'circle'  |
| avatarSize   | 头像大小     | number/string     | 60        |
| titleHeight  | 段落高度     | number/string     | 36        |
| titleWidth   | 段落宽度     | number/string     | '100%'    |
| rows         | 行数         | number            | 3         |

## Events

| 事件名称 | 说明         | 参数 |
| -------- | ------------ | ---- |
| -        | 暂无事件     | -    |

## Slots

| 名称    | 说明         |
| ------- | ------------ |
| default | 自定义骨架屏内容 |

## 外部样式类

| 类名         | 说明       |
| ------------ | ---------- |
| custom-class | 根节点样式 |

## 示例

更多用法请参考 `src/subPages/skeleton/Index.vue` 示例页面。

---

---
url: haaaaaaaaaaaaa-uni.cn/component/swiper.md
---
# Swiper 轮播图

轮播图组件，支持图片和视频播放，内置多种指示器样式。

## 基本用法

基本的图片轮播功能。

```html
<up-swiper :list="swiperList" :height="200" />
```

## 指示器配置

### 指示器类型

支持四种指示器类型：圆点(dots)、圆点条(dots-bar)、分式(fraction)、线条(line)。

```html
<!-- 圆点指示器 -->
<up-swiper :list="swiperList" :height="200" :indicator="{ type: 'dots' }" />

<!-- 圆点条指示器 -->
<up-swiper :list="swiperList" :height="200" :indicator="{ type: 'dots-bar' }" />

<!-- 分式指示器 -->
<up-swiper :list="swiperList" :height="200" :indicator="{ type: 'fraction' }" />

<!-- 线条指示器 -->
<up-swiper :list="swiperList" :height="200" :indicator="{ type: 'line' }" />
```

### 指示器位置

支持8个位置：左侧、左上、上方、右上、左下、下方、右下、右侧。

```html
<up-swiper 
  :list="swiperList" 
  :height="200" 
  :indicator="{ type: 'dots', indicatorPosition: 'top-right' }" 
/>
```

### 控制按钮

显示左右控制按钮。

```html
<up-swiper 
  :list="swiperList" 
  :height="200" 
  :indicator="{ type: 'dots', showControls: true }" 
/>
```

## 垂直方向

支持垂直方向的轮播。

```html
<up-swiper 
  :list="swiperList" 
  :height="300" 
  direction="vertical" 
  :indicator="{ type: 'dots', direction: 'vertical', indicatorPosition: 'right' }" 
/>
```

## 自定义内容

通过插槽自定义轮播内容。

```html
<up-swiper :list="customList" :height="160" :indicator="true" :autoplay="false">
  <template #default="{ item, index }">
    <view class="custom-item">
      <view class="custom-content" :style="{ background: item.color }">
        <text class="custom-title">{{ item.title }}</text>
        <text class="custom-desc">{{ item.description }}</text>
        <view class="custom-index">{{ index + 1 }}</view>
      </view>
    </view>
  </template>
</up-swiper>
```

## 最小显示数量

当轮播项数量少于设定值时不显示指示器。

```html
<up-swiper 
  :list="singleItemList" 
  :height="200" 
  :indicator="{ type: 'dots', minShowNum: 2 }" 
/>
```

## Attributes

### 基础属性

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| list | 轮播数据列表，可以是字符串数组或对象数组 | `Array<string \| SwiperList>` | `[]` |
| current | 当前轮播在哪一项（下标） | `number` | `0` |
| height | 轮播图高度 | `string \| number` | `192` |
| direction | 轮播滑动方向 | `'horizontal' \| 'vertical'` | `'horizontal'` |
| autoplay | 是否自动播放 | `boolean` | `true` |
| interval | 轮播间隔时间，单位 ms | `number` | `5000` |
| duration | 滑动动画时长，单位 ms | `number` | `300` |
| loop | 是否循环播放 | `boolean` | `true` |
| display-multiple-items | 同时显示的滑块数量 | `number` | `1` |
| easing-function | 指定 swiper 切换缓动动画类型 | `'default' \| 'linear' \| 'easeInCubic' \| 'easeOutCubic' \| 'easeInOutCubic'` | `'default'` |
| previous-margin | 前边距，可用于露出前一项的一小部分 | `string \| number` | `'0'` |
| next-margin | 后边距，可用于露出后一项的一小部分 | `string \| number` | `'0'` |
| snap-to-edge | 当 swiper-item 的个数大于等于 2，关闭时会将当前 item 居中 | `boolean` | `false` |

### 指示器属性

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| indicator | 指示器配置，可以是布尔值或配置对象 | `boolean \| IndicatorConfig` | `true` |
| indicator-position | 指示器位置（快捷方式，也可通过 indicator 对象配置） | `IndicatorPositionType` | `'bottom'` |

### 图片/内容属性

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| image-mode | 图片裁剪、缩放的模式 | `ImageMode` | `'aspectFill'` |
| value-key | 选项对象中，value 对应的 key | `string` | `'value'` |
| text-key | 选项对象中，标题 text 对应的 key | `string` | `'text'` |

### 视频播放属性

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| video-loop | 视频是否循环播放 | `boolean` | `true` |
| muted | 是否静音播放 | `boolean` | `true` |
| autoplay-video | 视频是否自动播放 | `boolean` | `true` |
| stop-previous-video | 切换轮播项时是否停止上一个视频的播放 | `boolean` | `true` |
| stop-autoplay-when-video-play | 视频播放时是否停止自动轮播 | `boolean` | `false` |

### 高度调整属性（支付宝小程序）

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| adjust-height | 自动以指定滑块的高度为整个容器的高度 | `'first' \| 'current' \| 'highest' \| 'none'` | `'highest'` |
| adjust-vertical-height | vertical 为 true 时强制使 adjust-height 生效 | `boolean` | `false` |

### 自定义样式类

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| custom-indicator-class | 自定义指示器类名 | `string` | `''` |
| custom-image-class | 自定义图片类名 | `string` | `''` |
| custom-prev-image-class | 自定义上一个图片类名 | `string` | `''` |
| custom-next-image-class | 自定义下一个图片类名 | `string` | `''` |
| custom-item-class | 自定义 swiper 子项类名 | `string` | `''` |
| custom-prev-class | 自定义上一个子项类名 | `string` | `''` |
| custom-next-class | 自定义下一个子项类名 | `string` | `''` |
| custom-text-class | 自定义文字标题类名 | `string` | `''` |
| custom-text-style | 自定义文字标题样式 | `string` | `''` |

### IndicatorConfig

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| type | 指示器类型 | `'dots' \| 'dots-bar' \| 'fraction' \| 'line'` | `'dots'` |
| indicatorPosition | 指示器位置 | `'left' \| 'top-left' \| 'top' \| 'top-right' \| 'bottom-left' \| 'bottom' \| 'bottom-right' \| 'right'` | `'bottom'` |
| direction | 指示器方向 | `'horizontal' \| 'vertical'` | `'horizontal'` |
| minShowNum | 最小显示数量 | `number` | `2` |
| showControls | 是否显示控制按钮 | `boolean` | `false` |

### SwiperList

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| \[valueKey] | 图片/视频地址 | `string` | - |
| type | 媒体类型 | `'image' \| 'video'` | - |
| poster | 视频封面 | `string` | - |
| \[textKey] | 文本内容 | `string` | - |

## Events

| 事件名 | 说明 | 回调参数 |
|--------|------|----------|
| click | 点击轮播项时触发 | `{ index: number, item: any }` |
| change | 轮播切换时触发 | `{ current: number, source: string }` |

## Slots

| 名称 | 说明 | 参数 |
|------|------|------|
| default | 自定义轮播内容 | `{ item: any, index: number }` |
| indicator | 自定义指示器 | `{ current: number, total: number }` |

## 外部样式类

| 类名         | 说明       |
| ------------ | ---------- |
| custom-class | 根节点样式 |

## 示例

更多用法请参考 `src/subPages/swiper/Index.vue` 示例页面。

## 指示器样式定制

### 线条指示器特点

* 支持进度式高亮：当前激活项及之前的所有项都会高亮
* 适合展示播放进度，如短视频应用
* 可设置为撑满容器底部

### 样式变量

可通过CSS变量自定义指示器样式：

```scss
:root {
  --swiper-nav-dot-size: 12rpx;
  --swiper-nav-dot-color: rgba(255, 255, 255, 0.5);
  --swiper-nav-dot-active-color: rgba(255, 255, 255, 0.9);
  --swiper-nav-btn-size: 60rpx;
  --swiper-nav-btn-bg-color: rgba(0, 0, 0, 0.3);
  --swiper-nav-btn-color: #ffffff;
}
```

---

---
url: haaaaaaaaaaaaa-uni.cn/component/swiper-nav.md
---
# Swiper-Nav 轮播指示器

轮播图指示器组件，通常配合 Swiper 组件使用，也可以独立使用。支持多种指示器类型和样式自定义。

## 基本用法

独立使用指示器，展示当前位置。

```html
<up-swiper-nav
  :current="currentIndex"
  :total="5"
  type="dots"
/>
```

```ts
import { ref } from 'vue'

const currentIndex = ref(0)
```

## 指示器类型

支持四种指示器类型：圆点(dots)、圆点条(dots-bar)、分式(fraction)、线条(line)。

### 圆点指示器

```html
<up-swiper-nav
  :current="0"
  :total="5"
  type="dots"
/>
```

### 圆点条指示器

```html
<up-swiper-nav
  :current="0"
  :total="5"
  type="dots-bar"
/>
```

### 分式指示器

显示 "1/5" 这样的分数形式。

```html
<up-swiper-nav
  :current="0"
  :total="5"
  type="fraction"
/>
```

### 线条指示器

适合短视频场景，当前项及之前的项都会高亮。

```html
<up-swiper-nav
  :current="0"
  :total="5"
  type="line"
/>
```

## 指示器位置

支持8个位置：左侧、左上、上方、右上、左下、下方、右下、右侧。

```html
<up-swiper-nav
  :current="0"
  :total="5"
  type="dots"
  indicator-position="top-right"
/>
```

可选值：

* `'left'` - 左侧
* `'top-left'` - 左上
* `'top'` - 上方
* `'top-right'` - 右上
* `'bottom-left'` - 左下
* `'bottom'` - 下方（默认）
* `'bottom-right'` - 右下
* `'right'` - 右侧

## 控制按钮

显示左右控制按钮。

```html
<up-swiper-nav
  :current="currentIndex"
  :total="5"
  type="dots"
  :show-controls="true"
  @prev="handlePrev"
  @next="handleNext"
/>
```

```ts
const handlePrev = () => {
  if (currentIndex.value > 0) {
    currentIndex.value--
  }
}

const handleNext = () => {
  if (currentIndex.value < 4) {
    currentIndex.value++
  }
}
```

## 垂直方向

支持垂直方向的指示器。

```html
<up-swiper-nav
  :current="0"
  :total="5"
  type="dots"
  direction="vertical"
  indicator-position="right"
/>
```

## 最小显示数量

当总数少于设定值时不显示指示器。

```html
<up-swiper-nav
  :current="0"
  :total="1"
  type="dots"
  :min-show-num="2"
/>
<!-- 因为 total(1) < minShowNum(2)，指示器不会显示 -->
```

## 配合 Swiper 使用

Swiper-Nav 通常作为 Swiper 组件的内部指示器，但也支持外部独立使用。

```html
<up-swiper
  :list="swiperList"
  :height="200"
  :indicator="{
    type: 'dots',
    indicatorPosition: 'bottom',
    showControls: true,
    minShowNum: 2
  }"
/>
```

## Attributes

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| current | 当前激活项的索引 | `number` | `0` |
| total | 总项数 | `number` | `0` |
| type | 指示器类型 | `'dots' \| 'dots-bar' \| 'fraction' \| 'line'` | `'dots'` |

> `line` 类型为 `0.0.70` 新增。
> | direction | 指示器方向 | `'horizontal' \| 'vertical'` | `'horizontal'` |
> | indicator-position | 指示器位置 | `'left' \| 'top-left' \| 'top' \| 'top-right' \| 'bottom-left' \| 'bottom' \| 'bottom-right' \| 'right'` | `'bottom'` |
> | min-show-num | 小于此数量时不显示指示器 | `number` | `2` |
> | show-controls | 是否显示控制按钮 | `boolean` | `false` |

## Events

| 事件名 | 说明 | 回调参数 |
|--------|------|----------|
| change | 点击控制按钮时触发 | `{ dir: 'prev' \| 'next', source: 'nav' }` |

## 外部样式类

| 类名 | 说明 |
| ------------ | ---------- |
| custom-class | 根节点样式 |

## 样式定制

### 线条指示器特点

* 支持进度式高亮：当前激活项及之前的所有项都会高亮
* 适合展示播放进度，如短视频应用
* 可设置为撑满容器底部

### 样式变量

可通过 CSS 变量自定义指示器样式：

```scss
:root {
  --swiper-nav-dot-size: 12rpx;
  --swiper-nav-dot-color: rgba(255, 255, 255, 0.5);
  --swiper-nav-dot-active-color: rgba(255, 255, 255, 0.9);
  --swiper-nav-btn-size: 60rpx;
  --swiper-nav-btn-bg-color: rgba(0, 0, 0, 0.3);
  --swiper-nav-btn-color: #ffffff;
}
```

## 示例

Swiper-Nav 组件通常在 Swiper 组件内部使用，更多用法请参考 `src/subPages/swiper/Index.vue` 示例页面。

---

---
url: haaaaaaaaaaaaa-uni.cn/component/waterfall.md
---
# Waterfall 瀑布流

瀑布流布局组件，适用于图片展示、商品列表等场景。组件会自动根据内容高度将数据分配到不同列中，实现瀑布流效果。

## 基础用法

不使用插槽时，组件会根据 `imageField` 属性自动渲染图片。

```vue
<template>
  <up-waterfall
    :list="waterfallList"
    :column="2"
    @item-click="handleItemClick"
    @load-complete="handleLoadComplete"
  />
</template>

<script setup>
import { ref } from 'vue'
const waterfallList = ref([
  {
    id: 1,
    imgUrl: 'https://picsum.photos/300/400?random=1',
    title: '瀑布流项目 1'
  },
  {
    id: 2,
    imgUrl: 'https://picsum.photos/300/600?random=2',
    title: '瀑布流项目 2'
  }
])

function handleItemClick(item, index) {
  console.log('点击了项目：', item, index)
}

function handleLoadComplete() {
  console.log('瀑布流加载完成')
}
</script>
```

## 自定义列数

```vue
<template>
  <up-waterfall
    :list="waterfallList"
    :column="3"
    :column-space="1"
    :sort-by-img-info="false"
  />
</template>
```

## 自定义渲染

完全自定义每个项目的渲染内容，包括图片和内容。

```vue
<template>
  <up-waterfall
    :list="customImageList"
    :column="2"
  >
    <template #default="{ item, onLoad, onError }">
      <image 
        :src="item.imgUrl" 
        mode="aspectFill" 
        class="custom-image" 
        @load="onLoad" 
        @error="onError" 
      />
      <view class="item-content">
        <text class="item-title">{{ item.title }}</text>
        <text class="item-price">¥{{ item.price }}</text>
      </view>
    </template>
  </up-waterfall>
</template>

<style>
.custom-image {
  width: 100%;
  height: 200rpx;
}
</style>
```

## 自定义图片源获取方法

通过 `getImageSrc` 属性可以自定义获取图片源的方法，这在需要对图片 URL 进行特殊处理时很有用。

```vue
<template>
  <up-waterfall
    :list="waterfallList"
    :column="2"
    :get-image-src="getCustomImageSrc"
  >
  </up-waterfall>
</template>

<script setup>
const waterfallList = ref([
  {
    id: 1,
    imgUrl: 'https://picsum.photos/300/400?random=1',
    title: '瀑布流项目 1'
  },
  {
    id: 2,
    imgUrl: 'https://picsum.photos/300/600?random=2',
    title: '瀑布流项目 2'
  }
])

// 自定义图片源获取方法 - 简单示例
const getCustomImageSrc = (data) => {
  return data.imgUrl || ''
}

// 自定义图片源获取方法 - 复杂示例
const getCustomImageSrc = (item) => {
  // 可以根据不同的字段获取图片
  if (item.images && item.images.length > 0) {
    return `https://cdn.example.com/${item.images[0]}`
  }
  if (item.thumbnail) {
    return `https://cdn.example.com/${item.thumbnail}`
  }
  if (item.cover) {
    return item.cover
  }
  // 添加默认图片或返回空字符串
  return item.imgUrl || 'https://via.placeholder.com/300x400'
}
</script>
```

### 使用场景

1. **统一图片域名**：为所有图片添加 CDN 前缀
2. **多字段支持**：根据不同的数据结构获取图片
3. **默认图片**：当没有图片时显示占位图
4. **图片处理**：添加图片尺寸、质量等参数

## 注意事项

* 当传入 `getImageSrc` 方法时，会优先使用该方法获取图片源，忽略 `imageField` 属性
* 开启 `sortByImgInfo` 后会根据图片高度逐一加载项目，适用于图片高度差异较大的场景
* 不使用插槽时，组件只会渲染图片，如需显示其他内容请使用默认插槽

## 是否开启sortByImgInfo

开启 `sortByImgInfo` 后会根据图片的高度和宽度信息对列表进行排序，确保瀑布流布局的美观，与此同时页面也会产生逐条加载的效果。

```vue
<template>
  <up-waterfall
    :list="waterfallList"
    :column="2"
    :sort-by-img-info="true"
  >
  </up-waterfall>
</template>

```

## Attributes

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| list | 瀑布流数据列表 | `WaterfallItem[]` | `[]` |
| column | 列数 | `number` | `2` |
| columnSpace | 列间距(百分比) | `number` | `2` |
| imageField | 图片字段名 | `string` | `'imgUrl'` |
| getImageSrc | 获取图片源的方法 | `(item: WaterfallItem) => string` | `undefined` |
| sortByImgInfo | 是否根据图片信息排序 | `boolean` | `false` |

## Events

| 事件名 | 说明 | 回调参数 |
|--------|------|----------|
| load-complete | 加载完成时触发 | - |
| item-click | 点击项目时触发 | `(item: WaterfallItem, index: number)` |
| image-load | 图片加载成功时触发 | `(item: WaterfallItem)` |
| image-error | 图片加载失败时触发 | `(item: WaterfallItem)` |

## Slots

| 插槽名 | 说明 | 参数 |
|--------|------|------|
| default | 自定义项目渲染 | `{ item, index, onLoad, onError }` |

## 外部样式类

| 类名         | 说明       |
| ------------ | ---------- |
| custom-class | 根节点样式 |

## 示例

更多用法请参考 `src/subPages/waterfall/Index.vue` 示例页面。

## 类型定义

```typescript
interface WaterfallItem {
  [key: string]: any
  index?: number
  id?: string | number
}
```

## 方法

通过 ref 可以访问到组件实例并调用实例方法。

| 方法名 | 说明 | 参数 |
|--------|------|------|
| resetWaterfall | 重置瀑布流 | `(list: WaterfallItem[])` |
| appendNewData | 追加新数据 | `(newItems: WaterfallItem[])` |

---

---
url: haaaaaaaaaaaaa-uni.cn/guide/introduction.md
---
# 介绍

`uni-ui-plus` 是一个专为 uni-app 生态打造的现代化组件库，基于 `Vue 3` + `TypeScript` 构建，提供丰富的高质量组件。

## 快速上手

请查看[快速上手](/guide/quick-use.html)文档。

## ✨ 特性

* 🎯 多平台覆盖，支持 微信小程序、支付宝小程序、钉钉小程序、H5、APP 等.
* 💪 使用 Typescript 构建，提供良好的组件类型系统.

## 链接

* [更新日志](/guide/changelog)

---

---
url: haaaaaaaaaaaaa-uni.cn/guide/quick-use.md
---
# 快速上手

## 安装

`uni-ui-plus` 提供了 `uni_modules` 和 `npm` 两种安装方式。

### npm 安装

::: code-group

```bash [pnpm]
pnpm add uni-ui-plus
```

```bash [yarn]
yarn add uni-ui-plus
```

```bash [npm]
npm i uni-ui-plus
```

:::

### uni\_modules 安装

在 `src` 目录下创建 `uni_modules` 文件夹并将 `uni-ui-plus` 解压到其中：

```bash
- uni_modules
- - - uni-ui-plus
```

## 配置

### 导入组件

::: tip 提示
使用 `uni_modules` 安装时组件天然支持 `easycom` 规范，无需额外配置。使用 `npm 安装` 需按照以下步骤配置。
:::

#### 基于 vite 配置自动引入组件（方案 1）

```ts
// src/resolvers/up-resolver.ts
import type { ComponentResolver } from '@uni-helper/vite-plugin-uni-components'
import { kebabCase } from '@uni-helper/vite-plugin-uni-components'

export function UpResolver(): ComponentResolver {
  return {
    type: 'component',
    resolve: (name: string) => {
      if (name.match(/^Up[A-Z]/)) {
        const compName = kebabCase(name)
        return {
          name,
          from: `uni-ui-plus/components/${compName}/${compName}.vue`,
        }
      }
    },
  }
}
```

```ts
// vite.config.ts
import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";
import Components from '@uni-helper/vite-plugin-uni-components'
import { UpResolver } from '@/resolvers/up-resolver'

export default defineConfig({
  plugins: [
    Components({ resolvers: [UpResolver()] }),
    uni()
  ],
});
```

如果使用 `pnpm`，请在根目录下的 `.npmrc` 文件中添加：

```text
public-hoist-pattern[]=@vue*
```

#### 配置 easycom 自动引入组件（方案 2）

```json
// pages.json
{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^up-(.*)": "uni-ui-plus/components/up-$1/up-$1.vue"
    }
  }
}
```

## 引入主题样式

`uni-ui-plus` 使用 CSS 自定义属性实现主题系统，需要在 `App.vue` 中全局引入主题样式：

```vue
<!-- App.vue -->
<style lang="scss">
@use 'uni-ui-plus/styles/theme/index.scss' as *;
</style>
```

如果使用 `uni_modules` 安装方式：

```vue
<!-- App.vue -->
<style lang="scss">
@use '@/uni_modules/uni-ui-plus/styles/theme/index.scss' as *;
</style>
```

::: warning 注意
不引入主题样式会导致组件的间距、颜色、圆角等 CSS 变量无法生效，组件样式会异常。
:::

## Volar 支持

在 `tsconfig.json` 中配置全局组件类型：

```json
{
  "compilerOptions": {
    "types": ["uni-ui-plus/global"]
  }
}
```

## 使用

配置完成后，可以直接在 SFC 中使用组件：

```html
<template>
  <up-image src="https://example.com/a.jpg" width="100" height="100" />
  <up-empty description="暂无数据" />
</template>
```

---

---
url: haaaaaaaaaaaaa-uni.cn/guide/dark-mode.md
---
# 深色模式

`uni-ui-plus` 内置了深色模式支持，通过 `up-config-provider` 设置主题即可使用。

## 开启深色模式

将 `theme` 设置为 `dark`，即可让当前 `up-config-provider` 包裹范围内的组件切换为深色风格。

::: warning 注意
使用深色模式前，需要在入口文件（如 `App.vue`）中引入主题变量文件：

* npm 安装：`@use 'uni-ui-plus/styles/theme/index.scss' as *;`
* uni\_modules 安装：`@use '@/uni_modules/uni-ui-plus/styles/theme/index.scss' as *;`
  :::

::: code-group

```html [页面]
<up-config-provider theme="dark">
  <up-empty description="暂无数据" />
</up-config-provider>
```

```scss [App.vue - npm]
@use 'uni-ui-plus/styles/theme/index.scss' as *;
```

```scss [App.vue - uni_modules]
@use '@/uni_modules/uni-ui-plus/styles/theme/index.scss' as *;
```

:::

## 自定义主题变量

通过 `theme-vars` 可以覆盖当前组件范围内的主题变量：

```html
<up-config-provider
  theme="dark"
  :theme-vars="{ emptyDescriptionColor: '#999999' }"
>
  <up-empty description="暂无数据" />
</up-config-provider>
```

更多配置请参见 [ConfigProvider](/component/config-provider) 组件文档。