# SinleUI

> SinleUI 是一个基于 uni-app x 的移动端 UI 框架，提供 100+ 组件与配套 API。

<!-- 本文件由 tools/gen-llms-txt.mjs 从 docs/.vitepress/config.mts 与源文档自动生成，请勿手动编辑。 -->
<!-- 在线索引：https://sinleui.pages.dev/llms.txt ｜ 文档站：https://sinleui.pages.dev -->

# AI 开发

SinleUI 为 Vibe Coding Harness（Claude Code、Codex、ZCode、DeepSeek Harness、Cursor、WorkBuddy、Trae等）提供了可安装的 Skill，以提供插件附带的组件与 API 能力清单。AI 可以据此查找框架已有能力，按框架规范生成页面和功能，减少重复实现和属性误用。

## 为什么需要这些资料

SinleUI 基于 uni-app x 框架开发，使用本插件时与普通 Vue 项目有不少差异，AI 按通用 Vue 项目的写法生成代码时，容易忽略以下几点：

- 组件名、props 和事件由框架定义，需要查阅后再使用；
- 页面根节点必须是 `sn-page`，否则主题变量会失效；
- 尺寸和颜色使用 `$` 动态值与 `--sn-*` 变量，不能都按固定 `px` 与十六进制色值处理；
- 原生端需要自定义基座，生成方案时也要考虑这一前提。

在开始任务前提供能力清单和这些约定，可以减少因框架用法不符而产生的返工。

## 本栏目内容

- [Skill](/ai/skill)：下载并安装 `sinleui-app-dev`，供 AI 查阅框架规范。
- [适配指南](/ai/setup)：安装后如何描述需求、检查结果。
- [实践经验](/ai/practices)：使用 AI 开发页面时的任务安排与检查建议。

## 能力清单

能力清单有两个入口，按是否联网选择：

- **联网时**：文档站提供 [llms.txt](https://sinleui.pages.dev/llms.txt) 分组索引与逐页 `.md`（如 `https://sinleui.pages.dev/components/sn-button.md`），AI 可直接抓取，无需解析 HTML；也可用 [llms-full.txt](https://sinleui.pages.dev/llms-full.txt) 一次读完全部页面。
- **离线时**：插件内的 `uni_modules/sinle-ui/ai-reference.md` 是单文件索引，覆盖同样的组件与 API，每一项都带文档站链接。

`ai-reference.md` 是**自动生成的派生产物**（源是 Skill 的 `references/` 索引），随插件一起分发：

| 部分 | 内容 |
| :--- | :--- |
| 开工前必读 | 页面根节点、easycom、`$` 动态值等硬约束 |
| 框架核心能力 | 全部 hooks 的用途与导入方式 |
| 组件清单 | 全部组件的分类、用途简述与文档链接 |
| API | `$snui`、`snu`、核心库、导出常量与类型的概述 |
| 组合速记 | 列表项、弹层、页面骨架、主题色、尺寸的常见写法 |

文件位置：`uni_modules/sinle-ui/ai-reference.md`。

::: warning 保持同步
能力清单随框架代码维护。新增、修改或删除组件与 API 时，会同步更新清单。**请勿直接编辑 `ai-reference.md`**——它由 Skill 的索引生成，改动应落到 Skill，再重新生成并校验。
使用旧版插件时，请结合当前代码和文档站核对用法。
:::

# Skill

sinleui-app-dev 是供 AI 编码助手使用的 SinleUI Skill。安装后，AI 可以查阅框架规范，减少每次对话中重复说明的内容。

## 下载

[下载 sinleui-app-dev.zip](/skills/sinleui-app-dev.zip)

压缩包内是一个标准 Skill 目录：

```
sinleui-app-dev/
├── SKILL.md                        技能入口：工作流、五条硬约束、按任务查
└── references/
    ├── component-index.md          全部组件：能干什么 + 文档链接
    ├── api-index.md                全部 API 与 hooks：能干什么 + 文档链接
    ├── page-structure.md           页面结构规则 + 相关文档链接
    ├── style-rules.md              尺寸与颜色规则 + 相关文档链接
    ├── recipes.md                  常见组合速记（列表项 / 骨架 / 弹层 / 尺寸颜色）
    └── checklist.md                交付前自查清单
```

## 内容与文档的分工

Skill 主要提供以下三类信息，组件和 API 的具体用法仍需查阅文档：

1. 框架提供的能力，以及各自的用途和文档链接；
2. 必须遵守的要求（`sn-page` 根节点、`$` 动态值、`--sn-*` 变量、easycom、不改 `uni_modules/`）；
3. 交付前需要检查的项目。

框架有一百多个组件，如果把 props 表全部放进 Skill，文件会很长，维护时也容易遗漏。因此，具体用法统一链接到文档站，Skill 用来帮助 AI 找到相关页面。

::: tip 使用流程
AI 接到任务后，先通过索引选择组件，再阅读对应文档页的属性表，最后按规则写代码、对照清单自查。这样能减少凭记忆编写代码的情况，也能控制上下文的长度。
:::

## 安装

不同工具的技能目录有所区别，下表列出了一些常见位置：

| 工具 | 常见位置 |
| :--- | :--- |
| Claude Code | `~/.claude/skills/`（全局）或项目内 `.claude/skills/` |
| CodeBuddy / Trae / Qoder | 各工具技能目录（如 `.codebuddy/skills/`、`.trae/skills/`） |
| 支持 AGENTS.md 类约定但不支持 Skill 的工具 | 见下方「不支持 Skill 时」 |

解压后，将整个 `sinleui-app-dev/` 目录放入技能目录，并保留内部目录结构。`SKILL.md` 通过相对路径引用 `references/` 下的文件。

::: tip 确认安装
不清楚技能目录时，可以在工具中询问，或查阅该工具的文档。安装后，新建对话让 AI 写一个 SinleUI 页面，检查它是否读取了组件索引，并使用 `sn-page` 作为根节点。
:::

## 不支持 Skill 时

不支持 Skill 的工具也可以使用压缩包中的 Markdown 文件：

- 支持在对话开头注入上下文时，将 `SKILL.md` 贴入上下文；
- 支持自定义指令 / 自定义 prompt 的工具，可以将 `SKILL.md` 作为指令内容；
- 不支持上述方式时，在任务开头要求 AI「先读 `<解压路径>/sinleui-app-dev/SKILL.md`，按里面的规范写」。

`SKILL.md` 内容较短，也便于通过这种方式加入对话上下文。

## 使用范围

Skill 会引导 AI 优先选择框架已有组件、按 `sn-page` 组织页面、使用 `$` 与 CSS 变量处理尺寸和颜色、查阅文档，并在交付前对照清单检查。查不到所需能力时，应明确说明「框架未提供」。

不得编造组件与属性、修改 `uni_modules/` 下的框架代码，或将未验证的结果写成已验证。编译与真机验证是否执行，仍以当前环境和项目规则为准。

## 让 AI 直接抓取文档

除 Skill 之外，文档站还按 [llms.txt](https://llmstxt.org) 约定提供了可直接抓取的索引，便于 AI 在不下载 Skill 时也能拿到完整页面内容：

| 地址 | 内容 |
| :--- | :--- |
| [https://sinleui.pages.dev/llms.txt](https://sinleui.pages.dev/llms.txt) | 分组索引：每个组件 / API 页面的标题、一句话说明与 Markdown 链接 |
| [https://sinleui.pages.dev/llms-full.txt](https://sinleui.pages.dev/llms-full.txt) | 全部页面的 Markdown 合订本，可一次性读完 |
| `https://sinleui.pages.dev/components/sn-button.md` | 任取一页的 Markdown 版本（组件、API、核心库同理） |

也就是说，AI 既能用 Skill 查「框架有什么」，也能直接抓 `.md` 拿「这个组件怎么用」，无需解析 HTML。在提示词里可以直接写：

```text
先读 https://sinleui.pages.dev/llms.txt，再按需读取对应组件的 .md 页面。
```

::: info 生成方式
`llms.txt` / `llms-full.txt` / 逐页 `.md` 均为**自动生成的派生产物**，随文档站一起发布。请勿直接编辑这些文件，改动应落到对应的源文档上，再重新运行生成脚本。
:::

## 离线索引

插件中的 `uni_modules/sinle-ui/ai-reference.md` 也按索引形式列出了组件、hooks 与 API 的用途，每一项都带文档站链接。能联网时，Skill 会引导 AI 查阅文档站与 `llms.txt`；联网不便时，可以读取这份离线索引。

它是**自动生成的派生产物**：源是 Skill 目录下的 `references/`，由 `tools/gen-ai-reference.mjs` 生成，请勿手动编辑。需要更新时，先改 Skill 索引，再重新生成，并用 `--check` 校验两者是否一致。

## 更新

Skill 随框架一起维护，下载包与文档站同步发布。需要更新时，重新下载并覆盖原目录即可。

::: info 维护说明
下载包由 `tools/pack-skill.ps1` 从 `docs/public/skills/sinleui-app-dev/` 生成，`-Check` 可校验两者是否一致。
:::

# 适配指南

安装 SinleUI 的 Skill 后，就可以向 AI 描述需要开发的页面或功能。

## 一、安装 Skill

下载并解压 [sinleui-app-dev](/ai/skill)，放入所用工具的技能目录。安装后，AI 可以查阅：

- 组件索引：组件的用途和对应文档；
- API 索引：`$snui`、`snu`、hooks、store、颜色与日期库的入口及文档链接；
- 页面结构与样式规则（`sn-page` 根节点、`$` 动态值、`--sn-*` 变量等）；
- 交付前自查清单。

Skill 主要提供索引，具体用法需查阅对应文档，便于随框架更新，也能减少上下文占用。安装位置及不支持 Skill 时的用法见 [Skill 页](/ai/skill)。

## 二、按场景描述需求

描述任务时，先说明页面或功能需求。AI 可以通过 Skill 查阅框架规则和相关文档。

| 你要做的 | 可以这样描述 |
| :--- | :--- |
| 一个列表页 | 「做一个消息列表页，每条显示标题、时间和摘要，点击进详情」 |
| 一个表单页 | 「做一个新建地址的表单，姓名、手机号、地区三级选择，带校验」 |
| 一段长列表 | 「商品列表，支持下拉刷新和加载更多，卡片式」 |
| 一个设置页 | 「设置页，分通用/账号两组，含暗黑模式开关和退出登录」 |
| 一次操作确认 | 「删除前弹确认框，确认后调接口并提示结果」 |
| 一个页面底部导航 | 「首页加底部三个 Tab：首页、分类、我的」 |
| 一个详情页 | 「商品详情页，顶部图片，内容从导航栏背后滚过」 |

::: tip 补充数据与状态
说明数据来源、加载中和空列表时的表现，AI 更容易写出符合项目需求的代码。例如：「数据从 `api.getMessages()` 来，加载中用骨架屏，空列表显示提示」。
:::

## 三、验收时看什么

AI 交付时应对照 Skill 的清单说明检查结果。你可以再复核以下几项：

- [ ] 页面根节点是 `sn-page`，弹层都在它内部；
- [ ] 尺寸使用 `$` 动态值或 `calc(var(--ff) * 14px)`，没有大量写死的 `px`；
- [ ] 颜色使用 `$primary` / `var(--sn-*)`，没有写死的十六进制色值；
- [ ] 提示类调用使用 `snu.showToast`，没有混入 `uni.showToast`；
- [ ] 列表页有加载中 / 空态 / 正常三种状态。

## 四、补充说明

**框架安装**：框架本身的安装只需完成一次，步骤见[安装](/get-started/setup)与[注意事项](/get-started/notes)。

**能力清单**：插件内的 `uni_modules/sinle-ui/ai-reference.md` 是供 AI 查阅的离线索引，简述了组件、hooks 与 API 的用途。Skill 会引导 AI 查阅文档站；联网不便时，可以先查这份索引。

**项目约定**：目录结构、接口封装、状态管理、命名习惯等额外规范，可以写进项目的 `AGENTS.md` 或规则文件。Skill 负责框架用法，业务约定仍以项目规则为准。

# 实践经验

用 AI 编写 SinleUI 页面时，除了说明需求，还需要提供框架资料和项目约定。下面整理了一些任务安排和检查方法，供开发时参考。

## 一、先提供能力清单

AI 不了解框架组件时，可能会用原生 `view` 重复实现已有组件，也可能误用不存在的 `sn-xxx`，导致返工。

开始任务前，可以先安装 Skill，让 AI 读取能力清单；也可以让它直接读取 `uni_modules/sinle-ui/ai-reference.md`。有了清单，AI 能根据需求选择组件，不必在指令中逐个点名。比如需要徽标时，可以选用 `sn-badge`；需要骨架屏时，可以选用 `sn-skeleton`。

::: tip 先查再写
可以按「先查索引 → 理解需求 → 阅读文档 → 编写代码」的顺序推进。先确认组件选择，再开始写代码，可以减少在已有结构上反复打补丁的情况。
:::

::: info 索引与手册的分工
索引用于查找框架是否提供某项能力、对应文档在哪里，手册说明具体用法。先看索引，再按需阅读文档页，可以减少上下文占用，也方便查阅文档站上的最新用法。
:::

## 二、把约定写成可检查的规则

约定要具体到 AI 可以在交付前逐项检查。例如，「注意代码质量」很难直接核对，而「页面根节点必须是 `sn-page`」可以逐文件检查。

下面几种写法比较容易检查：

| 写法 | 示例 | 检查依据 |
| :--- | :--- | :--- |
| 明确规则 | 页面根节点必须是 `sn-page` | 可逐文件确认根节点 |
| 给出反例 | 不要用 `uni.showToast`，用 `snu.showToast` | 明确要避免的调用及替代方法 |
| 给出写法 | 尺寸写 `$14`，不要写裸数字 | 可直接对照代码核对 |
| 限定修改范围 | 不要改 `uni_modules/` | 明确依赖目录不在修改范围内 |

常用约束可以控制在一屏左右，便于一次读完。长篇规范中的细节按任务需要另行查阅，避免重点被大量说明淹没。

## 三、允许 AI 说明不确定之处

AI 不确定某项能力时，有时会补出一个看似合理的用法。可以在任务中写明：

> 不确定某个能力是否存在时，先查能力清单与文档站；查不到就说明「框架未提供该能力」，不要编造，也不要在未说明的情况下换成不可用的实现。

允许 AI 明确说明能力缺失，有助于及早发现问题，避免继续沿着错误方案开发。

## 四、留意尺寸和颜色的写法

样式代码有时语法正确，却不符合框架的写法。常见问题包括：

- 将 `$14` 写成 `14`，尺寸就不会随乘数缩放，用户调整字号时也不会跟着变化；
- 将颜色写死为 `#4d82ff`，切换暗色主题后仍保持原色；
- 在脚本中拼接样式，却没有放进 `computed`，乘数变化时界面不会刷新；
- 用 `calc(var(--af) * 200ms)`，`--af` 是纯数值乘数，放进 `calc()` 算时间不成立。

这类问题不容易仅靠阅读代码发现。把对应规则写进约束文件，并在交付前逐项检查，有助于减少遗漏。

## 五、按步骤完成任务

同时要求 AI 搭页面、接接口、加动画和适配暗色主题时，容易出现细节遗漏。可以把任务拆成几轮：

1. **结构**：先确定 `sn-page`、布局和组件选择，暂不处理样式细节；
2. **数据**：接入真实数据，补齐空态 / 加载态 / 错误态；
3. **样式**：使用 `$` 与 `calc(var(--xx) * Npx)`，统一尺寸与颜色的写法；
4. **交互**：补充加载、禁用、点击态和动效。

每轮完成后分别检查，发现问题时也更容易定位。

## 六、交付时逐项检查

生成完成后，让 AI 对照清单说明检查结果，便于确认哪些内容已完成、哪些还需要验证。可以使用以下清单：

- [ ] 根节点是 `sn-page`，弹层都在内部；
- [ ] 没有大量写死的 `px` 与十六进制颜色；
- [ ] 提示使用 `snu.showToast`，没有 `uni.showToast`；
- [ ] 组件的 `ref` 调用发生在渲染之后；
- [ ] 列表页有加载中 / 空态 / 正常三种状态；
- [ ] 明确列出需要人工确认的交互点。

## 七、描述问题时给出操作和现象

AI 可以根据代码和编译产物分析问题，但不一定能看到实际运行画面。抽屉滑动是否顺畅、交互是否符合预期，仍需要你在运行时确认。

反馈问题时，说明页面位置、操作步骤和实际表现，再附上相关代码，会比只说「不生效」更容易定位。仅说「样式错了」，往往不足以判断原因。

# 介绍

<image src="/logo.png" style="width:150px;height:150px;margin:0 auto;" />

<h1 style="font-family:alipuhuiheavy;text-align:center;margin-top:calc(0.5rem - var(--navbar-height) - 35px);">SinleUI</h1>

<p style="text-align:center;color:#6d6d6d;margin-top:-5px;">一个简洁、轻巧的现代移动应用UI框架</p>

### 



### :desktop_computer:   作者有话说

这个UI框架是作者苦于 uni-app x 插件市场缺失适合自己的UI库，在开发项目的过程中写的。我自己项目比较多，而且都是一些小型项目，资金不算太充裕。对于小型个人项目来说，较完美的UI框架授权费用相对较高，自我感觉非常不划算，其他免费的UI框架大多有点不合项目的风格，于是自己写了一个。

由于作者时常在校，因此更新频率视情况待定。**若没有满足您的需求，可以自己二次开发**。

**本UI框架适合小型项目开发，大型商业项目慎用**。当然，如果您愿意为项目贡献，也欢迎提供代码、指出 Bug 或打赏，这也是我创作的动力。😊

---

### :pizza:  项目声明

本UI框架作者为：Aaron Lan 

采用MIT协议，允许二次开发和修改，以及对使用本UI框架的项目闭源处理。但必须在项目显著位置（包括但不限于项目发布页、项目声明文件、项目许可信息页面）进行使用声明。

---

### :fish_cake:  引用声明

本项目内置字体说明

- Remix Icon <Badge text="免费商用" type="tip" style="margin-left: 5px" />

---

### :book:  MIT许可证

> Copyright (C) <2023-> &lt;Singmy&gt;
>
> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
>
> The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
>
> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

# 安装

> [!warning]
> SinleUI 只支持通过 [DCloud 插件市场 ](https://ext.dcloud.net.cn/plugin?name=sinle-ui)下载安装

1. 进入插件下载页
2. 右上角选择 <span style="color:#35b571;">购买**源码授权版**（5.00 元）</span><span class="danger-text">（务必选择**源码**授权版；本项目仅收费 5 元，不要选择普通授权版）</span>
3. 付款
4. 导入对应项目即可

<div class="primaryButton"><a href="https://ext.dcloud.net.cn/plugin?name=sinle-ui">点我去插件市场下载😀</a></div>

# 快速上手

本节将介绍如何在项目中使用 SinleUI。

## 使用方法

1. 首先，请[安装SinleUI](../get-started/setup.md)。

2. 在项目根目录下 `App.uvue` 中导入 `CSS` 文件。

   ```vue
   <style lang="scss">
   	@import "@/uni_modules/sinle-ui/static/styles/fonts.scss";
   </style>
   ```
   
3. 组件符合 [easycom](https://uniapp.dcloud.net.cn/collocation/pages?id=easycom) 规范，无需 import，直接在项目中使用。

4. SinleUI API 则需要 import 相应对象后使用。

   ```typescript
   import { $snui } from '@/uni_modules/sinle-ui'
   ```

::: warning 注意
不可直接从插件内部任何 `ts` 文件导入对象或类型，大部分类型均从 `@/uni_modules/sinle-ui` 导入

组件专属类型同样从插件入口 `@/uni_modules/sinle-ui` 统一重导出，不再需要从组件目录导入。

**部分特殊类型**请参考 [类型](/api/types/index) 内容或按照其文档说明路径导入。

:::

5. 在 APP 端运行本框架必须**打包自定义基座**后运行，因为框架使用了第三方依赖。

# 注意事项

> [!important]
> 请仔细阅读此页内容，对于正确使用 SinleUI **非常重要**。


::: danger 必须放在 sn-page 下
- 页面内所有组件（含 sn-popup、sn-modal、sn-toast 等弹出层类组件）都必须放在 `sn-page` 下，务必让 `sn-page` 成为页面根节点，否则注入的 `--sn-*`、`--ani-time-*` CSS 变量无法作用到这些节点，颜色与动画时长会错乱
:::


1. 由于框架使用了第三方依赖，在 APP 端运行 SinleUI <span class="danger-text">**必须打包自定义基座**</span>后运行。

2. SinleUI 推荐**使用 `px` 作为基本长度单位**。SinleUI 部分组件涉及布局计算，现阶段对于其他单位如 `rpx` 、`%` 的支持并不太好（下期会改进）。因此，除非设置 css 或组件行内样式 `style`，否则不推荐在 SinleUI 组件中使用 `px` 外的长度单位。

3. SinleUI 推荐**使用 `ms` 作为基本时长单位**。SinleUI 部分组件涉及时长处理，默认以 `ms` 作为单位。因此，除非设置 css 或组件行内样式 `style`，否则不推荐在 SinleUI 组件中使用 `ms` 外的时长单位。

5. 获取组件 Ref 实例时，如果是选项式 API，使用 `this.$refs[xxxx]` 获取即可。<br />如果是组合式 API，必须设置一个**与组件 `ref` 属性同名**的、**组件实例类型**的响应式对象。例如：
   ```vue
   <template>
     <sn-modal ref="modalEle" title="标题" content="内容"></sn-modal>
   </template>
   <script setup>
     const modalEle = ref(null as SnModalComponentPublicInstance | null)
   </script>
   ```
   
6. 调用组件的方法需要通过 `ref` 获取组件实例，且**必须保证组件已渲染**。
   例如：
   ```vue
   <template>
     <sn-modal ref="modalEle" title="标题" content="内容"></sn-modal>
   </template>
   <script setup>
     const modalEle = ref(null as SnModalComponentPublicInstance | null)
   
     // onReady 可以保证 DOM 已渲染
     onReady(()=>{
       // 示例1 - 安全调用，组件未渲染也不会报错
       modalEle.value?.open?.()
   
       // 示例2 - 显性判空，仅当组件已渲染时调用
       if (modalEle.value != null) {
           modalEle.value!.close()
       }
     }) 
   </script>
   ```

# 框架设计

本页详细介绍 SinleUI 的整体架构、核心机制与设计理念，帮助您理解框架如何工作、为何这样设计。



## 概述

SinleUI 是一个面向 uni-app x 蒸汽模式（vapor）的轻量级移动端 UI 框架，以 `uni_modules` 形式分发，目标平台为 Android（Kotlin）、iOS（Swift）、HarmonyOS 与 Web（JavaScript）。

框架坚持以下设计原则：

- **简洁轻量**：核心无运行时依赖，按需打包
- **跨平台一致**：通过条件编译与平台目录（`utssdk/app-android`、`utssdk/app-ios` 等）隔离平台差异
- **主题化驱动**：风格（Style）与主题（Theme）双层体系，全局一处修改、处处生效
- **组合式 API**：向组件与开发者提供 `hooks` 复用框架能力
- **性能颜值平衡**：追求更优秀的 UI 设计，一切设计都在考虑性能的情况下尽可能优化 UI 设计。

---

## 目录结构

`uni_modules/sinle-ui/` 插件目录结构如下：

| 目录/文件 | 说明 |
| :--- | :--- |
| `components/` | 全部 `sn-*` 组件，每个组件一个独立目录（如 `sn-button/sn-button.uvue`） |
| `core/` | 框架核心模块 |
| `core/snui.ts` | `Snui` 单例类定义，`$snui` 全局实例 |
| `core/state.ts` | 全局响应式状态（主题、风格）、持久化与主题监听 |
| `core/types/index.ts` | 全部核心类型定义与导出（SnColorBase、SnStyle 等） |
| `core/theme/` | 内置风格文件（`default-style`、`ink-style`、`chinese-style` 等 6 套）与风格注册中心 |
| `core/utils/` | 工具库分组静态类（Random、Basic、Easing、ObjectUtils、System、Sort、Text、Ui、Perm、Verify） |
| `core/utils/index.ts` | `snu` 聚合门面 |
| `core/color/` | 颜色库（`ColorLib`、`TinyColor`） |
| `core/date/` | 日期库（`DateLib`、`Dayuts`、国际化） |
| `core/private/` | 内部钩子与机制（`use-theme`、`use-style`、`use-factors`、`use-hover`、`use-external-style`、`use-backtop`、`logger`、`dialog-store`） |
| `pages/popups/` | 全局弹窗页面（showModal、showActionsheet、showLoading） |
| `pages_init.json` | 注册插件内置弹窗页面 |
| `index.ts` | 插件入口，统一导出全部公开 API |



---

## 风格系统（Style）

一个应用可同时注册多套风格（皮肤），如现代、简约、古风、梦幻、科幻等。每套风格是一个 `SnStyle` 对象，包含：颜色集（亮/暗两套）、导航栏高度、亮/暗页面背景色，以及五个乘数与三个基础动画时长。

- **注册与切换**：`core/theme/index.ts` 在框架加载时执行 `initStyles()` 注册内置风格；`$snui.currentStyleId` 切换风格（`switchStyle` 会深拷贝目标风格再替换当前风格，避免互相污染）。

- **内置风格**：`default`（默认）、`ink`（水墨）、`chinese`（国风）、`new-year`（新年）、`morandi-green`（莫兰迪绿）、`orange`（活力橙）共 6 套。

- **持久化**：`switchStyle` 与各 setter 修改后调用 `persistCurrentStyle()`，将当前完整风格写入 storage（key：`sinleui_current_style`），风格 id 单独存储（key：`sinleui_current_style_id`）。应用重启自动恢复。

- **运行时微调**：开发者可直接修改 `$snui` 上的乘数与颜色等属性，改的是当前风格对象，随后自动持久化，覆盖预置值。

  #### SnStyle

  一套完整风格（皮肤）对象，即内置风格文件导出的结构。

  | 字段           | 类型                          | 描述                        |
  | :------------- | :---------------------------- | :-------------------------- |
  | id             | String                        | 风格唯一 id，如 `'default'` |
  | colorBases     | [SnColorBases](#sncolorbases) | 亮/暗两套颜色集             |
  | topbarHeight   | String                        | 导航栏高度（不含状态栏），默认 `48px` |
  | lightBgColor   | String                        | 亮色模式页面默认背景色      |
  | darkBgColor    | String                        | 暗色模式页面默认背景色      |
  | marginFactor   | Number                        | 外间距乘数                  |
  | paddingFactor  | Number                        | 内间距乘数                  |
  | radiusFactor   | Number                        | 圆角乘数                    |
  | fontsizeFactor | Number                        | 字号乘数                    |
  | aniTimeFactor  | Number                        | 动画时长乘数                |
  | aniTimeShort   | Number                        | 基础短动画时长（ms）        |
  | aniTimeNormal  | Number                        | 基础标准动画时长（ms）      |
  | aniTimeLong    | Number                        | 基础长动画时长（ms）        |

---

## 主题系统（Theme）

主题指亮色（`light`）与暗色（`dark`）两种颜色模式。一套风格的 `colorBases` 包含两套 `SnColorBase` 颜色集。

- **切换**：`$snui.theme = 'light' | 'dark'`；`autoTheme`（默认开启）跟随系统外观。两者都经 `uni.setAppTheme` 驱动框架应用主题，框架再回写 `currentTheme`（App 端 `uni.onAppThemeChange`、Web 端 `uni.onHostThemeChange`）。App 端建议在 `manifest.json` 配置 `app.defaultAppTheme: "auto"`，让冷启动首帧即与系统一致。
- **状态栏同步**：切换与初始化时会调用 `syncStatusBarColor()` 同步原生状态栏文字/背景色。
- **App 端原生主题**：通过 `uni.setAppTheme` 同步系统暗黑模式，保证 `window` 等系统 UI 与页面一致。
- **Web 端主题源**：Web 没有 `osTheme`（只有宿主 `hostTheme`），框架读取 `uni.getAppBaseInfo().hostTheme` 并监听 `uni.onHostThemeChange`，`autoTheme` 在浏览器中同样能正确跟随。手动切换主题时以**应用主题为准**，不受浏览器外观反向影响。

`core/state.ts` 中导出的响应式状态构成了框架状态的根基：`currentStyleId`、`currentStyle`、`currentTheme`、`autoTheme`、`cssPalette`（颜色变量是否回落到脚本内联写入），以及由 `currentStyle × currentTheme` 计算出的 `colors`（当前颜色集）。

---

## 颜色系统

`SnColorBase` 定义了完整的语义化颜色集，分为**功能色**与**特殊色**两类（字段明细见[核心类型](/api/types/api#sncolorbase)）。

功能色共 5 种语义：`primary`（主色）、`info`（信息）、`success`（成功）、`error`（错误）、`warning`（警告）。每种功能色在亮/暗模式下各有 3 个深浅程度（原色 / `Light` 更浅 / `Dark` 更深），每个程度配套 `Active`（激活态）与 `Text`（该色背景上的文字前景色）。

> 注意：后缀带 `Dark` 的是比原色更深的颜色，并非暗黑主题专属；带 `Light` 的是更浅的颜色。暗黑主题与亮色主题各自拥有独立的 `SnColorBase` 对象。

- **颜色变量（应用主题优先，媒体查询兜底）**：`sn-page` 根节点始终带 `sn-theme-light` / `sn-theme-dark` 类，声明内置默认风格的全部 `--sn-*` 颜色变量，随 `$snui.theme` 切换；同样的色板另由 `@media (prefers-color-scheme: light)` / `@media (prefers-color-scheme: dark)` 声明，作为系统外观兜底（需 HBuilderX 5.25+ 蒸汽模式）。优先级为「内联 > `sn-theme-*` 类 > 媒体查询」，因此**手动切换主题后颜色不会被相反的系统外观覆盖**。页面内所有组件与弹出层（必须位于 `sn-page` 根节点下）通过 `var(--sn-xxx)` 引用即随主题自动切换；乘数与动画时长变量仍由 `sn-page` 差量写入。
- **自定义配色的回落**：调用 `$snui.setColor` / `setColorBase` 或切换到非默认内置风格后，颜色改由脚本写入内联变量（覆盖类色板与媒体查询色板）。该页面此后按完整色板的实际值差量更新，切回默认风格时直接写回默认色值，避免依赖删除变量后的 CSS 回退；连续修改颜色与切换亮暗主题同样同步。新创建的默认风格页面仍使用 CSS 色板。
- **`$` 简化语法**：颜色类 props 统一经 [useResolve](/api/hooks/use-resolve) 钩子的 `resolveColor` 处理，`$primaryTextDark` 自动转换为 `var(--sn-primary-text-dark)`，非 `$` 开头的值原样返回。

全部 `--sn-*` 颜色变量的命名规则、完整清单与用法示例，以及与它们等价的 JS 读写方式，见 [CSS 变量](/get-started/css-variables)。



## 大小乘数与动画时长

框架通过五个全局乘数控制 UI 的密度与动效节奏，均可在 `$snui` 上读写并持久化：

| 乘数属性 | 作用 |
| :--- | :--- |
| fontsizeFactor | 字号乘数 |
| radiusFactor | 圆角乘数 |
| marginFactor | 外间距乘数 |
| paddingFactor | 内间距乘数 |
| aniTimeFactor | 动画时长乘数 |

还提供了三个常用动画时长，以保持应用全局动画的一致性： `$snui.aniTimeShort(150ms)` / `$snui.aniTimeNormal(250ms)` / `$snui.aniTimeLong(400ms)`。这些常用动画时长会自动适配 `aniTimeFactor` 机制，无需您自行处理。脚本侧直接读 `$snui` 属性，样式侧引用 `sn-page` 注入的 `--ani-time-short` / `--ani-time-normal` / `--ani-time-long`，两套写法的对应关系见 [CSS 变量 · 动画时长变量](/get-started/css-variables#动画时长变量)。

### 乘数的三种用法

**① 组件 props 上的 `$` 语法**（页面开发最常用）

尺寸类 props 的值写成 `$16` 即跟随对应乘数缩放，写成 `16px` 则固定不变，详见下方 [`$` 动态尺寸语法](#动态尺寸语法)。

**② JS 中直接读写乘数**

五个乘数都可通过 `$snui` 直接读取或修改，修改后会持久化到当前风格：

```typescript
$snui.paddingFactor = 1.2
const padding = 12 * $snui.paddingFactor
const radius = 8 * $snui.radiusFactor
```

**③ CSS 中的乘数变量**

使用 HBuilderX Alpha 5.31 或更高版本时，`sn-page` 还会注入五个数值 CSS 变量：`--marginFactor`、`--paddingFactor`、`--radiusFactor`、`--fontsizeFactor`、`--aniTimeFactor`，并为每个乘数并列注入一个同值缩写变量：`--mf`、`--pf`、`--rf`、`--ff`、`--af`（缩写与全称是各自独立的字面值，不是 `var()` 引用）。它们适合直接用于 `calc()`，写起来更短：

```scss
.card {
  padding: calc(var(--pf) * 12px);
  border-radius: calc(var(--rf) * 8px);
  font-size: calc(var(--ff) * 14px);
}
```

| 全称变量 | 缩写变量 | 对应乘数 |
| :--- | :--- | :--- |
| `--marginFactor` | `--mf` | 外间距乘数 |
| `--paddingFactor` | `--pf` | 内间距乘数 |
| `--radiusFactor` | `--rf` | 圆角乘数 |
| `--fontsizeFactor` | `--ff` | 字号乘数 |
| `--aniTimeFactor` | `--af` | 动画时长乘数（不可用于 `calc()`） |

CSS 变量的作用域是 `sn-page` 根节点及其后代。乘数变化时，`sn-page` 会差量更新变量；脱离 `sn-page` 的独立组件不会自动获得这些变量。框架内的三个弹窗页（`snu.showModal` / `snu.showActionsheet` / `snu.showLoading`）是 dialogPage，不在任何 `sn-page` 子树内，页面会自行把颜色、动画时长与五个乘数变量一并注入到自己的根节点，因此在这些弹窗的 `customStyle` 中写 `calc(var(--xxxFactor) * Npx)` 同样有效；而 `snu.showToast` 走原生弹层、不涉及 CSS 变量，尺寸只走 `$` 动态值。

三类变量的完整清单（含每个变量的用途与典型写法）与更多示例见 [CSS 变量](/get-started/css-variables)。

#### **`$` 动态尺寸语法**

`$` 是尺寸类 props 的"动态"标记：**带 `$` 的值随对应乘数缩放，不带 `$` 的值按固定值处理、不乘任何乘数**。想要跟随风格与用户调节整体缩放的尺寸（字号、圆角、间距、动画时长）就加 `$`，需要写死的尺寸就不加。不带 `$` 的纯数字字符串会自动补单位（`border-radius="10"` → `10px`，动画时长类补 `ms`），`16px`、`50%` 等已带单位的写法原样输出。

**一、写在组件 props 上**

尺寸类 props 的值直接写成 `$数值` 即可（单位可省略：动画时长为 `ms`，其余为 `px`，也可显式写 `$16px`）：

```vue
<template>
	<sn-page>
		<!-- 带 $：跟随全局乘数缩放 -->
		<sn-text font-size="$16" text="字号随 fontsizeFactor 缩放" />
		<sn-avatar size="$48" text="M" bg-color="$primary" />
		<sn-button text="按钮" radius="$20" />
		<sn-popup ani-time="$normal" />
		<!-- 不带 $：固定尺寸，任何风格、任何乘数下都不变；纯数字自动补 px -->
		<sn-text font-size="16px" text="固定 16px" />
		<sn-button text="固定圆角" radius="20" />
	</sn-page>
</template>
```

每个 prop 用哪个乘数由组件内部指定，各组件属性表会标注该 prop 的 `$` 支持与对应乘数（形如「支持 `$` 前缀按 ✕✕ 乘数缩放」），使用时以属性表标注为准。五类解析类型与乘数的对应关系如下：

| 解析类型 | 对应乘数 | 适用 props 举例 | 写法 → 结果（乘数为 1 时） |
| :--- | :--- | :--- | :--- |
| `font` | fontsizeFactor | 字号类：`fontSize`（sn-text）、`textSize` / `iconSize`（sn-alert） | `font-size="$14"` → `14px` |
| `radius` | radiusFactor | 圆角类：`radius`（sn-button）、`borderRadius` | `radius="$8"` → `8px` |
| `margin` | marginFactor | 外间距类：`margin`（sn-card、sn-view）、`gap`（sn-pagination）、`spacing`（sn-avatar-group） | `margin="$12"` → `12px` |
| `padding` | paddingFactor | 内间距类：`padding`（sn-toast、sn-tooltip）、`size`（sn-avatar） | `padding="$16px $20px"` → `16px 20px` |
| `aniTime` | aniTimeFactor | 动画时长类：`aniTime`（sn-popup）、`hoverTransTime`（sn-button） | `ani-time="$250"` → `250ms` |

动画时长类 props 还接受三个命名值：`$short`、`$normal`、`$long`，分别对应 `$snui.aniTimeShort`（150ms）、`$snui.aniTimeNormal`（250ms）、`$snui.aniTimeLong`（400ms），同样随 `aniTimeFactor` 缩放，不带 `$` 的 `short` / `normal` / `long` 写法等价。

**二、在 JS 中自己拼样式**

自行拼接样式或开发自定义组件时，用 [useResolve](/api/hooks/use-resolve) 的 `resolveSize`（返回带单位字符串）/ `resolveSizeNum`（返回数值），第二个参数为解析类型（`font` / `radius` / `margin` / `padding` / `aniTime`）。**必须放在 `computed` 中求值**，否则乘数变化后不会重算：

```typescript
import { useResolve } from '@/uni_modules/sinle-ui'

const resolver = useResolve()

const cardStyleC = computed<string>(() => {
	return `padding:${resolver.resolveSize('$12', 'padding')};border-radius:${resolver.resolveSize('$8', 'radius')};`
})

const iconSizeC = computed<number>(() => resolver.resolveSizeNum('$16', 'font'))
```

**三、完整示例**

带 `$` 与固定值混用、运行时调节乘数的完整页面：

```vue
<template>
	<sn-page title="动态尺寸">
		<view :style="previewStyleC">
			<sn-text font-size="$14" text="带 $ 的字号：随 fontsizeFactor 缩放" />
			<sn-avatar size="$44" text="M" bg-color="$primary" />
			<sn-text font-size="14px" text="不带 $ 的字号：固定 14px" />
		</view>
		<sn-button text="放大字号" @click="enlarge" />
	</sn-page>
</template>

<script setup lang="ts">
import { $snui, useResolve } from '@/uni_modules/sinle-ui'

const resolver = useResolve()

const previewStyleC = computed<Map<string, any>>(() => {
	const styles = new Map<string, any>()
	styles.set('padding', resolver.resolveSize('$12', 'padding'))
	styles.set('borderRadius', resolver.resolveSize('$8', 'radius'))
	styles.set('backgroundColor', 'var(--sn-primary-light)')
	return styles
})

function enlarge(): void {
	$snui.fontsizeFactor = Math.round(($snui.fontsizeFactor + 0.2) * 10) / 10
}
</script>
```

点击「放大字号」调大 `fontsizeFactor` 后，带 `$` 的字号随之变大，固定 `14px` 的文本保持不变；头像尺寸由 `size` 决定、属间距类 props，跟随 `paddingFactor` 缩放，调大该乘数同样会变。demo 的「设计 → 大小乘数」页（`pages/design/factors`）提供字号、圆角、外间距、内间距、动画时长五个乘数滑块的完整可交互版本。

**使用要点**

- `$` 只在组件暴露的尺寸类 props 上生效：写在 `custom-style`、`style` 或 `<style>` 里的 `$` 不会被解析，CSS 侧请改用 [③ 中的 `calc(var(--xxxFactor) * Npx)`](#乘数的三种用法) 写法。
- `$` 后只支持纯数字（可含小数与负号）以及可选的 `px`（动画时长为 `ms`）单位，不支持表达式；解析失败时原样返回输入值，即不会缩放。
- 空格分隔的多段值按段解析，如 `margin="$12px auto"` → `12px auto`（每段各自套用上述规则）。
- 乘数在 [`$snui`](/api/index) 上读写并自动持久化；改动后模板中带 `$` 的 props 会即时重算，JS 中自行解析的值需放在 `computed` 内才会更新。

---

## 工具库三层架构

1. **分组静态类**（`core/utils/*.ts`）：按功能拆分为 Random、Basic、Easing、ObjectUtils、System、Sort、Text、Ui、Perm、Verify 共 10 组。
2. **聚合门面**（`core/utils/index.ts`）：`snu` 静态类，每个方法一行转发。
3. **插件出口**（`index.ts`）：`export { snu }`。

用户侧统一使用 `snu.xxx`；组件内部为减小体积直接导入分组类。平台相关方法（系统、权限等）经 `sinle-api` 插件按平台目录（`utssdk/app-android`、`utssdk/app-ios`、`utssdk/app-harmony`）分别实现，无需条件编译。

---

## 钩子

框架向组件与开发者暴露 4 个核心 hooks（useTheme / useStyle / useFactors / useHover），详见[钩子](/api/hooks/index)。组件的主题、风格、乘数、点击态、解析等能力均经由 hooks 获取，保证响应式（状态变化自动触发重渲染）。对外导出的 hooks 有 `useTheme` / `useStyle` / `useFactors` / `useHover` / `useResolve`；另有内部复用 hooks：`useExternalStyle`（外部样式转字符串）、`useBacktop`（滚动容器与返回顶部联动）。

---

## 全局弹窗机制

`snu.showToast` / `snu.showModal` / `snu.showActionsheet` / `snu.showLoading` 实现"任意位置调用、无需放置组件"的全局弹窗：

1. 框架内置 3 个弹窗页面（showModal、showActionsheet、showLoading），经 `pages_init.json` 注册；
2. `core/private/dialog-store.ts` 提供一个键值存储，保存本次弹窗的配置对象；
3. `snu` 的 UI 方法把配置写入 dialog-store，并通过 `uni.openDialogPage` 打开对应弹窗页；弹窗页 `onLoad` 时按 id 取回配置并展示，交互完成后触发 `success/fail/complete` 回调并关闭页面。

`showToast` 与 `highlight` 类轻提示由组件实现而非页面，其中 `showToast` 同样可在任意位置调用。

---

## 日志与错误

- **日志**：框架内部统一使用 `core/private/logger.ts`（转发自 `sinle-logger` 插件）输出 `[Snui]` 前缀日志，受 `$snui.logging` 控制开关。组件禁止直接使用 `console`。
- **错误**：`UniError` 为框架统一错误类型（遵循 uni 错误规范），全局 API 失败时通过 `fail` 回调返回，详见[错误与日志](/api/error/error)。
---


## 国际化（i18n）

SinleUI 内置一套**独立于宿主项目**的国际化系统：框架内所有组件内置文本（确定/取消/加载中/上传/刷新/签名/扫码等）默认均通过翻译函数渲染，**不含任何硬编码文字**，并随组件语言自动切换。

> [!IMPORTANT] 独立性
>
> 插件 i18n 与宿主项目自身的 i18n（如项目按 [uni-app x 国际化文档](https://doc.dcloud.net.cn/uni-app-x/i18n.html) 搭建的 vue-i18n）**互相独立、互不影响**。插件不依赖项目是否接入 vue-i18n，因此 sinle-* 插件可安全地用于任何已适配或未适配 i18n 的项目。

### 支持的语言

共 11 种：

- 简体中文 `zh-Hans`
- 英语 `en`
- 法语 `fr`
- 俄语 `ru`
- 日语 `ja`
- 繁体中文 `zh-Hant`
- 韩语 `ko`
- 西班牙语 `es`
- 德语 `de`
- 意大利语 `it`
- 葡萄牙语 `pt`

### 默认语言策略

初始化时按「存储值 > 系统语言（自动匹配近似标签）> 简体中文」取默认值；切换后自动持久化（storage key：`sinleui_current_locale`），重启恢复。

### 使用方式

```typescript
import { $snui, t, locale, useI18n, SUPPORTED_LOCALES } from '@/uni_modules/sinle-ui'

// 切换组件语言（全局生效，自动持久化）
$snui.locale = 'en'

// 组件内翻译（响应式，语言变化自动重渲染）
const label = t('common.confirm')
const range = t('calendar.rangePrompt', { maxRange: '7' }) // 参数插值

// hooks 形式（模板中使用 t / locale）
const { t, locale } = useI18n()

// 支持的语言列表（含本地化名称，可直接渲染为语言选择器）
SUPPORTED_LOCALES // [{ code: 'zh-Hans', name: '简体中文' }, ...]
```

### 消息文件

- 插件消息：`uni_modules/sinle-ui/core/i18n/locale/*.ts`（每语言一个文件，键形如 `common.confirm`、`loadmore.more`）。
- 组件 props 默认值均已改为空串 + `t()` 兜底：用户传入自定义文本时优先显示用户值，否则回落到当前语言。
- 日历、日期格式化等组件（weekdays / 月份 / 相对时间）同样接入插件 i18n。

# CSS 变量

SinleUI 通过页面根组件 [sn-page](/components/sn-page) 向页面注入一整套 CSS 变量，页面内所有子组件（含 `sn-popup`、`sn-modal`、`sn-toast` 等弹出层类组件）只需用 `var(--xxx)` 引用，即可自动获得**主题配色**、**尺寸乘数**与**动画时长**，无需脚本参与上色。

这套变量共分三类：

| 分类 | 命名 | 数量 | 作用 |
| :--- | :--- | :--- | :--- |
| 颜色 | `--sn-*` | 61 | 亮/暗主题下的语义化颜色，随主题自动切换 |
| 尺寸乘数 | `--xxxFactor` 与缩写（`--mf`、`--pf` 等） | 5 + 5 | 字号、圆角、内外间距、动画时长的全局缩放系数 |
| 动画时长 | `--ani-time-*` | 3 | 短 / 标准 / 长三档动画时长（已乘动画乘数） |

::: danger 变量只存在于 sn-page 子树内
变量注入在 `sn-page` 根节点上，只对其后代生效。页面必须以 `sn-page` 为根节点，所有组件都放在其下，否则 `var(--sn-*)`、`var(--ani-time-*)` 引用会失效，颜色与动画时长错乱。
:::

---

## 变量总览

### 颜色变量

命名规则：**`$snui.colors` 的字段名由小驼峰转为 kebab-case，加 `--sn-` 前缀**。例如 `primaryLightActive` → `--sn-primary-light-active`、`disabledText` → `--sn-disabled-text`。

#### 特殊色

| CSS 变量 | 对应 `$snui.colors` 字段 | 用途 |
| :--- | :--- | :--- |
| `--sn-transparent` | `transparent` | 透明色（非 CSS 的 `transparent`，主题切换时不会闪黑，框架内透明背景一律用它） |
| `--sn-page` | `page` | 页面背景色 |
| `--sn-front` | `front` | 前景色，一般用作卡片等块状组件背景 |
| `--sn-dark` | `dark` | 亮色模式为黑色，暗色模式为白色 |
| `--sn-disabled` | `disabled` | 禁用状态背景色 |
| `--sn-disabled-text` | `disabledText` | 禁用状态文字色 |
| `--sn-disabled-dark` | `disabledDark` | 更深的禁用背景色 |
| `--sn-disabled-dark-text` | `disabledDarkText` | 更深的禁用文字色 |
| `--sn-line` | `line` | 线条色（分割线、边框） |
| `--sn-line-dark` | `lineDark` | 更深的线条色 |
| `--sn-line-text` | `lineText` | 线条区域的文字色 |
| `--sn-title` | `title` | 标题文字色 |
| `--sn-text` | `text` | 正文文字色 |
| `--sn-text-light` | `textLight` | 更浅的正文文字色（辅助说明） |
| `--sn-toast` | `toast` | 轻提示背景色 |
| `--sn-shadow` | `shadow` | 阴影色 |

#### 功能色

功能色共 5 种语义：`primary`（主色）、`info`（信息）、`success`（成功）、`error`（错误）、`warning`（警告）。每种语义在亮/暗模式下各有 3 个深浅程度（原色 / `light` 更浅 / `dark` 更深），每个程度配套 `active`（激活态）与 `text`（该色背景上的文字前景色）——即每种功能色有 9 个变量，5 种合计 45 个。

以 `primary` 为例：

| CSS 变量 | 对应 `$snui.colors` 字段 | 用途 |
| :--- | :--- | :--- |
| `--sn-primary` | `primary` | 主题色（原色） |
| `--sn-primary-active` | `primaryActive` | 主题色激活态 |
| `--sn-primary-text` | `primaryText` | 主题色背景上的文字色 |
| `--sn-primary-light` | `primaryLight` | 更浅的主题色 |
| `--sn-primary-light-active` | `primaryLightActive` | 更浅主题色的激活态 |
| `--sn-primary-light-text` | `primaryLightText` | 更浅主题色背景上的文字色 |
| `--sn-primary-dark` | `primaryDark` | 更深的主题色 |
| `--sn-primary-dark-active` | `primaryDarkActive` | 更深主题色的激活态 |
| `--sn-primary-dark-text` | `primaryDarkText` | 更深主题色背景上的文字色 |

`info` / `success` / `error` / `warning` 的变量名把上表的 `primary` 换成对应语义即可（如 `--sn-success-light-text`、`--sn-error-dark`）。

> 后缀带 `dark` 的是比原色更深的颜色，**不是暗黑主题专属**；带 `light` 的是更浅的颜色。暗黑主题与亮色主题是两个独立的颜色集。

### 乘数变量

五个乘数控制全局的尺寸密度与动效节奏，每个乘数同时提供一个同值缩写变量（缩写与全称是各自独立的字面值，不是 `var()` 引用）：

| 全称变量 | 缩写变量 | 对应 `$snui` 属性 | 用途 | 典型写法 |
| :--- | :--- | :--- | :--- | :--- |
| `--marginFactor` | `--mf` | `marginFactor` | 外间距乘数 | `margin-bottom: calc(var(--mf) * 10px);` |
| `--paddingFactor` | `--pf` | `paddingFactor` | 内间距乘数 | `padding: calc(var(--pf) * 16px);` |
| `--radiusFactor` | `--rf` | `radiusFactor` | 圆角乘数 | `border-radius: calc(var(--rf) * 12px);` |
| `--fontsizeFactor` | `--ff` | `fontsizeFactor` | 字号乘数 | `font-size: calc(var(--ff) * 14px);` |
| `--aniTimeFactor` | `--af` | `aniTimeFactor` | 动画时长乘数 | 仅作标记与调试，**不可用于 `calc()`**（时间类型不支持） |

乘数变量是**无单位的纯数字**，必须放在 `calc()` 中与固定设计值相乘，不能直接当长度值使用（`padding: var(--pf)` 无效）。

### 动画时长变量

| CSS 变量 | 对应 `$snui` 属性 | 说明 |
| :--- | :--- | :--- |
| `--ani-time-short` | `aniTimeShort` | 短动画时长，基础值 150ms × `aniTimeFactor` |
| `--ani-time-normal` | `aniTimeNormal` | 标准动画时长，基础值 250ms × `aniTimeFactor` |
| `--ani-time-long` | `aniTimeLong` | 长动画时长，基础值 400ms × `aniTimeFactor` |

变量值为带 `ms` 单位的字符串（如 `250ms`），可直接赋给 `transition-duration` 等时长属性。框架内动效统一走这三档时长（样式表引用变量、脚本读取 `$snui.aniTime*`），`aniTimeFactor` 变化时全站动画节奏同步变化。

---

## 使用示例

### 在样式表中引用颜色与动画时长

```scss
.card {
	background-color: var(--sn-front);
	border-bottom: 1px solid var(--sn-line);
	box-shadow: 0 4px 12px var(--sn-shadow);
	transition-property: background-color, border-color;
	transition-duration: var(--ani-time-normal);
}

.card-title {
	color: var(--sn-title);
	font-size: 16px;
}

.card-desc {
	color: var(--sn-text-light);
}

/* 带功能色的标签块：浅色底 + 对应文字色 */
.tag-primary {
	background-color: var(--sn-primary-light);
	color: var(--sn-primary-light-text);
	transition-duration: var(--ani-time-short);
}

/* 禁用态与透明背景 */
.btn-disabled {
	background-color: var(--sn-disabled);
	color: var(--sn-disabled-text);
}

.mask {
	background-color: var(--sn-transparent);
}
```

### 用 calc() 结合乘数变量

```scss
.block {
	padding: calc(var(--pf) * 16px);
	margin-bottom: calc(var(--mf) * 12px);
	border-radius: calc(var(--rf) * 12px);
}

.block-title {
	font-size: calc(var(--ff) * 16px);
	line-height: 1.4em;
}
```

> `calc()` 中 `+` / `-` 两侧必须留空格，`*` / `/` 至少一方必须是纯数字；乘数变量只能参与长度类属性（`width`、`padding`、`margin`、`border-radius` 等），不能用于时间、角度或颜色。

### 在模板与组件属性中引用

组件内置的 `$` 简写与 `var(--sn-*)` 等价：`color="$primary"` 会被框架自动转换为 `var(--sn-primary)`，因此**能用 `$` 简写的属性优先用 `$`，其余场合（`custom-style`、`style`、样式表）直接写 `var(--sn-*)`**。`$` 的完整规则（单位补全、`$short` / `$normal` / `$long` 命名值、各解析类型与乘数的对应关系）见 [框架设计 · `$` 动态尺寸语法](/get-started/framework#动态尺寸语法)。

```vue
<template>
	<sn-page title="CSS 变量">
		<!-- $ 简写：自动转 var(--sn-*)，随主题切换 -->
		<sn-card title="主题色卡片" title-color="$title" bg-color="$front" border="1px solid $line">
			<sn-text font-size="$14" color="$text" text="正文文字，使用 --sn-text" />
			<sn-text font-size="$12" color="$textLight" text="辅助文字，使用 --sn-text-light" />
			<view class="bar" :style="barStyles" />
		</sn-card>

		<!-- 直接写 CSS 变量同样有效 -->
		<sn-button text="主要操作" type="primary" radius="$20"
			custom-style="margin:calc(var(--mf) * 12px) 0;"></sn-button>
	</sn-page>
</template>

<script lang="ts" setup>
const barStyles = computed<Map<string, any>>(() => {
	const styles = new Map<string, any>()
	styles.set('height', '6px')
	styles.set('backgroundColor', 'var(--sn-primary)')
	styles.set('borderRadius', 'calc(var(--rf) * 3px)')
	return styles
})
</script>
```

### 在 JS 中拼样式

脚本里拼样式与编写自定义组件时，样式值同样使用 `var(--sn-*)` 字符串，**必须放在 `computed` 中**，否则主题或乘数变化后不会重算：

```typescript
import { useResolve } from '@/uni_modules/sinle-ui'

const resolver = useResolve()

const panelStyles = computed<Map<string, any>>(() => {
	const styles = new Map<string, any>()
	styles.set('backgroundColor', 'var(--sn-front)')
	styles.set('borderRadius', resolver.resolveSize('$12', 'radius'))
	styles.set('padding', resolver.resolveSize('$16', 'padding'))
	styles.set('transitionDuration', 'var(--ani-time-normal)')
	return styles
})
```

### 颜色变量的两个来源

| 场景 | 颜色变量来源 |
| :--- | :--- |
| 以内置**默认**风格加载、尚未注入过内联色板的页面 | `sn-page` 根节点的 `sn-theme-light` / `sn-theme-dark` 类（随应用主题切换），样式中的 `@media (prefers-color-scheme: light \| dark)` 作为系统外观兜底（需 HBuilderX 5.25+ 蒸汽模式） |
| 页面应用过 `setColor` / `setColorBase`，或切换到其它内置风格 | 脚本把当前主题色板写成根节点的**内联变量**（覆盖类色板与媒体查询色板），此后按实际值差量更新；切回默认风格时显式写回默认色值，后续亮暗主题和配色调整继续同步 |

无论哪种来源，页面内的写法都是 `var(--sn-*)`，不需要区分。乘数与动画时长变量则由 `sn-page` 差量写入，与颜色无关。

::: info 应用主题优先于系统外观
颜色变量按「内联 > `sn-theme-*` 类 > `prefers-color-scheme` 媒体查询」的顺序生效。这意味着**用户在应用内切换主题后，颜色以应用选择为准**，不会因为浏览器或系统外观相反而出现底色与文字割裂；只有当 `autoTheme` 开启、应用跟随系统外观时，两者才一致。
:::

三个内置弹窗页（`snu.showModal` / `snu.showActionsheet` / `snu.showLoading`）是独立的 dialogPage，不在任何 `sn-page` 子树内，页面会自行把颜色、动画时长与五个乘数变量注入自己的根节点，因此在它们的 `customStyle` 中写 `calc(var(--xxxFactor) * Npx)` 同样有效。`snu.showToast` 走原生弹层、不涉及 CSS 变量，尺寸只走 `$` 动态值。

---

## 与 CSS 变量同功能的 JS 方式

CSS 变量负责**"在样式里用颜色"**，JS 负责**"读取与修改"**。两者能力对照：

| 能力 | CSS 变量方式 | JS 方式 |
| :--- | :--- | :--- |
| 在样式中使用主题色 | `var(--sn-primary)` | `useResolve().resolveColor('$primary')` → `'var(--sn-primary)'` |
| 读取颜色当前的实际色值 | 不支持 | `$snui.colors.primary` |
| 在原生弹层 / 原生元素中使用主题色 | 不支持（原生层不解析 CSS 变量） | `useResolve().resolveColorValue('$primary')` → `'#4d82ff'` |
| 修改单个颜色键 | 不支持 | `$snui.setColor('light', 'primary', '#4d82ff')` |
| 整体替换一套配色 | 不支持 | `$snui.setColorBase('dark', myColorBase)` |
| 切换亮 / 暗主题 | `sn-theme-*` 类自动切换 | `$snui.theme = 'dark'`、`useTheme().setTheme()` |
| 跟随系统外观 | — | `$snui.autoTheme = true`、`useTheme().setAutoTheme()` |
| 在样式中使用尺寸乘数 | `calc(var(--pf) * 16px)` | `useResolve().resolveSize('$16', 'padding')` → `'16px'` |
| 读取尺寸乘数 | 不支持 | `$snui.paddingFactor` 等、`useFactors()` |
| 修改尺寸乘数 | 不支持 | `$snui.paddingFactor = 1.2` |
| 读取动画时长 | `var(--ani-time-normal)` | `$snui.aniTimeNormal` |
| 修改动画时长 / 动画乘数 | 不支持 | `$snui.baseAniTimeNormal = 300`、`$snui.aniTimeFactor = 0` |

### 读取颜色与实际色值

```typescript
import { $snui, useResolve } from '@/uni_modules/sinle-ui'

const resolver = useResolve()

// 实际色值：$snui.colors 是当前主题（light/dark）下的颜色集，只读
const brandText = computed<string>(() => $snui.colors.primary)

// 等价于 CSS 变量写法，用于拼样式
const brandVar = resolver.resolveColor('$primary')

// 脱离 CSS 变量作用域的场景（原生弹层、原生元素等）必须取实际色值
const brandValue = resolver.resolveColorValue('$primary')
```

`$snui.colors` 是响应式的：放在 `computed` 中，主题或配色变化时会自动重算。

### 修改主题颜色

```typescript
import { $snui } from '@/uni_modules/sinle-ui'

// ① 修改单个颜色键（theme 取 'light' | 'dark'，key 取 SnColorBase 的字段名）
$snui.setColor('light', 'primary', '#4d82ff')
$snui.setColor('dark', 'primary', '#4d82ff')

// 特殊色同理，例如修改页面背景色（等价于 $snui.lightBgColor）
$snui.setColor('light', 'page', '#f5f7fa')

// ② 整体替换某个主题的颜色集，一键换肤（myDarkColors 为完整的 SnColorBase 对象，构造方式见下）
$snui.setColorBase('dark', myDarkColors)
```

- `$snui.setColor` 的颜色键必须是 `SnColorBase` 中存在的字段（如 `primary`、`primaryLightText`、`textLight`、`shadow`），传入不存在的键只会输出警告、不生效。
- `$snui.setColorBase` 的入参是**完整的颜色集对象**，`SnColorBase` 的全部字段都必填，需要整块换肤时使用：

```typescript
import { $snui } from '@/uni_modules/sinle-ui'
import type { SnColorBase } from '@/uni_modules/sinle-ui'

// 以当前亮色颜色集为底稿（$snui.colors 即当前主题颜色集），替换主色系后整体写回
const light = $snui.colors

// 注意：SnColorBase 的 61 个字段全部必填，下面的值对象需写全，未改动字段从 light 照抄
const myLightColors: SnColorBase = {
	primary: '#22c55e',
	primaryActive: '#4ade80',
	primaryText: '#ffffff',
	primaryLight: '#dcfce7',
	primaryLightActive: '#bbf7d0',
	primaryLightText: '#22c55e',
	primaryDark: '#16a34a',
	primaryDarkActive: '#22c55e',
	primaryDarkText: '#ffffff'
	// …余下 52 个字段（transparent / page / front / info 系 / success 系 / error 系 / warning 系 …）照抄 light
}

$snui.setColorBase('light', myLightColors)
```

只改少量颜色时用 `$snui.setColor` 逐个写入更省事，无需改动整份颜色集。两种修改都会自动持久化（应用重启后保持），并把颜色变量的来源切换为内联写入，页面内的 `var(--sn-*)` 与组件配色即时更新，无需刷新页面。

### 切换主题与跟随系统

```typescript
import { $snui } from '@/uni_modules/sinle-ui'

$snui.theme = 'dark' // 切换到暗黑模式，同时自动关闭 autoTheme
$snui.theme = 'light' // 切换回亮色模式
$snui.autoTheme = true // 重新跟随系统外观
```

钩子形式（响应式，适合在设置页做开关）：

```typescript
import { useTheme } from '@/uni_modules/sinle-ui'

const { theme, isDark, isLight, isAuto, setTheme, setAutoTheme, toggleTheme } = useTheme()

function onDarkChange(val: boolean): void {
	setAutoTheme(false)
	setTheme(val ? 'dark' : 'light')
}
```

主题切换由框架驱动，`sn-page` 注入的颜色变量会随之更新，页面内所有 `var(--sn-*)` 自动换色——这也是**优先用 CSS 变量而不是在脚本里写死颜色**的原因。

### 读写乘数与动画时长

```typescript
import { $snui, useFactors } from '@/uni_modules/sinle-ui'

// 修改乘数（自动持久化；页面内带 $ 的 props 与 calc(var(--xf) * Npx) 样式即时重算）
$snui.fontsizeFactor = 1.2
$snui.paddingFactor = 1.1
$snui.radiusFactor = 1.5
$snui.marginFactor = 1
$snui.aniTimeFactor = 0 // 0 关闭动画、1 标准速度、2 慢速

// 读取乘数
const pf = $snui.paddingFactor

// 动画时长：读取为「基础时长 × aniTimeFactor」，赋值按当前乘数反算写回基础时长
const normal = $snui.aniTimeNormal
$snui.baseAniTimeNormal = 300 // 直接改基础时长（默认 250ms）
```

钩子形式（响应式读值）：

```typescript
import { useFactors } from '@/uni_modules/sinle-ui'

const { marginFactor, paddingFactor, radiusFactor, fontsizeFactor, aniTimeFactor } = useFactors()

const fontsizeText = computed<string>(() => `${fontsizeFactor.value}×`)
```

### 解析函数：resolveColor 与 resolveColorValue

| 函数 | 输入示例 | 输出 | 适用场景 |
| :--- | :--- | :--- | :--- |
| `resolveColor` | `'$primary'` | `'var(--sn-primary)'` | 页面内组件的样式（依赖 `sn-page` 注入变量，随主题实时切换） |
| `resolveColorValue` | `'$primary'` | `'#4d82ff'` 等实际色值 | 原生弹层、原生元素等脱离 CSS 变量作用域的场景 |
| `resolveSize` | `'$16'` + `'font'` | `'16px'`（× 字号乘数） | 尺寸类 props 与自定义样式，等价于 `calc(var(--ff) * 16px)` |

```typescript
import { useResolve } from '@/uni_modules/sinle-ui'

const resolver = useResolve()

const styles = computed<Map<string, any>>(() => {
	const out = new Map<string, any>()
	out.set('color', resolver.resolveColor('$primary')) // 'var(--sn-primary)'
	out.set('padding', resolver.resolveSize('$16', 'padding')) // 与 calc(var(--pf) * 16px) 等效
	return out
})

// 原生弹层（如 snu.showToast）不接受 CSS 变量，必须用实际色值
const toastColor = resolver.resolveColorValue('$primary')
```

---

## 注意事项

1. **变量只对 `sn-page` 后代生效**：页面必须以 `sn-page` 为根节点、所有组件放在其下；脱离 `sn-page` 的独立组件不会自动获得这些变量。
2. **不要写死颜色**：组件颜色类 props 用 `$` 简写（`$primary`、`$text`、`$line` 等），样式表用 `var(--sn-*)`，脚本拼样式也返回 `var(--sn-*)` 字符串；只有在原生弹层等无法解析 CSS 变量的场景才取实际色值（`resolveColorValue` / `$snui.colors`）。
3. **透明背景统一用 `var(--sn-transparent)`**，不要用 CSS 的 `transparent` 或 `rgba(0,0,0,0)`，避免主题切换瞬间出现闪黑。
4. **乘数变量必须包在 `calc()` 里**：`calc(var(--pf) * 16px)`；`--aniTimeFactor`（`--af`）不可用于 `calc()`。
5. **脚本中解析结果必须写在 `computed` 内**：主题、风格、乘数变化时才会计入重算。
6. **作用域提醒**：CSS 变量的可见范围等于 `sn-page` 根节点子树，同一页面内不同 `sn-page` 各自注入，互不影响。

相关阅读：[框架设计 · 颜色系统](/get-started/framework#颜色系统)、[框架设计 · 大小乘数与动画时长](/get-started/framework#大小乘数与动画时长)、[sn-page 组件](/components/sn-page)、[useResolve](/api/hooks/use-resolve)、[useTheme](/api/hooks/use-theme)、[useFactors](/api/hooks/use-factors)、[`$snui` API](/api/index)。

# API

SinleUI 向外暴露全局可操作的框架对象 `$snui`（框架配置与全局能力）、`snu`（工具库聚合门面）、一系列钩子、核心库（颜色库 `ColorLib`/`TinyColor`、日期库 `DateLib`/`Dayuts`）以及大量类型定义。

>[!WARNING] 注意
>
>不可直接从插件内部任何 `.ts` 文件导入对象或类型，所有对象及类型均从 `@/uni_modules/sinle-ui` 导入；`UniError` / `SourceError` 等错误对象为 uni-app x 运行时内置全局对象，无需导入。

```typescript
import {
	$snui,
	snu,
	syncStatusBarColor,
	ColorLib,
	TinyColor,
	DateLib,
	Dayuts,
	dayuts,
	isDayuts,
	dayutsIntl,
	useTheme,
	useStyle,
	useFactors,
	useHover,
	useResolve,
	useTabbarHeights,
	useI18n,
	t,
	locale,

	SUPPORTED_LOCALES,
	SN_DEFAULT_STYLE_ID,
	createCalendarDayPaint,
	createCalendarDayContent
} from '@/uni_modules/sinle-ui'
```

---

# 模块导出总览

| 分类 | 导出内容 | 说明 |
| :--- | :--- | :--- |
| 框架对象 | `$snui` | `Snui` 单例实例，框架全局配置与主题、风格控制入口 |
| 工具库 | `snu` | 工具方法聚合门面（静态类，包含随机、缓动、校验等 10 组方法），[详见](/libs/utils/index) |
| 钩子 | `useTheme` / `useStyle` / `useFactors` / `useHover` / `useResolve` / `useI18n` / `useTabbarHeights` | 获取主题、风格、乘数、点击态、解析、国际化和页面作用域 Tabbar 高度 |
| 颜色库 | `ColorLib` / `TinyColor` | 颜色解析、转换与色板生成，[详见](/libs/color/index) |
| 日期库 | `DateLib` / `Dayuts` / `dayuts` / `isDayuts` / `dayutsIntl` | 日期解析、格式化与国际化，[详见](/libs/date/index) |
| 全局函数 | `syncStatusBarColor` / `createCalendarDayPaint` / `createCalendarDayContent` / `t` | 状态栏颜色同步、日历天定制工具、国际化翻译 |
| 常量 | `SN_DEFAULT_STYLE_ID` / `SUPPORTED_LOCALES` / `locale` | 默认风格 id、支持的语言列表、当前组件语言 |
| 错误 | `UniError` | 统一错误类型（uni-app x 运行时内置），[详见](/api/error/error) |
| 类型 | 见[核心类型](/api/types/index) | `SnColorBase`、`SnStyle`、手势事件、弹窗配置等全部类型 |

> 类型字段：SN_DEFAULT_STYLE_ID（见 https://sinleui.pages.dev/api/types/component#sn_default_style_id）

> 类型字段：UniError（见 https://sinleui.pages.dev/api/types/component#unierror）

> 类型字段：SnColorBase（见 https://sinleui.pages.dev/api/types/component#sncolorbase）

> 类型字段：SnStyle（见 https://sinleui.pages.dev/api/types/component#snstyle）


---

:::

---

# $snui

`$snui` 是 `Snui` 类的单例实例，是 SinleUI 的全局配置中心。所有风格、主题、尺寸乘数、动画时长、页面背景等设置均通过它读写，修改后自动持久化，并实时驱动页面：颜色变量由 `sn-page` 样式中的系统外观媒体查询提供，乘数与动画时长变量由 `sn-page` 差量写入。

### 属性

| 名称 | 类型 | 只读 | 描述 |
| :--- | :--- | ---- | :--- |
| colors | `SnColorBase` | 是 | 当前主题（light/dark）下的颜色集对象，例如 `$snui.colors.primaryText` |
| currentStyleId | String | 否 | 当前风格 id，赋值为不存在的 id 时仅输出警告并保持原值 |
| theme | String | 否 | 当前主题模式，可选值 `light` \| `dark`，设置时会自动关闭 `autoTheme` |
| autoTheme | Boolean | 否 | 是否跟随系统外观自动切换主题（默认开启） |
| grayMode | Boolean | 否 | 哀悼置灰（灰度模式）开关，开启后全局呈现黑白效果 |
| grayLevel | Number | 否 | 哀悼置灰程度（0-100，默认 100 全灰），仅当 grayMode 开启时生效 |
| topbarHeight | String | 否 | `sn-topbar` 导航栏高度（不含状态栏），默认 `48px` |
| topbarHeightResolved | String | 是 | `sn-topbar` 在当前平台实际渲染的导航栏高度（不含状态栏）：非 Web 端等于 `topbarHeight`，Web 端为 `topbarHeight + 8px` |
| lightBgColor | String | 否 | 亮色模式页面默认背景色 |
| darkBgColor | String | 否 | 暗色模式页面默认背景色 |
| logging | Boolean | 否 | 是否开启框架日志输出（默认开启） |
| locale | String | 否 | 当前组件语言（BCP 47 标签，如 `'zh-Hans'` / `'en'`），赋值即切换并持久化，不支持的语言仅输出警告并保持原值 |
| marginFactor | Number | 否 | 外间距乘数 |
| paddingFactor | Number | 否 | 内间距乘数 |
| radiusFactor | Number | 否 | 圆角乘数 |
| fontsizeFactor | Number | 否 | 字号乘数 |
| aniTimeFactor | Number | 否 | 动画时长乘数，`0` 关闭动画、`1` 标准速度、`2` 慢速 |
| aniTimeShort | Number | 否 | 短动画时长（ms），读取 = `rounded(baseAniTimeShort × aniTimeFactor)`；赋值按当前乘数反算写入基础时长并持久化（乘数为 0 时直接写入） |
| aniTimeNormal | Number | 否 | 标准动画时长（ms），读取 = `rounded(baseAniTimeNormal × aniTimeFactor)`；赋值按当前乘数反算写入基础时长并持久化（乘数为 0 时直接写入） |
| aniTimeLong | Number | 否 | 长动画时长（ms），读取 = `rounded(baseAniTimeLong × aniTimeFactor)`；赋值按当前乘数反算写入基础时长并持久化（乘数为 0 时直接写入） |
| baseAniTimeShort | Number | 否 | 基础短动画时长（ms），默认 `150` |
| baseAniTimeNormal | Number | 否 | 基础标准动画时长（ms），默认 `250` |
| baseAniTimeLong | Number | 否 | 基础长动画时长（ms），默认 `400` |

### 方法

| 名称 | 参数 | 返回值 | 描述 |
| ---- | ---- | ------ | ---- |
| setColor | (theme: string, key: string, value: string) | - | 设置指定主题（`light` \| `dark`）中指定颜色键的值。颜色键必须是 `SnColorBase` 中存在的字段，否则输出警告。设置后自动持久化 |
| setColorBase | (theme: string, colorBase: `SnColorBase`) | - | 整体替换指定主题的颜色集，一键修改项目配色 |

| syncSystemTheme | () | - | 若 `autoTheme` 为开启，则应用系统当前外观主题 |

### 示例

```typescript
// 切换主题
$snui.theme = 'dark'

// 修改字号乘数
$snui.fontsizeFactor = 1.2

// 自定义主题色
$snui.setColor('light', 'primary', '#4d82ff')
$snui.setColorBase('dark', myDarkColorBase)
```

---

# syncStatusBarColor

### **同步状态栏文字与背景颜色**

将原生状态栏文字颜色与背景色同步为当前主题下的样式（亮色下黑字白底，暗色下白字黑底）。

| 参数 | 返回值 | 描述 |
| ---- | ------ | ---- |
| 无 | - | 依据当前 `$snui.theme` 同步系统状态栏颜色 |

---

# createCalendarDayPaint / createCalendarDayContent

创建 `sn-calendar-view` 日期格定制所需的数据结构与内容。

| 名称 | 参数 | 返回值 | 描述 |
| ---- | ---- | ------ | ---- |
| createCalendarDayPaint | (input: `SnCalendarDayPaintInput`) | `SnCalendarDayPaint` | 创建日期涂色数据，用于自定义日期背景、文本颜色等 |
| createCalendarDayContent | (input: `SnCalendarDayContentInput`) | `SnCalendarDayContent` | 创建日期内容数据，用于自定义日期内图标、圆点等 |

> 类型字段：SnCalendarDayPaintInput（见 https://sinleui.pages.dev/api/types/component#sncalendardaypaintinput）

> 类型字段：SnCalendarDayPaint（见 https://sinleui.pages.dev/api/types/component#sncalendardaypaint）


:::

> 类型字段：SnCalendarDayContentInput（见 https://sinleui.pages.dev/api/types/component#sncalendardaycontentinput）

> 类型字段：SnCalendarDayContent（见 https://sinleui.pages.dev/api/types/component#sncalendardaycontent）


---

# Snui（类）

`Snui` 类定义与 `$snui` 实例的属性、方法一致，完整风格对象结构参见 [SnStyle](/api/types/api#snstyle)。

# 钩子

SinleUI 采用 Vue3 组合式 API 设计，向组件与开发者暴露一组钩子，用于获取框架状态并在组件内响应式使用。所有 hooks 统一从插件入口导出：

```typescript
import { useTheme, useStyle, useFactors, useHover, useResolve, useHistory, useI18n, useTabbarHeights } from '@/uni_modules/sinle-ui'
```

> [!TIP] 提示
>
> 框架内部组件同样通过这些 hooks 获取主题、乘数、解析等能力，因此任何修改都会自动触发依赖它的组件更新。

## 钩子总览

| Hook | 功能描述 | 来源 |
| :--- | :--- | :--- |
| [useTheme](/api/hooks/use-theme) | 获取与切换当前主题（light / dark / auto） | 插件出口导出 |
| [useStyle](/api/hooks/use-style) | 获取当前风格与切换风格 | 插件出口导出 |
| [useFactors](/api/hooks/use-factors) | 响应式读取五个全局尺寸乘数 | 插件出口导出 |
| [useHover](/api/hooks/use-hover) | 统一点击态（按下反馈）机制 | 插件出口导出 |
| [useResolve](/api/hooks/use-resolve) | `$` 前缀动态尺寸解析与颜色简写解析 | 插件出口导出 |
| [useHistory](/api/hooks/use-history) | 增量操作日志式的撤销/重做存储引擎 | 插件出口导出 |
| [useI18n](/api/hooks/use-i18n) | 组件语言响应式读取与翻译函数 | 插件出口导出 |
| [useTabbarHeights](/api/hooks/use-tabbar-heights) | 读取当前 sn-page 内按 key 登记的 Tabbar 实际高度 | 插件出口导出 |
| [useExternalStyle](/api/hooks/use-external-style) | 外部样式（SnStyleValue）转样式字符串 | 组件内部使用，可复用 |
| [useBacktop](/api/hooks/use-backtop) | 滚动容器与 sn-backtop 回顶联动机制 | 组件内部使用，可复用 |

其中 `useTheme` / `useStyle` / `useFactors` / `useHover` / `useResolve` / `useHistory` / `useI18n` / `useTabbarHeights` 从插件入口 `@/uni_modules/sinle-ui` 导出，可直接在业务代码中使用；`useExternalStyle` 与 `useBacktop` 主要供框架内部组件复用，自定义组件开发时同样可以引入使用（从对应源文件路径导入）。

## 使用约定

- hooks 必须在组件 `<script setup>`（或钩子）中调用，返回值中的响应式状态为 Vue `computed` / `ref`，在模板中自动解包。
- 一个 hook 可多次调用；全局配置钩子共享框架全局状态，`useTabbarHeights` 仅共享最近的 sn-page 作用域状态。
- **读取型返回值一律为 `computed`（只读）**：`isDark`、`isAuto`、`styleId`、五个乘数、`locale` 等都不能直接 `v-model`，需用 `:model-value` + `@change` 回写，或自行包一层带 get/set 的 `computed`。
- 写入统一走框架 API：`$snui` 的属性与方法，或 hook 提供的 setter（`setTheme`、`setStyle` 等）。
- 框架内部还有若干仅供组件内部复用的工具型 hook（如 `useExternalStyle`、`useBacktop`），不在上表之外另行列举。

# useTheme

获取与切换当前主题（亮色 / 暗色 / 自动跟随系统）。

```typescript
import { useTheme } from '@/uni_modules/sinle-ui'
```

## 返回值

| 名称 | 类型 | 描述 |
| :--- | :--- | :--- |
| theme | `Ref<string>` | 当前主题，`'light'` 或 `'dark'` |
| isDark | `Ref<boolean>` | 是否为暗色模式 |
| isLight | `Ref<boolean>` | 是否为亮色模式 |
| isAuto | `Ref<boolean>` | 是否跟随系统自动切换 |
| setTheme | (val: string) => void | 设置主题，同时关闭自动跟随 |
| setAutoTheme | (val: boolean) => void | 设置是否跟随系统自动切换 |
| toggleTheme | () => void | 在当前主题间切换，同时关闭自动跟随 |

## 示例

### 最小接入

取自框架 demo 的设置页：用 `sn-switch` 控制"跟随系统"与"暗黑模式"两个开关。注意 `onDarkChange` 里先关掉自动跟随再设置主题——因为 `setTheme` 内部本就会关闭 `autoTheme`，这里的显式调用是为了让开关状态与主题同步。

```vue
<template>
	<sn-page title="设置" :show-back="true">
		<view class="setting-row" flatten>
			<sn-text font-size="$14" color="$text">跟随系统</sn-text>
			<sn-switch :model-value="isAuto" active-bg-color="$primary" @change="onAutoChange" />
		</view>
		<view class="setting-row" flatten>
			<sn-text font-size="$14" color="$text">暗黑模式</sn-text>
			<sn-switch :model-value="isDark" active-bg-color="$primary" @change="onDarkChange" />
		</view>
	</sn-page>
</template>

<script lang="ts" setup>
import { useTheme } from '@/uni_modules/sinle-ui'

const { isAuto, isDark, setTheme, setAutoTheme } = useTheme()

function onAutoChange(val: boolean): void {
	setAutoTheme(val)
}

function onDarkChange(val: boolean): void {
	if (val) {
		setAutoTheme(false)
		setTheme('dark')
	} else {
		setTheme('light')
	}
}
</script>
```

### 按主题切换自定义颜色

框架颜色经 `var(--sn-xxx)` 由 `sn-page` 注入，自动随主题切换。框架外的元素（如 demo 中的说明文字）需自行按 `isDark` 取值：

```typescript
const { isDark } = useTheme()

const nameColor = computed<string>(() => isDark.value ? '#CBD5E1' : '#334155')
const valueColor = computed<string>(() => isDark.value ? '#73a2ff' : '#4d82ff')
```

```vue
<sn-text font-size="$12" :color="nameColor" custom-style="flex:1;">{{ item.name }}</sn-text>
```

### 使用要点

- 返回值中 `theme` / `isDark` / `isLight` / `isAuto` 均为 `computed`，模板中自动解包；在 `script` 中需写 `.value`。
- `setTheme` 与 `toggleTheme` **都会关闭自动跟随**（`autoTheme` 置为 `false`），这是为了让手动选择生效；想恢复跟随系统必须显式调用 `setAutoTheme(true)`。
- 样式与模板统一用 `var(--sn-xxx)` 或 `$` 简写（`$primary` 等自动转 `var(--sn-primary)`）；`$snui.colors.xxx` 只用于需要实色的原生弹层（配合 `resolveColorValue`），不要在脚本里用它拼样式值。
- 颜色由 `sn-page` 根节点上的 `sn-theme-light` / `sn-theme-dark` 类提供（随应用主题切换），样式中的 `@media (prefers-color-scheme: light|dark)` 作为系统外观兜底（需 HBuilderX 5.25+ 蒸汽模式）。应用主题优先于系统外观，手动切换后不会被相反的浏览器/系统外观覆盖。
- 框架已监听应用/系统外观变化（App 端 `uni.onAppThemeChange`、Web 端 `uni.onHostThemeChange`）并回写 `theme`，无需自行监听。
- App 端建议在 `manifest.json` 配置 `app.defaultAppTheme: "auto"`，冷启动首帧即跟随系统。
- App 端需在 `pages.json` 的 `globalStyle` 引用 `theme.json` 中的 `navigationBarTextStyle`，使新页面从首帧就能按主题显示状态栏文字。切换主题时框架会调用 `syncStatusBarColor` 同步当前页面状态栏前景色（亮色为黑色，暗色为白色）；Android 6.0 以下不支持动态切换状态栏前景色。

# useStyle

获取当前风格（Style，应用皮肤）与切换风格。

```typescript
import { useStyle } from '@/uni_modules/sinle-ui'
```

## 返回值

| 名称 | 类型 | 描述 |
| :--- | :--- | :--- |
| style | Ref<`SnStyle`> | 当前完整风格对象 |
| styleId | `Ref<string>` | 当前风格 id |
| availableStyles | `Ref<string[]>` | 全部已注册的风格 id 列表 |
| setStyle | (id: string) => boolean | 切换风格，目标 id 存在时返回 `true` |

> 类型字段：SnStyle（见 https://sinleui.pages.dev/api/types/component#snstyle）


---

:::

## 示例

### 最小接入

取自框架 demo 的设置页：用 `sn-select` 切换风格。`availableStyles` 只有 id，中文名需自行映射；`styleId` 变化后需同步回选中索引。

```vue
<template>
	<sn-page title="设置" :show-back="true">
		<view class="setting-row" flatten>
			<sn-text font-size="$14" color="$text">风格</sn-text>
			<sn-select v-model="styleIdx" :data="styleOptions" width="132px" selected-mode="check"
				@change="onStyleChange" />
		</view>
	</sn-page>
</template>

<script lang="ts" setup>
import { useStyle } from '@/uni_modules/sinle-ui/index.ts'
import type { SnDataItem } from '@/uni_modules/sinle-ui/core/types/index.ts'

const { styleId, setStyle } = useStyle()

const styleOptions = computed<SnDataItem[]>(() => [
	{ id: 'default', text: '默认' },
	{ id: 'ink', text: '水墨' },
	{ id: 'chinese', text: '国风' },
	{ id: 'new-year', text: '新年' },
	{ id: 'morandi-green', text: '莫兰迪绿' },
	{ id: 'orange', text: '活力橙' }
])

const styleIdx = ref<number>(0)

function syncStyleIdx(): void {
	const list = styleOptions.value
	for (let i = 0; i < list.length; i++) {
		if (list[i].id == styleId.value) {
			styleIdx.value = i
			return
		}
	}
	styleIdx.value = 0
}

function onStyleChange(idx: number): void {
	const list = styleOptions.value
	if (idx >= 0 && idx < list.length) {
		const id = list[idx].id
		if (id != null) {
			setStyle(id)
		}
	}
}

onMounted((): void => {
	syncStyleIdx()
})

watch(styleId, (): void => {
	syncStyleIdx()
})
</script>
```

### 遍历全部已注册风格

`availableStyles`（返回 `Ref<string[]>`）可直接用于遍历：

```typescript
const { styleId, availableStyles, setStyle } = useStyle()

const ids = computed<string[]>(() => availableStyles.value)
```

```vue
<sn-cell
	v-for="item in ids"
	:key="item"
	:title="item"
	:value="item == styleId ? '使用中' : ''"
	@click="setStyle(item)"
/>
```

### 使用要点

- `setStyle(id)` 内部为 `switchStyle(id)`：目标 id 不存在时返回 `false` 并输出警告、保持原风格，可用于做失败提示。
- 框架内置 6 套风格：`default`、`ink`、`chinese`、`new-year`、`morandi-green`、`orange`。`availableStyles` 只返回 id 列表，展示中文名需自行维护映射（demo 中通过 i18n 键 `style.default` 等获取）。
- 切换风格时框架会**深拷贝**目标风格再替换当前风格，避免互相污染；修改也随之持久化到 storage。
- `style` 为完整 `SnStyle` 对象，切换后整体替换。不要解构它的字段，应在 `computed` 中访问 `style.value.xxx`。
- 若仅需微调颜色或乘数而不整套换肤，直接改 `$snui.setColor()` / `$snui.fontsizeFactor` 等属性即可，无需调用本 hook。

# useFactors

响应式读取五个全局尺寸乘数（修改 `$snui.*Factor` 后自动更新）。

```typescript
import { useFactors } from '@/uni_modules/sinle-ui'
```

## 返回值

| 名称 | 类型 | 描述 |
| :--- | :--- | :--- |
| marginFactor | `Ref<number>` | 外间距乘数 |
| paddingFactor | `Ref<number>` | 内间距乘数 |
| radiusFactor | `Ref<number>` | 圆角乘数 |
| fontsizeFactor | `Ref<number>` | 字号乘数 |
| aniTimeFactor | `Ref<number>` | 动画时长乘数 |

## 示例

### 最小接入

取自框架 demo 的设置页：用 5 个 `sn-slider` 调节各乘数。乘数需放大 10 倍取整后再交给 slider（步进为 1），显示时再还原为一位小数。

```vue
<template>
	<sn-page title="设置" :show-back="true">
		<view class="slider-block" flatten>
			<view class="slider-label-row" flatten>
				<sn-text font-size="$13" color="$text">字体大小</sn-text>
				<sn-text bold font-size="$13" color="$primary">{{ fontsizeFactorText }}×</sn-text>
			</view>
			<sn-slider :model-value="fontsizeFactorInt" :min="6" :max="16" :step="1"
				active-color="$primary" inactive-color="$line" @change="onFontsizeChange" />
		</view>
		<view class="slider-block" flatten>
			<view class="slider-label-row" flatten>
				<sn-text font-size="$13" color="$text">圆角</sn-text>
				<sn-text bold font-size="$13" color="$primary">{{ radiusFactorText }}×</sn-text>
			</view>
			<sn-slider :model-value="radiusFactorInt" :min="0" :max="20" :step="1"
				active-color="$primary" inactive-color="$line" @change="onRadiusChange" />
		</view>
	</sn-page>
</template>

<script lang="ts" setup>
import { $snui, useFactors } from '@/uni_modules/sinle-ui/index.ts'

const { marginFactor, paddingFactor, fontsizeFactor, radiusFactor, aniTimeFactor } = useFactors()

const fontsizeFactorInt = computed<number>(() => Math.round(fontsizeFactor.value * 10))
const radiusFactorInt = computed<number>(() => Math.round(radiusFactor.value * 10))

function formatFactor(val: number): string {
	const i = Math.round(val * 10)
	return (i / 10).toString()
}

const fontsizeFactorText = computed<string>(() => formatFactor(fontsizeFactor.value))
const radiusFactorText = computed<string>(() => formatFactor(radiusFactor.value))

function onFontsizeChange(idx: number): void {
	$snui.fontsizeFactor = idx / 10
}

function onRadiusChange(idx: number): void {
	$snui.radiusFactor = idx / 10
}
</script>
```

### 动画速度档位

`aniTimeFactor` 是连续值，设置页通常将其映射为几档离散速度：

```typescript
const aniTimeFactorLabels = computed<string[]>(() => [t('settings.aniOff'), '×0.5', '×1', '×1.5', '×2'])

const aniTimeFactorIdx = computed<number>(() => {
	const val = aniTimeFactor.value
	if (val <= 0) return 0
	if (val <= 0.5) return 1
	if (val <= 1) return 2
	if (val <= 1.5) return 3
	return 4
})

const aniTimeFactorLabel = computed<string>(() => aniTimeFactorLabels.value[aniTimeFactorIdx.value])

function onAniTimeFactorChange(idx: number): void {
	const values = [0, 0.5, 1, 1.5, 2]
	$snui.aniTimeFactor = values[idx]
}
```

### 使用要点

- 五个乘数均为 `computed<number>`，在 `script` 中必须写 `.value`；模板中自动解包。
- 本 hook 只负责**读取**。写入请直接赋值 `$snui.fontsizeFactor` 等属性，赋值后本 hook 的返回值会自动更新。
- 乘数对应关系：`fontsizeFactor` 字号、`radiusFactor` 圆角、`marginFactor` 外间距、`paddingFactor` 内间距、`aniTimeFactor` 动画时长乘数（`0` 关闭动画、`1` 标准、`2` 慢速）。
- 组件内部固定设计值应写成 `Math.round(14 * $snui.fontsizeFactor)` 形式（框架统一用 `Math.round` 取整）；用户通过 props 传入的尺寸值则交给 [useResolve](/api/hooks/use-resolve) 的 `$` 语法处理，两者不要混用。
- 修改乘数会写入当前风格对象并自动持久化，应用重启后保持。

# useHover

统一点击态（按下反馈）机制。组件的按下/抬起/过渡状态管理，替代旧版 `hover-class`。本 hook 为组件内部使用，也可用于自定义组件。

```typescript
import { useHover } from '@/uni_modules/sinle-ui'
```

## 参数

useHover(options: [UseHoverOptions](/api/types/api#usehoveroptions))，其中 `UseHoverOptions` 各字段为返回当前配置的**函数**：

| 字段 | 类型 | 描述 |
| :--- | :--- | :--- |
| enabled | () => boolean | 是否启用点击态（如禁用态返回 `false`） |
| startTime | () => number | 按下后进入点击态的延迟（ms） |
| stayTime | () => number | 抬起后点击态保留时长（ms） |
| transTime | () => number | 点击态过渡动画时长（ms） |
| normalTime | () => number | 常态过渡动画时长（ms） |

## 返回值

| 名称 | 类型 | 描述 |
| :--- | :--- | :--- |
| pressed | `Ref<boolean>` | 是否处于按下状态 |
| transitionDuration | `Ref<string>` | 当前过渡时长（如 `'150ms'`），绑定到节点 `transition-duration` |
| onTouchStart | (e: UniTouchEvent) => void | 绑定到节点 `@touchstart` |
| onTouchEnd | (e: UniTouchEvent) => void | 绑定到节点 `@touchend` |
| onTouchMove | (e: UniTouchEvent) => void | 绑定到节点 `@touchmove`，移动超过阈值自动取消点击态 |
| onTouchCancel | (e: UniTouchEvent) => void | 绑定到节点 `@touchcancel` |

## 示例

### 最小接入

将返回的事件处理器绑定到节点的触摸事件，根据 `pressed` 切换按下态样式；`transitionDuration` 绑定到节点 `transition-duration`（按下/抬起时自动在 `transTime` 与 `normalTime` 之间切换过渡时长）。

```vue
<template>
	<view
		class="demo-item"
		:style="itemStyle"
		@touchstart="hover.onTouchStart"
		@touchmove="hover.onTouchMove"
		@touchend="hover.onTouchEnd"
		@touchcancel="hover.onTouchCancel"
	>
		<text>{{ pressed ? '按住中' : '点击区域' }}</text>
	</view>
</template>

<script setup>
import { computed, ref } from 'vue'
import { useHover } from '@/uni_modules/sinle-ui'

const disabled = ref(false)

const hover = useHover({
	enabled: () => !disabled.value,
	startTime: () => 0,
	stayTime: () => 150,
	transTime: () => 150,
	normalTime: () => $snui.aniTimeShort
})

const pressed = hover.pressed

const itemStyle = computed(() => {
	return `transition-property: background-color, transform;
transition-duration: ${hover.transitionDuration.value};
background-color: ${pressed.value ? '#e8e8e8' : 'transparent'};
transform: ${pressed.value ? 'scale(0.97)' : 'scale(1)'};`
})
</script>
```

### 使用要点

- `enabled` 返回 `false` 时（如禁用态）按下态不生效，事件处理器仍可绑定，样式不受影响。
- `onTouchMove` 绑定后，手指移动超过阈值会自动取消按下态，适用于列表滚动等需要拦截滑动手势的场景。
- `pressed` 为响应式引用（`Ref<boolean>`），模板中使用时自动解包；绑定事件直接传 `hover.onTouchStart` 等即可，无需包裹箭头函数。
- `transitionDuration` 值为 `'150ms'` 形式的字符串，动态作用于 `transition-duration`，实现按下时快进、抬起时回弹过渡的效果。

# useResolve

`$` 前缀动态尺寸解析与颜色简写解析。

2.0 起 Resolve 从 Utils 工具库迁移为钩子：组件收到尺寸类、颜色类 props 后，通过 `useResolve()` 获取解析函数进行处理。`$` 是唯一的"动态"标记——带 `$` 的值乘以对应全局乘数，不带 `$` 的值按固定值处理（纯数字字符串自动补单位，其余原样返回）。

解析结果分两种形态：`resolveColor` 输出 `var(--sn-xxx)` CSS 变量，适用于页面内组件样式（依赖 `sn-page` 注入变量、随主题实时切换）；`resolveColorValue` 输出当前主题的**具体色值**，适用于原生弹层、原生元素等**脱离页面 CSS 变量作用域**的场景（如 `snu.showToast`、`snu.setPermTipsStyle`）。

```typescript
import { useResolve } from '@/uni_modules/sinle-ui'
```

## 获取方式

```typescript
const resolver = useResolve()
```

## 返回值

| 名称 | 类型 | 描述 |
| :--- | :--- | :--- |
| resolveColor | (val: string, defaultVal?: string) => string | 颜色解析：`$xxx` 自动转 `var(--sn-xxx)` CSS 变量，非 `$` 开头（如 `var(--sn-primary-text-dark)`、`#fff`、`rgba(...)`）原样返回；`val` 为空时使用 `defaultVal` |
| resolveColorValue | (val: string, defaultVal?: string) => string | 颜色解析（具体值）：`$xxx` 转为当前主题下该颜色的**实际色值**（如 `#3b82f6`），`var(--sn-xxx)` 同样转实际色值，非 `$`/非 `var(--sn-*)` 值原样返回；`val` 为空时使用 `defaultVal`，`$` 名称不存在时回退 `defaultVal` |
| resolveSize | (val: string \| number, type: `SnResolveType`, defaultVal?: string \| number) => string | 尺寸解析：`$16` 乘以对应乘数后加单位（`px` / `ms`）；无 `$` 的纯数字字符串按固定值补单位（`'10'` → `10px`），`'16px'`、`'50%'` 等其他无 `$` 值原样返回；支持空格分隔的多段值（如 `'$16px $20px'`） |
| resolveSizeNum | (val: string \| number, type: `SnResolveType`, defaultVal?: string \| number) => number | 同 `resolveSize`，但返回四舍五入后的数值；无 `$` 值只转数值，不做乘数处理 |

> 类型字段：SnResolveType（见 https://sinleui.pages.dev/api/types/component#snresolvetype）


## 解析规则

| 输入示例 | type | 输出（fontsizeFactor=1 时） | 说明 |
| :--- | :--- | :--- | :--- |
| `'$16'` | `'font'` | `16px` | 16 × 字号乘数 |
| `'16px'` | `'font'` | `16px` | 无 `$` 且带单位，原样返回 |
| `'16'` | `'font'` | `16px` | 无 `$` 的纯数字字符串，按固定值补单位，不乘乘数 |
| `16` | `'font'` | `16px` | 数字，按固定值补单位 |
| `'$250'` | `'aniTime'` | `250ms` | 动画时长单位为 ms |
| `'250'` | `'aniTime'` | `250ms` | 无 `$` 纯数字按固定值补 ms |
| `'$16px $20px'` | `'padding'` | `16px 20px` | 多段值逐段解析 |
| `'10 20'` | `'padding'` | `10px 20px` | 多段纯数字逐段补单位 |
| `'$primaryTextDark'` | —（resolveColor） | `var(--sn-primary-text-dark)` | 颜色简写 |
| `'$primaryTextDark'` | —（resolveColorValue） | `#ffffff` 等具体色值 | 颜色具体值（原生弹层用） |

## 示例

### 直接观察解析结果

取自框架 demo 的 API 页，把各输入值的解析结果直接列出来对照：

```typescript
import { useResolve } from '@/uni_modules/sinle-ui'

const resolver = useResolve()

type DemoItem = {
	name: string
	value: string
}

const resolveItems = computed<DemoItem[]>(() => {
	return [
		{ name: "resolveSize('$16', 'font')", value: resolver.resolveSize('$16', 'font') },
		{ name: "resolveSize('16', 'font')", value: resolver.resolveSize('16', 'font') },
		{ name: "resolveSize('16px', 'font')", value: resolver.resolveSize('16px', 'font') },
		{ name: "resolveSize('10', 'radius')", value: resolver.resolveSize('10', 'radius') },
		{ name: "resolveSize(16, 'font')", value: resolver.resolveSize(16, 'font') },
		{ name: "resolveSizeNum('$16', 'font')", value: resolver.resolveSizeNum('$16', 'font').toString() },
		{ name: "resolveSizeNum(16, 'font')", value: resolver.resolveSizeNum(16, 'font').toString() },
		{ name: "resolveColor('$primaryTextDark')", value: resolver.resolveColor('$primaryTextDark') },
		{ name: "resolveColorValue('$primaryTextDark')", value: resolver.resolveColorValue('$primaryTextDark') },
		{ name: "resolveColor('#ff0000')", value: resolver.resolveColor('#ff0000') }
	]
})
```

```vue
<view v-for="(item, i) in resolveItems" :key="'v' + i" flatten>
	<sn-text font-size="$12" :color="nameColor" custom-style="flex:1;">{{ item.name }}</sn-text>
	<sn-text font-size="$12" :color="valueColor" custom-style="flex:1;text-align:right;">{{ item.value }}</sn-text>
</view>
```

### 组件内解析 props

框架组件（如 `sn-alert`）的标准写法：props 有值时解析用户值，为空时回退到按乘数计算的默认值。

```typescript
const resolver = useResolve()

const textSizeC = computed<string>(() => {
	if (props.textSize != null && props.textSize != '') {
		return resolver.resolveSize(props.textSize, 'font')
	}
	return `${Math.round(14 * $snui.fontsizeFactor)}px`
})

const borderRadiusC = computed<string>(() => {
	if (props.borderRadius != null && props.borderRadius != '') {
		return resolver.resolveSize(props.borderRadius, 'radius')
	}
	return `${Math.round(8 * $snui.radiusFactor)}px`
})

const iconSizeNum = computed<number>(() => {
	if (props.iconSize != null && props.iconSize != '') {
		return resolver.resolveSizeNum(props.iconSize, 'font')
	}
	return Math.round(16 * $snui.fontsizeFactor)
})
```

颜色类 props 通常再包一层回退逻辑：

```typescript
function resolveColor(propVal: string, fallback: string): string {
	if (propVal != '') {
		return resolver.resolveColor(propVal)
	}
	return fallback
}

const bgColorC = computed<string>(() => {
	return resolveColor(props.bgColor, getThemeColor(typeC.value, isDark.value ? '' : 'Light'))
})
```

### 使用要点

- 第二个参数 `type` 必填，取 `'font'` / `'radius'` / `'margin'` / `'padding'` / `'aniTime'`，决定 `$` 值乘以哪个乘数以及输出单位（`aniTime` 为 `ms`，其余为 `px`）。
- `resolveSize` 返回带单位字符串，可直接拼进 style；`resolveSizeNum` 返回四舍五入后的数值，用于需要在 JS 中继续计算的场景（如图标尺寸）。
- 带 `$` 的值只支持纯数字 + `px`/无单位，且不支持计算表达式；解析失败时原样返回输入值。
- 无 `$` 的值按固定值处理：纯数字字符串补单位（`'10'` → `10px`，`aniTime` 类型的 `'250'` → `250ms`），不乘任何乘数；`'10px'`、`'50%'`、`'auto'` 等非纯数字值原样返回。
- 字符串含空格时按空格分段逐段解析，适用于 `'$16px $20px'` 这类简写值。
- `resolveColor` 仅处理 `$` 前缀（转 `var(--sn-xxx)`，下划线/驼峰会转为 kebab-case），`#fff`、`rgba(...)`、`var(...)` 等原样返回；`val` 为空时返回 `defaultVal`。
- `resolveColorValue` 与 `resolveColor` 的入参规则一致，但输出**当前主题具体色值**：页面内组件样式请用 `resolveColor`（随主题实时切换），原生弹层 / 原生元素的颜色请用 `resolveColorValue`（原生层无法解析 CSS 变量）。
- 解析结果依赖全局乘数，必须放在 `computed` 中求值，否则乘数变化后不会更新。

# useHistory

增量操作日志式的撤销/重做存储引擎。

`useHistory` 把「一步操作」抽象为一条极轻量的记录 ``SnHistoryStep``（`kind` / `ref` / `weight` 三个数字），只保存这一步在宿主文档中的定位与权重，**不保存文档快照、不复制宿主载荷**。时间线存放在环形缓冲中并按游标推进，撤销与重做只移动游标，定位复杂度为 O(1)；超出最大步数或最大权重预算时从最旧一步开始淘汰并立即释放其权重，不做数组整体移位。框架内 `sn-sketchpad`、`sn-signature` 的撤销/重做即由本引擎驱动。

它解决的是画板类场景里最常见的两个存储问题：一是把整幅画布或整个文档快照进历史导致内存随步数线性膨胀，二是把历史日志放进框架响应式状态导致每次读写都走代理陷阱。本引擎的时间线是调用方作用域内的普通数据，只把 `canUndo` / `canRedo` / `stats` 这类标量以 `computed` 暴露给视图层。

```typescript
import { useHistory } from '@/uni_modules/sinle-ui'
```

## 获取方式

```typescript
import { useHistory } from '@/uni_modules/sinle-ui'

const history = useHistory({
	maxSteps: () => 20,
	maxWeight: () => 120000
})

history.push({ kind: 0, ref: 0, weight: 12 } as SnHistoryStep)
history.undo()
```

## 返回值

| 名称 | 类型 | 描述 |
| :--- | :--- | :--- |
| stats | ComputedRef<`SnHistoryStats`> | 当前时间线统计：游标位置、总步数、累计权重、已淘汰步数 |
| canUndo | ComputedRef\<boolean\> | 是否可撤销 |
| canRedo | ComputedRef\<boolean\> | 是否可重做 |
| push | (step: `SnHistoryStep`) => void | 记录一步：截断重做侧后追加，超限自动淘汰最旧步 |
| undo | () => `SnHistoryStep` \| null | 回退一步并返回该步；无可回退时返回 null |
| redo | () => `SnHistoryStep` \| null | 前进一步并返回该步；无可前进时返回 null |
| peekUndo | () => `SnHistoryStep` \| null | 读取待撤销的一步但不移动游标 |
| peekRedo | () => `SnHistoryStep` \| null | 读取待重做的一步但不移动游标 |
| trim | () => void | 按当前的 `maxSteps` / `maxWeight` 立即裁剪时间线，用于上限被调小后即时生效 |
| reset | () => void | 清空时间线，游标、权重与淘汰计数一并归零 |

> 类型字段：UseHistoryOptions（见 https://sinleui.pages.dev/api/types/component#usehistoryoptions）

> 类型字段：SnHistoryStep（见 https://sinleui.pages.dev/api/types/component#snhistorystep）

> 类型字段：SnHistoryStats（见 https://sinleui.pages.dev/api/types/component#snhistorystats）


## 存储模型

时间线用「环形缓冲 + 游标」表达，而不是「撤销栈 + 重做栈」两个数组：

| 机制 | 做法 | 相对朴素实现的收益 |
| :--- | :--- | :--- |
| 增量日志 | 每条记录只存 `kind` / `ref` / `weight`，载荷由调用方自持 | 历史内存与「变更量」成正比，而不是与「文档总量」成正比 |
| 游标 | `undo` / `redo` 只移动游标，记录原地不动 | 无需在两个栈之间搬运对象，也无需按下标查找目标 |
| 环形缓冲 | 淘汰只推进头部偏移，累积到阈值才做一次压缩 | 出栈是 O(1)，没有 `splice(0, n)` 的整体移位 |
| 权重预算 | 除步数外再按 `weight` 累计值淘汰 | 内存上限由「字节/点数」保证，而不是由「步数」间接保证 |
| 视窗模型 | 框架内画板用「只追加池 + 可见数量」表达文档 | 撤销/重做不搬移笔画对象，重做不再需要额外的重做栈 |

三条值得注意的语义：

- **截断时机**：只有 `push`（产生新的已提交步骤）会截断重做侧。`reset` 会清空一切，除此之外没有任何操作会隐式丢弃重做。
- **淘汰语义**：被淘汰的最旧步骤仍在宿主文档中生效，只是无法再撤销；`stats.evicted` 可用于观测是否发生过淘汰。
- **游标与淘汰的关系**：游标小于总步数（即存在可重做步骤）时发生淘汰，游标会同步回退，保证 `cursor` 始终等于「已应用步数」。

## 示例

### 用操作日志驱动画板的撤销/重做

取自框架内 `sn-sketchpad` 的用法：文档是「只追加的笔画池 + 可见数量」，每一步记录新笔画在池中的下标。

```typescript
import { useHistory } from '@/uni_modules/sinle-ui'
import type { SnHistoryStep } from '@/uni_modules/sinle-ui'

const STEP_ADD = 0

let strokes: Stroke[] = []
let visibleCount = 0

const history = useHistory({
	maxSteps: () => 20,
	maxWeight: () => 120000
})

function commitStroke(s: Stroke): void {
	if (visibleCount < strokes.length) {
		strokes.splice(visibleCount)
	}
	strokes.push(s)
	visibleCount = strokes.length
	const step: SnHistoryStep = { kind: STEP_ADD, ref: visibleCount - 1, weight: s.points.length }
	history.push(step)
}

function undo(): void {
	const step = history.undo()
	if (step == null) {
		return
	}
	visibleCount = step.ref
	repaintStrokes(step.ref)
}

function redo(): void {
	const step = history.redo()
	if (step == null) {
		return
	}
	visibleCount = step.ref + 1
	drawStroke(strokes[step.ref])
}
```

### 只读派生状态

`canUndo` / `canRedo` / `stats` 都是 `computed`，可直接绑定到按钮的禁用状态；不要在 `push` 之后手动维护布尔量。

```vue
<sn-button :disabled="!history.canUndo" @click="onUndo">{{ history.stats.total }}</sn-button>
```

## 使用要点

- `maxSteps` 与 `maxWeight` 都是读取函数而不是值：调用方传入 props 派生值后，props 变化会即时生效，无需重建 hook。
- 淘汰只在 `push` 时进行；若上限在运行期被调小并希望立刻回收多余步骤，调用一次 `trim`。
- `push` 传入的 `weight` 由调用方估算，建议与「这一笔实际占用的内存或重放成本」同量级；权重恒定时等价于只按步数限制。
- `undo` / `redo` 返回被移动的那一步，调用方据此执行最小重绘；返回 `null` 表示游标已到边界。
- `peekUndo` / `peekRedo` 只读不移动，适合在重绘前预判下一步的目标，例如判断能否用脏矩形局部重绘。
- 时间线本身不是响应式的：不要在模板里直接读取它，请通过 `stats` / `canUndo` / `canRedo` 取值。
- 引擎不持有计时器与监听器，无需在 `onUnmounted` 中清理；但调用方应在组件卸载时丢弃自己持有的文档池。

# useTabbarHeights

读取当前 `sn-page` 作用域内的 Tabbar 实际高度，用于在子页面滚动内容末尾放置占位，使内容能经过固定导航栏背后呈现毛玻璃效果。

```typescript
import { useTabbarHeights } from '@/uni_modules/sinle-ui'
const { tabbarHeights } = useTabbarHeights()
```

## 返回值

| 名称 | 类型 | 描述 |
| :--- | :--- | :--- |
| tabbarHeights | ComputedRef\<Record\<string, number\>\> | 当前 sn-page 的高度字典，以 tabbarKey 为键、实际高度（px 数值）为值；未登记时读取为 null 或 undefined，请使用 ?? 0；只读，不直接修改 |
| setHeight | (key: string, height: number) => void | 框架内部登记或更新当前组件拥有的高度记录，非有限值按 0 处理，四舍五入且不小于 0；同作用域重复 key 不覆盖其他组件记录 |
| removeHeight | (key: string) => void | 框架内部移除当前组件拥有的记录，不删除其他组件拥有的同名记录 |

## 使用方式

固定导航栏放在 `sn-page` 内，显式指定 `tabbar-key`：

```vue
<sn-page fill-content>
	<home-content />
	<sn-tabbar tabbar-key="home" :data="data" :blur="true" />
</sn-page>
```

`home-content` 等后代组件在自身 `<script setup>` 调用钩子，占位必须位于滚动容器内部、内容末尾：

```vue
<template>
	<scroll-view direction="vertical" class="content-scroll">
		<view class="content-body"><slot /></view>
		<view :style="placeholderStyle" flatten />
	</scroll-view>
</template>

<script lang="ts" setup>
import { useTabbarHeights } from '@/uni_modules/sinle-ui'
const { tabbarHeights } = useTabbarHeights()
const placeholderStyle = computed<string>(() => {
	const height = (tabbarHeights.value['home'] as number | null) ?? 0
	return `height: ${height}px; flex-shrink: 0;`
})
</script>
```

若 Tabbar 通过 `bottom` 设置安全距离，或配置了底部外边距，占位高度需额外加上这些距离。登记高度仅是主体的渲染高度，不自动包含它们。

## 隔离与生命周期

- `frameStore` 是框架全局单例；每个 `sn-page` 在 setup 中提供独立的 `tabbarHeights:<实例 uid>` 存储键，不以路由或当前页面栈顶作为作用域。
- 存储内容为纯数值记录及组件归属，不存放 Vue ref 或组件实例，不持久化到 Storage。
- `tabbarHeights` 是按字符串 key 访问的高度字典，不是按数字索引排序的数组。
- 不同 `sn-page` 可以使用相同 `tabbarKey`，包括同一路由的多个实例和嵌套 `sn-page`；后代读取最近的 `sn-page` 作用域。
- 同一作用域内多个固定 Tabbar 必须使用不同 key。重复 key 发出框架日志，后登记的组件不覆盖前一个组件，也不能误删其记录。
- Tabbar 首次登记为 0，渲染测量后更新；尺寸变化、页面再次显示会重新测量。`tabbarKey` 变化或 `fixed=false` 会移除旧记录。
- 登记组件卸载时只清理自己拥有的记录；`sn-page` 卸载时清理整个页面作用域。
- `tabbarKey=''` 不参与登记；`__proto__`、`constructor`、`prototype` 不能用作 key。
- 钩子必须在 `sn-page` 后代组件 setup 中调用。包含 `<sn-page>` 的页面自身 setup 不是其后代，不能从那里读取该组件提供的作用域；没有作用域时读取为空，尝试登记会输出日志。

## 兼容能力

`v-model:height` 与 `heightchange` 保留，仍可用于已有布局；跨子页面共享高度优先使用本钩子。业务只读取 `tabbarHeights`，`setHeight` / `removeHeight` 主要由 `sn-tabbar` 内部调用。

# useI18n

组件语言（插件 i18n）响应式读取。

::: warning 仅供框架内部使用
`useI18n` 是框架给自身组件（如 sn-calendar、sn-modal、sn-search 等内置文案翻译）使用的 hook。**开发者不应调用它返回的 `t`** 翻译自己的文案——框架内置消息表不包含业务键，也无法扩展。开发者的文案翻译请使用宿主项目自己的 i18n 方案（如 `vue-i18n`）。

开发者使用本 hook 只需读取 `locale`（响应式获取当前组件语言），用于渲染语言选择器、同步等场景。
:::

```typescript
import { useI18n } from '@/uni_modules/sinle-ui'

const { locale } = useI18n()
```

| 返回 | 类型 | 说明 |
| :--- | :--- | :--- |
| t | (key: string, params?: Record\<string, string \| number\>) => string | 框架内部翻译函数，仅供框架组件翻译内置文案使用，**开发者不得调用** |
| locale | `ComputedRef<string>` | 当前组件语言（BCP 47 标签），响应式 |

## 说明

- `useI18n` 面向框架内部：框架组件用它翻译内置文案（如星期、月份、按钮文案等），开发者无需也不应调用 `t`。
- 开发者读取的 `locale` 是响应式的，语言切换后自动更新。
- 切换语言请使用 `$snui.locale`（赋值即切换并持久化），详见[框架国际化](/get-started/framework#国际化-i18n)。

## 支持的语言

| 语言 | 标签 |
| :--- | :--- |
| 简体中文 | `zh-Hans` |
| 英语 | `en` |
| 法语 | `fr` |
| 俄语 | `ru` |
| 日语 | `ja` |
| 繁体中文 | `zh-Hant` |
| 韩语 | `ko` |
| 西班牙语 | `es` |
| 德语 | `de` |
| 意大利语 | `it` |
| 葡萄牙语 | `pt` |

完整列表见 `SUPPORTED_LOCALES`（含本地化名称，可直接渲染为语言选择器）。

## 示例

### 读取当前语言

读取当前组件语言（响应式），用于展示或同步到语言选择器：

```vue
<template>
	<sn-page :title="pageTitle" :show-back="true">
		<sn-text font-size="$14" color="$text">{{ currentLocale }}</sn-text>
	</sn-page>
</template>

<script lang="ts" setup>
import { useI18n } from '@/uni_modules/sinle-ui'

const { locale } = useI18n()

const currentLocale = computed<string>(() => locale.value)
</script>
```

### 语言切换（配合宿主项目自己的 i18n）

框架 demo 的设置页同时维护了两套 i18n：插件语言经 `$snui.locale` 切换，宿主项目语言经 `vue-i18n` 的 `locale` 切换。二者相互独立，需分别设置。

```typescript
import { useI18n } from 'vue-i18n'
import { $snui } from '@/uni_modules/sinle-ui/index.ts'

const { t, locale: appLocale } = useI18n()

let appLocaleIdx = ref<number>(0)

function onAppLocaleChange(idx: number): void {
	if (idx >= 0 && idx < appLocaleOptions.length) {
		const id = appLocaleOptions[idx].id
		if (id != null) {
			appLocale.value = id
			$snui.locale = id
		}
	}
}
```

### 渲染语言选择器

用 `SUPPORTED_LOCALES` 生成语言列表，套进 `sn-select` 的 `data`。注意 `sn-select` 的 `v-model` 绑定的是索引，切换后需把 `locale` 变化同步回索引：

```typescript
import { $snui, SUPPORTED_LOCALES } from '@/uni_modules/sinle-ui'

const appLocaleOptions = ref<SnDataItem[]>(SUPPORTED_LOCALES.map((item) => {
	return { id: item.code, text: item.name } as SnDataItem
}))
```

```vue
<sn-select v-model="appLocaleIdx" :data="appLocaleOptions" width="132px" selected-mode="check"
	@change="onAppLocaleChange" />
```

### 使用要点

- `locale` 为只读 `computed`；切换语言请用 `$snui.locale = 'en'`（赋值即切换并持久化，不支持的语言仅输出警告并保持原值）。
- `settings.uvue` 中通过 `watch(appLocale)` 把语言变化同步回 `sn-select` 的选中索引，避免手动切换后下拉框显示不同步。
- 插件 i18n 与宿主项目的 vue-i18n 相互独立，二者语言不会自动同步；如需一致，需在业务层分别设置。
- 语言切换后自动持久化到 `current_locale`，应用重启时恢复。

# useExternalStyle

外部样式透传转字符串。将组件接收的 `SnStyleValue` 外部样式（`customStyle`、`{语义}Style` 等）统一转为样式字符串。为内部使用，亦可复用。

从对应源文件导入：

```typescript
import { useExternalStyle } from '@/uni_modules/sinle-ui/core/private/use-external-style.ts'
```

## 参数与返回值

`useExternalStyle(source: () => SnStyleValue | null)` 返回 `Ref<string>`，即转换后的 `key:value;` 拼接字符串。

- 参数 `source` 为返回透传样式的函数（通常为 `() => props.customStyle`），保证透传值变化时自动重新转换。
- 转换规则：字符串原样返回（判空后）；样式对象逐字段转为 kebab-case 的 `key:value;` 片段并拼接，`null` 值字段跳过。

另提供独立工具函数 `externalStyleToText(style: SnStyleValue | null): string`，即上述转换的非响应式版本。

## 示例

### 最小接入

框架组件（如 `sn-alert`）的标准写法：每个 externalStyle 类 prop 各调用一次，得到可直接绑定的样式字符串。

```typescript
import { useExternalStyle } from '../../core/private/use-external-style.ts'

const customStyleText = useExternalStyle((): SnStyleValue => props.customStyle)
const textStyleText = useExternalStyle((): SnStyleValue => props.textStyle)
const iconStyleText = useExternalStyle((): SnStyleValue => props.iconStyle)
```

```vue
<view class="sn-alert" :class="customClass" :style="customStyleText">
	<text class="sn-alert-text" :class="textClass" :style="`${textStyleText}${textStyleC}`">{{ text }}</text>
</view>
```

### 与内部样式合并

透传结果作为后置覆盖与组件默认样式拼接，用户传入的同名字段优先级更高（后写的覆盖先写的）：

```typescript
const customStyleText = useExternalStyle((): SnStyleValue => props.customStyle)

const rootStyleC = computed<string>(() => {
	return `padding-top:${Math.round(8 * $snui.paddingFactor)}px;
padding-bottom:${Math.round(8 * $snui.paddingFactor)}px;
${customStyleText.value}`
})
```

### 点击态样式

`sn-button` 中按下时才应用用户传入的 `hoverStyle`：

```typescript
const hoverStyleText = computed<string>(() => {
	if (!pressed.value || !hasHoverStyle.value) return ''
	return externalStyleToText(props.hoverStyle)
})
```

### 使用要点

- 参数必须写成**返回 props 的函数**（如 `() => props.customStyle`）而非直接传值，否则透传样式变化时不会重新转换。
- 仅适用于 externalStyle 类透穿样式（`customStyle`、`textStyle`、`iconStyle` 等）；组件自身内部样式应直接用 `computed` 构建 Map 或字符串，不要绕经本 hook。
- 转换规则：字符串判空后原样返回；样式对象逐字段按**小驼峰转 kebab-case** 拼接为 `key:value;` 片段，`null` 值字段跳过。因此值需自带单位（如 `16px` 而非 `16`）。
- 非响应式场景可直接用 `externalStyleToText(style)`，无需在 `setup` 中调用 hook。
- 内部实现按平台分支：App 端经 `toMap()` 遍历，非 App 端用 `Object.keys`；写组件时无需关心该差异。
- 不要把它用于 `Map` 类型的值——组件对外的 `customStyle` / `{语义}Style` 只接受 `SnStyleValue`。

# useBacktop

滚动容器与返回顶部联动机制。`sn-scroll-view` / `sn-list-view` / `sn-waterflow` / `sn-page` 等滚动容器复用此 hook，通过 provide/inject 与 `sn-backtop` 联动。

从对应源文件导入：

```typescript
import { useBacktop } from '@/uni_modules/sinle-ui/core/private/use-backtop.ts'
```

## 返回值

| 名称 | 类型 | 描述 |
| :--- | :--- | :--- |
| scrollTop | `Ref<number>` | 当前纵向滚动距离（px） |
| registerBacktop | (update: (scrollTop: number) => void) => void | 注册滚动更新回调（`sn-backtop` 显式 target 绑定时调用） |
| notifyBacktop | (top: number) => void | 容器在 scroll 事件中调用，同步 `scrollTop` 并通知全部已注册回调 |

## 工作机制

- 滚动容器在 scroll 事件中调用 `notifyBacktop(top)`：既更新响应式 `scrollTop`，也通知所有已注册回调。
- 自动绑定时 `sn-backtop` 经 `inject` 取容器 provide 的 `'snBacktopScrollTop'`（响应式滚动位置）并 `watch` 它决定显隐，回顶则经 `'snBacktopScrollTo'` 调用容器的滚动方法；该路径规避了 App 端 `$callMethod` 传函数回调的兼容问题。
- 显式 `target` 绑定时（或 provide 链断开时）`sn-backtop` 调用容器的 `registerBacktop(setScrollTop)` 注册回调，容器在后续 scroll 中经 `notifyBacktop` 逐个通知。
- 容器未传 `target` 时会自动查找：先同级、后父级，识别 `sn-scroll-view` / `sn-list-view` / `sn-waterflow` / `sn-page`。

## 示例

### 滚动容器接入

`sn-page` 是框架中最简的接入范例：`onScroll` 里通知滚动位置，再经 provide 暴露给 `sn-backtop`。

```typescript
import { useBacktop } from '../../core/private/use-backtop.ts'

const backtop = useBacktop()

function onScroll(e: UniScrollEvent): void {
	emit('scroll', e)
	backtop.notifyBacktop(e.detail.scrollTop)
}

provide('snBacktopScrollTop', backtop.scrollTop)
provide('snBacktopScrollTo', (top: number, left: number): void => {
	scrollTo(top, left)
})
```

### 组件化滚动容器（推荐）

`sn-scroll-view` / `sn-list-view` / `sn-waterflow` 的完整做法：既 provide 响应式滚动位置，又把 `registerBacktop` 通过 `defineExpose` 暴露出去，兼容 `sn-backtop` 的 `target` 显式绑定。

```typescript
const backtopCtx = useBacktop()

provide('snBacktopScrollTop', backtopCtx.scrollTop)
provide('snBacktopScrollTo', (top: number, left: number): void => {
	scrollTo(top, left)
})

function onScroll(e: UniScrollEvent): void {
	emit('scroll', e)
	backtopCtx.notifyBacktop(e.detail.scrollTop)
}

defineExpose({
	scrollTo,
	registerBacktop: backtopCtx.registerBacktop,
	startRefresh,
	stopRefresh
})
```

### 显式 target 绑定

当 `sn-backtop` 与容器不构成 provide/inject 链时（如跨层级），它会调用容器的 `registerBacktop` 注册回调。容器侧只需保证该方法已通过 `defineExpose` 暴露：

```vue
<sn-scroll-view ref="scrollRef" class="scroll-box">
	<sn-backtop target="scrollRef"></sn-backtop>
</sn-scroll-view>
```

### 使用要点

- 每次滚动必须调用 `notifyBacktop`，它同时负责更新 `scrollTop` 与通知全部已注册回调；只更新其中一项会导致按钮显隐或回顶位置不同步。
- provide 的键为 `'snBacktopScrollTop'`（传 `backtop.scrollTop`，即 `Ref<number>`）与 `'snBacktopScrollTo'`（传 `(top, left) => void` 的回顶方法），`sn-backtop` 端以 `inject` 取用。
- `registerBacktop` 需通过 `defineExpose` 暴露，`sn-backtop` 内部以 `$callMethod('registerBacktop', ...)` 调用；这也是它比 provide 响应式位置更"兜底"的一条路径。
- 自动查找顺序为「先同级、后父级」；`target` 可传父作用域中的 ref 名，或元素 id（Web 端也支持选择器与原生 scroll 监听）。
- 框架已在 `sn-scroll-view` / `sn-list-view` / `sn-waterflow` / `sn-page` 中内置该 hook。日常使用直接组合这些容器与 `sn-backtop` 即可，**仅在开发自定义滚动容器时**才需要自行接入。
- `scrollTop` 为 `Ref<number>`，除供 `sn-backtop` 判断显隐外，也可在容器外部用于吸顶导航、滚动进度条等联动。

# 类型

SinleUI 的全部类型（含扩展组件类型）均统一从 `@/uni_modules/sinle-ui` 导出，使用时从插件入口导入即可，例如：

```typescript
import { SnColorBase, SnStyle, SnDataItem } from '@/uni_modules/sinle-ui'
```

类型分为两类展示：

- [API 类型](/api/types/api)：组件与 API 公用、或仅 API 使用的框架级类型（颜色集、风格、手势事件、全局弹窗配置、权限、解析类型等）。
- [组件类型](/api/types/component)：组件专属类型（如 `SnCalendarValue`、`SnTreeData`、`SnFormItemRule`、`AgreementLinkDetail` 等）。

`UniError` / `SourceError` 等错误对象为 uni-app x 运行时内置全局对象，无需导入，详见[错误与日志](/api/error/error)。

本页与[组件类型](/api/types/component)覆盖框架内**全部**类型定义：既包括供开发者使用的公开类型，也包括仅框架内部使用的类型（如分组组件的 group config、子组件内部注入与回传的类型）。内部类型同样完整列出字段与类型，并在各自章节以「内部使用」标记说明其用途，便于理解组件行为与排查问题——但业务侧**不应**依赖这些内部类型，其字段可能随版本调整。

# API 类型

组件与 API 公用、或仅 API 使用的框架级类型。全部类型从 `@/uni_modules/sinle-ui` 导入：

```typescript
import { SnColorBase, SnStyle, SnDataItem } from '@/uni_modules/sinle-ui'
```

> 组件专属类型（日历、树、级联、消息通知、媒体等）见[组件类型](/api/types/component)。本页类型按字母顺序排列。

> [!TIP] 提示
>
> 其中 `SnRequestSystemPermissionOptions` / `SnRequestMediaPermissionOptions` 来自 `@/uni_modules/sinle-api`，经 `sinle-ui` 重导出。

---

# SN_DEFAULT_STYLE_ID

```typescript
const SN_DEFAULT_STYLE_ID = 'default'
```

默认风格 id 常量。

---

# SnColorBase

`$snui.colors` 的类型。一个主题下的**全部语义化颜色集合**，字段分为特殊色与功能色两类，颜色随 `sn-page` 注入的 `--sn-*` CSS 变量自动切换主题。

> [!TIP] 提示
>
> 后缀带 `Dark` 的是比原色更深的颜色，并非暗黑主题专属；带 `Light` 的是更浅的颜色。暗黑主题与亮色主题分别拥有独立的 `SnColorBase` 对象。

### 特殊色

| 字段 | 类型 | 描述 |
| :--- | :--- | :--- |
| transparent | String | 透明色（非 CSS 的 `transparent`，变化时不会闪黑） |
| page | String | 页面背景色 |
| front | String | 前景色，一般用作块状组件背景色 |
| dark | String | 亮色模式为黑色，暗色模式为白色 |
| light | String | 亮色模式为白色，暗色模式为黑色 |
| disabled | String | 禁用状态颜色 |
| disabledText | String | 禁用状态文字颜色 |
| disabledDark | String | 更深的禁用背景色 |
| disabledDarkText | String | 更深的禁用文字颜色 |
| line | String | 线条颜色 |
| lineDark | String | 更深的线条颜色 |
| lineText | String | 线条文字颜色 |
| title | String | 标题颜色 |
| text | String | 文本颜色 |
| textLight | String | 更浅的文本颜色 |
| toast | String | 轻提示背景色 |
| shadow | String | 阴影颜色（2.0 新增） |

### 功能色（primary/info/success/error/warning 五组同构）

每种功能色包含 9 个字段（以 `primary` 为例，其余功能色将 `primary` 替换为 `info` / `success` / `error` / `warning`）：

| 字段 | 类型 | 描述 |
| :--- | :--- | :--- |
| primary | String | 主题色（原色） |
| primaryActive | String | 激活态 |
| primaryText | String | 主题色背景上的文字前景色 |
| primaryLight | String | 更浅的主色 |
| primaryLightActive | String | 激活态更浅主色 |
| primaryLightText | String | 更浅主色背景上的前景色 |
| primaryDark | String | 更深的主题色 |
| primaryDarkActive | String | 激活态更深的主题色 |
| primaryDarkText | String | 更深的主题色背景上的前景色 |

---

# SnColorBases

一套风格中亮/暗两套颜色集的容器。

| 字段 | 类型 | 描述 |
| :--- | :--- | :--- |
| light | [SnColorBase](#sncolorbase) | 亮色主题颜色集 |
| dark | [SnColorBase](#sncolorbase) | 暗色主题颜色集 |

---

# SnDataItem

通用数据项类型，全局弹窗操作菜单与多数列表类组件共用（组件侧详见[组件类型](/api/types/component#sndataitem)）。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| id | String | 否 | 项 id |
| text | String | 否 | 显示文本 |
| icon | String | 否 | 图标名 |
| value | String | 否 | 关联值 |
| color | String | 否 | 文本颜色 |
| disabled | Boolean | 否 | 是否禁用 |

---

# SnFlingEvent

`sn-view`、`sn-gesture` 等组件的快速滑动（fling）手势事件返回类型。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| type | String | 是 | 事件类型 |
| beginX | Number | 是 | 起始点横坐标 |
| beginY | Number | 是 | 起始点纵坐标 |
| endX | Number | 是 | 结束点横坐标 |
| endY | Number | 是 | 结束点纵坐标 |
| vX | Number | 是 | 横向速度 |
| vY | Number | 是 | 纵向速度 |

---

# SnFormData

表单数据对象。键为表单项的 `field`，值为该表单项绑定的值，作为 `sn-form` 的 `v-model` 被深度监听。

```typescript
const formData = ref<SnFormData>({
	name: '',
	age: 18
})
```

---

# SnFunctionalColor

五种功能色枚举，用于 `type` 类属性。

| 可选值 | 备注 |
| :--- | :--- |
| `primary` | 主色 |
| `info` | 信息色 |
| `success` | 成功色 |
| `error` | 错误色 |
| `warning` | 警告色 |

---

# SnModalAnimationFn

自定义弹窗开合动画函数，接收遮罩元素、内容元素与动画时长。

| 参数 | 类型 | 说明 |
| :--- | :--- | :--- |
| mask | UniElement \| null | 遮罩元素 |
| content | UniElement \| null | 内容元素 |
| duration | number | 动画时长（ms） |
| 返回值 | void | - |

---

# SnPermTipConfig

[`setPermTips`](/libs/utils/permission) 中单个权限的提示内容配置，四个字段均可省略。`html` 非空时优先展示（替代 `title` / `content`）。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| html | String | 否 | 自定义 HTML 内容 |
| title | String | 否 | 提示标题 |
| content | String | 否 | 提示正文 |
| icon | String | 否 | 提示图标名 |

---

# SnPermTipsStyleConfig

[`setPermTipsStyle`](/libs/utils/permission) 的提示气泡样式配置，各字段均可省略（省略时使用内置默认值）。颜色字段支持 `$` 简写（解析为当前主题实色，原生层直接可用），尺寸字段支持 `$` 动态值（乘对应乘数）与纯数字（按固定值）。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| position | String | 否 | 弹出位置，可选值 `top` \| `bottom`，默认 `top` |
| bgColor | String | 否 | 气泡背景颜色，默认 `$front` |
| radius | String \| Number | 否 | 气泡圆角，默认 `$12` |
| padding | String \| Number | 否 | 内边距，默认 `'$16px $20px'` |
| margin | String \| Number | 否 | 外边距，默认 `'$12px'` |
| titleColor | String | 否 | 标题颜色，默认 `$title` |
| titleSize | String \| Number | 否 | 标题字号，默认 `$16` |
| contentColor | String | 否 | 正文颜色，默认 `$text` |
| contentSize | String \| Number | 否 | 正文字号，默认 `$14` |
| iconColor | String | 否 | 图标颜色，默认 `$title` |
| iconSize | String \| Number | 否 | 图标字号，默认 `$22` |
| spacing | String \| Number | 否 | 行与行、图标与文本的间距，默认 `$10` |
| maxWidth | String \| Number | 否 | 气泡最大宽度（px），`0` 表示不限制 |
| aniTime | String \| Number | 否 | 出入动画时长，默认 `$250` |

---

# SnPointerEvent

`sn-view`、`sn-gesture` 等组件的指针事件返回类型。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| type | String | 是 | 事件类型：`click` \| `dbclick` \| `down` |
| x | Number | 是 | 点击点横坐标 |
| y | Number | 是 | 点击点纵坐标 |
| event | UniPointerEvent | 否 | 原事件，可用以阻止默认行为、阻止冒泡 |

---

# SnRequestMediaPermissionOptions

`snu.requestMediaPermission` 的配置。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| types | [SnRequestMediaPermissionOptionsType](#snrequestmediapermissionoptionstype)[] | 是 | 请求的媒体权限类型列表 |
| success | (allRight: boolean, grantedList: string[]) => void | 否 | 成功回调：是否全部授权、已授权列表 |
| fail | (doNotAskAgain: boolean, deniedList: string[]) => void | 否 | 失败回调：是否不再询问、被拒绝列表 |

---

# SnRequestMediaPermissionOptionsType

媒体权限类型。

| 可选值 | 备注 |
| :--- | :--- |
| `image` | 图片 |
| `video` | 视频 |
| `audio` | 音频 |

---

# SnRequestSystemPermissionOptions

[`snu.requestSystemPermission`](/libs/utils/permission#snu-requestsystempermission) 的配置。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| permissions | String[] | 是 | 请求的系统权限列表 |
| success | (allRight: boolean, grantedList: string[]) => void | 否 | 成功回调：是否全部授权、已授权列表 |
| fail | (doNotAskAgain: boolean, deniedList: string[]) => void | 否 | 失败回调：是否不再询问、被拒绝列表 |

---

# SnResolveType

[useResolve](/api/hooks/use-resolve) 解析函数的解析类型，决定 `$xxx` 乘以哪个乘数：`font` 字号、`radius` 圆角、`margin` 外间距、`padding` 内间距、`aniTime` 动画时长。

| 可选值 | 备注 |
| :--- | :--- |
| `font` | 字号 |
| `radius` | 圆角 |
| `margin` | 外间距 |
| `padding` | 内间距 |
| `aniTime` | 动画时长 |

---

# SnRotateEvent

`sn-view`、`sn-gesture` 等组件的旋转手势事件返回类型。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| degree | Number | 是 | 相对上一次旋转事件的角度增量（deg），顺时针为正 |

---

# SnScaleEvent

`sn-view`、`sn-gesture` 等组件的缩放手势事件返回类型。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| zoom | Number | 是 | 缩放倍数（相对上一次缩放事件） |

---

# SnShowActionsheetConfig

[`snu.showActionsheet`](/libs/utils/ui#snu-showactionsheet) 的配置。除与模态框类似的常用字段外：颜色字段支持 `$` 简写（解析为当前主题实色，原生层直接可用），尺寸字段支持 `$` 动态值（乘对应乘数）与纯数字（按固定值）。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| actions | Array<[SnDataItem](#sndataitem)> | 是 | 操作项列表 |
| title | String | 否 | 标题文本 |
| titleColor | String | 否 | 标题颜色 |
| titleSize | String \| Number | 否 | 标题字号 |
| showCancel | Boolean | 否 | 是否显示取消项 |
| cancelText | String | 否 | 取消项文案 |
| bgColor | String | 否 | 面板背景色 |
| borderRadius | String \| Number | 否 | 面板圆角 |
| maskOpacity | Number | 否 | 遮罩透明度 |
| itemTextSize | String \| Number | 否 | 操作项字号 |
| itemPadding | String \| Number | 否 | 操作项内边距 |
| aniTime | String \| Number | 否 | 动画时长 |
| preventBack | Boolean | 否 | 阻止返回键关闭 |
| disabled | Boolean | 否 | 禁用操作菜单 |
| maskClose | Boolean | 否 | 点击遮罩关闭 |
| wrapStyle | SnStyleValue | 否 | 队列容器样式 |
| wrapClass | String | 否 | 队列容器外部样式类 |
| panelStyle | SnStyleValue | 否 | 面板样式 |
| panelClass | String | 否 | 面板外部样式类 |
| itemStyle | SnStyleValue | 否 | 操作项样式（复用 sn-cell 样式链，透传 cell customStyle） |
| itemBorder | Boolean | 否 | 操作项是否显示分隔线（透传 cell border） |
| itemHoverStyle | SnStyleValue | 否 | 操作项点击态样式（透传 cell hoverStyle） |
| openAnimation | [SnModalAnimationFn](#snmodalanimationfn) | 否 | 自定义打开动画 |
| closeAnimation | [SnModalAnimationFn](#snmodalanimationfn) | 否 | 自定义关闭动画 |
| success | (tapIndex: number) => void | 否 | 成功回调，返回点击的操作项索引 |
| fail | (error: UniError) => void | 否 | 失败回调 |
| complete | (res: any \| null) => void | 否 | 完成回调 |

---

# SnShowLoadingConfig

[`snu.showLoading`](/libs/utils/ui#snu-showloading) 的配置。颜色字段支持 `$` 简写（解析为当前主题实色，原生层直接可用），尺寸字段支持 `$` 动态值（乘对应乘数）与纯数字（按固定值）。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| text | String | 否 | 提示文本 |
| overlay | Boolean | 否 | 是否显示遮罩 |
| maskOpacity | Number | 否 | 遮罩透明度 |
| shadow | Boolean | 否 | 是否显示阴影 |
| aniTime | String \| Number | 否 | 动画时长 |
| iconColor | String | 否 | 图标颜色 |
| iconSize | String \| Number | 否 | 图标字号 |
| textColor | String | 否 | 文本颜色 |
| textSize | String \| Number | 否 | 文本字号 |
| bgColor | String | 否 | 背景色 |
| borderRadius | String \| Number | 否 | 圆角 |
| padding | String \| Number | 否 | 内边距 |
| preventBack | Boolean | 否 | 阻止返回 |
| customStyle | SnStyleValue | 否 | 自定义样式 |
| success | () => void | 否 | 成功回调 |
| fail | (error: UniError) => void | 否 | 失败回调 |
| complete | (res: any \| null) => void | 否 | 完成回调 |

---

# SnShowModalConfig

[`snu.showModal`](/libs/utils/ui#snu-showmodal) 的配置。颜色字段支持 `$` 简写（解析为当前主题实色，原生层直接可用），尺寸字段支持 `$` 动态值（乘对应乘数）与纯数字（按固定值）。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| title | String | 否 | 标题文本 |
| titleAlign | String | 否 | 标题对齐方式 |
| titleSize | String \| Number | 否 | 标题字号 |
| titleFont | String | 否 | 标题字体 |
| titleColor | String | 否 | 标题颜色 |
| content | String | 否 | 内容文本 |
| contentAlign | String | 否 | 内容对齐方式 |
| contentSize | String \| Number | 否 | 内容字号 |
| contentColor | String | 否 | 内容颜色 |
| contentFont | String | 否 | 内容字体 |
| bgColor | String | 否 | 弹窗背景色 |
| borderRadius | String \| Number | 否 | 弹窗圆角 |
| buttonType | String | 否 | 可选值 `embed`（嵌入式）\| `float`（浮动式） |
| buttonBorder | String | 否 | 按钮边框样式 |
| confirmText | String | 否 | 确定按钮文字 |
| confirmTextColor | String | 否 | 确定按钮文字颜色 |
| confirmTextSize | String \| Number | 否 | 确定按钮文字字号 |
| showCancel | Boolean | 否 | 是否显示取消按钮 |
| showConfirm | Boolean | 否 | 是否显示确定按钮 |
| cancelText | String | 否 | 取消按钮文字 |
| cancelTextColor | String | 否 | 取消按钮文字颜色 |
| cancelTextSize | String \| Number | 否 | 取消按钮文字字号 |
| position | String | 否 | 可选值 `center` \| `top` \| `bottom` \| `left` \| `right` |
| aniTime | String \| Number | 否 | 动画时长 |
| maskClose | Boolean | 否 | 点击遮罩关闭 |
| maskOpacity | Number | 否 | 遮罩透明度 |
| disabled | Boolean | 否 | 禁用弹窗交互 |
| preventBack | Boolean | 否 | 阻止返回键关闭 |
| openAnimation | [SnModalAnimationFn](#snmodalanimationfn) | 否 | 自定义打开动画 |
| closeAnimation | [SnModalAnimationFn](#snmodalanimationfn) | 否 | 自定义关闭动画 |
| customStyle | SnStyleValue | 否 | 自定义样式 |
| success | (confirm: boolean, cancel: boolean) => void | 否 | 成功回调，可区分点击确定/取消/遮罩关闭 |
| fail | (error: UniError) => void | 否 | 失败回调 |
| complete | (res: any \| null) => void | 否 | 完成回调 |

---

# SnShowToastConfig

[`snu.showToast`](/libs/utils/ui#snu-showtoast) 的配置。`text` 与 `title` 兼容（仅有 `title` 时当 `text` 用，两者并存忽略 `title`）。颜色字段支持 `$` 简写（解析为当前主题实色，原生弹层直接可用），尺寸字段支持 `$` 动态值（乘对应乘数）与纯数字（按固定值）。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| text | String | 否 | 提示文本 |
| title | String | 否 | 兼容 `uni.showToast` 写法：仅有 `title` 时当作 `text` 使用；`text` 与 `title` 同时存在时忽略 `title` |
| bgColor | String | 否 | 背景色（默认 `$snui.colors.toast`，支持 `$` 简写主题色） |
| position | String | 否 | 可选值 `top` \| `center` \| `bottom`，默认 `center` |
| duration | Number | 否 | 显示时长（ms），默认 `2000` |
| textSize | String \| Number | 否 | 提示文本字号，默认 `$14` |
| textColor | String | 否 | 提示文本颜色（支持 `$` 简写），默认 `'#fff'` |
| borderRadius | String \| Number | 否 | 轻提示圆角，默认 `$12` |
| padding | String \| Number | 否 | 内边距，默认 `'$12px $15px'`（支持多段写法） |
| icon | String | 否 | 提示图标名（`success` / `error` / `info` / `warning` 等标准值）；`none` 或不传表示不显示图标 |
| iconSize | String \| Number | 否 | 图标字号，默认 `$20` |
| iconColor | String | 否 | 图标颜色（支持 `$` 简写），默认 `'#fff'` |
| textAlign | String | 否 | 文本对齐方式 |
| loading | Boolean | 否 | 是否显示加载图标（优先生效于 icon） |
| textLines | Number | 否 | 文本最大行数，超出省略；默认 `0` 不限制 |
| passThrough | Boolean | 否 | 是否穿透点击，默认 `true` |
| customStyle | SnStyleValue | 否 | 自定义样式 |
| success | () => void | 否 | 成功回调（同步触发） |
| fail | (error: UniError) => void | 否 | 失败回调 |
| complete | (res: any \| null) => void | 否 | 完成回调 |

---

# SnStyle

一套完整风格（皮肤）对象，即内置风格文件导出的结构。

| 字段 | 类型 | 描述 |
| :--- | :--- | :--- |
| id | String | 风格唯一 id，如 `'default'` |
| colorBases | [SnColorBases](#sncolorbases) | 亮/暗两套颜色集 |
| topbarHeight | String | 导航栏高度（不含状态栏），默认 `48px` |
| lightBgColor | String | 亮色模式页面默认背景色 |
| darkBgColor | String | 暗色模式页面默认背景色 |
| marginFactor | Number | 外间距乘数 |
| paddingFactor | Number | 内间距乘数 |
| radiusFactor | Number | 圆角乘数 |
| fontsizeFactor | Number | 字号乘数 |
| aniTimeFactor | Number | 动画时长乘数 |
| aniTimeShort | Number | 基础短动画时长（ms） |
| aniTimeNormal | Number | 基础标准动画时长（ms） |
| aniTimeLong | Number | 基础长动画时长（ms） |

---

# SnStyleValue

外部样式值，自定义样式 props（`customStyle`、`{语义}Style`、`hoverStyle` 等）的统一类型：既可以是样式字符串（如 `'color: red;'`），也可以是样式对象（键为小驼峰样式名、值为带单位的样式字符串，如 `{ padding: '8px' }`）。

```typescript
<sn-cell custom-style="padding: 8px;" />
<sn-cell :custom-style="{ padding: '8px' }" />
```

---

# SnSysToastOptions

`snu.showSysToast` 的配置，系统级原生 Toast 参数。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| title | String | 否 | 提示文本 |
| type | String | 否 | 显示时长，可选值 `short` / `long`（默认 `short`） |
| position | String | 否 | 显示位置，可选值 `top` / `center` / `bottom`（默认 `center`） |

---

# SnThemeMode

主题（颜色模式）枚举。

| 可选值 | 备注 |
| :--- | :--- |
| `light` | 亮色模式 |
| `dark` | 暗色模式 |

---

# SnToastParams

`sn-toast` 组件参数型轻提示的配置，见[组件类型](/api/types/component#sntoastparams)。

---

# SnTouch

单指触摸点信息，`sn-view`、`sn-gesture` 等组件的手势事件返回类型。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| x | Number | 是 | 触摸点横坐标 |
| y | Number | 是 | 触摸点纵坐标 |
| diffX | Number | 是 | 相对上一次触摸点的横向差值（正右负左） |
| diffY | Number | 是 | 相对上一次触摸点的纵向差值（正下负上） |
| direction | String | 是 | 手指移动方向 |
| id | Number | 是 | 手指 ID |

---

# SnTouchEvent

`sn-view`、`sn-gesture` 等组件的触摸事件返回类型。

| 字段 | 类型 | 必备 | 描述 |
| :--- | :--- | :--- | :--- |
| type | String | 是 | 事件类型：`touchstart` \| `touchend` \| `touchmove` \| `touchcancel` \| `longpress` \| `showpress` |
| touches | Array<[SnTouch](#sntouch)> | 是 | 多指触摸信息 |
| event | UniEvent | 否 | 原事件，可用以阻止默认行为、阻止冒泡 |

---

# UseHoverOptions

[useHover](/api/hooks/use-hover) 的参数类型，各字段为返回当前配置的函数。

| 字段 | 类型 | 描述 |
| :--- | :--- | :--- |
| enabled | () => boolean | 是否启用点击态 |
| startTime | () => number | 按下到进入点击态的延迟（ms） |
| stayTime | () => number | 抬起后点击态保留时长（ms） |
| transTime | () => number | 点击态过渡时长（ms） |
| normalTime | () => number | 常态过渡时长（ms） |

---

# UseHistoryOptions

[useHistory](/api/hooks/use-history) 的参数类型，各字段为返回当前配置的函数。

| 字段 | 类型 | 描述 |
| :--- | :--- | :--- |
| maxSteps | () => number | 最大历史步数，取值不大于 0 时按默认值 20 处理 |
| maxWeight | () => number | 最大累计权重（内存预算），取值不大于 0 表示只按步数限制 |

---

# SnHistoryStep

[useHistory](/api/hooks/use-history) 的单步历史记录。引擎只保存这三个数字，宿主载荷由调用方自持，因此历史内存与变更量成正比而非与文档总量成正比。

| 字段 | 类型 | 描述 |
| :--- | :--- | :--- |
| kind | number | 步类型，由调用方自定义语义（框架内 0 表示「新增一笔」） |
| ref | number | 载荷引用，通常是该步在调用方文档集合中的下标 |
| weight | number | 该步权重，参与最大权重预算淘汰，常用点数或字节量估算 |

---

# SnHistoryStats

[useHistory](/api/hooks/use-history) 的时间线统计快照，由 `stats` 返回。

| 字段 | 类型 | 描述 |
| :--- | :--- | :--- |
| cursor | number | 当前已应用步数（游标位置） |
| total | number | 时间线内保留的总步数 |
| weight | number | 时间线内保留步骤的累计权重 |
| evicted | number | 因超出步数或权重预算被淘汰的步数 |

---
# 其他类型

- 颜色库类型 `LColorOptions` / `LGenerateOptions` 见 [Color 颜色库类型](/libs/color/types)。
- 日期库类型 `DayutsConfig` / `DayutsUnit` / `DayutsFormats` / `DayutsRelativeTime` / `DayutsLocale` / `DayutsObject` 见 [Date 日期库类型](/libs/date/types)。
- `PermListener`（权限监听回调对象）见 [权限类](/libs/utils/permission#permlistener)。
- `UniError` 错误类型见 [错误处理机制](/api/error/error#unierror)。

# 组件类型

SinleUI 组件专属类型的统一参考。全部类型（含扩展组件类型）均统一从 `@/uni_modules/sinle-ui` 导出，使用时从插件入口导入即可：

```typescript
import { SnDataItem, SnCalendarValue, SnTreeData } from '@/uni_modules/sinle-ui'
```

> [!TIP] 提示
>
> 标记「内部使用」的类型由框架组件内部写入或回传，业务侧**只读、无需自行构造**：既包括仅在组件之间传递的类型，也包括组件事件 / 回调返回的详情类型（如各 `*-change`、`select` 事件的 detail）。业务**需要主动显式传入数据**的类型（组件 `data` / `v-model` / 配置类 props，以及 `load-data`、`format` 等回调函数的入参类型）均不加此标记。组件与 API 公用或仅 API 使用的类型（颜色集、风格、手势事件、全局弹窗配置、权限等）见 [API 类型](/api/types/api)。
>
> 本页与 [API 类型](/api/types/api) 覆盖框架内**全部**类型定义——公开类型与框架内部自用类型（分组组件 group config、子组件间注入 / 回传的类型等）均完整收录并列出字段，不做省略。内部类型仅供理解组件行为与排查问题，业务侧**不应**依赖，其字段可能随版本调整。本页类型按字母顺序排列。

---

# AgreementLinkDetail <Badge type="warning" text="内部使用" />

`sn-agreement` 的 `open-link` 事件返回的链接详情。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| text | String | 是 | 链接文本 |
| index | Number | 是 | 链接在协议中的序号（从 0 开始） |

---

# CheckboxGroupConfig <Badge type="warning" text="内部使用" />

`sn-checkbox-group` 向其子组件（`sn-checkbox`、`sn-checkbox-tag`）注入的配置对象，用于统一子项的外观与样式。业务侧只读，请通过 `sn-checkbox-group` 的属性控制。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| boxSize | String \| Number | 是 | 勾选框尺寸 |
| boxBorderRadius | String \| Number | 是 | 勾选框圆角 |
| boxBorderWidth | String \| Number | 是 | 勾选框边框宽度 |
| boxTextSize | String \| Number | 是 | 勾选框文字字号 |
| boxTextColor | String | 是 | 勾选框文字颜色 |
| disabledBoxTextColor | String | 是 | 禁用态勾选框文字颜色 |
| boxIcon | String | 是 | 勾选框选中图标名 |
| boxIconSize | String \| Number | 是 | 勾选框图标字号 |
| boxIconColor | String | 是 | 勾选框图标颜色 |
| disabledBoxIconColor | String | 是 | 禁用态勾选框图标颜色 |
| boxBorderColor | String | 是 | 勾选框边框颜色 |
| disabledBoxBorderColor | String | 是 | 禁用态勾选框边框颜色 |
| boxActiveBorderColor | String | 是 | 选中态勾选框边框颜色 |
| disabledBoxActiveBorderColor | String | 是 | 禁用态选中态勾选框边框颜色 |
| boxBgColor | String | 是 | 勾选框背景颜色 |
| disabledBoxBgColor | String | 是 | 禁用态勾选框背景颜色 |
| boxActiveBgColor | String | 是 | 选中态勾选框背景颜色 |
| disabledBoxActiveBgColor | String | 是 | 禁用态选中态勾选框背景颜色 |
| tagType | String | 是 | 标签模式功能色（`primary` \| `info` \| `success` \| `error` \| `warning`） |
| tagLevel | String | 是 | 标签模式表现程度等级（`first` \| `second` \| `third` \| `least`） |
| tagBorderRadius | String \| Number | 是 | 标签圆角 |
| tagPadding | String | 是 | 标签内边距 |
| tagTextSize | String \| Number | 是 | 标签文字字号 |
| tagBgColor | String | 是 | 标签背景颜色 |
| disabledTagBgColor | String | 是 | 禁用态标签背景颜色 |
| tagActiveBgColor | String | 是 | 选中态标签背景颜色 |
| disabledTagActiveBgColor | String | 是 | 禁用态选中态标签背景颜色 |
| tagTextColor | String | 是 | 标签文字颜色 |
| disabledTagTextColor | String | 是 | 禁用态标签文字颜色 |
| tagActiveTextColor | String | 是 | 选中态标签文字颜色 |
| disabledTagActiveTextColor | String | 是 | 禁用态选中态标签文字颜色 |
| boxContainStyle | SnStyleValue | 是 | 勾选框容器自定义样式 |
| boxStyle | SnStyleValue | 是 | 勾选框自定义样式 |
| boxIconStyle | SnStyleValue | 是 | 勾选框图标自定义样式 |
| tagStyle | SnStyleValue | 是 | 标签自定义样式 |
| textStyle | SnStyleValue | 是 | 文字自定义样式 |
| boxContainClass | String | 是 | 勾选框容器外部样式类 |
| boxClass | String | 是 | 勾选框外部样式类 |
| boxIconClass | String | 是 | 勾选框图标外部样式类 |
| tagClass | String | 是 | 标签外部样式类 |
| textClass | String | 是 | 文字外部样式类 |

---

# ChooseMediaWebOptions <Badge type="warning" text="内部使用" />

Web 平台下 `sn-upload-media` / `sn-upload-media-unicloud` 的内置文件选择器入参，仅 Web 端编译，业务侧不应直接引用。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| type | String | 是 | 媒体类型，可选值 `image` \| `video` \| `all` |
| multiple | Boolean \| null | 否 | 是否允许多选 |
| maxCount | Number \| null | 否 | 最大选择数量 |
| success | (files: [SnFile](#snfile)[]) => void \| null | 否 | 选择成功回调 |
| fail | (err: UniError) => void \| null | 否 | 选择失败回调 |

---

# CollapseConfig <Badge type="warning" text="内部使用" />

`sn-collapse` 向其子组件注入的配置对象，用于统一子项的外观与样式。业务侧只读，请通过 `sn-collapse` 的属性控制。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| accordion | Boolean | 是 | 是否手风琴模式（同时只展开一项） |
| showBorder | Boolean | 是 | 是否显示边框 |
| aniTime | String | 是 | 展开 / 收起动画时长 |
| bgColor | String | 是 | 背景颜色 |
| titleSize | String | 是 | 标题字号 |
| titleColor | String | 是 | 标题颜色 |
| noteSize | String | 是 | 备注字号 |
| noteColor | String | 是 | 备注颜色 |
| activeTitleColor | String | 是 | 展开态标题颜色 |
| borderRadius | String | 是 | 圆角 |
| titleStyle | SnStyleValue | 是 | 标题自定义样式 |
| holderStyle | SnStyleValue | 是 | 内容容器自定义样式 |
| noteStyle | SnStyleValue | 是 | 备注自定义样式 |
| titleClass | String | 是 | 标题外部样式类 |
| noteClass | String | 是 | 备注外部样式类 |
| holderClass | String | 是 | 内容容器外部样式类 |

---

# FingerOut <Badge type="warning" text="内部使用" />

`sn-gesture` 内部手势识别器每帧回传的手指状态对象，含位移、缩放、旋转与速度等信息。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| type | String | 是 | 手势类型 |
| x | Number | 是 | 当前触点横坐标 |
| y | Number | 是 | 当前触点纵坐标 |
| startX | Number | 是 | 起始横坐标 |
| startY | Number | 是 | 起始纵坐标 |
| endX | Number | 是 | 结束横坐标 |
| endY | Number | 是 | 结束纵坐标 |
| zoom | Number | 是 | 相对起始的缩放倍数 |
| rotate | Number | 是 | 相对起始的旋转角度（deg） |
| direction | String | 是 | 移动方向 |
| deltaX | Number | 是 | 本帧横向位移增量 |
| deltaY | Number | 是 | 本帧纵向位移增量 |
| vX | Number | 是 | 横向速度 |
| vY | Number | 是 | 纵向速度 |
| evt | UniTouchEvent \| null | 否 | 原始触摸事件 |

---

# LoadingPageBridge <Badge type="warning" text="内部使用" />

全局加载（`snu.showLoading`）与承载它的页面（`pages/popups/showLoading`）之间的通信桥接对象。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| page | any | 是 | 加载页实例引用 |
| hide | () => void | 是 | 关闭加载页的方法 |

---

# QrCellPoint <Badge type="warning" text="内部使用" />

二维码绘制点，`QrCodeData` 的 `points` 列表项。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| x | Number | 是 | 横向坐标 |
| y | Number | 是 | 纵向坐标 |
| type | Number | 是 | 模块类型（QrPointType 枚举值） |

---

# QrCodeData <Badge type="warning" text="内部使用" />

二维码绘制数据，由组件内部编码生成。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| size | Number | 是 | 含留白的最终矩阵尺寸 |
| moduleCount | Number | 是 | 不含留白的原始模块数 |
| version | Number | 是 | 实际使用的二维码版本 |
| matrix | Boolean[][] | 是 | 模块矩阵 |
| typeTable | Number[][] | 是 | 各模块类型表（对应 QrPointType 枚举） |
| points | [QrCellPoint](#qrcellpoint)[] | 是 | 有效模块点列表（含坐标与类型） |

---

# QrEcLevel

二维码纠错等级。

| 可选值 | 备注 |
| :--- | :--- |
| `low` | 低（约 7% 纠错） |
| `medium` | 中（约 15% 纠错） |
| `quartile` | 四分位（约 25% 纠错） |
| `high` | 高（约 30% 纠错） |

---

# QrEncodeOptions <Badge type="warning" text="内部使用" />

二维码编码配置，由组件内部按属性组装后传入编码器。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| ecc | [QrEcLevel](#qreclevel) | 是 | 纠错等级，默认 `medium` |
| version | Number | 是 | 二维码版本，`0` 表示自动 |
| mask | Number | 是 | 掩码图样，`-1` 表示自动 |
| border | Number | 是 | 留白边距（模块数），默认 `2` |

---

# QrModuleShape

二维码模块形状。

| 可选值 | 备注 |
| :--- | :--- |
| `square` | 方形 |
| `rounded` | 圆角方形 |
| `circle` | 圆形 |
| `diamond` | 菱形 |

---

# QrPointType <Badge type="warning" text="内部使用" />

二维码模块的功能类型枚举，用于绘制时区分数据区与定位 / 校正 / 时序等特殊区域。

| 可选值 | 备注 |
| :--- | :--- |
| `DATA` | 数据模块 |
| `POS_CENTER` | 定位图案中心 |
| `POS_OTHER` | 定位图案其他 |
| `ALIGN_CENTER` | 校正图案中心 |
| `ALIGN_OTHER` | 校正图案其他 |
| `TIMING` | 时序图案 |
| `FORMAT` | 格式信息 |
| `VERSION` | 版本信息 |

---

# SnAvatarConfig

内置 `sn-avatar` 的组件（如列表项、发布卡）可通过 `avatarConfig` 属性统一配置头像参数。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| mode | [SnAvatarMode](#snavatarmode) | 否 | 显示模式，默认 `image` |
| src | String | 否 | 图片路径（`mode` 为 `image` 时生效） |
| text | String | 否 | 文本内容（`mode` 为 `text` 时生效） |
| icon | String | 否 | 图标名（`mode` 为 `icon` 时生效） |
| size | String \| Number | 否 | 尺寸大小 |
| shape | [SnAvatarShape](#snavatarshape) | 否 | 形状 |
| bgColor | String | 否 | 背景颜色 |
| textColor | String | 否 | 文本颜色 |
| iconColor | String | 否 | 图标颜色 |
| borderRadius | String \| Number | 否 | 圆角大小 |
| enablePreview | Boolean | 否 | 是否启用图片预览（`mode` 为 `image` 时生效） |

---

# SnAvatarGroupItem

`sn-avatar-group` 的 `data` 属性需要传入一个 `SnAvatarGroupItem[]` 类型的数组。此对象只能传入数据，样式请通过 `sn-avatar-group` 的属性统一设置。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| src | String | 否 | 图片路径 |
| text | String | 否 | 文本内容 |
| icon | String | 否 | 图标名称 |
| bgColor | String | 否 | 背景颜色 |
| textColor | String | 否 | 文本颜色 |
| iconColor | String | 否 | 图标颜色 |

---

# SnAvatarMode

头像显示模式。

| 可选值 | 备注 |
| :--- | :--- |
| `image` | 图片 |
| `text` | 文本 |
| `icon` | 图标 |

---

# SnAvatarShape

头像形状。

| 可选值 | 备注 |
| :--- | :--- |
| `square` | 方形 |
| `circle` | 圆形 |

---

# SnBadgeParams

内置 `sn-badge` 的组件可通过 `badgeConfig` 属性配置徽标参数。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| value | Number | 否 | 显示的值（仅 number 模式） |
| max | Number | 否 | 最大值，超过显示 `max+` |
| size | String | 否 | 大小 |
| offset | String | 否 | 偏移量（transform） |
| mode | String | 否 | 可选值 `number` \| `text` \| `dot` |
| text | String | 否 | 文本内容（仅 text 模式） |
| showZero | Boolean | 否 | 是否显示 0 |
| textColor | String | 否 | 文字颜色 |
| bgColor | String | 否 | 背景颜色 |

---

# SnBarcodeBarElement <Badge type="warning" text="内部使用" />

条码单元。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| width | Number | 是 | 模块宽度 |
| bar | Boolean | 是 | 是否为条纹（`false` 为间隙） |

---

# SnBarcodeData <Badge type="warning" text="内部使用" />

条码绘制数据，由组件内部编码生成。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| elements | [SnBarcodeBarElement](#snbarcodebarelement)[] | 是 | 条纹元素序列 |
| totalModules | Number | 是 | 总模块数 |
| value | String | 是 | 实际编码的文本（可能被截断） |

---

# SnBarcodeFormat

条码格式。

| 可选值 | 备注 |
| :--- | :--- |
| `code128` | Code 128 |
| `code39` | Code 39 |
| `code93` | Code 93 |
| `codabar` | Codabar |
| `ean8` | EAN-8 |
| `ean13` | EAN-13 |
| `upca` | UPC-A |
| `upce` | UPC-E |
| `itf` | ITF（交错 2/5） |

---

# SnCalendarBoundaries <Badge type="warning" text="内部使用" />

日历可选日期范围边界，由组件内部经 `min-date` / `max-date` 属性归一化后传递。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| minDate | Number | 是 | 可选最小日期时间戳（当日 0 点） |
| maxDate | Number | 是 | 可选最大日期时间戳（当日 0 点） |

---

# SnCalendarSelectionResult <Badge type="warning" text="内部使用" />

日历选中计算的结果，由 `sn-calendar-view` 内部根据当前值与点击日期推导。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| value | [SnCalendarValue](#sncalendarvalue) | 是 | 计算后的新选中值 |
| changed | Boolean | 是 | 选中值是否发生变化 |
| overRange | Boolean | 是 | 是否超出允许的选择范围 |

---

# SnCalendarDay <Badge type="warning" text="内部使用" />

`formatter` 回调入参，单个日期格的完整信息。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| timestamp | Number | 是 | 当日 0 点时间戳 |
| year | Number | 是 | 年 |
| month | Number | 是 | 月 |
| date | Number | 是 | 日 |
| weekday | Number | 是 | 星期（0-6） |
| text | String | 是 | 日期文本 |
| prefix | String | 是 | 前缀文字（默认空） |
| suffix | String | 是 | 后缀文字（默认空） |
| today | Boolean | 是 | 是否今天 |
| disabled | Boolean | 是 | 是否禁用 |
| currentMonth | Boolean | 是 | 是否当前显示月份 |
| state | [SnCalendarDayState](#sncalendardaystate) | 是 | 选中状态 |
| paint | [SnCalendarDayPaint](#sncalendardaypaint) \| null | 否 | 绘制配置 |

---

# SnCalendarDayContent <Badge type="warning" text="内部使用" />

日期格内容（formatter 返回值）。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| prefix | String | 否 | 前缀文字（如「休」） |
| text | String | 否 | 日期文本（默认为日号） |
| suffix | String | 否 | 后缀文字（如「今天」） |
| paint | [SnCalendarDayPaint](#sncalendardaypaint) \| null | 否 | 绘制配置 |

---

# SnCalendarDayContentInput

`createCalendarDayContent(input)` 的入参类型，在内容字段之外可快捷设置圆点相关字段。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| prefix | String | 否 | 前缀文字 |
| text | String | 否 | 日期文本 |
| suffix | String | 否 | 后缀文字 |
| showDot | Boolean | 否 | 是否显示圆点 |
| dotColor | String | 否 | 圆点颜色 |
| dotPosition | [SnCalendarDayDotPosition](#sncalendardaydotposition) | 否 | 圆点位置 |
| paint | [SnCalendarDayPaintInput](#sncalendardaypaintinput) | 否 | 绘制配置 |

---

# SnCalendarDayDotPosition <Badge type="warning" text="内部使用" />

日历圆点标记位置。

| 可选值 | 备注 |
| :--- | :--- |
| `left` | 左侧 |
| `right` | 右侧 |
| `top` | 顶部 |
| `bottom` | 底部 |

---

# SnCalendarDayFormatter

日期格格式化器：返回 `null` 表示使用默认内容。

| 参数 | 类型 | 说明 |
| :--- | :--- | :--- |
| day | [SnCalendarDay](#sncalendarday) | 日期格信息 |
| 返回值 | [SnCalendarDayContent](#sncalendardaycontent) \| null | 格式化后的内容，`null` 表示使用默认内容 |

---

# SnCalendarDayPaint <Badge type="warning" text="内部使用" />

日期格绘制配置（由 `SnCalendarDayContent.paint` 携带，经 formatter 或 `createCalendarDayPaint` 构造）。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| backgroundColor | String | 否 | 背景颜色 |
| borderColor | String | 否 | 边框颜色 |
| borderWidth | Number | 否 | 边框宽度 |
| fontSize | String \| Number | 否 | 日期字号 |
| prefixColor | String | 否 | 前缀文字颜色 |
| textColor | String | 否 | 日期文字颜色 |
| suffixColor | String | 否 | 后缀文字颜色 |
| prefixFontSize | Number | 否 | 前缀字号 |
| suffixFontSize | Number | 否 | 后缀字号 |
| fontWeight | String | 否 | 字重 |
| showDot | Boolean | 否 | 是否显示圆点 |
| dotColor | String | 否 | 圆点颜色 |
| dotPosition | [SnCalendarDayDotPosition](#sncalendardaydotposition) | 否 | 圆点位置 |

---

# SnCalendarDayPaintInput

`createCalendarDayPaint(input)` 的入参类型，字段与 [SnCalendarDayPaint](#sncalendardaypaint) 一致。

---

# SnCalendarDayState <Badge type="warning" text="内部使用" />

日历日期格状态。

| 可选值 | 备注 |
| :--- | :--- |
| `normal` | 普通 |
| `selected` | 选中 |
| `range-start` | 范围起点 |
| `range-middle` | 范围中间 |
| `range-end` | 范围终点 |
| `range-start-end` | 起终点同日 |

---

# SnCalendarLocaleText

日历文案配置。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| title | String | 是 | 弹层标题 |
| confirmText | String | 是 | 确认按钮文案 |
| confirmDisabledText | String | 是 | 确认按钮禁用态文案 |
| rangePrompt | String | 是 | 范围选择提示文案 |
| weekdays | String[] | 是 | 星期标题数组 |
| yearMonthFormat | String | 是 | 年月格式 |

---

# SnCalendarPanelChangeDetail <Badge type="warning" text="内部使用" />

日历 `panel-change` 事件返回的面板切换详情。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| timestamp | Number | 是 | 面板首日时间戳 |
| year | Number | 是 | 年 |
| month | Number | 是 | 月 |

---

# SnCalendarPunchDay <Badge type="warning" text="内部使用" />

打卡日历（sn-calendar-punch）`select` 事件返回的单日信息。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| timestamp | Number | 是 | 当日 0 点时间戳 |
| year | Number | 是 | 年 |
| month | Number | 是 | 月 |
| date | Number | 是 | 日 |
| fullDate | String | 是 | `YYYY-MM-DD` 格式日期字符串 |
| signed | Boolean | 是 | 当日是否已打卡 |
| supplementable | Boolean | 是 | 当日是否可补签 |
| today | Boolean | 是 | 是否今天 |

---

# SnCalendarSwitchMode

日历面板切换粒度。

| 可选值 | 备注 |
| :--- | :--- |
| `month` | 按月切换 |
| `year-month` | 按年-月切换 |

---

# SnCalendarType

日历选择模式。

| 可选值 | 备注 |
| :--- | :--- |
| `single` | 单选 |
| `multiple` | 多选 |
| `range` | 范围选择 |

---

# SnCalendarValue

日历选中值（`v-model`），随 `type` 变化：`single` 为时间戳 `number \| null`；`range` 为 `[]` 或 `[start, end]`（单点范围写成 `[same, same]`）；`multiple` 为时间戳数组 `number[]`。

| 类型 | 说明 |
| :--- | :--- |
| `number \| null` | `single` 模式：时间戳或空 |
| `number[]` | `multiple` 模式：时间戳数组 |
| `[]` \| `[start, end]` | `range` 模式：空或起止时间戳（单点范围写成 `[same, same]`） |

---

# SnCalendarWeekChangeDetail <Badge type="warning" text="内部使用" />

周日历（sn-calendar-week）`week-change` 事件返回详情。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| timestamp | Number | 是 | 当前周首日时间戳 |
| year | Number | 是 | 年 |
| month | Number | 是 | 月 |

---

# SnCalendarWeekDay <Badge type="warning" text="内部使用" />

周日历（sn-calendar-week）单日信息，由组件内部构建。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| timestamp | Number | 是 | 当日 0 点时间戳 |
| text | String | 是 | 日号文本 |
| weekTitle | String | 是 | 所属周标题 |
| today | Boolean | 是 | 是否今天 |
| disabled | Boolean | 是 | 是否禁用 |
| showDot | Boolean | 是 | 是否显示圆点 |
| dotColor | String | 是 | 圆点颜色 |

---

# SnCalendarWeekStartDay

日历周起始日。

| 可选值 | 备注 |
| :--- | :--- |
| `sunday` | 星期日 |
| `monday` | 星期一 |
| `tuesday` | 星期二 |
| `wednesday` | 星期三 |
| `thursday` | 星期四 |
| `friday` | 星期五 |
| `saturday` | 星期六 |

---

# SnCascaderDetail <Badge type="warning" text="内部使用" />

`sn-cascader` 的 `change` 事件返回的详情。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| values | String[] | 是 | 各级选中值 |
| labels | String[] | 是 | 各级选中文本 |
| options | [SnCascaderOption](#sncascaderoption)[] | 是 | 各级选中的选项对象 |

---

# SnCascaderLoadData

`sn-cascader` 的 `load-data` 属性接收 `SnCascaderLoadData` 函数：`parent` 为 `null` 表示加载第一级，`level` 为当前层级；成功经 `resolve(options)` 返回选项列表，失败调用 `reject()`。

| 类型 | 签名 |
| :--- | :--- |
| SnCascaderResolve | (options: [SnCascaderOption](#sncascaderoption)[]) => void |
| SnCascaderReject | () => void |
| SnCascaderLoadData | (parent: [SnCascaderOption](#sncascaderoption) \| null, level: number, resolve: [SnCascaderResolve](#sncascaderresolve), reject: [SnCascaderReject](#sncascaderreject)) => void |

---

# SnCascaderOption

级联选项。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| value | String | 是 | 选项值 |
| label | String | 是 | 选项显示文本 |
| disabled | Boolean | 否 | 是否禁用 |
| leaf | Boolean | 否 | 是否叶子节点（懒加载模式下标记不再展开） |
| children | [SnCascaderOption](#sncascaderoption)[] | 否 | 子级选项列表 |

---

# SnCascaderReject

`sn-cascader` 的 `load-data` 回调参数之一：懒加载失败时调用，通知组件结束加载态（由 [SnCascaderLoadData](#sncascaderloaddata) 的 `reject` 参数使用）。

| 类型 | 签名 |
| :--- | :--- |
| Function | () => void |

---

# SnCascaderResolve

`sn-cascader` 的 `load-data` 回调参数之一：懒加载成功时调用，传入该层级的选项列表（由 [SnCascaderLoadData](#sncascaderloaddata) 的 `resolve` 参数使用）。

| 类型 | 签名 |
| :--- | :--- |
| Function | (options: [SnCascaderOption](#sncascaderoption)[]) => void |

---

# SnCascaderValue

级联选中值：各级选项 `value` 组成的数组（`v-model`）。

| 类型 | 说明 |
| :--- | :--- |
| `string[]` | 各级选中值数组 |

---

# SnDataItem

通用数据项类型，通用列表类组件与全局操作菜单使用。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| id | String | 否 | 数据的唯一标识 |
| text | String | 否 | 数据显示文本 |
| icon | String | 否 | 数据显示图标 |
| value | String | 否 | 关联值 |
| color | String | 否 | 文本颜色 |
| disabled | Boolean | 否 | 是否禁用子项 |

---

# SnSelectItem

`sn-select` 专用选项类型，支持左右图标和选项级文字样式。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| id | String | 否 | 数据的唯一标识 |
| text | String | 否 | 数据显示文本 |
| icon | String | 否 | 兼容字段，作为左侧图标 |
| leftIcon | String | 否 | 左侧图标名 |
| rightIcon | String | 否 | 右侧图标名 |
| value | String | 否 | 关联值 |
| color | String | 否 | 兼容字段，作为文本颜色 |
| textColor | String | 否 | 文本颜色 |
| textSize | String \| Number | 否 | 文本字号 |
| leftIconColor | String | 否 | 左侧图标颜色 |
| rightIconColor | String | 否 | 右侧图标颜色 |
| leftIconSize | String \| Number | 否 | 左侧图标尺寸 |
| rightIconSize | String \| Number | 否 | 右侧图标尺寸 |
| disabled | Boolean | 否 | 是否禁用子项 |

---

# SnDatetimePickerTimeModeValue

日期时间选择器时间选择粒度模式。

| 可选值 | 备注 |
| :--- | :--- |
| `year` | 年 |
| `month` | 月 |
| `date` | 日 |
| `hour` | 时 |
| `minute` | 分 |
| `second` | 秒 |

---

# SnDatetimePickerValue

日期时间选择器选中值（`v-model`）：时间戳数字或时间格式字符串。

| 类型 | 说明 |
| :--- | :--- |
| `string \| number` | 时间格式字符串或时间戳数字 |

---

# SnEmptyColorConfig <Badge type="warning" text="内部使用" />

`sn-empty` 内部传递插画配色参数。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| themeColor | String | 是 | 主题颜色 |
| hairColor | String | 是 | 头发颜色 |
| clothesColor | String | 是 | 衣服颜色 |
| trousersColor | String | 是 | 裤子颜色 |
| shoesColor | String | 是 | 鞋子颜色 |
| itemColor | String | 是 | 项目颜色 |
| skinColor | String | 是 | 皮肤颜色 |
| elementColor | String | 是 | 元素颜色 |

---

# SnFile <Badge type="warning" text="内部使用" />

上传媒体文件信息，由 `sn-upload-media` 的 `file-chose` 事件与内部选择逻辑返回。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| filename | String | 是 | 文件名 |
| path | String | 是 | 文件路径 |
| size | Number | 否 | 文件大小 |
| ext | String | 是 | 扩展名 |

---

# SnFooterLink

`sn-footer` 链接项。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| name | String | 否 | 链接名称 |
| url | String | 否 | 跳转地址 |
| openType | String | 否 | 打开方式 |

---

# SnFooterLogo

`sn-footer` Logo 配置。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| icon | String | 否 | 图标名 |
| title | String | 否 | 标题文本 |
| url | String | 否 | 跳转地址 |
| openType | String | 否 | 打开方式 |

---

# SnFormItemData <Badge type="warning" text="内部使用" />

`sn-form-item` 内部注册组件数据类型。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| field | String | 是 | 子项名称 |
| instance | ComponentPublicInstance | 是 | 子项实例 |

---

# SnFormItemRule

`sn-form-item` 的 `rule` 属性校验规则。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| type | String | 否 | 字段类型（如 `string` / `number` / `array` / `url` / `email` / `phone` 等） |
| required | Boolean | 否 | 是否必填 |
| message | String | 否 | 校验失败提示信息 |
| pattern | RegExp | 否 | 正则校验规则 |
| min | Number | 否 | 最小长度 |
| max | Number | 否 | 最大长度 |
| len | Number | 否 | 固定长度 |
| enum | any[] | 否 | 枚举校验，值须在列表内 |
| transform | (value: any) => any | 否 | 校验前对值进行转换 |
| valid | (value: any) => string | 否 | 自定义校验函数，返回非空字符串表示失败信息 |

---

# SnFormItemVerifyResult <Badge type="warning" text="内部使用" />

单项校验结果，经 `sn-form` 的 `fail` 事件与 `valid.fail` 回调返回，业务侧只读。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| valid | Boolean | 是 | 是否通过校验 |
| message | String | 否 | 失败信息 |
| field | String | 是 | 子项名称 |

---

# SnFormValidResult

`sn-form` 的 `valid` 属性回调配置。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| success | () => void | 否 | 全部通过回调 |
| fail | (failResults: [SnFormItemVerifyResult](#snformitemverifyresult)[]) => void | 否 | 失败回调，入参为失败结果数组 |

---

# SnLocaleInfo

语言条目，`SUPPORTED_LOCALES` 数组的元素类型，可直接渲染为语言选择器。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| code | String | 是 | 语言代码（如 `zh-Hans`、`en`） |
| name | String | 是 | 该语言的本地化名称（如 `简体中文`、`English`） |

---

# SnLoadmoreParams

`sn-loadmore` / 列表加载更多的文案与样式配置。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| loadmoreText | String | 否 | 加载前文案 |
| nomoreText | String | 否 | 没有更多文案 |
| loadingText | String | 否 | 加载中文案 |
| textSize | String | 否 | 文本字号 |
| textColor | String | 否 | 文本颜色 |
| iconSize | String | 否 | 图标字号 |
| iconColor | String | 否 | 图标颜色 |
| lineColor | String | 否 | 线条颜色 |
| lineHeight | String | 否 | 线条高度 |
| dashed | Boolean | 否 | 线条是否虚线 |
| disabled | Boolean | 否 | 是否禁用 |

---

# SnMedia <Badge type="warning" text="内部使用" />

上传媒体条目。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| file | any | 否 | 文件对象 |
| src | String | 否 | 预览路径 |
| thumb | String | 否 | 缩略图路径 |
| name | String | 是 | 文件名 |
| status | String | 是 | 上传状态，可选值 `uploaded` \| `uploading` \| `unuploaded` \| `error` |
| type | String | 是 | 媒体类型，可选值 `image` \| `video` |
| ext | String | 否 | 扩展名 |

---

# SnMessageLevel

消息条表现程度等级。

| 可选值 | 备注 |
| :--- | :--- |
| `first` | 一级（表现最重） |
| `second` | 二级 |
| `third` | 三级（表现最轻） |

---

# SnMessageParams

`sn-message` 组件 `add` 方法入参。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| text | String | 否 | 消息内容 |
| type | [SnMessageType](#snmessagetype) | 否 | 消息类型 |
| level | [SnMessageLevel](#snmessagelevel) | 否 | 消息等级 |
| position | [SnMessagePosition](#snmessageposition) | 否 | 队列位置 |
| duration | Number | 否 | 显示时长（ms） |
| showIcon | Boolean | 否 | 是否显示图标 |
| icon | String | 否 | 图标名 |
| closable | Boolean | 否 | 是否显示关闭按钮 |
| grouping | Boolean | 否 | 相同内容是否归并计数 |
| bgColor | String | 否 | 背景颜色 |
| textColor | String | 否 | 文字颜色 |
| iconColor | String | 否 | 图标颜色 |
| textSize | String | 否 | 文字字号 |
| borderRadius | String | 否 | 圆角 |
| customStyle | SnStyleValue | 否 | 自定义样式 |

---

# SnMessagePosition

消息条队列位置。

| 可选值 | 备注 |
| :--- | :--- |
| `top-left` | 左上 |
| `top` | 顶部 |
| `top-right` | 右上 |
| `bottom-left` | 左下 |
| `bottom` | 底部 |
| `bottom-right` | 右下 |

---

# SnMessageType

消息条类型。

| 可选值 | 备注 |
| :--- | :--- |
| `primary` | 主色 |
| `success` | 成功 |
| `error` | 错误 |
| `info` | 信息 |
| `warning` | 警告 |

---

# SnNotificationLevel

通知表现程度等级。

| 可选值 | 备注 |
| :--- | :--- |
| `first` | 一级（表现最重） |
| `second` | 二级 |
| `third` | 三级（表现最轻） |

---

# SnNotificationParams

`sn-notification` 组件 `add` 方法入参。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| title | String | 否 | 通知标题 |
| content | String | 否 | 通知内容 |
| type | [SnNotificationType](#snnotificationtype) | 否 | 通知类型 |
| level | [SnNotificationLevel](#snnotificationlevel) | 否 | 通知等级 |
| position | [SnNotificationPosition](#snnotificationposition) | 否 | 队列位置，可选值 `top` \| `bottom` |
| duration | Number | 否 | 显示时长（ms） |
| showProgress | Boolean | 否 | 是否显示进度条 |
| showIcon | Boolean | 否 | 是否显示图标 |
| icon | String | 否 | 图标名 |
| closable | Boolean | 否 | 是否显示关闭按钮 |
| showAction | Boolean | 否 | 是否显示右侧操作插槽（`slot="action"`，需组件标签内定义插槽内容） |
| grouping | Boolean | 否 | 相同内容是否归并计数 |
| bgColor | String | 否 | 背景颜色 |
| titleColor | String | 否 | 标题颜色 |
| contentColor | String | 否 | 内容颜色 |
| iconColor | String | 否 | 图标颜色 |
| borderRadius | String | 否 | 圆角 |
| draggable | Boolean | 否 | 是否可拖拽 |
| dragThreshold | String \| Number | 否 | 拖拽关闭位移阈值 |
| customStyle | SnStyleValue | 否 | 自定义样式 |

---

# SnNotificationPosition

通知队列位置。

| 可选值 | 备注 |
| :--- | :--- |
| `top` | 顶部 |
| `bottom` | 底部 |

---

# SnNotificationType

通知类型。

| 可选值 | 备注 |
| :--- | :--- |
| `primary` | 主色 |
| `success` | 成功 |
| `error` | 错误 |
| `info` | 信息 |
| `warning` | 警告 |

---

# SnPostCardAction

动态卡片（sn-post-card）操作栏按钮配置。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| id | String | 否 | 按钮 id |
| icon | String | 否 | 图标名 |
| text | String | 否 | 按钮文字（一般为数量） |
| disabled | Boolean | 否 | 是否禁用 |
| isActive | Boolean | 否 | 是否处于激活态（如已点赞） |
| iconColor | String | 否 | 图标颜色 |
| textColor | String | 否 | 文字颜色 |
| activeIconColor | String | 否 | 激活态图标颜色 |
| activeTextColor | String | 否 | 激活态文字颜色 |

---

# SnPostCardComment

动态卡片评论区条目。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| id | String | 否 | 评论 id |
| user | String | 否 | 评论用户 |
| content | String | 否 | 评论内容 |
| replyTo | String | 否 | 回复的用户名（为空表示直接评论） |

---

# RadioGroupConfig <Badge type="warning" text="内部使用" />

`sn-radio-group` 向其子组件（`sn-radio`、`sn-radio-tag`）注入的配置对象，用于统一子项的外观与样式。业务侧只读，请通过 `sn-radio-group` 的属性控制。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| radioSize | String \| Number | 是 | 单选按钮尺寸 |
| radioBorderWidth | String \| Number | 是 | 单选按钮边框宽度 |
| radioTextSize | String \| Number | 是 | 单选按钮文字字号 |
| radioBgColor | String | 是 | 单选按钮背景颜色 |
| disabledRadioBgColor | String | 是 | 禁用态单选按钮背景颜色 |
| radioActiveBgColor | String | 是 | 选中态单选按钮背景颜色 |
| disabledRadioActiveBgColor | String | 是 | 禁用态选中态单选按钮背景颜色 |
| radioTextColor | String | 是 | 单选按钮文字颜色 |
| disabledRadioTextColor | String | 是 | 禁用态单选按钮文字颜色 |
| radioBorderColor | String | 是 | 单选按钮边框颜色 |
| disabledRadioBorderColor | String | 是 | 禁用态单选按钮边框颜色 |
| radioActiveBorderColor | String | 是 | 选中态单选按钮边框颜色 |
| disabledRadioActiveBorderColor | String | 是 | 禁用态选中态单选按钮边框颜色 |
| tagType | String | 是 | 标签模式功能色（`primary` \| `info` \| `success` \| `error` \| `warning`） |
| tagLevel | String | 是 | 标签模式表现程度等级（`first` \| `second` \| `third` \| `least`） |
| tagBorderRadius | String \| Number | 是 | 标签圆角 |
| tagPadding | String | 是 | 标签内边距 |
| tagTextSize | String \| Number | 是 | 标签文字字号 |
| tagBgColor | String | 是 | 标签背景颜色 |
| disabledTagBgColor | String | 是 | 禁用态标签背景颜色 |
| tagActiveBgColor | String | 是 | 选中态标签背景颜色 |
| disabledTagActiveBgColor | String | 是 | 禁用态选中态标签背景颜色 |
| tagTextColor | String | 是 | 标签文字颜色 |
| disabledTagTextColor | String | 是 | 禁用态标签文字颜色 |
| tagActiveTextColor | String | 是 | 选中态标签文字颜色 |
| disabledTagActiveTextColor | String | 是 | 禁用态选中态标签文字颜色 |
| radioContainStyle | SnStyleValue | 是 | 单选按钮容器自定义样式 |
| radioStyle | SnStyleValue | 是 | 单选按钮自定义样式 |
| tagStyle | SnStyleValue | 是 | 标签自定义样式 |
| textStyle | SnStyleValue | 是 | 文字自定义样式 |
| radioContainClass | String | 是 | 单选按钮容器外部样式类 |
| radioClass | String | 是 | 单选按钮外部样式类 |
| tagClass | String | 是 | 标签外部样式类 |
| textClass | String | 是 | 文字外部样式类 |

---

# SnRefresherParams

下拉刷新区域文案与样式配置。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| refreshText | String | 否 | 下拉中文案 |
| refreshingText | String | 否 | 刷新中文案 |
| textSize | String | 否 | 文本字号 |
| textColor | String | 否 | 文本颜色 |
| icon | String | 否 | 图标名 |
| iconSize | String | 否 | 图标字号 |
| iconColor | String | 否 | 图标颜色 |

---

# SnRegionDetail <Badge type="warning" text="内部使用" />

`sn-region-picker` 的 `change` 事件返回详情。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| codes | String[] | 是 | 各级区划代码数组 |
| names | String[] | 是 | 各级名称数组 |

---

# SnRegionLevel

行政区划层级。

| 可选值 | 备注 |
| :--- | :--- |
| `province` | 省 |
| `city` | 市 |
| `county` | 区县 |

---

# SnRegionNode

行政区划节点。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| code | String | 是 | 区划代码 |
| name | String | 是 | 名称 |
| children | [SnRegionNode](#snregionnode)[] | 否 | 子级节点 |

---

# SnRegionValue

`sn-region-picker` 选中值（`v-model`）：各级区划代码数组。

| 类型 | 说明 |
| :--- | :--- |
| `string[]` | 各级区划代码数组 |

---

# SnScanParams

`sn-scan` 经 `uni.navigateTo` 打开扫码页时通过 `SnScanParams` 传参（`snu.openScanPage` 等封装亦使用）。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| scanType | String | 否 | 扫码类型，可选值 `barcode` \| `qrcode` \| `all`，默认 `all` |
| continuous | Boolean | 否 | 是否连续扫码 |
| scanOnlyOnce | Boolean | 否 | 是否识别一次后自动返回 |
| continuousSleep | Number | 否 | 连续扫码间隔（ms） |
| enableDing | Boolean | 否 | 识别成功提示音 |
| dingFileSrc | String | 否 | 自定义提示音文件路径 |
| showTorch | Boolean | 否 | 是否显示手电筒按钮 |
| showAlbum | Boolean | 否 | 是否显示相册选择按钮 |
| showBackButton | Boolean | 否 | 是否显示返回按钮 |
| showAni | Boolean | 否 | 是否显示扫码动画 |
| enableZoom | Boolean | 否 | 是否启用手势缩放 |
| initZoomScale | Number | 否 | 初始缩放倍数 |
| title | String | 否 | 页面标题 |
| titleSize | String \| Number | 否 | 标题字号 |
| titleColor | String | 否 | 标题颜色 |
| tip | String | 否 | 提示文本 |
| tipSize | String \| Number | 否 | 提示字号 |
| tipColor | String | 否 | 提示颜色 |
| customTitleStyle | SnStyleValue | 否 | 标题自定义样式 |
| customTipStyle | SnStyleValue | 否 | 提示自定义样式 |

---

# SnSignatureBrush

签名笔触类型。

| 可选值 | 备注 |
| :--- | :--- |
| `default` | 默认 |
| `pen` | 钢笔 |
| `gel` | 中性笔 |
| `pencil` | 铅笔 |
| `marker` | 马克笔 |
| `brush` | 毛笔 |
| `crayon` | 蜡笔 |
| `fur` | 毛皮 |
| `ink` | 墨水 |
| `longfur` | 长绒毛 |
| `ribbon` | 丝带 |
| `shaded` | 阴影 |
| `sketchy` | 速写 |
| `spray` | 喷漆 |
| `squares` | 方格 |
| `circle` | 圆泡 |
| `web` | 蛛网 |

---

# SnSignatureGridStyle

签名板网格样式。可选值：`dot`（点阵）、`square`（方格）、`line`（横线）。

---

# SnStepStatus

步骤条步骤状态。

| 可选值 | 备注 |
| :--- | :--- |
| `wait` | 等待 |
| `finish` | 已完成 |
| `process` | 进行中 |
| `error` | 错误 |

---

# SnTableConfig <Badge type="warning" text="内部使用" />

`sn-table` 向其子组件（`sn-tr`、`sn-td`、`sn-th`）注入的表格样式配置。业务侧只读，请通过 `sn-table` 的属性控制。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| bordered | Boolean | 是 | 是否显示单元格边框 |
| underline | Boolean | 是 | 是否显示单元格下划线 |
| borderColor | String | 是 | 边框与下划线颜色 |
| scrollable | Boolean | 是 | 是否允许横向滚动 |

---

# SnTableCellReport <Badge type="warning" text="内部使用" />

表格单元格向行组件回传的尺寸上报信息，用于计算固定列的偏移量。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| kind | String | 是 | 固定类型，可选值 `left` \| `right` \| `all` |
| width | Number | 是 | 单元格实测宽度（px） |

---

# SnTabbarItem

`sn-tabbar` 标签栏项数据。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| text | String | 否 | 文本 |
| icon | String | 否 | 图标名 |
| image | String | 否 | 图片路径（优先于 icon） |
| activeIcon | String | 否 | 选中态图标名 |
| activeText | String | 否 | 选中态文本 |
| activeImage | String | 否 | 选中态图片路径 |
| interceptor | () => boolean | 否 | 切换拦截器，返回 `false` 阻止切换 |
| badge | [SnBadgeParams](#snbadgeparams) \| null | 否 | 徽标配置 |

---

# SnTabParams

`sn-tabs` 标签项数据。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| text | String | 是 | 标签文本 |
| icon | String | 否 | 图标名 |
| id | String | 是 | 标签唯一 id |
| disabled | Boolean | 否 | 是否禁用 |
| checked | Boolean | 否 | 是否选中 |
| showBadge | Boolean | 否 | 是否显示徽标 |
| badgeConfig | [SnBadgeParams](#snbadgeparams) \| null | 否 | 徽标配置 |

---

# SnTime <Badge type="warning" text="内部使用" />

`sn-timer`、`sn-countdown` 等组件的 `change` 事件返回的时间结构。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| d | Number | 是 | 天 |
| h | Number | 是 | 时 |
| m | Number | 是 | 分 |
| s | Number | 是 | 秒 |
| ms | Number | 是 | 毫秒 |

---

# SnToastParams

`sn-toast` 组件 `show` 方法入参，字段与 [SnShowToastConfig](/api/types/api#snshowtoastconfig) 基本一致（无回调字段），另含 `overlay`（是否显示遮罩）。颜色字段支持 `$` 简写，尺寸字段支持 `$` 动态值与纯数字。

---

# SnTreeData

树形数据集合，即 `sn-tree` 的 `data` 属性类型。

| 类型 | 说明 |
| :--- | :--- |
| [SnTreeItem](#sntreeitem)[] | 树节点列表 |

---

# SnTreeItem

树节点数据。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| id | String | 是 | 节点唯一 id |
| text | String | 是 | 节点显示文本 |
| icon | String | 否 | 节点图标名 |
| activeIcon | String | 否 | 选中态图标名 |
| rotate | Number | 否 | 图标展开旋转角度（deg） |
| disabled | Boolean | 否 | 是否禁用节点 |
| lazy | Boolean | 否 | 是否懒加载子节点（配合 `load-data`） |
| children | [SnTreeItem](#sntreeitem)[] | 否 | 子节点列表 |

---

# SnTreeLoadData

`sn-tree` 的 `load-data` 属性接收 `SnTreeLoadData` 函数：懒加载节点展开时调用，加载成功经 `resolve(children)` 返回子节点，失败调用 `reject()`。

| 类型 | 签名 |
| :--- | :--- |
| SnTreeLoadResolve | (children: [SnTreeData](#sntreedata)) => void |
| SnTreeLoadReject | () => void |
| SnTreeLoadData | (item: [SnTreeItem](#sntreeitem), resolve: [SnTreeLoadResolve](#sntreeloadresolve), reject: [SnTreeLoadReject](#sntreeloadreject)) => void |

---

# SnTreeLoadReject

`sn-tree` 的 `load-data` 回调参数之一：懒加载失败时调用，通知组件结束加载态（由 [SnTreeLoadData](#sntreeloaddata) 的 `reject` 参数使用）。

| 类型 | 签名 |
| :--- | :--- |
| Function | () => void |

---

# SnTreeLoadResolve

`sn-tree` 的 `load-data` 回调参数之一：懒加载成功时调用，传入子节点数据（由 [SnTreeLoadData](#sntreeloaddata) 的 `resolve` 参数使用）。

| 类型 | 签名 |
| :--- | :--- |
| Function | (children: [SnTreeData](#sntreedata)) => void |

---

# SnTypeGroup <Badge type="warning" text="内部使用" />

`sn-list-view` / `sn-waterflow` 内部按 `type` 对列表项分组后的结果，用于在同一列表中以不同布局渲染不同 `type` 的条目。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| type | Number | 是 | 分组类型值（取自列表项的 `type` 字段，缺省为 `0`） |
| entries | [SnTypeGroupEntry](#sntypegroupentry)[] | 是 | 该分组下的条目列表 |

---

# SnTypeGroupEntry <Badge type="warning" text="内部使用" />

`sn-list-view` / `sn-waterflow` 内部打平后的列表条目，承载原始数据及其索引与分组类型。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| item | any | 是 | 原始列表项数据 |
| index | Number | 是 | 该条目在原始 `list` 中的下标 |
| type | Number | 是 | 该条目的分组类型值 |

---

# StepsConfig <Badge type="warning" text="内部使用" />

`sn-steps` 向其子组件（`sn-step`）注入的配置对象，用于统一各步骤的外观与样式。业务侧只读，请通过 `sn-steps` 的属性控制。

| 名称 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| vertical | Boolean | 是 | 是否纵向排列 |
| type | String | 是 | 步骤条类型 |
| selectable | Boolean | 是 | 步骤是否可点击切换 |
| activeColor | String | 是 | 激活态颜色 |
| circleSize | String \| Number | 是 | 步骤圆圈尺寸 |
| textSize | String \| Number | 是 | 标题文字字号 |
| contentSize | String \| Number | 是 | 内容文字字号 |
| stepStyle | SnStyleValue | 是 | 步骤项自定义样式 |
| stepClass | String | 是 | 步骤项外部样式类 |
| titleStyle | SnStyleValue | 是 | 标题自定义样式 |
| titleClass | String | 是 | 标题外部样式类 |
| contentStyle | SnStyleValue | 是 | 内容自定义样式 |
| contentClass | String | 是 | 内容外部样式类 |
| lineStyle | SnStyleValue | 是 | 连接线自定义样式 |
| lineClass | String | 是 | 连接线外部样式类 |

---

# SnSketchpadBrush

画板笔触类型。可选值：`default`、`pen`、`gel`、`pencil`、`marker`、`brush`、`eraser`、`crayon`、`fur`、`ink`、`longfur`、`ribbon`、`shaded`、`sketchy`、`spray`、`squares`、`circle`、`web`。

---

# SnSketchpadGridStyle

画板网格样式。可选值：`dot`（点阵）、`square`（方格）、`line`（横线）。

---

# 其他说明

- 日期时间库类型（`DayutsConfig`、`DayutsUnit`、`DayutsFormats`、`DayutsRelativeTime`、`DayutsLocale`、`DayutsObject`）见 [Date 日期库类型](/libs/date/types)。
- 颜色库类型（`LColorOptions`、`LGenerateOptions`）见 [Color 颜色库类型](/libs/color/types)。
- `PermListener`（权限监听）见 [权限类](/libs/utils/permission#permlistener)。
- `UniError` 错误类型见 [错误处理机制](/api/error/error#unierror)。
- 分组组件的 group config（`CheckboxGroupConfig`、`RadioGroupConfig`、`CollapseConfig`、`StepsConfig`）及其他框架内部自用类型（`SnTableConfig`、`SnTableCellReport`、`SnTypeGroup`、`SnTypeGroupEntry`、`SnCalendarBoundaries`、`SnCalendarSelectionResult` 等）已在上文完整收录，均标记为「内部使用」。

# 错误处理机制

SinleUI 的错误处理完全遵循 [uni 错误规范](https://doc.dcloud.net.cn/uni-app-x/err-spec.html)，统一使用 `UniError` 对象。框架全局 API（`snu.showToast` 等）失败时通过 `fail` 回调返回 `UniError` 实例；主题、风格等设置异常时则输出警告日志。

`UniError` / `SourceError` / `UniAggregateError` 为 uni-app x 运行时内置全局对象，无需导入，直接构造使用：

- `UniError`：统一错误信息，包含 `errSubject` / `errCode` / `errMsg` / `cause` / `data`
- `SourceError`：源错误（如底层 SDK、系统调用、uni API 的原始错误），用作 `UniError.cause`
- `UniAggregateError`：多个 `SourceError` 的聚合，仅存在多个源错误时使用

```typescript
// 构造一个 UniError
const err = new UniError('sinle-ui::component::sn-avatar', 9010011, '参数不合法')
err.cause = new SourceError('底层错误信息')
```

## UniError

### 构造

```typescript
new UniError(errSubject: string, errCode: number, errMsg: string)
```

### 属性

| 名称 | 类型 | 描述 |
| :--- | :--- | :--- |
| errSubject | String | 错误主题（模块）名称。存在多级模块时使用 `::` 分割，即 `模块名称::二级模块名称`。如 sinle-ui 的组件 `sn-avatar` → `'sinle-ui::component::sn-avatar'`；`snu.showToast` → `'sinle-ui::api::utils::showToast'` |
| errCode | Number | 统一错误码，通常 `0` 表示成功。含义见[错误码对照表](/api/error/standard) |
| errMsg | String | 统一错误描述信息，准确描述引起错误的原因 |
| data | Object \| null | 可选，错误时返回的数据 |
| cause | SourceError \| UniAggregateError \| null | 可选，源错误信息。只有一个源错误时为 `SourceError`，多个时为 `UniAggregateError`（访问 `cause.errors` 获取数组） |

## 抛出与降级约定

- 非中断提示、降级、失败回调记录一律使用 `log` / `info` / `debug`；异步失败通过 `fail` 回调返回 `UniError` 实例，插件内部不随意 `throw`。
- 真正的编程性错误（参数非法等）经 sinle-logger 的 `warn(err)` / `error(err)` 输出日志后**抛出**所传入的 `UniError`。
- SinleUI 相关插件（sinle-ui、sinle-api、sn-e-toast、sn-perm-listener 等）统一接入该机制，控制台信息只经 sinle-logger 输出，禁止直接 `console`。

# 日志管理机制

框架（及 SinleUI 相关插件）的日志统一经 `sinle-logger` 插件输出，带 `[Snui]` 前缀，可通过全局开关控制。组件内部禁止直接使用 `console`，控制台信息只经 `sinle-logger` 的 logger 统一管理。

## 日志方法

从 `@/uni_modules/sinle-logger` 导入：

```typescript
import { log, info, debug, warn, error } from '@/uni_modules/sinle-logger'
```

| 名称 | 参数 | 描述 |
| :--- | :--- | :--- |
| log | (message: string) => void | 普通日志（`console.log`） |
| info | (message: string) => void | 信息日志（`console.info`） |
| debug | (message: string) => void | 调试日志（`console.debug`） |
| warn | (err: [UniError](/api/error/error#unierror)) => void | 警告：输出警告日志后**抛出**所传入的 `UniError`（抛出型 API） |
| error | (err: [UniError](/api/error/error#unierror)) => void | 错误：输出错误日志后**抛出**所传入的 `UniError`（抛出型 API） |

> [!WARNING] 注意
>
> `warn` / `error` 是抛出型 API，调用会中断执行流程，仅用于真正的编程性错误（参数非法等）。非中断提示、降级、失败回调记录一律使用 `log` / `info` / `debug`；异步失败通过 `fail` 回调返回 `UniError`。

## 错误码查询

| 名称 | 参数 | 返回值 | 描述 |
| :--- | :--- | :--- | :--- |
| getErrMsg | (errCode: number) | string | 按[错误码对照表](/api/error/standard)查询错误信息，未登记的错误码返回空字符串 |

## 日志开关

| 名称 | 参数 | 返回值 | 描述 |
| :--- | :--- | :--- | :--- |
| setLogging | (val: boolean) => void | - | 开关相关插件日志输出 |
| getLogging | () | boolean | 查询当前是否输出日志 |

框架侧也可通过 `$snui.logging` 读写同一开关：

```typescript
import { $snui } from '@/uni_modules/sinle-ui'

$snui.logging = true
```

# 错误码对照表

SinleUI 相关插件统一错误码与错误信息对照。各 API 失败时返回的 `UniError.errCode` 对应下表，`errMsg` 由各模块按表提供；也可通过 `sinle-logger` 的 `getErrMsg(errCode)` 查询。

| errCode | errMsg                                                       | 含义                                                         |
| ------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 0       | ok                                                           | 成功                                                         |
| 1       | cancel                                                       | 撤销                                                         |
| 3       | system permission denied                                     | 系统权限未授予                                               |
| 1001    | title is empty                                               | 轻提示文本为空（`snu.showToast` 未传入 `text` / `title`，`sn-e-toast` 插件返回） |
| 1002    | show toast failed                                            | 显示轻提示失败（HarmonyOS 原生 Toast 调用失败）              |
| 1300002 | No such file or directory                                    | 找不到文件或目录                                             |
| 9010002 | not support on this platform                                 | 此平台不支持该功能                                           |
| 9010005 | no returned data                                             | 无返回数据                                                   |
| 9010006 | cannot find object "uniCloud", please bind uniCloud first    | 找不到 uniCloud 对象，请先绑定服务空间                       |
| 9010007 | please bind URL first                                        | 请先绑定 URL 地址                                            |
| 9010008 | fail to read file                                            | 读取文件失败                                                 |
| 9010009 | fail to upload file                                          | 文件上传失败                                                 |
| 9010010 | fail to choose file                                          | 选择文件失败                                                 |
| 9010011 | brothers or parent of sn-backtop must be sn-scroll, sn-longlist or sn-page | Backtop 组件同级或父级必须为 sn-scroll/sn-longlist/sn-page；**历史保留**：2.0 起 sn-backtop 不再产出该码   |
| 9010012 | v-model must be a length-2 number[]                          | Slider Double 组件的 `v-model` 属性必须为长度为 2 的 `number[]`；**已废弃**：2.0 的 sn-slider-double 改为静默兜底 |
| 9010013 | id of param feature's item cannot be "menu"                  | Topbar 组件 feature 属性子项 id 不能为“menu”；**已废弃**：sn-topbar 的 feature 属性已改为 menuData                 |
| 9010014 | param "digit" must be a positive integer                     | digits 参数必须为正整数                                      |
| 9010015 | this storeKey already exists, please try another one         | StoreLib 实例的 `storeKey` 不得重复；**已废弃**：Store 状态管理库 2.0 已移除                          |
| 9010016 | upload timeout                                               | `sn-upload-media` 组件上传超时（超时后已中止上传任务）       |
| 9010051 | param "content" not provided                                 | 未提供 `content` 参数；**已废弃**：2.0 起无模块产出                                        |
| 9010052 | param "path" not provided                                    | 未提供 `path` 参数；**已废弃**：2.0 起无模块产出                                           |
| 9010053 | invalid param "path"                                         | `path` 参数提供的路径不合法；**已废弃**：2.0 起无模块产出                                  |
| 9010054 | failed to open dialogPage                                    | 打开弹窗页失败；**已废弃**：已细分为 9010055 / 9010056 / 9010057                                               |
| 9010055 | failed to open modal dialogPage                              | 打开模态框弹窗页失败                                         |
| 9010056 | failed to open actionsheet dialogPage                        | 打开操作菜单弹窗页失败                                       |
| 9010057 | failed to open loading dialogPage                            | 打开加载弹窗页失败                                           |
| 9012001 | Worker 创建失败                                              | `runSort`（sn-sort 插件）的 Worker 子线程创建失败            |
| 9012002 | Worker 运行错误                                              | `runSort`（sn-sort 插件）的 Worker 子线程运行错误，错误详情以 `：` 追加在后 |
| 1602001 | camera permission denied                                     | 相机权限未授予                                               |
| 1602002 | camera initialization failed                                 | 相机初始化失败                                               |
| 1602003 | image scan failed                                            | 图片识别失败                                                 |
| 1602004 | invalid image uri                                            | 图片路径不合法                                               |
| 1602005 | internal error                                               | 内部错误                                                     |

> 说明：标注**历史保留**的错误码在 2.0 源码中已无模块产出、仅为兼容 1.x 保留；标注**已废弃**的错误码对应的能力已在 2.0 移除。二者仍保留在 `sinle-logger` 的错误信息表中，`getErrMsg(errCode)` 可正常查询。

# Button 按钮

> [查看 sn-button 的 2.0 版本差异](/differences/components/sn-button)

## 基础用法

按钮组件，用于触发操作或提交表单。

- 内置五种功能色与四级等级样式，可组合出丰富的视觉表现
- 支持文本、图标与圆形纯图标按钮，以及镂空、虚线边框、加载与禁用等状态
- 支持自定义尺寸、圆角与按下点击态样式

```vue
<template>
	<sn-button type="primary" text="Primary"></sn-button>
</template>
```

**更多演示请下载 demo 查看**

## 平台差异

HarmonyOS 端文字和图标使用独立渲染节点；`loading` 时保留内容占位并隐藏，避免按钮尺寸跳变。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| type | 按钮主题色类型 | String | `primary` | `primary` \| `info` \| `success` \| `error` \| `warning` |
| level | 按钮等级，决定表现程度（first 最重、least 最轻） | String | `first` | `first` \| `second` \| `third` \| `least` |
| size | 按钮尺寸，影响内边距、字号与圆角 | String | `normal` | `small` \| `normal` \| `large` |
| text | 按钮文本内容（未提供默认插槽内容时显示） | String | `''` | - |
| icon | 按钮图标名称，传入后显示图标（sn-icon 图标名） | String | `''` | - |
| iconPosition | 图标位置 | String | `left` | `left` \| `right` |
| shape | 按钮形状，`circle` 时为纯图标圆形按钮，不显示文本 | String | `rect` | `rect` \| `circle` |
| radius | 自定义按钮圆角，`shape` 为 `circle` 时强制全圆角 | String \| Number | `''` | - |
| plain | 是否镂空（透明背景 + 边框样式） | Boolean | `false` | `true` \| `false` |
| dashed | 是否虚线边框（一般配合 `plain` 使用） | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用，禁用后透明度降低且不可点击 | Boolean | `false` | `true` \| `false` |
| loading | 是否加载状态，显示加载遮罩并阻止点击 | Boolean | `false` | `true` \| `false` |
| loadingClass | 加载指示器外部样式类 | String | `''` | - |
| loadingStyle | 加载指示器自定义样式 | SnStyleValue | `` `border-color: ${$snui.colors.primary}` `` | - |
| iconClass | 图标外部样式类 | String | `''` | - |
| iconStyle | 图标自定义样式 | SnStyleValue | `''` | - |
| textClass | 文本外部样式类 | String | `''` | - |
| textStyle | 文本自定义样式 | SnStyleValue | `''` | - |
| hoverStyle | 按下时的点击态样式（如 `background`、`transform: scale(0.94)` 等） | SnStyleValue | `''` | - |
| hoverStopPropagation | 是否阻止点击态的父节点传播 | Boolean | `false` | `true` \| `false` |
| hoverStartTime | 按下后点击态出现的延迟时间（ms） | Number | `0` | - |
| hoverStayTime | 松手后点击态保留的时间（ms） | Number | `0` | - |
| hoverTransTime | 点击态过渡动画时长，支持 `$` 前缀按动画乘数缩放 | String \| Number | `$short` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 自定义根节点样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| click | () => Void | 点击按钮时触发（禁用或加载状态下不触发） |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 替换按钮内部原有的文本内容 |
| body | 替换按钮整体内部内容（含图标与文本），自定义按钮内部布局 |

<DemoPhone name="sn-button" />

# Icon 图标

> [查看 sn-icon 的 2.0 版本差异](/differences/components/sn-icon)

## 基础用法

字体图标组件，内置开源图标库 Remix Icon 全量图标，组件加载时自动注册字体。

- 通过图标名指定要显示的图标
- 图标大小与颜色可配置

::: info 根节点默认拍平

`sn-icon` 根节点默认拍平以提升渲染性能，因此不支持事件与部分样式；需要时请外裹 `view`，详见 [拍平元素不支持的功能或样式](/components/flatten)。

:::

```vue
<template>
	<sn-icon name="home-line"></sn-icon>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| name | 图标名称（Remix Icon 图标名，不需要前缀） | String | - | 参考 [Remix Icon](https://remixicon.com/) |
| size | 图标大小，支持 `$` 简写 | String \| Number | `$16` | - |
| color | 图标颜色，支持 `$` 功能色简写 | String | `var(--sn-text)` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| iconClass | 根节点的外部样式类 | String | - | - |

<DemoPhone name="sn-icon" />

# Image 图片

> [查看 sn-image 的 2.0 版本差异](/differences/components/sn-image)

## 基础用法

增强版图片组件，相比内置 `image` 组件更易用。

- 支持加载占位（可自定义图标、图片或插槽）、图片预览、懒加载与显示动画
- 默认等比适应模式：未设置高度时按图片比例自动计算高度，未设置宽度时平分父容器剩余宽度
- 同时设置宽高后自动高度计算失效

```vue
<template>
	<sn-image src="https://www.example.com/example.png"></sn-image>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| src | 图片路径（网络路径、本地路径皆可） | String | `''` | - |
| width | 图片宽度，平分父容器剩余宽度，支持 `$` 前缀按间距乘数缩放 | String \| Number | - | - |
| height | 图片高度，仅在同时设置 `width` 时生效，支持 `$` 前缀按间距乘数缩放 | String \| Number | `''` | - |
| mode | 图片裁剪、缩放方式，`aspectFit` 且未设置 `height` 时自动按图片比例计算高度 | String | `aspectFit` | `scaleToFill` \| `aspectFit` \| `aspectFill` \| `widthFix` \| `heightFix` \| `top` \| `bottom` \| `center` \| `left` \| `right` \| `top left` \| `top right` \| `bottom left` \| `bottom right` |
| borderRadius | 图片圆角大小，支持 `$` 前缀按圆角乘数缩放 | String \| Number | `$12` | - |
| loadingBgColor | 加载占位块背景颜色 | String | `$info` | - |
| loadingIconColor | 加载占位块中的图标颜色 | String | `$infoDark` | - |
| loadingIcon | 加载占位图标名（未传 `loadingImage` 时显示） | String | `image-line` | - |
| loadingImage | 加载占位图片地址，传入后替代占位图标 | String | `''` | - |
| loadingImageMode | 加载占位图片的裁剪、缩放方式 | String | `aspectFit` | 同 `mode` |
| loadingSize | 加载占位块尺寸，支持 `$` 前缀按间距乘数缩放 | String \| Number | `80px` | - |
| lazyLoad | 图片懒加载，只针对 page 与 scroll-view 下的 image 有效，同内置 `image` 组件 | Boolean | `false` | `true` \| `false` |
| fadeShow | 图片显示动画效果，同内置 `image` 组件 | Boolean | `true` | `true` \| `false` |
| enablePreview | 点击后调用内置的 uni.previewImage 进行图片预览（图片加载失败时不触发） | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义图片容器样式 | SnStyleValue | `''` | - |
| imageStyle | 自定义内部图片（内置 image）样式 | SnStyleValue | `''` | - |
| loadingStyle | 自定义加载占位块样式 | SnStyleValue | `''` | - |
| customClass | 自定义图片容器样式类 | String | `''` | - |
| imageClass | 自定义内部图片样式类 | String | `''` | - |
| loadingClass | 自定义加载占位块样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| error | (event: UniImageErrorEvent) => Void | 图片加载错误时触发 |
| load | (event: UniImageLoadEvent) => Void | 图片加载成功时触发 |
| click | (event: UniPointerEvent) => Void | 点击图片时触发；双击时在 `dbclick` 之前触发 |
| dbclick | (event: UniPointerEvent) => Void | 快速双击图片时触发（300ms 内连续点击两次，在第二次 `click` 后触发） |
| longpress | (event: UniEvent) => Void | 长按图片时触发 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| loading | 替换默认的加载占位图标/图片，可放任意加载动画组件 |

<DemoPhone name="sn-image" />

# Link 链接

> [查看 sn-link 的 2.0 版本差异](/differences/components/sn-link)

## 基础用法

可点击跳转的文本链接，默认以主题深主色显示。

- 支持系统方式打开与内置 Webview 打开两种跳转方式
- 支持前后缀图标，图标大小随链接字号自动匹配
- 支持下划线与自定义按压配色；跳转地址为空时点击不跳转并派发错误事件

```vue
<template>
	<sn-link text="这是一个链接" href="https://www.example.com"></sn-link>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| text | 链接文本内容 | String | `''` | - |
| href | 链接跳转地址，为空时点击触发 `error` 事件 | String | `''` | - |
| prefixIcon | 链接前缀图标名称 | String | `''` | - |
| suffixIcon | 链接后缀图标名称 | String | `''` | - |
| color | 链接文本与图标颜色 | String | `$primaryDark` | - |
| size | 链接文本大小 | String \| Number | `$14` | - |
| underline | 是否显示下划线 | Boolean | `false` | `true` \| `false` |
| hoverBgColor | 按压时背景颜色，设置后显示圆角背景点击态 | String | `''` | - |
| hoverTextColor | 按压时文字与图标颜色 | String | `''` | - |
| local | 是否使用内置 Webview 打开链接 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义链接根节点样式 | SnStyleValue | `''` | - |
| textStyle | 自定义链接文本样式 | SnStyleValue | `''` | - |
| textClass | 链接文本外部类 | String | `''` | - |
| iconStyle | 自定义图标样式 | SnStyleValue | `''` | - |
| iconClass | 图标外部类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| error | (message: string) => Void | `href` 为空时点击触发，参数为错误信息 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 替换链接文本内容 |
| prefix | 替换链接前缀图标 |
| suffix | 替换链接后缀图标 |

<DemoPhone name="sn-link" />

# Text 文本

> [查看 sn-text 的 2.0 版本差异](/differences/components/sn-text)

## 基础用法

文本组件，既支持通过属性传值，也支持通过默认插槽放置内容（使用插槽时优先显示插槽内容）。

- 支持标题、正文、浅色文本与五种功能色等预设文本类型
- 字号、颜色与加粗可自定义
- 可限制最大显示行数，超出部分自动隐藏；也可开启长按选择复制

::: info 根节点默认拍平

`sn-text` 根节点默认拍平以提升渲染性能，因此不支持事件与部分样式；需要时请外裹 `view` 或改用原生 `text`，详见 [拍平元素不支持的功能或样式](/components/flatten)。

:::

```vue
<template>
	<sn-text text="故人西辞黄鹤楼，烟花三月下扬州。"></sn-text>
</template>
```

**更多演示请下载 demo 查看**

## 文本类型

根据场景使用不同类型的文本，更具识别度：

- `title`：标题（字号 16，主题标题色）
- `text`：正文（默认，字号 14，主题文本色）
- `text-light`：浅色辅助文本
- `primary` / `info` / `success` / `warning` / `error`：对应功能色文本

```vue
<template>
	<sn-text type="title" text="登鹳雀楼"></sn-text>
	<sn-text type="text-light" text="王之涣"></sn-text>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| type | 文本类型，决定字号与颜色 | TextType | `text` | `title` \| `text` \| `text-light` \| `primary` \| `info` \| `success` \| `warning` \| `error` |
| text | 文本内容 | String | - | - |
| fontSize | 字体大小，支持 `$` 简写；由 `type` 决定（title 为 `$16`、其余 `$14`） | String \| Number | - | - |
| color | 文本颜色，支持 `$` 功能色简写；由 `type` 决定 | String | - | - |
| bold | 是否加粗 | Boolean | `false` | `true` \| `false` |
| lines | 最大显示行数，超出隐藏；`0` 表示不限制 | Number | `0` | - |
| selectable | 是否可选择（长按复制） | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| textClass | 文本节点的外部样式类 | String | - | - |

## 插槽

| 名称 | 说明 |
| :--- | :--- |
| default | 替换原有的 `text` 文本内容 |

<DemoPhone name="sn-text" />

# View 视图容器

> [查看 sn-view 的 2.0 版本差异](/differences/components/sn-view)

## 基础用法

最基础的视图容器，用于包裹各种元素内容、搭建页面结构，用法与内置 `view` 组件类似。

- 在内置 `view` 之上扩展了区域加载、区域禁用、点击态与丰富的手势事件
- 支持通过属性快速设置背景色、圆角、内边距、外边距与阴影

```vue
<template>
	<sn-view bg-color="$primaryLight" border-radius="$16" padding="14px">
		<sn-text text="一个容器"></sn-text>
	</sn-view>
</template>
```

**更多演示请下载 demo 查看**

## 区域加载与禁用

- `loading` 为 `true` 时覆盖一层半透明遮罩并显示加载指示器，区域内容不可交互，容器尺寸保持不变。
- `disabled` 为 `true` 时屏蔽区域内所有组件的交互，区域整体变淡。

```vue
<template>
	<sn-view :loading="loading" padding="14px">
		<sn-text text="加载中的区域"></sn-text>
	</sn-view>
</template>
```

## 点击态

- 通过 `hover-style`（格式同 `custom-style`）设置按下时应用的样式，松开后平滑恢复。
- `hover-start-time` 控制按下后进入点击态的延迟，`hover-stay-time` 控制松开后点击态保留时长，`hover-trans-time` 控制过渡时长。

```vue
<template>
	<sn-view padding="18px" hover-style="transform:scale(0.95);">
		<sn-text text="按下轻微缩放"></sn-text>
	</sn-view>
</template>
```

## 手势事件

`sn-view` 支持按下（`down`）、单击（`click`）、双击（`dbclick`）、长按（`longpress`）、双指旋转（`rotate`）、双指缩放（`scale`）以及 `touchstart`、`touchmove`、`touchend`、`touchcancel` 触摸事件。

- 指针类事件回调参数为 [SnPointerEvent](/api/types/api#snpointerevent)，包含 `x`、`y` 与原始事件。
- 触摸类事件回调参数为 [SnTouchEvent](/api/types/api#sntouchevent)，其中的每个 `SnTouch` 额外携带 `diffX`、`diffY`（与上次的位移）和 `direction`（`up` / `down` / `left` / `right` / `none`），可直接用于滑动判断。

```vue
<template>
	<sn-view @touchmove="onTouchMove">
		<sn-text text="滑动的方向"></sn-text>
	</sn-view>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| loading | 是否区域加载状态，为 `true` 时覆盖遮罩并显示加载指示器，内容不可交互 | Boolean | `false` | `true` \| `false` |
| disabled | 是否区域禁用状态，为 `true` 时屏蔽区域内所有组件的交互 | Boolean | `false` | `true` \| `false` |
| bgColor | 背景颜色，支持 `$` 功能色简写 | String | - | - |
| borderRadius | 圆角大小，支持 `$` 简写 | String \| Number | - | - |
| margin | 外边距，支持 `$` 简写 | String \| Number | `0` | - |
| padding | 内边距，支持 `$` 简写 | String \| Number | `0` | - |
| boxShadow | 阴影，一般不要设置，uni-app x 的阴影在 App 端时有异常 | String | - | - |
| aniTime | 动画时长，`$` 开头时乘以动画时长乘数 | String \| Number | `$250` | - |
| hoverStyle | 按下时应用的样式，为空时不启用点击态 | SnStyleValue | - | - |
| hoverStopPropagation | 是否阻止点击态扩散到父节点 | Boolean | `false` | `true` \| `false` |
| hoverStartTime | 按下后进入点击态的延迟时间（ms） | Number | `50` | - |
| hoverStayTime | 手指松开后点击态保留时间（ms） | Number | `0` | - |
| hoverTransTime | 进入/退出点击态的过渡时长，取 `aniTime` | String \| Number | - | - |
| loadingStyle | 加载指示器的自定义样式 | SnStyleValue | - | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| loadingClass | 加载指示器的外部样式类 | String | - | - |
| customClass | 根节点的外部样式类 | String | - | - |

## 事件

| 名称 | 类型 | 说明 |
| :--- | :--- | :--- |
| click | (event: `SnPointerEvent`) => Void | 点击事件 |
| dbclick | (event: `SnPointerEvent`) => Void | 双击事件（300ms 内连续点击两次） |
| down | (event: `SnPointerEvent`) => Void | 按下事件 |
| longpress | (event: `SnTouchEvent`) => Void | 长按事件 |
| touchstart | (event: `SnTouchEvent`) => Void | 手指落下事件 |
| touchmove | (event: `SnTouchEvent`) => Void | 手指移动事件 |
| touchend | (event: `SnTouchEvent`) => Void | 手指抬起事件 |
| touchcancel | (event: `SnTouchEvent`) => Void | 触摸打断事件 |
| rotate | (event: `SnRotateEvent`) => Void | 双指旋转事件，degree 为相对上一次旋转事件的角度增量（deg），顺时针为正 |
| scale | (event: `SnScaleEvent`) => Void | 双指缩放手势事件，zoom 为相对上一次缩放事件的倍数 |

> 类型字段：SnPointerEvent（见 https://sinleui.pages.dev/api/types/component#snpointerevent）

> 类型字段：SnRotateEvent（见 https://sinleui.pages.dev/api/types/component#snrotateevent）

> 类型字段：SnScaleEvent（见 https://sinleui.pages.dev/api/types/component#snscaleevent）

> 类型字段：SnTouchEvent（见 https://sinleui.pages.dev/api/types/component#sntouchevent）


:::

## 插槽

| 名称 | 说明 |
| :--- | :--- |
| default | 在这里放置内容 |

<DemoPhone name="sn-view" />

# Rate 评分

> [查看 sn-rate 的 2.0 版本差异](/differences/components/sn-rate)

## 基础用法

评分组件，通过点击图标（默认星星）打分。

- 评分值支持双向绑定，支持半星评分与再次点击当前值清零
- 图标数量、图标样式与颜色均可自定义
- 只读模式采用单文本双层渲染，性能高、适合长列表，且支持小数与超限数值

```vue
<template>
	<sn-rate v-model="value"></sn-rate>
</template>

<script lang="ts" setup>
const value = ref<number>(3)
</script>
```

**更多演示请下载 demo 查看**

## 半星与清除

开启 `allow-half` 后，点击图标左半部分计半星、右半部分计整星；开启 `clearable` 后，再次点击当前评分值可清零：

```vue
<template>
	<sn-rate v-model="value" allow-half clearable></sn-rate>
</template>
```

## 自定义图标与颜色

图标名称使用 remixicon 图标名；`active-icon` 不传时选中图标与 `icon` 相同：

```vue
<template>
	<sn-rate v-model="value" icon="heart-3-fill" active-color="$error"></sn-rate>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 当前选中的评分值 | Number | `0` | - |
| count | 总评分（图标）数量 | Number | `5` | - |
| readonly | 是否为只读状态，只读时不可点击 | Boolean | `false` | `true` \| `false` |
| clearable | 是否允许再次点击当前评分值清零 | Boolean | `false` | `true` \| `false` |
| allowHalf | 是否允许半星评分 | Boolean | `false` | `true` \| `false` |
| spacing | 图标之间的间距 | String \| Number | `5px` | - |
| inactiveColor | 未选中图标的颜色 | String | `$infoDark` | 任意色值或 `$` 主题色简写 |
| activeColor | 选中图标的颜色 | String | `$warning` | 任意色值或 `$` 主题色简写 |
| icon | 默认（未选中）图标名称 | String | `star-fill` | `remixicon 图标名` |
| iconSize | 图标大小 | String \| Number | `$20` | - |
| activeIcon | 选中图标的名称，与 `icon` 相同 | String | - | `remixicon 图标名` |
| halfIcon | 半星图标的名称（`allow-half` 时使用） | String | `star-half-fill` | `remixicon 图标名` |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: Number) => Void | 当前评分值变化时触发，携带新值 |

<DemoPhone name="sn-rate" />

# Slider 滑动选择

> [查看 sn-slider 的 2.0 版本差异](/differences/components/sn-slider)

## 基础用法

滑动选择器，通过拖动滑块在一个数值区间内选择数值。

- 支持横向与竖向、自定义范围与步长、显示当前值文本
- 绑定值会自动夹取到范围区间并按步长取整
- 点击轨道任意位置可快速定位到该处

::: info 区间选择
需要选择一个数值区间（双向滑块）时，请使用 `sn-slider-double`。
:::

```vue
<template>
	<sn-slider v-model="value"></sn-slider>
</template>

<script lang="ts" setup>
const value = ref<number>(30)
</script>
```

**更多演示请下载 demo 查看**

激活条保留真实圆角，滑块大于轨道粗细时允许滑块溢出显示。按下 thumb 时会显示一个浅灰半透明外圈，直径取 thumb 与轨道粗细中的较大值再加 `6px`（保证 thumb 嵌入轨道时外圈比轨道略大、清晰可见），外圈圆角在 thumb 圆角基础上同步外扩（thumb 为全圆角时外圈即为同心圆），松手后淡出；拖动过程中不重复测量轨道，激活条的宽度/高度与 thumb 的位置均通过 DOM 直写更新，thumb 与外圈的 transform 均强制使用 `0ms`。外圈的显隐过渡遵循 `--ani-time-*` 与 `aniTimeFactor`，设置 `show-glow` 为 `false` 可关闭该光晕。

## 竖向滑动

`vertical` 为 `true` 时竖向显示，父容器需要给定高度：

```vue
<template>
	<view style="height: 200px;">
		<sn-slider v-model="value" vertical></sn-slider>
	</view>
</template>
```

## 显示当前值

开启 `show-value-text` 后会在组件右侧（竖向时为下方）显示当前值：

```vue
<template>
	<sn-slider v-model="value" show-value-text :min="10" :max="60" :step="5"></sn-slider>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定当前值（自动夹取到 `[min, max]` 并按 `step` 取整） | Number | `0` | - |
| vertical | 是否为竖向滑动选择器 | Boolean | `false` | `true` \| `false` |
| min | 最小值 | Number | `0` | - |
| max | 最大值 | Number | `100` | - |
| step | 步长，取值按步长取整 | Number | `1` | - |
| disabled | 是否禁用，禁用后轨道与激活条呈禁用色且不可交互 | Boolean | `false` | `true` \| `false` |
| activeColor | 激活部分（进度）颜色 | String | `$primary` | 任意色值或 `$` 主题色简写 |
| inactiveColor | 轨道未激活部分颜色 | String | `$infoActive` | 任意色值或 `$` 主题色简写 |
| thickness | 轨道粗细 | String \| Number | `20px` | - |
| borderRadius | 轨道圆角，自动取轨道粗细的一半（全圆角） | String \| Number | - | - |
| thumbBorderRadius | 滑块圆角，自动取滑块尺寸的一半（全圆角） | String \| Number | - | - |
| thumbBorder | 滑块边框（CSS border 值，如 `2px solid #ffffff`） | String | `''` | - |
| thumbSize | 滑块尺寸 | String \| Number | `10px` | - |
| showGlow | 是否显示按下 thumb 时的拖拽光晕 | Boolean | `true` | `true` \| `false` |
| showValueText | 是否在右侧/下方显示当前值文本 | Boolean | `false` | `true` \| `false` |
| valueTextWidth | 当前值文本宽度 | String \| Number | `30px` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |
| trackClass | 轨道的外部样式类 | String | `''` | - |
| trackStyle | 轨道自定义样式 | SnStyleValue | `''` | - |
| activeClass | 激活条的外部样式类 | String | `''` | - |
| activeStyle | 激活条自定义样式 | SnStyleValue | `''` | - |
| thumbClass | 滑块的外部样式类 | String | `''` | - |
| thumbStyle | 滑块自定义样式 | SnStyleValue | `''` | - |
| valueTextClass | 值文本的外部样式类 | String | `''` | - |
| valueTextStyle | 值文本自定义样式 | SnStyleValue | `''` | - |

尺寸类属性支持 `$` 前缀动态尺寸（乘对应乘数），如 `thumb-size="$14"`。

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: Number) => Void | 拖动松手后触发，携带最终值（拖动过程中不触发，外部赋值不触发） |

<DemoPhone name="sn-slider" />

# SliderDouble 双向滑动选择

## 基础用法

双向（区间）滑动选择器，轨道上有两个滑块，绑定长度为 2 的数值数组表示区间 `[较小值, 较大值]`。

- 拖动需按住滑块，拖动结束时若两值交叉会自动交换排序，保证数组前项小于等于后项
- 支持竖向、范围与步长、显示值文本与自定义样式
- 其余表现与 `sn-slider` 一致

```vue
<template>
	<sn-slider-double v-model="range"></sn-slider-double>
</template>

<script lang="ts" setup>
const range = ref<number[]>([20, 40])
</script>
```

**更多演示请下载 demo 查看**

激活条保留真实圆角，滑块大于轨道粗细时允许滑块溢出显示。按下任一 thumb 时才显示与其圆角同心外扩的浅灰半透明外圈，直径取 thumb 与轨道粗细中的较大值再加 `6px`（保证 thumb 嵌入轨道时外圈比轨道略大、清晰可见），松手后淡出；拖动过程中不重复测量轨道，激活条的尺寸/位置与两个滑块的位置均通过 DOM 直写更新，thumb 与外圈的 transform 均强制使用 `0ms`；外圈显隐过渡遵循 `--ani-time-*` 与 `aniTimeFactor`，设置 `show-glow` 为 `false` 可关闭该光晕。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定区间值（两项分别为区间两端，自动按序排列并夹取到 `[min, max]`） | `Array<Number>` | `[0, 0]` | - |
| vertical | 是否为竖向滑动选择器 | Boolean | `false` | `true` \| `false` |
| min | 最小值 | Number | `0` | - |
| max | 最大值 | Number | `100` | - |
| step | 步长，取值按步长取整 | Number | `1` | - |
| disabled | 是否禁用，禁用后轨道与激活条呈禁用色且不可交互 | Boolean | `false` | `true` \| `false` |
| activeColor | 激活部分（两滑块之间）颜色 | String | `$primary` | 任意色值或 `$` 主题色简写 |
| inactiveColor | 轨道未激活部分颜色 | String | `$infoActive` | 任意色值或 `$` 主题色简写 |
| thickness | 轨道粗细 | String \| Number | `20px` | - |
| borderRadius | 轨道圆角，自动取轨道粗细的一半（全圆角） | String \| Number | - | - |
| thumbBorderRadius | 滑块圆角，自动取滑块尺寸的一半（全圆角） | String \| Number | - | - |
| thumbBorder | 滑块边框（CSS border 值，如 `2px solid #ffffff`） | String | `''` | - |
| thumbSize | 滑块尺寸 | String \| Number | `10px` | - |
| showGlow | 是否显示按下 thumb 时的拖拽光晕 | Boolean | `true` | `true` \| `false` |
| showValueText | 是否在右侧/下方显示当前区间文本（格式如 `20 - 40`） | Boolean | `false` | `true` \| `false` |
| valueTextWidth | 区间文本宽度 | String \| Number | `30px` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |
| trackClass | 轨道的外部样式类 | String | `''` | - |
| trackStyle | 轨道自定义样式 | SnStyleValue | `''` | - |
| activeClass | 激活条的外部样式类 | String | `''` | - |
| activeStyle | 激活条自定义样式 | SnStyleValue | `''` | - |
| thumbClass | 滑块的外部样式类（两个滑块共用） | String | `''` | - |
| thumbStyle | 滑块自定义样式（两个滑块共用） | SnStyleValue | `''` | - |
| valueTextClass | 值文本的外部样式类 | String | `''` | - |
| valueTextStyle | 值文本自定义样式 | SnStyleValue | `''` | - |

绑定数组长度不为 2 时，组件会自动重置为 `[min, min]`。尺寸类属性支持 `$` 前缀动态尺寸（乘对应乘数）。

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | `(value: Array<Number>) => Void` | 拖动松手后触发，携带排序后的最终区间值（拖动过程中不触发，外部赋值不触发） |

# ArcSlider 环形滑块

## 基础用法

沿圆弧拖动的滑动选择器，用于角度或数值选择。

- 支持自定义弧的起止角度，设为 0 与 360 即为完整圆形轨道
- 支持色相环模式，颜色随取值映射并支持双向绑定
- 中间区域默认显示当前值，可用插槽完全自定义

::: info 端点行为
在接近整圆的长弧段上触摸或拖动时，滑块按触点相对圆心的位置定位；再次按住当前圆点不会因角度跨越 0° 而跳到其他位置。
:::

```vue
<template>
	<sn-arc-slider v-model="value"></sn-arc-slider>
</template>

<script lang="ts" setup>
const value = ref<number>(36)
</script>
```

**更多演示请下载 demo 查看**

## 范围与步长

```vue
<template>
	<sn-arc-slider v-model="temperature" :min="16" :max="30" :step="0.5" size="$180" stroke-color="$warning"></sn-arc-slider>
</template>
```

## 色环取色

`is-hue` 开启后，可直接给 `v-model:color` 绑定一个颜色值，组件会反推出对应的色相位置：

```vue
<template>
	<sn-arc-slider v-model="hue" v-model:color="color" is-hue size="$190" @color-change="onColorChange"></sn-arc-slider>
</template>

<script lang="ts" setup>
const hue = ref<number>(210)
const color = ref<string>('#0080FF')

function onColorChange(color: string): void {
	console.log(color)
}
</script>
```

## 自定义中间内容

通过 `value` 插槽替换中间区域，作用域参数：`value`（当前值）、`color`（当前颜色）、`hex`（hue 模式下的 hex 文本，非 hue 模式为空字符串）：

```vue
<template>
	<sn-arc-slider v-model="value">
		<template #value="{ value, color }">
			<sn-text :text="`${value}`" :color="color" bold></sn-text>
		</template>
	</sn-arc-slider>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定当前值（自动夹取到 `[min, max]` 并按 `step` 取整） | Number | `0` | - |
| v-model:color | hue 模式下绑定颜色值（hex），赋值会反推色相位置 | String | `''` | - |
| size | 组件尺寸（正方形边长） | String \| Number | `$200` | - |
| startAngle | 轨道起始角度（度，0° 为正右方，顺时针为正） | Number | `-225` | - |
| endAngle | 轨道结束角度 | Number | `45` | - |
| lineCap | 轨道端点形状（完整圆形轨道时强制为 `butt`） | String | `round` | `butt` \| `round` \| `square` |
| strokeWidth | 进度弧粗细 | String \| Number | `$20` | - |
| strokeColor | 进度弧颜色 | String | `$primary` | 任意色值或 `$` 主题色简写 |
| trailWidth | 轨道粗细 | String \| Number | `$20` | - |
| trailColor | 轨道颜色 | String | `$line` | 任意色值或 `$` 主题色简写 |
| dotSize | 圆点（滑块）直径 | String \| Number | `$12` | - |
| dotBgColor | 圆点背景颜色 | String | `$front` | 任意色值或 `$` 主题色简写 |
| dotBorderColor | 圆点描边颜色 | String | `$line` | 任意色值或 `$` 主题色简写 |
| dotBorderWidth | 圆点描边宽度，为 `0` 时不绘制描边 | String \| Number | `0` | - |
| min | 最小值 | Number | `0` | - |
| max | 最大值 | Number | `100` | - |
| step | 步长 | Number | `1` | - |
| isHue | 是否为色环模式（取值映射到 0° - 360° 色相，轨道绘制为完整色环） | Boolean | `false` | `true` \| `false` |
| showValueText | 是否显示中间默认内容（当前值；hue 模式为颜色球与 hex 文本） | Boolean | `true` | `true` \| `false` |
| disabled | 是否禁用，禁用后半透明且不响应拖动 | Boolean | `false` | `true` \| `false` |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部样式类 | String | `''` | - |

尺寸类属性支持 `$` 前缀动态尺寸（乘对应乘数）。

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: Number) => Void | 拖动过程中值变化时实时触发，携带新值 |
| color-change | (color: String) => Void | hue 模式下拖动过程中颜色变化时实时触发，携带 hex 颜色值 |

`change` / `color-change` 在拖动过程中实时触发；`v-model` 与 `v-model:color` 则在松手时才提交最终值。

## 插槽

| 名称 | 说明 |
| --- | --- |
| value | 自定义组件中间区域内容，替换默认的值/颜色球显示。作用域参数：`value`（当前值）、`color`（当前颜色）、`hex`（hex 文本，非 hue 模式为空字符串） |

<DemoPhone name="sn-arc-slider" />

# Switch 开关

> [查看 sn-switch 的 2.0 版本差异](/differences/components/sn-switch)

## 基础用法

开关选择器，点击在开 / 关之间切换，小球带滑动动画。

- 绑定值为布尔类型
- 支持禁用与加载状态：禁用或加载中时点击不切换，加载中会在小球内显示加载动画
- 支持轨道内显示文本与图标，开 / 关与禁用状态各有独立配色，尺寸、间隙与圆角可自定义

```vue
<template>
	<sn-switch v-model="value"></sn-switch>
</template>

<script lang="ts" setup>
const value = ref<boolean>(false)
</script>
```

**更多演示请下载 demo 查看**

## 自定义内容

通过 `text` 与 `icon` 可在轨道内显示文本、图标，按需加大 `width`：

```vue
<template>
	<sn-switch v-model="value" text="开" icon="star-fill" width="60px"></sn-switch>
</template>

<script lang="ts" setup>
const value = ref<boolean>(false)
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值，当前开关状态 | Boolean | `false` | `true` \| `false` |
| width | 开关宽度 | String \| Number | `'50px'` | - |
| height | 开关高度 | String \| Number | `'25px'` | - |
| text | 轨道内文本内容 | String | `''` | - |
| icon | 轨道内图标名称 | String | `''` | - |
| iconSize | 轨道内图标大小 | String \| Number | `$12` | - |
| padding | 小球与轨道内边缘的间隙 | String \| Number | `'5px'` | - |
| borderRadius | 轨道圆角，取高度一半呈胶囊形 | String \| Number | - | - |
| bgColor | 关闭状态轨道背景颜色 | String | `'$line'` | - |
| activeBgColor | 开启状态轨道背景颜色 | String | `'$primary'` | - |
| disabledBgColor | 禁用且关闭时轨道背景颜色 | String | `'$disabled'` | - |
| disabledActiveBgColor | 禁用且开启时轨道背景颜色 | String | `'$disabledDark'` | - |
| blockColor | 关闭状态小球颜色 | String | `'#fff'` | - |
| activeBlockColor | 开启状态小球颜色 | String | `'#fff'` | - |
| disabledBlockColor | 禁用且关闭时小球颜色 | String | `'#fff'` | - |
| disabledActiveBlockColor | 禁用且开启时小球颜色 | String | `'#fff'` | - |
| blockBorderRadius | 小球圆角，取小球尺寸一半呈圆形 | String \| Number | - | - |
| textColor | 轨道内文本颜色 | String | `'#fff'` | - |
| textSize | 轨道内文本大小 | String \| Number | `$12` | - |
| loading | 是否处于加载状态（小球内显示加载动画，期间不可点击） | Boolean | `false` | `true` \| `false` |
| loadingClass | 加载动画的外部样式类 | String | `''` | - |
| loadingStyle | 自定义加载动画样式 | SnStyleValue | `''` | - |
| disabled | 是否禁用开关 | Boolean | `false` | `true` \| `false` |
| thumbClass | 小球的外部样式类 | String | `''` | - |
| thumbStyle | 自定义小球样式 | SnStyleValue | `''` | - |
| customStyle | 自定义开关根节点样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: boolean) => Void | 状态改变时触发，携带切换后的新值 |

<DemoPhone name="sn-switch" />

# SwitchButton 切换按钮

## 基础用法

可切换选中状态的按钮，内部基于 `sn-button` 扩展。

- 绑定布尔值，点击在选中与未选中之间切换
- 选中态与未选中态各自拥有独立配色，可用等级机制组合，也可直接指定两态的背景色与文字色
- 支持两态不同文案与图标、加载与禁用状态，以及文本、图标的外部样式扩展

::: tip 文本传参
文本请统一通过 `text` / `active-text` 传入（组件不透传插槽）。子组件 `sn-button` 以 `$slots.default != null` 判定插槽，若向上层透传空插槽会导致文本属性被忽略、按钮显示为空。
:::

```vue
<template>
	<sn-switch-button v-model="value" text="关注" active-text="已关注" active-type="success"
		active-level="second"></sn-switch-button>
</template>

<script lang="ts" setup>
const value = ref<boolean>(false)
</script>
```

**更多演示请下载 demo 查看**

## 两态配色（type / level）

未选中态与选中态分别由 `type` + `level` 与 `active-type` + `active-level` 决定，四级 `level` 的表现程度与 `sn-button` 一致：

| level | 背景色 | 文字色 |
| --- | --- | --- |
| `first` | 功能色原色 | 功能色背景上的文字色 |
| `second` | 功能色浅色（Light） | 功能色原色 |
| `third` | `info` 信息色 | 功能色原色 |
| `least` | 透明 | 功能色原色 |

```vue
<template>
	<sn-switch-button v-model="value" type="info" level="second" active-type="primary" active-level="first"></sn-switch-button>
	<sn-switch-button v-model="value2" type="primary" level="least" active-type="primary" active-level="first"></sn-switch-button>
</template>

<script lang="ts" setup>
const value = ref<boolean>(false)
const value2 = ref<boolean>(true)
</script>
```

## 自定义两态颜色

直接传入颜色属性即可覆盖等级配色，两态的颜色互不影响，可只覆盖其中一态。颜色值支持 `$` 简写（如 `$primary`、`$textLight`），也可传入 `#rrggbb`、`rgb()`、`rgba()` 等常规颜色值：

```vue
<template>
	<sn-switch-button v-model="value" text="关注" active-text="已关注" bg-color="rgba(124,92,255,0.15)"
		text-color="#7c5cff" active-bg-color="#7c5cff" active-text-color="#ffffff"></sn-switch-button>
</template>

<script lang="ts" setup>
const value = ref<boolean>(false)
</script>
```

## 镂空（plain）

`plain` 为 `true` 时背景固定为透明，只保留边框与文字：文字与边框取当前态（未选中取 `type`、选中取 `active-type`）的功能色**原色**，不会取"功能色背景上的文字色"，因此在透明背景上始终可见；`active-level` 不再影响镂空态的文字色。

```vue
<template>
	<sn-switch-button v-model="value" plain text="镂空" border-color="$line" text-color="$textLight"
		active-type="primary" active-level="first"></sn-switch-button>
</template>
```

可用 `border-color` / `active-border-color` 分别覆盖两态边框色（上例未选中为浅灰描边、选中为蓝色描边，状态切换一目了然）；`dashed` 可将边框改为虚线。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值，当前是否选中 | Boolean | `false` | `true` \| `false` |
| type | 未选中态功能色类型 | String | `info` | `primary` \| `info` \| `success` \| `error` \| `warning` |
| level | 未选中态等级，决定表现程度（first 最重、least 最轻） | String | `second` | `first` \| `second` \| `third` \| `least` |
| activeType | 选中态功能色类型 | String | `primary` | `primary` \| `info` \| `success` \| `error` \| `warning` |
| activeLevel | 选中态等级 | String | `first` | `first` \| `second` \| `third` \| `least` |
| text | 未选中态文本内容 | String | `''` | - |
| activeText | 选中态文本内容，沿用 `text` | String | - | - |
| bgColor | 未选中态背景颜色，传入后覆盖等级配色 | String | `''` | - |
| activeBgColor | 选中态背景颜色，传入后覆盖等级配色 | String | `''` | - |
| textColor | 未选中态文字与图标颜色 | String | `''` | - |
| activeTextColor | 选中态文字与图标颜色 | String | `''` | - |
| borderColor | 未选中态边框颜色，取该态功能色原色 | String | - | - |
| activeBorderColor | 选中态边框颜色，取该态功能色原色 | String | - | - |
| size | 按钮尺寸，影响内边距、字号与圆角 | String | `normal` | `small` \| `normal` \| `large` |
| shape | 按钮形状，`circle` 时为纯图标圆形按钮 | String | `rect` | `rect` \| `circle` |
| icon | 图标名称（sn-icon 图标名） | String | `''` | - |
| iconPosition | 图标位置 | String | `left` | `left` \| `right` |
| iconSize | 图标大小 | String \| Number | `''` | - |
| radius | 自定义按钮圆角 | String \| Number | `''` | - |
| plain | 是否镂空（透明背景 + 边框样式） | Boolean | `false` | `true` \| `false` |
| dashed | 是否虚线边框（一般配合 `plain` 使用） | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用，禁用后不可切换 | Boolean | `false` | `true` \| `false` |
| loading | 是否加载状态，显示加载遮罩并阻止切换 | Boolean | `false` | `true` \| `false` |
| loadingStyle | 加载指示器自定义样式 | SnStyleValue | `''` | - |
| hoverStyle | 按下时的点击态样式 | SnStyleValue | `''` | - |
| hoverStopPropagation | 是否阻止点击态的父节点传播 | Boolean | `false` | `true` \| `false` |
| hoverStartTime | 按下后点击态出现的延迟时间（ms） | Number | `0` | - |
| hoverStayTime | 松手后点击态保留的时间（ms） | Number | `0` | - |
| hoverTransTime | 点击态过渡动画时长，支持 `$` 前缀 | String \| Number | `''` | - |
| textClass | 文本外部样式类 | String | `''` | - |
| textStyle | 文本自定义样式 | SnStyleValue | `''` | - |
| iconClass | 图标外部样式类 | String | `''` | - |
| iconStyle | 图标自定义样式 | SnStyleValue | `''` | - |
| customStyle | 自定义根节点（按钮本体）样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| click | () => Void | 点击按钮时触发（禁用或加载状态下不触发） |
| change | (value: boolean) => Void | 选中状态改变时触发，携带切换后的新值 |

<DemoPhone name="sn-switch-button" />

# Stepper 步进器

> [查看 sn-stepper 的 2.0 版本差异](/differences/components/sn-stepper)

## 基础用法

步进器，由减按钮、数值输入框与加按钮组成。

- 点击按钮或直接输入均可改变数值，数值支持双向绑定
- 支持范围与步长（步长支持小数）、长按连续增减、禁用输入与整体禁用
- 失焦或键盘确认时提交输入：非法输入恢复为当前值，合法输入自动夹取并按步长格式化

```vue
<template>
	<sn-stepper v-model="value"></sn-stepper>
</template>

<script lang="ts" setup>
const value = ref<number>(0)
</script>
```

**更多演示请下载 demo 查看**

## 范围与步长

`step` 为小数时输入框自动切换为小数键盘，并按小数位数格式化显示；`max` 不设置（默认 `NaN`）表示无上限：

```vue
<template>
	<sn-stepper v-model="value" :min="5" :max="25" :step="5"></sn-stepper>
	<sn-stepper v-model="value2" :min="0" :max="10" :step="0.5"></sn-stepper>
</template>
```

## 长按连续增减

`longpress` 默认开启：按住按钮 500ms 后开始连续增减（每 100ms 一步），到达边界自动停止：

```vue
<template>
	<sn-stepper v-model="value" :max="50"></sn-stepper>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定当前值 | Number | `0` | - |
| size | 按钮（及输入框）边长 | String \| Number | `30px` | - |
| spacing | 按钮与输入框之间的间距 | String \| Number | `2px` | - |
| inputWidth | 输入框宽度 | String \| Number | `50px` | - |
| textSize | 文本大小 | String \| Number | `$14` | - |
| textColor | 按钮符号与输入框文本颜色 | String | `$text` | 任意色值或 `$` 主题色简写 |
| inputTextColor | 输入框文本颜色，取 `textColor` | String | - | 任意色值或 `$` 主题色简写 |
| disabledTextColor | 禁用状态文本颜色 | String | `$disabledText` | 任意色值或 `$` 主题色简写 |
| inputBgColor | 输入框背景颜色 | String | `$info` | 任意色值或 `$` 主题色简写 |
| inputActiveBgColor | 输入框聚焦激活背景颜色 | String | `$info` | 任意色值或 `$` 主题色简写 |
| disabledBgColor | 禁用状态输入框背景颜色 | String | `$disabled` | 任意色值或 `$` 主题色简写 |
| buttonBgColor | 按钮背景颜色，留空时为描边样式按钮 | String | `''` | 任意色值或 `$` 主题色简写 |
| borderRadius | 按钮、输入框圆角 | String \| Number | `$8` | - |
| min | 最小值 | Number | `0` | - |
| max | 最大值，`NaN` 表示无上限 | Number | `NaN` | - |
| step | 步长（支持小数，显示按其小数位格式化） | Number | `1` | - |
| longpress | 是否开启长按连续增减 | Boolean | `true` | `true` \| `false` |
| disableInput | 是否禁用输入框（仅能通过按钮增减） | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用整个步进器 | Boolean | `false` | `true` \| `false` |
| placeholder | 输入框占位文本 | String | `''` | - |
| maxlength | 输入框最大输入长度，`-1` 表示不限制 | String \| Number | `-1` | - |
| showBorder | 输入框是否显示边框 | Boolean | `false` | `true` \| `false` |
| borderColor | 输入框边框颜色 | String | `''` | 任意色值或 `$` 主题色简写 |
| activeBorderColor | 输入框激活状态边框颜色 | String | `''` | 任意色值或 `$` 主题色简写 |
| borderWidth | 输入框边框宽度 | String \| Number | `2` | - |
| textFont | 输入框文本字体 | String | `''` | - |
| cursorColor | 输入框光标颜色 | String | `''` | 任意色值或 `$` 主题色简写 |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |

尺寸类属性支持 `$` 前缀动态尺寸（乘对应乘数）。

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: Number) => Void | 数值变化时触发，携带新值（按钮点击、长按连续增减、输入提交均会触发） |

<DemoPhone name="sn-stepper" />

# Input 输入框

> [查看 sn-input 的 2.0 版本差异](/differences/components/sn-input)

## 基础用法

基于内置 `input` 组件封装的输入框，输入内容支持双向绑定。

- 内置聚焦激活态、禁用与只读配色、加载状态、清除按钮与密码明密文切换
- 支持前后置图标并在点击时派发对应事件，也可用插槽自定义前后缀内容

::: info $ 简写
尺寸与颜色属性支持 `$` 简写（如 `border-radius="$16"`、`bg-color="$info"`），随风格乘数与主题自动缩放换色。
:::

```vue
<template>
	<sn-input v-model="value" placeholder="请输入内容"></sn-input>
</template>

<script lang="ts" setup>
const value = ref<string>('')
</script>
```

**更多演示请下载 demo 查看**

## 密码输入

设置 `password` 后输入内容以密文显示，右侧自动出现明文/密文切换按钮，点击即可切换显示。

```vue
<template>
	<sn-input v-model="pwd" password placeholder="请输入密码"></sn-input>
</template>

<script lang="ts" setup>
const pwd = ref<string>('')
</script>
```

## 自定义样式

通过 `customStyle` 定制根容器，`inputStyle` 内联作用于输入框本体，前后图标可用 `prefixIconClass` / `suffixIconClass`（外部类）或 `prefixIconStyle` / `suffixIconStyle`（内联样式）定制。

```vue
<template>
	<sn-input v-model="value" input-style="font-size: 18px; font-weight: bold;"
		prefix-icon="search-line" prefix-icon-style="color: #f56c6c;"
		placeholder="大字加粗 + 红色图标"></sn-input>
</template>

<script lang="ts" setup>
const value = ref<string>('')
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值 | String | `''` | - |
| name | 表单的控件名称，作为键值对的一部分与表单一同提交 | String | `''` | - |
| type | 输入框类型 | String | `text` | `text` \| `number` \| `digit` \| `tel` \| `idcard` \| `nickname` |
| password | 是否密码类型，为 true 时右侧显示明文/密文切换按钮 | Boolean | `false` | `true` \| `false` |
| placeholder | 输入框为空时的占位符 | String | `''` | - |
| placeholderStyle | 占位符内联样式 | String | `''` | - |
| placeholderClass | 占位符外部类 | String | `''` | - |
| maxlength | 最大输入长度，`-1` 表示不限制 | String \| Number | `-1` | - |
| focus | 获取焦点 | Boolean | `false` | `true` \| `false` |
| autoFocus | 自动获取焦点，与 `focus` 相比只在首次生效 | Boolean | `false` | `true` \| `false` |
| cursor | 指定聚焦时的光标位置，`-1` 表示不指定 | String \| Number | `-1` | - |
| cursorColor | 光标颜色 | String | `$primary` | - |
| cursorSpacing | 光标与键盘的距离（px） | String \| Number | `0` | - |
| selectionStart | 光标起始位置，自动聚焦时有效，需与 `selectionEnd` 搭配 | String \| Number | `-1` | - |
| selectionEnd | 光标结束位置，自动聚焦时有效，需与 `selectionStart` 搭配 | String \| Number | `-1` | - |
| confirmType | 键盘右下角按钮的文字 | String | `done` | `send` \| `search` \| `next` \| `go` \| `done` |
| confirmHold | 点击键盘右下角按钮时是否保持键盘不收起 | Boolean | `false` | `true` \| `false` |
| holdKeyboard | 聚焦时点击页面不收起键盘 | Boolean | `false` | `true` \| `false` |
| adjustPosition | 键盘弹起时是否自动上推页面 | Boolean | `true` | `true` \| `false` |
| controlled | 是否为受控属性（原生 input 的 controlled） | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用，禁用后不可输入且背景、文字使用禁用配色 | Boolean | `false` | `true` \| `false` |
| readonly | 是否只读，只读时颜色不变 | Boolean | `false` | `true` \| `false` |
| loading | 是否加载中，右侧显示加载指示器（延迟 100ms 显示避免闪烁） | Boolean | `false` | `true` \| `false` |
| loadingClass | 加载指示器外部类 | String | `''` | - |
| loadingStyle | 加载指示器样式 | SnStyleValue | `''` | - |
| clearable | 是否显示清除按钮（有内容且非禁用/只读时显示，点击清空） | Boolean | `false` | `true` \| `false` |
| showBorder | 是否显示边框 | Boolean | `true` | `true` \| `false` |
| showActiveBorder | 聚焦时是否切换为激活边框颜色 | Boolean | `true` | `true` \| `false` |
| borderColor | 边框颜色 | String | `'$line'` | - |
| activeBorderColor | 聚焦时的边框颜色 | String | `'$line'` | - |
| bgColor | 背景颜色 | String | `$info` | - |
| activeBgColor | 聚焦时的背景颜色 | String | `$info` | - |
| disabledBgColor | 禁用时的背景颜色 | String | `$disabled` | - |
| textColor | 文本颜色 | String | `$text` | - |
| disabledTextColor | 禁用时的文本颜色 | String | `$disabledText` | - |
| iconColor | 前后置图标颜色 | String | `$text` | - |
| borderRadius | 圆角大小 | String \| Number | `$8` | - |
| borderWidth | 边框宽度 | String \| Number | `1px` | - |
| padding | 内边距，支持 `$` 前缀按间距乘数缩放 | String | `8px 13px` | - |
| textSize | 文本字体大小 | String \| Number | `$14` | - |
| textFont | 文本字体 | String | `''` | - |
| align | 文本对齐方式 | String | `left` | `left` \| `center` \| `right` |
| prefixIcon | 前置图标名称，存在 prefix 插槽时不显示 | String | `''` | - |
| suffixIcon | 后置图标名称，存在 suffix 插槽时不显示 | String | `''` | - |
| iconSize | 图标大小 | String \| Number | `$16` | - |
| inputStyle | 自定义输入框本体样式 | SnStyleValue | `''` | - |
| inputClass | 输入框本体的外部类 | String | `''` | - |
| prefixIconStyle | 自定义前置图标样式 | SnStyleValue | `''` | - |
| prefixIconClass | 前置图标的外部类 | String | `''` | - |
| suffixIconStyle | 自定义后置图标样式 | SnStyleValue | `''` | - |
| suffixIconClass | 后置图标的外部类 | String | `''` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| input | (event: UniInputEvent) => Void | 键盘输入时触发，`event.detail = { value, cursor }` |
| focus | (event: UniInputFocusEvent) => Void | 输入框聚焦时触发 |
| blur | (event: UniInputBlurEvent) => Void | 输入框失去焦点时触发 |
| confirm | (event: UniInputConfirmEvent) => Void | 点击键盘右下角按钮时触发 |
| keyboardheightchange | (event: UniInputKeyboardHeightChangeEvent) => Void | 键盘高度变化时触发 |
| prefix-click | () => Void | 点击前置图标时触发 |
| suffix-click | () => Void | 点击后置图标时触发 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| prefix | 自定义前置内容，使用后前置图标不显示 |
| suffix | 自定义后置内容，使用后后置图标不显示 |

<DemoPhone name="sn-input" />

# Mention 提及输入框

## 基础用法

用于在文本输入中通过提及符号插入并管理标签的输入框，常见于 @ 好友、# 话题等场景。

- 支持自定义提及符号，输入符号时抛出事件交由宿主弹出选择面板
- 提及对象以标签形式插入输入框，标签可整段删除，删除前支持校验

```vue
<template>
	<sn-mention ref="mentionRef" v-model="text" placeholder="输入 @ 选择好友" @mention="onMention"
		@removemention="onRemove"></sn-mention>
</template>

<script lang="ts" setup>
const text = ref<string>('')
const mentionRef = ref<SnMentionComponentPublicInstance | null>(null)

function onMention(): void {
	uni.hideKeyboard()
	openFriendPanel()
}

function onRemove(tag: string): void {
	console.log('已删除标签：@' + tag)
}

function selectFriend(name: string): void {
	mentionRef.value?.$callMethod('insertMention', name)
}
</script>
```

**更多演示请下载 demo 查看**

## 实现原理

组件在 `sn-input` 基础上扩展，继承其全部属性与事件，并追加提及相关的属性、事件与方法。

## 拦截标签删除

`beforeRemove` 返回 false 时，退格仅按普通字符删除，不触发 `removemention`；返回 true 时整段删除标签。

```vue
<template>
	<sn-mention ref="mentionRef" v-model="text" :before-remove="beforeRemove" @removemention="onRemove"></sn-mention>
</template>

<script lang="ts" setup>
const text = ref<string>('')
const mentionRef = ref<SnMentionComponentPublicInstance | null>(null)

function beforeRemove(tag: string): boolean {
	return isFriend(tag)
}

function onRemove(tag: string): void {
	console.log('已整段删除标签 @' + tag)
}
</script>
```

## 自定义提及符号

```vue
<template>
	<sn-mention ref="mentionRef" v-model="text" mention-char="#" placeholder="输入 # 触发话题提及"></sn-mention>
</template>

<script lang="ts" setup>
const text = ref<string>('')
const mentionRef = ref<SnMentionComponentPublicInstance | null>(null)
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值 | String | `''` | - |
| mentionChar | 触发提及的符号，设为空字符串时关闭提及功能 | String | `@` | - |
| beforeRemove | 删除标签前的校验函数，返回 false 则按普通字符删除 | ((tag: string) => boolean) \| null | `null` | - |
| name | 表单的控件名称，作为键值对的一部分与表单一同提交 | String | `''` | - |
| type | 输入框类型 | String | `text` | `text` \| `number` \| `digit` \| `tel` \| `idcard` \| `nickname` |
| password | 是否密码类型，为 true 时右侧显示明文/密文切换按钮 | Boolean | `false` | `true` \| `false` |
| placeholder | 输入框为空时的占位符 | String | `请输入内容，@选择` | - |
| placeholderStyle | 占位符内联样式 | String | `''` | - |
| placeholderClass | 占位符外部类 | String | `''` | - |
| maxlength | 最大输入长度，`-1` 表示不限制 | String \| Number | `-1` | - |
| focus | 获取焦点 | Boolean | `false` | `true` \| `false` |
| autoFocus | 自动获取焦点，与 `focus` 相比只在首次生效 | Boolean | `false` | `true` \| `false` |
| cursor | 指定聚焦时的光标位置，`-1` 表示不指定 | String \| Number | `-1` | - |
| cursorColor | 光标颜色 | String | `$primary` | - |
| cursorSpacing | 光标与键盘的距离（px） | String \| Number | `0` | - |
| selectionStart | 光标起始位置，自动聚焦时有效，需与 `selectionEnd` 搭配 | String \| Number | `-1` | - |
| selectionEnd | 光标结束位置，自动聚焦时有效，需与 `selectionStart` 搭配 | String \| Number | `-1` | - |
| confirmType | 键盘右下角按钮的文字 | String | `done` | `send` \| `search` \| `next` \| `go` \| `done` |
| confirmHold | 点击键盘右下角按钮时是否保持键盘不收起 | Boolean | `false` | `true` \| `false` |
| holdKeyboard | 聚焦时点击页面不收起键盘 | Boolean | `false` | `true` \| `false` |
| adjustPosition | 键盘弹起时是否自动上推页面 | Boolean | `true` | `true` \| `false` |
| controlled | 是否为受控属性 | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用 | Boolean | `false` | `true` \| `false` |
| readonly | 是否只读 | Boolean | `false` | `true` \| `false` |
| loading | 是否加载中，右侧显示加载指示器 | Boolean | `false` | `true` \| `false` |
| loadingClass | 加载指示器外部类 | String | `''` | - |
| loadingStyle | 加载指示器样式 | SnStyleValue | `''` | - |
| clearable | 是否显示清除按钮 | Boolean | `false` | `true` \| `false` |
| showBorder | 是否显示边框 | Boolean | `true` | `true` \| `false` |
| showActiveBorder | 聚焦时是否切换为激活边框颜色 | Boolean | `true` | `true` \| `false` |
| borderColor | 边框颜色 | String | `'$line'` | - |
| activeBorderColor | 聚焦时的边框颜色 | String | `'$line'` | - |
| bgColor | 背景颜色 | String | `'$info'` | - |
| activeBgColor | 聚焦时的背景颜色 | String | `'$info'` | - |
| disabledBgColor | 禁用时的背景颜色 | String | `$disabled` | - |
| textColor | 文本颜色 | String | `$text` | - |
| disabledTextColor | 禁用时的文本颜色 | String | `$disabledText` | - |
| iconColor | 前后置图标颜色 | String | `$text` | - |
| borderRadius | 圆角大小 | String \| Number | `$8` | - |
| borderWidth | 边框宽度 | String \| Number | `1px` | - |
| padding | 内边距 | String | `8px 12px` | - |
| textSize | 文本字体大小 | String \| Number | `$14` | - |
| textFont | 文本字体 | String | `''` | - |
| align | 文本对齐方式 | String | `left` | `left` \| `center` \| `right` |
| prefixIcon | 前置图标名称，存在 prefix 插槽时不显示 | String | `''` | - |
| suffixIcon | 后置图标名称，存在 suffix 插槽时不显示 | String | `''` | - |
| iconSize | 图标大小 | String \| Number | `$16` | - |
| containStyle | 自定义内部输入框容器样式 | SnStyleValue | `''` | - |
| inputStyle | 自定义输入框本体样式 | SnStyleValue | `''` | - |
| inputClass | 输入框本体的外部类 | String | `''` | - |
| prefixIconStyle | 自定义前置图标样式 | SnStyleValue | `''` | - |
| prefixIconClass | 前置图标的外部类 | String | `''` | - |
| suffixIconStyle | 自定义后置图标样式 | SnStyleValue | `''` | - |
| suffixIconClass | 后置图标的外部类 | String | `''` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| mention | () => Void | 输入提及符号时触发，通常在此收起键盘并打开选择面板 |
| removemention | (tag: string) => Void | 整段删除一个提及标签时触发，参数为标签内容（不含提及符号） |
| change | (value: string) => Void | 绑定值变化时触发，参数为当前值 |
| input | (event: UniInputEvent) => Void | 键盘输入时触发 |
| focus | (event: UniInputFocusEvent) => Void | 输入框聚焦时触发 |
| blur | (event: UniInputBlurEvent) => Void | 输入框失去焦点时触发 |
| confirm | (event: UniInputConfirmEvent) => Void | 点击键盘右下角按钮时触发 |
| keyboardheightchange | (event: UniInputKeyboardHeightChangeEvent) => Void | 键盘高度变化时触发 |
| prefix-click | () => Void | 点击前置图标时触发 |
| suffix-click | () => Void | 点击后置图标时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| setFocus | val: boolean | - | 设置输入框聚焦状态 |
| insertMention | name: string | - | 在提及符号处插入 `@name` 标签并重新聚焦，一般由选择面板选中后调用 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| prefix | 自定义前置内容，透传给内部输入框，使用后前置图标不显示 |
| suffix | 自定义后置内容，透传给内部输入框，使用后后置图标不显示 |

<DemoPhone name="sn-mention" />

# InputField 标签输入框

## 基础用法

自带标签与错误提示的单行输入框，用于移动端表单的文本录入。

- 支持密码明密文切换、一键清空与加载指示器，并提供禁用、只读配色
- 支持前置/后置图标与标签、前缀、后缀、错误等插槽扩展
- 可置于 `sn-form` 中直接参与整表校验

::: info $ 简写
尺寸与颜色属性支持 `$` 简写（如 `label-size="$18"`、`label-color="$primaryDark"`），随风格乘数与主题自动缩放换色。
:::

```vue
<template>
	<sn-input-field v-model="value" label="用户账号" required placeholder="请输入账号" clearable />
	<sn-input-field v-model="pwd" label="密码" password placeholder="请输入密码" clearable />
</template>

<script lang="ts" setup>
	const value = ref<string>('')
	const pwd = ref<string>('')
</script>
```

**更多演示请下载 demo 查看**

## 布局与标签

`direction` 切换水平/垂直布局：horizontal 标签在左（默认），vertical 标签在上。`label-align` 控制标签文字水平对齐，`label-justify` 控制标签在容器内竖向对齐（top / center / bottom），`label-width` 与 `column-gap` 控制标签宽度与间距。

```vue
<template>
	<sn-input-field v-model="valueV" direction="vertical" label="商品名称" placeholder="请输入商品名称" clearable />
	<sn-input-field v-model="valueR" label="标签靠右" label-align="right" label-width="80px" placeholder="标签靠右" />
</template>

<script lang="ts" setup>
	const valueV = ref<string>('')
	const valueR = ref<string>('')
</script>
```

## 配合 sn-form 使用

设置 `field` 与 `rule` 后直接参与 `sn-form` 整表校验，校验失败信息通过 `error` 属性展示。

本组件自身即表单字段，无需再包一层 `sn-form-field`。

```vue
<template>
	<sn-form ref="formRef" v-model="formData">
		<sn-input-field field="username" :rule="userRule" v-model="(formData['username'] as string)" label="用户名" :error="getFieldError('username')" placeholder="4-16 位字母数字下划线" clearable />
		<sn-input-field field="phone" :rule="phoneRule" v-model="(formData['phone'] as string)" label="手机号" :error="getFieldError('phone')" type="number" :maxlength="11" clearable />
	</sn-form>
	<sn-button text="提交" type="primary" custom-style="margin-top:16px;" @click="onFormSubmit" />
</template>

<script lang="ts" setup>
	import type { SnFormItemRule, SnFormItemVerifyResult, SnFormValidResult } from '@/uni_modules/sinle-ui'

	const formRef = ref<SnInputFieldComponentPublicInstance | null>(null)
	const formData = ref<SnFormData>({
		username: '',
		phone: ''
	})
	const failResults = ref<SnFormItemVerifyResult[]>([])

	function getFieldError(field: string): string {
		const list = failResults.value
		for (let i = 0; i < list.length; i++) {
			if (list[i].field == field) {
				return list[i].message ?? ''
			}
		}
		return ''
	}

	const userRule = ref<SnFormItemRule>({
		pattern: /^[a-zA-Z0-9_]{4,16}$/,
		message: '用户名需为 4-16 位字母、数字或下划线'
	} as SnFormItemRule)

	const phoneRule = ref<SnFormItemRule>({
		type: 'phone',
		required: true,
		message: '请填写正确的手机号'
	} as SnFormItemRule)

	function onFormSubmit(): void {
		formRef.value?.$callMethod('submit', {
			success: () => {
				failResults.value = []
			},
			fail: (results: SnFormItemVerifyResult[]) => {
				failResults.value = results
			}
		} as SnFormValidResult)
	}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值 | String | `''` | - |
| direction | 布局方向，horizontal 标签在左、vertical 标签在上 | String | `horizontal` | `horizontal` \| `vertical` |
| label | 标签文字 | String | `''` | - |
| labelSize | 标签字体大小 | String \| Number | `$14` | - |
| labelColor | 标签颜色 | String | `$title` | - |
| labelWidth | 横向布局时标签宽度 | String \| Number | `$80` | - |
| labelAlign | 标签文字水平对齐 | String | `left` | `left` \| `right` \| `center` |
| labelJustify | 标签在容器内的竖向对齐 | String | `top` | `top` \| `center` \| `bottom` |
| required | 是否必填，标签后追加红色 `*` 标记 | Boolean | `false` | `true` \| `false` |
| error | 错误提示文字（存在 error 插槽时不显示） | String | `''` | - |
| errorSize | 错误文字大小 | String \| Number | `$12` | - |
| errorColor | 错误文字颜色 | String | `$error` | - |
| columnGap | 标签与内容的间距 | String \| Number | `$12` | - |
| name | 表单的控件名称，作为键值对的一部分与表单一同提交 | String | `''` | - |
| field | 表单字段名，非空且位于 sn-form 内时注册参与整表校验 | String | `''` | - |
| rule | 校验规则，配合 field 使用 | `SnFormItemRule` | `{}` | - |
| type | 输入框类型 | String | `text` | `text` \| `number` \| `digit` \| `tel` \| `idcard` \| `nickname` |
| password | 是否密码类型，为 true 时右侧显示明文/密文切换按钮 | Boolean | `false` | `true` \| `false` |
| placeholder | 输入框为空时的占位符 | String | `''` | - |
| placeholderStyle | 占位符内联样式 | String | `''` | - |
| placeholderClass | 占位符外部类 | String | `''` | - |
| maxlength | 最大输入长度，`-1` 表示不限制 | String \| Number | `-1` | - |
| focus | 获取焦点 | Boolean | `false` | `true` \| `false` |
| autoFocus | 自动获取焦点，与 `focus` 相比只在首次生效 | Boolean | `false` | `true` \| `false` |
| cursor | 指定聚焦时的光标位置，`-1` 表示不指定 | String \| Number | `-1` | - |
| cursorColor | 光标颜色 | String | `$primary` | - |
| cursorSpacing | 光标与键盘的距离（px） | String \| Number | `0` | - |
| selectionStart | 光标起始位置，自动聚焦时有效，需与 `selectionEnd` 搭配 | String \| Number | `-1` | - |
| selectionEnd | 光标结束位置，自动聚焦时有效，需与 `selectionStart` 搭配 | String \| Number | `-1` | - |
| confirmType | 键盘右下角按钮的文字 | String | `done` | `send` \| `search` \| `next` \| `go` \| `done` |
| confirmHold | 点击键盘右下角按钮时是否保持键盘不收起 | Boolean | `false` | `true` \| `false` |
| holdKeyboard | 聚焦时点击页面不收起键盘 | Boolean | `false` | `true` \| `false` |
| adjustPosition | 键盘弹起时是否自动上推页面 | Boolean | `true` | `true` \| `false` |
| controlled | 是否为受控属性（原生 input 的 controlled） | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用，禁用后不可输入且背景、文字使用禁用配色 | Boolean | `false` | `true` \| `false` |
| readonly | 是否只读，只读时颜色不变 | Boolean | `false` | `true` \| `false` |
| loading | 是否加载中，输入区右侧显示加载指示器（延迟 100ms 显示避免闪烁） | Boolean | `false` | `true` \| `false` |
| loadingClass | 加载指示器外部类 | String | `''` | - |
| loadingStyle | 加载指示器样式 | SnStyleValue | `''` | - |
| clearable | 是否显示清除按钮（有内容且非禁用/只读时显示，点击清空） | Boolean | `false` | `true` \| `false` |
| showBorder | 是否显示边框 | Boolean | `true` | `true` \| `false` |
| showActiveBorder | 聚焦时是否切换为激活边框颜色 | Boolean | `false` | `true` \| `false` |
| borderColor | 边框颜色 | String | `var(--sn-transparent)` | - |
| activeBorderColor | 聚焦激活时的边框颜色 | String | `$primary` | - |
| bgColor | 背景颜色 | String | `$front` | - |
| activeBgColor | 聚焦时的背景颜色 | String | `$front` | - |
| disabledBgColor | 禁用时的背景颜色 | String | `$disabled` | - |
| textColor | 输入文字颜色 | String | `$text` | - |
| disabledTextColor | 禁用时的文字颜色 | String | `$disabledText` | - |
| iconColor | 前后置图标颜色 | String | `$text` | - |
| borderRadius | 圆角大小 | String \| Number | `0px` | - |
| borderWidth | 边框宽度 | String \| Number | `2` | - |
| padding | 内边距，支持 `$` 前缀按间距乘数缩放 | String | `10px 13px` | - |
| textSize | 输入文字大小 | String \| Number | `$14` | - |
| textFont | 输入文字字体 | String | `''` | - |
| align | 输入文字对齐方式 | String | `left` | `left` \| `center` \| `right` |
| prefixIcon | 前置图标名称，存在 prefix 插槽时不显示 | String | `''` | - |
| suffixIcon | 后置图标名称，存在 suffix 插槽时不显示 | String | `''` | - |
| iconSize | 前后置图标大小 | String \| Number | `$16` | - |
| labelStyle | 标签节点自定义样式 | SnStyleValue | `''` | - |
| labelClass | 标签节点外部类 | String | `''` | - |
| errorStyle | 错误节点自定义样式 | SnStyleValue | `''` | - |
| errorClass | 错误节点外部类 | String | `''` | - |
| inputStyle | 自定义输入框本体样式 | SnStyleValue | `''` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部类 | String | `''` | - |
| prefixIconStyle | 自定义前置图标样式 | SnStyleValue | `''` | - |
| prefixIconClass | 前置图标的外部类 | String | `''` | - |
| suffixIconStyle | 自定义后置图标样式 | SnStyleValue | `''` | - |
| suffixIconClass | 后置图标的外部类 | String | `''` | - |

> 类型字段：SnFormItemRule（见 https://sinleui.pages.dev/api/types/component#snformitemrule）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| input | (event: UniInputEvent) => Void | 键盘输入时触发，`event.detail = { value, cursor }` |
| focus | (event: UniInputFocusEvent) => Void | 输入框聚焦时触发 |
| blur | (event: UniInputBlurEvent) => Void | 输入框失去焦点时触发 |
| confirm | (event: UniInputConfirmEvent) => Void | 点击键盘右下角按钮时触发 |
| keyboardheightchange | (event: UniInputKeyboardHeightChangeEvent) => Void | 键盘高度变化时触发 |
| prefix-click | () => Void | 点击前置图标时触发 |
| suffix-click | () => Void | 点击后置图标时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| verify | (value: any, callback: (res: SnFormItemVerifyResult) => Void) | - | 按 rule 校验当前表单项并回调结果；一般由 sn-form 自动调用，无需手动调用 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| label | 自定义标签内容，替换 label 属性文字 |
| prefix | 自定义前置内容，使用后前置图标不显示 |
| suffix | 自定义后置内容，使用后后置图标不显示 |
| error | 自定义错误提示内容，替换 error 属性文字 |

<DemoPhone name="sn-input-field" />

# CodeInput 验证码输入框

## 基础用法

验证码 / 密码输入框，由若干独立单元格组成。

- 输入一位自动跳转下一格，支持整段粘贴自动分配
- 提供方格与下划线两种样式，可限制输入字符并自动匹配键盘
- 输入满位后派发完成事件，并提供聚焦、失焦与清空方法

```vue
<template>
	<sn-code-input v-model="code" :length="6" format="number" @finish="onFinish"></sn-code-input>
</template>

<script lang="ts" setup>
const code = ref<string>('')

function onFinish(value: string): void {
	console.log(value)
}
</script>
```

**更多演示请下载 demo 查看**

## 下划线模式与掩码

`mode="line"` 切换为底部横线风格；`mask` 开启后已输入的字符以掩码图标显示，事件回调仍返回真实值。

```vue
<template>
	<sn-code-input v-model="pwd" :length="6" format="number" mode="line" :mask="true"></sn-code-input>
</template>

<script lang="ts" setup>
const pwd = ref<string>('')
</script>
```

## 聚焦与清空

通过 ref 调用 `focus` / `clear` 方法，外部控制输入状态。
点击已聚焦的单元格只调整光标位置，不会先失焦再重建键盘；输入与整段粘贴会同步过滤非法字符。

```vue
<template>
	<sn-code-input ref="codeRef" v-model="code" :length="4"></sn-code-input>
</template>

<script lang="ts" setup>
const code = ref<string>('')
const codeRef = ref<SnCodeInputComponentPublicInstance | null>(null)

function doFocus(): void {
	codeRef.value?.$callMethod('focus')
}

function doClear(): void {
	codeRef.value?.$callMethod('clear')
}
</script>
```

## 注意事项

当前激活单元格高亮并显示闪烁光标。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值 | String | `''` | - |
| length | 验证码位数，最小为 1 | String \| Number | `6` | - |
| mode | 单元格样式 | String | `box` | `box` \| `line` |
| format | 允许输入的字符类型，`number` 时自动弹出数字键盘，非法字符会被自动过滤 | String | `mixed` | `mixed` \| `number` \| `letter` |
| mask | 是否以掩码图标显示已输入字符 | Boolean | `false` | `true` \| `false` |
| maskIcon | 掩码图标名称，`mask` 为 true 时生效 | String | `circle-fill` | - |
| size | 单个单元格尺寸，最小 20px | String \| Number | `40px` | - |
| space | 单元格间距 | String \| Number | `5px` | - |
| borderRadius | 单元格圆角大小 | String \| Number | `12px` | - |
| borderWidth | 单元格边框宽度 | String \| Number | `2` | - |
| textSize | 字符字体大小 | String \| Number | `$22` | - |
| textColor | 字符颜色 | String | `$text` | - |
| caretSize | 光标大小 | String \| Number | `$14` | - |
| caretColor | 光标颜色 | String | `$primary` | - |
| borderColor | 未填充单元格边框颜色 | String | `$line` | - |
| activeColor | 已填充与激活单元格的边框颜色 | String | `$primary` | - |
| bgColor | 单元格背景颜色 | String | `$front` | - |
| activeBgColor | 激活单元格背景颜色 | String | `$primaryLight` | - |
| focus | 是否自动聚焦 | Boolean | `false` | `true` \| `false` |
| adjustPosition | 键盘弹起时是否自动上推页面 | Boolean | `true` | `true` \| `false` |
| disabled | 是否禁用 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部类 | String | `''` | - |
| itemStyle | 自定义单元格样式 | SnStyleValue | `''` | - |
| itemClass | 单元格外部类 | String | `''` | - |
| textStyle | 自定义字符样式 | SnStyleValue | `''` | - |
| textClass | 字符外部类 | String | `''` | - |
| caretStyle | 自定义光标样式 | SnStyleValue | `''` | - |
| caretClass | 光标外部类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| input | (event: UniInputEvent) => Void | 键盘输入时触发 |
| change | (value: string) => Void | 绑定值变化时触发，参数为当前值 |
| finish | (value: string) => Void | 输入满 `length` 位时触发，参数为完整验证码 |
| focus | (event: UniInputFocusEvent) => Void | 聚焦时触发 |
| blur | (event: UniInputBlurEvent) => Void | 失去焦点时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| focus | - | - | 使输入框聚焦，光标定位到末尾 |
| blur | - | - | 使输入框失去焦点 |
| clear | - | - | 清空输入内容并触发 `change` 事件 |

<DemoPhone name="sn-code-input" />

# SlideCaptcha 滑块验证

## 基础用法

滑块验证码组件。

- 支持滑块模式（拖动滑块到目标区域）与拼图模式（拖动滑块使拼图块对准缺口）
- 验证通过 / 失败分别派发事件，失败后提示片刻自动复位并重新生成目标位置
- Web 端支持鼠标按住拖动验证

::: info 验证判定
滑块模式的目标区域宽度为滑块尺寸加两倍容差，滑块中心落入目标区域即通过。
:::

```vue
<template>
	<sn-slide-captcha @success="onSuccess" @fail="onFail"></sn-slide-captcha>
</template>
```

**更多演示请下载 demo 查看**

## 拼图模式

拼图模式通过 `src` 传入图片地址，组件在图片上随机生成缺口与拼图块，拖动滑块使拼图块对准缺口（允许误差为 `tolerance` 像素）即通过验证。图片右上角提供刷新按钮，可重新生成缺口位置。

```vue
<template>
	<sn-slide-captcha mode="puzzle" src="/static/captcha.png" @success="onSuccess" @fail="onFail"></sn-slide-captcha>
</template>
```

## 指定目标位置

`target` 取 `0 - 100` 时指定目标在轨道可滑动范围内的百分比位置，取 `-1` 时随机生成目标位置；默认 `100`（轨道最右端）。

```vue
<template>
	<sn-slide-captcha :target="60"></sn-slide-captcha>
</template>
```

## 事件与重置

验证失败后组件会自动复位；也可通过 `ref` 调用 `reset` 方法随时重新开始验证。

```vue
<template>
	<sn-slide-captcha ref="captcha" hint-text="拖动滑块完成安全验证" @success="onSuccess" @fail="onFail"></sn-slide-captcha>
	<sn-button text="重新验证" @click="onResetClick"></sn-button>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| mode | 验证模式 | String | `'slide'` | `slide` \| `puzzle` |
| src | 拼图模式图片路径，仅 puzzle 模式有效 | String | `''` | - |
| width | 组件宽度，支持 `$` 前缀按间距乘数缩放 | String \| Number | `'100%'` | - |
| height | 拼图图片区域高度，仅 puzzle 模式有效，支持 `$` 前缀按间距乘数缩放 | String \| Number | `'180px'` | - |
| thumbSize | 滑块尺寸（正方形边长），支持 `$` 前缀按间距乘数缩放 | String \| Number | `'40px'` | - |
| thumbRadius | 滑块圆角，支持 `$` 前缀按圆角乘数缩放；默认为滑块尺寸的一半（圆形） | String \| Number | `''` | - |
| tolerance | 判定容差（px）。slide 模式下目标区域宽度为滑块尺寸加两倍容差；puzzle 模式下为拼图块对准缺口的允许误差 | Number | `6` | - |
| target | 目标位置百分比（0-100，相对轨道可滑动范围），-1 表示随机；仅 slide 模式有效 | Number | `100` | `-1` - `100` |
| activeColor | 滑动填充条颜色；滑块颜色取其对应原色（传入 Light 变体色时自动去除 Light 后缀） | String | `'$primaryLight'` | - |
| trackColor | 轨道背景颜色 | String | `'$infoActive'` | - |
| successColor | 验证通过后的填充条与滑块颜色 | String | `'$success'` | - |
| failColor | 验证失败后的填充条与滑块颜色 | String | `'$error'` | - |
| targetColor | 目标区域颜色 | String | `'$primary'` | - |
| hintText | 待验证时轨道中的提示文本 | String | `'拖动滑块完成验证'` | - |
| successText | 验证通过后的提示文本 | String | `'验证通过'` | - |
| failText | 验证失败后的提示文本 | String | `'验证失败，请重试'` | - |
| disabled | 禁用组件，无法拖动，整体降低透明度 | Boolean | `false` | `true` \| `false` |
| customStyle | 组件根节点自定义样式 | SnStyleValue | `''` | - |
| customClass | 组件根节点自定义样式类名 | String | `''` | - |
| imageStyle | 拼图图片区域自定义样式 | SnStyleValue | `''` | - |
| imageClass | 拼图图片区域自定义样式类名 | String | `''` | - |
| trackStyle | 轨道自定义样式 | SnStyleValue | `''` | - |
| trackClass | 轨道自定义样式类名 | String | `''` | - |
| thumbStyle | 滑块自定义样式 | SnStyleValue | `''` | - |
| thumbClass | 滑块自定义样式类名 | String | `''` | - |
| fillStyle | 填充条自定义样式 | SnStyleValue | `''` | - |
| fillClass | 填充条自定义样式类名 | String | `''` | - |
| targetStyle | 目标区域自定义样式 | SnStyleValue | `''` | - |
| targetClass | 目标区域自定义样式类名 | String | `''` | - |
| textStyle | 提示文本自定义样式 | SnStyleValue | `''` | - |
| textClass | 提示文本自定义样式类名 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| success | () => Void | 验证通过时触发 |
| fail | () => Void | 验证失败时触发，随后组件自动复位并重新生成目标位置 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| reset | - | - | 复位组件并重新生成目标位置，开始新一轮验证 |

<DemoPhone name="sn-slide-captcha" />

# Textarea 文本域

> [查看 sn-textarea 的 2.0 版本差异](/differences/components/sn-textarea)

## 基础用法

基于内置 `textarea` 组件封装的多行文本输入域，输入内容支持双向绑定。

- 高度可固定，也可随内容自动增高
- 内置聚焦激活态、禁用与只读配色、加载状态与字数计数器
- 限制最大字数后右下角显示已输入 / 最大字数，计数器可用插槽自定义

```vue
<template>
	<sn-textarea v-model="text" :maxlength="50" placeholder="请输入内容"></sn-textarea>
</template>

<script lang="ts" setup>
const text = ref<string>('')
</script>
```

**更多演示请下载 demo 查看**

## 自动增高

设置 `autoHeight` 后初始高度由内容撑开，输入多行时自动增高，`height` 不再生效。

```vue
<template>
	<sn-textarea v-model="text" auto-height placeholder="自动增高"></sn-textarea>
</template>

<script lang="ts" setup>
const text = ref<string>('')
</script>
```

## 自定义样式

通过 `customStyle` 定制根容器，`inputStyle` 内联作用于文本域本体，计数器可用 `counterClass` / `counterStyle` 定制。

```vue
<template>
	<sn-textarea v-model="text" :maxlength="20" input-style="font-size: 18px; font-weight: bold;"
		counter-style="background-color: #ff6600; color: #fff;"
		placeholder="大字加粗 + 橙色计数器"></sn-textarea>
</template>

<script lang="ts" setup>
const text = ref<string>('')
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值 | String | `''` | - |
| name | 表单的控件名称，作为键值对的一部分与表单一同提交 | String | `''` | - |
| height | 文本域高度，`autoHeight` 开启时不生效，支持 `$` 前缀按间距乘数缩放 | String \| Number | `100px` | - |
| placeholder | 输入框为空时的占位符 | String | `''` | - |
| placeholderStyle | 占位符内联样式 | String | `''` | - |
| placeholderClass | 占位符外部类 | String | `''` | - |
| maxlength | 最大输入长度，`-1` 表示不限制；设置后右下角显示字数计数器 | String \| Number | `-1` | - |
| focus | 获取焦点 | Boolean | `false` | `true` \| `false` |
| autoFocus | 自动获取焦点，与 `focus` 相比只在首次生效 | Boolean | `false` | `true` \| `false` |
| autoHeight | 是否自动增高，开启后 `height` 不生效 | Boolean | `false` | `true` \| `false` |
| cursor | 指定聚焦时的光标位置，`-1` 表示不指定 | String \| Number | `-1` | - |
| cursorColor | 光标颜色 | String | `''` | - |
| cursorSpacing | 光标与键盘的距离（px） | String \| Number | `0` | - |
| selectionStart | 光标起始位置，自动聚焦时有效，需与 `selectionEnd` 搭配 | String \| Number | `-1` | - |
| selectionEnd | 光标结束位置，自动聚焦时有效，需与 `selectionStart` 搭配 | String \| Number | `-1` | - |
| confirmType | 键盘右下角按钮的文字 | String | `return` | `send` \| `search` \| `next` \| `go` \| `done` \| `return` |
| confirmHold | 点击键盘右下角按钮时是否保持键盘不收起 | Boolean | `false` | `true` \| `false` |
| holdKeyboard | 聚焦时点击页面不收起键盘 | Boolean | `false` | `true` \| `false` |
| adjustPosition | 键盘弹起时是否自动上推页面 | Boolean | `true` | `true` \| `false` |
| inputmode | 输入数据类型提示，提供键盘类型提示 | String | `text` | `none` \| `text` \| `decimal` \| `numeric` \| `tel` \| `search` \| `email` \| `url` |
| fixed | 是否为固定定位元素（textarea 原生属性，用于在固定区域内使用） | Boolean | `false` | `true` \| `false` |
| showConfirmBar | 是否显示键盘上方"完成"栏 | Boolean | `true` | `true` \| `false` |
| disabled | 是否禁用，禁用后不可输入且背景、文字使用禁用配色 | Boolean | `false` | `true` \| `false` |
| readonly | 是否只读，只读时颜色不变 | Boolean | `false` | `true` \| `false` |
| loading | 是否加载中，右上角显示加载指示器（延迟 100ms 显示避免闪烁） | Boolean | `false` | `true` \| `false` |
| loadingClass | 加载指示器外部类 | String | `''` | - |
| loadingStyle | 加载指示器样式 | SnStyleValue | `''` | - |
| showBorder | 是否显示边框 | Boolean | `true` | `true` \| `false` |
| activeBorder | 聚焦时是否切换为激活边框颜色 | Boolean | `true` | `true` \| `false` |
| borderColor | 边框颜色 | String | `'$line'` | - |
| activeBorderColor | 聚焦时的边框颜色 | String | `'$line'` | - |
| bgColor | 背景颜色 | String | `$info` | - |
| activeBgColor | 聚焦时的背景颜色 | String | `$info` | - |
| disabledBgColor | 禁用时的背景颜色 | String | `$disabled` | - |
| textColor | 文本颜色，禁用时为 `$disabledText` | String | `$text` | - |
| disabledTextColor | 禁用时的文本颜色 | String | `$disabledText` | - |
| borderRadius | 圆角大小 | String \| Number | `$8` | - |
| borderWidth | 边框宽度 | String \| Number | `1px` | - |
| padding | 内边距，支持 `$` 前缀按间距乘数缩放 | String | `8px 13px` | - |
| textSize | 文本字体大小 | String \| Number | `$14` | - |
| textFont | 文本字体 | String | `''` | - |
| align | 文本对齐方式 | String | `left` | `left` \| `center` \| `right` |
| counterSize | 计数器字体大小 | String \| Number | `$12` | - |
| counterColor | 计数器文本颜色 | String | `$text` | - |
| counterBgColor | 计数器背景颜色 | String | `$info` | - |
| inputStyle | 自定义文本域本体样式 | SnStyleValue | `''` | - |
| inputClass | 文本域本体的外部类 | String | `''` | - |
| counterClass | 计数器外部类 | String | `''` | - |
| counterStyle | 自定义计数器样式 | SnStyleValue | `''` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| input | (event: UniInputEvent) => Void | 键盘输入时触发，`event.detail = { value, cursor }` |
| focus | (event: UniTextareaFocusEvent) => Void | 输入框聚焦时触发 |
| blur | (event: UniTextareaBlurEvent) => Void | 输入框失去焦点时触发 |
| confirm | (event: UniInputConfirmEvent) => Void | 点击键盘右下角按钮时触发 |
| linechange | (event: UniTextareaLineChangeEvent) => Void | 输入框行数变化时触发，`event.detail = { height, heightRpx, lineCount }` |
| keyboardheightchange | (event: UniInputKeyboardHeightChangeEvent) => Void | 键盘高度变化时触发 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| counter | 替换内置的字数计数器（仅在设置了 `maxlength` 时渲染） |

<DemoPhone name="sn-textarea" />

# TextareaField 标签文本域

## 基础用法

自带标签与错误提示的多行文本域，用于表单中的长文本录入。

- 默认垂直布局（标签在上），支持由内容自动撑高
- 支持最大字数限制与右下角字数统计胶囊
- 可置于 `sn-form` 中直接参与整表校验

::: info $ 简写
尺寸与颜色属性支持 `$` 简写（如 `height="$120"`、`label-color="$primaryDark"`），随风格乘数与主题自动缩放换色。
:::

```vue
<template>
	<sn-textarea-field v-model="value" label="商品评价" placeholder="说说你的使用感受" />
	<sn-textarea-field v-model="comment" label="评论" :maxlength="50" placeholder="最多 50 字" />
</template>

<script lang="ts" setup>
	const value = ref<string>('')
	const comment = ref<string>('')
</script>
```

**更多演示请下载 demo 查看**

## 高度与字数统计

默认高度 `100px`，`height` 可自定义；设置 `auto-height` 后高度由内容撑开（`height` 失效）。`maxlength` 限制最大字数并在右下角显示"当前字数/最大字数"计数器，可用 `counter` 插槽或 `counterSize` / `counterColor` / `counterBgColor` 等属性定制。

```vue
<template>
	<sn-textarea-field v-model="value1" label="动态高度" auto-height placeholder="输入多行试试，自动撑开" />
	<sn-textarea-field v-model="value2" direction="horizontal" label="吐槽" height="80px" :maxlength="200" placeholder="横向标签在左" />
</template>

<script lang="ts" setup>
	const value1 = ref<string>('')
	const value2 = ref<string>('')
</script>
```

## 配合 sn-form 使用

设置 `field` 与 `rule` 后直接参与 `sn-form` 整表校验，校验失败信息通过 `error` 属性展示。

本组件自身即表单字段，无需再包一层 `sn-form-field`。

```vue
<template>
	<sn-form ref="formRef" v-model="formData">
		<sn-textarea-field field="remark" :rule="remarkRule" v-model="(formData['remark'] as string)" label="备注" :error="getFieldError('remark')" :maxlength="100" placeholder="备注最多 100 字" />
	</sn-form>
	<sn-button text="提交" type="primary" custom-style="margin-top:16px;" @click="onFormSubmit" />
</template>

<script lang="ts" setup>
	import type { SnFormItemRule, SnFormItemVerifyResult, SnFormValidResult } from '@/uni_modules/sinle-ui'

	const formRef = ref<SnTextareaFieldComponentPublicInstance | null>(null)
	const formData = ref<SnFormData>({
		remark: ''
	})
	const failResults = ref<SnFormItemVerifyResult[]>([])

	function getFieldError(field: string): string {
		const list = failResults.value
		for (let i = 0; i < list.length; i++) {
			if (list[i].field == field) {
				return list[i].message ?? ''
			}
		}
		return ''
	}

	const remarkRule = ref<SnFormItemRule>({
		max: 100,
		message: '备注最多 100 字'
	} as SnFormItemRule)

	function onFormSubmit(): void {
		formRef.value?.$callMethod('submit', {
			success: () => {
				failResults.value = []
			},
			fail: (results: SnFormItemVerifyResult[]) => {
				failResults.value = results
			}
		} as SnFormValidResult)
	}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值 | String | `''` | - |
| direction | 布局方向，horizontal 标签在左、vertical 标签在上 | String | `vertical` | `horizontal` \| `vertical` |
| label | 标签文字 | String | `''` | - |
| labelSize | 标签字体大小 | String \| Number | `$14` | - |
| labelColor | 标签颜色 | String | `$title` | - |
| labelWidth | 横向布局时标签宽度 | String \| Number | `$80` | - |
| labelAlign | 标签文字水平对齐 | String | `left` | `left` \| `right` \| `center` |
| labelJustify | 标签在容器内的竖向对齐 | String | `top` | `top` \| `center` \| `bottom` |
| required | 是否必填，标签后追加红色 `*` 标记 | Boolean | `false` | `true` \| `false` |
| error | 错误提示文字（存在 error 插槽时不显示） | String | `''` | - |
| errorSize | 错误文字大小 | String \| Number | `$12` | - |
| errorColor | 错误文字颜色 | String | `$error` | - |
| columnGap | 标签与内容的间距 | String \| Number | `$12` | - |
| name | 表单的控件名称，作为键值对的一部分与表单一同提交 | String | `''` | - |
| field | 表单字段名，非空且位于 sn-form 内时注册参与整表校验 | String | `''` | - |
| rule | 校验规则，配合 field 使用 | `SnFormItemRule` | `{}` | - |
| height | 文本域高度（开启 auto-height 后失效），支持 `$` 前缀按间距乘数缩放 | String \| Number | `100px` | - |
| placeholder | 文本域为空时的占位符 | String | `''` | - |
| placeholderStyle | 占位符内联样式 | String | `''` | - |
| placeholderClass | 占位符外部类 | String | `''` | - |
| maxlength | 最大输入长度，`-1` 表示不限制（生效时显示字数统计） | String \| Number | `-1` | - |
| focus | 获取焦点 | Boolean | `false` | `true` \| `false` |
| autoFocus | 自动获取焦点，与 `focus` 相比只在首次生效 | Boolean | `false` | `true` \| `false` |
| autoHeight | 是否自动增高，由内容撑开高度 | Boolean | `false` | `true` \| `false` |
| cursor | 指定聚焦时的光标位置，`-1` 表示不指定 | String \| Number | `-1` | - |
| cursorColor | 光标颜色 | String | `''` | - |
| cursorSpacing | 光标与键盘的距离（px） | String \| Number | `0` | - |
| selectionStart | 光标起始位置，自动聚焦时有效，需与 `selectionEnd` 搭配 | String \| Number | `-1` | - |
| selectionEnd | 光标结束位置，自动聚焦时有效，需与 `selectionStart` 搭配 | String \| Number | `-1` | - |
| confirmType | 键盘右下角按钮的文字 | String | `return` | - |
| confirmHold | 点击键盘右下角按钮时是否保持键盘不收起 | Boolean | `false` | `true` \| `false` |
| holdKeyboard | 聚焦时点击页面不收起键盘 | Boolean | `false` | `true` \| `false` |
| adjustPosition | 键盘弹起时是否自动上推页面 | Boolean | `true` | `true` \| `false` |
| inputmode | 输入模式，影响键盘类型 | String | `text` | - |
| fixed | 是否为固定定位区域内的文本域（如 popup 内使用需开启） | Boolean | `false` | `true` \| `false` |
| showConfirmBar | 是否显示键盘上方的完成栏 | Boolean | `true` | `true` \| `false` |
| disabled | 是否禁用，禁用后不可输入且背景、文字使用禁用配色 | Boolean | `false` | `true` \| `false` |
| readonly | 是否只读，只读时颜色不变 | Boolean | `false` | `true` \| `false` |
| loading | 是否加载中，右上角显示加载指示器（延迟 100ms 显示避免闪烁） | Boolean | `false` | `true` \| `false` |
| loadingClass | 加载指示器外部类 | String | `''` | - |
| loadingStyle | 加载指示器样式 | SnStyleValue | `''` | - |
| showBorder | 是否显示边框 | Boolean | `true` | `true` \| `false` |
| showActiveBorder | 聚焦时是否切换为激活边框颜色 | Boolean | `false` | `true` \| `false` |
| borderColor | 边框颜色 | String | `var(--sn-transparent)` | - |
| activeBorderColor | 聚焦激活时的边框颜色 | String | `$primary` | - |
| bgColor | 背景颜色 | String | `$front` | - |
| activeBgColor | 聚焦时的背景颜色 | String | `$front` | - |
| disabledBgColor | 禁用时的背景颜色 | String | `$disabled` | - |
| textColor | 输入文字颜色 | String | `$text` | - |
| disabledTextColor | 禁用时的文字颜色 | String | `$disabledText` | - |
| borderRadius | 圆角大小 | String \| Number | `$8` | - |
| borderWidth | 边框宽度 | String \| Number | `2` | - |
| padding | 内边距，支持 `$` 前缀按间距乘数缩放 | String | `8px 13px` | - |
| textSize | 输入文字大小 | String \| Number | `$14` | - |
| textFont | 输入文字字体 | String | `''` | - |
| align | 输入文字对齐方式 | String | `left` | `left` \| `center` \| `right` |
| counterSize | 字数统计文字大小 | String \| Number | `$12` | - |
| counterColor | 字数统计文字颜色 | String | `$text` | - |
| counterBgColor | 字数统计背景颜色 | String | `$info` | - |
| labelStyle | 标签节点自定义样式 | SnStyleValue | `''` | - |
| labelClass | 标签节点外部类 | String | `''` | - |
| errorStyle | 错误节点自定义样式 | SnStyleValue | `''` | - |
| errorClass | 错误节点外部类 | String | `''` | - |
| inputStyle | 自定义文本域本体样式 | SnStyleValue | `''` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部类 | String | `''` | - |
| counterClass | 字数统计节点外部类 | String | `''` | - |
| counterStyle | 字数统计节点自定义样式 | SnStyleValue | `''` | - |

> 类型字段：SnFormItemRule（见 https://sinleui.pages.dev/api/types/component#snformitemrule）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| input | (event: UniInputEvent) => Void | 键盘输入时触发，`event.detail = { value, cursor }` |
| focus | (event: UniTextareaFocusEvent) => Void | 文本域聚焦时触发 |
| blur | (event: UniTextareaBlurEvent) => Void | 文本域失去焦点时触发 |
| confirm | (event: UniInputConfirmEvent) => Void | 点击键盘右下角按钮时触发 |
| linechange | (event: UniTextareaLineChangeEvent) => Void | 输入行数变化时触发 |
| keyboardheightchange | (event: UniInputKeyboardHeightChangeEvent) => Void | 键盘高度变化时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| verify | (value: any, callback: (res: SnFormItemVerifyResult) => Void) | - | 按 rule 校验当前表单项并回调结果；一般由 sn-form 自动调用，无需手动调用 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| label | 自定义标签内容，替换 label 属性文字 |
| counter | 自定义字数统计内容，替换默认的计数胶囊 |
| error | 自定义错误提示内容，替换 error 属性文字 |

<DemoPhone name="sn-textarea-field" />

# FormField 表单项

## 基础用法

通用表单项容器基座，是 `sn-input-field`、`sn-textarea-field` 等字段组件的布局外壳，提供「标签 + 内容 + 底部错误提示」结构。

- 内容区可放置原生输入框或任意 `sn-` 表单控件
- 横向布局内容默认右对齐，纵向布局默认左对齐，对齐方式可调
- 置于表单内并配置字段与校验规则时自动参与整表校验，独立使用时仅作布局容器

```vue
<template>
	<sn-form-field label="昵称">
		<input class="demo-input" v-model="nickname" placeholder="请输入昵称" />
	</sn-form-field>
	<sn-form-field label="性别" required>
		<sn-radio-group v-model="gender">
			<sn-radio text="男" />
			<sn-radio text="女" />
		</sn-radio-group>
	</sn-form-field>
	<sn-form-field label="城市" show-border>
		<sn-select v-model="city" :data="cityOptions" width="140px" />
	</sn-form-field>
</template>

<script lang="ts" setup>
	const nickname = ref<string>('')
	const gender = ref<number>(0)
	const city = ref<number>(0)
	const cityOptions = ref<SnDataItem[]>([
		{ id: 'beijing', text: '北京' },
		{ id: 'shanghai', text: '上海' }
	] as SnDataItem[])
</script>
```

**更多演示请下载 demo 查看**

## 配合 sn-form 使用

设置 `field` 与 `rule` 后参与 `sn-form` 整表校验；校验取值为表单 `v-model` 对象中 `field` 对应的值，需把控件的 `v-model` 绑定到该字段，校验失败信息通过 `error` 属性展示。

```vue
<template>
	<sn-form v-model="formData">
		<sn-form-field field="gender" :rule="genderRule" label="性别" :error="getFieldError('gender')">
			<sn-radio-group v-model="(formData['gender'] as number)">
				<sn-radio text="男" />
				<sn-radio text="女" />
			</sn-radio-group>
		</sn-form-field>
	</sn-form>
</template>

<script lang="ts" setup>
	import type { SnFormItemRule } from '@/uni_modules/sinle-ui'

	const genderRule = ref<SnFormItemRule>({
		required: true,
		message: '请选择性别'
	} as SnFormItemRule)
</script>
```

输入类字段（文本、多行文本）建议直接使用 `sn-input-field` / `sn-textarea-field`，它们已内置标签、输入区与错误提示，无需再用 `sn-form-field` 包裹。

## 自定义错误提示

设置 `error` 属性在内容下方显示一行错误文字（对齐跟随 `content-align`）；也可使用 `error` 插槽完全自定义错误内容，优先级高于 `error` 属性。

```vue
<template>
	<sn-form-field label="自定义错误" content-align="left">
		<template #error>
			<sn-icon name="error-warning-line" :size="14" color="#f56c6c" />
			<sn-text font-size="$12" color="$error">请检查输入内容</sn-text>
		</template>
		<sn-switch v-model="value" />
	</sn-form-field>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| direction | 布局方向，horizontal 标签在左、vertical 标签在上 | String | `horizontal` | `horizontal` \| `vertical` |
| field | 表单字段名，非空且位于 sn-form 内时注册参与整表校验 | String | `''` | - |
| rule | 校验规则，配合 field 使用 | `SnFormItemRule` | `{}` | - |
| label | 标签文字 | String | `''` | - |
| labelSize | 标签字体大小 | String \| Number | `$14` | - |
| labelColor | 标签颜色 | String | `$title` | - |
| labelWidth | 横向布局时标签宽度 | String \| Number | `$80` | - |
| labelAlign | 标签文字水平对齐 | String | `left` | `left` \| `right` \| `center` |
| labelJustify | 标签在容器内的竖向对齐 | String | `center` | `top` \| `center` \| `bottom` |
| required | 是否必填，标签后追加红色 `*` 标记 | Boolean | `false` | `true` \| `false` |
| error | 错误提示文字（存在 error 插槽时不显示） | String | `''` | - |
| errorSize | 错误文字大小 | String \| Number | `$12` | - |
| errorColor | 错误文字颜色 | String | `$error` | - |
| columnGap | 标签与内容的间距 | String \| Number | `$12` | - |
| contentAlign | 内容区水平对齐；横向布局默认 right、纵向布局默认 left | String | - | `left` \| `center` \| `right` |
| showBorder | 是否显示底部下划线 | Boolean | `false` | `true` \| `false` |
| borderColor | 下划线颜色 | String | `$line` | - |
| borderWidth | 下划线高度 | String \| Number | `1` | - |
| borderStyle | 下划线节点自定义样式 | SnStyleValue | `''` | - |
| borderClass | 下划线节点外部类 | String | `''` | - |
| bgColor | 背景颜色 | String | `$front` | - |
| borderRadius | 圆角大小 | String \| Number | `$8` | - |
| padding | 内边距，支持 `$` 前缀按间距乘数缩放 | String | `10px 13px` | - |
| labelStyle | 标签节点自定义样式 | SnStyleValue | `''` | - |
| labelClass | 标签节点外部类 | String | `''` | - |
| errorStyle | 错误节点自定义样式 | SnStyleValue | `''` | - |
| errorClass | 错误节点外部类 | String | `''` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部类 | String | `''` | - |
| containStyle | 内容区自定义样式 | SnStyleValue | `''` | - |

> 类型字段：SnFormItemRule（见 https://sinleui.pages.dev/api/types/component#snformitemrule）


## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| verify | (value: any, callback: (res: SnFormItemVerifyResult) => Void) | - | 按 rule 校验当前表单项并回调结果；一般由 sn-form 自动调用，无需手动调用 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 内容区，放置表单控件 |
| label | 自定义标签内容，替换 label 属性文字 |
| error | 自定义错误提示内容，替换 error 属性文字 |

<DemoPhone name="sn-form-field" />

# Keyboard 自定义键盘

## 基础用法

基于底部弹层封装的安全键盘，由组件接管输入，适合替代系统键盘的场景。

- 支持数字、整数、密码全键盘、身份证与车牌五种键盘
- 输入内容与弹层显隐均支持双向绑定，输入变化与完成操作分别派发事件
- 可限制输入长度、开启字符键洗牌；长按退位键一键清空，头部可显示实时输入内容

::: info 配合系统键盘
需要替代系统键盘时，配合 `uni.hideKeyboard()` 使用。
:::

```vue
<template>
	<sn-button text="打开数字键盘" @click="show = true"></sn-button>
	<sn-keyboard type="number" v-model:show="show" v-model="value" :maxlength="10" @confirm="onConfirm"></sn-keyboard>
</template>

<script lang="ts" setup>
const show = ref<boolean>(false)
const value = ref<string>('')

function onConfirm(): void {
	console.log(value.value)
}
</script>
```

**更多演示请下载 demo 查看**

## 密码与车牌键盘

密码键盘支持字母大小写切换与数字/符号模式切换；车牌键盘默认为省份简称汉字模式，可通过键盘上的模式切换键切到字母模式。

```vue
<template>
	<sn-keyboard type="password" v-model:show="pwdShow" v-model="pwd" :maxlength="16"></sn-keyboard>
	<sn-keyboard type="car" v-model:show="carShow" v-model="car" :maxlength="8"></sn-keyboard>
</template>

<script lang="ts" setup>
const pwdShow = ref<boolean>(false)
const pwd = ref<string>('')
const carShow = ref<boolean>(false)
const car = ref<string>('')
</script>
```

## 自定义按键样式

通过 `keyStyle` / `keyTextStyle` / `keyIconStyle` / `keyHoverStyle` 定制按键，`confirmType` / `confirmLevel` / `confirmText` 定制完成键。

```vue
<template>
	<sn-keyboard type="number" v-model:show="show" v-model="value" confirm-type="success" confirm-level="second"
		confirm-text="确定" key-gap="$6"
		key-style="background-color:#DBEAFE;border-radius:8px;border:1px solid #BFDBFE;"
		key-hover-style="background-color:#BFDBFE;"
		key-text-style="color:#1D4ED8;font-size:18px;font-weight:600;"></sn-keyboard>
</template>

<script lang="ts" setup>
const show = ref<boolean>(false)
const value = ref<string>('')
</script>
```

## 注意事项

头部默认显示「安全键盘，放心输入」提示。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 输入内容 | String | `''` | - |
| v-model:show | 弹层显示状态 | Boolean | `false` | `true` \| `false` |
| type | 键盘类型 | String | `number` | `number` \| `int` \| `password` \| `idcard` \| `car` |
| maxlength | 最大输入长度，`0` 表示不限制（车牌键盘不受此限制） | Number | `0` | - |
| show | 是否显示弹层（也可仅用 `v-model:show`） | Boolean | `false` | `true` \| `false` |
| showInput | 是否在头部实时显示已输入内容（内容非空时替换安全提示） | Boolean | `true` | `true` \| `false` |
| longpress | 是否开启长按退位键 1000ms 一键清空 | Boolean | `true` | `true` \| `false` |
| maskClose | 点击遮罩是否关闭 | Boolean | `true` | `true` \| `false` |
| maskOpacity | 遮罩透明度 | Number | `0.3` | - |
| preventBack | 是否阻止返回键关闭 | Boolean | `true` | `true` \| `false` |
| aniTime | 弹层动画时长，支持 `$` 简写 | String \| Number | `$long` | - |
| drawerCustomStyle | 自定义内部抽屉弹层样式 | SnStyleValue | `''` | - |
| drawerHeight | 弹层高度，按键盘类型自动设置（number/idcard/int 为 44%，password 为 52%，car 汉字模式为 60% 等），支持 `$` 前缀按间距乘数缩放 | String \| Number | - | - |
| padding | 弹层内边距，支持 `$` 前缀按间距乘数缩放 | String | `8px 6px 30px 6px` | - |
| confirmType | 完成键的功能色 | String | `primary` | `primary` \| `info` \| `success` \| `error` \| `warning` |
| confirmLevel | 完成键的颜色等级 | String | `first` | `first` \| `second` \| `third` \| `least` |
| confirmText | 完成键文本 | String | `完成` | - |
| shuffle | 是否每次打开时随机打乱字符键顺序（功能键位置固定） | Boolean | `false` | `true` \| `false` |
| keyGap | 按键间距，支持 `$` 简写 | String \| Number | `3` | - |
| keyStyle | 自定义普通按键样式 | SnStyleValue | `''` | - |
| keyClass | 普通按键外部类 | String | `''` | - |
| keyTextStyle | 自定义按键文字样式 | SnStyleValue | `''` | - |
| keyTextClass | 按键文字外部类 | String | `''` | - |
| keyIconStyle | 自定义按键图标样式 | SnStyleValue | `''` | - |
| keyIconClass | 按键图标外部类 | String | `''` | - |
| keyHoverStyle | 自定义按键按下态样式 | SnStyleValue | `''` | - |
| confirmKeyStyle | 自定义完成键样式 | SnStyleValue | `''` | - |
| confirmKeyClass | 完成键外部类 | String | `''` | - |
| confirmKeyTextStyle | 自定义完成键文字样式 | SnStyleValue | `''` | - |
| confirmKeyTextClass | 完成键文字外部类 | String | `''` | - |
| confirmKeyHoverStyle | 自定义完成键按下态样式 | SnStyleValue | `''` | - |
| headerStyle | 自定义头部样式 | SnStyleValue | `''` | - |
| headerClass | 头部外部类 | String | `''` | - |
| headerTextStyle | 自定义头部文字样式 | SnStyleValue | `''` | - |
| headerTextClass | 头部文字外部类 | String | `''` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| update:show | (value: boolean) => Void | 弹层显示状态变化时触发（配合 `v-model:show`） |
| change | (value: string) => Void | 输入内容变化（输入、删除、清空）时触发 |
| confirm | () => Void | 点击完成键时触发，随后自动收起键盘 |
| close | () => Void | 点击头部关闭按钮时触发 |
| open | () => Void | 弹层打开动画结束后触发 |
| close-anim-end | () => Void | 弹层关闭动画结束后触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 打开键盘弹层（开启 `shuffle` 时会先打乱字符键顺序） |
| close | - | - | 收起键盘弹层 |

<DemoPhone name="sn-keyboard" />

# Radio 单选

> [查看 sn-radio 的 2.0 版本差异](/differences/components/sn-radio)

## 基础用法

单选组件，由单选组、圆球形态选项与标签形态选项三部分组成。

- 由单选组统一管理选中状态与组级配置，同一时刻只能选中一项
- 同一组内可混用两种选项形态，索引统一分配
- 选项默认自带右、下外边距并自动换行排列，可改为纵向排列

::: danger 选项必须放在单选组内
选项（`sn-radio` / `sn-radio-tag`）必须是 `sn-radio-group` 的子代，选项自身不维护选中状态，需通过组控制。
:::

```vue
<template>
	<sn-radio-group v-model="current">
		<sn-radio text="确定"></sn-radio>
		<sn-radio text="取消"></sn-radio>
		<sn-radio-tag text="稍后再说"></sn-radio-tag>
	</sn-radio-group>
</template>

<script lang="ts" setup>
const current = ref<number>(0)
</script>
```

**更多演示请下载 demo 查看**

## 组配置下发

`sn-radio-group` 上的尺寸、颜色与样式类等配置会统一下发到组内全部 `sn-radio` / `sn-radio-tag`（这些配置项构成组配置对象 `RadioGroupConfig`）。选项组件自身的同名属性（如 `text-class`、`type`、`level`）优先级高于组配置，可单独覆盖某一选项的表现。尺寸类属性支持 `$` 前缀动态尺寸（乘对应乘数），颜色类属性支持 `$` 简写（如 `$primary` 自动引用主题色变量）。

圆球选项的呈现方式：未选中时圆球为 `line` 色描边、内部圆点为 `front` 色；选中时圆球填充主题色（默认 `$primary`）、内部圆点仍为 `front` 色，形成"彩环 + 白点"效果。

## sn-radio 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| text | 圆球右侧的文本内容 | String | `''` | - |
| disabled | 是否禁用该选项 | Boolean | `false` | `true` \| `false` |
| containStyle | 自定义选项整行容器样式（仅当前选项生效） | SnStyleValue | `''` | - |
| customStyle | 自定义圆球样式（仅当前选项生效） | SnStyleValue | `''` | - |
| textClass | 文本的外部样式类 | String | `''` | - |
| textStyle | 自定义文本样式（仅当前选项生效） | SnStyleValue | `''` | - |

## sn-radio-tag 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| text | 标签内部文本内容 | String | `''` | - |
| type | 标签主题类型，覆盖组配置 `tag-type` | String | - | `primary` \| `info` \| `success` \| `error` \| `warning` |
| level | 标签等级（选中态配色深浅），覆盖组配置 `tag-level` | String | - | `first` \| `second` \| `third` \| `least` |
| disabled | 是否禁用该选项 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义标签样式（仅当前选项生效） | SnStyleValue | `''` | - |
| textClass | 文本的外部样式类 | String | `''` | - |

标签选项未选中时默认 `info` 色背景配 `text` 色文字；选中后配色由 `type` 与 `level` 共同决定：

| level | 背景 | 文字 |
| --- | --- | --- |
| first | `type` 对应原色（如 `$primary`） | `type` 对应文字色（如 `$primaryText`） |
| second | `type` 对应浅色（如 `$primaryLight`） | `type` 对应原色 |
| third | `info` 色 | `type` 对应原色 |
| least | 透明 | `type` 对应原色 |

禁用时未选中为 `disabled` 底配 `disabledText` 字，选中为 `disabledDark` 底配 `disabledDarkText` 字。

## sn-radio-group 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值，当前选中项的索引 | Number | `0` | - |
| vertical | 是否纵向排列 | Boolean | `false` | `true` \| `false` |
| radioSize | 圆球直径 | String \| Number | `'20px'` | - |
| radioBorderWidth | 圆球边缘与内部圆点之间的间隙宽度（圆点直径 = 圆球直径 - 2 × 该值） | String \| Number | `'2px'` | - |
| radioTextSize | 选项文本大小 | String \| Number | `$13` | - |
| radioBgColor | 未选中时圆球内部圆点颜色 | String | `$front` | - |
| disabledRadioBgColor | 禁用且未选中时圆点颜色 | String | `$front` | - |
| radioActiveBgColor | 选中时圆点颜色 | String | `$front` | - |
| disabledRadioActiveBgColor | 禁用且选中时圆点颜色 | String | `$front` | - |
| radioTextColor | 选项文本颜色 | String | `$text` | - |
| disabledRadioTextColor | 禁用状态下选项文本颜色 | String | `$disabledText` | - |
| radioBorderColor | 未选中时圆球颜色 | String | `$line` | - |
| disabledRadioBorderColor | 禁用且未选中时圆球颜色 | String | `$disabled` | - |
| radioActiveBorderColor | 选中时圆球颜色 | String | `$primary` | - |
| disabledRadioActiveBorderColor | 禁用且选中时圆球颜色 | String | `$disabledDark` | - |
| tagType | 标签选项主题类型 | String | `'primary'` | `primary` \| `info` \| `success` \| `error` \| `warning` |
| tagLevel | 标签选项等级 | String | `'second'` | `first` \| `second` \| `third` \| `least` |
| tagBorderRadius | 标签选项圆角 | String \| Number | `'10px'` | - |
| tagPadding | 标签选项内边距 | String | `'6px 10px'` | - |
| tagTextSize | 标签选项文本大小 | String \| Number | `$12` | - |
| tagBgColor | 标签选项未选中时背景颜色 | String | `$info` | - |
| disabledTagBgColor | 禁用且未选中时标签背景颜色 | String | `$disabled` | - |
| tagActiveBgColor | 标签选项选中时背景颜色 | String | - | - |
| disabledTagActiveBgColor | 禁用且选中时标签背景颜色 | String | `$disabledDark` | - |
| tagTextColor | 标签选项未选中时文本颜色 | String | `$text` | - |
| disabledTagTextColor | 禁用且未选中时标签文本颜色 | String | `$disabledText` | - |
| tagActiveTextColor | 标签选项选中时文本颜色 | String | - | - |
| disabledTagActiveTextColor | 禁用且选中时标签文本颜色 | String | `$disabledDarkText` | - |
| radioContainStyle | 自定义圆球选项整行容器样式 | SnStyleValue | `''` | - |
| radioStyle | 自定义圆球样式 | SnStyleValue | `''` | - |
| tagStyle | 自定义标签选项样式 | SnStyleValue | `''` | - |
| textStyle | 自定义选项文本样式 | SnStyleValue | `''` | - |
| radioContainClass | 圆球选项整行容器的外部样式类 | String | `''` | - |
| radioClass | 圆球的外部样式类 | String | `''` | - |
| tagClass | 标签选项根节点的外部样式类 | String | `''` | - |
| textClass | 选项文本的外部样式类 | String | `''` | - |
| customStyle | 自定义单选组根节点样式 | SnStyleValue | `''` | - |

## 事件

**sn-radio-group**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: number) => Void | 选中项变化时触发，携带新选中的索引 |

## 插槽

**sn-radio**

| 名称 | 说明 |
| --- | --- |
| default | 替换圆球右侧的文本内容，可以是任意内容 |

**sn-radio-tag**

| 名称 | 说明 |
| --- | --- |
| default | 替换标签内部的文本内容，可以是任意内容 |

**sn-radio-group**

| 名称 | 说明 |
| --- | --- |
| default | 放置子组件 `sn-radio` 或 `sn-radio-tag` |

<DemoPhone name="sn-radio" />

# Agreement 协议

## 基础用法

用户协议勾选组件，用于协议文本展示与勾选确认。

- 勾选框为自绘的受控样式，勾选状态支持双向绑定
- 协议文本中的链接自动分段高亮，点击链接不改变勾选状态
- 禁用态仅禁止勾选切换，协议链接仍可点击

```vue
<template>
	<sn-agreement v-model="agreed" text="我已阅读并同意《用户协议》和《隐私政策》" :links="['《用户协议》', '《隐私政策》']"
		@change="onChange" @open-link="onOpenLink"></sn-agreement>
</template>
```

**更多演示请下载 demo 查看**

## 自定义样式

可通过 `link-color`、`font-size`、`box-size` 等属性定制外观，也可通过 `box-style` / `box-class`、`text-style` / `text-class`、`link-style` / `link-class` 细调勾选框、文本与链接的样式。

```vue
<template>
	<sn-agreement v-model="agreed" text="我已仔细阅读并完全理解《会员服务协议》《个人信息保护政策》及《免责声明》的全部内容"
		:links="['《会员服务协议》', '《个人信息保护政策》', '《免责声明》']" link-color="$error" font-size="$14"
		box-size="20px"></sn-agreement>
</template>
```

## 注意事项

`links` 中每个链接文本在 `text` 中按首次出现位置匹配；未在 `text` 中出现的链接不渲染，与其他链接重叠时按传入顺序先到先得。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 勾选状态 | Boolean | `false` | `true` \| `false` |
| text | 协议文本内容 | String | `''` | - |
| links | 需要渲染为链接的文本，在 text 中匹配并分段；支持单个链接文本或链接文本数组 | String \| String[] | `''` | - |
| disabled | 禁用组件，仅禁用勾选切换，链接仍可点击 | Boolean | `false` | `true` \| `false` |
| fontSize | 文本字体大小，支持 `$` 前缀按字体大小乘数缩放 | String \| Number | `$13` | - |
| color | 文本颜色，支持 `$` 前缀简写，禁用时为 `$disabledText` | String | `$text` | - |
| linkColor | 链接文本颜色，支持 `$` 前缀简写 | String | `$primary` | - |
| boxSize | 勾选框边长，支持 `$` 前缀按间距乘数缩放 | String \| Number | `$19` | - |
| customStyle | 组件根节点自定义样式 | SnStyleValue | `''` | - |
| customClass | 组件根节点自定义样式类名 | String | `''` | - |
| boxStyle | 勾选框自定义样式 | SnStyleValue | `''` | - |
| boxClass | 勾选框自定义样式类名 | String | `''` | - |
| textStyle | 文本自定义样式 | SnStyleValue | `''` | - |
| textClass | 文本自定义样式类名 | String | `''` | - |
| linkStyle | 链接文本自定义样式 | SnStyleValue | `''` | - |
| linkClass | 链接文本自定义样式类名 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: boolean) => Void | 用户点击勾选框或普通文本切换勾选状态时触发，参数为切换后的勾选状态 |
| open-link | (detail: `AgreementLinkDetail`) => Void | 点击链接文本时触发（不切换勾选状态）；detail 包含 text（点击的链接文本）与 index（该链接在 links 中的序号，从 0 开始） |

> 类型字段：AgreementLinkDetail（见 https://sinleui.pages.dev/api/types/component#agreementlinkdetail）


<DemoPhone name="sn-agreement" />

# Checkbox 复选

> [查看 sn-checkbox 的 2.0 版本差异](/differences/components/sn-checkbox)

## 基础用法

复选组件，用于在一组选项中选中任意多项。

- 提供方框与标签两种形态的选项，可在同一组内混用
- 由复选组统一管理选中状态，选项按组内顺序分配索引
- 选中结果以索引数组双向绑定，支持任意多选

::: danger 选项必须放在复选组内
`sn-checkbox` 与 `sn-checkbox-tag` 自身不维护选中状态，必须作为 `sn-checkbox-group` 的子代使用，由组统一控制。
:::

```vue
<template>
	<sn-checkbox-group v-model="checked">
		<sn-checkbox text="苹果"></sn-checkbox>
		<sn-checkbox text="香蕉"></sn-checkbox>
		<sn-checkbox-tag text="菠萝"></sn-checkbox-tag>
	</sn-checkbox-group>
</template>

<script lang="ts" setup>
const checked = ref<number[]>([])
</script>
```

**更多演示请下载 demo 查看**

## 实现原理

选项通过注入与复选组通信：每个选项在挂载时向组内登记并获得索引（两种形态混用时索引统一分配），选中状态由组统一维护。

组内选项自动换行排列，选项自带右、下外边距；`vertical` 为 `true` 时改为纵向排列。

## 注意事项

再次点击已选中的选项会取消该项选中，其索引从绑定数组中移除。

## 组配置下发

`sn-checkbox-group` 上的尺寸、颜色与样式类等配置会统一下发到组内全部 `sn-checkbox` / `sn-checkbox-tag`（这些配置项构成组配置对象 `CheckboxGroupConfig`）。选项组件自身的同名属性（如 `icon`、`type`、`text-class`）优先级高于组配置，可单独覆盖某一选项的表现。尺寸类属性支持 `$` 前缀动态尺寸（乘对应乘数），颜色类属性支持 `$` 简写（如 `$primary` 自动引用主题色变量）。

## sn-checkbox 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| text | 方框右侧的文本内容 | String | `''` | - |
| icon | 选中时方框内显示的图标名称，覆盖组配置 `box-icon` | String | `''` | - |
| disabled | 是否禁用该选项 | Boolean | `false` | `true` \| `false` |
| containStyle | 自定义选项整行容器样式（仅当前选项生效） | SnStyleValue | `''` | - |
| boxClass | 勾选方框的外部样式类 | String | `''` | - |
| customStyle | 自定义勾选方框样式（仅当前选项生效，定制整行容器用 `containStyle`） | SnStyleValue | `''` | - |
| boxIconClass | 方框内图标的外部样式类 | String | `''` | - |
| textClass | 文本的外部样式类 | String | `''` | - |

## sn-checkbox-tag 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| text | 标签内部文本内容 | String | `''` | - |
| type | 标签主题类型，覆盖组配置 `tag-type`；默认取组配置，兜底 `primary` | String | - | `primary` \| `info` \| `success` \| `error` \| `warning` |
| level | 标签等级（选中态配色深浅），覆盖组配置 `tag-level`；默认取组配置，兜底 `second` | String | - | `first` \| `second` \| `third` \| `least` |
| disabled | 是否禁用该选项 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义标签样式（仅当前选项生效） | SnStyleValue | `''` | - |
| textClass | 文本的外部样式类 | String | `''` | - |

标签选项未选中时默认 `info` 色背景配 `text` 色文字；选中后配色由 `type` 与 `level` 共同决定：

| level | 背景 | 文字 |
| --- | --- | --- |
| first | `type` 对应原色（如 `$primary`） | `type` 对应文字色（如 `$primaryText`） |
| second | `type` 对应浅色（如 `$primaryLight`） | `type` 对应原色 |
| third | `info` 色 | `type` 对应原色 |
| least | 透明 | `type` 对应原色 |

禁用时未选中为 `disabled` 底配 `disabledText` 字，选中为 `disabledDark` 底配 `disabledDarkText` 字。

## sn-checkbox-group 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值，当前选中项的索引数组 | `Array<Number>` | `[]` | - |
| vertical | 是否纵向排列 | Boolean | `false` | `true` \| `false` |
| boxSize | 勾选方框边长 | String \| Number | `'19px'` | - |
| boxBorderRadius | 勾选方框圆角 | String \| Number | `'5px'` | - |
| boxBorderWidth | 勾选方框边框宽度 | String \| Number | `'2px'` | - |
| boxTextSize | 方框选项文本大小 | String \| Number | `$13` | - |
| boxTextColor | 方框选项文本颜色 | String | `$text` | - |
| disabledBoxTextColor | 禁用状态下方框选项文本颜色 | String | `$disabledText` | - |
| boxIcon | 勾选方框内图标名称 | String | `'check-fill'` | - |
| boxIconSize | 勾选方框内图标大小 | String \| Number | `$13` | - |
| boxIconColor | 勾选方框内图标颜色 | String | `'#fff'` | - |
| disabledBoxIconColor | 禁用状态下方框内图标颜色 | String | `'#fff'` | - |
| boxBorderColor | 勾选方框边框颜色 | String | `$line` | - |
| disabledBoxBorderColor | 禁用且未选中时方框边框颜色 | String | `$disabled` | - |
| boxActiveBorderColor | 选中时方框边框颜色 | String | `$primary` | - |
| disabledBoxActiveBorderColor | 禁用且选中时方框边框颜色 | String | `$disabledText` | - |
| boxBgColor | 勾选方框背景颜色 | String | `var(--sn-transparent)` | - |
| disabledBoxBgColor | 禁用且未选中时方框背景颜色 | String | `$disabled` | - |
| boxActiveBgColor | 选中时方框背景颜色 | String | `$primary` | - |
| disabledBoxActiveBgColor | 禁用且选中时方框背景颜色 | String | `$disabledText` | - |
| tagType | 标签选项主题类型 | String | `'primary'` | `primary` \| `info` \| `success` \| `error` \| `warning` |
| tagLevel | 标签选项等级 | String | `'second'` | `first` \| `second` \| `third` \| `least` |
| tagBorderRadius | 标签选项圆角 | String \| Number | `'10px'` | - |
| tagPadding | 标签选项内边距 | String | `'6px 10px'` | - |
| tagTextSize | 标签选项文本大小 | String \| Number | `$12` | - |
| tagBgColor | 标签选项未选中时背景颜色 | String | `$info` | - |
| disabledTagBgColor | 禁用且未选中时标签背景颜色 | String | `$disabled` | - |
| tagActiveBgColor | 标签选项选中时背景颜色；默认由 `tag-type` + `tag-level` 决定 | String | - | - |
| disabledTagActiveBgColor | 禁用且选中时标签背景颜色 | String | `$disabledDark` | - |
| tagTextColor | 标签选项未选中时文本颜色 | String | `$text` | - |
| disabledTagTextColor | 禁用且未选中时标签文本颜色 | String | `$disabledText` | - |
| tagActiveTextColor | 标签选项选中时文本颜色；默认由 `tag-type` + `tag-level` 决定 | String | - | - |
| disabledTagActiveTextColor | 禁用且选中时标签文本颜色 | String | `$disabledDarkText` | - |
| boxContainStyle | 自定义方框选项整行容器样式 | SnStyleValue | `''` | - |
| boxStyle | 自定义勾选方框样式 | SnStyleValue | `''` | - |
| boxIconStyle | 自定义方框内图标样式 | SnStyleValue | `''` | - |
| tagStyle | 自定义标签选项样式 | SnStyleValue | `''` | - |
| textStyle | 自定义选项文本样式 | SnStyleValue | `''` | - |
| boxContainClass | 方框选项整行容器的外部样式类 | String | `''` | - |
| boxClass | 勾选方框的外部样式类 | String | `''` | - |
| boxIconClass | 方框内图标的外部样式类 | String | `''` | - |
| tagClass | 标签选项根节点的外部样式类 | String | `''` | - |
| textClass | 选项文本的外部样式类 | String | `''` | - |
| customStyle | 自定义复选组根节点样式 | SnStyleValue | `''` | - |

## 事件

**sn-checkbox-group**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: number[]) => Void | 选中项变化时触发，携带最新的选中索引数组 |

## 插槽

**sn-checkbox**

| 名称 | 说明 |
| --- | --- |
| default | 替换方框右侧的文本内容，可以是任意内容 |

**sn-checkbox-tag**

| 名称 | 说明 |
| --- | --- |
| default | 替换标签内部的文本内容，可以是任意内容 |

**sn-checkbox-group**

| 名称 | 说明 |
| --- | --- |
| default | 放置子组件 `sn-checkbox` 或 `sn-checkbox-tag` |

<DemoPhone name="sn-checkbox" />

# Tree 树形选择

## 基础用法

树形结构数据的选择与浏览组件。

- 绑定选中节点 id 数组，支持单选与多选（多选默认开启）
- 提供点击行选中与复选框选择两种模式；级联模式下只保存叶子节点 id，父级显示全选 / 半选状态
- 支持异步节点逐层加载（加载时在展开箭头位置显示加载态）与前后缀插槽、节点级图标定制

```vue
<template>
	<sn-tree v-model="value" :data="data" checkable cascade :default-expanded-ids="['docs']"></sn-tree>
</template>
```

**更多演示请下载 demo 查看**

## 进阶用法

### 异步加载

```vue
<template>
	<sn-tree v-model="value" :data="data" checkable cascade :load-data="loadData" @load-error="onLoadError"></sn-tree>
</template>
<script lang="ts" setup>
	function loadData(item: SnTreeItem, resolve: SnTreeLoadResolve, reject: SnTreeLoadReject): void {
		requestChildren(item.id).then((children: SnTreeData) => {
			resolve(children)
		}).catch(() => {
			reject()
		})
	}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 选中节点 id 数组（cascade 模式下仅包含叶子节点 id） | String[] | `[]` | - |
| data | 树形数据源 | SnTreeData | `[]` | - |
| checkable | 是否显示复选框（false 时为行高亮选中） | Boolean | `false` | `true \| false` |
| multiple | 是否多选（false 时始终最多保留一个 id） | Boolean | `true` | `true \| false` |
| cascade | 是否级联选择（多选下父级显示全选/半选，值只存叶子 id） | Boolean | `false` | `true \| false` |
| selectable | 行是否可选中（false 且 checkable 为 false 时点击整行仅展开/收起） | Boolean | `true` | `true \| false` |
| disableParentSelection | 是否禁止选中父节点（开启后父节点不显示复选框） | Boolean | `false` | `true \| false` |
| defaultExpandedIds | 默认展开的节点 id 数组 | String[] | `[]` | - |
| loadData | 异步加载子级数据的函数（item 为 lazy 节点，通过 resolve/reject 返回子级） | SnTreeLoadData | `null` | - |
| icon | 展开开关图标名（收起态） | String | `arrow-right-s-line` | - |
| activeIcon | 展开开关图标名（展开态） | String | `arrow-right-s-line` | - |
| rotate | 展开时开关图标旋转角度（deg） | Number | `90` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| customClass | 自定义根节点外部样式类 | String | - | - |
| itemStyle | 自定义节点行样式 | SnStyleValue | - | - |
| itemClass | 外部样式类 | String | - | - |
| lineStyle | 自定义选中指示竖线样式 | SnStyleValue | - | - |
| lineClass | 外部样式类 | String | - | - |
| arrowStyle | 自定义展开开关容器样式 | SnStyleValue | - | - |
| arrowClass | 外部样式类 | String | - | - |
| checkboxStyle | 自定义复选框样式 | SnStyleValue | - | - |
| checkboxClass | 外部样式类 | String | - | - |
| textStyle | 自定义节点文字样式 | SnStyleValue | - | - |
| textClass | 外部样式类 | String | - | - |
| selectedTextStyle | 自定义选中节点文字样式 | SnStyleValue | - | - |
| selectedTextClass | 外部样式类 | String | - | - |

> 类型字段：SnTreeData（见 https://sinleui.pages.dev/api/types/component#sntreedata）

> 类型字段：SnTreeLoadData（见 https://sinleui.pages.dev/api/types/component#sntreeloaddata）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: String[], item: `SnTreeItem`) => Void | 选中值变化时触发，`value` 为最新 id 数组，`item` 为本次操作的节点 |
| expand | (item: `SnTreeItem`, expanded: Boolean) => Void | 节点展开/收起时触发 |
| load-error | (item: `SnTreeItem`) => Void | 异步加载子级失败时触发 |

> 类型字段：SnTreeItem（见 https://sinleui.pages.dev/api/types/component#sntreeitem）


:::

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| expand | id: String | - | 展开指定节点 |
| collapse | id: String | - | 收起指定节点 |

## 插槽

| 名称 | 说明 | 作用域参数 |
| --- | --- | --- |
| prefix | 节点文字前插入自定义内容 | item: `SnTreeItem` |
| suffix | 节点文字后插入自定义内容 | item: `SnTreeItem` |

## 类型

### SnTreeData

`SnTreeItem[]`：树形数据源。

### SnTreeLoadData

`(item: SnTreeItem, resolve: SnTreeLoadResolve, reject: SnTreeLoadReject) => Void`：异步加载函数，`resolve(children)` 返回子级数据，`reject()` 表示加载失败。

# Label Radio 标签单选

> [查看 sn-label-radio 的 2.0 版本差异](/differences/components/sn-label-radio)

## 基础用法

标签形式的单选组件，只需提供数据即可使用，比 Radio 更简单。

- 由数据数组驱动选项，选中项以索引双向绑定
- 选中项显示图标并高亮文本
- 支持整组禁用，也可单独禁用某一项

::: info $ 简写
- 颜色、尺寸类属性均支持 `$` 简写（如 `item-bg-color="$primaryLight"`、`text-size="$16"`）
:::

```vue
<template>
	<sn-label-radio v-model="selected" :data="data"></sn-label-radio>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 选中的选项索引 | Number | `0` | - |
| data | 选项数据数组 | `SnDataItem`[] | `[]` | - |
| disabled | 是否禁用所有选项 | Boolean | `false` | `true` \| `false` |
| itemBgColor | 选项背景颜色 | String | `$front` | - |
| activeItemBgColor | 选项按压时的背景颜色 | String | `$info` | - |
| disabledItemBgColor | 禁用选项的背景颜色 | String | `$disabled` | - |
| disabledTextColor | 禁用选项的文本颜色 | String | `$disabledText` | - |
| disabledIconColor | 禁用且选中选项的图标颜色 | String | `$disabledText` | - |
| itemPadding | 选项内边距 | String | `12px 20px` | - |
| textColor | 选项文本颜色 | String | `$text` | - |
| activeTextColor | 选中时选项文本颜色 | String | `$primary` | - |
| textSize | 选项文本大小 | String \| Number | `$14` | - |
| icon | 选中项显示的图标名称，为空时不显示图标 | String | `check-line` | - |
| iconPosition | 图标位置 | String | `left` | `left` \| `right` |
| iconColor | 选中项图标颜色 | String | `$primary` | - |
| iconSize | 图标大小 | String \| Number | `$16` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| itemStyle | 自定义每个选项的样式 | SnStyleValue | `''` | - |
| itemClass | 自定义每个选项的样式类 | String | `''` | - |

> 类型字段：SnDataItem（见 https://sinleui.pages.dev/api/types/component#sndataitem）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: number) => Void | 选中项变化时触发，携带最新的选中索引 |

<DemoPhone name="sn-label-radio" />

# Label Checkbox 标签多选

> [查看 sn-label-checkbox 的 2.0 版本差异](/differences/components/sn-label-checkbox)

## 基础用法

标签形式的多选组件，只需提供数据即可使用，比 Checkbox 更简单。

- 由数据数组驱动选项，选中项以索引数组双向绑定并自动升序排列
- 选中项显示图标并高亮文本
- 支持整组禁用，也可单独禁用某一项

::: info $ 简写
- 颜色、尺寸类属性均支持 `$` 简写（如 `item-bg-color="$successLight"`、`text-size="$16"`）
:::

```vue
<template>
	<sn-label-checkbox v-model="selected" :data="data"></sn-label-checkbox>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 选中的选项索引数组 | number[] | `[]` | - |
| data | 选项数据数组 | `SnDataItem`[] | `[]` | - |
| disabled | 是否禁用所有选项 | Boolean | `false` | `true` \| `false` |
| itemBgColor | 选项背景颜色 | String | `$front` | - |
| activeItemBgColor | 选项按压时的背景颜色 | String | `$info` | - |
| disabledItemBgColor | 禁用选项的背景颜色 | String | `$disabled` | - |
| disabledTextColor | 禁用选项的文本颜色 | String | `$disabledText` | - |
| disabledIconColor | 禁用且选中选项的图标颜色 | String | `$disabledText` | - |
| itemPadding | 选项内边距 | String | `12px 20px` | - |
| textColor | 选项文本颜色 | String | `$text` | - |
| activeTextColor | 选中时选项文本颜色 | String | `$primary` | - |
| textSize | 选项文本大小 | String \| Number | `$14` | - |
| icon | 选中项显示的图标名称，为空时不显示图标 | String | `check-line` | - |
| iconPosition | 图标位置 | String | `left` | `left` \| `right` |
| iconColor | 选中项图标颜色 | String | `$primary` | - |
| iconSize | 图标大小 | String \| Number | `$16` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| itemStyle | 自定义每个选项的样式 | SnStyleValue | `''` | - |
| itemClass | 自定义每个选项的样式类 | String | `''` | - |

> 类型字段：SnDataItem（见 https://sinleui.pages.dev/api/types/component#sndataitem）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: number[]) => Void | 选中项变化时触发，携带最新的选中索引数组 |

<DemoPhone name="sn-label-checkbox" />

# Select 选择框

> [查看 sn-select 的 2.0 版本差异](/differences/components/sn-select)

## 基础用法

用于简单单选的数据选择器，点击选择框后在锚点附近弹出选项列表，点选即完成选择。

- 数据项支持左右双图标、文字样式与禁用
- 选中态支持背景高亮与前置对钩两种模式，展开时自动滚动定位到当前选中项
- 下方空间不足时自动翻转到上方；在弹层内使用时沿用弹出层层级，遮罩拦截底层触摸滚动

::: danger 必须放在 sn-page 下
组件内含弹出层，使用时需放在 `sn-page` 根节点下。
:::

::: info 平台差异
HarmonyOS 端弹出菜单阴影使用较轻的默认值，仍可通过弹层样式自定义；菜单透明度由入退场动画控制，遮罩独立淡入淡出。
:::

```vue
<template>
	<sn-select v-model="value" :data="data" width="200px"></sn-select>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 当前选中项的索引 | Number | `0` | - |
| data | 选项数据源 | `SnSelectItem`[] | `[]` | - |
| width | 选择框宽度（弹出层宽度与其一致），支持 `$` 前缀按间距乘数缩放 | String \| Number | `100px` | - |
| bgColor | 选择框背景颜色 | String | `$front` | - |
| popBgColor | 弹出层背景颜色 | String | `$front` | - |
| selectedMode | 选中项展示模式：bg 为选中项背景高亮，check 为选中项前置对钩图标 | String | `bg` | `bg` \| `check` |
| selectedItemBgColor | 选中项背景颜色（selectedMode 为 bg 时生效） | String | `$infoDark` | - |
| selectedItemTextColor | 选中项文字颜色（selectedMode 为 bg 时生效） | String | `$primaryDark` | - |
| checkIconColor | 选中项对钩图标颜色（selectedMode 为 check 时生效） | String | `$primary` | - |
| checkIconSize | 选中项对钩图标大小（selectedMode 为 check 时生效） | String \| Number | `$14` | - |
| textSize | 选择框文本大小 | String \| Number | `$14` | - |
| textColor | 选择框文本颜色（下拉箭头同色） | String | `$text` | - |
| leftIcon | 选择框左侧默认图标 | String | `''` | - |
| rightIcon | 选项右侧默认图标 | String | `''` | - |
| leftIconColor | 左侧图标默认颜色 | String | `$text` | - |
| rightIconColor | 右侧图标默认颜色 | String | `$text` | - |
| leftIconSize | 左侧图标默认尺寸 | String \| Number | `$18` | - |
| rightIconSize | 右侧图标默认尺寸 | String \| Number | `$16` | - |
| borderRadius | 选择框与弹出层圆角大小 | String \| Number | `$8` | - |
| maxHeight | 弹出层选项列表最大高度，支持 `$` 前缀按间距乘数缩放 | String \| Number | `500px` | - |
| maskOpacity | 弹出层蒙层透明度 | Number | `0` | `0~1` |
| aniTime | 弹出层动画时长 | String \| Number | `$200` | - |
| disabled | 是否禁用选择框（整体半透明且不可点击） | Boolean | `false` | `true` \| `false` |
| itemBorder | 选项之间是否显示分隔线（最后一项不显示） | Boolean | `true` | `true` \| `false` |
| itemStyle | 自定义选项（sn-cell）样式 | SnStyleValue | - | - |
| itemClass | 自定义选项外部样式类 | String | - | - |
| itemHoverStyle | 自定义选项按压态样式 | SnStyleValue | `background: var(--sn-info);` | - |
| itemTextStyle | 自定义选项文字样式 | SnStyleValue | - | - |
| itemIconStyle | 自定义选项图标样式 | SnStyleValue | - | - |
| hoverStyle | 选择框按压态样式 | SnStyleValue | `background: var(--sn-info);` | - |
| hoverStartTime | 按压态启动延时（ms） | Number | `50` | - |
| hoverStayTime | 松手后按压态保持时长（ms） | Number | `0` | - |
| hoverTransTime | 按压态过渡动画时长 | String \| Number | - （默认取 `$snui.aniTimeShort`） | - |
| customStyle | 自定义选择框根节点样式 | SnStyleValue | - | - |
| textStyle | 自定义选择框文本样式 | SnStyleValue | - | - |
| textClass | 自定义选择框文本外部样式类 | String | - | - |
| popStyle | 自定义弹出层容器样式 | SnStyleValue | - | - |
| popClass | 自定义弹出层容器外部样式类 | String | - | - |

> 类型字段：SnSelectItem（见 https://sinleui.pages.dev/api/types/component#snselectitem）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: Number) => Void | 选中项变化时触发，`value` 即为选中项索引 |

<DemoPhone name="sn-select" />

# Cascader 级联选择器

## 基础用法

从底部弹出的多级联动选择器，适合多层级数据的逐级选择。

- 数据层级不限，支持静态数据与逐层异步加载两种来源
- 顶部导航条展示已选路径，可点击回退或左右滑动切换层级
- 点选选项即写入绑定值并触发变化事件，无需确认

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下（页面根节点或 `sn-page` 的直接子节点），否则页面的 `--sn-*`、`--ani-time-*` 变量不生效，颜色与动画异常。
:::

```vue
<template>
	<sn-cascader ref="cascaderEle" v-model="value" :data="data" title="请选择商品分类" @change="onChange"></sn-cascader>
</template>
```

**更多演示请下载 demo 查看**

## 实现原理

组件基于 `sn-drawer` 封装，`children` 支持任意层级；顶部导航条（已选路径、未选层级的占位项与随层级切换移动的下划线）与当前层级的选项列表均由组件内部渲染。

## 注意事项

选中叶子节点后弹出层自动关闭；选项满足以下任一条件即视为叶子节点：`leaf` 为 `true`、`children` 为空数组、或 `children` 为空且未配置 `loadData`。

## 进阶用法

### 异步加载

```vue
<template>
	<sn-cascader ref="cascaderEle" v-model="value" :load-data="loadData" @load-error="onLoadError"></sn-cascader>
</template>
<script lang="ts" setup>
	function loadData(parent: SnCascaderOption | null, level: number, resolve: SnCascaderResolve, reject: SnCascaderReject): void {
		if (parent == null) {
			resolve(rootOptions)
			return
		}
		requestChildren(parent.value, level).then((options: SnCascaderOption[]) => {
			resolve(options)
		}).catch(() => {
			reject()
		})
	}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 当前选中的值路径（各级 option 的 value 数组） | SnCascaderValue | `[]` | - |
| data | 级联数据源（静态数据，children 任意嵌套） | SnCascaderOption[] | `[]` | - |
| loadData | 异步加载子级数据的函数，通过 resolve/reject 返回该层结果 | SnCascaderLoadData | `null` | - |
| disabled | 是否禁用（禁用后无法打开，所有选项视为禁用） | Boolean | `false` | `true \| false` |
| height | 弹出层整体高度 | String \| Number | `470px` | - |
| title | 标题 | String | `请选择` | - |
| titleSize | 标题字号 | String \| Number | `$17` | - |
| placeholder | 未选层级在导航条上的占位文字 | String | `请选择` | - |
| loadingText | 加载中提示文字 | String | `加载中` | - |
| emptyText | 无数据提示文字 | String | `暂无数据` | - |
| navTextSize | 导航条文字字号 | String \| Number | `$15` | - |
| stateTextSize | 加载中/空状态提示文字字号 | String \| Number | `$13` | - |
| loadingIconSize | 加载图标大小 | String \| Number | `$22` | - |
| closeIconSize | 关闭图标大小 | String \| Number | `$22` | - |
| showClose | 是否显示右上角关闭按钮 | Boolean | `true` | `true \| false` |
| showScrollbar | 选项列表是否显示滚动条 | Boolean | `true` | `true \| false` |
| itemBorder | 选项之间是否显示分隔线 | Boolean | `false` | `true \| false` |
| navMode | 导航条下划线切换动画方式：swipe 平移滑动，push 挤压伸展 | String | `swipe` | `swipe \| push` |
| maskClose | 是否可以通过点击蒙层关闭 | Boolean | `true` | `true \| false` |
| maskOpacity | 蒙层透明度 | Number | `0.4` | `0~1` |
| preventBack | 是否阻止返回键/返回手势关闭 | Boolean | `false` | `true \| false` |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| customClass | 自定义根节点外部样式类 | String | - | - |
| headerStyle | 自定义标题栏样式 | SnStyleValue | - | - |
| headerClass | 外部样式类 | String | - | - |
| titleStyle | 自定义标题样式 | SnStyleValue | - | - |
| titleClass | 外部样式类 | String | - | - |
| closeStyle | 自定义关闭按钮样式 | SnStyleValue | - | - |
| closeClass | 外部样式类 | String | - | - |
| navStyle | 自定义导航条容器样式 | SnStyleValue | - | - |
| navClass | 外部样式类 | String | - | - |
| navItemStyle | 自定义导航项样式 | SnStyleValue | - | - |
| navItemClass | 外部样式类 | String | - | - |
| navTextStyle | 自定义导航项文字样式 | SnStyleValue | - | - |
| navTextClass | 外部样式类 | String | - | - |
| activeNavTextStyle | 自定义当前层级导航项文字样式 | SnStyleValue | - | - |
| activeNavTextClass | 外部样式类 | String | - | - |
| listStyle | 自定义选项列表样式 | SnStyleValue | - | - |
| listClass | 外部样式类 | String | - | - |
| optionStyle | 自定义选项样式 | SnStyleValue | - | - |
| optionClass | 外部样式类 | String | - | - |
| optionTextStyle | 自定义选项文字样式 | SnStyleValue | - | - |
| optionTextClass | 外部样式类 | String | - | - |
| activeOptionTextStyle | 自定义选中选项文字样式 | SnStyleValue | - | - |
| activeOptionTextClass | 外部样式类 | String | - | - |
| optionIconStyle | 自定义选项图标样式 | SnStyleValue | - | - |
| optionIconClass | 外部样式类 | String | - | - |
| activeOptionIconStyle | 自定义选中选项对钩图标样式 | SnStyleValue | - | - |
| activeOptionIconClass | 外部样式类 | String | - | - |

> 类型字段：SnCascaderValue（见 https://sinleui.pages.dev/api/types/component#sncascadervalue）

> 类型字段：SnCascaderOption（见 https://sinleui.pages.dev/api/types/component#sncascaderoption）

> 类型字段：SnCascaderLoadData（见 https://sinleui.pages.dev/api/types/component#sncascaderloaddata）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: `SnCascaderValue`, detail: `SnCascaderDetail`) => Void | 点选选项后触发，v-model 同步更新 |
| select | (value: `SnCascaderValue`, detail: `SnCascaderDetail`) => Void | 点选选项后触发（与 change 同时触发） |
| cancel | () => Void | 点击关闭按钮时触发 |
| load | (parent: `SnCascaderOption` \| null, level: Number, options: `SnCascaderOption`[]) => Void | 异步加载成功后触发 |
| load-error | (parent: `SnCascaderOption` \| null, level: Number) => Void | 异步加载失败时触发 |
| open | () => Void | 弹出层打开后触发 |
| close | () => Void | 弹出层关闭后触发 |
| clickoverlay | () => Void | 点击蒙层时触发 |
| beforeenter | () => Void | 进入动画开始前触发 |
| enter | () => Void | 进入动画开始时触发 |
| afterenter | () => Void | 进入动画结束后触发 |
| beforeleave | () => Void | 离开动画开始前触发 |
| leave | () => Void | 离开动画开始时触发 |
| afterleave | () => Void | 离开动画结束后触发 |

> 类型字段：SnCascaderDetail（见 https://sinleui.pages.dev/api/types/component#sncascaderdetail）


## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 打开级联选择器（重置路径并按 v-model 回溯定位） |
| close | - | - | 关闭级联选择器 |

<DemoPhone name="sn-cascader" />

# Picker 选择器

> [查看 sn-picker 的 2.0 版本差异](/differences/components/sn-picker)

## 基础用法

从底部弹出的多列滚动选择器，适合数据量大或结构较复杂的选择场景。

- 支持多列数据选择，每列可独立滚动
- 选择结果仅在确认后写入绑定值，取消或关闭都不写入
- 标题栏、按钮与选项样式均可定制

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下（页面根节点或 `sn-page` 的直接子节点），否则页面的 `--sn-*`、`--ani-time-*` 变量不生效，颜色与动画异常。
:::

::: info 简单数据用 sn-select
仅需单项或少量选项选择时，推荐使用 `sn-select` 组件。
:::

```vue
<template>
	<sn-picker ref="pickerEle" v-model="value" :data="data" title="请选择" @confirm="onConfirm"></sn-picker>
</template>
```

**更多演示请下载 demo 查看**

## 实现原理

组件基于 `sn-drawer` + `sn-picker-view` 封装。

## 注意事项

- 组件自身不带触发入口，需通过 ref 调用 `open()` 打开
- 颜色与尺寸类属性均支持 `$` 简写语法（如 `$primary` 自动引用主题色变量）

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 当前选中的选项索引数组 | Number[] | `[]` | - |
| data | 选择器数据数组，每个子数组代表一列 | `SnDataItem`[][] | `[]` | - |
| disabled | 是否禁用选择器（选项不可滚动、按钮不可点击） | Boolean | `false` | `true` \| `false` |
| maskClose | 是否可以通过点击蒙层关闭选择器 | Boolean | `true` | `true` \| `false` |
| maskOpacity | 蒙层透明度 | Number | `0.4` | `0~1` |
| preventBack | 是否阻止返回键/返回手势关闭选择器 | Boolean | `false` | `true` \| `false` |
| height | 选择器整体高度（含标题与按钮区域） | String \| Number | `350px` | - |
| title | 选择器标题，为空时不显示标题 | String | - | - |
| titleAlign | 标题对齐方式 | String | `center` | `left` \| `center` \| `right` |
| titleColor | 标题颜色 | String | `$title` | - |
| titleSize | 标题大小 | String \| Number | `$14` | - |
| cancelText | 取消按钮文字 | String | `取消` | - |
| confirmText | 确定按钮文字 | String | `确定` | - |
| cancelTextSize | 取消按钮文字大小 | String \| Number | `$14` | - |
| confirmTextSize | 确定按钮文字大小 | String \| Number | `$14` | - |
| showCancel | 是否显示取消按钮 | Boolean | `true` | `true` \| `false` |
| showConfirm | 是否显示确定按钮 | Boolean | `true` | `true` \| `false` |
| showClose | 是否显示右上角关闭按钮 | Boolean | `true` | `true` \| `false` |
| columnSpacing | 列之间的间距 | String \| Number | `10px` | - |
| actionSpacing | 取消/确定按钮之间的间距 | String \| Number | `10px` | - |
| itemHeight | 选项高度 | String \| Number | `$50` | - |
| itemBorderRadius | 选项圆角大小 | String \| Number | `$8` | - |
| itemTextColor | 选项文字颜色 | String | `$textLight`（亮色模式）/ `$lineText`（暗黑模式） | - |
| itemTextSize | 选项文字大小 | String \| Number | `$13` | - |
| activeItemTextColor | 激活选项文字颜色 | String | `$text` | - |
| disabledItemTextColor | 禁用选项文字颜色 | String | `$disabledText` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| headerStyle | 自定义标题栏样式 | SnStyleValue | - | - |
| headerClass | 自定义标题栏外部样式类 | String | - | - |
| titleStyle | 自定义标题样式 | SnStyleValue | - | - |
| titleClass | 自定义标题外部样式类 | String | - | - |
| closeButtonStyle | 自定义关闭按钮样式 | SnStyleValue | - | - |
| closeButtonClass | 自定义关闭按钮外部样式类 | String | - | - |
| actionsStyle | 自定义底部按钮栏样式 | SnStyleValue | - | - |
| actionsClass | 自定义底部按钮栏外部样式类 | String | - | - |
| cancelButtonStyle | 自定义取消按钮样式 | SnStyleValue | - | - |
| cancelButtonClass | 自定义取消按钮外部样式类 | String | - | - |
| confirmButtonStyle | 自定义确定按钮样式 | SnStyleValue | - | - |
| confirmButtonClass | 自定义确定按钮外部样式类 | String | - | - |
| itemStyle | 自定义选项样式 | SnStyleValue | - | - |
| itemClass | 自定义选项外部样式类 | String | - | - |
| columnStyle | 自定义列样式 | SnStyleValue | - | - |
| columnClass | 自定义列外部样式类 | String | - | - |

> 类型字段：SnDataItem（见 https://sinleui.pages.dev/api/types/component#sndataitem）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: Number[]) => Void | 点击确定后，选中值写入 v-model 时触发 |
| confirm | () => Void | 点击确定按钮时触发（在 change 之前触发） |
| cancel | () => Void | 点击取消按钮时触发 |
| open | () => Void | 选择器打开后触发 |
| close | () => Void | 选择器关闭后触发 |
| clickoverlay | () => Void | 点击蒙层时触发 |
| beforeenter | () => Void | 进入动画开始前触发 |
| enter | () => Void | 进入动画开始时触发 |
| afterenter | () => Void | 进入动画结束后触发 |
| beforeleave | () => Void | 离开动画开始前触发 |
| leave | () => Void | 离开动画开始时触发 |
| afterleave | () => Void | 离开动画结束后触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 打开选择器（打开前会将 v-model 当前值复制为内部临时值，仅确定后才写回） |
| close | - | - | 关闭选择器 |

---

## sn-picker-view 选择器容器

`sn-picker-view` 是基于官方 `picker-view` 封装的多列选择器容器，可独立在页面内使用，也是 `sn-picker` 的内部核心。扩展了禁用项（滚动到禁用项会回弹）、禁用状态拦截与指示器、选项样式定制；颜色与尺寸均支持 `$` 简写语法。

```vue
<template>
	<sn-picker-view v-model="value" :data="data"></sn-picker-view>
</template>
```

### sn-picker-view 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 当前选中的选项索引数组 | Number[] | `[]` | - |
| data | 选择器数据数组，每个子数组代表一列 | `SnDataItem`[][] | `[]` | - |
| disabled | 是否禁用选择器容器（通过透明遮罩拦截操作） | Boolean | `false` | `true` \| `false` |
| height | 选择器容器高度 | String \| Number | `250px` | - |
| itemHeight | 选项高度 | String \| Number | `$50` | - |
| itemBorderRadius | 选项圆角大小（同时作用于指示器圆角） | String \| Number | `$8` | - |
| itemTextColor | 选项文字颜色 | String | `$textLight`（亮色模式）/ `$lineText`（暗黑模式） | - |
| itemTextSize | 选项文字大小 | String \| Number | `$13` | - |
| activeItemTextColor | 激活选项文字颜色 | String | `$text` | - |
| disabledItemTextColor | 禁用选项文字颜色 | String | `$disabledText` | - |
| columnSpacing | 列间距 | String \| Number | `10px` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| customClass | 自定义根节点外部样式类 | String | - | - |
| itemStyle | 自定义选项样式 | SnStyleValue | - | - |
| itemClass | 自定义选项外部样式类 | String | - | - |
| columnStyle | 自定义列样式 | SnStyleValue | - | - |
| columnClass | 自定义列外部样式类 | String | - | - |

### sn-picker-view 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: Number[]) => Void | 滚动选择导致选中值变化时触发（实时触发，不等确认） |

<DemoPhone name="sn-picker" />

# DatetimePicker 日期时间选择器

> [查看 sn-datetime-picker 的 2.0 版本差异](/differences/components/sn-datetime-picker)

## 基础用法

从底部弹出的日期时间滚动选择器，用于选择日期与时间。

- 年、月、日、时、分、秒可自由组合
- 支持列选项过滤、自定义列标签与可选范围限制
- 双向绑定兼容格式化字符串与毫秒时间戳

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下（页面根节点或 `sn-page` 的直接子节点），否则页面的 `--sn-*`、`--ani-time-*` 变量不生效，颜色与动画异常。
:::

::: info 仅确定后写入
滚动选择期间不会改动 `v-model`；点击「取消」、遮罩或关闭按钮均放弃本次选择。
:::

```vue
<template>
	<sn-datetime-picker ref="pickerEle" v-model="value" mode="年月日" title="请选择日期"></sn-datetime-picker>
</template>
```

**更多演示请下载 demo 查看**

## 实现原理

组件基于 `sn-drawer` + `sn-datetime-picker-view` 封装；选择视图在首次打开后才渲染（懒渲染），首开性能更佳。

## 模式组合

`mode` 属性控制显示年、月、日、时、分、秒的组合，支持传入汉字或位掩码数字：

- **汉字组合**：直接传入连续的汉字（必须连续，不能出现"年分"这类跳级组合），如 `年月日`、`日时`。
- **位掩码**：数字对应 `1` 年、`2` 月、`4` 日、`8` 时、`16` 分、`32` 秒，可传按位或运算表达式的结果（如 `7` 即年月日），也支持包含汉字的混合写法。

```vue
<template>
	<sn-datetime-picker v-model="value1" mode="年月日"></sn-datetime-picker>
	<sn-datetime-picker v-model="value2" mode="时分"></sn-datetime-picker>
	<sn-datetime-picker v-model="value3" :mode="7"></sn-datetime-picker>
	<sn-datetime-picker v-model="value4" :mode="15"></sn-datetime-picker>
</template>
```

默认 `mode` 为 `7`（年月日）。以时/分/秒开头的纯时间模式下，时/分/秒范围由 `minHour` / `maxHour` 等属性控制；日期模式下列范围会随 `start` / `end` 与当前选中值逐级收窄（如选中最小年时月份列从最小月开始）。

## 过滤项

传入 `customFilter` 函数可对各列选项数组进行过滤，剔除指定项。此函数在每一列均会执行一次，请做好条件判断。

函数类型：`(type: SnDatetimePickerTimeModeValue, columns: SnDataItem[]) => SnDataItem[]`

- type：当前列类型，为 `year` / `month` / `date` / `hour` / `minute` / `second` 枚举值。
- columns：当前列的子项列表（`SnDataItem[]`，`id` 为该项数值文本）。

```vue
<template>
	<sn-datetime-picker v-model="value" :custom-filter="filter"></sn-datetime-picker>
</template>
<script lang="ts" setup>
	const filter = (type: SnDatetimePickerTimeModeValue, columns: SnDataItem[]): SnDataItem[] => {
		if (type == 'date') {
			return columns.filter((item: SnDataItem): boolean => parseInt(item.id!) % 2 != 0)
		}
		return columns
	}
</script>
```

## 自定义列标签

传入 `renderLabel` 函数可自定义各列标签（默认为"xxx年""xxx月"等，`showUnit` 为 false 时为纯数字）。此函数在每一子项均会执行一次，请做好条件判断。

函数类型：`(type: string, value: string) => string`

```vue
<template>
	<sn-datetime-picker v-model="value" :render-label="renderLabel"></sn-datetime-picker>
</template>
<script lang="ts" setup>
	const renderLabel = (type: string, value: string): string => {
		if (type == 'year') return `Y${value}`
		if (type == 'month') return `M${value}`
		return value
	}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定的日期值（字符串按 format 解析，数字为毫秒时间戳） | SnDatetimePickerValue | `当前时间` | - |
| mode | 选择器模式（详见模式组合） | String \| Number | `7` | - |
| format | 日期格式化字符串（解析与输出均按此格式） | String | `YYYY-MM-DD HH:mm:ss` | - |
| start | 可选开始日期（无效或未设置时为 10 年前） | SnDatetimePickerValue | - | - |
| end | 可选结束日期（无效或未设置时为 10 年后） | SnDatetimePickerValue | - | - |
| customFilter | 自定义过滤项函数（详见过滤项） | Function | `null` | - |
| renderLabel | 自定义列标签函数（详见自定义列标签） | Function | `null` | - |
| showUnit | 是否显示单位（年/月/日/时/分/秒） | Boolean | `true` | `true \| false` |
| minHour | 最小小时值 | Number | `0` | `0~23` |
| maxHour | 最大小时值 | Number | `23` | `0~23` |
| minMinute | 最小分钟值 | Number | `0` | `0~59` |
| maxMinute | 最大分钟值 | Number | `59` | `0~59` |
| minSecond | 最小秒数值 | Number | `0` | `0~59` |
| maxSecond | 最大秒数值 | Number | `59` | `0~59` |
| disabled | 是否禁用选择器（选项不可滚动、按钮不可点击） | Boolean | `false` | `true \| false` |
| maskClose | 是否可以通过点击蒙层关闭选择器 | Boolean | `true` | `true \| false` |
| maskOpacity | 蒙层透明度 | Number | `0.4` | `0~1` |
| preventBack | 是否阻止返回键/返回手势关闭选择器 | Boolean | `false` | `true \| false` |
| height | 选择器整体高度（含标题与按钮区域） | String \| Number | `400px` | - |
| title | 选择器标题，为空时不显示标题 | String | - | - |
| titleAlign | 标题对齐方式 | String | `center` | `left \| center \| right` |
| titleColor | 标题颜色 | String | `$title` | - |
| titleSize | 标题大小 | String \| Number | `$14` | - |
| cancelText | 取消按钮文字 | String | `取消` | - |
| confirmText | 确定按钮文字 | String | `确定` | - |
| cancelTextSize | 取消按钮文字大小 | String \| Number | `$14` | - |
| confirmTextSize | 确定按钮文字大小 | String \| Number | `$14` | - |
| showCancel | 是否显示取消按钮 | Boolean | `true` | `true \| false` |
| showConfirm | 是否显示确定按钮 | Boolean | `true` | `true \| false` |
| showClose | 是否显示右上角关闭按钮 | Boolean | `true` | `true \| false` |
| columnSpacing | 列之间的间距 | String \| Number | `10px` | - |
| actionSpacing | 取消/确定按钮之间的间距 | String \| Number | `10px` | - |
| itemHeight | 选项高度 | String \| Number | `$50` | - |
| itemBorderRadius | 选项圆角大小 | String \| Number | `$8` | - |
| itemTextColor | 选项文字颜色 | String | `$textLight（亮色模式）/ $lineText（暗黑模式）` | - |
| itemTextSize | 选项文字大小 | String \| Number | `$13` | - |
| activeItemTextColor | 激活选项文字颜色 | String | `$text` | - |
| disabledItemTextColor | 禁用选项文字颜色 | String | `$disabledText` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| headerStyle | 自定义标题栏样式 | SnStyleValue | - | - |
| headerClass | 外部样式类 | String | - | - |
| titleStyle | 自定义标题样式 | SnStyleValue | - | - |
| titleClass | 外部样式类 | String | - | - |
| closeButtonStyle | 自定义关闭按钮样式 | SnStyleValue | - | - |
| closeButtonClass | 外部样式类 | String | - | - |
| actionsStyle | 自定义底部按钮栏样式 | SnStyleValue | - | - |
| actionsClass | 外部样式类 | String | - | - |
| cancelButtonStyle | 自定义取消按钮样式 | SnStyleValue | - | - |
| cancelButtonClass | 外部样式类 | String | - | - |
| confirmButtonStyle | 自定义确定按钮样式 | SnStyleValue | - | - |
| confirmButtonClass | 外部样式类 | String | - | - |
| itemStyle | 自定义选项样式 | SnStyleValue | - | - |
| itemClass | 外部样式类 | String | - | - |
| columnStyle | 自定义列样式 | SnStyleValue | - | - |
| columnClass | 外部样式类 | String | - | - |

> 类型字段：SnDatetimePickerValue（见 https://sinleui.pages.dev/api/types/component#sndatetimepickervalue）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: `SnDatetimePickerValue`) => Void | 点击确定后，选中值写入 v-model 时触发 |
| confirm | () => Void | 点击确定按钮时触发（在 change 之前触发） |
| cancel | () => Void | 点击取消按钮时触发 |
| open | () => Void | 选择器打开后触发 |
| close | () => Void | 选择器关闭后触发 |
| clickoverlay | () => Void | 点击蒙层时触发 |
| beforeenter | () => Void | 进入动画开始前触发 |
| enter | () => Void | 进入动画开始时触发 |
| afterenter | () => Void | 进入动画结束后触发 |
| beforeleave | () => Void | 离开动画开始前触发 |
| leave | () => Void | 离开动画开始时触发 |
| afterleave | () => Void | 离开动画结束后触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 打开选择器（打开前会将 v-model 当前值复制为内部临时值，仅确定后才写回） |
| close | - | - | 关闭选择器 |

---

## sn-datetime-picker-view 日期时间选择器容器

`sn-datetime-picker-view` 基于 `sn-picker-view` 封装，是日期时间选择的核心视图，可独立在页面内使用。v-model 与 `change` 事件值均为按 `format` 格式化的日期字符串（滚动时防抖 120ms 后更新）。

```vue
<template>
	<sn-datetime-picker-view v-model="value" mode="年月日"></sn-datetime-picker-view>
</template>
```

### sn-datetime-picker-view 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定的日期值（字符串按 format 解析，数字为毫秒时间戳） | SnDatetimePickerValue | `当前时间` | - |
| mode | 选择器模式（同 sn-datetime-picker） | String \| Number | `7` | - |
| format | 日期格式化字符串 | String | `YYYY-MM-DD HH:mm:ss` | - |
| start | 可选开始日期（无效或未设置时为 10 年前） | SnDatetimePickerValue | - | - |
| end | 可选结束日期（无效或未设置时为 10 年后） | SnDatetimePickerValue | - | - |
| customFilter | 自定义过滤项函数 | Function | `null` | - |
| renderLabel | 自定义列标签函数 | Function | `null` | - |
| showUnit | 是否显示单位 | Boolean | `true` | `true \| false` |
| minHour | 最小/最大小时值 | Number | `0` | `0~23` |
| maxHour | 最小/最大小时值 | Number | `23` | `0~23` |
| minMinute | 最小/最大分钟值 | Number | `0` | `0~59` |
| maxMinute | 最小/最大分钟值 | Number | `59` | `0~59` |
| minSecond | 最小/最大秒数值 | Number | `0` | `0~59` |
| maxSecond | 最小/最大秒数值 | Number | `59` | `0~59` |
| disabled | 是否禁用选择器容器 | Boolean | `false` | `true \| false` |
| height | 选择器容器高度 | String \| Number | `250px` | - |
| itemHeight | 选项高度 | String \| Number | `$50` | - |
| itemBorderRadius | 选项圆角大小 | String \| Number | `$8` | - |
| itemTextColor | 选项文字颜色 | String | `$textLight（亮色模式）/ $lineText（暗黑模式）` | - |
| itemTextSize | 选项文字大小 | String \| Number | `$13` | - |
| activeItemTextColor | 激活选项文字颜色 | String | `$text` | - |
| disabledItemTextColor | 禁用选项文字颜色 | String | `$disabledText` | - |
| columnSpacing | 列间距 | String \| Number | `10px` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| customClass | 自定义根节点外部样式类 | String | - | - |
| itemStyle | 自定义选项样式 | SnStyleValue | - | - |
| itemClass | 外部样式类 | String | - | - |
| columnStyle | 自定义列样式 | SnStyleValue | - | - |
| columnClass | 外部样式类 | String | - | - |

### sn-datetime-picker-view 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: `SnDatetimePickerValue`) => Void | 滚动选择后触发（防抖 120ms），值为按 `format` 格式化的字符串 |

### 类型

**SnDatetimePickerValue**：`String | Number` —— 日期字符串（按 `format` 解析）或毫秒时间戳。

**SnDatetimePickerTimeModeValue**：`'year' | 'month' | 'date' | 'hour' | 'minute' | 'second'` —— 列类型枚举。

<DemoPhone name="sn-datetime-picker" />

# Calendar 日历选择器

## 基础用法

从底部弹出的日历选择器，支持单选、范围与多选三种选择模式。

- 提供「确认事务」草稿模式与即时提交两种提交时机，未确认的选择可整体取消
- 支持双向控制显隐，也可通过组件实例方法打开与关闭
- 支持自定义单日内容与内置文案，头部、底部区域可用插槽替换

::: danger 必须放在 sn-page 下
本组件为弹出层组件，需直接放在 `sn-page` 根节点下使用，否则页面注入的主题颜色变量与动画时长变量无法作用到弹层。
:::

```vue
<template>
	<sn-page>
		<sn-button text="选择日期" type="primary" @click="openCalendar"></sn-button>
		<sn-calendar ref="calendarEle" v-model="date" title="选择日期"></sn-calendar>
	</sn-page>
</template>

<script lang="ts" setup>
	import type { SnCalendarValue } from '@/uni_modules/sinle-ui/index.ts'

	const calendarEle = ref<SnCalendarComponentPublicInstance | null>(null)
	const date = ref<SnCalendarValue>(null)

	function openCalendar(): void {
		calendarEle.value?.$callMethod('open')
	}
</script>
```

**更多演示请下载 demo 查看**

## 进阶用法

### 范围选择（草稿确认）

```vue
<template>
	<sn-calendar v-model:visible="show" v-model="range" type="range" :max-range="7"
		title="选择日期范围" range-prompt="最多选择 7 天"></sn-calendar>
</template>
```

超出 `maxRange` 时会以 toast 提示，且本次点击不会生效。

### 即时提交（多选）

```vue
<template>
	<sn-calendar v-model="dates" type="multiple" :show-confirm="false" allow-cancel title="多选日期"></sn-calendar>
</template>
```

`allow-cancel` 开启后，再次点击已选日期可取消选择。

### 自定义单日内容

```vue
<template>
	<sn-calendar v-model="date" :format="formatDay" title="排班日历"></sn-calendar>
</template>

<script lang="ts" setup>
	import { createCalendarDayContent } from '@/uni_modules/sinle-ui/index.ts'
	import type { SnCalendarDay, SnCalendarDayFormatter, SnCalendarValue } from '@/uni_modules/sinle-ui/index.ts'

	const date = ref<SnCalendarValue>(null)

	const formatDay: SnCalendarDayFormatter = (day: SnCalendarDay) => {
		if (day.weekday == 0 || day.weekday == 6) {
			return createCalendarDayContent({ suffix: '休', paint: { suffixColor: '$warning' } })
		}
		return null
	}
</script>
```

## 实现原理

本组件是 `sn-calendar-view` 月历视图的弹层形态，内部月历由它承载；每次打开弹层时以 v-model 当前值重建内部草稿。

## 属性

### 选择行为

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值，形态随 `type` 变化（见下方类型说明） | `SnCalendarValue` | `null` | - |
| v-model:visible | 弹层显示状态（双向绑定） | Boolean | `false` | `true` \| `false` |
| type | 选择模式 | String | `single` | `single` \| `range` \| `multiple` |
| minDate | 最小可选日期（毫秒时间戳），默认当天 | Number | - | - |
| maxDate | 最大可选日期（毫秒时间戳），默认当天起 6 个月 | Number | - | - |
| maxRange | 限制范围选择的天数（含首尾）或多选的个数，0 表示不限制 | Number | `0` | - |
| rangePrompt | 超出 `maxRange` 时的提示文字，`{maxRange}` 会被替换为实际值，取 `localeText.rangePrompt` | String | - | - |
| firstDayOfWeek | 每周第一天（0 为周日） | Number | `0` | `0~6` |
| switchMode | 面板标题显示模式：`month` 显示「N月」，`year-month` 按 `yearMonthFormat` 显示年月 | String | `year-month` | `month` \| `year-month` |
| format | 单日内容格式化函数，可自定义文字与绘制样式，返回 `null` 保持默认 | `SnCalendarDayFormatter` | `null` | - |
| localeText | 内置文案配置（标题、按钮文字、星期标题、年月格式等） | `SnCalendarLocaleText` | `中文默认文案` | 见下方类型 |
| readonly | 是否只读（禁用面板切换与选择） | Boolean | `false` | `true` \| `false` |
| allowCancel | 再次点击已选日期是否取消选择 | Boolean | `false` | `true` \| `false` |
| fullFillDates | 是否绘制前后月份的补位日期 | Boolean | `false` | `true` \| `false` |

> 类型字段：SnCalendarValue（见 https://sinleui.pages.dev/api/types/component#sncalendarvalue）

> 类型字段：SnCalendarDayFormatter（见 https://sinleui.pages.dev/api/types/component#sncalendardayformatter）

> 类型字段：SnCalendarLocaleText（见 https://sinleui.pages.dev/api/types/component#sncalendarlocaletext）


### 标题与按钮

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| title | 弹层标题，取 `localeText.title` | String | - | - |
| showClose | 是否显示右上角关闭按钮 | Boolean | `true` | `true` \| `false` |
| showConfirm | 是否显示底部「取消 / 确定」按钮；为 `false` 时选择结果即时写入 v-model | Boolean | `true` | `true` \| `false` |
| confirmText | 确定按钮文字，取 `localeText.confirmText` | String | - | - |
| confirmDisabledText | 预留属性：确定按钮禁用态文字（当前版本未在界面使用） | String | `''` | - |
| forceEnableConfirm | 值未完成选择（`single` 未选 / `multiple` 为空 / `range` 不足两点）时是否仍允许点击确定 | Boolean | `false` | `true` \| `false` |

### 弹层

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| height | 弹层高度；为默认 `560px` 时按标题栏、月历视图与按钮区高度自动计算，传入其他值则固定使用 | String \| Number | `560px` | - |
| maskClose | 点击遮罩是否关闭（关闭时会丢弃草稿并触发 `cancel`） | Boolean | `true` | `true` \| `false` |
| maskOpacity | 遮罩透明度 | Number | `0.4` | `0~1` |
| preventBack | 显示时是否阻止页面返回 | Boolean | `false` | `true` \| `false` |
| aniTime | 显隐动画时长（ms），支持 `$` 简写 | String \| Number | `$long` | - |
| zIndex | 弹出层层级 | Number | `999` | - |

### 月历视图

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| rowHeight | 单行日期高度 | String \| Number | `$48` | - |
| showMark | 预留属性（当前版本绘制中无可见效果） | Boolean | `true` | `true` \| `false` |
| showWatermark | 是否显示月份水印数字 | Boolean | `true` | `true` \| `false` |
| watermarkColor | 水印颜色，支持 `$` 简写 | String | `$lineText` | - |
| watermarkFontSize | 水印字号 | String \| Number | `$96` | - |
| titlePicker | 点击标题是否展开年月选择面板 | Boolean | `false` | `true` \| `false` |
| switchLongpress | 长按左右切换按钮是否连续切换（年月面板中的年步进器长按同样生效） | Boolean | `true` | `true` \| `false` |

### 日期颜色与尺寸

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| dayTextColor | 日期文字颜色 | String | `$text` | - |
| adjacentDayTextColor | 非当前月日期文字颜色 | String | `$lineText` | - |
| disabledDayTextColor | 禁用日期文字颜色 | String | `$disabledText` | - |
| selectedDayTextColor | 选中日期文字颜色 | String | `$primaryText` | - |
| selectedDayBgColor | 选中日期背景色 | String | `$primary` | - |
| rangeDayTextColor | 范围中间日期文字颜色 | String | `$primaryLightText` | - |
| rangeDayBgColor | 范围中间日期背景色 | String | `$primaryLight` | - |
| prefixTextColor | 日期上标文字颜色，随日期文字颜色 | String | - | - |
| suffixTextColor | 日期下标文字颜色，随日期文字颜色 | String | - | - |
| todayBorderColor | 今天日期描边颜色 | String | `$primary` | - |
| dayFontSize | 日期字号 | String \| Number | `$14` | - |
| prefixFontSize | 上标字号 | String \| Number | `$8` | - |
| suffixFontSize | 下标字号 | String \| Number | `$8` | - |
| dayRadius | 日期气泡圆角 | String \| Number | `$6` | - |
| dayGap | 日期气泡与单元格边缘的间距 | String \| Number | `$2` | - |

### 样式扩展

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 外部样式类 | String | `''` | - |
| headerStyle | 自定义头部区域样式 | SnStyleValue | `''` | - |
| headerClass | 外部样式类 | String | `''` | - |
| titleStyle | 自定义标题文字样式 | SnStyleValue | `''` | - |
| titleClass | 外部样式类 | String | `''` | - |
| closeStyle | 自定义关闭按钮样式 | SnStyleValue | `''` | - |
| closeClass | 外部样式类 | String | `''` | - |
| actionsStyle | 自定义底部按钮区样式 | SnStyleValue | `''` | - |
| actionsClass | 外部样式类 | String | `''` | - |
| confirmButtonStyle | 自定义确定按钮样式 | SnStyleValue | `''` | - |
| confirmButtonClass | 外部样式类 | String | `''` | - |
| viewStyle | 自定义内部月历视图根节点样式 | SnStyleValue | `''` | - |
| viewClass | 外部样式类 | String | `''` | - |
| viewHeaderStyle | 自定义月历视图头部样式 | SnStyleValue | `''` | - |
| viewHeaderClass | 外部样式类 | String | `''` | - |
| switchStyle | 自定义月份切换按钮样式 | SnStyleValue | `''` | - |
| switchClass | 外部样式类 | String | `''` | - |
| weekdaysStyle | 自定义星期标题行样式 | SnStyleValue | `''` | - |
| weekdaysClass | 外部样式类 | String | `''` | - |
| weekdayStyle | 自定义单个星期标题样式 | SnStyleValue | `''` | - |
| weekdayClass | 外部样式类 | String | `''` | - |
| monthsStyle | 自定义月份滑动区样式 | SnStyleValue | `''` | - |
| monthsClass | 外部样式类 | String | `''` | - |
| monthStyle | 自定义单月容器样式 | SnStyleValue | `''` | - |
| monthClass | 外部样式类 | String | `''` | - |
| monthTitleStyle | 自定义月份标题文字样式 | SnStyleValue | `''` | - |
| monthTitleClass | 外部样式类 | String | `''` | - |
| watermarkStyle | 自定义月份水印样式 | SnStyleValue | `''` | - |
| watermarkClass | 外部样式类 | String | `''` | - |

### 年月选择面板

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| pickerLayerStyle | 自定义面板遮罩层样式 | SnStyleValue | `''` | - |
| pickerLayerClass | 外部样式类 | String | `''` | - |
| pickerPanelStyle | 自定义面板容器样式 | SnStyleValue | `''` | - |
| pickerPanelClass | 外部样式类 | String | `''` | - |
| pickerHeaderStyle | 自定义面板头部样式 | SnStyleValue | `''` | - |
| pickerHeaderClass | 外部样式类 | String | `''` | - |
| pickerYearStepperWrapStyle | 自定义年步进器容器样式 / 外部样式类，取 pickerTitleStyle / pickerTitleClass | SnStyleValue | - | - |
| pickerYearStepperWrapClass | 自定义年步进器容器样式 / 外部样式类，取 pickerTitleStyle / pickerTitleClass | String | - | - |
| pickerYearStepperStyle | 自定义年步进器样式 | SnStyleValue | `''` | - |
| pickerYearStepperSize | 年步进器尺寸 | String \| Number | `$32` | - |
| pickerYearStepperSpacing | 年步进器内间距 | String \| Number | `$8` | - |
| pickerYearStepperInputWidth | 年份输入框宽度 | String \| Number | `$92` | - |
| pickerYearStepperTextSize | 年步进器文字字号 | String \| Number | `$16` | - |
| pickerYearStepperTextColor | 年步进器文字颜色，支持 $ 简写 | String | `$text` | - |
| pickerYearStepperInputTextColor | 年份输入框文字颜色，支持 $ 简写 | String | `$text` | - |
| pickerYearStepperDisabledTextColor | 禁用态文字颜色，支持 $ 简写 | String | `$disabledText` | - |
| pickerYearStepperInputBgColor | 年份输入框背景色，支持 $ 简写 | String | `$page` | - |
| pickerYearStepperInputActiveBgColor | 年份输入框激活背景色，支持 $ 简写 | String | `$page` | - |
| pickerYearStepperDisabledBgColor | 禁用态背景色，支持 $ 简写 | String | `''` | - |
| pickerYearStepperButtonBgColor | 步进按钮背景色，支持 $ 简写 | String | `$page` | - |
| pickerYearStepperBorderRadius | 年步进器圆角 | String \| Number | `$8` | - |
| pickerYearStepperShowBorder | 年步进器是否显示边框 | Boolean | `false` | `true \| false` |
| pickerYearStepperBorderColor | 边框颜色，支持 $ 简写 | String | `''` | - |
| pickerYearStepperActiveBorderColor | 激活态边框颜色，支持 $ 简写 | String | `''` | - |
| pickerYearStepperBorderWidth | 边框宽度 | String \| Number | `2` | - |
| pickerYearStepperTextFont | 年步进器文字字体 | String | `''` | - |
| pickerYearStepperCursorColor | 输入光标颜色，支持 $ 简写 | String | `''` | - |
| pickerMonthsStyle | 自定义月份宫格容器样式 / 外部样式类，取 pickerBodyStyle / pickerBodyClass | SnStyleValue | - | - |
| pickerMonthsClass | 自定义月份宫格容器样式 / 外部样式类，取 pickerBodyStyle / pickerBodyClass | String | - | - |
| pickerMonthStyle | 自定义单个月份项样式 / 外部样式类，取 pickerRowStyle / pickerRowClass | SnStyleValue | - | - |
| pickerMonthClass | 自定义单个月份项样式 / 外部样式类，取 pickerRowStyle / pickerRowClass | String | - | - |
| pickerMonthTextStyle | 自定义月份文字样式 / 外部样式类，取 pickerLabelStyle / pickerLabelClass | SnStyleValue | - | - |
| pickerMonthTextClass | 自定义月份文字样式 / 外部样式类，取 pickerLabelStyle / pickerLabelClass | String | - | - |
| pickerTitleStyle | 年步进器容器兜底样式 / 外部样式类（pickerYearStepperWrapStyle / Class 为空时生效） | SnStyleValue | `''` | - |
| pickerTitleClass | 年步进器容器兜底样式 / 外部样式类（pickerYearStepperWrapStyle / Class 为空时生效） | String | `''` | - |
| pickerBodyStyle | 月份宫格兜底样式 / 外部样式类（pickerMonthsStyle / Class 为空时生效） | SnStyleValue | `''` | - |
| pickerBodyClass | 月份宫格兜底样式 / 外部样式类（pickerMonthsStyle / Class 为空时生效） | String | `''` | - |
| pickerRowStyle | 月份项兜底样式 / 外部样式类（pickerMonthStyle / Class 为空时生效） | SnStyleValue | `''` | - |
| pickerRowClass | 月份项兜底样式 / 外部样式类（pickerMonthStyle / Class 为空时生效） | String | `''` | - |
| pickerLabelStyle | 月份文字兜底样式 / 外部样式类（pickerMonthTextStyle / Class 为空时生效） | SnStyleValue | `''` | - |
| pickerLabelClass | 月份文字兜底样式 / 外部样式类（pickerMonthTextStyle / Class 为空时生效） | String | `''` | - |
| promptStyle | 自定义超限提示文字样式 | SnStyleValue | `''` | - |
| promptClass | 外部样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| select | (value: `SnCalendarValue`) => Void | 选择日期时触发（`showConfirm` 为 `true` 时基于内部草稿值） |
| change | (value: `SnCalendarValue`) => Void | 绑定值变化时触发：`showConfirm` 为 `true` 时点击确定后触发，为 `false` 时每次选择即时触发 |
| confirm | (value: `SnCalendarValue`) => Void | 点击确定按钮后触发，草稿此时写入 v-model |
| cancel | () => Void | 点击取消按钮、关闭按钮或（`maskClose` 开启时的）遮罩后触发，草稿被丢弃 |
| panel-change | (detail: `SnCalendarPanelChangeDetail`) => Void | 面板所在月份变化时触发 |
| open | () => Void | 弹层完全打开（入场动画结束）后触发 |
| close | () => Void | 弹层完全关闭（离场动画结束）后触发 |
| clickoverlay | () => Void | 点击遮罩时触发 |
| beforeenter | () => Void | 入场动画开始前触发 |
| enter | () => Void | 入场动画开始时触发 |
| afterenter | () => Void | 入场动画结束后触发 |
| beforeleave | () => Void | 离场动画开始前触发 |
| leave | () => Void | 离场动画开始时触发 |
| afterleave | () => Void | 离场动画结束后触发 |

> 类型字段：SnCalendarPanelChangeDetail（见 https://sinleui.pages.dev/api/types/component#sncalendarpanelchangedetail）


## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 打开日历弹层 |
| close | - | - | 关闭日历弹层，丢弃未确认的草稿 |
| confirm | - | - | 确认当前草稿（等效点击确定按钮），写入 v-model 并关闭弹层 |
| scrollToDate | (value: Number) | - | 选中指定日期（毫秒时间戳）并跳转到其所在月份；弹层未打开或尚未渲染时会缓存该操作，打开后自动定位并选中（不会被「打开时重置草稿」清掉） |

## 插槽

| 名称 | 说明 |
| --- | --- |
| header | 自定义整个头部区域（标题 + 关闭按钮） |
| title | 自定义标题文字区域 |
| footer | 自定义底部区域（取消 / 确定按钮组） |

## 类型

### SnCalendarValue

`Number | null | Number[]`：按 `type` 约定——`single` 为当天零点时间戳或 `null`；`range` 为 `[]` 或 `[开始, 结束]`（只选一天时两端相同）；`multiple` 为时间戳数组。赋入超出 `minDate` / `maxDate` 范围的值会被自动规范化（裁剪到范围内）。
`format` 相关的 `SnCalendarDay` / `SnCalendarDayContent` / `SnCalendarDayPaint` 等类型见 `sn-calendar-view` 文档的「类型」一节。

<DemoPhone name="sn-calendar" />

# CalendarView 月历视图

## 基础用法

内联在页面中的可滑动月历视图（无弹层），支持单选、范围与多选三种模式；`sn-calendar`（弹层日历）与 `sn-calendar-punch`（签到日历）均基于它封装，也可单独使用。

- 支持箭头点击、横向滑动与长按连续切换月份，并提供年月选择面板快速跳转
- 日期格内容与绘制样式可自定义，支持前后月补位日期与月份数字水印

::: info 平台差异
Web 端额外支持鼠标点击与拖动选择。
:::

```vue
<template>
	<sn-calendar-view v-model="date" type="single" height="420px"></sn-calendar-view>
</template>

<script lang="ts" setup>
	import type { SnCalendarValue } from '@/uni_modules/sinle-ui/index.ts'

	const date = ref<SnCalendarValue>(null)
</script>
```

**更多演示请下载 demo 查看**

## 进阶用法

### 范围选择与跳转日期

```vue
<template>
	<sn-calendar-view ref="viewEle" v-model="range" type="range" :max-range="7"
		height="420px" title-picker></sn-calendar-view>
</template>

<script lang="ts" setup>
	import { dayuts } from '@/uni_modules/sinle-ui/index.ts'
	import type { SnCalendarValue } from '@/uni_modules/sinle-ui/index.ts'

	const viewEle = ref<SnCalendarViewComponentPublicInstance | null>(null)
	const range = ref<SnCalendarValue>([])

	function jump(): void {
		viewEle.value?.$callMethod('scrollToDate', dayuts('2032-06-15').startOf('day').valueOf())
	}
</script>
```

`scrollToDate` 会选中目标日期并跳转到其所在月份；`title-picker` 开启后也可点击标题展开年月面板跳转，面板由年步进器与 12 个月份宫格组成。超出 `maxRange` 时会以 toast 提示，且本次选择不生效。

### 自定义单日内容与圆点

```vue
<template>
	<sn-calendar-view v-model="date" :format="formatDay" full-fill-dates></sn-calendar-view>
</template>

<script lang="ts" setup>
	import { createCalendarDayContent } from '@/uni_modules/sinle-ui/index.ts'
	import type { SnCalendarDay, SnCalendarDayFormatter, SnCalendarValue } from '@/uni_modules/sinle-ui/index.ts'

	const date = ref<SnCalendarValue>(null)

	const formatDay: SnCalendarDayFormatter = (day: SnCalendarDay) => {
		if (day.date % 5 == 0) {
			return createCalendarDayContent({ showDot: true, dotColor: '$success', dotPosition: 'bottom' })
		}
		return null
	}
</script>
```

`full-fill-dates` 开启后绘制前后月份的补位日期。

## 实现原理

日期格基于 Canvas 绘制，当前月中央叠加月份数字水印；主题（颜色）变化时自动重绘。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值，形态随 type 变化（见下方类型说明） | SnCalendarValue | `null` | - |
| type | 选择模式 | String | `single` | `single \| range \| multiple` |
| minDate | 最小可选日期（毫秒时间戳），默认当天 | Number | - | - |
| maxDate | 最大可选日期（毫秒时间戳），默认当天起 6 个月 | Number | - | - |
| maxRange | 限制范围选择的天数（含首尾）或多选的个数，0 表示不限制 | Number | `0` | - |
| rangePrompt | 超出 maxRange 时的提示文字，{maxRange} 会被替换为实际值，取 localeText.rangePrompt | String | - | - |
| firstDayOfWeek | 每周第一天（0 为周日） | Number | `0` | `0~6` |
| switchMode | 面板标题显示模式：month 显示「N月」，year-month 按 yearMonthFormat 显示年月 | String | `year-month` | `month \| year-month` |
| format | 单日内容格式化函数，可自定义文字与绘制样式，返回 null 保持默认 | SnCalendarDayFormatter | `null` | - |
| localeText | 内置文案配置（星期标题、年月格式、超限提示等） | SnCalendarLocaleText | `中文默认文案` | 见下方类型 |
| rowHeight | 单行日期高度 | String \| Number | `$48` | - |
| height | 视图整体高度 | String \| Number | `$420` | - |
| showMark | 预留属性（当前版本绘制中无可见效果） | Boolean | `true` | `true \| false` |
| showWatermark | 是否显示月份水印数字 | Boolean | `true` | `true \| false` |
| watermarkColor | 水印颜色，支持 $ 简写 | String | `$lineText` | - |
| watermarkFontSize | 水印字号 | String \| Number | `$96` | - |
| titlePicker | 点击标题是否展开年月选择面板 | Boolean | `false` | `true \| false` |
| switchLongpress | 长按左右切换按钮是否连续切换（年月面板中的年步进器长按同样生效） | Boolean | `true` | `true \| false` |
| readonly | 是否只读（禁用面板切换与选择） | Boolean | `false` | `true \| false` |
| fullFillDates | 是否绘制前后月份的补位日期 | Boolean | `false` | `true \| false` |
| allowCancel | 再次点击已选日期是否取消选择 | Boolean | `false` | `true \| false` |
| dayTextColor | 日期文字颜色 | String | `$text` | - |
| adjacentDayTextColor | 非当前月日期文字颜色 | String | `$lineText` | - |
| disabledDayTextColor | 禁用日期文字颜色 | String | `$disabledText` | - |
| selectedDayTextColor | 选中日期文字颜色 | String | `$primaryText` | - |
| selectedDayBgColor | 选中日期背景色 | String | `$primary` | - |
| rangeDayTextColor | 范围中间日期文字颜色 | String | `$primaryLightText` | - |
| rangeDayBgColor | 范围中间日期背景色 | String | `$primaryLight` | - |
| prefixTextColor | 日期上标文字颜色，随日期文字颜色 | String | - | - |
| suffixTextColor | 日期下标文字颜色，随日期文字颜色 | String | - | - |
| todayBorderColor | 今天日期描边颜色 | String | `$primary` | - |
| dayFontSize | 日期字号 | String \| Number | `$14` | - |
| prefixFontSize | 上标字号 | String \| Number | `$8` | - |
| suffixFontSize | 下标字号 | String \| Number | `$8` | - |
| dayRadius | 日期气泡圆角 | String \| Number | `$6` | - |
| dayGap | 日期气泡与单元格边缘的间距 | String \| Number | `$2` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 外部样式类 | String | `''` | - |
| headerStyle | 自定义头部样式 | SnStyleValue | `''` | - |
| headerClass | 外部样式类 | String | `''` | - |
| switchStyle | 自定义月份切换按钮样式 | SnStyleValue | `''` | - |
| switchClass | 外部样式类 | String | `''` | - |
| weekdaysStyle | 自定义星期标题行样式 | SnStyleValue | `''` | - |
| weekdaysClass | 外部样式类 | String | `''` | - |
| weekdayStyle | 自定义单个星期标题样式 | SnStyleValue | `''` | - |
| weekdayClass | 外部样式类 | String | `''` | - |
| monthsStyle | 自定义月份滑动区样式 | SnStyleValue | `''` | - |
| monthsClass | 外部样式类 | String | `''` | - |
| monthStyle | 自定义单月容器样式 | SnStyleValue | `''` | - |
| monthClass | 外部样式类 | String | `''` | - |
| monthTitleStyle | 自定义月份标题文字样式 | SnStyleValue | `''` | - |
| monthTitleClass | 外部样式类 | String | `''` | - |
| watermarkStyle | 自定义月份水印样式 | SnStyleValue | `''` | - |
| watermarkClass | 外部样式类 | String | `''` | - |
| pickerLayerStyle | 自定义年月面板遮罩层样式 | SnStyleValue | `''` | - |
| pickerLayerClass | 外部样式类 | String | `''` | - |
| pickerPanelStyle | 自定义年月面板容器样式 | SnStyleValue | `''` | - |
| pickerPanelClass | 外部样式类 | String | `''` | - |
| pickerHeaderStyle | 自定义年月面板头部样式 | SnStyleValue | `''` | - |
| pickerHeaderClass | 外部样式类 | String | `''` | - |
| pickerYearStepperWrapStyle | 自定义年步进器容器样式 | SnStyleValue | `''` | - |
| pickerYearStepperWrapClass | 外部样式类 | String | `''` | - |
| pickerYearStepperStyle | 自定义年步进器样式 | SnStyleValue | `''` | - |
| pickerYearStepperSize | 年步进器尺寸 | String \| Number | `$32` | - |
| pickerYearStepperSpacing | 年步进器内间距 | String \| Number | `$8` | - |
| pickerYearStepperInputWidth | 年份输入框宽度 | String \| Number | `$92` | - |
| pickerYearStepperTextSize | 年步进器文字字号 | String \| Number | `$16` | - |
| pickerYearStepperTextColor | 年步进器文字颜色，支持 $ 简写 | String | `$text` | - |
| pickerYearStepperInputTextColor | 年份输入框文字颜色，支持 $ 简写 | String | `$text` | - |
| pickerYearStepperDisabledTextColor | 禁用态文字颜色，支持 $ 简写 | String | `$disabledText` | - |
| pickerYearStepperInputBgColor | 年份输入框背景色，支持 $ 简写 | String | `$page` | - |
| pickerYearStepperInputActiveBgColor | 年份输入框激活背景色，支持 $ 简写 | String | `$page` | - |
| pickerYearStepperDisabledBgColor | 禁用态背景色，支持 $ 简写 | String | `''` | - |
| pickerYearStepperButtonBgColor | 步进按钮背景色，支持 $ 简写 | String | `$page` | - |
| pickerYearStepperBorderRadius | 年步进器圆角 | String \| Number | `$8` | - |
| pickerYearStepperShowBorder | 年步进器是否显示边框 | Boolean | `false` | `true \| false` |
| pickerYearStepperBorderColor | 边框颜色，支持 $ 简写 | String | `''` | - |
| pickerYearStepperActiveBorderColor | 激活态边框颜色，支持 $ 简写 | String | `''` | - |
| pickerYearStepperBorderWidth | 边框宽度 | String \| Number | `2` | - |
| pickerYearStepperTextFont | 年步进器文字字体 | String | `''` | - |
| pickerYearStepperCursorColor | 输入光标颜色，支持 $ 简写 | String | `''` | - |
| pickerMonthsStyle | 自定义月份宫格容器样式 | SnStyleValue | `''` | - |
| pickerMonthsClass | 外部样式类 | String | `''` | - |
| pickerMonthStyle | 自定义单个月份项样式 | SnStyleValue | `''` | - |
| pickerMonthClass | 外部样式类 | String | `''` | - |
| pickerMonthTextStyle | 自定义月份文字样式 | SnStyleValue | `''` | - |
| pickerMonthTextClass | 外部样式类 | String | `''` | - |
| promptStyle | 自定义超限提示文字样式 | SnStyleValue | `''` | - |
| promptClass | 外部样式类 | String | `''` | - |

> 类型字段：SnCalendarValue（见 https://sinleui.pages.dev/api/types/component#sncalendarvalue）

> 类型字段：SnCalendarDayFormatter（见 https://sinleui.pages.dev/api/types/component#sncalendardayformatter）

> 类型字段：SnCalendarLocaleText（见 https://sinleui.pages.dev/api/types/component#sncalendarlocaletext）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| select | (value: `SnCalendarValue`) => Void | 选择日期时触发 |
| change | (value: `SnCalendarValue`) => Void | 绑定值变化时触发（与 `select` 同时触发） |
| panel-change | (detail: `SnCalendarPanelChangeDetail`) => Void | 面板所在月份变化时触发（箭头切换、滑动、年月面板跳转均会触发） |

> 类型字段：SnCalendarPanelChangeDetail（见 https://sinleui.pages.dev/api/types/component#sncalendarpanelchangedetail）


## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| scrollToDate | (value: Number) | - | 选中指定日期（毫秒时间戳，自动裁剪到范围内）并跳转到其所在月份 |

## 类型

### SnCalendarType

选择模式：`'single'`（单选）| `'multiple'`（多选）| `'range'`（范围）。

### SnCalendarValue

`Number | null | Number[]`：按 `type` 约定——`single` 为当天零点时间戳或 `null`；`range` 为 `[]` 或 `[开始, 结束]`（只选一天时两端相同）；`multiple` 为时间戳数组。赋入超出 `minDate` / `maxDate` 范围的值会被自动裁剪到范围内。

### SnCalendarSwitchMode

面板标题显示模式：`'month'`（按月显示）| `'year-month'`（按年月显示）。

> 类型字段：SnCalendarDay（见 https://sinleui.pages.dev/api/types/component#sncalendarday）

> 类型字段：SnCalendarDayState（见 https://sinleui.pages.dev/api/types/component#sncalendardaystate）

> 类型字段：SnCalendarDayPaint（见 https://sinleui.pages.dev/api/types/component#sncalendardaypaint）


:::

### SnCalendarDayFormatter

`(day: SnCalendarDay) => SnCalendarDayContent | null`：单日内容格式化函数。返回 `null` 保持默认渲染；返回的 `prefix` / `text` / `suffix` / `paint` 仅覆盖对应字段。推荐使用工厂函数 `createCalendarDayContent` / `createCalendarDayPaint` 构造返回值（均已从插件出口 `@/uni_modules/sinle-ui/index.ts` 导出）。

> 类型字段：SnCalendarDayContent（见 https://sinleui.pages.dev/api/types/component#sncalendardaycontent）

> 类型字段：SnCalendarDayDotPosition（见 https://sinleui.pages.dev/api/types/component#sncalendardaydotposition）


<DemoPhone name="sn-calendar-view" />

# CalendarWeek 周日历

## 基础用法

一次只显示一周的周日历，可左右滑动切换。

- 选中日期以高亮底色显示，点击日期即可选中
- 切换按钮按天移动选中日期，横向滑动按周切换
- 支持可选范围与禁用日期，周起始日、七天标题与事件圆点均可自定义

```vue
<template>
	<sn-calendar-week v-model="date" @week-change="onWeekChange"></sn-calendar-week>
</template>

<script lang="ts" setup>
	import { dayuts } from '@/uni_modules/sinle-ui/index.ts'
	import type { SnCalendarValue, SnCalendarWeekChangeDetail } from '@/uni_modules/sinle-ui/index.ts'

	const date = ref<SnCalendarValue>(dayuts().startOf('day').valueOf())

	function onWeekChange(detail: SnCalendarWeekChangeDetail): void {
		console.log(detail.year, detail.month)
	}
</script>
```

**更多演示请下载 demo 查看**

## 进阶用法

### 范围、禁用日期与圆点

```vue
<template>
	<sn-calendar-week v-model="date" :min-date="minDate" :max-date="maxDate"
		:disabled-dates="disabledDates" :format="markFormatter" week-start="monday"></sn-calendar-week>
</template>

<script lang="ts" setup>
	import { dayuts, createCalendarDayContent } from '@/uni_modules/sinle-ui/index.ts'
	import type { SnCalendarDay, SnCalendarDayFormatter, SnCalendarValue } from '@/uni_modules/sinle-ui/index.ts'

	const date = ref<SnCalendarValue>(dayuts().startOf('day').valueOf())
	const minDate = ref<number>(dayuts().subtract(1, 'month').startOf('day').valueOf())
	const maxDate = ref<number>(dayuts().add(1, 'month').startOf('day').valueOf())
	const disabledDates = ref<number[]>([dayuts().add(1, 'day').startOf('day').valueOf()])

	const markFormatter: SnCalendarDayFormatter = (day: SnCalendarDay) => {
		if (day.date % 5 == 0) return createCalendarDayContent({ showDot: true, dotColor: '$success' })
		return null
	}
</script>
```

## 注意事项

左右切换按钮按「日」为粒度移动选中日期（上一天 / 下一天），横向滑动按「周」切换；视图绘制到可选范围所在的周，可选范围均未设置时从当前周开始。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 选中的日期（当天零点毫秒时间戳） | Number \| null | `null` | - |
| minDate | 最小可选日期（毫秒时间戳），null 不限制 | Number | `null` | - |
| maxDate | 最大可选日期（毫秒时间戳），null 不限制 | Number | `null` | - |
| disabledDates | 禁用日期列表（毫秒时间戳数组，无效值自动忽略） | Number[] \| null | `null` | - |
| weekStart | 每周起始日 | String | `sunday` | `sunday \| monday \| tuesday \| wednesday \| thursday \| friday \| saturday` |
| weekTitles | 七天标题（从周日开始排列，随 weekStart 轮转显示） | String[] | `['日', '一', '二', '三', '四', '五', '六']` | - |
| showSwitch | 是否显示左右切换按钮 | Boolean | `true` | `true \| false` |
| switchIconSize | 切换按钮图标大小 | String \| Number | `$18` | - |
| switchIconColor | 切换按钮图标颜色，支持 $ 简写 | String | `$textLight` | - |
| selectedBgColor | 选中日期背景色，支持 $ 简写 | String | `$primary` | - |
| selectedTextColor | 选中日期文字颜色，支持 $ 简写 | String | `$primaryText` | - |
| format | 单日格式化函数，返回 showDot / dotColor 时绘制圆点，返回 text 覆盖日期文字 | SnCalendarDayFormatter | `null` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 外部样式类 | String | `''` | - |
| switchStyle | 自定义切换按钮样式 | SnStyleValue | `''` | - |
| switchClass | 外部样式类 | String | `''` | - |
| weeksStyle | 自定义周滑动区样式 | SnStyleValue | `''` | - |
| weeksClass | 外部样式类 | String | `''` | - |
| weekStyle | 自定义单周容器样式 | SnStyleValue | `''` | - |
| weekClass | 外部样式类 | String | `''` | - |
| dayStyle | 自定义日期格样式 | SnStyleValue | `''` | - |
| dayClass | 外部样式类 | String | `''` | - |
| dayTitleStyle | 自定义周标题文字样式 | SnStyleValue | `''` | - |
| dayTitleClass | 外部样式类 | String | `''` | - |
| dayTextStyle | 自定义日期文字样式 | SnStyleValue | `''` | - |
| dayTextClass | 外部样式类 | String | `''` | - |

> 类型字段：SnCalendarDayFormatter（见 https://sinleui.pages.dev/api/types/component#sncalendardayformatter）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| select | (value: Number) => Void | 点击选中日期时触发 |
| change | (value: Number) => Void | 选中值变化时触发 |
| week-change | (detail: `SnCalendarWeekChangeDetail`) => Void | 当前周切换时触发（滑动、方法跳转均会触发） |

> 类型字段：SnCalendarWeekChangeDetail（见 https://sinleui.pages.dev/api/types/component#sncalendarweekchangedetail）


## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| scrollToDate | (value: Number) | - | 选中指定日期（毫秒时间戳，自动裁剪到范围内）并跳转到其所在周 |

## 类型

### SnCalendarWeekStartDay

每周起始日：`'sunday'` | `'monday'` | `'tuesday'` | `'wednesday'` | `'thursday'` | `'friday'` | `'saturday'`。

> 类型字段：SnCalendarWeekDay（见 https://sinleui.pages.dev/api/types/component#sncalendarweekday）


`format` 相关的 `SnCalendarDay` / `SnCalendarDayContent` / `SnCalendarDayPaint` 等类型见 `sn-calendar-view` 文档的「类型」一节。

<DemoPhone name="sn-calendar-week" />

# RegionPicker 地区选择器

## 基础用法

从底部弹出的省/市/县三级行政区划滚动选择器，内置中国省市区数据，无需业务传入数据源。

- 支持汉字或位掩码组合省、市、县（区）列，详见「模式组合」
- 省列变化时市 / 县列自动级联重置为该级首项，绑定值为空时自动填充各级首项

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下（页面根节点或 `sn-page` 的直接子节点），否则页面的 `--sn-*`、`--ani-time-*` 变量不生效，颜色与动画异常。
:::

::: info 仅确定后写入
滚动选择期间不会改动 `v-model`；点击「取消」、遮罩或关闭按钮均放弃本次选择。
:::

```vue
<template>
	<sn-region-picker ref="pickerEle" v-model="value" title="请选择地区" @change="onChange"></sn-region-picker>
</template>
```

**更多演示请下载 demo 查看**

## 实现原理

组件基于 `sn-drawer` + `sn-region-picker-view` 封装；选择视图在首次打开后才渲染（懒渲染），首开性能更佳。

## 模式组合

`mode` 属性控制显示省、市、县（区）列的组合，支持传入汉字或位掩码数字：

- **汉字组合**：支持 `省`、`市`、`县`、`区`（`县`/`区` 等价），如 `省市`、`省县`。
- **位掩码**：`1` 省、`2` 市、`4` 县（区），可传按位或运算表达式的结果（如 `7` 即省市县），也支持英文 `province` / `city` / `county` 混合写法。

```vue
<template>
	<sn-region-picker v-model="value1" mode="省市"></sn-region-picker>
	<sn-region-picker v-model="value2" :mode="1"></sn-region-picker>
	<sn-region-picker v-model="value3" :mode="7"></sn-region-picker>
</template>
```

默认 `mode` 为 `7`（省市县）。

列始终以省开头，`mode` 未含省时会自动补充省列；直辖市在市列显示自身，区县列为其下辖区县。

## 过滤项

传入 `customFilter` 函数可对各列选项数组进行过滤（如剔除特定省份）。此函数在每一列均会执行一次，请做好条件判断。

函数类型：`(type: SnRegionLevel, columns: SnDataItem[]) => SnDataItem[]`

- type：当前列类型，为 `province` / `city` / `county` 枚举值。
- columns：当前列的子项列表（`SnDataItem[]`，`id` 为区划代码、`text` 为区划名称）。

```vue
<template>
	<sn-region-picker v-model="value" :custom-filter="filter"></sn-region-picker>
</template>
<script lang="ts" setup>
	const filter = (type: SnRegionLevel, columns: SnDataItem[]): SnDataItem[] => {
		if (type == 'province') {
			return columns.filter((item: SnDataItem): boolean => item.id != '110000')
		}
		return columns
	}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 选中地区的区划代码数组（按省、市、县列顺序） | SnRegionValue | `[]` | - |
| mode | 选择器模式（详见模式组合） | String \| Number | `7` | - |
| customFilter | 自定义过滤项函数（详见过滤项） | Function | `null` | - |
| disabled | 是否禁用选择器（选项不可滚动、按钮不可点击） | Boolean | `false` | `true \| false` |
| maskClose | 是否可以通过点击蒙层关闭选择器 | Boolean | `true` | `true \| false` |
| maskOpacity | 蒙层透明度 | Number | `0.4` | `0~1` |
| preventBack | 是否阻止返回键/返回手势关闭选择器 | Boolean | `false` | `true \| false` |
| height | 选择器整体高度（含标题与按钮区域） | String \| Number | `350px` | - |
| title | 选择器标题，为空时不显示标题 | String | - | - |
| titleAlign | 标题对齐方式 | String | `center` | `left \| center \| right` |
| titleColor | 标题颜色 | String | `$title` | - |
| titleSize | 标题大小 | String \| Number | `$14` | - |
| cancelText | 取消按钮文字 | String | `取消` | - |
| confirmText | 确定按钮文字 | String | `确定` | - |
| cancelTextSize | 取消按钮文字大小 | String \| Number | `$14` | - |
| confirmTextSize | 确定按钮文字大小 | String \| Number | `$14` | - |
| showCancel | 是否显示取消按钮 | Boolean | `true` | `true \| false` |
| showConfirm | 是否显示确定按钮 | Boolean | `true` | `true \| false` |
| showClose | 是否显示右上角关闭按钮 | Boolean | `true` | `true \| false` |
| columnSpacing | 列之间的间距 | String \| Number | `10px` | - |
| actionSpacing | 取消/确定按钮之间的间距 | String \| Number | `10px` | - |
| itemHeight | 选项高度 | String \| Number | `$50` | - |
| itemBorderRadius | 选项圆角大小 | String \| Number | `$8` | - |
| itemTextColor | 选项文字颜色 | String | `$textLight（亮色模式）/ $lineText（暗黑模式）` | - |
| itemTextSize | 选项文字大小 | String \| Number | `$13` | - |
| activeItemTextColor | 激活选项文字颜色 | String | `$text` | - |
| disabledItemTextColor | 禁用选项文字颜色 | String | `$disabledText` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| headerStyle | 自定义标题栏样式 | SnStyleValue | - | - |
| headerClass | 外部样式类 | String | - | - |
| titleStyle | 自定义标题样式 | SnStyleValue | - | - |
| titleClass | 外部样式类 | String | - | - |
| closeButtonStyle | 自定义关闭按钮样式 | SnStyleValue | - | - |
| closeButtonClass | 外部样式类 | String | - | - |
| actionsStyle | 自定义底部按钮栏样式 | SnStyleValue | - | - |
| actionsClass | 外部样式类 | String | - | - |
| cancelButtonStyle | 自定义取消按钮样式 | SnStyleValue | - | - |
| cancelButtonClass | 外部样式类 | String | - | - |
| confirmButtonStyle | 自定义确定按钮样式 | SnStyleValue | - | - |
| confirmButtonClass | 外部样式类 | String | - | - |
| itemStyle | 自定义选项样式 | SnStyleValue | - | - |
| itemClass | 外部样式类 | String | - | - |
| columnStyle | 自定义列样式 | SnStyleValue | - | - |
| columnClass | 外部样式类 | String | - | - |

> 类型字段：SnRegionValue（见 https://sinleui.pages.dev/api/types/component#snregionvalue）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: `SnRegionValue`, detail: `SnRegionDetail`) => Void | 点击确定后，选中值写入 v-model 时触发，`detail` 含代码与名称 |
| confirm | () => Void | 点击确定按钮时触发（在 change 之前触发） |
| cancel | () => Void | 点击取消按钮时触发 |
| open | () => Void | 选择器打开后触发 |
| close | () => Void | 选择器关闭后触发 |
| clickoverlay | () => Void | 点击蒙层时触发 |
| beforeenter | () => Void | 进入动画开始前触发 |
| enter | () => Void | 进入动画开始时触发 |
| afterenter | () => Void | 进入动画结束后触发 |
| beforeleave | () => Void | 离开动画开始前触发 |
| leave | () => Void | 离开动画开始时触发 |
| afterleave | () => Void | 离开动画结束后触发 |

> 类型字段：SnRegionDetail（见 https://sinleui.pages.dev/api/types/component#snregiondetail）


## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 打开选择器（打开前会将 v-model 当前值复制为内部临时值，仅确定后才写回） |
| close | - | - | 关闭选择器 |

---

## sn-region-picker-view 地区选择器容器

`sn-region-picker-view` 基于 `sn-picker-view` 封装，是地区选择的核心视图，可独立在页面内使用。滚动选择实时生效，`change` 防抖 120ms 后触发。

```vue
<template>
	<sn-region-picker-view v-model="value" @change="onChange"></sn-region-picker-view>
</template>
```

### sn-region-picker-view 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 选中地区的区划代码数组（按列顺序） | SnRegionValue | `[]` | - |
| mode | 选择器模式（同 sn-region-picker） | String \| Number | `7` | - |
| customFilter | 自定义过滤项函数 | Function | `null` | - |
| disabled | 是否禁用选择器容器 | Boolean | `false` | `true \| false` |
| height | 选择器容器高度 | String \| Number | `250px` | - |
| itemHeight | 选项高度 | String \| Number | `$50` | - |
| itemBorderRadius | 选项圆角大小 | String \| Number | `$8` | - |
| itemTextColor | 选项文字颜色 | String | `$textLight（亮色模式）/ $lineText（暗黑模式）` | - |
| itemTextSize | 选项文字大小 | String \| Number | `$13` | - |
| activeItemTextColor | 激活选项文字颜色 | String | `$text` | - |
| disabledItemTextColor | 禁用选项文字颜色 | String | `$disabledText` | - |
| columnSpacing | 列间距 | String \| Number | `10px` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| customClass | 自定义根节点外部样式类 | String | - | - |
| itemStyle | 自定义选项样式 | SnStyleValue | - | - |
| itemClass | 外部样式类 | String | - | - |
| columnStyle | 自定义列样式 | SnStyleValue | - | - |
| columnClass | 外部样式类 | String | - | - |

### sn-region-picker-view 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: `SnRegionValue`, detail: `SnRegionDetail`) => Void | 滚动选择后触发（防抖 120ms），`detail` 含代码与名称 |

## 类型

### SnRegionLevel

`'province' | 'city' | 'county'` —— 列类型枚举。

> 类型字段：SnRegionNode（见 https://sinleui.pages.dev/api/types/component#snregionnode）


### SnRegionValue

`String[]`：选中地区各级区划代码数组（按列顺序）。

<DemoPhone name="sn-region-picker" />

# ColorPicker 颜色选择器

## 基础用法

弹出式颜色选择器，用于在底部抽屉中完成颜色选取与确认。

- 支持面板二维取色、色相 / 透明度滑块，以及 HEX / RGBA / HSB / HSL 四种格式输入
- 内置预设颜色区，预设区与扩展区均可用插槽整体替换
- 打开状态下，外部修改绑定值会实时同步到取色面板

::: info 确定后写入
仅点击“确定”才将颜色值写入 `v-model`，点击“取消”或关闭时丢弃本次修改
:::

```vue
<template>
	<sn-button type="primary" text="打开颜色选择器" @click="openPicker"></sn-button>
	<sn-color-picker ref="picker" v-model="color" title="选择颜色" @confirm="onConfirm"></sn-color-picker>
</template>

<script lang="ts" setup>

	const picker = ref<SnColorPickerComponentPublicInstance | null>(null)
	const color = ref<string>('#F5222D')

	function openPicker() {
		picker.value?.$callMethod('open')
	}

	function onConfirm(value: string) {
		console.log(value)
	}
</script>
```

**更多演示请下载 demo 查看**

## 实现原理

弹出式部分基于 `sn-drawer` 底部抽屉封装，内部嵌入 `sn-color-picker-view`。

遮罩与面板在首次打开时挂载，与其他 Picker 保持一致，关闭后保留节点；不再预挂载固定定位面板，以规避首次显示时的层级异常。此挂载策略不影响独立使用的 `sn-color-picker-view`。

格式下拉菜单属于嵌套弹层：打开时使用高于颜色选择器的动态层级，遮罩拦截底层触摸滚动；点击格式选项切换输入格式，点击菜单外区域仅关闭格式菜单，不关闭颜色选择器。

拖动取色时面板仅更新饱和度与亮度；拖动到边界时保持当前色相，亮度降为 0 时色相滑块不会跳回红色端点；手指越过面板进入色相条仍保持原色相，色相条右端保持在 360° 位置。

## 注意事项

标题默认居中显示；取消 / 确定按钮在未传入文案时自动使用当前语言的默认文案。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定的颜色值 | String | `#F5222D` | - |
| disabled | 是否禁用（取色、输入、按钮均不可用） | Boolean | `false` | `true \| false` |
| height | 弹出抽屉的高度 | String \| Number | `620px` | - |
| maskClose | 点击遮罩是否可关闭 | Boolean | `true` | `true \| false` |
| maskOpacity | 遮罩透明度 | Number | `0.4` | - |
| preventBack | 是否阻止返回键关闭 | Boolean | `false` | `true \| false` |
| title | 标题，为空时不显示 | String | `''` | - |
| showClose | 是否显示右上角关闭按钮 | Boolean | `true` | `true \| false` |
| showAlpha | 是否显示透明度滑块与透明度输入 | Boolean | `true` | `true \| false` |
| showPresets | 是否显示预设颜色区域 | Boolean | `true` | `true \| false` |
| format | 初始输入格式 | String | `hex` | `hex \| rgba \| hsb \| hsl` |
| presetTitle | 预设颜色区域标题 | String | `内置颜色` | - |
| presetColors | 自定义预设颜色，二维数组（每行一组）；使用内置色板 | `Array<Array<String>>` | - | - |
| panelHeight | 取色面板高度 | String \| Number | `260px` | - |
| showCancel | 是否显示取消按钮 | Boolean | `true` | `true \| false` |
| showConfirm | 是否显示确定按钮 | Boolean | `true` | `true \| false` |
| cancelText | 取消按钮文字 | String | `取消` | - |
| confirmText | 确定按钮文字 | String | `确定` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |
| headerStyle | 标题栏自定义样式 | SnStyleValue | `''` | - |
| headerClass | 样式类 | String | `''` | - |
| titleStyle | 标题文字自定义样式 | SnStyleValue | `''` | - |
| titleClass | 样式类 | String | `''` | - |
| closeButtonStyle | 关闭按钮自定义样式 | SnStyleValue | `''` | - |
| closeButtonClass | 样式类 | String | `''` | - |
| actionsStyle | 底部按钮区域自定义样式 | SnStyleValue | `''` | - |
| actionsClass | 样式类 | String | `''` | - |
| cancelButtonStyle | 取消按钮自定义样式 | SnStyleValue | `''` | - |
| cancelButtonClass | 样式类 | String | `''` | - |
| confirmButtonStyle | 确定按钮自定义样式 | SnStyleValue | `''` | - |
| confirmButtonClass | 样式类 | String | `''` | - |
| viewStyle | 透传至内部 sn-color-picker-view 根节点的自定义样式 | SnStyleValue | `''` | - |
| viewClass | 样式类 | String | `''` | - |
| panelStyle | 透传至内部 sn-color-picker-view，取色面板自定义样式 | SnStyleValue | `''` | - |
| panelClass | 样式类 | String | `''` | - |
| thumbClass | 透传至内部 sn-color-picker-view，取色面板指示圆点样式类 | String | `''` | - |
| slidersStyle | 透传至内部 sn-color-picker-view，滑块容器自定义样式 | SnStyleValue | `''` | - |
| slidersClass | 样式类 | String | `''` | - |
| hueStyle | 透传至内部 sn-color-picker-view，色相滑块自定义样式 | SnStyleValue | `''` | - |
| hueClass | 样式类 | String | `''` | - |
| alphaStyle | 透传至内部 sn-color-picker-view，透明度滑块自定义样式 | SnStyleValue | `''` | - |
| alphaClass | 样式类 | String | `''` | - |
| sliderThumbClass | 透传至内部 sn-color-picker-view，滑块指示圆点样式类 | String | `''` | - |
| inputRowStyle | 透传至内部 sn-color-picker-view，格式与数值输入行自定义样式 | SnStyleValue | `''` | - |
| inputRowClass | 样式类 | String | `''` | - |
| fieldsStyle | 透传至内部 sn-color-picker-view，数值输入区域自定义样式 | SnStyleValue | `''` | - |
| fieldsClass | 样式类 | String | `''` | - |
| selectStyle | 透传至内部 sn-color-picker-view，格式下拉选择自定义样式 | SnStyleValue | `''` | - |
| selectClass | 样式类 | String | `''` | - |
| inputStyle | 透传至内部 sn-color-picker-view，数值输入框自定义样式 | SnStyleValue | `''` | - |
| inputClass | 样式类 | String | `''` | - |
| presetsStyle | 透传至内部 sn-color-picker-view，预设颜色区域自定义样式 | SnStyleValue | `''` | - |
| presetsClass | 样式类 | String | `''` | - |
| presetTitleStyle | 透传至内部 sn-color-picker-view，预设颜色标题自定义样式 | SnStyleValue | `''` | - |
| presetTitleClass | 样式类 | String | `''` | - |
| presetGridStyle | 透传至内部 sn-color-picker-view，预设颜色网格自定义样式 | SnStyleValue | `''` | - |
| presetGridClass | 样式类 | String | `''` | - |
| presetItemStyle | 透传至内部 sn-color-picker-view，预设颜色块自定义样式 | SnStyleValue | `''` | - |
| presetItemClass | 样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: string) => Void | 点击确定写入颜色值时触发，与 v-model 同步 |
| confirm | (value: string) => Void | 点击确定时触发，携带确认后的颜色值 |
| cancel | () => Void | 点击取消时触发 |
| open | () => Void | 选择器打开（动画结束）时触发 |
| close | () => Void | 选择器关闭（动画结束）时触发 |
| clickoverlay | () => Void | 点击遮罩时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 打开颜色选择器，以当前 v-model 值作为初始颜色 |
| close | - | - | 关闭颜色选择器，不写入颜色值 |

## 插槽

| 名称 | 说明 | 作用域 |
| --- | --- | --- |
| preset | 替换「内置颜色」预设区域内容；未传入时渲染预设颜色网格（预设标题与色块），`showPresets` 为 `false` 时不显示该区域 | color：当前颜色值 |
| extra | 预设颜色区域下方的扩展区域，可放置自定义内容（如自定义色板）；未传入时不渲染 | color：当前颜色值 |

`extra` 插槽可作为“自定义色板”使用：点击色点直接修改 `v-model`（打开状态下会同步到取色面板）：

```vue
<template>
	<sn-color-picker ref="picker" v-model="color" title="选择颜色">
		<template #extra="slotProps">
			<view class="my-palette">
				<view v-for="(c, i) in palette" :key="i" class="my-palette-dot" :style="dotStyle(c, slotProps.color)"
					@click="onPick(c)"></view>
			</view>
		</template>
	</sn-color-picker>
</template>

<script lang="ts" setup>
	const picker = ref<SnColorPickerComponentPublicInstance | null>(null)
	const color = ref<string>('#F5222D')
	const palette = ref<string[]>(['#1F1F1F', '#EF4444', '#3B82F6'])

	function onPick(c: string) {
		color.value = c
	}

	function dotStyle(c: string, current: any): string {
		const ring = current == c ? 'var(--sn-primary)' : 'var(--sn-line)'
		return `width:28px;height:28px;border-radius:14px;margin-right:8px;background-color:${c};border:2px solid ${ring};`
	}
</script>
```

---

以下属性属于 **sn-color-picker-view**（颜色选择容器），可直接嵌入页面单独使用，不依赖弹出层：

```vue
<template>
	<sn-color-picker-view v-model="color" @change="onChange"></sn-color-picker-view>
</template>

<script lang="ts" setup>
	const color = ref<string>('#F5222D')

	function onChange(value: string) {
		console.log(value)
	}
</script>
```

## sn-color-picker-view 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定的颜色值 | String | `#F5222D` | - |
| active | 是否激活；为 false 时不响应外部颜色值变化与交互 | Boolean | `true` | `true \| false` |
| disabled | 是否禁用（拖动取色与输入均不可用） | Boolean | `false` | `true \| false` |
| showAlpha | 是否显示透明度滑块与透明度输入 | Boolean | `true` | `true \| false` |
| showPresets | 是否显示预设颜色区域 | Boolean | `true` | `true \| false` |
| format | 初始输入格式 | String | `hex` | `hex \| rgba \| hsb \| hsl` |
| presetTitle | 预设颜色区域标题 | String | `内置颜色` | - |
| presetColors | 自定义预设颜色，二维数组（每行一组）；使用内置色板 | `Array<Array<String>>` | - | - |
| panelHeight | 取色面板高度 | String \| Number | `300px` | - |
| sliderHeight | 滑块轨道高度 | String \| Number | `$24` | - |
| sliderSpacing | 滑块、输入行、预设区域之间的间距 | String \| Number | `$12` | - |
| borderRadius | 取色面板与滑块的圆角大小 | String \| Number | `$10` | - |
| thumbSize | 取色面板指示圆点大小 | String \| Number | `$30` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |
| customClass | 根节点自定义样式类 | String | `''` | - |
| panelStyle | 取色面板自定义样式 | SnStyleValue | `''` | - |
| panelClass | 样式类 | String | `''` | - |
| thumbClass | 取色面板指示圆点样式类 | String | `''` | - |
| slidersStyle | 滑块容器自定义样式 | SnStyleValue | `''` | - |
| slidersClass | 样式类 | String | `''` | - |
| hueStyle | 色相滑块自定义样式 | SnStyleValue | `''` | - |
| hueClass | 样式类 | String | `''` | - |
| alphaStyle | 透明度滑块自定义样式 | SnStyleValue | `''` | - |
| alphaClass | 样式类 | String | `''` | - |
| sliderThumbClass | 滑块指示圆点样式类 | String | `''` | - |
| inputRowStyle | 格式与数值输入行自定义样式 | SnStyleValue | `''` | - |
| inputRowClass | 样式类 | String | `''` | - |
| fieldsStyle | 数值输入区域自定义样式 | SnStyleValue | `''` | - |
| fieldsClass | 样式类 | String | `''` | - |
| selectStyle | 格式下拉选择自定义样式 | SnStyleValue | `''` | - |
| selectClass | 样式类 | String | `''` | - |
| inputStyle | 数值输入框自定义样式 | SnStyleValue | `''` | - |
| inputClass | 样式类 | String | `''` | - |
| presetsStyle | 预设颜色区域自定义样式 | SnStyleValue | `''` | - |
| presetsClass | 样式类 | String | `''` | - |
| presetTitleStyle | 预设颜色标题自定义样式 | SnStyleValue | `''` | - |
| presetTitleClass | 样式类 | String | `''` | - |
| presetGridStyle | 预设颜色网格自定义样式 | SnStyleValue | `''` | - |
| presetGridClass | 样式类 | String | `''` | - |
| presetItemStyle | 预设颜色块自定义样式 | SnStyleValue | `''` | - |
| presetItemClass | 样式类 | String | `''` | - |

## sn-color-picker-view 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: string) => Void | 拖动取色、修改数值输入、点击预设颜色时触发，携带当前颜色值 |

## sn-color-picker-view 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| refresh | - | - | 重新测量取色面板与滑块位置并同步显示（一般无需手动调用） |

## sn-color-picker-view 插槽

| 名称 | 说明 | 作用域 |
| --- | --- | --- |
| preset | 替换「内置颜色」预设区域内容；未传入时渲染预设颜色网格（预设标题与色块），`showPresets` 为 `false` 时不显示该区域 | color：当前颜色值 |
| extra | 预设颜色区域下方的扩展区域，可放置自定义内容（如自定义色板）；未传入时不渲染 | color：当前颜色值 |

<DemoPhone name="sn-color-picker" />

# Form 表单

> [查看 sn-form 的 2.0 版本差异](/differences/components/sn-form)

## 基础用法

数据收集与校验组件，三层结构配合完成表单项的注册、校验与错误展示。

- 表单容器统一持有表单数据，各表单项按字段名注册校验
- 自带标签的输入框与文本域字段组件可直接参与校验，其余控件放入通用表单项容器
- 校验结果交由外部回填展示，组件不自动渲染错误提示

```vue
<template>
	<sn-form ref="formRef" v-model="formData">
		<sn-input-field field="name" :rule="nameRule" v-model="(formData['name'] as string)" label="姓名" :error="getFieldError('name')" placeholder="请输入中文姓名" clearable />
		<sn-input-field field="phone" :rule="phoneRule" v-model="(formData['phone'] as string)" label="手机号" :error="getFieldError('phone')" type="number" placeholder="请输入手机号" clearable />
		<sn-form-field field="gender" :rule="genderRule" label="性别" :error="getFieldError('gender')">
			<sn-radio-group v-model="(formData['gender'] as number)">
				<sn-radio text="男" />
				<sn-radio text="女" />
			</sn-radio-group>
		</sn-form-field>
	</sn-form>
	<sn-button text="提交" type="primary" custom-style="margin-top:16px;" @click="onSubmit" />
</template>

<script lang="ts" setup>
	import type { SnFormItemRule, SnFormItemVerifyResult, SnFormValidResult } from '@/uni_modules/sinle-ui'

	const formRef = ref<SnFormComponentPublicInstance | null>(null)
	const formData = ref<SnFormData>({
		name: '',
		phone: '',
		gender: 0
	})
	const failResults = ref<SnFormItemVerifyResult[]>([])

	function getFieldError(field: string): string {
		const list = failResults.value
		for (let i = 0; i < list.length; i++) {
			if (list[i].field == field) {
				return list[i].message ?? ''
			}
		}
		return ''
	}

	const nameRule = ref<SnFormItemRule>({
		type: 'chinese',
		required: true,
		message: '请填写正确的中文姓名'
	} as SnFormItemRule)

	const phoneRule = ref<SnFormItemRule>({
		type: 'phone',
		required: true,
		message: '请填写正确的手机号'
	} as SnFormItemRule)

	const genderRule = ref<SnFormItemRule>({
		required: true,
		message: '请选择性别'
	} as SnFormItemRule)

	function onSubmit(): void {
		formRef.value?.$callMethod('submit', {
			success: () => {
				failResults.value = []
			},
			fail: (results: SnFormItemVerifyResult[]) => {
				failResults.value = results
			}
		} as SnFormValidResult)
	}
</script>
```

**更多演示请下载 demo 查看**

## 三层结构与配合方式

| 组件 | 职责 |
| --- | --- |
| sn-form | 数据容器与校验调度器：`v-model` 持有整个表单数据对象，收集所有注册的表单项并逐项校验 |
| sn-input-field / sn-textarea-field | 自带标签与输入控件（textarea）的字段组件：设置 `field` + `rule` 即参与校验，内部已实现标签布局与错误提示，**无需**再包一层 `sn-form-field` |
| sn-form-field | 通用表单项容器基座：标签 + 内容插槽 + 错误提示的布局外壳，内容区放任意控件，通过 `field` + `rule` 注册校验 |

配合要点：

- 表单项组件必须位于 `sn-form` 内部（`sn-form` 通过 provide/inject 收集子项），此时 `field` + `rule` 才会生效；独立使用时表单项仅作为普通布局/输入组件。
- 校验时 `sn-form` 从自身 `v-model` 对象中按 `field` 取值传给表单项校验，因此需把控件的 `v-model` 绑定到表单数据对象的对应字段，如 `v-model="(formData['gender'] as number)"`。
- 错误提示不会自动显示：把 `fail` 结果中对应字段的 `message` 赋给表单项的 `error` 属性即可（三类表单项组件都有 `error` 属性与 `error` 插槽）。
- 开启 `trigger-change` 后，表单数据每次变化都会自动执行一遍校验，适合"输入即反馈"场景，通过结果可触发 `pass` / `fail` 事件。

## 校验规则

> 类型字段：SnFormItemRule（见 https://sinleui.pages.dev/api/types/component#snformitemrule）


`type` 可选值：`string`、`number`、`boolean`、`object`、`array`、`integer`、`float`、`enum`、`url`、`email`、`idcard`、`phone`、`landline`、`qqnumber`、`abc`、`chinese`、`carnumber`、`ipv4`、`ipv6`。格式类校验对空值不生效，空值校验交给 `required`。

```typescript
const adultRule = ref<SnFormItemRule>({
	type: 'integer',
	required: true,
	message: '请填写年龄',
	transform: (value: any): any => {
		if (value == null || value == '') {
			return null
		}
		return parseInt(value as string)
	},
	valid: (value: any): string => {
		if (typeof value == 'number' && value < 18) {
			return '必须年满 18 周岁'
		}
		return ''
	}
} as SnFormItemRule)
```

校验单项结果 `SnFormItemVerifyResult` 包含 `valid`（是否通过）、`message`（提示信息）、`field`（字段名）。提交回调类型 `SnFormValidResult` 包含 `success` 与 `fail`（携带失败结果数组）两个可选回调。

## 仅校验不提交

调用 `validate` 方法只做校验，通过与否都不会触发 `submit` 事件。

```vue
<template>
	<sn-form ref="formRef" v-model="formData">
		<sn-input-field field="age" :rule="ageRule" v-model="(formData['age'] as string)" label="年龄" type="number" />
	</sn-form>
	<sn-button text="仅校验" @click="onValidateOnly" />
</template>

<script lang="ts" setup>
	import type { SnFormValidResult } from '@/uni_modules/sinle-ui'

	const formRef = ref<SnFormComponentPublicInstance | null>(null)

	function onValidateOnly(): void {
		formRef.value?.$callMethod('validate', {
			success: () => {},
			fail: () => {}
		} as SnFormValidResult)
	}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 表单数据对象，键为表单项的 `field`，值为对应控件绑定的值；深度监听，变化时触发 change 事件 | SnFormData | `{}` | - |
| triggerChange | 是否在表单数据变化时自动执行校验 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| submit | () => Void | 调用 submit 方法且校验通过后触发 |
| pass | () => Void | 校验通过时触发 |
| fail | (failResults: SnFormItemVerifyResult[]) => Void | 校验失败时触发，携带全部失败项的结果数组 |
| change | (value: SnFormData) => Void | 表单数据变化时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| validate | (callback: `SnFormValidResult` \| null)，可省略 | - | 仅校验不提交：通过时触发 pass 事件并执行 success 回调，失败时触发 fail 事件并执行 fail 回调（携带失败结果数组） |
| submit | (callback: `SnFormValidResult` \| null)，可省略 | - | 校验通过后触发 submit 事件并执行 success 回调；失败时执行 fail 回调 |
| register | (item: SnFormItemData) | - | 注册表单项，由表单项组件自动调用，无需手动调用 |
| unregister | (field: String) | - | 注销表单项，由表单项组件自动调用，无需手动调用 |

> 类型字段：SnFormValidResult（见 https://sinleui.pages.dev/api/types/component#snformvalidresult）


## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 放置 sn-input-field、sn-textarea-field、sn-form-field 等表单项组件 |

<DemoPhone name="sn-form" />

# UploadMedia 媒体上传

> [查看 sn-upload-media 的 2.0 版本差异](/differences/components/sn-upload-media)

## 基础用法

用于快速选择并上传图片 / 视频媒体文件，分为基础版（`sn-upload-media`）与 uniCloud 版（`sn-upload-media-unicloud`）。

- 支持选择、预览、删除与状态角标展示
- 选择后可自动上传，也可通过实例方法手动上传
- 添加项占位符可经默认插槽自定义，未传插槽时显示加号图标

::: info 上传失败状态
`timeout` 默认 `30000`（30s）。上传请求在超时时间内未完成（含未配置有效服务器地址导致的连接挂起，或 H5 HTTPS 页面拦截 HTTP 上传请求）会被中止，状态置为「上传失败」并触发 `upload-error` 事件。网络异常、服务端非 200 响应、以及上传结果未能通过回调返回的情况同样置为「上传失败」，且每个文件只触发一次 `upload-error`。
:::

```vue
<template>
	<sn-upload-media url="https://example.com/upload" :timeout="30000"></sn-upload-media>
</template>
```

> 说明：`timeout` 默认 `30000`（30s）。上传请求在超时时间内未完成（含未配置有效服务器地址导致的连接挂起，或 H5 HTTPS 页面拦截 HTTP 上传请求）会被中止，状态置为「上传失败」并触发 `upload-error` 事件。

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| url | 上传地址 | String | - | - |
| autoUpload | 是否在选择后自动上传；设为 `false` 时可通过 `upload` 方法手动上传 | Boolean | `true` | `true` \| `false` |
| mode | 媒体模式 | String | `image` | `image` \| `video` \| `all` |
| chooseCount | 一次可选择的文件数量（视频每次仅 1 个） | Number | `20` | - |
| maxCount | 最多可上传的文件数量，小于等于 0 不限制 | Number | `-1` | - |
| timeout | 上传超时时间（单位：ms），超时后中止请求并触发 `upload-error`，状态置为上传失败；H5 HTTPS 页面拦截 HTTP 上传请求时也按此计时 | Number | `30000` | - |
| formData | 附加到上传请求的表单数据 | SnFormData | `{}` | - |
| sourceType | 可选择媒体的来源 | `Array<String>` | `["album", "camera"]` | `album` \| `camera` |
| width | 媒体文件子项宽度，支持 `$` 前缀按间距乘数缩放 | String \| Number | `70px` | - |
| height | 媒体文件子项高度，支持 `$` 前缀按间距乘数缩放 | String \| Number | `70px` | - |
| itemBgColor | 占位项背景颜色 | String | `$line` | `$primary` 等主题色 |
| itemBorderRadius | 媒体文件子项圆角 | String \| Number | `$8` | - |
| iconSize | 占位项中央图标大小 | String \| Number | `40px` | - |
| disabled | 是否禁用选择、预览与删除 | Boolean | `false` | `true` \| `false` |
| chooseErrorTip | 选择媒体失败时的提示信息 | String | `选择媒体文件失败` | - |
| enablePreview | 是否启用点击图片预览，仅图片生效 | Boolean | `true` | `true` \| `false` |
| uploadingText | 上传中的状态文本 | String | `上传中` | - |
| uploadedText | 上传成功的状态文本 | String | `上传成功` | - |
| unuploadedText | 未上传的状态文本 | String | `未上传` | - |
| errorText | 上传失败的状态文本 | String | `上传失败` | - |
| clearable | 是否显示删除按钮 | Boolean | `true` | `true` \| `false` |
| compressed | 是否压缩视频，仅视频模式生效 | Boolean | `true` | `true` \| `false` |
| maxDuration | 录像最大时长（单位：s），仅视频模式生效 | Number | `60` | - |
| customStyle | 自定义整个上传区域样式 | SnStyleValue | - | - |
| customItemStyle | 自定义媒体文件子项样式 | SnStyleValue | - | - |

## sn-upload-media-unicloud 属性

uniCloud 版上传至云存储，**无 `url`、`timeout`、`formData`** 属性（上传走 `uniCloud.uploadFile`），其余属性与上表一致，额外新增：

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| directory | 上传至云存储的目录，与随机生成的文件名拼合为云路径；开头 `/` 与结尾 `/` 会被自动规整 | String | `uploadImages/` | - |

## 事件

基础版与 uniCloud 版事件名一致，差异仅在 `uploaded` 的回调参数类型（基础版 `UploadFileSuccess`，uniCloud 版 `UniCloudUploadFileResult`）。

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| uploaded | (response: UploadFileSuccess) => Void | 每个文件上传成功时触发（uniCloud 版为 `UniCloudUploadFileResult`） |
| upload-error | (error: `UniError`) => Void | 每个文件上传失败时触发 |
| choose-error | (error: `UniError`) => Void | 选择媒体文件失败时触发（用户主动取消不触发） |
| image-chose | (res: ChooseImageSuccess) => Void | 选择图片成功时触发 |
| video-chose | (res: ChooseVideoSuccess) => Void | 选择视频成功时触发 |
| file-chose | (files: `SnFile`[]) => Void | 混合模式选择文件（图片和视频）成功时触发 |

> 类型字段：UniError（见 https://sinleui.pages.dev/api/types/component#unierror）

> 类型字段：SnFile（见 https://sinleui.pages.dev/api/types/component#snfile）


## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| upload | - | - | 手动上传所有未上传 / 上传失败的文件 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 替换默认的媒体文件占位项 |

<DemoPhone name="sn-upload-media" />

# Cell 单元格

## 基础用法

列表项单元格，左侧为标题与描述，右侧为值与箭头图标。

- 标题、描述、值与左右图标均可配置
- 显示右箭头时自动具备点击态，也可单独开启
- 底部分隔线可开关，并自动避开左侧图标

```vue
<template>
	<sn-cell title="单元格" value="内容" label="描述信息" right-icon="arrow-right"
		@click="onCellClick"></sn-cell>
</template>

<script lang="ts" setup>
function onCellClick(name: string | number): void {
	console.log(name)
}
</script>
```

**更多演示请下载 demo 查看**

## 自定义各部分内容

每个区域均可通过插槽自定义，插槽优先级高于同名属性。

```vue
<template>
	<sn-cell right-icon="arrow-right">
		<template #icon>
			<sn-icon name="user-line" size="18" color="#fff"></sn-icon>
		</template>
		<template #title>
			<sn-text type="title" font-size="$14">自定义标题</sn-text>
		</template>
		<template #value>
			<sn-text type="primary" font-size="$12">自定义内容</sn-text>
		</template>
	</sn-cell>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| title | 单元格标题 | String \| Number | `''` | - |
| label | 标题下方的描述信息 | String \| Number | `''` | - |
| value | 右侧内容 | String \| Number | `''` | - |
| icon | 左侧图标名称 | String | `''` | - |
| disabled | 是否禁用，禁用后不触发点击且整体半透明 | Boolean | `false` | `true` \| `false` |
| border | 是否显示底部 1px 分隔线 | Boolean | `true` | `true` \| `false` |
| clickable | 是否开启可点击状态（显示按压反馈） | Boolean | `false` | `true` \| `false` |
| rightIcon | 右侧图标名称，设置后单元格自动可点击 | String | `''` | - |
| arrowDirection | 箭头方向，仅对 `arrow-right` 图标生效 | String | `right` | `left` \| `up` \| `down` \| `right` |
| stop | 点击时是否阻止事件冒泡 | Boolean | `true` | `true` \| `false` |
| name | 点击事件携带的标识符 | String \| Number | `''` | - |
| bgColor | 背景颜色 | String | `var(--sn-front)` | - |
| padding | 内边距，为空时使用随间距乘数缩放的默认值，支持 `$` 前缀按间距乘数缩放 | String | - | - |
| hoverStyle | 按压时应用的样式 | SnStyleValue | `background: var(--sn-info);` | - |
| hoverStopPropagation | 按压态是否阻止向父节点传播 | Boolean | `false` | `true` \| `false` |
| hoverStartTime | 按压态启动延时（ms） | Number | `0` | - |
| hoverStayTime | 松手后按压态保持时长（ms） | Number | `0` | - |
| hoverTransTime | 按压态过渡动画时长，支持 `$` 简写 | String \| Number | `$short` | - |
| iconStyle | 自定义左侧图标样式 | SnStyleValue | `''` | - |
| iconClass | 左侧图标外部类 | String | `''` | - |
| titleStyle | 自定义标题样式 | SnStyleValue | `''` | - |
| titleClass | 标题外部类 | String | `''` | - |
| rightIconStyle | 自定义右侧图标样式 | SnStyleValue | `''` | - |
| rightIconClass | 右侧图标外部类 | String | `''` | - |
| customStyle | 自定义单元格根节点样式 | SnStyleValue | `''` | - |
| customClass | 单元格根节点外部类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| click | (name: string \| number) => Void | 点击单元格时触发，参数为 `name` 标识符；禁用时不触发 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| icon | 替换左侧图标 |
| title | 替换标题内容 |
| label | 替换描述信息内容 |
| value | 替换右侧内容 |
| right-icon | 替换右侧图标 |

<DemoPhone name="sn-cell" />

# Album 相册

## 基础用法

用于以九宫格形式展示一组图片，常见于动态、详情页的图片列表。

- 默认三列等宽方形排列，列数、间距与圆角可调
- 加载中或加载失败时显示占位图标（或占位图），加载成功后移除占位层
- 点击图片默认打开系统图片预览；超出最大行数时折叠，并在最后一张上显示 `+n` 数量遮罩

```vue
<template>
	<sn-album :urls="urls"></sn-album>
</template>
<script lang="ts" setup>
const urls: string[] = [
	'https://example.com/1.jpg',
	'https://example.com/2.jpg',
	'https://example.com/3.jpg'
]
</script>
```

**更多演示请下载 demo 查看**

## 最大行数与长按菜单

设置 `max-row` 后，超出 `maxRow × rowCount` 的图片折叠，最后一张上显示 `+n` 遮罩；`preview-actions` 设置预览时长按图片弹出的操作菜单。

```vue
<template>
	<sn-album :urls="urls" :max-row="2" :preview-actions="actions"></sn-album>
</template>
<script lang="ts" setup>
const actions: string[] = ['保存图片', '发送给朋友']
</script>
```

## 点击事件

`preview` 设为 `false` 可关闭默认预览，仅监听 `@click` 事件（参数为图片索引）。

```vue
<template>
	<sn-album :urls="urls" :preview="false" @click="onClick"></sn-album>
</template>
<script lang="ts" setup>
function onClick(index: number): void {
	console.log(`点击了第 ${index + 1} 张图片`)
}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| urls | 图片地址列表 | String[] | `[]` | - |
| rowCount | 每行图片数量 | Number | `3` | - |
| maxRow | 最大行数，超出部分折叠为数量遮罩（0 表示不限制） | Number | `0` | - |
| space | 图片间距，支持 `$` 简写 | String \| Number | `$6` | - |
| borderRadius | 图片圆角，支持 `$` 简写 | String \| Number | `$8` | - |
| imageMode | 图片裁剪缩放模式（同内置 image 组件 mode） | String | `aspectFill` | `aspectFill` \| `aspectFit` \| `scaleToFill` \| `widthFix` 等 |
| lazyLoad | 是否懒加载图片 | Boolean | `true` | `true` \| `false` |
| preview | 点击图片时是否调用系统图片预览 | Boolean | `true` | `true` \| `false` |
| showMore | 超出 maxRow 时是否在最后一张上显示 `+n` 遮罩 | Boolean | `true` | `true` \| `false` |
| previewActions | 预览时长按图片弹出的操作菜单文本列表（非空时启用长按菜单） | String[] | `[]` | - |
| placeholderImage | 占位图片地址（加载中/加载失败时显示，优先于占位图标） | String | `''` | - |
| placeholderIcon | 占位图标名称 | String | `image-line` | - |
| placeholderColor | 占位区背景颜色 | String | `$info` | - |
| placeholderIconColor | 占位图标颜色 | String | `$infoDark` | - |
| placeholderIconSize | 占位图标大小，支持 `$` 简写 | String \| Number | `24px` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部样式类（external-class：`custom-class`） | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| :--- | :--- | :--- |
| click | (index: number) => Void | 点击图片时触发，参数为图片在 `urls` 中的索引；`preview` 为 true 时同时打开系统图片预览 |

<DemoPhone name="sn-album" />

# Line 分割线

> [查看 sn-line 的 2.0 版本差异](/differences/components/sn-line)

## 基础用法

分割线组件，可包含文本或圆点。

- 支持水平与垂直方向，长度可指定
- 支持虚线，可在水平分割线中间显示文本或以圆点代替文本
- 颜色默认取主题线条色并可自定义，与上下（或左右）内容的间距可调

```vue
<template>
	<sn-line text="这是分割线" margin="16"></sn-line>
</template>
```

**更多演示请下载 demo 查看**

## 垂直分割线

垂直分割线常用于行内内容之间的分隔，需在水平排列的容器中使用。

```vue
<template>
	<view class="row">
		<text>文字</text>
		<sn-line direction="vertical" :length="20" margin="12"></sn-line>
		<text>文字</text>
	</view>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| direction | 分割线方向 | String | `horizontal` | `horizontal` \| `vertical` |
| color | 分割线颜色 | String | `$line` | - |
| length | 分割线长度（px），水平时为宽度、垂直时为高度；非数值时水平占满宽度、垂直使用默认高度；支持 `$` 前缀按间距乘数缩放 | String \| Number | - | - |
| thickness | 分割线粗细（px） | String \| Number | `1` | - |
| margin | 分割线外边距（px），水平时作用于上下、垂直时作用于左右 | String \| Number | `0` | - |
| dashed | 是否显示为虚线 | Boolean | `false` | `true` \| `false` |
| dot | 是否以圆点"•"代替文本（仅水平方向有效） | Boolean | `false` | `true` \| `false` |
| text | 分割线中间显示的文本（仅水平方向有效） | String | `''` | - |
| customStyle | 自定义分割线样式（仅无文本模式生效） | SnStyleValue | `''` | - |

<DemoPhone name="sn-line" />

# ArcProgress 环形进度

## 基础用法

环形（圆弧）进度展示组件。

- 基于 canvas 绘制，起止角度与轨道 / 进度条样式可自定义
- 进度值支持双向绑定，越界自动夹取并以缓动动画过渡
- 默认在圆弧中心显示百分比，也可用插槽完全自定义

```vue
<template>
	<sn-arc-progress v-model="value"></sn-arc-progress>
</template>
```

**更多演示请下载 demo 查看**

## 仪表盘进度

通过 `start-angle` 与 `end-angle` 定义圆弧区间（角度制，0° 为 3 点钟方向，顺时针为正），配合 `min`、`max` 可实现温度计、仪表盘等非 0-100 场景。

```vue
<template>
	<sn-arc-progress v-model="temperature" :min="16" :max="30" :start-angle="-180" :end-angle="0" stroke-color="$warning">
		<template v-slot:value="scope">
			<sn-text :text="`${scope.value} °C`" bold></sn-text>
		</template>
	</sn-arc-progress>
</template>
```

## 自定义中心内容

使用 `value` 插槽可替换中心默认的百分比文本，插槽作用域提供当前值 `value` 与百分比 `percent`。

```vue
<template>
	<sn-arc-progress v-model="percent" stroke-color="$success">
		<template v-slot:value="scope">
			<sn-text :text="`${scope.percent}%`" color="$success" bold></sn-text>
		</template>
	</sn-arc-progress>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值（进度值，自动夹取到 [min, max] 区间） | Number | `0` | - |
| size | 组件尺寸（宽高一致），支持 `$` 前缀动态尺寸 | String \| Number | `$200` | - |
| start-angle | 轨道起始角度（度，0° 为 3 点钟方向，顺时针为正） | Number | `-225` | - |
| end-angle | 轨道结束角度，与起始角度构成圆弧区间，区间 ≥ 360° 时绘制完整圆环 | Number | `45` | - |
| line-cap | 圆弧线端点样式，完整圆环时强制为 `butt` | String | `round` | `butt` \| `round` \| `square` |
| stroke-width | 进度条粗细，支持 `$` 前缀动态尺寸 | String \| Number | `$20` | - |
| stroke-color | 进度条颜色，支持 `$` 简写 | String | `$primary` | - |
| trail-width | 轨道粗细，支持 `$` 前缀动态尺寸 | String \| Number | `$20` | - |
| trail-color | 轨道颜色，支持 `$` 简写 | String | `$line` | - |
| min | 数值下限 | Number | `0` | - |
| max | 数值上限 | Number | `100` | - |
| show-value-text | 是否在中心显示百分比文本 | Boolean | `true` | `true` \| `false` |
| ani-time | 进度变化动画时长（ms），支持 `$` 前缀动态时长，传 `0` 关闭动画 | String \| Number | `$long` | - |
| custom-style | 自定义根节点样式 | SnStyleValue | `''` | - |
| custom-class | 根节点外部样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: Number) => Void | 绑定值变化（夹取后）时触发 |
| finish | (value: Number) => Void | 进度动画结束（或无动画直接到位）时触发，参数为最终目标值 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| value | 自定义圆弧中心内容，替换默认百分比文本，作用域为 `{ value: Number, percent: Number }` |

<DemoPhone name="sn-arc-progress" />

# Badge 徽标

> [查看 sn-badge 的 2.0 版本差异](/differences/components/sn-badge)

## 基础用法

未读消息与消息提示徽标，包裹在目标内容右上角显示。

- 支持数字、文本与浮点三种模式
- 数字超过上限显示“max+”，为 0 时默认隐藏
- 不包裹内容时也可独立使用

```vue
<template>
	<sn-badge :value="15">
		<sn-avatar src="https://www.example.com/example.png"></sn-avatar>
	</sn-badge>
</template>
```

**更多演示请下载 demo 查看**

## 自定义徽标内容

- 通过 `value` 插槽完全自定义徽标内部内容（优先级最高）。
- 通过 `offset` 在默认右上角定位基础上追加位移，格式同 css `transform`（如 `translate(-10px, 6px)`）。

```vue
<template>
	<sn-badge :value="0">
		<template #value>
			<sn-icon name="emotion-happy-line" :size="12" color="#FFFFFF"></sn-icon>
		</template>
		<sn-icon name="notification-3-line" :size="26"></sn-icon>
	</sn-badge>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| mode | 徽标显示模式 | BadgeMode | `number` | `number` \| `text` \| `dot` |
| value | 数字模式下徽标的数字值 | Number | `0` | - |
| max | 数字模式下徽标的最大数字值，超过显示 `max+`；`-1` 表示不限制 | Number | `-1` | - |
| text | 文本模式下徽标的文本内容 | String | - | - |
| type | 徽标功能色，背景与文字色自动配套 | BadgeType | `error` | `primary` \| `info` \| `success` \| `warning` \| `error` |
| bgColor | 徽标背景颜色，支持 `$` 功能色简写；取 `type` 对应色 | String | - | - |
| textColor | 徽标文字颜色，支持 `$` 功能色简写；取 `type` 对应文字色 | String | - | - |
| size | 数字/文本模式下控制字号，浮点模式下控制圆点直径；支持 `$` 简写 | String \| Number | - | - |
| showZero | 数字模式下数字为 `0` 时是否显示 | Boolean | `false` | `true` \| `false` |
| show | 是否显示徽标 | Boolean | `true` | `true` \| `false` |
| offset | 徽标偏移量，格式同 css 属性 `transform` | String | - | - |
| alwaysWrap | 是否始终保留外层容器包裹内容；默认隐藏徽标时内容直出（无多余节点），开启后显隐切换带过渡动画 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义徽标样式 | SnStyleValue | - | - |
| textStyle | 徽标内数字/文本的自定义样式 | SnStyleValue | - | - |
| dotStyle | 浮点模式下徽标圆点的自定义样式 | SnStyleValue | - | - |
| containStyle | 包裹内容的外层容器自定义样式 | SnStyleValue | - | - |
| badgeClass | 徽标的外部样式类 | String | - | - |
| textClass | 徽标内数字/文本的外部样式类 | String | - | - |
| containClass | 外层容器的外部样式类 | String | - | - |

## 插槽

| 名称 | 说明 |
| :--- | :--- |
| default | 需要显示徽标的内容，可选；不传时徽标独立使用 |
| value | 完全自定义徽标内部内容，优先级最高 |

<DemoPhone name="sn-badge" />

# Avatar 头像

> [查看 sn-avatar 的 2.0 版本差异](/differences/components/sn-avatar)

## 基础用法

用户头像组件，支持图片、文本与图标三种展示形式。

- 支持方形与圆形外观
- 开启预览后点击图片头像可查看大图
- 可与 `sn-avatar-group` 组合展示，超出数量上限自动显示“+N”

```vue
<template>
	<sn-avatar src="https://www.example.com/example.png" shape="circle" size="60px"></sn-avatar>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| mode | 头像展示模式 | String | `image` | `image` \| `text` \| `icon` |
| src | 图片模式下头像图片地址 | String | `''` | - |
| imageMode | 图片裁剪铺满方式 | String | `aspectFill` | `scaleToFill` \| `aspectFit` \| `aspectFill` \| `widthFix` \| `heightFix` \| `top` \| `bottom` \| `center` \| `left` \| `right` \| `top left` \| `top right` \| `bottom left` \| `bottom right` |
| text | 文本模式下头像内部文本 | String | `''` | - |
| icon | 图标模式下头像内部图标名 | String | `''` | - |
| size | 头像尺寸（外框边长），支持 `$` 前缀按间距乘数缩放 | String \| Number | `40px` | - |
| textSize | 文本模式下内部文本大小，支持 `$` 前缀按字体乘数缩放 | String \| Number | `25px` | - |
| textColor | 文本模式下文本颜色，亮色模式为 `$infoDark`、暗黑模式为 `$dark` | String | - | - |
| iconSize | 图标模式下内部图标大小，支持 `$` 前缀按字体乘数缩放 | String \| Number | `25px` | - |
| iconColor | 图标模式下图标颜色，同 `textColor` 规则 | String | - | - |
| bgColor | 头像背景颜色 | String | `$info` | - |
| shape | 头像形状，`circle` 时圆角强制为尺寸的一半 | String | `square` | `square` \| `circle` |
| borderRadius | 头像圆角大小（仅 `shape="square"` 时生效） | String \| Number | `$4` | - |
| lazyLoad | 图片懒加载（只针对 page 与 scroll-view 下的 image 有效） | Boolean | `false` | `true` \| `false` |
| enablePreview | 图片模式下启用点击预览大图 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 自定义根节点样式类 | String | `''` | - |
| textStyle | 内部文本自定义样式 | SnStyleValue | `''` | - |
| textClass | 内部文本外部样式类 | String | `''` | - |
| iconStyle | 内部图标自定义样式 | SnStyleValue | `''` | - |
| iconClass | 内部图标外部样式类 | String | `''` | - |

## sn-avatar-group 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| data | 头像组数据，数组项字段见下方 `SnAvatarGroupItem` | Array<`SnAvatarGroupItem`> | `[]` | - |
| size | 头像大小，支持 `$` 前缀按间距乘数缩放 | String \| Number | `40px` | - |
| spacing | 头像之间的间距（仅 `mode="spread"` 时生效），支持 `$` 前缀按外间距乘数缩放 | String \| Number | `5px` | - |
| max | 显示的最大头像数量，超过该数量的以 "+N" 形式显示，`-1` 表示不限制 | Number | `-1` | - |
| mode | 头像组布局模式，`heap` 为堆叠（重叠量为头像尺寸的 40%），`spread` 为分散 | String | `heap` | `heap` \| `spread` |
| borderRadius | 头像圆角大小（仅 `shape="square"` 时生效） | String \| Number | `$4` | - |
| textSize | 头像中文本的大小 | String \| Number | `20px` | - |
| iconSize | 头像中图标的大小 | String \| Number | `20px` | - |
| textColor | 头像中文本的颜色，亮色模式为 `$infoDark`、暗黑模式为 `$dark` | String | - | - |
| iconColor | 头像中图标的颜色，同 `textColor` 规则 | String | - | - |
| bgColor | 头像的背景颜色 | String | `$info` | - |
| randomBgColor | 是否随机生成头像背景颜色（从五种功能色 Light 系色板随机取色，文字颜色自动配套） | Boolean | `false` | `true` \| `false` |
| shape | 头像的形状 | String | `circle` | `circle` \| `square` |
| customStyle | 自定义头像组根节点样式 | SnStyleValue | `''` | - |
| avatarStyle | 自定义组内每个头像的样式 | SnStyleValue | `''` | - |
| avatarClass | 自定义组内每个头像的样式类 | String | `''` | - |

> 类型字段：SnAvatarGroupItem（见 https://sinleui.pages.dev/api/types/component#snavatargroupitem）


## 事件

**sn-avatar 事件**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| click | (e: UniPointerEvent) => Void | 点击头像时触发 |
| dbclick | (e: UniPointerEvent) => Void | 快速双击头像时触发（300ms 内连续点击两次） |
| load | (e: UniImageLoadEvent) => Void | 头像图片加载完成时触发 |
| error | (e: UniImageErrorEvent) => Void | 头像图片加载失败时触发 |
| longpress | (e: UniEvent) => Void | 长按头像时触发 |

**sn-avatar-group 事件**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| click | (item: `SnAvatarGroupItem`) => Void | 点击组内头像时触发，携带该头像的数据项 |
| dbclick | (item: `SnAvatarGroupItem`) => Void | 快速双击组内头像时触发，携带该头像的数据项 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 非 `image` 模式（或未传 `src`）下替换内部原有的图标和文字，可以是任意组件 |

<DemoPhone name="sn-avatar" />

# AvatarGroup 头像组

> [查看 sn-avatar-group 的 2.0 版本差异](/differences/components/index)

## 基础用法

将多个头像组合成头像组，用于展示参与者。

- 支持铺排与堆叠两种模式
- 支持自定义样式

```vue
<template>
<sn-avatar-group :data="avatars"></sn-avatar-group>
</template>
```
**更多演示请下载 demo 查看**
## 属性
| 参数            | 说明                                                         | 类型            | 默认值    | 可选值              |
| --------------- | ------------------------------------------------------------ | --------------- | --------- | ------------------- |
| data | 头像组数据 | Array<`SnAvatarGroupItem`> | `[]` | - |
| size | 头像大小 | String | `40px` | - |
| spacing | 头像之间的间距（仅当 `mode="spread"` 时生效） | String | `5px` | - |
| max | 显示的最大头像数量，超过该数量的显示为“N+”，默认为 `-1`（即不限制） | Number | `-1` | - |
| mode | 头像组布局模式，可选 `heap`（堆叠）或 `spread`（分散）。 | String | `heap` | `heap` \| `spread` |
| borderRadius | 头像的圆角大小 | String | `$xsmall` | - |
| textSize | 头像中文本的大小 | String | `20px` | - |
| iconSize | 头像中图标的大小 | String | `20px` | - |
| textColor | 头像中文本的颜色 | String | `$infoDark` （亮色模式）<br />`$dark`（暗黑模式） | - |
| iconColor | 头像中图标的颜色 | String | `$infoDark` （亮色模式）<br />`$dark`（暗黑模式） | - |
| bgColor | 头像的背景颜色 | String | `$info` | - |
| randomBgColor | 是否随机生成头像背景颜色 | Boolean | `false` | `true` \| `false` |
| shape | 头像的形状，可选 `circle`（圆形）或 `square`（方形）。 | String | `circle` | `circle `\| `square` |
| customStyle | 自定义头像组样式 | SnStyleValue | `{}` | - |
| customAvatarStyle | 自定义头像样式 | SnStyleValue | `{}` | - |

> 类型字段：SnAvatarGroupItem（见 https://sinleui.pages.dev/api/types/component#snavatargroupitem）

## 事件
| 名称   | 类型                                                         | 说明               |
| ------ | ------------------------------------------------------------ | ------------------ |
| click  | (item: `SnAvatarGroupItem`) => Void                           | 点击头像时触发     |
| dbclick| (item: `SnAvatarGroupItem`) => Void                           | 双击头像时触发     |

<DemoPhone name="sn-avatar-group" />

# Card 卡片

> [查看 sn-card 的 2.0 版本差异](/differences/components/sn-card)

## 基础用法

通用内容卡片容器，用于收纳展示一组相关信息。

- 支持标题与章节标符，头部 / 尾部区域按内容有无自动显隐
- 提供头部、尾部与操作栏插槽
- 支持自定义边框样式

```vue
<template>
	<sn-card title="卡片标题">
		<sn-text>卡片内容，可以放置文本、图片、表单等任意内容。</sn-text>
	</sn-card>
</template>
```

**更多演示请下载 demo 查看**

## 头像卡片

通过 `avatar-config` 配置卡片头部头像，字段与 sn-avatar 组件属性对齐；也可使用 `avatar` 插槽完全自定义头像内容。

```vue
<template>
	<sn-card title="团队空间" :avatar-config="avatarConfig">
		<sn-text>团队成员 128 人。</sn-text>
	</sn-card>
</template>

<script lang="ts" setup>
import type { SnAvatarConfig } from '@/uni_modules/sinle-ui/core/types/index.ts'

const avatarConfig = {
	mode: 'text',
	text: 'UI',
	shape: 'circle',
	bgColor: '$info'
} as SnAvatarConfig
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| title | 卡片标题 | String | `''` | - |
| titleColor | 卡片标题颜色 | String | `$title` | - |
| titleFont | 卡片标题字体 | String | `''` | - |
| titleSize | 卡片标题字体大小 | String \| Number | `$16` | - |
| titleLines | 卡片标题最大显示行数，超出截断 | Number | `-1` | - |
| avatarConfig | 头像参数配置，字段与 sn-avatar 组件属性对齐 | `SnAvatarConfig` | `{}` | - |
| bgColor | 卡片背景颜色 | String | `$front` | - |
| border | 卡片边框样式，设为 `none` 时去除边框 | String | `1px solid $line` | - |
| boxShadow | 卡片阴影 | String | `''` | - |
| margin | 卡片外边距 | String | `10px 0` | - |
| padding | 卡片内边距 | String \| Number | `$15` | - |
| borderRadius | 卡片圆角大小 | String \| Number | `$12` | - |
| section | 是否显示标题左侧章节标符 | Boolean | `false` | `true` \| `false` |
| sectionColor | 章节标符颜色 | String | `$primary` | - |
| customStyle | 自定义卡片根节点样式 | SnStyleValue | `''` | - |
| titleStyle | 自定义标题文本样式 | SnStyleValue | `''` | - |
| titleClass | 标题文本外部类 | String | `''` | - |
| headerClass | 标题栏外部类 | String | `''` | - |
| headerStyle | 自定义标题栏样式 | SnStyleValue | `''` | - |
| footerClass | 尾部区域外部类 | String | `''` | - |
| footerStyle | 自定义尾部区域样式 | SnStyleValue | `''` | - |
| actionClass | 操作栏外部类 | String | `''` | - |
| actionStyle | 自定义操作栏样式 | SnStyleValue | `''` | - |

> 类型字段：SnAvatarConfig（见 https://sinleui.pages.dev/api/types/component#snavatarconfig）

> 类型字段：SnAvatarShape（见 https://sinleui.pages.dev/api/types/component#snavatarshape）


:::

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 放置卡片主体内容 |
| title | 替换默认的卡片标题文本 |
| avatar | 替换默认头像，可放置头像、LOGO 等 |
| header-extra | 标题栏扩展区域，可放置按钮、徽标等 |
| footer | 放置卡片尾部内容 |
| action | 放置卡片操作栏内容 |

<DemoPhone name="sn-card" />

# PostCard 动态卡片

## 基础用法

用于展示社交动态 / 帖子卡片，常见于动态流与详情页。

- 头部、正文、底部操作栏与评论区均支持数据渲染与插槽替换
- 操作栏与评论区支持数组数据渲染，操作项支持激活态与禁用态
- 头像、昵称、头部、正文、操作按钮、评论用户名与评论文本均有独立点击事件

```vue
<template>
	<sn-post-card :avatar-config="avatarConfig" nickname="林间有风" :datetime="datetime"
		:actions="actions" @action-click="onActionClick">
		<sn-text text="周末去郊外徒步，山顶的风景太治愈了。"></sn-text>
		<template #header-action>
			<sn-icon name="more-line" :size="18" color="$textLight"></sn-icon>
		</template>
	</sn-post-card>
</template>
<script lang="ts" setup>
import type { SnAvatarConfig, SnPostCardAction } from '@/uni_modules/sinle-ui/core/types/index.ts'

const datetime: number = Date.now()
const avatarConfig: SnAvatarConfig = {
	mode: 'text',
	text: '林',
	size: '40px',
	shape: 'circle',
	bgColor: '$primary',
	textColor: '#FFFFFF'
}
const actions: SnPostCardAction[] = [
	{ id: 'like', icon: 'heart-3-line', text: '86', activeIconColor: '$error', activeTextColor: '$error' },
	{ id: 'comment', icon: 'chat-1-line', text: '32' }
]

function onActionClick(action: SnPostCardAction, index: number): void {
	if (action.id == 'like') {
		action.isActive = !(action.isActive ?? false)
		action.icon = action.isActive ? 'heart-3-fill' : 'heart-3-line'
	}
}
</script>
```

**更多演示请下载 demo 查看**

## 评论区

通过 `comments` 数组渲染评论列表，评论项的 `replyTo` 生成「xxx 回复 xxx」结构；`show-more` 显示展开评论按钮。

```vue
<template>
	<sn-post-card :avatar-config="avatarConfig" nickname="林间有风" :datetime="datetime"
		:comments="comments" :show-more="true"
		@comment-user-click="onCommentUserClick" @comment-click="onCommentClick" @more-click="onMoreClick">
		<sn-text text="看到一个填词挑战，也试着填一下。"></sn-text>
	</sn-post-card>
</template>
<script lang="ts" setup>
import type { SnAvatarConfig, SnPostCardComment } from '@/uni_modules/sinle-ui/core/types/index.ts'

const comments: SnPostCardComment[] = [
	{ id: 'c1', user: '聆江', content: '写得很安静，喜欢。' },
	{ id: 'c2', user: '猫屋', content: '喵喵喵？', replyTo: '聆江' }
]
</script>
```

## 插槽自定义

头部（`header`）、头像（`avatar`）、昵称/时间区（`info`）、头部扩展操作区（`header-action`）、底部操作栏（`action`）、评论区（`comment`）均可整体替换。

```vue
<template>
	<sn-post-card>
		<template #avatar>
			<sn-avatar text="A" :size="40" shape="circle" bg-color="$warning" text-color="#FFFFFF"></sn-avatar>
		</template>
		<template #info>
			<sn-text bold font-size="$14" color="$title" text="Aiden"></sn-text>
		</template>
		<template #action>
			<sn-button level="second" text="评论"></sn-button>
			<sn-button level="second" text="转发"></sn-button>
		</template>
		<sn-text text="城市的傍晚自带滤镜，随手一拍就是壁纸。"></sn-text>
	</sn-post-card>
</template>
```

## 属性

**基础**

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| avatarConfig | 头像配置，字段见文末 `SnAvatarConfig`（src/text/icon 均为空时不显示头像） | `SnAvatarConfig` | `{}` | - |
| nickname | 昵称 | String | `''` | - |
| datetime | 时间戳（毫秒），大于 0 时显示 | Number | `0` | - |
| dateFormat | 时间格式化模板 | String | `YYYY-MM-DD HH:mm:ss` | - |

> 类型字段：SnAvatarConfig（见 https://sinleui.pages.dev/api/types/component#snavatarconfig）

> 类型字段：SnAvatarShape（见 https://sinleui.pages.dev/api/types/component#snavatarshape）


:::

**颜色与字号**

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| bgColor | 卡片背景颜色 | String | `$front` | - |
| nicknameColor | 昵称颜色 | String | `$title` | - |
| nicknameSize | 昵称字体大小，支持 `$` 简写 | String \| Number | `$14` | - |
| datetimeColor | 时间文本颜色 | String | `$textLight` | - |
| datetimeSize | 时间字体大小，支持 `$` 简写 | String \| Number | `$11` | - |
| actionColor | 操作按钮默认颜色（图标与文本未单独指定时生效） | String | `$textLight` | - |
| actionSize | 操作文本字体大小，支持 `$` 简写 | String \| Number | `$12` | - |
| actionIconSize | 操作图标大小，支持 `$` 简写 | String \| Number | `$18` | - |
| commentUserColor | 评论用户名颜色 | String | `$primary` | - |
| commentColor | 评论文本颜色 | String | `$text` | - |
| commentSize | 评论字体大小，支持 `$` 简写 | String \| Number | `$14` | - |

**数据**

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| actions | 底部操作项列表，字段见文末 `SnPostCardAction` | `SnPostCardAction`[] | `[]` | - |
| comments | 评论列表，字段见文末 `SnPostCardComment` | `SnPostCardComment`[] | `[]` | - |
| showMore | 是否显示展开评论按钮（评论区无内容且 showMore 为 true 时也会渲染） | Boolean | `false` | `true` \| `false` |
| moreText | 展开评论按钮文本 | String | `查看更多评论` | - |

> 类型字段：SnPostCardAction（见 https://sinleui.pages.dev/api/types/component#snpostcardaction）

> 类型字段：SnPostCardComment（见 https://sinleui.pages.dev/api/types/component#snpostcardcomment）


**样式扩展**

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| customStyle | 根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部样式类（external-class：custom-class） | String | `''` | - |
| headerStyle | 头部区域样式 | SnStyleValue | `''` | - |
| headerClass | 外部样式类 | String | `''` | - |
| infoStyle | 昵称与时间容器样式 | SnStyleValue | `''` | - |
| infoClass | 外部样式类 | String | `''` | - |
| nicknameStyle | 昵称样式 | SnStyleValue | `''` | - |
| nicknameClass | 外部样式类 | String | `''` | - |
| datetimeStyle | 时间样式 | SnStyleValue | `''` | - |
| datetimeClass | 外部样式类 | String | `''` | - |
| contentStyle | 正文区域样式 | SnStyleValue | `''` | - |
| contentClass | 外部样式类 | String | `''` | - |
| actionStyle | 底部操作栏样式 | SnStyleValue | `''` | - |
| actionClass | 外部样式类 | String | `''` | - |
| actionBtnStyle | 操作按钮样式 | SnStyleValue | `''` | - |
| actionBtnClass | 外部样式类 | String | `''` | - |
| commentsStyle | 评论区容器样式 | SnStyleValue | `''` | - |
| commentsClass | 外部样式类 | String | `''` | - |
| commentStyle | 单条评论样式 | SnStyleValue | `''` | - |
| commentClass | 外部样式类 | String | `''` | - |
| moreStyle | 展开评论按钮样式 | SnStyleValue | `''` | - |
| moreClass | 外部样式类 | String | `''` | - |

头部区域在 `nickname`、`datetime`（大于 0）、`avatarConfig` 含 src/text/icon、或 `header`/`avatar`/`info`/`header-action` 插槽任一存在时渲染；正文、操作栏、评论区分别在其数据或插槽存在时渲染。

## 事件

| 名称 | 类型 | 说明 |
| :--- | :--- | :--- |
| avatar-click | (event: UniPointerEvent) => Void | 点击头像时触发 |
| nickname-click | (event: UniPointerEvent) => Void | 点击昵称时触发 |
| header-click | (event: UniPointerEvent) => Void | 点击头部区域时触发 |
| content-click | (event: UniPointerEvent) => Void | 点击正文区域时触发 |
| action-click | (action: `SnPostCardAction`, index: number) => Void | 点击底部操作按钮时触发（禁用项不触发） |
| comment-click | (comment: `SnPostCardComment`, index: number) => Void | 点击评论文本时触发 |
| comment-user-click | (comment: `SnPostCardComment`, name: string) => Void | 点击评论中的用户名或被回复用户名时触发 |
| more-click | () => Void | 点击展开评论按钮时触发 |

## 插槽

| 名称 | 说明 |
| :--- | :--- |
| default | 正文内容 |
| header | 整体替换头部区域（含头像、昵称、时间与扩展操作区） |
| avatar | 自定义头像（替换 avatarConfig 渲染的头像） |
| info | 自定义昵称与时间区域 |
| header-action | 头部右侧扩展操作区（如「更多」按钮） |
| action | 整体替换底部操作栏 |
| comment | 整体替换评论列表（`show-more` 对应的展开按钮仍按需渲染在评论区底部） |

## 类型

> 类型字段：SnPostCardAction（见 https://sinleui.pages.dev/api/types/component#snpostcardaction）

> 类型字段：SnPostCardComment（见 https://sinleui.pages.dev/api/types/component#snpostcardcomment）

> 类型字段：SnAvatarMode（见 https://sinleui.pages.dev/api/types/component#snavatarmode）

> 类型字段：SnAvatarShape（见 https://sinleui.pages.dev/api/types/component#snavatarshape）


<DemoPhone name="sn-post-card" />

# Skeleton 骨架屏

> [查看 sn-skeleton 的 2.0 版本差异](/differences/components/sn-skeleton)

## 基础用法

骨架屏组件，在真实数据加载之前展示页面的大致结构。

- 本身不带 UI，可当作带动画的 `view` 使用，样式完全自定义
- 提供高光带扫过与透明度呼吸两种动画模式

```vue
<template>
	<sn-skeleton width="44px" height="44px" border-radius="$12"></sn-skeleton>
</template>
```

**更多演示请下载 demo 查看**

## 组合出页面结构

多个骨架屏组合即可搭出页面的占位结构，数据加载完成后用 `v-if` 切换为真实内容。

```vue
<template>
	<view class="row">
		<sn-skeleton width="48px" height="48px" border-radius="$24" margin="0 12px 0 0"></sn-skeleton>
		<view class="col">
			<sn-skeleton width="60%" height="16px" border-radius="$4" margin="2px 0"></sn-skeleton>
			<sn-skeleton width="100%" height="14px" border-radius="$4" margin="2px 0"></sn-skeleton>
		</view>
	</view>
</template>
```

## 插槽内容

骨架屏内可放置内容，适合在占位的同时展示提示文字。

```vue
<template>
	<sn-skeleton width="100%" height="56px" border-radius="$12">
		<text>内容加载中，请稍候…</text>
	</sn-skeleton>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| width | 骨架屏宽度 | String \| Number | `100%` | - |
| height | 骨架屏高度 | String \| Number | `20px` | - |
| borderRadius | 骨架屏圆角大小，支持 `$` 简写随圆角乘数缩放 | String \| Number | `$8` | - |
| margin | 骨架屏外边距，支持 `$` 简写随外间距乘数缩放 | String | - | - |
| mode | 动画模式：`glow` 高光带从左到右循环扫过，`pulse` 整块透明度呼吸闪烁 | String | `glow` | `glow` \| `pulse` |
| aniTime | 动画时长，支持 `$` 简写随动画乘数缩放，`0` 关闭动画 | String \| Number | `$1500` | - |
| bgColor | 骨架屏背景色 | String | `$disabled` | - |
| glowColor | 高光带颜色（仅 glow 模式生效），暗色主题为 `rgba(255,255,255,0.05)`、亮色主题为 `rgba(0,0,0,0.03)` | String | - | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 在骨架屏内放置内容 |

<DemoPhone name="sn-skeleton" />

# Tag 标签

> [查看 sn-tag 的 2.0 版本差异](/differences/components/sn-tag)

## 基础用法

标签组件，用于标记和分类。

- 可通过功能色与配色深浅等级组合外观
- 也可直接自定义背景色与文字色，优先级高于主题默认色

```vue
<template>
	<sn-tag text="标签"></sn-tag>
</template>
```

**更多演示请下载 demo 查看**

## 配色等级

`level` 控制标签配色深浅：

- `first`：原色背景 + 对应文字色
- `second`：更浅色（Light）背景
- `third`：中性色（info）背景 + 原色文字
- `least`：透明背景 + 线条色边框 + 原色文字

```vue
<template>
	<sn-tag text="first" type="primary" level="first"></sn-tag>
	<sn-tag text="least" type="primary" level="least"></sn-tag>
</template>
```

## 可关闭与加载

- `closable` 显示关闭按钮，点击后标签移除并触发 `close` 事件。
- `loading` 显示加载指示器，此时关闭按钮隐藏。

```vue
<template>
	<sn-tag text="可关闭标签" closable @close="onClose"></sn-tag>
	<sn-tag text="加载中" loading></sn-tag>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| text | 标签内文本内容 | String | - | - |
| align | 标签内容对齐方向 | String | `center` | `flex-start` \| `center` \| `flex-end` 等 css `justify-content` 取值 |
| type | 标签主题功能色 | String | `info` | `info` \| `primary` \| `success` \| `error` \| `warning` |
| level | 标签配色等级 | String | `first` | `first` \| `second` \| `third` \| `least` |
| loading | 是否加载状态，显示加载指示器并隐藏关闭按钮 | Boolean | `false` | `true` \| `false` |
| closable | 是否可关闭，显示关闭按钮，点击移除标签 | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用，背景与文本切换禁用配色 | Boolean | `false` | `true` \| `false` |
| bgColor | 标签背景颜色，支持 `$` 功能色简写，优先于主题默认色 | String | - | - |
| disabledBgColor | 禁用状态下的背景颜色 | String | `$disabled` | - |
| textColor | 标签文本颜色，支持 `$` 功能色简写，优先于主题默认色 | String | - | - |
| disabledTextColor | 禁用状态下的文本颜色 | String | `$disabledText` | - |
| iconColor | 关闭图标和加载图标颜色，跟随文本颜色 | String | - | - |
| disabledIconColor | 禁用状态下的图标颜色 | String | `$disabledText` | - |
| borderRadius | 标签圆角大小，支持 `$` 简写 | String \| Number | - | - |
| textSize | 标签文本大小，支持 `$` 简写 | String \| Number | - | - |
| iconSize | 关闭图标和加载图标大小，支持 `$` 简写 | String \| Number | - | - |
| loadingStyle | 加载指示器的自定义样式 | SnStyleValue | - | - |
| textStyle | 标签内文本的自定义样式 | SnStyleValue | - | - |
| customStyle | 自定义标签根节点样式 | SnStyleValue | - | - |
| loadingClass | 加载指示器的外部样式类 | String | - | - |
| textClass | 标签内文本的外部样式类 | String | - | - |

## 事件

| 名称 | 类型 | 说明 |
| :--- | :--- | :--- |
| close | () => Void | 点击关闭按钮、标签被移除时触发 |

## 插槽

| 名称 | 说明 |
| :--- | :--- |
| default | 替换标签内部原有的 `text`，可以是任意内容 |

<DemoPhone name="sn-tag" />

# More 查看更多

> [查看 sn-more 的 2.0 版本差异](/differences/components/sn-more)

## 基础用法

可折叠的长内容容器，内容高度超过最小高度时显示「展开查看更多」。

- 点击在收起与展开之间切换，带高度过渡动画
- 收起时内容底部显示与背景色一致的渐变遮罩，提示下方还有内容
- 提示文本、图标、颜色、动画时长与禁用状态均可配置

```vue
<template>
	<sn-more :min-height="80">
		<sn-text>这里是一段可能很长的内容，超过收起高度时会出现展开按钮。</sn-text>
	</sn-more>
</template>
```

**更多演示请下载 demo 查看**

## 自定义文案与图标

`unfold-text` / `fold-text` 自定义展开与收起提示；`icon` 自定义图标时会覆盖默认的上下箭头（默认根据状态切换 `arrow-down-s-line` / `arrow-up-s-line`）。

```vue
<template>
	<sn-more :min-height="80" unfold-text="查看完整描述" fold-text="收起描述" icon="add-line">
		<sn-text>需要折叠的内容。</sn-text>
	</sn-more>
</template>
```

## 自定义颜色与动画

`text-color` / `bg-color` 支持 `$` 简写，背景色同时决定遮罩渐变色；`ani-time` 控制高度过渡动画时长（ms），传 `0` 关闭动画。

```vue
<template>
	<sn-more :min-height="80" text-color="$primary" bg-color="$primaryLight" :ani-time="300">
		<sn-text>需要折叠的内容。</sn-text>
	</sn-more>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| min-height | 收起时的内容区高度，支持 `$` 前缀动态尺寸 | String \| Number | `100px` | - |
| unfold-text | 展开提示文本 | String | `展开查看更多` | - |
| fold-text | 收起提示文本 | String | `收起` | - |
| icon | 自定义图标名称，会覆盖默认展开/收起时的上下箭头图标 | String | `''` | - |
| text-size | 提示文本大小，支持 `$` 前缀动态尺寸 | String \| Number | `''` | - |
| text-color | 提示文本颜色，支持 `$` 简写 | String | `''` | - |
| bg-color | 内容区背景颜色（同时决定收起遮罩渐变色），支持 `$` 简写 | String | `''` | - |
| disabled | 是否禁用展开/收起操作，文本与图标显示禁用色 | Boolean | `false` | `true` \| `false` |
| ani-time | 高度过渡动画时长（ms），支持 `$` 前缀动态时长，传 `0` 关闭动画 | String \| Number | `$300` | - |
| content-style | 内容区（含遮罩）外部样式 | SnStyleValue | `''` | - |
| content-class | 内容区外部样式类 | String | `''` | - |
| wrap-style | 内容包裹层外部样式 | SnStyleValue | `''` | - |
| wrap-class | 内容包裹层外部样式类 | String | `''` | - |
| fold-text-style | 展开/收起提示文本外部样式 | SnStyleValue | `''` | - |
| fold-text-class | 展开/收起提示文本外部样式类 | String | `''` | - |
| custom-style | 自定义根节点样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| fold | () => Void | 收起时触发 |
| unfold | () => Void | 展开时触发 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 折叠区域的内容，内容高度超过 min-height 时出现展开/收起按钮 |

<DemoPhone name="sn-more" />

# Loading 加载

> [查看 sn-loading 的 2.0 版本差异](/differences/components/sn-loading)

## 基础用法

加载中状态指示组件。

- 提供原生加载组件与旋转图标两种模式，前者 GPU 加速渲染，不受主线程繁忙影响
- 图标与文本默认水平排列，也可改为垂直排列

```vue
<template>
	<sn-loading mode="icon" text="加载中..."></sn-loading>
</template>
```

**更多演示请下载 demo 查看**

## 更换图标

`icon` 模式下可通过 `icon` 属性自由更换旋转图标。

```vue
<template>
	<sn-loading mode="icon" icon="loader-2-line"></sn-loading>
	<sn-loading mode="icon" icon="refresh-line"></sn-loading>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| mode | 加载模式 | String | `native` | `native` \| `icon` |
| text | 加载文本内容，为空时不显示 | String | - | - |
| icon | icon 模式下的图标名称 | String | `loader-4-line` | - |
| iconColor | 加载图标颜色 | String | `$primary` | - |
| iconSize | 加载图标大小 | String \| Number | `$24` | - |
| textColor | 文本颜色 | String | `$primaryDark` | - |
| textSize | 文本字体大小 | String \| Number | `$16` | - |
| vertical | 图标与文本是否垂直排列 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| customClass | 自定义根节点外部样式类 | String | - | - |
| loadingStyle | 自定义加载指示器节点内联样式 | SnStyleValue | - | - |
| loadingClass | 自定义加载指示器节点外部样式类 | String | - | - |
| textStyle | 自定义文本节点内联样式 | SnStyleValue | - | - |
| textClass | 自定义文本节点外部样式类 | String | - | - |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 替换默认的加载文本内容 |

<DemoPhone name="sn-loading" />

# Progress 进度条

> [查看 sn-progress 的 2.0 版本差异](/differences/components/sn-progress)

## 基础用法

进度条组件，用于显示一个任务或过程的进度。

- 进度值支持双向绑定，超出 0 ~ 100 范围自动夹紧
- 颜色、高度、圆角与动画时长可配置
- 支持加载中状态：激活条固定为 40% 轨道宽并循环平移，适合处理中 / 未知进度场景

```vue
<template>
	<sn-progress v-model="value"></sn-progress>
</template>

<script setup>
	const value = ref<number>(30)
</script>
```

**更多演示请下载 demo 查看**

## 进度值文本

`show-value-text` 显示百分比文本，`value-text-position` 切换文本在进度条内部或外部。

```vue
<template>
	<sn-progress v-model="value" show-value-text></sn-progress>
	<sn-progress v-model="value" show-value-text value-text-position="inside" height="22px"></sn-progress>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定进度值，范围 0 ~ 100（超出自动夹紧） | Number | `0` | - |
| showValueText | 是否显示进度值文本 | Boolean | `false` | `true` \| `false` |
| valueTextPosition | 进度值文本位置 | String | `outside` | `inside` \| `outside` |
| valueTextSize | 进度值文本字体大小，外部为 14px × 字体乘数、内部取进度条高度 × 0.6（最小 9px） | String \| Number | - | - |
| valueTextWidth | 外部进度值文本宽度 | String \| Number | `40px` | - |
| height | 进度条高度 | String \| Number | `6px` | - |
| bgColor | 轨道（未激活部分）颜色 | String | `$line` | - |
| activeColor | 激活部分颜色 | String | `$primary` | - |
| textColor | 进度值文本颜色，内部为 `#fff`、外部为主题文本色 | String | - | - |
| borderRadius | 进度条圆角大小，取高度一半（胶囊形） | String \| Number | - | - |
| aniTime | 进度变化动画时长，支持 `$` 简写随动画乘数缩放 | String \| Number | - | - |
| loading | 加载中状态：激活条固定为 40% 轨道宽并循环平移 | Boolean | `false` | `true` \| `false` |
| activeMode | 进度更新动画方式：`forwards` 从当前位置继续补间，`backwards` 每次更新从 0 重新播放 | String | `forwards` | `forwards` \| `backwards` |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| containStyle | 自定义外层容器节点内联样式 | SnStyleValue | - | - |
| activeStyle | 自定义激活条节点内联样式 | SnStyleValue | - | - |
| activeClass | 自定义激活条节点外部样式类 | String | - | - |
| textStyle | 自定义进度值文本内联样式（inside / outside 均生效） | SnStyleValue | - | - |
| textClass | 自定义进度值文本外部样式类（仅 outside 位置生效） | String | - | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: Number) => Void | 进度值变化时触发，参数为夹紧到 0 ~ 100 后的值 |

<DemoPhone name="sn-progress" />

# Dateformat 日期格式化

> [查看 sn-dateformat 的 2.0 版本差异](/differences/components/sn-dateformat)

## 基础用法

时间格式化组件，将时间戳格式化为指定格式的日期字符串或相对时间。

- 相对时间支持实时刷新与固定计算两种模式
- 支持中文与英文两种本地化文案

```vue
<script setup lang="ts">
	const date = Date.now()
</script>
<template>
	<sn-dateformat :date="date"></sn-dateformat>
</template>
```

**更多演示请下载 demo 查看**

## 相对时间与阈值

组件会对与当前时间较近的日期做友好转化，`threshold`（单位 ms）用于控制转化阈值。将传入时间与当前时间差的绝对值记为 delta（以默认阈值 `[60000, 86400000]` 为例）：

- `delta < 60000` 时，过去的时间显示为"刚刚"，未来的时间显示为"马上"（`en` 下为 "just now" / "right away"）
- `60000 <= delta < 86400000` 时，显示为"N秒前|N秒后"、"N分钟前|N分钟后"、"N小时前|N小时后"、"N天前|N天后"、"N个月前|N个月后"、"N年前|N年后"（`en` 下为 "N minutes ago|later" 等）
- `delta >= 86400000` 时，按 `format` 参数传入的格式进行格式化输出

如果不想转化为"马上|刚刚"，可以传入 `:threshold="[0, 86400000]"`；传入空数组则使用默认阈值。

固定模式（`mode="fixed"`）下相对时间仅在 `date` 等值变化时计算，适合列表等静态展示场景；实时模式（`mode="realtime"`）默认开启，每秒自动刷新。

## 日期格式

`format` 支持以下占位符（星期、月份名称随 `locale` 变化）：

| 占位符 | 示例 | 描述 |
| :--- | :--- | :--- |
| `YYYY` | 2001 | 四位数的年份 |
| `YY` | 01 | 两位数的年份 |
| `MMMM` | January | 月份名称 |
| `MM` | 01-12 | 月份，两位数 |
| `M` | 1-12 | 月份，从 1 开始计数 |
| `DD` | 01 | 一个月的某一天，两位数 |
| `D` | 1-31 | 一个月的某一天 |
| `dddd` | Monday | 星期全称 |
| `ddd` | Mon | 星期缩写 |
| `dd` | Mo | 星期简写 |
| `d` | 0-6 | 星期数（周日为 0） |
| `HH` | 00-23 | 小时数（24 小时制），两位数 |
| `H` | 0-23 | 小时数（24 小时制） |
| `hh` | 01-12 | 小时数（12 小时制），两位数 |
| `h` | 1-12 | 小时数（12 小时制） |
| `mm` | 00-59 | 分钟数，两位数 |
| `m` | 0-59 | 分钟数 |
| `ss` | 00-59 | 秒数，两位数 |
| `s` | 0-59 | 秒数 |
| `SSS` | 000-999 | 毫秒数，三位数 |
| `A` | AM PM | 上午或下午，大写 |
| `a` | am pm | 上午或下午，小写 |
| `Z` | -05:00 | 相对于 UTC 的偏移量 |

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| date | 需要格式化的时间戳（单位 ms） | Number | `Date.now()` | - |
| format | 日期格式，占位符见上方"日期格式" | String | `YYYY-MM-DD HH:mm:ss` | - |
| threshold | 相对时间阈值（单位 ms），第一个值为"刚刚/马上"阈值，第二个值为格式化阈值 | Number[] | `[60000, 86400000]` | - |
| mode | 显示模式：`realtime` 每秒实时刷新相对时间，`fixed` 仅在值变化时计算 | String | `realtime` | `fixed` \| `realtime` |
| locale | 本地化语言 | String | `zh-cn` | `zh-cn` \| `en` |
| textColor | 文本颜色，支持 `$` 主题色简写 | String | `$text` | - |
| textSize | 文本字体大小，支持 `$` 动态尺寸 | String \| Number | `$14` | - |
| textFont | 文本字体 | String | `''` | - |
| customClass | 根节点（即文本节点）外部样式类 | String | `''` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |
| textClass | 文本外部样式类 | String | `''` | - |
| textStyle | 文本自定义样式 | SnStyleValue | `''` | - |

<DemoPhone name="sn-dateformat" />

# Empty 缺省页

> [查看 sn-empty 的 2.0 版本差异](/differences/components/sn-empty)

## 基础用法

缺省页组件，在页面异常、无内容或加载状态时给出友好提示。

- 内置 20 种缺省插图模式，插图以内联 SVG 渲染
- 插图主题色可自由定制
- 提供插图、提示文本与操作区三个插槽

```vue
<template>
	<sn-empty mode="data" text="Oops! 数据丢失了"></sn-empty>
</template>
```

**更多演示请下载 demo 查看**

## 多模式

目前共支持 20 种模式。

| 模式 | 名称 | 模式 | 名称 |
| --- | --- | --- | --- |
| schedule | 日程 | loading | 加载中 |
| card | 卡包 | message | 消息 |
| favor | 收藏 | star | 喜爱 |
| coupon | 优惠券 | permission | 权限 |
| data | 数据 | record | 记录 |
| location | 位置 | search | 搜索 |
| fail | 载入失败 | server | 服务器 |
| folder | 文件夹 | shopping | 购物车 |
| page1 | 页面丢失1 | network | 无网络 |
| page2 | 页面丢失2 | slow | 网速缓慢 |

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| mode | 缺省页模式 | String | `data` | 见上方多模式表 |
| text | 缺省页提示文本 | String | `''` | - |
| textSize | 提示文本字体大小，支持 `$` 前缀按字体乘数缩放 | String \| Number | `$14` | - |
| textColor | 提示文本颜色 | String | `$lineText` | - |
| themeColor | 缺省插图主题色 | String | `$primary` | - |
| hairColor | 缺省插图人物头发颜色 | String | `#483029` | - |
| clothesColor | 缺省插图人物上衣颜色 | String | `#EDA20C` | - |
| trousersColor | 缺省插图人物裤子颜色，同 `themeColor` | String | - | - |
| shoesColor | 缺省插图人物鞋子颜色，同 `themeColor` | String | - | - |
| itemColor | 缺省插图物品颜色 | String | `#483029` | - |
| skinColor | 缺省插图人物皮肤颜色 | String | `#ffcda5` | - |
| elementColor | 缺省插图元素颜色 | String | `#ffffff` | - |
| imageSize | 缺省插图尺寸，支持 `$` 前缀按间距乘数缩放 | String \| Number | `200px` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| textStyle | 提示文本自定义样式 | SnStyleValue | `''` | - |
| textClass | 提示文本外部样式类 | String | `''` | - |

## 插槽

| 名称 | 说明 |
| --- | --- |
| image | 替换默认缺省插图 |
| text | 替换默认提示文本 |
| action | 操作区，可放置按钮等操作组件 |

<DemoPhone name="sn-empty" />

# HighlightText 高亮文本

## 基础用法

高亮文本组件，将文本中匹配关键词的片段以主题主色高亮，常用于搜索结果与关键词标注。

- 关键词支持字符串、字符串数组（优先匹配较长者）与正则表达式
- 默认按字面量转义正则字符、不区分大小写；点击高亮片段派发事件
- 提供与 `sn-text` 一致的预设样式，可限制行数并支持长按选中

```vue
<template>
	<sn-highlight-text text="SinleUI 是面向 uni-app x 的轻量 UI 框架" keywords="uni-app x"></sn-highlight-text>
</template>
```

**更多演示请下载 demo 查看**

## 搜索场景

搜索词实时驱动正文高亮，配合 sn-search 使用。

```vue
<template>
	<sn-search v-model="keyword" placeholder="输入关键词"></sn-search>
	<sn-highlight-text :text="content" :keywords="keyword"></sn-highlight-text>
</template>

<script lang="ts" setup>
const keyword = ref<string>('组件')
const content = ref<string>('SinleUI 提供统一的组件样式、主题能力和跨平台交互。')
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| text | 文本内容 | String | `''` | - |
| keywords | 高亮关键词，支持单个关键词、关键词数组或正则表达式 | String \| String[] \| RegExp | `''` | - |
| autoEscape | 是否自动转义关键词中的正则特殊字符（按字面量匹配） | Boolean | `true` | `true` \| `false` |
| caseSensitive | 是否区分大小写 | Boolean | `false` | `true` \| `false` |
| type | 预设文字样式类型，决定默认字号与颜色 | String | `text` | `title` \| `text` \| `text-light` \| `primary` \| `info` \| `success` \| `warning` \| `error` |
| fontSize | 文本字号，按 `type` 取默认字号（title 为 16、其余为 14）并乘字体乘数 | String \| Number | - | - |
| color | 文本颜色，按 `type` 取对应主题色 | String | - | - |
| bold | 是否加粗（font-weight: 600） | Boolean | `false` | `true` \| `false` |
| lines | 最大显示行数，`0` 不限制 | Number | `0` | - |
| selectable | 文本是否可选中（蒸汽模式） | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部类 | String | `''` | - |
| textStyle | 自定义普通文本片段样式 | SnStyleValue | `''` | - |
| textClass | 普通文本片段外部类 | String | `''` | - |
| highlightStyle | 自定义高亮片段样式 | SnStyleValue | `''` | - |
| highlightClass | 高亮片段外部类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| highlight-click | (detail: HighlightClickDetail) => Void | 点击高亮片段时触发。detail 包含：`text`（片段文本）、`index`（第几个高亮片段，从 0 开始）、`start` / `end`（在原文中的起止位置） |

<DemoPhone name="sn-highlight-text" />

# Ellipsis 文本省略

## 基础用法

多行文本省略组件，内容超出行数限制时自动截断并显示省略号。

- 自动计算可容纳的字符数，支持在尾部 / 头部 / 中间省略
- 支持自定义省略符号与最大显示行数
- 可开启展开 / 收起操作按钮（禁用后置灰不可点击），也支持默认插槽放置富文本

```vue
<template>
	<sn-ellipsis :content="longText" :rows="2" expand-text="展开" collapse-text="收起"
		@expand="onExpand" @collapse="onCollapse"></sn-ellipsis>
</template>

<script lang="ts" setup>
const longText = 'SinleUI 提供统一的组件样式、主题能力和跨平台交互。'
function onExpand(): void {
	console.log('已展开')
}
function onCollapse(): void {
	console.log('已收起')
}
</script>
```

**更多演示请下载 demo 查看**

## 自定义操作按钮

使用 `expand` / `collapse` 插槽可完全自定义展开与收起按钮；使用默认插槽可放置富文本并做截断预览。

```vue
<template>
	<sn-ellipsis :rows="2" :content="longText">
		<template #expand>
			<sn-icon name="arrow-down-s-line" :size="14"></sn-icon>
			<sn-text font-size="$13" color="$primary">查看全部</sn-text>
		</template>
		<template #collapse>
			<sn-icon name="arrow-up-s-line" :size="14"></sn-icon>
			<sn-text font-size="$13" color="$primary">收起</sn-text>
		</template>
	</sn-ellipsis>
</template>

<script lang="ts" setup>
const longText = '支持 48dB 混合主动降噪，通透模式智能过滤环境噪音。'
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| content | 文本内容 | String | `''` | - |
| rows | 最大显示行数 | String \| Number | `1` | - |
| dots | 省略符号 | String | `…` | - |
| position | 省略位置 | String | `end` | `end` \| `start` \| `middle` |
| expandText | 展开按钮文字，设置后内容被截断时显示展开按钮 | String | `''` | - |
| collapseText | 收起按钮文字，依次跟随 `expandText`、`收起` | String | - | - |
| showCollapse | 展开后是否显示收起按钮 | Boolean | `true` | `true` \| `false` |
| fontSize | 文本字号 | String \| Number | `$14` | - |
| lineHeight | 行高：Number 小于 100 时按字号倍数、大于等于 100 时按 px 处理；String 支持 `$14`（乘字体乘数）、`22px`、`1.6`（字号倍数）；字号的 1.6 倍 | String \| Number | - | - |
| color | 文本颜色 | String | `$text` | - |
| actionColor | 操作按钮颜色；禁用时为禁用文本色 | String | `$primary` | - |
| selectable | 文本是否可选中（蒸汽模式） | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用操作按钮 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部类 | String | `''` | - |
| textStyle | 自定义文本样式 | SnStyleValue | `''` | - |
| textClass | 文本外部类 | String | `''` | - |
| actionStyle | 自定义操作按钮样式 | SnStyleValue | `''` | - |
| actionClass | 操作按钮外部类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| expand | () => Void | 点击操作按钮展开内容时触发 |
| collapse | () => Void | 点击操作按钮收起内容时触发 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 自定义文本内容（可为富文本），此时截断以高度方式呈现、操作按钮显示在内容下方 |
| expand | 替换展开操作按钮 |
| collapse | 替换收起操作按钮 |

<DemoPhone name="sn-ellipsis" />

# Watermark 水印

## 基础用法

在页面或卡片内容上方平铺一层倾斜重复的水印文本。

- 水印层不拦截点击事件，内部按钮、开关等可正常操作
- 水印内容支持换行实现多行，字号、行距、列距、旋转角度与透明度均可调
- 组件根节点为相对定位容器，水印层绝对定位铺满最上层

```vue
<template>
	<sn-watermark content="SinleUI" custom-style="border-radius:16px;">
		<view>
			<sn-text text="内容区示例"></sn-text>
		</view>
	</sn-watermark>
</template>
```

**更多演示请下载 demo 查看**

## 进阶用法

### 多行水印

`content` 中使用换行符即可生成多行水印。

```vue
<template>
	<sn-watermark :content="'机密文件\n请勿外传'" color="rgba(239, 68, 68)" :font-size="16" :rotate="0">
		<view>
			<sn-text text="内部资料"></sn-text>
		</view>
	</sn-watermark>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| content | 水印文本内容，支持 `\n` 换行 | String | `SinleUI` | - |
| color | 水印文字颜色 | String | `rgba(0, 0, 0)` | - |
| fontSize | 水印字号，数字单位为 px，支持 `$` 动态尺寸语法 | String \| Number | `$24` | - |
| letterSpacing | 水印文字字间距，数字单位为 px | String \| Number | `2` | - |
| lineHeight | 水印文字行高，数字单位为 px，最小取字号大小，支持 `$` 动态尺寸语法 | String \| Number | `$24` | - |
| rowGap | 水印行间距，数字单位为 px，支持 `$` 动态尺寸语法 | String \| Number | `$80` | - |
| colGap | 水印列间距，数字单位为 px，支持 `$` 动态尺寸语法 | String \| Number | `$100` | - |
| rotate | 水印旋转角度（deg），范围 -90 ~ 90，超范围自动截断 | Number | `-30` | `-90 ~ 90` |
| opacity | 水印整体透明度（0-1） | Number | `0.2` | `0 ~ 1` |
| minHeight | 容器最小高度，数字单位为 px，为空时不设置 | String \| Number | `''` | - |
| contentStyle | 自定义内容区样式 | SnStyleValue | `''` | - |
| layerStyle | 自定义水印层样式 | SnStyleValue | `''` | - |
| textStyle | 自定义水印文字样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部样式类 | String | `''` | - |
| contentClass | 内容区外部样式类 | String | `''` | - |
| layerClass | 水印层外部样式类 | String | `''` | - |
| textClass | 水印文字外部样式类 | String | `''` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 被水印覆盖的内容 |
| content | 同默认插槽一样渲染在内容区，可作为多节点内容的补充插槽 |

<DemoPhone name="sn-watermark" />

# Alert 警告信息

> [查看 sn-alert 的 2.0 版本差异](/differences/components/sn-alert)

## 基础用法

页面内的重要提示信息条，用于展示警告、成功等状态提示。

- 内置五种功能色主题与浅色 / 深色两种显示效果
- 支持自定义图标，未指定时按类型自动匹配
- 支持文字居中与可关闭

```vue
<template>
	<sn-alert text="这是一条警告信息。"></sn-alert>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| text | 警告信息文本内容（未提供默认插槽内容时显示） | String | `''` | - |
| icon | 左侧图标名，按 `type` 自动选择默认图标 | String | - | - |
| type | 警告信息主题样式类型 | String | `info` | `info` \| `primary` \| `success` \| `error` \| `warning` |
| effect | 显示效果，`light` 为浅色，`dark` 为深色 | String | `light` | `light` \| `dark` |
| bgColor | 背景颜色，按 `type` 与 `effect` 取主题色（light 取 `{type}Light`，dark 取 `{type}`） | String | - | - |
| textColor | 文本颜色，按 `type` 与 `effect` 取主题配对色（`info` 类型取 `$text`） | String | - | - |
| textSize | 文本大小，支持 `$` 前缀按字体乘数缩放 | String \| Number | `$14` | - |
| iconColor | 图标颜色，同 `textColor` | String | - | - |
| iconSize | 图标大小，支持 `$` 前缀按字体乘数缩放 | String \| Number | `$16` | - |
| borderRadius | 圆角大小，支持 `$` 前缀按圆角乘数缩放 | String \| Number | `$8` | - |
| showIcon | 是否显示图标 | Boolean | `true` | `true` \| `false` |
| center | 文字是否居中显示 | Boolean | `false` | `true` \| `false` |
| closable | 是否显示关闭按钮，点击后组件隐藏并触发 `close` 事件 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| textClass | 文本外部样式类 | String | `''` | - |
| textStyle | 文本自定义样式 | SnStyleValue | `''` | - |
| iconClass | 图标外部样式类 | String | `''` | - |
| iconStyle | 图标自定义样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| close | () => Void | 点击关闭按钮时触发（组件随即自行隐藏，如需重新显示可通过 `v-if` 控制组件重建） |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 替换警告信息原有的文本内容，可以是任意组件 |
| icon | 替换左侧默认图标 |
| close | 替换右侧默认关闭按钮图标 |

<DemoPhone name="sn-alert" />

# Amount 金额

## 基础用法

金额格式化展示组件，将数值拆分为货币符号、整数与小数三部分渲染。

- 三部分可分别控制字号与颜色，支持语义配色与可选中复制
- 支持千分位分隔、中文大写金额与四种舍入模式
- 舍入基于字符串精确计算，避免浮点精度误差

```vue
<template>
	<sn-amount :value="123456.789" currency="¥"></sn-amount>
</template>
```

**更多演示请下载 demo 查看**

## 舍入模式与小数位

`rounding-mode` 四种规则：`round` 四舍五入、`ceil` 进一法（向正无穷）、`floor` 退一法（向负无穷）、`trunc` 截断法（向零）；`decimals` 控制保留位数，不足自动补 0。

```vue
<template>
	<sn-amount :value="'1.005'" currency="¥" :decimals="2" rounding-mode="round"></sn-amount>
	<sn-amount :value="'-1.005'" currency="¥" :decimals="2" rounding-mode="ceil"></sn-amount>
	<sn-amount :value="'1234.56789'" currency="$" :decimals="4"></sn-amount>
</template>
```

## 中文大写金额

`to-upper` 显示中文大写金额，支持负数与万亿级数值；此时可配合 `type`、`bold` 等统一控制样式。

```vue
<template>
	<sn-amount :value="12345.67" :to-upper="true" type="primary"></sn-amount>
	<sn-amount :value="'-12345678901234.56'" :decimals="2" :to-upper="true"></sn-amount>
</template>
```

## 分部分样式

`currency-font-size` / `int-font-size` / `decimal-font-size` 与 `currency-color` / `int-color` / `decimal-color` 分别控制三部分字号与颜色（优先于 `font-size` / `color`），也可用对应的外部样式类定制。

```vue
<template>
	<sn-amount :value="'88888.66'" currency="¥"
		currency-font-size="14px" currency-color="$textLight"
		int-font-size="28px" int-color="$primary"
		decimal-font-size="14px" decimal-color="$textLight" bold></sn-amount>
</template>
```

## 实现原理

舍入基于字符串精确计算（不经过浮点 `toFixed`），避免浮点精度误差；中文大写金额符合央行票据规范。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| value | 金额值，支持 Number 或字符串（字符串可含货币符号、千分位分隔符，解析时自动去除） | String \| Number | `0` | - |
| currency | 货币符号，为空时不显示 | String | `''` | - |
| decimals | 保留小数位数，`0` 表示不显示小数部分 | Number | `2` | - |
| rounding-mode | 舍入模式 | String | `round` | `round` \| `ceil` \| `floor` \| `trunc` |
| separator | 整数千分位分隔符，传空字符串不分割 | String | `,` | - |
| separator-digits | 千分位分隔位数 | Number | `3` | - |
| to-upper | 是否显示中文大写金额 | Boolean | `false` | `true` \| `false` |
| type | 语义配色类型（与 sn-text 一致），可被 `color` 覆盖 | String | `text` | `title` \| `text` \| `text-light` \| `primary` \| `info` \| `success` \| `warning` \| `error` |
| font-size | 统一字号，支持 `$` 前缀动态尺寸；由 `type` 决定（title 为 `$16`、其余 `$14`） | String \| Number | - | - |
| currency-font-size | 货币符号字号，优先于 font-size | String \| Number | `''` | - |
| int-font-size | 整数部分字号，优先于 font-size | String \| Number | `''` | - |
| decimal-font-size | 小数部分（含小数点）字号，优先于 font-size | String \| Number | `''` | - |
| color | 统一文字颜色，支持 `$` 简写 | String | `''` | - |
| currency-color | 货币符号颜色，优先于 color | String | `''` | - |
| int-color | 整数部分颜色，优先于 color | String | `''` | - |
| decimal-color | 小数部分颜色，优先于 color | String | `''` | - |
| bold | 是否加粗（字重 600） | Boolean | `false` | `true` \| `false` |
| lines | 最大行数，`0` 表示不限制，超出部分省略 | Number | `0` | - |
| selectable | 是否可长按选中复制 | Boolean | `false` | `true` \| `false` |
| currency-style | 货币符号外部样式 | SnStyleValue | `''` | - |
| currency-class | 货币符号外部样式类 | String | `''` | - |
| int-style | 整数部分外部样式 | SnStyleValue | `''` | - |
| int-class | 整数部分外部样式类 | String | `''` | - |
| decimal-style | 小数部分外部样式 | SnStyleValue | `''` | - |
| decimal-class | 小数部分外部样式类 | String | `''` | - |
| text-class | 大写金额文本外部样式类（to-upper 为 true 时作用） | String | `''` | - |
| custom-style | 自定义根节点样式 | SnStyleValue | `''` | - |
| custom-class | 根节点外部样式类 | String | `''` | - |

<DemoPhone name="sn-amount" />

# NoticeBar 通知栏

> [查看 sn-notice-bar 的 2.0 版本差异](/differences/components/sn-notice-bar)

## 基础用法

通知栏组件，用于展示通知信息。

- 支持滚动与轮播两种模式，轮播支持横向与纵向步进
- 整体配色随主题，可通过外部样式覆盖
- 可显示关闭按钮，点击后隐藏并派发事件

```vue
<template>
	<sn-notice-bar :texts="['这是第一条通知', '这是第二条通知']"></sn-notice-bar>
</template>
```

**更多演示请下载 demo 查看**

## 轮播模式

`mode="swiper"` 时逐条轮播通知，`vertical` 可切换为纵向步进。

```vue
<template>
	<sn-notice-bar mode="swiper" vertical :texts="['纵向轮播第一条', '纵向轮播第二条', '纵向轮播第三条']"></sn-notice-bar>
</template>
```

## 自定义样式

通过 `custom-style` 控制根节点，`text-style` / `icon-style` 定制文本与图标。

```vue
<template>
	<sn-notice-bar :texts="['自定义背景与圆角的通知栏']" icon="notification-3-line"
		custom-style="background-color: var(--sn-info-light); border-radius: 12px;"
		text-style="color: var(--sn-info-dark); font-size: 13px;" icon-style="color: var(--sn-info);"></sn-notice-bar>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| texts | 通知文本数组 | `Array<String>` | `[]` | - |
| icon | 通知图标名称，传空字符串不显示图标 | String | `volume-up-line` | - |
| speed | 滚动速度（px/s），支持数字或带 px 的字符串，仅 scroll 模式生效 | String \| Number | `50` | - |
| mode | 显示模式，`vertical` 为 `true` 时强制为 `swiper` | String | `scroll` | `scroll` \| `swiper` |
| swiper-interval | 轮播间隔时间（ms），仅 swiper 模式生效 | Number | `2000` | - |
| vertical | 是否纵向步进（仅 swiper 模式生效） | Boolean | `false` | `true` \| `false` |
| closable | 是否显示关闭按钮，点击后通知栏隐藏并触发 close 事件 | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用（scroll 模式不滚动，swiper 模式不自动轮播） | Boolean | `false` | `true` \| `false` |
| padding | 上下内边距（px），与文本高度共同决定通知栏高度 | Number | `10` | - |
| custom-style | 自定义通知栏根节点样式 | SnStyleValue | `''` | - |
| text-style | 自定义通知文本样式 | SnStyleValue | `''` | - |
| text-class | 通知文本外部样式类 | String | `''` | - |
| icon-style | 自定义通知图标样式 | SnStyleValue | `''` | - |
| icon-class | 通知图标外部样式类 | String | `''` | - |
| close-style | 自定义关闭按钮样式 | SnStyleValue | `''` | - |
| close-class | 关闭按钮外部样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| close | () => Void | 点击关闭按钮、通知栏关闭时触发 |

<DemoPhone name="sn-notice-bar" />

# Table 表格

## 基础用法

表格组件，由表格容器、行与单元格三部分配合组成。

- 行 `sn-tr` 必须位于 `sn-table` 内，单元格 `sn-td` 必须位于行内
- 单元格宽度不带单位时按比例分配剩余宽度，带单位时为固定宽度
- 支持单元格边框与行下边框并可自定义颜色；在单元格内嵌套行可实现多级表头

::: danger HarmonyOS 端 flatten 限制
在 HarmonyOS 端，表格行、单元格以及单元格内文字不要同时使用 `flatten`，否则嵌套文字可能无法绘制；Demo 中各层均保留独立节点。
:::

```vue
<template>
	<sn-table>
		<sn-tr>
			<sn-td width="2"><text>ID</text></sn-td>
			<sn-td width="2"><text>姓名</text></sn-td>
			<sn-td width="3"><text>城市</text></sn-td>
		</sn-tr>
		<sn-tr>
			<sn-td width="2"><text>1</text></sn-td>
			<sn-td width="2"><text>张三</text></sn-td>
			<sn-td width="3"><text>广州</text></sn-td>
		</sn-tr>
	</sn-table>
</template>
```

**更多演示请下载 demo 查看**

## 固定表头与固定列

设置 `height` 后表格进入可滚动模式：表头通过 `#head` 插槽声明并固定在顶部，表体纵向滚动（滚动到底部会触发 `scrolltolower`，可用于加载更多）。

在表头和表体对应的 `sn-td` 上设置 `fixed` 或 `fixed="left"` 可固定左列，设置 `fixed="right"` 可固定右列。横向滚动时，固定列保持在表格可视区域的左右两侧，中间列与表头同步滚动；同侧有多列时按声明顺序排列。

固定列应为表头和表体设置相同的明确宽度，例如 `width="90px"`。宽度已包含单元格内边距与边框；固定单元格会铺满所在行的高度。

::: danger 固定列节点
固定列及其定位容器不要使用 `flatten`，以保留定位与层级。
:::

```vue
<template>
	<sn-table height="240px" underline @scrolltolower="onLoadMore">
		<template #head>
			<sn-tr>
				<sn-td fixed width="90px"><text>ID</text></sn-td>
				<sn-td width="110px"><text>姓名</text></sn-td>
				<sn-td fixed="right" width="90px"><text>操作</text></sn-td>
			</sn-tr>
		</template>
		<sn-tr v-for="item in rows" :key="item.id">
			<sn-td fixed width="90px"><text>{{ item.id }}</text></sn-td>
			<sn-td width="110px"><text>{{ item.name }}</text></sn-td>
			<sn-td fixed="right" width="90px"><text>编辑</text></sn-td>
		</sn-tr>
	</sn-table>
</template>
```

## 属性

以下属性属于 **sn-table**：

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| bordered | 是否显示单元格边框 | Boolean | `false` | `true` \| `false` |
| underline | 是否显示行下边框（`bordered` 为 true 时以内边框为准） | Boolean | `false` | `true` \| `false` |
| height | 表格高度；设置后启用固定表头与纵向滚动模式 | String \| Number | `''` | - |
| borderColor | 边框颜色，支持 `$` 简写 | String | `$line` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |
| customClass | 根节点自定义样式类 | String | `''` | - |

## 事件

以下事件属于 **sn-table**（仅设置 `height` 进入可滚动模式后才会触发）：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| scroll | (ev: UniScrollEvent) => Void | 表格滚动时触发（含横向与纵向滚动） |
| scrolltoupper | (ev: UniScrollToUpperEvent) => Void | 纵向滚动到顶部时触发 |
| scrolltolower | (ev: UniScrollToLowerEvent) => Void | 纵向滚动到底部时触发，常用于加载更多 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 表体内容，放置 sn-tr |
| head | 表头内容，放置 sn-tr；仅在设置 `height`（可滚动模式）时渲染并固定在顶部 |

## sn-tr 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| customStyle | 行自定义样式 | SnStyleValue | `''` | - |
| customClass | 行自定义样式类 | String | `''` | - |

sn-tr 的默认插槽用于放置 sn-td；位于 `#head` 插槽中的第一级行会自动添加表头背景色。

## sn-td 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| width | 单元格宽度：Number 按 px；纯数字字符串（如 `"2"`）按比例分配剩余宽度；带单位字符串（如 `"90px"`）为固定宽度；百分比字符串按百分比；自动均分剩余宽度 | String \| Number | - | - |
| fixed | 是否固定列：`true` 或 `"left"` 固定在左侧，`"right"` 固定在右侧；仅设置 `height`（可滚动模式）时生效 | Boolean \| String | `false` | `true` \| `false` \| `left` \| `right` |
| customStyle | 单元格自定义样式 | SnStyleValue | `''` | - |
| customClass | 单元格自定义样式类 | String | `''` | - |

sn-td 的默认插槽用于放置单元格内容。

# Result 结果页

> [查看 sn-result 的 2.0 版本差异](/differences/components/sn-result)

## 基础用法

结果页组件，用于展示成功、失败、警告等操作结果。

- 提供五种结果类型，默认图标与图标颜色随类型自动匹配
- 支持通过插槽自定义图标、标题、文本与操作区

```vue
<template>
	<sn-result mode="success" title="支付成功" text="订单号：SN20260806001"></sn-result>
</template>
```

**更多演示请下载 demo 查看**

## 自定义图标

使用 `icon` 插槽可完全替换默认图标；若仅调整默认图标的大小与颜色，直接使用 `icon-size`、`icon-color` 属性即可。

```vue
<template>
	<sn-result mode="success" title="订单已完成" text="配送员正在派送中">
		<template #icon>
			<sn-icon name="truck-line" :size="34" color="#ffffff"></sn-icon>
		</template>
	</sn-result>
</template>
```

## 操作区

使用 `action` 插槽在结果页底部放置后续操作按钮。

```vue
<template>
	<sn-result mode="success" title="支付成功" text="¥ 128.00">
		<template #action>
			<sn-button text="返回首页" @click="backHome"></sn-button>
			<sn-button text="查看订单" level="second" @click="viewOrder"></sn-button>
		</template>
	</sn-result>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| mode | 结果页类型，决定默认图标与图标颜色 | String | `info` | `info` \| `primary` \| `success` \| `warning` \| `error` |
| title | 标题文本 | String | - | - |
| titleSize | 标题字体大小 | String \| Number | `$18` | - |
| titleColor | 标题颜色 | String | `$text` | - |
| text | 文本内容 | String | - | - |
| textSize | 文本字体大小 | String \| Number | `$14` | - |
| textColor | 文本颜色 | String | `$textLight` | - |
| iconSize | 图标大小 | String \| Number | `$56` | - |
| iconColor | 图标颜色，随 mode 使用对应功能色 | String | - | - |
| titleStyle | 自定义标题节点内联样式 | SnStyleValue | - | - |
| titleClass | 自定义标题节点外部样式类 | String | - | - |
| textStyle | 自定义文本节点内联样式 | SnStyleValue | - | - |
| textClass | 自定义文本节点外部样式类 | String | - | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |

## 插槽

| 名称 | 说明 |
| --- | --- |
| icon | 替换结果图标 |
| title | 替换结果标题 |
| text | 替换结果文本 |
| action | 放置操作按钮等后续操作内容 |

<DemoPhone name="sn-result" />

# Popup 弹出层

> [查看 sn-popup 的 2.0 版本差异](/differences/components/sn-popup)

## 基础用法

通用弹出层容器，只负责遮罩、显隐与动画，内容完全由插槽自定义。

- 内置五个弹出方向的默认动画，并可为打开与关闭分别提供自定义动画
- 遮罩与内容独立分层，遮罩拦截点击穿透与滚动
- 不提供内置 UI 模板，需要模板化弹层可选用 Drawer、Modal 等组件

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下（页面根节点或 `sn-page` 的直接子节点），否则页面的 `--sn-*`、`--ani-time-*` 变量不生效，颜色与动画异常。
:::

```vue
<template>
	<sn-page>
		<sn-button text="打开弹层" type="primary" @click="open"></sn-button>
		<sn-popup ref="popupEle" position="bottom">
			<view class="content">
				<sn-text text="底部弹层内容"></sn-text>
			</view>
		</sn-popup>
	</sn-page>
</template>
```

**更多演示请下载 demo 查看**

## 实现原理

弹层在首次打开后保留节点，通过 `visibility` 与 CSS 过渡完成显隐切换，默认动画不会逐次重建节点。

默认动画在透明准备阶段被关闭打断时，会立即隐藏弹层并释放层级，已过期的异步回调不会重新打开弹层。

每个弹层预留遮罩与内容两个层级，后打开弹层的遮罩高于已打开弹层的内容。遮罩阻止点击、触摸移动冒泡及默认滚动，Web 端同时阻止遮罩上的滚轮滚动；内容只阻止点击与触摸移动冒泡，不禁止内部滚动。

## 注意事项

弹层内使用 `scroll-view` 展示可变数量的内容时，按内容自然高度排布并设置最大高度；不要为短列表设置 `flex: 1`，否则会撑出无法点击遮罩的空白滚动区域。

## 自定义动画

`openAnimation` / `closeAnimation` 分别接管对应方向的默认动画，函数签名为 `(overlay: UniElement | null, content: UniElement | null, duration: number) => void`。组件不会获取回调内部创建的动画实例，因此回调需要自行保存并取消上一条动画。入场过程中 `close` 会立即调用关闭回调；关闭回调应先读取当前变换和透明度，再取消上一条动画，以当前样式作为退场首帧，不能把起点固定为 `scale(1)` 或 `opacity: 1`。

Android 的 `animate` 仅支持 `fill: 'forwards'`。为避免首帧显示终态再跳回起点，需要先通过 `customStyle` 或 `style.setProperty` 设置与入场首帧一致的样式，再创建动画；动画结束后取消动画并直写终态，释放 `fill: forwards` 对后续样式的覆盖。demo 的四种自定义动画均按此流程管理实例，页面卸载时取消剩余动画。

全屏根容器使用固定定位，随组件初始化创建并保留，不随打开操作条件挂载；内部通过 `template v-if` 延迟渲染遮罩和内容，避免 Android 多实例排障中观察到的动态 fixed 根 View 未附着窗口的路径。根容器不设置动画透明度；默认遮罩和内容使用绝对定位，在其内部独立动画，避免遮罩隐藏状态影响内容。居中弹层默认按内容实际宽高定位，动画函数可直接使用 `scale`、`rotate` 或 `translate`；在 `customStyle` 中明确传入 `position` 定位时，由开发者提供所需的 `top` / `left` / `right` / `bottom`。

各端内置入退场动画通过内容节点的位移/缩放与透明度过渡、遮罩淡入淡出实现；五种位置均按内容实际尺寸定位，顶部/底部仅占内容宽度，左右侧仅占内容高度，空白区域点击由遮罩处理。默认动画首次打开与隐藏后重开均经过透明准备阶段：恢复根容器可见，等待有效容器尺寸，再测量内容、设置定位偏移，并在布局提交后启动入场；不能只凭隐藏节点保留的 `offsetWidth` / `offsetHeight` 判定布局已就绪。关闭动画完成前两者保持挂载，默认动画关闭后仅隐藏节点。自定义动画在定位稳定后先建立动画再显示节点；自定义动画如需对内容淡入淡出，应直接在回调中操作 `content` 的透明度。

下方仅展示入场关键帧；包含动画实例清理和半程关闭衔接的完整用法见 popup demo。

```vue
<template>
	<sn-popup ref="popupEle" :ani-time="500" :open-animation="bounceOpenAnim" custom-style="transform: scale(0.6); opacity: 1;">
		<view class="content">
			<sn-text text="弹跳进入"></sn-text>
		</view>
	</sn-popup>
</template>

<script lang="ts" setup>
const bounceOpenAnim = (overlay: UniElement | null, content: UniElement | null, duration: number): void => {
	if (overlay != null) {
		overlay.animate(
			[{ opacity: '0' } as UniAnimationKeyframe, { opacity: '1' } as UniAnimationKeyframe],
			{ duration: duration, easing: 'ease-out', fill: 'forwards' }
		)
	}
	if (content != null) {
		content.animate(
			[
				{ transform: 'scale(0.6)' } as UniAnimationKeyframe,
				{ transform: 'scale(1.08)' } as UniAnimationKeyframe,
				{ transform: 'scale(1)' } as UniAnimationKeyframe
			],
			{ duration: duration, easing: 'ease-out', fill: 'forwards' }
		)
	}
}
</script>
```

## 显隐诊断

当前 popup demo 带有用于定位 Android 多实例显隐问题的临时诊断日志，前缀为 `[sn-popup-diagnostic]`，统一经过框架 logger 输出。日志仅在 `pages/components/sn-popup` 页面且 `$snui.logging` 开启时采集；不修改弹层显隐、动画或层级行为。

日志记录实例 id、生命周期阶段、逻辑显隐、准备状态、层级栈与灰度配置，并在入场启动、入场完成和关闭完成后的 64ms 采样根容器、遮罩、内容及祖先节点的实际样式和位置尺寸；定位样式包括 `top` / `left` / `right` / `bottom`、`margin-left` / `margin-top`。`prepare-visible` 标记透明准备阶段。同步的打开阶段只记录状态，不主动测量节点，降低诊断对首次渲染时序的影响。页面卸载时清理采样定时器。

复现时保留两组日志：重新进入页面后首先打开目标弹层的正常日志，以及先打开关闭基础弹层，再打开自定义遮罩或嵌套弹层的异常日志。异常弹层打开后等待至少一秒再关闭，以保留 `afterenter-next-frame` 的节点采样。问题定位后应移除这组临时诊断。

Android 在 `afterenter-next-frame` 和 `afterleave-next-frame` 额外通过 `sinle-api` 的临时 `capturePopupNativeViewInfo` 接口采集实际原生 View。结果按 `native depth=N` 逐层输出，包含 `isAttachedToWindow`、`isShown`、原生 `visibility/alpha`、屏幕坐标、全局可见矩形、父链和裁剪配置；原生坐标为物理像素，不可直接与 UniElement 日志的逻辑像素比较。`status=no-native-view` 表示未获取到原生节点；只有原生挂载及父链结果才能进一步判断是否为节点脱离窗口、父容器隐藏或裁剪。采样只读，不改变 UI。

本轮 Android 异常日志中，根 View 的 `isAttachedToWindow=false`、`windowTokenIsNull=true`、`parentIndex=-1`，而内容在该根 View 内的位置正常，说明整棵弹层原生子树未附着窗口，不能把屏幕坐标 `(0,0)` 直接判为定位失效。常驻根容器改动仍需复测确认：打开后根 View 应附着窗口、拥有父链，且 `isShown=true`；正确的 CSS 样式与尺寸不能替代挂载状态检查。

原生诊断修改包含 Kotlin 混编，需由开发者重新运行 Android 项目完成联编。该接口仅供临时排障，不作为稳定业务 API，问题验证后应与临时日志一并移除。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| position | 弹出位置，弹出动画随位置变化 | String | `center` | `center` \| `top` \| `bottom` \| `left` \| `right` |
| renderMode | 内部遮罩与内容的渲染方式，`v-if` 为首次打开时挂载，`v-show` 为初始即挂载仅切换显隐；固定根容器始终常驻 | String | `v-if` | `v-if` \| `v-show` |
| aniTime | 动画时长（ms），支持 `$` 前缀按动画乘数缩放，`0` 关闭动画 | String \| Number | `$long` | `$long` \| `$normal` \| `$short` \| 数值 |
| preventBack | 是否阻止返回键关闭弹出层 | Boolean | `false` | `true` \| `false` |
| maskClose | 点击遮罩是否关闭弹出层 | Boolean | `true` | `true` \| `false` |
| maskOpacity | 遮罩透明度 | Number | `0.4` | - |
| zIndex | 弹出层基础层级；打开时按栈内已有弹层自动抬升，内容层级为实际遮罩层级加 1 | Number | `999` | - |
| overlayStyle | 自定义遮罩层样式，后置覆盖默认遮罩样式 | SnStyleValue | `''` | - |
| customClass | 遮罩层外部样式类 | String | `''` | - |
| customStyle | 自定义内容容器样式 | SnStyleValue | `''` | - |
| openAnimation | 自定义打开动画函数，传入后接管默认打开动画 | Function \| null | `null` | - |
| closeAnimation | 自定义关闭动画函数，传入后接管默认关闭动画 | Function \| null | `null` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| clickoverlay | () => Void | 点击遮罩时触发 |
| beforeenter | () => Void | 打开动画开始前触发 |
| enter | () => Void | 打开动画开始时触发 |
| afterenter | () => Void | 打开动画结束后触发 |
| beforeleave | () => Void | 关闭动画开始前触发 |
| leave | () => Void | 关闭动画开始时触发 |
| afterleave | () => Void | 关闭动画结束后触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 打开弹出层；默认动画退场中立即反向入场，自定义动画退场中在收尾后重开 |
| close | - | - | 关闭弹出层；入场期间立即启动退场，自定义动画的当前帧衔接由关闭回调负责 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 弹出层内容 |

<DemoPhone name="sn-popup" />

# Modal 模态框

> [查看 sn-modal 的 2.0 版本差异](/differences/components/sn-modal)

## 基础用法

自带完整 UI 模板的模态对话框：标题 + 内容 + 确定 / 取消按钮。

- 内容区内置滚动，超过窗口高度 80% 时自动限高滚动
- 通过组件方法控制显隐，按钮点击后自动关闭并派发对应事件

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下使用，否则主题颜色与动画时长等 CSS 变量无法作用到组件内部。
:::

::: tip 建议直接使用 API
推荐使用 [snu.showModal](/libs/utils/ui#snu-showmodal)：无需在页面放置组件或绑定 `ref`，配置字段与组件 props 一致，结果经 `success` 返回。组件与 API 的唯一差异是组件支持 `header` / `content` / `actions` 三个插槽，不需要插槽定制时推荐使用 API。
:::

::: info 内部间距随乘数缩放
标题 / 内容区的内边距随 `paddingFactor`、按钮区外边距随 `marginFactor` 缩放，无需额外配置。
:::

```typescript
snu.showModal({
	title: '提示',
	content: '确定执行此操作吗？',
	success: (confirm, cancel) => {}
})
```


```vue
<template>
	<sn-modal ref="modalEle" title="提示" content="确定执行此操作吗？" @confirm="onConfirm" @cancel="onCancel"></sn-modal>
</template>
```

**更多演示请下载 demo 查看**

## 自定义动画

`openAnimation` / `closeAnimation` 传入函数后完全接管默认动画，函数签名为 `(mask: UniElement | null, content: UniElement | null, duration: number) => void`：`mask` 为遮罩节点，`content` 为模态框节点，`duration` 为本次动画时长（ms）。

```vue
<template>
	<sn-modal ref="modalEle" title="弹跳进入" :open-animation="bounceOpenAnim"></sn-modal>
</template>

<script lang="ts" setup>
	const bounceOpenAnim = (mask: UniElement | null, content: UniElement | null, duration: number): void => {
		if (mask != null) {
			mask.animate(
				[{ opacity: '0' } as UniAnimationKeyframe, { opacity: '1' } as UniAnimationKeyframe],
				{ duration: duration, easing: 'ease-out', fill: 'forwards' }
			)
		}
		if (content != null) {
			content.animate(
				[
					{ transform: 'scale(0.6)' } as UniAnimationKeyframe,
					{ transform: 'scale(1.08)' } as UniAnimationKeyframe,
					{ transform: 'scale(1)' } as UniAnimationKeyframe
				],
				{ duration: duration, easing: 'ease-out', fill: 'forwards' }
			)
		}
	}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| title | 模态框标题 | String | `''` | - |
| titleAlign | 标题对齐方式 | String | `center` | `left` \| `center` \| `right` |
| titleSize | 标题字体大小 | String \| Number | `$17` | - |
| titleFont | 标题字体 | String | `''` | - |
| titleColor | 标题颜色，支持 `$` 简写主题色 | String | `$title` | - |
| bgColor | 模态框背景颜色，支持 `$` 简写主题色 | String | `$front` | - |
| borderRadius | 模态框圆角大小 | String \| Number | `$12` | - |
| content | 模态框内容 | String | `''` | - |
| contentAlign | 内容对齐方式 | String | `center` | `left` \| `center` \| `right` |
| contentSize | 内容字体大小 | String \| Number | `$15` | - |
| contentColor | 内容颜色，支持 `$` 简写主题色 | String | `$text` | - |
| contentFont | 内容字体 | String | `''` | - |
| buttonType | 按钮类型，`embed` 为底部嵌入式文字按钮，`float` 为浮动式 sn-button 并排展示 | String | `embed` | `embed` \| `float` |
| buttonBorder | 嵌入式按钮分隔边框样式，颜色支持 `$` 简写主题色 | String | `0.5px solid $line` | - |
| confirmText | 确定按钮文本 | String | `确定` | - |
| confirmTextColor | 确定按钮文本颜色，支持 `$` 简写主题色 | String | `$primaryDark` | - |
| confirmTextSize | 确定按钮文本大小 | String \| Number | `$16` | - |
| showCancel | 是否显示取消按钮 | Boolean | `true` | `true` \| `false` |
| showConfirm | 是否显示确定按钮 | Boolean | `true` | `true` \| `false` |
| cancelText | 取消按钮文本 | String | `取消` | - |
| cancelTextColor | 取消按钮文本颜色，支持 `$` 简写主题色 | String | `$text` | - |
| cancelTextSize | 取消按钮文本大小 | String \| Number | `$16` | - |
| position | 弹出位置，弹出动画随位置变化 | String | `center` | `center` \| `top` \| `bottom` \| `left` \| `right` |
| aniTime | 动画时长（ms），支持 `$` 前缀按动画乘数缩放 | String \| Number | `$long` | `$long` \| `$normal` \| `$short` \| 数值 |
| maskClose | 点击遮罩是否关闭模态框 | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用操作按钮，禁用后点击无效且颜色变为禁用色 | Boolean | `false` | `true` \| `false` |
| preventBack | 是否阻止返回键关闭模态框 | Boolean | `false` | `true` \| `false` |
| maskOpacity | 遮罩透明度 | Number | `0.4` | - |
| openAnimation | 自定义打开动画函数，传入后接管默认打开动画 | Function \| null | `null` | - |
| closeAnimation | 自定义关闭动画函数，传入后接管默认关闭动画 | Function \| null | `null` | - |
| customStyle | 自定义模态框主体样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| open | () => Void | 打开时触发 |
| close | () => Void | 关闭时触发 |
| clickMask | () => Void | 点击遮罩时触发 |
| confirm | () => Void | 点击确定按钮时触发，触发后自动关闭模态框 |
| cancel | () => Void | 点击取消按钮时触发，触发后自动关闭模态框 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 打开模态框 |
| close | - | - | 关闭模态框（不触发 confirm / cancel 事件） |
| confirm | - | - | 相当于点击确定按钮：触发 confirm 事件并关闭模态框（禁用状态下无效） |
| cancel | - | - | 相当于点击取消按钮：触发 cancel 事件并关闭模态框（禁用状态下无效） |

## 插槽

| 名称 | 说明 |
| --- | --- |
| header | 替换标题区域 |
| content | 替换内容区域 |
| actions | 替换操作按钮区域 |

<DemoPhone name="sn-modal" />

# Overlay 遮罩层

> [查看 sn-overlay 的 2.0 版本差异](/differences/components/sn-overlay)

## 基础用法

全屏遮罩层，用于强调特定元素或拦截页面交互，常与弹出层、模态框搭配使用。

- 遮罩内插槽可放置任意内容
- 点击遮罩区域默认关闭
- 通过组件方法控制显隐，层级固定

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下使用，否则主题颜色与动画时长等 CSS 变量无法作用到组件内部。
:::

```vue
<template>
	<sn-page>
		<sn-button text="打开遮罩" type="primary" @click="open"></sn-button>
		<sn-overlay ref="overlayEle">
			<view class="content">
				<sn-text text="遮罩内容"></sn-text>
			</view>
		</sn-overlay>
	</sn-page>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| maskClose | 点击遮罩区域是否关闭遮罩层 | Boolean | `true` | `true` \| `false` |
| opacity | 遮罩层透明度 | Number | `0.4` | - |
| aniTime | 动画时长（ms），支持 `$` 前缀按动画乘数缩放，`0` 时瞬时显隐 | String \| Number | `$long` | `$long` \| `$normal` \| `$short` \| 数值 |
| bgColor | 遮罩背景颜色，支持 `$` 简写主题色 | String | `#000` | - |
| customStyle | 自定义遮罩根节点样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| open | () => Void | 打开时触发 |
| close | () => Void | 关闭时触发 |
| click-mask | () => Void | 点击遮罩区域时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 打开遮罩层 |
| close | - | - | 关闭遮罩层 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 遮罩层内容 |

<DemoPhone name="sn-overlay" />

# Toast 轻提示

> [查看 sn-toast 的 2.0 版本差异](/differences/components/sn-toast)

## 基础用法

轻提示（吐司），默认居中显示、2 秒后自动消失，可配置图标、加载状态与显示位置。

- 通过组件方法显示与关闭：可按组件配置显示，也可传入参数临时覆盖配置
- 默认不拦截手势，提示期间仍可操作页面；开启遮罩后可防穿透
- 加载状态下不自动关闭，需手动关闭

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下使用，否则主题颜色与动画时长等 CSS 变量无法作用到组件内部。
:::

::: tip 建议直接使用 API
推荐使用 [snu.showToast](/libs/utils/ui#snu-showtoast)：无需在页面放置组件或绑定 `ref`，任意位置可直接调用（`snu.hideToast()` 关闭），配置字段与组件 props 一致（组件的 `overlay` 对应 API 的 `passThrough`，默认均为不拦截手势）。组件本身不提供插槽，需先放置到页面再通过 `ref` 调用。
:::

```typescript
snu.showToast({ text: '保存成功', icon: 'success' })

snu.showToast({
	text: '加载中...',
	loading: true,
	duration: 3000
})
```


```vue
<template>
	<sn-page>
		<sn-button text="显示轻提示" type="primary" @click="show"></sn-button>
		<sn-toast ref="toastEle" text="这是一个提示信息"></sn-toast>
	</sn-page>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| text | 提示文本内容 | String | `''` | - |
| bgColor | 轻提示背景颜色，支持 `$` 简写主题色 | String | `$toast` | - |
| overlay | 是否显示透明遮罩（防穿透），开启后提示期间拦截底部页面点击 | Boolean | `false` | `true` \| `false` |
| position | 轻提示位置 | String | `center` | `top` \| `center` \| `bottom` |
| duration | 轻提示显示时长（ms），`loading` 为 true 时不自动关闭 | Number | `2000` | - |
| textSize | 提示文本字体大小 | String \| Number | `$14` | - |
| textColor | 提示文本颜色，支持 `$` 简写主题色 | String | `#fff` | - |
| borderRadius | 轻提示圆角大小 | String \| Number | `$12` | - |
| padding | 轻提示内边距，支持 `$` 前缀按间距乘数缩放 | String | `12px 15px` | - |
| icon | 提示图标名称（sn-icon 图标名） | String | `''` | - |
| iconSize | 图标大小 | String \| Number | `$20` | - |
| iconColor | 图标颜色，支持 `$` 简写主题色（`loading` 圈的描边色同样取此颜色） | String | `#fff` | - |
| textAlign | 文本对齐方式 | String | `center` | `left` \| `center` \| `right` |
| loading | 是否显示加载中图标（旋转 loading 圈） | Boolean | `false` | `true` \| `false` |
| textLines | 文本最大行数，超长自动换行，`0` 不限制 | Number | `0` | - |
| customStyle | 自定义轻提示内容块样式 | SnStyleValue | `''` | - |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| show | - | - | 按组件 props 配置显示轻提示 |
| configShow | param: `SnToastParams` \| null | - | 按传入参数显示轻提示，参数缺省字段回退组件 props 配置，无需改动属性 |
| close | - | - | 关闭轻提示（`loading` 状态下必须通过此方法关闭） |

> 类型字段：SnToastParams（见 https://sinleui.pages.dev/api/types/component#sntoastparams）


<DemoPhone name="sn-toast" />

# Message 消息条

## 基础用法

全局消息条组件，在页面顶部 / 底部弹出轻量消息提示，支持多条消息依次排列成队列并自动消失。

- 通过实例方法弹出与关闭消息，可关闭单条或全部
- 提供五种功能色类型与三种深浅等级，默认图标随类型自动匹配
- 支持六个方向的队列位置、关闭按钮、相同消息自动合并计数与自动关闭时长

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下使用，否则主题颜色与动画时长等 CSS 变量无法作用到组件内部。
:::

::: info 平台差异
HarmonyOS 端消息条默认阴影较轻。
:::

```vue
<template>
	<sn-page>
		<sn-button text="显示消息" type="primary" @click="showMessage"></sn-button>
		<sn-message ref="messageRef"></sn-message>
	</sn-page>
</template>

<script lang="ts" setup>
import type { SnMessageParams } from '@/uni_modules/sinle-ui/core/types/index.ts'

const messageRef = ref<SnMessageComponentPublicInstance | null>(null)

function showMessage(): void {
	messageRef.value?.$callMethod('show', {
		text: '这是一条消息提示',
		type: 'success'
	} as SnMessageParams)
}
</script>
```

**更多演示请下载 demo 查看**

## 消息合并与手动关闭

```vue
<template>
	<sn-message ref="messageRef" @close="onMessageClose"></sn-message>
</template>

<script lang="ts" setup>
import type { SnMessageParams } from '@/uni_modules/sinle-ui/core/types/index.ts'

const messageRef = ref<SnMessageComponentPublicInstance | null>(null)
let msgId = ''

function show(): void {
	msgId = messageRef.value?.$callMethod('show', {
		text: '这条消息可通过 close(id) 提前关闭',
		type: 'primary',
		closable: true,
		duration: 30000
	} as SnMessageParams) as string
}

function close(): void {
	messageRef.value?.$callMethod('close', msgId)
}

function onMessageClose(): void {
	console.log('有一条消息被关闭')
}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| text | 默认消息文字 | String | `''` | - |
| type | 消息类型（功能色） | String | `info` | `info` \| `primary` \| `success` \| `error` \| `warning` |
| level | 消息配色等级 | String | `first` | `first` \| `second` \| `third` |
| position | 消息队列整体位置 | String | `top` | `top-left` \| `top` \| `top-right` \| `bottom-left` \| `bottom` \| `bottom-right` |
| duration | 自动关闭时长（ms），`0` 表示不自动关闭 | Number | `3000` | - |
| showIcon | 是否显示类型图标 | Boolean | `true` | `true` \| `false` |
| icon | 自定义图标名称，按 `type` 使用默认图标 | String | - | - |
| closable | 是否显示右侧关闭按钮 | Boolean | `false` | `true` \| `false` |
| grouping | 是否开启消息合并，相同内容自动合并计数 | Boolean | `false` | `true` \| `false` |
| bgColor | 消息条背景颜色，支持 `$` 简写，按 `type` 与 `level` 取主题色 | String | - | - |
| textColor | 消息文字颜色，支持 `$` 简写，按 `type` 与 `level` 取主题色 | String | - | - |
| iconColor | 图标颜色，支持 `$` 简写，跟随文字颜色 | String | - | - |
| textSize | 消息文字大小，支持 `$` 简写 | String \| Number | `$14` | - |
| borderRadius | 消息条圆角大小，支持 `$` 简写 | String \| Number | `$8` | - |
| customStyle | 自定义消息条样式 | SnStyleValue | `''` | - |
| customClass | 消息条外部类 | String | `''` | - |
| textStyle | 自定义消息文字样式 | SnStyleValue | `''` | - |
| textClass | 消息文字外部类 | String | `''` | - |
| iconStyle | 自定义图标样式 | SnStyleValue | `''` | - |
| iconClass | 图标外部类 | String | `''` | - |
| closeStyle | 自定义关闭按钮样式 | SnStyleValue | `''` | - |
| closeClass | 关闭按钮外部类 | String | `''` | - |
| badgeStyle | 自定义合并计数徽标样式 | SnStyleValue | `''` | - |
| badgeClass | 合并计数徽标外部类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| close | () => Void | 有一条消息被关闭（移除）时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| show | param: `SnMessageParams` \| null | String | 弹出一条消息，参数字段优先于组件属性默认值，返回消息 `id` |
| close | id: String（默认 `''`） | - | 关闭消息；传入 `id` 时仅关闭对应消息，留空时关闭全部消息 |

> 类型字段：SnMessageParams（见 https://sinleui.pages.dev/api/types/component#snmessageparams）


## show 参数（SnMessageParams）

| 字段 | 说明 | 类型 |
| --- | --- | --- |
| text | 消息文字 | String \| null |
| type | 消息类型 | `SnMessageType` \| null |
| level | 配色等级 | `SnMessageLevel` \| null |
| position | 弹出位置 | `SnMessagePosition` \| null |
| duration | 自动关闭时长（ms） | Number \| null |
| showIcon | 是否显示类型图标 | Boolean \| null |
| icon | 自定义图标名称 | String \| null |
| closable | 是否显示关闭按钮 | Boolean \| null |
| grouping | 是否开启消息合并 | Boolean \| null |
| bgColor | 背景颜色 | String \| null |
| textColor | 文字颜色 | String \| null |
| iconColor | 图标颜色 | String \| null |
| textSize | 文字大小 | String \| null |
| borderRadius | 圆角大小 | String \| null |
| customStyle | 自定义消息条样式 | SnStyleValue \| null |

> 类型字段：SnMessageType（见 https://sinleui.pages.dev/api/types/component#snmessagetype）

> 类型字段：SnMessageLevel（见 https://sinleui.pages.dev/api/types/component#snmessagelevel）

> 类型字段：SnMessagePosition（见 https://sinleui.pages.dev/api/types/component#snmessageposition）


<DemoPhone name="sn-message" />

# Notification 通知

## 基础用法

全局通知组件，从页面顶部或底部弹出带标题与内容的通知卡片，适合订单状态、系统消息等重要提醒。

- 通知以队列形式堆叠，弹出位置可选页面顶部或底部
- 支持自动关闭、剩余时间进度条、关闭按钮与相同通知合并计数
- 支持手势拖动关闭，可关闭单条通知或一次清空全部

::: danger 必须放在 sn-page 下
弹出层类组件需直接放在 `sn-page` 根节点下使用，否则主题颜色与动画时长等 CSS 变量无法作用到组件内部。
:::

::: info 平台差异
HarmonyOS 端通知卡片默认阴影较轻。
:::

```vue
<template>
	<sn-page>
		<sn-button text="显示通知" type="primary" @click="showNotice"></sn-button>
		<sn-notification ref="notificationRef"></sn-notification>
	</sn-page>
</template>

<script lang="ts" setup>
import type { SnNotificationParams } from '@/uni_modules/sinle-ui/core/types/index.ts'

const notificationRef = ref<SnNotificationComponentPublicInstance | null>(null)

function showNotice(): void {
	notificationRef.value?.$callMethod('show', {
		title: '订单支付成功',
		content: '您的订单已支付成功，预计 3 天内发货。',
		type: 'success'
	} as SnNotificationParams)
}
</script>
```

**更多演示请下载 demo 查看**

## 操作插槽与手动关闭

在 `show()` 参数中设置 `showAction: true` 时显示右侧操作插槽，插槽作用域暴露当前通知 `id`。

```vue
<template>
	<sn-notification ref="notificationRef">
		<template v-slot:action="slotProps">
			<sn-button type="primary" level="least" text="复制" @click="onCopy(slotProps.id)"></sn-button>
		</template>
	</sn-notification>
</template>

<script lang="ts" setup>
import type { SnNotificationParams } from '@/uni_modules/sinle-ui/core/types/index.ts'

const notificationRef = ref<SnNotificationComponentPublicInstance | null>(null)

function show(): void {
	notificationRef.value?.$callMethod('show', {
		title: '订单待支付',
		content: '订单号 SN20260101001，请尽快完成支付。',
		type: 'warning',
		duration: 10000,
		showAction: true
	} as SnNotificationParams)
}

function onCopy(id: string): void {
	uni.setClipboardData({ data: '订单号 SN20260101001' })
	notificationRef.value?.$callMethod('close', id)
}
</script>
```

## 拖动关闭

开启 `draggable` 后按住通知左右拖动可跟手移动，松手未达阈值时回弹；拖动期间自动关闭计时暂停，Web 端同时支持鼠标拖拽。

## 实现原理

卡片图标位于按 `type` 与 `level` 着色的圆角色块中，默认图标随类型自动匹配；配色等级与 sn-button 的 type / level 体系一致。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| title | 默认通知标题 | String | `''` | - |
| content | 默认通知内容 | String | `''` | - |
| type | 通知类型（功能色） | String | `info` | `info` \| `primary` \| `success` \| `error` \| `warning` |
| level | 通知配色等级 | String | `first` | `first` \| `second` \| `third` |
| position | 通知队列整体位置 | String | `top` | `top` \| `bottom` |
| duration | 自动关闭时长（ms），`0` 表示不自动关闭 | Number | `4500` | - |
| showProgress | 是否显示卡片底部剩余时间进度条 | Boolean | `false` | `true` \| `false` |
| showIcon | 是否显示类型图标 | Boolean | `true` | `true` \| `false` |
| icon | 自定义图标名称，按 `type` 使用默认图标 | String | - | - |
| closable | 是否显示右侧关闭按钮 | Boolean | `false` | `true` \| `false` |
| grouping | 是否开启通知合并，相同标题 + 内容自动合并计数 | Boolean | `false` | `true` \| `false` |
| bgColor | 通知卡片背景颜色，支持 `$` 简写 | String | `$front` | - |
| titleColor | 标题颜色，支持 `$` 简写 | String | `$title` | - |
| contentColor | 内容颜色，支持 `$` 简写 | String | `$text` | - |
| iconColor | 图标颜色，支持 `$` 简写，按 `type` 与 `level` 取主题色 | String | - | - |
| titleSize | 标题字号，支持 `$` 简写 | String \| Number | `$15` | - |
| contentSize | 内容字号，支持 `$` 简写 | String \| Number | `$13` | - |
| borderRadius | 卡片圆角大小，支持 `$` 简写 | String \| Number | `$12` | - |
| draggable | 是否开启手势拖动关闭 | Boolean | `false` | `true` \| `false` |
| dragThreshold | 横向拖动关闭阈值，超过则飞出关闭，支持数字（px）与百分比字符串（相对卡片宽度） | String \| Number | `80` | - |
| customStyle | 自定义通知卡片样式 | SnStyleValue | `''` | - |
| customClass | 通知卡片外部类 | String | `''` | - |
| titleStyle | 自定义标题样式 | SnStyleValue | `''` | - |
| titleClass | 标题外部类 | String | `''` | - |
| contentStyle | 自定义内容样式 | SnStyleValue | `''` | - |
| contentClass | 内容外部类 | String | `''` | - |
| iconStyle | 自定义图标样式 | SnStyleValue | `''` | - |
| iconClass | 图标外部类 | String | `''` | - |
| closeStyle | 自定义关闭按钮样式 | SnStyleValue | `''` | - |
| closeClass | 关闭按钮外部类 | String | `''` | - |
| badgeStyle | 自定义合并计数徽标样式 | SnStyleValue | `''` | - |
| badgeClass | 合并计数徽标外部类 | String | `''` | - |
| actionStyle | 自定义操作插槽容器样式 | SnStyleValue | `''` | - |
| actionClass | 操作插槽容器外部类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| close | () => Void | 有一条通知被关闭（移除）时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| show | param: `SnNotificationParams` \| null | String | 弹出一条通知，参数字段优先于组件属性默认值，返回通知 `id` |
| close | id: String（默认 `''`） | - | 关闭通知；传入 `id` 时仅关闭对应通知，留空时关闭全部通知 |

> 类型字段：SnNotificationParams（见 https://sinleui.pages.dev/api/types/component#snnotificationparams）


## show 参数（SnNotificationParams）

| 字段 | 说明 | 类型 |
| --- | --- | --- |
| title | 通知标题 | String \| null |
| content | 通知内容 | String \| null |
| type | 通知类型 | `SnNotificationType` \| null |
| level | 配色等级 | `SnNotificationLevel` \| null |
| position | 弹出位置 | `SnNotificationPosition` \| null |
| duration | 自动关闭时长（ms） | Number \| null |
| showProgress | 是否显示进度条 | Boolean \| null |
| showIcon | 是否显示类型图标 | Boolean \| null |
| icon | 自定义图标名称 | String \| null |
| closable | 是否显示关闭按钮 | Boolean \| null |
| showAction | 是否显示右侧操作插槽（需组件内定义插槽内容） | Boolean \| null |
| grouping | 是否开启通知合并 | Boolean \| null |
| bgColor | 卡片背景颜色 | String \| null |
| titleColor | 标题颜色 | String \| null |
| contentColor | 内容颜色 | String \| null |
| iconColor | 图标颜色 | String \| null |
| borderRadius | 圆角大小 | String \| null |
| draggable | 是否开启手势拖动关闭 | Boolean \| null |
| dragThreshold | 拖动关闭阈值 | String \| Number \| null |
| customStyle | 自定义通知卡片样式 | SnStyleValue \| null |

> 类型字段：SnNotificationType（见 https://sinleui.pages.dev/api/types/component#snnotificationtype）

> 类型字段：SnNotificationLevel（见 https://sinleui.pages.dev/api/types/component#snnotificationlevel）

> 类型字段：SnNotificationPosition（见 https://sinleui.pages.dev/api/types/component#snnotificationposition）


## 插槽

| 名称 | 说明 |
| --- | --- |
| action | 卡片右侧操作区插槽，仅当 `show()` 参数 `showAction` 为 `true` 时显示；作用域暴露 `id`（当前通知 id） |

<DemoPhone name="sn-notification" />

# Tooltip 提示框

> [查看 sn-tooltip 的 2.0 版本差异](/differences/components/sn-tooltip)

## 基础用法

提示框，点击触发器后在附近弹出说明文字，常用于解释某个按钮或操作的用途。

- 支持 12 个弹出方位，内容自动定位到触发器附近，靠近屏幕边缘时自动收进避免超出屏幕
- 点击触发器弹出，再次点击触发器或点击提示框外部关闭
- 未提供触发器插槽时，默认插槽内容或文本自身充当触发器

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下使用，否则主题颜色与动画时长等 CSS 变量无法作用到组件内部。
:::

::: info 平台差异
HarmonyOS 端提示框默认阴影较轻，显式传入 `boxShadow` 时仍以传入值为准；提示框透明度由入退场动画控制。
:::

```vue
<template>
	<sn-tooltip text="这是一个提示信息">
		<template #trigger>
			<sn-button type="primary" level="second" text="点我"></sn-button>
		</template>
	</sn-tooltip>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| text | 提示文本内容 | String | `''` | - |
| position | 弹出方位（相对触发器） | String | `top-start` | `top-start` \| `top` \| `top-end` \| `bottom-start` \| `bottom` \| `bottom-end` \| `left-start` \| `left` \| `left-end` \| `right-start` \| `right` \| `right-end` |
| width | 提示框宽度，`$` 前缀按字体大小乘数缩放 | String \| Number | `''` | - |
| height | 提示框高度，`$` 前缀按字体大小乘数缩放 | String \| Number | `''` | - |
| borderRadius | 提示框圆角大小，`$` 前缀按圆角乘数缩放 | String \| Number | `12px` | - |
| padding | 提示框内边距，支持 `$` 前缀按间距乘数缩放 | String | `10px 10px` | - |
| bgColor | 提示框背景颜色，支持 `$` 简写主题色 | String | `$info` | - |
| boxShadow | 提示框阴影 | String | `0px 2px 10px 0px $infoDark` | - |
| aniTime | 动画时长（ms），支持 `$` 前缀按动画乘数缩放，`0` 关闭动画 | String \| Number | `$normal` | `$long` \| `$normal` \| `$short` \| 数值 |
| customStyle | 自定义组件根节点样式 | SnStyleValue | `''` | - |
| tooltipStyle | 提示框自定义样式 | SnStyleValue | `''` | - |
| tooltipClass | 提示框外部样式类 | String | `''` | - |
| triggerStyle | 触发器自定义样式 | SnStyleValue | `''` | - |
| triggerClass | 触发器外部样式类 | String | `''` | - |

## 插槽

| 名称 | 说明 |
| --- | --- |
| trigger | 触发器内容（如一个按钮），点击后弹出提示框 |
| default | 提示框内容；未提供 `trigger` 插槽时同时充当触发器 |

<DemoPhone name="sn-tooltip" />

# LoadingPage 加载页

> [查看 sn-loading-page 的 2.0 版本差异](/differences/components/sn-loading-page)

## 基础用法

页面级加载占位组件，页面信息尚未加载完成时使用，避免出现视觉空白。

- 基于全屏遮罩实现，显隐可控制
- 提供内置加载组件与旋转图标两种加载指示器模式
- 可传入图片替代加载指示器

```vue
<template>
	<sn-loading-page :show="show" text="加载中"></sn-loading-page>
</template>

<script setup>
	onLoad(() => {
		// onLoad 内设置延时可以避免组件刚加载的瞬间出现的闪动
		setTimeout(() => {
			show.value = true
		}, 1)
	})
</script>
```

**更多演示请下载 demo 查看**

## 图片模式

传入 `img-src` 后以图片替代加载指示器，可通过 `img-style` 控制图片尺寸。

```vue
<template>
	<sn-loading-page :show="show" img-src="/static/logo-trans.png" text="SinleUI"
		img-style="width:80px;height:80px;" text-style="margin-top:10px;font-weight:bold;"></sn-loading-page>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| show | 是否显示加载页 | Boolean | `false` | `true` \| `false` |
| text | 加载页显示的文本内容 | String | `加载中` | - |
| imgSrc | 加载页显示的图片路径，非空时以图片替代加载指示器 | String | - | - |
| bgColor | 加载页背景颜色 | String | `$info` | - |
| textColor | 加载页文本颜色 | String | `$primary` | - |
| textSize | 加载页文本大小 | String \| Number | `$20` | - |
| iconColor | 加载页图标颜色（如果显示图标），跟随 `textColor` | String | - | - |
| iconSize | 加载页图标大小（如果显示图标） | String \| Number | `$38` | - |
| mode | 加载指示器模式 | String | `native` | `native` \| `icon` |
| aniTime | 加载页显隐动画时长，支持 `$` 简写随动画乘数缩放，`0` 为瞬时 | String \| Number | - | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| imgStyle | 自定义图片节点内联样式 | SnStyleValue | `width: 70px; height: 70px;` | - |
| imgClass | 自定义图片节点外部样式类 | String | - | - |
| textStyle | 自定义文本节点内联样式 | SnStyleValue | `margin-top: 15px;` | - |
| textClass | 自定义文本节点外部样式类 | String | - | - |

<DemoPhone name="sn-loading-page" />

# Drawer 抽屉

> [查看 sn-drawer 的 2.0 版本差异](/differences/components/sn-drawer)

## 基础用法

从屏幕四个方向滑出的半屏面板，常用于导航菜单、筛选、购物车等场景。

- 支持上下左右四个滑出方向与面板尺寸配置
- 内置滑动关闭手势，未达阈值自动回弹，Web 端同时支持鼠标拖拽
- 抽屉内容沿用弹出层的动态层级，嵌套打开其它弹层时层级正确

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下使用，否则主题颜色与动画时长等 CSS 变量无法作用到组件内部。
:::

::: info 组件选型
内嵌长列表请改用 **DrawerList**，在 `sn-drawer` 内嵌长列表会出现严重的嵌套滚动问题；`sn-float-board` 始终显示、无需调用方法；`sn-popup` 只负责动画与显隐，UI 需自行实现。
:::

```vue
<template>
	<sn-page>
		<sn-button text="打开抽屉" type="primary" @click="open"></sn-button>
		<sn-drawer ref="drawerRef" position="bottom" height="300px">
			<sn-text text="抽屉内容"></sn-text>
		</sn-drawer>
	</sn-page>
</template>

<script lang="ts" setup>

const drawerRef = ref<SnDrawerComponentPublicInstance | null>(null)

function open(): void {
	drawerRef.value?.$callMethod('open')
}
</script>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| position | 抽屉滑出的方向 | String | `bottom` | `top` \| `right` \| `bottom` \| `left` |
| renderMode | 渲染模式，`v-if` 关闭后销毁内容，`v-show` 保留内容 | String | `v-if` | `v-if` \| `v-show` |
| showLine | 是否显示面板上的滑动指示条 | Boolean | `true` | `true` \| `false` |
| slideClose | 是否启用滑动关闭手势 | Boolean | `true` | `true` \| `false` |
| width | 面板宽度，`position` 为 `left` \| `right` 时生效，支持 `$` 前缀按间距乘数缩放 | String \| Number | `300px` | - |
| height | 面板高度，`position` 为 `top` \| `bottom` 时生效，支持 `$` 前缀按间距乘数缩放 | String \| Number | `300px` | - |
| slideHeight | 纵向滑动关闭阈值，滑动距离达到阈值则关闭，支持 `$` 前缀按间距乘数缩放 | String \| Number | `100px` | - |
| slideWidth | 横向滑动关闭阈值，滑动距离达到阈值则关闭，支持 `$` 前缀按间距乘数缩放 | String \| Number | `100px` | - |
| bgColor | 面板背景颜色，支持 `$` 简写 | String | `$front` | - |
| lineColor | 滑动指示条颜色，支持 `$` 简写 | String | `$lineText` | - |
| padding | 面板内边距，支持 `$` 前缀按间距乘数缩放 | String | `25px 15px 10px 15px` | - |
| borderRadius | 面板圆角大小，支持 `$` 简写 | String \| Number | `$20` | - |
| aniTime | 显示 / 关闭动画时长（ms），支持 `$` 简写 | String \| Number | `$long` | - |
| preventBack | 显示时是否阻止页面返回事件 | Boolean | `false` | `true` \| `false` |
| maskClose | 是否启用点击遮罩关闭 | Boolean | `true` | `true` \| `false` |
| maskOpacity | 遮罩透明度 | Number | `0.3` | - |
| zIndex | 弹出层层级 | Number | `999` | - |
| customStyle | 自定义面板样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| clickoverlay | () => Void | 点击遮罩时触发 |
| beforeenter | () => Void | 入场动画开始前触发 |
| enter | () => Void | 入场动画开始时触发 |
| afterenter | () => Void | 入场动画结束后触发 |
| beforeleave | () => Void | 离场动画开始前触发 |
| leave | () => Void | 离场动画开始时触发 |
| afterleave | () => Void | 离场动画结束后触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 打开抽屉 |
| close | - | - | 关闭抽屉 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 抽屉面板内的内容 |

<DemoPhone name="sn-drawer" />

# DrawerList 抽屉长列表

## 基础用法

底部滑出的抽屉式长列表，适合在抽屉中展示大量数据的场景（如播放列表、消息列表、评论区）。

- 内置 `sn-list-view` 长列表，支持加载更多与下拉刷新
- 支持滑动关闭面板，在列表顶部继续下滑即跟手关闭（详见「滑动关闭」）
- 面板高度支持百分比（如 `50%` 表示占视口高度一半）

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下（页面根节点或 `sn-page` 的直接子节点），否则页面的 `--sn-*`、`--ani-time-*` 变量不生效，颜色与动画异常。
:::

```vue
<template>
	<sn-page>
		<sn-button text="打开抽屉列表" type="primary" @click="open"></sn-button>
		<sn-drawer-list ref="drawerRef" :list="items">
			<template v-slot:default="slotProps">
				<view class="item">
					<text class="item-text">{{ slotProps.item }}</text>
				</view>
			</template>
		</sn-drawer-list>
	</sn-page>
</template>

<script lang="ts" setup
const drawerRef = ref<SnDrawerListComponentPublicInstance | null>(null)
const items = ref<any[]>([])
for (let i = 1; i <= 50; i++) {
	items.push(`列表项目 ${i}`)
}

function open(): void {
	drawerRef.value?.$callMethod('open')
}
</script>
```

**更多演示请下载 demo 查看**

## 实现原理

组件与 Drawer 的底层实现机制完全不同，主要为解决 Drawer 内嵌长列表时的嵌套滚动与手势事件冲突。

## 加载更多

开启 `loadmore` 后，列表滚动到底部触发 `loadmore` 事件，通过 `v-model:loadmore-status` 控制底部加载状态。

```vue
<template>
	<sn-drawer-list ref="drawerRef" :list="items" :loadmore="true"
		v-model:loadmore-status="loadmoreStatus" @loadmore="onLoadmore">
		<template v-slot:default="slotProps">
			<view class="item">
				<text class="item-text">{{ slotProps.item }}</text>
			</view>
		</template>
	</sn-drawer-list>
</template>

<script lang="ts" setup>

const drawerRef = ref<SnDrawerListComponentPublicInstance | null>(null)
const loadmoreStatus = ref<string>('loadmore')

function onLoadmore(): void {
	setTimeout((): void => {
		loadmoreStatus.value = 'nomore'
	}, 800)
}
</script>
```

## 滑动关闭

列表未滚动到顶部时可正常滚动内容；列表在顶部时继续下滑，面板跟随手势移动，松手超过 `slideHeight` 阈值或快速下滑即关闭，未达阈值回弹。Web 端同时支持鼠标拖拽。

## 抽屉面板属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| list | 列表数据数组 | `Array<any>` | `[]` | - |
| renderMode | 渲染模式，`v-if` 关闭后销毁内容，`v-show` 保留内容 | String | `v-if` | `v-if` \| `v-show` |
| showLine | 是否显示面板上的滑动指示条 | Boolean | `true` | `true` \| `false` |
| slideClose | 是否启用滑动关闭手势 | Boolean | `true` | `true` \| `false` |
| height | 面板高度，支持百分比，支持 `$` 前缀按间距乘数缩放 | String \| Number | `300px` | - |
| slideHeight | 滑动关闭阈值，面板下滑距离达到阈值则关闭，支持 `$` 前缀按间距乘数缩放 | String \| Number | `100px` | - |
| bgColor | 面板背景颜色，支持 `$` 简写 | String | `$front` | - |
| lineColor | 滑动指示条颜色，支持 `$` 简写 | String | `$lineText` | - |
| padding | 面板内边距，支持 `$` 前缀按间距乘数缩放 | String | `25px 15px 10px 15px` | - |
| borderRadius | 面板圆角大小，支持 `$` 简写 | String \| Number | `$20` | - |
| aniTime | 显示 / 关闭动画时长（ms），支持 `$` 简写 | String \| Number | `$long` | - |
| preventBack | 显示时是否阻止页面返回事件 | Boolean | `false` | `true` \| `false` |
| maskClose | 是否启用点击遮罩关闭 | Boolean | `true` | `true` \| `false` |
| maskOpacity | 遮罩透明度 | Number | `0.3` | - |
| zIndex | 弹出层层级 | Number | `999` | - |
| customStyle | 自定义面板样式 | SnStyleValue | `''` | - |
| v-model:refresher-triggered | 下拉刷新状态绑定值 | Boolean | `false` | `true` \| `false` |
| v-model:loadmore-status | 加载更多状态绑定值 | String | `loadmore` | `loadmore` \| `loading` \| `nomore` |

## 透传 sn-list-view 属性

以下属性透传给内部 `sn-list-view`，用于控制列表滚动、回弹、下拉刷新与回到顶部等行为。

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| bounces | iOS 下是否支持回弹 | Boolean | `true` | `true` \| `false` |
| nested | 是否使用嵌套滚动模式 | Boolean | `false` | `true` \| `false` |
| customNestedScroll | 是否使用自定义嵌套滚动处理 | Boolean | `false` | `true` \| `false` |
| upperThreshold | 距顶部多远时触发 `scrolltoupper` 事件（px） | Number | `50` | - |
| lowerThreshold | 距底部多远时触发 `scrolltolower` 事件（px） | Number | `50` | - |
| scrollTop | 设置竖向滚动位置 | Number | `0` | - |
| scrollLeft | 设置横向滚动位置 | Number | `0` | - |
| showScrollbar | 是否显示滚动条 | Boolean | `true` | `true` \| `false` |
| scrollIntoView | 滚动到指定子元素（值为元素 id） | String | `''` | - |
| scrollWithAnimation | 滚动位置变化时是否使用滚动动画 | Boolean | `true` | `true` \| `false` |
| androidOverscroll | Android 下是否支持滚动越界 | Boolean | `false` | `true` \| `false` |
| androidScrollbarDraggable | 滚动条是否可拖拽（仅 Android） | Boolean | `false` | `true` \| `false` |
| enableBackToTop | 点击顶部状态栏回到顶部（仅 iOS） | Boolean | `false` | `true` \| `false` |
| scrollAnchoring | 是否开启滚动锚定（App 端生效） | Boolean | `false` | `true` \| `false` |
| nestedScrollChild | 嵌套滚动的子容器 id | String | `''` | - |
| listPadding | 列表内边距 | `Array<Number>` | `[]` | - |
| refresherEnabled | 是否开启下拉刷新 | Boolean | `false` | `true` \| `false` |
| refresherThreshold | 下拉刷新触发阈值（px） | Number | `45` | - |
| refresherMaxDragDistance | 下拉刷新最大拖拽距离（px），`0` 表示不限制 | Number | `0` | - |
| refresherBackground | 下拉刷新区域背景颜色，支持 `$` 简写 | String | `transparent` | - |
| refresherDefaultStyle | 下拉刷新默认样式 | String | `white` | `white` \| `black` \| `none` |
| enablePassive | 是否启用被动滚动模式（仅 Web 默认为 `true`，其余平台为 `false`） | Boolean | 见说明 | `true` \| `false` |
| backtop | 是否显示回到顶部按钮 | Boolean | `false` | `true` \| `false` |
| backtopTarget | 回到顶部滚动目标元素 id | String | `''` | - |
| backtopTop | 回到顶部按钮距顶部距离（px） | Number | `400` | - |
| backtopRight | 回到顶部按钮距右侧距离（px） | Number | `30` | - |
| backtopBottom | 回到顶部按钮距底部距离（px） | Number | `100` | - |
| loadmore | 是否开启加载更多 | Boolean | `false` | `true` \| `false` |
| loadmoreConfig | 加载更多样式配置 | `SnLoadmoreParams` | `{}` | - |
| refresherConfig | 下拉刷新样式配置 | `SnRefresherParams` | `{}` | - |
| listStyle | 自定义列表样式 | SnStyleValue | `''` | - |
| listClass | 列表外部类 | String | `''` | - |

> 类型字段：SnLoadmoreParams（见 https://sinleui.pages.dev/api/types/component#snloadmoreparams）

> 类型字段：SnRefresherParams（见 https://sinleui.pages.dev/api/types/component#snrefresherparams）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| clickoverlay | () => Void | 点击遮罩时触发 |
| beforeenter | () => Void | 入场动画开始前触发 |
| enter | () => Void | 入场动画开始时触发 |
| afterenter | () => Void | 入场动画结束后触发 |
| beforeleave | () => Void | 离场动画开始前触发 |
| leave | () => Void | 离场动画开始时触发 |
| afterleave | () => Void | 离场动画结束后触发 |
| scrolltoupper | (ev: UniScrollToUpperEvent) => Void | 列表滚动到顶部时触发 |
| scrolltolower | (ev: UniScrollToLowerEvent) => Void | 列表滚动到底部时触发 |
| scroll | (ev: UniScrollEvent) => Void | 列表滚动时触发 |
| scrollend | (ev: UniScrollEvent) => Void | 列表滚动结束时触发 |
| refresherpulling | (ev: UniRefresherEvent) => Void | 下拉刷新被拉动时触发 |
| refresherrefresh | (ev: UniRefresherEvent) => Void | 下拉刷新被触发时触发 |
| refresherrestore | (ev: UniRefresherEvent) => Void | 下拉刷新被复位时触发 |
| refresherabort | (ev: UniRefresherEvent) => Void | 下拉刷新被中止时触发 |
| loadmore | () => Void | 列表滚动到底部且 `loadmore` 开启时触发 |
| click | () => Void | 列表区域被点击时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 打开抽屉 |
| close | - | - | 关闭抽屉 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 列表项内容的作用域插槽，暴露 `item`（当前项数据）与 `index`（当前项索引） |
| prefix | 列表上方的内容区，位于 sn-list-view 之前，不随列表滚动 |
| suffix | 列表下方的内容区，位于 sn-list-view 之后，不随列表滚动 |

<DemoPhone name="sn-drawer-list" />

# Actionsheet 操作菜单

> [查看 sn-actionsheet 的 2.0 版本差异](/differences/components/sn-actionsheet)

## 基础用法

从底部弹出的操作菜单，用于展示一组操作项供用户选择。

- 点击操作项后自动关闭并派发选择事件
- 内置取消按钮与标题，均可按需隐藏
- 支持操作项文字颜色与禁用状态

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下使用，否则主题颜色与动画时长等 CSS 变量无法作用到组件内部。
:::

::: tip 建议直接使用 API
推荐使用 [snu.showActionsheet](/libs/utils/ui#snu-showactionsheet)：无需在页面放置组件或绑定 `ref`，配置字段与组件 props 一致，结果经 `success` 回调返回；作为整页弹层可覆盖导航栏 / tabbar 并拦截返回键。组件本身不提供插槽，需先放置到页面再通过 `ref` 调用。
:::

::: info 内部间距随乘数缩放
标题 / 操作项内边距随 `paddingFactor`、取消项外边距随 `marginFactor` 缩放，无需额外配置。
:::

```typescript
snu.showActionsheet({
	title: '请选择',
	actions: [{ text: '拍照' }, { text: '相册' }],
	success: (tapIndex) => {}
})
```


```vue
<template>
	<sn-page>
		<sn-button text="打开操作菜单" type="primary" @click="open"></sn-button>
		<sn-actionsheet ref="sheetRef" title="选择操作" :actions="actions"
			@click-item="onClickItem"></sn-actionsheet>
	</sn-page>
</template>

<script lang="ts" setup>
import type { SnDataItem } from '@/uni_modules/sinle-ui/core/types/index.ts'

const sheetRef = ref<SnActionsheetComponentPublicInstance | null>(null)
const actions = ref<SnDataItem[]>([
	{ text: '选项一' },
	{ text: '选项二' },
	{ text: '选项三' }
])

function open(): void {
	sheetRef.value?.$callMethod('open')
}

function onClickItem(item: SnDataItem): void {
	console.log(item.text)
}
</script>
```

**更多演示请下载 demo 查看**

## 自定义操作项

操作项颜色支持 `$` 简写，可单独禁用某一项。

```vue
<template>
	<sn-actionsheet ref="sheetRef" title="分享到" :actions="actions"></sn-actionsheet>
</template>

<script lang="ts" setup>
import type { SnDataItem } from '@/uni_modules/sinle-ui/core/types/index.ts'

const actions = ref<SnDataItem[]>([
	{ text: '微信', color: '$success' },
	{ text: '朋友圈', color: '$success' },
	{ text: '删除', color: '$error' },
	{ text: '暂不可用', disabled: true }
])
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| title | 操作菜单标题，为空则不显示标题与分隔线 | String | `''` | - |
| actions | 操作项数组，每项支持 `text`（文字）、`color`（文字颜色，支持 `$` 简写）、`disabled`（是否禁用）等字段 | Array<`SnDataItem`> | `[]` | - |
| showCancel | 是否显示底部取消按钮 | Boolean | `true` | `true` \| `false` |
| titleColor | 标题颜色，支持 `$` 简写 | String | `$title` | - |
| titleSize | 标题字号，支持 `$` 简写 | String \| Number | `$13` | - |
| bgColor | 面板背景颜色，支持 `$` 简写 | String | `$front` | - |
| cancelText | 取消按钮文字 | String | `取消` | - |
| maskOpacity | 遮罩透明度 | Number | `0.4` | - |
| aniTime | 动画时长（ms），支持 `$` 简写 | String \| Number | `$long` | - |
| preventBack | 是否阻止返回键关闭 | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用，禁用后操作项与取消按钮均不可点击 | Boolean | `false` | `true` \| `false` |
| maskClose | 点击遮罩时是否关闭 | Boolean | `true` | `true` \| `false` |
| customStyle | 自定义面板样式，后应用，优先于 `panelStyle` | SnStyleValue | `''` | - |
| wrapStyle | 自定义外层容器样式 | SnStyleValue | `''` | - |
| wrapClass | 外层容器外部类 | String | `''` | - |
| panelStyle | 自定义面板样式 | SnStyleValue | `''` | - |
| panelClass | 面板外部类 | String | `''` | - |
| itemStyle | 自定义操作项样式（透传内部 sn-cell） | SnStyleValue | `''` | - |
| itemClass | 操作项外部类（透传内部 sn-cell） | String | `''` | - |
| itemBorder | 是否显示操作项之间的分隔线 | Boolean | `true` | `true` \| `false` |
| itemHoverStyle | 操作项按压时应用的样式 | SnStyleValue | `background-color: var(--sn-info)` | - |

> 类型字段：SnDataItem（见 https://sinleui.pages.dev/api/types/component#sndataitem）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| clickItem | (item: `SnDataItem`) => Void | 点击操作项时触发，参数为所选操作项，随后自动关闭 |
| cancel | () => Void | 点击取消按钮（或调用 `cancel` 方法）时触发，随后关闭 |
| clickoverlay | () => Void | 点击遮罩时触发 |
| beforeenter | () => Void | 入场动画开始前触发 |
| enter | () => Void | 入场动画开始时触发 |
| afterenter | () => Void | 入场动画结束后触发 |
| beforeleave | () => Void | 离场动画开始前触发 |
| leave | () => Void | 离场动画开始时触发 |
| afterleave | () => Void | 离场动画结束后触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 打开操作菜单 |
| close | - | - | 关闭操作菜单 |
| cancel | - | - | 关闭操作菜单并触发 `cancel` 事件 |

<DemoPhone name="sn-actionsheet" />

# Popover 定位弹出层

## 基础用法

在指定屏幕坐标处弹出的轻量弹出层，常用于长按菜单、点击气泡等场景。

- 支持按窗口坐标弹出（触摸事件可直接传入坐标并支持偏移），也支持双向绑定显隐
- 内容靠近屏幕边缘时自动避让，不会超出屏幕
- 支持多种内置动画与自定义动画，可开启遮罩；Web 端弹出期间自动锁定页面滚动

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下使用，否则主题颜色与动画时长等 CSS 变量无法作用到组件内部。
:::

```vue
<template>
	<sn-page>
		<sn-button text="打开弹出层" type="primary" @click="open"></sn-button>
		<sn-popover ref="popoverEle">
			<view class="menu">
				<sn-cell title="复制" icon="file-copy-line" clickable @click="close"></sn-cell>
				<sn-cell title="粘贴" icon="clipboard-line" clickable @click="close"></sn-cell>
			</view>
		</sn-popover>
	</sn-page>
</template>

<script lang="ts" setup>

	const popoverEle = ref<SnPopoverComponentPublicInstance | null>(null)

	function open(): void {
		const info = uni.getWindowInfo()
		popoverEle.value?.$callMethod('open', Math.round(info.windowWidth / 2), Math.round(info.windowHeight / 2))
	}

	function close(): void {
		popoverEle.value?.$callMethod('close')
	}
</script>
```

**更多演示请下载 demo 查看**

## 长按弹出

典型场景：在触摸区域监听 `longpress` 事件，用触点坐标打开弹出层。

```vue
<template>
	<sn-view bg-color="$infoDark" border-radius="$16" custom-style="height: 220px;" @touchstart="onTouchStart" @longpress="onLongpress">
		<sn-text text="长按此区域触发弹层"></sn-text>
	</sn-view>
	<sn-popover ref="popoverEle">
		<view class="menu">
			<sn-cell title="复制" icon="file-copy-line" clickable @click="close"></sn-cell>
		</view>
	</sn-popover>
</template>

<script lang="ts" setup>
	import type { SnTouchEvent } from '@/uni_modules/sinle-ui'

	const popoverEle = ref<SnPopoverComponentPublicInstance | null>(null)
	let point = [0, 0]

	function onTouchStart(e: SnTouchEvent): void {
		if (e.touches.length > 0) {
			point = [e.touches[0].x, e.touches[0].y]
		}
	}

	function onLongpress(): void {
		popoverEle.value?.$callMethod('open', point[0], point[1])
	}

	function close(): void {
		popoverEle.value?.$callMethod('close')
	}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model:show | 显示状态双向绑定，关闭时自动同步为 false | Boolean | `false` | `true` \| `false` |
| zIndex | 弹出层层级 | Number | `999` | - |
| overlay | 是否显示暗色遮罩 | Boolean | `false` | `true` \| `false` |
| overlayOpacity | 遮罩透明度（仅 `overlay` 为 true 时生效） | Number | `0.3` | - |
| overlayStyle | 自定义遮罩层样式 | SnStyleValue | `''` | - |
| overlayClass | 遮罩层外部样式类 | String | `''` | - |
| contentStyle | 弹出内容自定义样式 | SnStyleValue | `''` | - |
| contentClass | 弹出内容外部样式类 | String | `''` | - |
| closeOnClickOverlay | 点击遮罩区域是否关闭弹出层 | Boolean | `true` | `true` \| `false` |
| aniTime | 动画时长（ms），支持 `$` 前缀按动画乘数缩放，`0` 关闭动画 | String \| Number | `200` | `$long` \| `$normal` \| `$short` \| 数值 |
| offsetX | 弹出坐标 X 方向偏移（px） | Number | `0` | - |
| offsetY | 弹出坐标 Y 方向偏移（px） | Number | `0` | - |
| animation | 内置动画类型 | String | `scale` | `fade` \| `scale` \| `slide-up` \| `slide-down` \| `slide-left` \| `slide-right` \| `zoom` \| `bounce` |
| openAnimation | 自定义打开动画函数，传入后 `animation` 不再生效 | Function \| null | `null` | - |
| closeAnimation | 自定义关闭动画函数，传入后 `animation` 不再生效 | Function \| null | `null` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| update:show | (value: boolean) => Void | 显示状态变化时触发（配合 `v-model:show` 使用） |
| clickoverlay | () => Void | 点击遮罩区域时触发 |
| beforeenter | () => Void | 打开动画开始前触发 |
| enter | () => Void | 打开动画开始时触发 |
| afterenter | () => Void | 打开动画结束后触发 |
| beforeleave | () => Void | 关闭动画开始前触发 |
| leave | () => Void | 关闭动画开始时触发 |
| afterleave | () => Void | 关闭动画结束后触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | x: Number, y: Number | - | 在屏幕坐标 (x, y) 处打开弹出层（叠加 `offsetX` / `offsetY` 偏移） |
| close | - | - | 关闭弹出层 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 弹出层内容 |

<DemoPhone name="sn-popover" />

# Page 页面

> [查看 sn-page 的 2.0 版本差异](/differences/components/sn-page)

## 基础用法

页面根组件，占据整个页面并内置纵向滚动的内容区（不显示滚动条），无需手动管理滚动容器。

- 在页面加载时自动将背景色写入原生页面，避免加载初期白屏闪烁
- 在根节点提供全部主题颜色 CSS 变量，应用主题优先、系统外观兜底
- 在根节点注入乘数与动画时长 CSS 变量，页面内子组件直接引用
- 为后代组件提供独立的 Tabbar 高度登记作用域，卸载时清理

::: danger 必须放在 sn-page 下
- 页面内所有组件（含 sn-popup、sn-modal、sn-toast 等弹出层类组件）都必须放在 `sn-page` 下，务必让 `sn-page` 成为页面根节点，否则注入的 `--sn-*`、`--ani-time-*` CSS 变量无法作用到这些节点，颜色与动画时长会错乱
:::

::: details 注入的 CSS 变量
- 在根节点提供全部主题颜色 CSS 变量（如 `--sn-primary`、`--sn-front`、`--sn-transparent` 等）：根节点始终带 `sn-theme-light` 或 `sn-theme-dark` 类，声明默认风格的主题色板；样式中的 `@media (prefers-color-scheme: light|dark)` 色板作为系统外观兜底。首次使用默认风格时由 CSS 提供颜色；页面注入过自定义配色或非默认风格后，继续按当前色板差量更新内联变量
- 五个乘数 CSS 变量（`--marginFactor`、`--paddingFactor`、`--radiusFactor`、`--fontsizeFactor`、`--aniTimeFactor`）及其同值缩写（`--mf`、`--pf`、`--rf`、`--ff`、`--af`）与动画时长变量（`--ani-time-short`、`--ani-time-normal`、`--ani-time-long`），页面内所有子组件通过 `var()` 引用这些变量
:::

::: info 应用主题与系统外观的关系
颜色变量的优先级为**应用主题（`$snui.theme`）> 系统外观（`prefers-color-scheme`）**。用户在应用内手动切换亮/暗主题后，即使浏览器或系统外观相反，页面颜色也以应用选择为准；未手动切换（`autoTheme` 开启）时跟随系统外观。
:::

```vue
<template>
	<sn-page title="首页" :show-back="true">
		<sn-text text="页面内容"></sn-text>
	</sn-page>
</template>
```

**更多演示请下载 demo 查看**

## 自定义背景颜色

`bgColor` 不传或传空字符串时，自动使用当前主题的页面背景色（`$snui.colors.page`，随亮暗主题切换），并同步应用到原生页面背景与内置导航栏背景。传入具体色值后，主题切换不再影响该页背景。

```vue
<template>
	<sn-page bg-color="#f0f0f0"></sn-page>
</template>
```

## 内置导航栏

`title` 非空时自动在页面顶部渲染一个 sn-topbar 导航栏，标题为 `title`，`showBack` 控制返回按钮显隐，导航栏背景与页面背景保持一致。

内置导航栏根容器向上覆盖状态栏区域（沉浸式），顶部状态栏安全距离与内容占位由 `sn-page` 管理（占位高度 = `$snui.topbarHeightResolved` + 状态栏高度）。启用 `blur` 且使用内置滚动时，内容占位放在滚动内容开头，滚动内容可经过导航栏背后呈现模糊；`fillContent` 模式仍保留导航栏下方的固定间距。显式 `topbarBgColor` 可传半透明颜色，不透明颜色会遮住模糊效果。


```vue
<template>
	<sn-page title="页面标题" :show-back="true"></sn-page>
</template>
```

## 内容区不滚动

采用固定 Tabbar 的全屏子页面，应在子页面自己的滚动内容末尾，根据 [useTabbarHeights](/api/hooks/use-tabbar-heights) 读取的 `tabbarHeights[key]` 设置占位，不要在子组件外增加固定空白带。作用域存储于框架 `frameStore`，布局高度不持久化；`sn-page` 不自动创建 Tabbar 占位。

默认内容区放在内置 scroll-view 中纵向滚动，该滚动区已关闭 `show-scrollbar`（不显示滚动条），内容仍可正常滑动与滚轮滚动。若页面内部自带独立滚动容器（如 sn-waterflow、sn-list-view 的全屏子页面），设置 `fillContent` 让内容区填满剩余高度，由内部容器自行滚动。

```vue
<template>
	<sn-page :fill-content="true">
		<sn-waterflow></sn-waterflow>
	</sn-page>
</template>
```

## 实现原理

在 `onLoad` 时自动将页面背景色写入原生页面（同时设置 `navigationStyle` 为 `custom`），避免页面加载初期白屏闪烁。页面显示和主题切换更新背景色时，会在写入页面样式后同步状态栏前景色：亮色为黑色，暗色为白色。自定义导航栏模式下状态栏背景透明，由页面顶部背景决定。

页面注入过内联色板后，切回默认风格时会直接写入默认色值，避免依赖删除变量后的 class 色板回退。此后切换亮暗主题、修改单个颜色或替换颜色集时，都按实际变量值差量更新；已挂载但暂不可见的页面也会同步。新创建的默认风格页面仍优先使用 CSS 色板。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| bgColor | 页面背景颜色，并同步原生页面背景与内置导航栏背景；变化时自动更新页面背景 | String | `$page` | - |
| title | 页面标题，非空时自动渲染内置导航栏 | String | `''` | - |
| showBack | 是否显示内置导航栏的返回按钮（仅 title 非空时生效） | Boolean | `false` | `true` \| `false` |
| blur | 是否启用内置导航栏背景高斯模糊 | Boolean | `false` | `true` \| `false` |
| blurRadius | 内置导航栏背景高斯模糊半径（单位 px） | Number | `15` | - |
| blurOpacity | 未设置 bgColor 与 topbarBgColor 时的内置导航栏模糊背景透明度，取值 0~1 | Number | `0.78` | - |
| topbarBgColor | 内置导航栏背景颜色；为空时跟随页面背景颜色 | String | `''` | - |
| fillContent | 是否让内容区填满剩余高度而不使用内置滚动，用于内部自带滚动容器的全屏子页面 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| scrollTo | `(top: number, left?: number)` | - | 滚动内容区到指定位置，`top` 为纵向滚动距离、`left` 为横向滚动距离（单位 px），Web 端以平滑动画滚动 |
| registerBacktop | `(update: (scrollTop: number) => void)` | - | 注册滚动位置更新回调，供 sn-backtop 组件联动显隐（一般无需手动调用） |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 页面内容，默认放置在内置纵向滚动的 scroll-view 中（fillContent 为 true 时直接填满剩余高度） |

<DemoPhone name="sn-page" />

# ScrollView 滚动视图

## 基础用法

通用滚动视图容器，适用于页面内容、长列表等需要滚动与加载状态的场景。

- 内置下拉刷新、加载更多与回到顶部按钮，均可按需开关
- 支持纵向与横向滚动，并可开启嵌套滚动与父容器联动
- 刷新与加载更多的文案、图标等样式可通过配置对象定制

```vue
<template>
	<sn-scroll-view refresher-enabled v-model:refresher-triggered="refresherTriggered"
		loadmore v-model:loadmore-status="loadmoreStatus" backtop
		@refresherrefresh="onRefresh" @loadmore="onLoadmore">
		<view v-for="(item, index) in items" :key="index" class="scroll-item">
			<sn-text :text="item"></sn-text>
		</view>
	</sn-scroll-view>
</template>
```

**更多演示请下载 demo 查看**

## 实现原理

组件基于 `scroll-view` 封装，内部按开关集成下拉刷新（`sn-refresher`）、加载更多（`sn-loadmore`）与回到顶部按钮（`sn-backtop`）。

## 注意事项

滚动方向请使用 `direction`，旧的 `scroll-x` / `scroll-y` 写法已废弃。

## 横向滚动

设置 `direction="horizontal"` 即可横向滚动，容器内部主轴方向自动跟随切换。

```vue
<template>
	<sn-scroll-view direction="horizontal" :refresher-enabled="false" :loadmore="false">
		<view class="h-row">
			<view v-for="(item, index) in hItems" :key="index" class="h-item">
				<sn-text :text="item"></sn-text>
			</view>
		</view>
	</sn-scroll-view>
</template>
```

## 嵌套滚动

设置 `nested` 为 `true` 后组件与父级嵌套滚动容器关联（等同于 `associative-container="nested-scroll-view"`），并透传 `startnestedscroll` / `nestedprescroll` / `stopnestedscroll` 三个嵌套滚动协商事件。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| direction | 滚动方向 | String | `vertical` | `none` \| `horizontal` \| `vertical` |
| v-model:refresher-triggered | 绑定当前下拉刷新状态 | Boolean | `false` | `true` \| `false` |
| v-model:loadmore-status | 绑定加载更多组件状态，触底或点击加载更多时组件内部自动改写为 `loading`，由父组件在 `loadmore` 事件中更新加载结果 | String | `loadmore` | `loadmore` \| `loading` \| `nomore` |
| refresherEnabled | 是否开启下拉刷新 | Boolean | `true` | `true` \| `false` |
| refresherConfig | 下拉刷新组件配置（`refreshText`、`refreshingText`、`textSize`、`textColor`、`icon`、`iconSize`、`iconColor`） | `SnRefresherParams` | `{}` | - |
| refresherThreshold | 下拉刷新阈值（单位 px，仅自定义刷新样式下生效） | Number | `45` | - |
| refresherMaxDragDistance | 下拉最大拖拽距离（单位 px，App 端生效） | Number | `0` | - |
| refresherBackground | 下拉刷新区域背景颜色 | String | `transparent` | - |
| refresherDefaultStyle | 下拉刷新默认样式；开启下拉刷新时组件强制使用自定义刷新条 | String | `white` | `white` \| `black` \| `none` |
| loadmore | 是否开启加载更多（触底自动触发，底部显示加载状态条） | Boolean | `true` | `true` \| `false` |
| loadmoreConfig | 加载更多组件配置（`loadmoreText`、`nomoreText`、`loadingText`、`textSize`、`textColor`、`iconSize`、`iconColor`、`lineHeight`、`lineColor`、`dashed`、`disabled`） | `SnLoadmoreParams` | `{}` | - |
| backtop | 是否内置回到顶部按钮 | Boolean | `false` | `true` \| `false` |
| backtopTarget | 内置回到顶部按钮的绑定目标（ref 名或元素 id） | String | `''` | - |
| backtopTop | 内置回到顶部按钮的显示阈值（滚动距离，单位 px） | Number | `400` | - |
| backtopRight | 内置回到顶部按钮距右边界距离（单位 px） | Number | `30` | - |
| backtopBottom | 内置回到顶部按钮距下边界距离（单位 px） | Number | `100` | - |
| bounces | 是否启用回弹效果（App 端生效） | Boolean | `true` | `true` \| `false` |
| associativeContainer | 关联的滚动容器（App 端嵌套滚动场景使用） | String | `''` | - |
| nested | 是否开启嵌套滚动模式，为 `true` 时自动关联嵌套滚动容器 | Boolean | `false` | `true` \| `false` |
| customNestedScroll | 子元素是否开启嵌套滚动协商（仅 Android 端生效） | Boolean | `false` | `true` \| `false` |
| nestedScrollChild | 嵌套滚动的子容器元素 id | String | `''` | - |
| upperThreshold | 距顶部/左边多远时（单位 px）触发 `scrolltoupper` 事件 | Number | `50` | - |
| lowerThreshold | 距底部/右边多远时（单位 px）触发 `scrolltolower` 事件 | Number | `50` | - |
| scrollTop | 设置竖向滚动条位置 | Number | `0` | - |
| scrollLeft | 设置横向滚动条位置 | Number | `0` | - |
| scrollIntoView | 值应为某子元素 id（id 不能以数字开头），滚动到该元素 | String | `''` | - |
| scrollWithAnimation | 设置滚动条位置时是否使用滚动动画 | Boolean | `true` | `true` \| `false` |
| showScrollbar | 是否显示滚动条 | Boolean | `true` | `true` \| `false` |
| androidOverscroll | Android 端是否开启弹簧回弹效果 | Boolean | `false` | `true` \| `false` |
| androidScrollbarDraggable | Android 端滚动条是否可拖拽 | Boolean | `false` | `true` \| `false` |
| androidRefresherColor | Android 端下拉刷新默认样式颜色 | String | `''` | - |
| enableBackToTop | 点击状态栏回到顶部（iOS 端生效） | Boolean | `false` | `true` \| `false` |
| enablePassive | 是否开启 passive 滚动监听（仅 Web 端） | Boolean | Web 端 `true`，其他端 `false` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 自定义根节点外部样式类 | String | `''` | - |

> 类型字段：SnRefresherParams（见 https://sinleui.pages.dev/api/types/component#snrefresherparams）

> 类型字段：SnLoadmoreParams（见 https://sinleui.pages.dev/api/types/component#snloadmoreparams）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| scrolltoupper | (e: UniScrollToUpperEvent) => Void | 滚动到顶部/左边时触发，同时内部复位下拉刷新条 |
| scrolltolower | (e: UniScrollToLowerEvent) => Void | 滚动到底部/右边时触发，开启 `loadmore` 时自动触发加载 |
| scroll | (e: UniScrollEvent) => Void | 滚动时触发 |
| scrollend | (e: UniScrollEvent) => Void | 滚动结束时触发（App 端） |
| refresherpulling | (e: UniRefresherEvent) => Void | 下拉刷新控件被下拉时触发 |
| refresherrefresh | (e: UniRefresherEvent) => Void | 下拉刷新被触发时触发，同时置位 `refresher-triggered` |
| refresherrestore | (e: UniRefresherEvent) => Void | 下拉刷新被复位时触发 |
| refresherabort | (e: UniRefresherEvent) => Void | 下拉刷新被中止时触发（App 端） |
| startnestedscroll | (e: UniStartNestedScrollEvent) => Void | 嵌套滚动开始时触发 |
| nestedprescroll | (e: UniNestedPreScrollEvent) => Void | 嵌套滚动预滚动协商时触发 |
| stopnestedscroll | (e: UniStopNestedScrollEvent) => Void | 嵌套滚动结束时触发 |
| loadmore | () => Void | 触底或点击加载状态条时触发，仅在开启 `loadmore` 且状态为 `loadmore` 时生效，触发后状态自动变为 `loading` |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| scrollTo | top: Number, left: Number（默认 0） | - | 滚动到指定位置（单位 px），Web 端带平滑动画 |
| registerBacktop | update: (scrollTop: Number) => Void | - | 注册滚动位置更新回调，供 `sn-backtop` 绑定（一般无需手动调用） |
| startRefresh | - | - | 主动触发下拉刷新，进入刷新中状态并置位 `refresher-triggered` |
| stopRefresh | - | - | 结束下拉刷新，恢复可下拉状态并复位 `refresher-triggered` |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 滚动内容区域，放置任意内容 |

<DemoPhone name="sn-scroll-view" />

# ListView 长列表

> [查看 sn-list-view 的 2.0 版本差异](/differences/components/sn-list-view)

## 基础用法

数据驱动的长列表组件，适合展示大量同类数据。

- 条目按类型分组复用回收，长列表滚动更省节点
- 内置下拉刷新、加载更多与回到顶部按钮，可按需开启
- 默认作用域插槽逐条渲染数据，作用域提供数据项与索引

```vue
<template>
	<sn-list-view :list="items" refresher-enabled v-model:refresher-triggered="refresherTriggered"
		loadmore v-model:loadmore-status="loadmoreStatus" backtop
		@refresherrefresh="onRefresh" @loadmore="onLoadmore">
		<template v-slot:default="slotProps">
			<view class="list-item-inner">
				<sn-text font-size="$14" color="$text">{{ slotProps.item }}</sn-text>
			</view>
		</template>
	</sn-list-view>
</template>
```

**更多演示请下载 demo 查看**

## 数据复用与 type 分组

组件基于官方 `list-view` 封装：会根据数据项的 `type` 字段（数字）对条目分组，同 `type` 的条目在 App 端复用同一类节点，`type` 越少复用效果越好。未声明 `type` 的数据项默认归入 `0` 组。

```vue
<template>
	<sn-list-view :list="items">
		<template v-slot:default="slotProps">
			<view v-if="itemType(slotProps.item) == 1" class="item-card">
				<sn-text :text="itemTitle(slotProps.item)"></sn-text>
			</view>
			<view v-else class="item-line">
				<sn-text :text="itemTitle(slotProps.item)"></sn-text>
			</view>
		</template>
	</sn-list-view>
</template>

<script setup>
	type Item = {
		type: number
		title: string
	}
	function itemType(item: any): number {
		return (item as Item).type
	}
	function itemTitle(item: any): string {
		return (item as Item).title
	}
</script>
```

- 内部保留了两个特殊 `type` 值：下拉刷新条目为 `2`、加载更多条目为 `99998`，业务数据请避开这两个值。
- 不提供插槽内容时，默认渲染"条目 N"占位文本。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| list | 列表数据数组，数据项可为任意对象，支持 `type` 数字字段声明复用分组 | Array | `[]` | - |
| direction | 滚动方向 | String | `vertical` | `none` \| `horizontal` \| `vertical` |
| v-model:refresher-triggered | 绑定当前下拉刷新状态 | Boolean | `false` | `true` \| `false` |
| v-model:loadmore-status | 绑定加载更多组件状态，触底或点击加载更多时组件内部自动改写为 `loading`，由父组件在 `loadmore` 事件中更新加载结果 | String | `loadmore` | `loadmore` \| `loading` \| `nomore` |
| refresherEnabled | 是否开启下拉刷新 | Boolean | `true` | `true` \| `false` |
| refresherConfig | 下拉刷新组件配置（`refreshText`、`refreshingText`、`textSize`、`textColor`、`icon`、`iconSize`、`iconColor`） | `SnRefresherParams` | `{}` | - |
| refresherThreshold | 下拉刷新阈值（单位 px，仅自定义刷新样式下生效） | Number | `45` | - |
| refresherMaxDragDistance | 下拉最大拖拽距离（单位 px，App 端生效） | Number | `0` | - |
| refresherBackground | 下拉刷新区域背景颜色 | String | `transparent` | - |
| refresherDefaultStyle | 下拉刷新默认样式；开启下拉刷新时组件强制使用自定义刷新条 | String | `white` | `white` \| `black` \| `none` |
| loadmore | 是否开启加载更多（触底自动触发，底部显示加载状态条） | Boolean | `false` | `true` \| `false` |
| loadmoreConfig | 加载更多组件配置（`loadmoreText`、`nomoreText`、`loadingText`、`textSize`、`textColor`、`iconSize`、`iconColor`、`lineHeight`、`lineColor`、`dashed`、`disabled`） | `SnLoadmoreParams` | `{}` | - |
| backtop | 是否内置回到顶部按钮 | Boolean | `false` | `true` \| `false` |
| backtopTarget | 内置回到顶部按钮的绑定目标（ref 名或元素 id） | String | `''` | - |
| backtopTop | 内置回到顶部按钮的显示阈值（滚动距离，单位 px） | Number | `400` | - |
| backtopRight | 内置回到顶部按钮距右边界距离（单位 px） | Number | `30` | - |
| backtopBottom | 内置回到顶部按钮距下边界距离（单位 px） | Number | `100` | - |
| bounces | 是否启用回弹效果（App 端生效） | Boolean | `true` | `true` \| `false` |
| associativeContainer | 关联的滚动容器（App 端嵌套滚动场景使用） | String | `''` | - |
| nested | 是否开启嵌套滚动模式，为 `true` 时自动关联嵌套滚动容器（App 端生效） | Boolean | `false` | `true` \| `false` |
| customNestedScroll | 子元素是否开启嵌套滚动协商（仅 Android 端生效） | Boolean | `false` | `true` \| `false` |
| nestedScrollChild | 嵌套滚动的子容器元素 id | String | `''` | - |
| upperThreshold | 距顶部/左边多远时（单位 px）触发 `scrolltoupper` 事件 | Number | `50` | - |
| lowerThreshold | 距底部/右边多远时（单位 px）触发 `scrolltolower` 事件 | Number | `50` | - |
| scrollTop | 设置竖向滚动条位置 | Number | `0` | - |
| scrollLeft | 设置横向滚动条位置（App 端生效） | Number | `0` | - |
| scrollIntoView | 值应为某子元素 id（id 不能以数字开头），滚动到该元素 | String | `''` | - |
| scrollWithAnimation | 设置滚动条位置时是否使用滚动动画 | Boolean | `true` | `true` \| `false` |
| scrollAnchoring | 开启滚动锚定（App 端生效） | Boolean | `false` | `true` \| `false` |
| initialScrollBottom | 初始渲染时定位到底部（App 端生效，聊天类场景使用） | Boolean | `false` | `true` \| `false` |
| showScrollbar | 是否显示滚动条 | Boolean | `true` | `true` \| `false` |
| androidOverscroll | Android 端是否开启弹簧回弹效果 | Boolean | `false` | `true` \| `false` |
| androidScrollbarDraggable | Android 端滚动条是否可拖拽 | Boolean | `false` | `true` \| `false` |
| androidRefresherColor | Android 端下拉刷新默认样式颜色 | String | `''` | - |
| enableBackToTop | 点击状态栏回到顶部（iOS 端生效） | Boolean | `false` | `true` \| `false` |
| enablePassive | 是否开启 passive 滚动监听（仅 Web 端） | Boolean | Web 端 `true`，其他端 `false` | `true` \| `false` |
| padding | 预留参数（当前版本未启用） | Number[] | `[]` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 自定义根节点外部样式类 | String | `''` | - |

> 类型字段：SnRefresherParams（见 https://sinleui.pages.dev/api/types/component#snrefresherparams）

> 类型字段：SnLoadmoreParams（见 https://sinleui.pages.dev/api/types/component#snloadmoreparams）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| scrolltoupper | (e: UniScrollToUpperEvent) => Void | 滚动到顶部/左边时触发，同时内部复位下拉刷新条 |
| scrolltolower | (e: UniScrollToLowerEvent) => Void | 滚动到底部/右边时触发，开启 `loadmore` 时自动触发加载 |
| scroll | (e: UniScrollEvent) => Void | 滚动时触发 |
| scrollend | (e: UniScrollEvent) => Void | 滚动结束时触发（App 端） |
| refresherpulling | (e: UniRefresherEvent) => Void | 下拉刷新控件被下拉时触发 |
| refresherrefresh | (e: UniRefresherEvent) => Void | 下拉刷新被触发时触发，同时置位 `refresher-triggered` |
| refresherrestore | (e: UniRefresherEvent) => Void | 下拉刷新被复位时触发 |
| refresherabort | (e: UniRefresherEvent) => Void | 下拉刷新被中止时触发 |
| loadmore | () => Void | 触底或点击加载状态条时触发，仅在开启 `loadmore` 且状态为 `loadmore` 时生效，触发后状态自动变为 `loading` |
| click | () => Void | 点击列表区域时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| scrollTo | top: Number, left: Number（默认 0） | - | 滚动到指定位置（单位 px），Web 端带平滑动画 |
| setDirection | d: String | - | 同步设置滚动方向（`none` \| `horizontal` \| `vertical`），供手势组件同步禁滚/恢复滚动 |
| registerBacktop | update: (scrollTop: Number) => Void | - | 注册滚动位置更新回调，供 `sn-backtop` 绑定（一般无需手动调用） |
| startRefresh | - | - | 主动触发下拉刷新，进入刷新中状态并置位 `refresher-triggered` |
| stopRefresh | - | - | 结束下拉刷新，恢复可下拉状态并复位 `refresher-triggered` |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 作用域插槽，渲染每一条数据，作用域参数：`item`（当前数据项）、`index`（当前索引）；同 `type` 数据项共用此模板复用回收 |

<DemoPhone name="sn-list-view" />

# Refresher 下拉刷新

> [查看 sn-refresher 的 2.0 版本差异](/differences/components/sn-refresher)

## 基础用法

下拉刷新条，用于自定义滚动容器的下拉刷新样式，也可单独使用。

- 提供可下拉与刷新中两种显示状态，分别显示不同的图标与提示文本
- 在可下拉状态下点击刷新条同样会触发刷新

```vue
<template>
	<sn-refresher status="refresh"></sn-refresher>
</template>
```

**更多演示请下载 demo 查看**

## 双向绑定与交互控制

通过 `v-model:refresher-triggered` 双向绑定刷新状态，点击刷新条触发 `refresh` 事件；也可通过 `startRefresh` / `stopRefresh` 方法主动控制。

```vue
<template>
	<sn-refresher ref="refresherRef" v-model:refresher-triggered="triggered"
		status="refresh" refresh-text="点击我触发刷新" @refresh="onRefresh"></sn-refresher>
</template>

<script setup>
	const refresherRef = ref<SnRefresherComponentPublicInstance | null>(null)
	const triggered = ref<boolean>(false)
	function onRefresh(triggeredVal: boolean): void {
		triggered.value = triggeredVal
		setTimeout(() => {
			refresherRef.value?.$callMethod('stopRefresh')
		}, 1500)
	}
</script>
```

## 自定义图标与文本

图标名称、颜色、大小与两种状态文本均可自定义，颜色、尺寸支持 `$` 简写。

```vue
<template>
	<sn-refresher status="refresh" icon="arrow-down-circle-line" refresh-text="我就是我，不一样的烟火~"
		text-color="$success" icon-color="$success"></sn-refresher>
	<sn-refresher status="refreshing" refreshing-text="努力刷新吖..." text-size="$14" icon-size="$18"
		text-color="$primary" icon-color="$primary" custom-style="margin-top:12px;"></sn-refresher>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model:refresher-triggered | 绑定当前刷新状态，`true` 表示刷新已触发 | Boolean | `false` | `true` \| `false` |
| status | 显示状态 | String | `refresh` | `refresh` \| `refreshing` |
| icon | 未刷新状态下的图标名称 | String | `refresh-line` | - |
| refreshText | 未刷新状态下的文本提示 | String | `松开刷新` | - |
| refreshingText | 刷新中状态下的文本提示 | String | `刷新中` | - |
| textSize | 文本字体大小（支持 `$` 简写） | String \| Number | `$13` | - |
| iconSize | 图标大小（支持 `$` 简写） | String \| Number | `$14` | - |
| iconColor | 图标颜色（支持 `$` 简写） | String | `$lineText` | - |
| textColor | 文本颜色（支持 `$` 简写） | String | `$lineText` | - |
| hoverStopPropagation | 是否阻止点击态事件冒泡 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 自定义根节点外部样式类 | String | `''` | - |
| iconClass | 自定义图标节点外部样式类 | String | `''` | - |
| iconStyle | 自定义图标节点内联样式 | SnStyleValue | `''` | - |
| textClass | 自定义文本节点外部样式类 | String | `''` | - |
| textStyle | 自定义文本节点内联样式（默认带 6px 左边距） | SnStyleValue | `''` | - |
| loadingClass | 自定义刷新中加载动画节点外部样式类 | String | `''` | - |
| loadingStyle | 自定义刷新中加载动画节点内联样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| refresh | (triggered: boolean) => Void | `refresh` 状态下点击刷新条时触发，组件进入刷新中状态并置位 `refresher-triggered` |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| startRefresh | - | - | 主动开始刷新，切换到刷新中状态并置位 `refresher-triggered` |
| stopRefresh | - | - | 主动结束刷新，恢复可下拉状态并复位 `refresher-triggered` |

<DemoPhone name="sn-refresher" />

# Backtop 回到顶部

> [查看 sn-backtop 的 2.0 版本差异](/differences/components/sn-backtop)

## 基础用法

长页面 / 长列表的回到顶部按钮，滚动超过阈值后浮现。

- 自动绑定就近的滚动容器，无需额外配置，也可显式指定目标
- 页面级滚动时固定定位，容器内滚动时随容器定位
- 点击后平滑滚动回顶部

```vue
<template>
	<sn-page>
		<sn-backtop></sn-backtop>
	</sn-page>
</template>
```

**更多演示请下载 demo 查看**

## 绑定指定容器

`target` 可传滚动容器组件的 ref 名，或滚动容器元素的 id（Web 端也可传选择器）。为空时自动查找：先同级后父级。

```vue
<template>
	<sn-scroll-view ref="scrollRef" class="scroll-box">
		<sn-backtop target="scrollRef"></sn-backtop>
	</sn-scroll-view>
</template>
```

## 自定义样式

图标、形状、主题类型与等级、背景色、尺寸、位置、动画时长均可自定义；设置 `bg-color` 后覆盖 `type` 和 `level` 推导出的主题色。

```vue
<template>
	<sn-backtop type="warning" level="second" icon="arrow-up-line" size="60px" :right="90" :bottom="110"></sn-backtop>
	<sn-backtop type="info" shape="square" :right="160" :bottom="110"></sn-backtop>
</template>
```

## 实现原理

绑定 `sn-page`（页面级滚动）时按钮采用 `fixed` 定位，绑定容器内滚动时采用 `absolute` 定位；App 端回顶直接设置滚动容器的 `scrollTop` / `scrollLeft`，HarmonyOS 下同样适用。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| icon | 按钮内部图标 | String | `skip-up-line` | - |
| shape | 按钮形状 | String | `circle` | `circle` \| `square` |
| type | 主题样式类型 | String | `primary` | `info` \| `primary` \| `success` \| `error` \| `warning` |
| level | 等级，与 `type` 共同推导背景色和图标色 | String | `first` | `first` \| `second` \| `third` \| `least` |
| bgColor | 自定义背景颜色，设置后覆盖 `type` 和 `level` 的主题色 | String | `''` | - |
| iconColor | 图标颜色，按 `type` / `level` 配色矩阵推导 | String | - | - |
| iconSize | 图标大小（支持 `$` 简写） | String \| Number | `$20` | - |
| size | 按钮尺寸（支持 `$` 简写），圆形按钮圆角为尺寸的一半 | String \| Number | `50px` | - |
| zIndex | 按钮 `z-index` 层级 | Number | `991` | - |
| aniTime | 显示/隐藏过渡动画时长（支持 `$` 简写） | String \| Number | `$normal` | - |
| top | 滚动距离超过该值（单位 px）时显示按钮 | Number | `400` | - |
| right | 按钮距右边界距离（单位 px） | Number | `30` | - |
| bottom | 按钮距下边界距离（单位 px） | Number | `100` | - |
| disabled | 是否禁用，禁用时按钮变灰且不可点击 | Boolean | `false` | `true` \| `false` |
| target | 绑定目标：父作用域中滚动容器组件的 ref 名，或滚动容器元素 id/选择器；为空自动查找 | String | `''` | - |
| customStyle | 自定义按钮样式 | SnStyleValue | `''` | - |
| customClass | 自定义按钮外部样式类 | String | `''` | - |
| externalStyle | 额外内联样式 | SnStyleValue | `''` | - |
| externalClass | 额外外部样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| click | (e: UniPointerEvent) => Void | 点击按钮时触发（先执行回到顶部滚动，禁用时不触发） |

<DemoPhone name="sn-backtop" />

# Grid 宫格

> [查看 sn-grid 的 2.0 版本差异](/differences/components/sn-grid)

## 基础用法

宫格组件，用于同时展示多个同类项目，常作为首页「金刚区」入口。

- 子项按列数等分宽度并自动换行排列
- 列数可配置
- 末行子项不满一行时可指定对齐方式

```vue
<template>
	<sn-grid-group>
		<sn-grid-item>
			<sn-text text="项目1"></sn-text>
		</sn-grid-item>
		<sn-grid-item>
			<sn-text text="项目2"></sn-text>
		</sn-grid-item>
		<sn-grid-item>
			<sn-text text="项目3"></sn-text>
		</sn-grid-item>
		<sn-grid-item>
			<sn-text text="项目4"></sn-text>
		</sn-grid-item>
	</sn-grid-group>
</template>
```

**更多演示请下载 demo 查看**

## 间距与对齐

`gutter` 设置子项间距（间距非 0 时按容器实测宽度等分子项）；`align` 控制子项不满一行时的对齐方式。

```vue
<template>
	<sn-grid-group :col="5" gutter="12px">
		<sn-grid-item v-for="(item, index) in menuList" :key="index">
			<sn-icon :name="item.icon" :size="24" color="$primary"></sn-icon>
			<sn-text :font-size="12" :text="item.name"></sn-text>
		</sn-grid-item>
	</sn-grid-group>
	<sn-grid-group :col="4" gutter="10px" align="center">
		<sn-grid-item bg-color="$primaryLight">
			<sn-text text="居中项目"></sn-text>
		</sn-grid-item>
	</sn-grid-group>
</template>
```

宫格也可置于 `swiper`、`scroll-view` 内实现分页金刚区、横向滚动入口等布局（置于 `scroll-view` 时通过 `custom-style` 加宽容器并自定义列数）。

## 属性

**sn-grid-group**

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| col | 宫格布局列数 | Number | `4` | - |
| gutter | 子项间距，支持 `px`/`rpx`/`%` 数值字符串 | String | `0px` | - |
| align | 子项不满一行时的对齐方式 | String | `left` | `left` \| `start` \| `center` \| `right` \| `end` \| `around` \| `between` |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |

`gutter` 非 0 时，group 会测量自身宽度，将子项宽度按列数等分（px），子项左右各加 gutter/2 外边距；`align` 的 `start`/`end`/`around`/`between` 分别映射为对应的 flex 对齐值。

**sn-grid-item**

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| bgColor | 子项背景颜色 | String | `透明` | - |
| customStyle | 自定义子项根节点样式 | SnStyleValue | `''` | - |

## 插槽

**sn-grid-group**

| 名称 | 说明 |
| :--- | :--- |
| default | 在这里放置子组件 `sn-grid-item` |

**sn-grid-item**

| 名称 | 说明 |
| :--- | :--- |
| default | 子项内部放置内容 |

<DemoPhone name="sn-grid" />

# Drag 拖拽排序

## 基础用法

拖拽排序组件，通过双向绑定数组数据调整顺序。

- 长按子项后拖动即可调整顺序，其余子项自动让位
- 支持宫格模式与指定列数
- 支持开启删除区，拖入后松手即删除；也可仅允许通过手柄拖动

```vue
<template>
	<sn-drag v-model="list" @change="onChange">
		<sn-drag-item v-for="(item, index) in list" :key="item.id" :index="index">
			<view class="item">
				<text>{{ item.name }}</text>
			</view>
		</sn-drag-item>
	</sn-drag>
</template>
```

**更多演示请下载 demo 查看**

## 宫格模式与拖拽删除

```vue
<template>
	<sn-drag v-model="list" mode="grid" :column="3" deletable @delete="onDelete">
		<sn-drag-item v-for="(item, index) in list" :key="item.id" :index="index">
			<view class="grid-item">
				<text>{{ item.name }}</text>
			</view>
		</sn-drag-item>
	</sn-drag>
</template>
```

## 手柄拖动

提供 `handle` 插槽后，拖动不会占用内容区的点击交互（如开关、按钮），按住手柄可立即开始拖动，无需长按。

```vue
<template>
	<sn-drag v-model="list">
		<sn-drag-item v-for="(item, index) in list" :key="item.id" :index="index">
			<view class="item">
				<sn-switch v-model="item.enabled" />
				<text>{{ item.name }}</text>
			</view>
			<template #handle>
				<sn-icon name="menu-line" :size="22" color="$lineText" />
			</template>
		</sn-drag-item>
	</sn-drag>
</template>
```

## sn-drag 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定的列表数据，排序或删除完成后自动更新 | any[] | `[]` | - |
| mode | 子项排列模式 | String | `column` | `column` \| `grid` |
| column | 宫格模式的列数（mode 为 `grid` 时生效） | Number | `3` | - |
| deletable | 是否启用拖拽删除（拖动时底部出现删除区） | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用拖拽 | Boolean | `false` | `true` \| `false` |
| longPressTime | 长按触发拖拽的时长（毫秒） | Number | `350` | - |
| deleteBarHeight | 底部删除区高度 | String \| Number | `56px` | - |
| deleteText | 删除区默认文本 | String | `拖到此处删除` | - |
| deleteActiveText | 子项拖入删除区后的文本 | String | `松手删除` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| deleteClass | 自定义删除区样式类 | String | `''` | - |
| deleteStyle | 自定义删除区样式 | SnStyleValue | `''` | - |

## sn-drag-item 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| index | 子项在数据中的索引 | Number | `-（必填）` | - |
| disabled | 是否禁用该子项的拖拽 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义子项内容区样式 | SnStyleValue | `''` | - |
| contentClass | 自定义子项内容区样式类 | String | `''` | - |
| handleClass | 自定义手柄样式类 | String | `''` | - |
| handleStyle | 自定义手柄样式 | SnStyleValue | `''` | - |

## 事件

**sn-drag 事件**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: any[]) => Void | 排序或删除提交时触发，携带新顺序的数据数组 |
| delete | (index: Number) => Void | 子项被拖入删除区松手删除时触发，携带被删除项索引 |
| drag-start | (index: Number) => Void | 开始拖拽时触发，携带子项索引 |
| drag-end | (from: Number, to: Number) => Void | 拖拽结束时触发，携带起始索引与目标索引；`to` 为 -1 表示该项被删除 |

**sn-drag-item 事件**

无

## 插槽

**sn-drag 插槽**

| 名称 | 说明 |
| --- | --- |
| default | 放置 sn-drag-item 子项 |

**sn-drag-item 插槽**

| 名称 | 说明 |
| --- | --- |
| default | 子项内容 |
| handle | 拖拽手柄，提供后仅手柄可立即拖动，内容区保持正常交互 |

<DemoPhone name="sn-drag" />

# Gap 占位间隔

> [查看 sn-gap 的 2.0 版本差异](/differences/components/sn-gap)

## 基础用法

单纯用于占位的间隔组件。

- 通过高度控制占位大小
- 支持快速占位状态栏高度或底部安全区高度
- 背景颜色与圆角可配置

```vue
<template>
	<sn-gap height="20px"></sn-gap>
</template>
```

**更多演示请下载 demo 查看**

## 占位模式

`mode` 为 `statusbar` 或 `safearea` 时忽略 `height`，自动取系统状态栏 / 底部安全区高度。

```vue
<template>
	<sn-gap mode="statusbar" bg-color="$primaryLight"></sn-gap>
	<sn-gap mode="safearea" bg-color="$successLight"></sn-gap>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| mode | 占位间隔模式 | GapMode | `custom` | `custom` \| `statusbar` \| `safearea` |
| height | 占位间隔高度（仅 `mode` 为 `custom` 时生效），支持 `$` 简写 | String \| Number | `$20` | - |
| bgColor | 占位间隔背景颜色，支持 `$` 功能色简写 | String | `var(--sn-transparent)` | - |
| borderRadius | 占位间隔圆角大小，支持 `$` 简写 | String \| Number | - | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |

<DemoPhone name="sn-gap" />

# KeyboardTop 键盘上方区域

## 基础用法

把任意内容固定在系统键盘上方的容器组件，常用于评论输入栏、回复框与工具栏。

- 键盘未打开时整体隐藏，键盘弹出后吸附在键盘正上方并实时跟随高度变化
- 宽度默认铺满屏幕、高度由插槽内容撑开，背景与圆角等样式可自由定制
- 默认插槽下发键盘高度与聚焦状态，便于在区域内部自行布局与接管输入焦点

::: danger 必须放在 sn-page 下
组件根节点为 `fixed` 定位且不占文档流，需像弹出层一样直接放在页面根节点（`sn-page`）下，否则取不到 `sn-page` 注入的 `--sn-*` CSS 变量。
:::

```vue
<template>
	<sn-page>
		<!-- 页面内容 -->
		<sn-scroll-view>
			<sn-input v-model="comment" placeholder="说点什么…" :adjust-position="false" />
		</sn-scroll-view>

		<!-- 键盘上方区域：直接放在 sn-page 根节点下 -->
		<sn-keyboard-top>
			<view class="comment-bar">
				<sn-input v-model="comment" placeholder="说点什么…" :adjust-position="false" />
				<sn-button type="primary" @click="send">发送</sn-button>
			</view>
		</sn-keyboard-top>
	</sn-page>
</template>

<style lang="scss">
	.comment-bar {
		flex-direction: row;
		align-items: center;
		padding: 8px 12px;
		background-color: var(--sn-front);
		border-top-width: 1px;
		border-top-style: solid;
		border-top-color: var(--sn-line);
	}
</style>
```

**更多演示请下载 demo 查看**

## 自定义样式

宽度默认铺满屏幕，可用 `width` 直接改（如 `width="94%"`）；间距、圆角、背景、内边距建议直接写在插槽内容上，或通过 `customStyle` / `customClass` 定制根节点。

`offset` 用于在键盘顶部再让出一点距离（例如避开键盘自带的完成栏、候选词栏），支持 `$` 简写。

```vue
<template>
	<sn-keyboard-top width="94%" :offset="10" :z-index="995">
		<view class="toolbar">
			<sn-input v-model="text" placeholder="工具栏输入框…" :adjust-position="false" />
			<sn-button type="primary" @click="done">完成</sn-button>
		</view>
	</sn-keyboard-top>
</template>

<style lang="scss">
	.toolbar {
		flex-direction: row;
		align-items: center;
		padding: 8px 12px;
		background-color: var(--sn-front);
		border-radius: 15px 15px 0 0;
	}
</style>
```

## 过渡动画

键盘弹出时，区域从屏幕下方上滑并淡入；**取消显示（键盘收起、失去显示权或 `show` 为 false）时立即使节点不可见并移出屏幕，不做收起动画**，避免收起过程与键盘动画叠加产生残影。

`aniTime` 控制淡入时长（支持 `$` 简写，随 `aniTimeFactor` 缩放），为空时使用框架标准时长；传 `0` 则显隐都无过渡。

隐藏态位移按**实测像素高度**计算（组件挂载后与隐藏时测量自身高度），不使用百分比终点——uni-app x 的 `transition` 不支持结束属性值为百分比，用百分比会让 App 端动画退化为瞬跳。

```vue
<template>
	<sn-keyboard-top ani-time="$400">…</sn-keyboard-top>
</template>
```

## 多个实例

**建议同一时间只显示一个实例**。组件**不做多实例仲裁**——同一页面若同时显示多个 `sn-keyboard-top`，它们会重叠吸附在键盘上方（可用 `zIndex` 与 `offset` 自行错开，但不推荐）。需要多个面板切换时，用 `show` 控制只保留一个：

```vue
<template>
	<sn-page>
		<sn-button @click="showPanel('comment')">评论栏</sn-button>
		<sn-button @click="showPanel('reply')">回复框</sn-button>

		<!-- 三个实例常驻，用 show 控制同一时间只显示一个 -->
		<sn-keyboard-top :show="panel == 'comment'">
			<view class="comment-bar">…</view>
		</sn-keyboard-top>

		<sn-keyboard-top :show="panel == 'reply'">
			<view class="reply-bar">…</view>
		</sn-keyboard-top>
	</sn-page>
</template>
```

## 插槽作用域

默认插槽会实时下发键盘高度与聚焦状态，方便在区域内部自行展示、布局与接管输入框焦点：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| keyboardHeight | Number | 当前键盘高度（px） |
| show | Boolean | 本实例当前是否显示中 |
| focus | Boolean | 是否应聚焦区域内输入框（由 `requestFocus` 驱动，初始为 `false`，避免组件显示时重复请求聚焦造成键盘闪动） |
| requestFocus | () => Void | 主动请求聚焦区域内输入框（走 `false` → `nextTick` → `true`，保证原生能识别到 focus 变化） |

区域内输入框建议这样绑定，焦点由 `requestFocus` 统一驱动，避免出现“输入框点不动、无占位文本”：

```vue
<template>
	<sn-keyboard-top ref="panelRef">
		<template v-slot:default="slotProps">
			<sn-input v-model="text" :focus="slotProps.focus" :hold-keyboard="true" placeholder="说点什么…" />
		</template>
	</sn-keyboard-top>
</template>
```

显示/切换面板时调用组件实例方法请求聚焦：`panelRef.value?.$callMethod('requestFocus')`。

> 注意不要在组件“显示中”时反复调用 `requestFocus`：`focus` 会先变 `false` 让原生输入框失焦、下一帧再变 `true` 重新聚焦，期间键盘会收起再弹出（肉眼可见闪动）。同一面板显示期间只需调用一次。

## 使用注意

### 推荐架构：页面内只读触发器 + 区域内的真实输入框

页面内的输入框设为 `readonly` 作为**触发器**（点击它不自己聚焦，而是让区域内的输入框获得焦点），两处用同一个 `v-model` 同步值。这样键盘始终属于区域内那一个输入框，能同时满足：

- 点击**区域内的空白处**不收起键盘（区域内输入框开启 `hold-keyboard`）；
- 点击**页面其他位置**正常收起键盘；
- 切到二级面板（如回复框）时焦点自然转移，不会出现区域内输入框“点不动、无占位文本”的情况。

```vue
<template>
	<sn-page>
		<!-- 页面内的只读触发器 -->
		<view class="trigger" @click="openPanel">
			<sn-input v-model="text" :readonly="true" :adjust-position="false" placeholder="说点什么…" />
		</view>

		<sn-keyboard-top ref="panelRef">
			<template v-slot:default="slotProps">
				<sn-input v-model="text" :focus="slotProps.focus" :hold-keyboard="true" placeholder="说点什么…" />
			</template>
		</sn-keyboard-top>
	</sn-page>
</template>

<script setup lang="ts">
	import type { ComponentPublicInstance } from 'vue'

	const text = ref<string>('')
	const panelRef = ref<ComponentPublicInstance | null>(null)

	function openPanel(): void {
		panelRef.value?.$callMethod('requestFocus')
	}
</script>
```

注意触发器的 `adjust-position` 要设为 `false`：触发器本身不承载输入，若保持默认 `true`，键盘弹出时原生会滚动页面上推该输入框，出现“打开键盘页面滚动、收起又滚回”的现象。

### 其它注意

- 区域内的输入框建议设置 `:hold-keyboard="true"`：uni-app x App-Android 平台下点击输入框以外的屏幕会自动收起软键盘；开启后点击区域内空白处键盘保留（**注意**：未采用上面的只读触发器方案时，`hold-keyboard` 也会让点击页面其他位置同样无法收起键盘，此时需自行调用 `uni.hideKeyboard()`）。
- 区域内的 `sn-input` / `sn-textarea` 建议设置 `:adjust-position="false"`，由组件自身负责吸附，避免原生页面二次上推导致位置抖动。
- 插槽内使用 `textarea` 时建议设置 `fixed`（`sn-textarea` 的 `fixed` 属性）以获得更好的原生表现。
- 需要“紧贴键盘”时 `offset` 保持默认 `0`；键盘自带完成栏/候选栏时可用 `offset` 让位。
- Android / iOS / 微信小程序依赖 `uni.onKeyboardHeightChange`（HBuilderX 4.71+，鸿蒙 5.08+）；Web 端该 API 不支持，组件自动使用 `visualViewport` 降级测量，桌面浏览器无软键盘时区域不会显示。
- 组件为 `fixed` 定位不占文档流，页面最后一块内容可能被面板遮住；**预留空白必须放在滚动内容末尾**（如末尾加一个 `height:60px` 的占位 `view`），不要写成 `sn-page` 的 `custom-style="padding-bottom:..."`——`sn-page` 根节点包着 `scroll-view`，padding 落在滚动容器之外会形成一条永远存在的固定空白带。

## 实现原理

键盘高度采用全局监听，同一页面只注册一次，监听值归零即视为键盘收起。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| aniTime | 显隐过渡动画时长（支持 `$` 简写） | String \| Number | `$normal` | - |
| zIndex | 键盘上方区域的 `z-index` 层级 | Number | `990` | - |
| offset | 距离键盘顶部的额外偏移（支持 `$` 简写，用于避开键盘自带的完成栏等） | String \| Number | `0` | - |
| width | 键盘上方区域宽度（支持 `$` 简写） | String \| Number | `100%` | - |
| show | 是否允许显示，设为 `false` 时即使键盘打开也不显示 | Boolean | `true` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 自定义根节点外部样式类 | String | `''` | - |
| externalStyle | 额外内联样式 | SnStyleValue | `''` | - |
| externalClass | 额外外部样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (visible: boolean) => Void | 键盘上方区域显示状态变化时触发（键盘弹出收起、`show` 变化时触发） |

## 插槽

| 名称 | 作用域参数 | 说明 |
| --- | --- | --- |
| default | `keyboardHeight`（键盘高度 px）、`show`（是否显示中）、`focus`（是否应聚焦输入框）、`requestFocus`（主动请求聚焦） | 区域内容 |

<DemoPhone name="sn-keyboard-top" />

# Float Board 浮动面板

> [查看 sn-float-board 的 2.0 版本差异](/differences/components/sn-float-board)

## 基础用法

固定吸附在屏幕四边之一的浮动面板，始终显示。

- 通过手势拖拽在折叠与展开状态之间切换，松手后按滑动距离自动归位
- 组件为固定定位，不占据文档流空间

::: info 与 sn-drawer 的区别
`sn-drawer` 是弹出层，需要调用方法才能显示；`sn-float-board` 始终显示。可理解为：`sn-drawer` 是关闭的浮动面板，`sn-float-board` 是半开的浮动面板。
:::

::: info 预留空隙
组件不占据文档流空间，请在页面底部为面板折叠后的空隙预留位置（如使用 `sn-gap`）。
:::

```vue
<template>
	<sn-float-board>
		<sn-text text="Float Board 浮动面板"></sn-text>
	</sn-float-board>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| position | 浮动面板吸附的位置，非法值回退为 `bottom` | String | `bottom` | `top` \| `right` \| `bottom` \| `left` |
| showLine | 是否显示指示条 | Boolean | `true` | `true` \| `false` |
| maxWidth | 当 `position` 为 `left` \| `right` 且展开时浮动面板的宽度，支持 `$` 前缀按间距乘数缩放 | String | `300px` | - |
| minWidth | 当 `position` 为 `left` \| `right` 且折叠时浮动面板的宽度，支持 `$` 前缀按间距乘数缩放 | String | `50px` | - |
| maxHeight | 当 `position` 为 `top` \| `bottom` 且展开时浮动面板的高度，支持 `$` 前缀按间距乘数缩放 | String | `500px` | - |
| minHeight | 当 `position` 为 `top` \| `bottom` 且折叠时浮动面板的高度，支持 `$` 前缀按间距乘数缩放 | String | `50px` | - |
| slideHeight | 纵向滑动阈值，松手时滑动距离达到阈值则折叠或展开，支持 `$` 前缀按间距乘数缩放 | String | `100px` | - |
| slideWidth | 横向滑动阈值，松手时滑动距离达到阈值则折叠或展开，支持 `$` 前缀按间距乘数缩放 | String | `100px` | - |
| bgColor | 浮动面板背景颜色 | String | `$infoActive` | - |
| lineColor | 指示条颜色 | String | `$lineText` | - |
| padding | 面板内容区内边距（传给内部 sn-view） | String | `25px 15px 10px 15px` | - |
| borderRadius | 面板圆角大小，为随圆角乘数计算的默认圆角（四个直角侧自动贴合屏幕边缘） | String \| Number | - | - |
| aniTime | 展开/折叠动画时长，支持 `$` 动态时长语法 | String \| Number | `$long` | - |
| disabled | 是否禁用滑动手势 | Boolean | `false` | `true` \| `false` |
| zIndex | 面板层级 | Number | `999` | - |
| customStyle | 自定义浮动面板样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| unfold | () => Void | 展开浮动面板时触发 |
| fold | () => Void | 折叠浮动面板时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| unfold | - | - | 展开浮动面板 |
| fold | - | - | 折叠浮动面板 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 在浮动面板内部放置组件 |

<DemoPhone name="sn-float-board" />

# Float Button 浮动按钮

> [查看 sn-float-button 的 2.0 版本差异](/differences/components/sn-float-button)

## 基础用法

固定定位的悬浮按钮，可用于悬浮操作入口、回到顶部等场景。

- 支持八方位预设位置，也可自由拖动，松手后自动吸附至左右两侧
- 按钮当前位置支持双向绑定，位置变化时派发事件
- Web 端支持鼠标拖动，窗口尺寸变化时自动重新校正位置

```vue
<template>
	<sn-float-button icon="add-line" bg-color="$primary"></sn-float-button>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 按钮当前位置坐标，形如 `[x, y]` | `Array<Number>` | `[0, 0]` | - |
| position | 预设位置（`init` 为 true 时初始化定位至此） | String | `bottom` | `top-start` \| `top` \| `top-end` \| `right` \| `bottom-end` \| `bottom` \| `bottom-start` \| `left` |
| init | 是否在初始化时定位到 `position` 预设位置 | Boolean | `true` | `true` \| `false` |
| absorb | 松手后是否自动吸附至左右两侧 | Boolean | `true` | `true` \| `false` |
| disabled | 是否禁用（禁用后不可拖动、不响应点击） | Boolean | `false` | `true` \| `false` |
| bgColor | 背景颜色，支持 `$` 简写 | String | `$front` | - |
| size | 按钮尺寸（宽高相同） | String \| Number | `60px` | - |
| icon | 内置图标名称 | String | `''` | - |
| iconColor | 图标颜色，支持 `$` 简写，禁用时为禁用色 | String | `$text` | - |
| iconSize | 图标字体大小 | String \| Number | `$30` | - |
| margin | 处于预设位置或吸附时与屏幕边缘的边距 | Number | `20` | - |
| borderRadius | 圆角大小 | String \| Number | `$12000` | - |
| boxShadow | 阴影 | String | `0 0 15px -10px` | - |
| aniTime | 拖动松手 / 吸附时的过渡动画时长 | String \| Number | `$long` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| click | (event: UniPointerEvent) => Void | 点击按钮时触发（禁用时不触发） |
| change | `(position: Array<Number>) => Void` | 初始化定位或拖动结束时触发，携带当前位置坐标 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 替换按钮内部默认的图标 |

<DemoPhone name="sn-float-button" />

# Swipe Action 滑动操作

> [查看 sn-swipe-action 的 2.0 版本差异](/differences/components/sn-swipe-action)

## 基础用法

列表项的滑动操作组件：左滑露出右侧操作区，右滑露出左侧操作区。

- 操作区宽度由插槽内容自动决定，可放置任意自定义内容
- 左右操作区与主体内容自动等高（以主体内容高度为准），Web 端支持鼠标拖动
- 多个滑动操作自动联动：打开一个自动收起其他，点击内容区收起全部

::: danger 插槽布局注意
- 使用注意：请勿给 `left` / `right` 插槽的根节点设置 `height: 100%`，也无需为操作区指定高度，`align-self: stretch` 即可铺满
- 使用注意：插槽根节点请勿对 `height` / `width` 等布局属性开启过渡动画（`transition-property: all` 同样包含布局属性），布局变化时会触发异常的尺寸动画；如需过渡动画仅限 `background-color` 等非布局属性
:::

```vue
<template>
	<sn-swipe-action>
		<view class="content">
			<text>滑动显示操作</text>
		</view>
		<template #right>
			<view class="action-button" @click="onEdit">编辑</view>
			<view class="action-button" @click="onDelete">删除</view>
		</template>
	</sn-swipe-action>
</template>

<style>
.content {
	padding: 14px;
	background-color: var(--sn-front);
}

.action-button {
	width: 60px;
	align-self: stretch;
	flex-direction: column;
	align-items: center;
	justify-content: center;
}
</style>
```

**更多演示请下载 demo 查看**

## 异步确认关闭

设置 `before-close` 后，在展开状态下点击主体内容时会先调用该回调，Promise resolve `true` 才会收起操作区。

```vue
<template>
	<sn-swipe-action :before-close="beforeClose">
		<view class="content">
			<text>确认后才会收起操作区</text>
		</view>
		<template #right>
			<view class="action-button" @click="onDelete">删除</view>
		</template>
	</sn-swipe-action>
</template>
```

## 主动控制

通过实例方法 `open` / `close` 控制展开与收起，`open` 参数为露出的操作区方向。

```vue
<template>
	<sn-swipe-action ref="action">
		<view class="content">
			<text>可编程控制的操作项</text>
		</view>
		<template #right>
			<view class="action-button" @click="onDelete">删除</view>
		</template>
	</sn-swipe-action>
</template>
<script lang="ts" setup>
	const action = ref<SnSwipeActionComponentPublicInstance | null>(null)

	function openLeft() {
		action.value?.$callMethod('open', 'left')
	}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| disabled | 是否禁用滑动操作 | Boolean | `false` | `true` \| `false` |
| threshold | 默认打开阈值：松手时滑过操作区宽度的该比例即吸附打开（openThreshold 为空时生效） | Number | `0.4` | - |
| openThreshold | 自定义打开阈值，支持百分比（如 `20%`）、像素（如 `60px`）或数字（按 px 处理），跟随 `threshold` | String \| Number | - | - |
| beforeClose | 关闭前的确认回调，返回 Promise，resolve `true` 才会收起操作区；参数 direction 为当前露出的操作区方向 | (direction: string) => Promise&lt;boolean&gt; \| null | `null` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 自定义根节点样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| open | (direction: string) => Void | 操作区打开时触发，direction 为露出的操作区方向：`left` 左侧（右滑）、`right` 右侧（左滑） |
| close | () => Void | 操作区关闭时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | direction: string | - | 打开指定方向的操作区（`left` 左侧 / `right` 右侧） |
| close | - | - | 关闭操作区 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 主体内容 |
| left | 左侧操作区（右滑露出） |
| right | 右侧操作区（左滑露出） |

<DemoPhone name="sn-swipe-action" />

# Loadmore 加载更多

> [查看 sn-loadmore 的 2.0 版本差异](/differences/components/sn-loadmore)

## 基础用法

用于标识页面底部加载数据时的状态。

- 提供加载更多、加载中、没有更多三种状态，加载更多状态可点击触发事件
- 两侧线条支持实线与虚线

::: info 平台差异
加载状态文案保留独立的文字节点，兼容 HarmonyOS 原生绘制。
:::

```vue
<template>
	<sn-loadmore @loadmore="onLoadmore"></sn-loadmore>
</template>
```

**更多演示请下载 demo 查看**

加载状态文案保留独立的文字节点，兼容 HarmonyOS 原生绘制。

## 加载状态切换

配合列表加载流程切换 `status`：点击加载更多后进入加载中，数据加载完毕后标记为没有更多。

```vue
<template>
	<sn-loadmore :status="status" @loadmore="onLoadmore"></sn-loadmore>
</template>

<script setup>
	const status = ref<string>('loadmore')
	function onLoadmore(): void {
		status.value = 'loading'
	}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| status | 加载状态 | String | `loadmore` | `loadmore` \| `loading` \| `nomore` |
| loadmoreText | loadmore 状态显示的文本 | String | `加载更多` | - |
| nomoreText | nomore 状态显示的文本 | String | `没有更多了` | - |
| loadingText | loading 状态显示的文本 | String | `加载中` | - |
| textSize | 文本字体大小 | String \| Number | `$13` | - |
| iconSize | 加载指示器大小，与文本字号一致 | String \| Number | - | - |
| iconColor | 加载指示器颜色 | String | `$primary` | - |
| textColor | 文本颜色 | String | `$lineText` | - |
| lineColor | 两侧线条颜色 | String | `$line` | - |
| lineHeight | 两侧线条粗细 | String \| Number | `0.5px` | - |
| disabled | 是否禁用，禁用时 loadmore 状态点击不触发事件 | Boolean | `false` | `true` \| `false` |
| dashed | 两侧线条是否为虚线 | Boolean | `false` | `true` \| `false` |
| loadingClass | 自定义 loading 指示器节点外部样式类 | String | - | - |
| loadingStyle | 自定义 loading 指示器节点内联样式 | SnStyleValue | `border-color: <主题线条文本色>` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| loadmore | () => Void | 点击加载更多时触发（仅 status 为 `loadmore` 且未禁用时响应） |

<DemoPhone name="sn-loadmore" />

# Pagination 分页器

## 基础用法

分页器，用于列表内容的分页导航。

- 当前页码支持双向绑定，总页数可直接指定，也可由数据总条数自动计算
- 页码较多时自动显示省略号，实际展示的页码按钮数量可配置
- 支持整体禁用所有按钮与跳转输入框

```vue
<template>
	<sn-pagination v-model:page="page" :page-count="20"></sn-pagination>
</template>

<script lang="ts" setup>
	const page = ref<number>(1)
</script>
```

**更多演示请下载 demo 查看**

## 快速跳转

开启 `showQuickJumper` 后显示跳转输入框，输入页码后回车或失焦生效，超出范围自动收敛。可通过 `goto` 插槽自定义输入框前的提示文字。

```vue
<template>
	<sn-pagination v-model:page="page" :page-count="100" show-quick-jumper>
		<template #goto>前往</template>
	</sn-pagination>
</template>
```

## 简单模式

`simple` 设为 true 时仅显示“当前页 / 总页数”，配合 `showQuickJumper` 可直接输入页码跳转。

```vue
<template>
	<sn-pagination v-model:page="page" :page-count="100" simple show-quick-jumper></sn-pagination>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model:page | 当前页码 | Number | `1` | - |
| v-model:page-size | 每页条数，与 `itemCount` 配合自动计算总页数 | Number | `10` | - |
| pageCount | 总页数；取值不大于 1 时若 `itemCount` 大于 0，则按 `itemCount` / `pageSize` 向上取整自动计算 | String \| Number | `1` | - |
| pageSlot | 页码按钮最大显示数量（含省略号占位） | String \| Number | `5` | - |
| itemCount | 数据总条数，用于自动计算总页数 | String \| Number | `-1` | - |
| simple | 简单模式，仅显示“当前页 / 总页数” | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用 | Boolean | `false` | `true` \| `false` |
| showQuickJumper | 是否显示快速跳转输入框（回车或失焦生效） | Boolean | `false` | `true` \| `false` |
| showPrevNext | 是否显示上一页 / 下一页按钮 | Boolean | `true` | `true` \| `false` |
| buttonType | 页码按钮与翻页按钮的功能色类型 | String | `info` | `primary` \| `info` \| `success` \| `error` \| `warning` |
| buttonLevel | 页码按钮与翻页按钮的等级 | String | `first` | `first` \| `second` \| `third` \| `least` |
| size | 页码按钮宽高（正方形），同时决定跳转输入框高度 | String \| Number | `$35` | - |
| gap | 按钮之间的间距 | String \| Number | `4` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |
| customClass | 根节点自定义样式类 | String | `''` | - |
| pageClass | 页码按钮与翻页按钮的自定义样式类 | String | `''` | - |
| pageStyle | 页码按钮与翻页按钮的自定义样式 | SnStyleValue | `''` | - |
| activePageClass | 当前页码按钮的自定义样式类 | String | `''` | - |
| activePageStyle | 当前页码按钮的自定义样式 | SnStyleValue | `''` | - |
| buttonTextClass | 页码、省略号与翻页按钮文字的自定义样式类 | String | `''` | - |
| buttonTextStyle | 页码、省略号与翻页按钮文字的自定义样式 | SnStyleValue | `line-height: 1;` | - |
| simpleTextClass | 简单模式文字的自定义样式类 | String | `''` | - |
| simpleTextStyle | 简单模式文字的自定义样式 | SnStyleValue | `''` | - |
| jumperClass | 跳转区域的自定义样式类 | String | `''` | - |
| jumperStyle | 跳转区域的自定义样式 | SnStyleValue | `''` | - |
| jumperInputClass | 跳转输入框的自定义样式类 | String | `''` | - |
| jumperInputStyle | 跳转输入框的自定义样式 | SnStyleValue | `''` | - |

## 插槽

| 名称 | 说明 |
| --- | --- |
| prefix | 分页器最前部的附加内容 |
| suffix | 分页器最后部的附加内容 |
| prev | 替换上一页按钮内容（默认为左箭头图标） |
| next | 替换下一页按钮内容（默认为右箭头图标） |
| goto | 快速跳转输入框前的提示文字（默认为“跳至”），仅非简单模式生效 |

<DemoPhone name="sn-pagination" />

# Waterflow 瀑布流

> [查看 sn-waterflow 的 2.0 版本差异](/differences/components/sn-waterflow)

## 基础用法

数据驱动的瀑布流组件，按多列排布不定高条目，支持下拉刷新与滚动加载。

- 数据由数组传入，通过默认作用域插槽渲染每条内容
- 内置下拉刷新、加载更多与回到顶部按钮
- 支持自定义列数与行列间距，Web 端可按容器宽度自适应列数

::: danger type 保留值
App 端条目按数据项 `type` 字段分组复用，其中下拉刷新条目占用 `2`、加载更多条目占用 `6`，业务数据请避开这两个值。
:::

::: info 插槽 item 类型
插槽的 `item` 为 `any` 类型，对象的字段访问需在函数体内 `as` 强转后使用，不要直接在模板内访问属性。
:::

```vue
<template>
	<sn-waterflow :list="items" :cross-axis-count="2" cross-axis-gap="10" main-axis-gap="12"
		refresher-enabled v-model:refresher-triggered="refresherTriggered"
		loadmore v-model:loadmore-status="loadmoreStatus" backtop
		@refresh="onRefresh" @loadmore="onLoadmore">
		<template v-slot:default="slotProps">
			<view class="flow-card" :style="cardStyle(slotProps.item)">
				<sn-text bold color="$primaryText">{{ flowTitle(slotProps.item) }}</sn-text>
			</view>
		</template>
	</sn-waterflow>
</template>

<script setup>
	type FlowItem = {
		title: string
		height: number
	}
	function flowTitle(item: any): string {
		return (item as FlowItem).title
	}
	function cardStyle(item: any): Map<string, any> {
		const styles = new Map<string, any>()
		styles.set('height', `${(item as FlowItem).height}px`)
		styles.set('background-color', 'var(--sn-primaryLight)')
		styles.set('border-radius', '10px')
		return styles
	}
</script>
```

**更多演示请下载 demo 查看**

## 实现原理

App 端基于官方 `waterflow` 组件，条目以 `flow-item` 复用回收；Web 端为自研虚拟滚动瀑布流，动态测量条目高度，仅渲染可视区域及 `overscan` 范围内的条目。内置的下拉刷新、加载更多与回到顶部按钮分别由 `sn-refresher`、`sn-loadmore`、`sn-backtop` 实现。

## 自定义列数与响应式断点

- `cross-axis-count` 控制基础列数（最小为 1）。
- Web 端支持两种自适应方式：`col-width` 大于 0 时按容器宽度与列宽计算实际列数（不超过 `cross-axis-count`）；`breakpoints` 传入响应式断点数组（`minWidth` 容器最小宽度、`columns` 对应列数），取容器宽度匹配到的最后一项。

```vue
<template>
	<sn-waterflow :list="items" :cross-axis-count="3" cross-axis-gap="8" main-axis-gap="10"
		:col-width="140" :estimated-item-height="180" :overscan="200">
		<template v-slot:default="slotProps">
			<view class="flow-card">
				<sn-text :text="flowTitle(slotProps.item)"></sn-text>
			</view>
		</template>
	</sn-waterflow>
</template>
```

## 无限加载

- `loadmore` 开启后触底自动触发 `loadmore` 事件（App 端与 Web 端均为滚动接近底部时触发，触发距离由 `lower-threshold` 控制）。
- 无限滚动场景可将 `show-loadmore` 设为 `false` 隐藏底部加载状态条，加载逻辑照常生效。

```vue
<template>
	<sn-waterflow :list="items" :cross-axis-count="2" :lower-threshold="4000"
		loadmore :show-loadmore="false" v-model:loadmore-status="loadmoreStatus"
		@loadmore="onLoadmore">
		<template v-slot:default="slotProps">
			<view class="flow-card">
				<sn-text :text="flowTitle(slotProps.item)"></sn-text>
			</view>
		</template>
	</sn-waterflow>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| list | 列表数据数组，数据项可为任意对象，App 端支持 `type` 数字字段声明复用分组 | Array | `[]` | - |
| crossAxisCount | 列数 | Number | `2` | - |
| crossAxisGap | 列间距（支持 `$` 简写） | String \| Number | `10px` | - |
| mainAxisGap | 行间距（支持 `$` 简写） | String \| Number | `10px` | - |
| colWidth | 单列基准宽度（单位 px，Web 端生效；大于 0 时按容器宽度自适应实际列数，不超过 `crossAxisCount`） | Number | `0` | - |
| estimatedItemHeight | 条目预估高度（单位 px，Web 端虚拟滚动初始布局用，实际高度测量后自动修正） | Number | `280` | - |
| overscan | 虚拟滚动预渲染范围（单位 px，Web 端生效） | Number | `400` | - |
| breakpoints | 响应式断点数组（Web 端生效），每项含 `minWidth`（容器最小宽度）与 `columns`（对应列数） | SnWaterflowBreakpoint[] | `[]` | - |
| v-model:refresher-triggered | 绑定当前下拉刷新状态 | Boolean | `false` | `true` \| `false` |
| v-model:loadmore-status | 绑定加载更多组件状态，触底或点击加载更多时组件内部自动改写为 `loading`，由父组件在 `loadmore` 事件中更新加载结果 | String | `loadmore` | `loadmore` \| `loading` \| `nomore` |
| refresherEnabled | 是否开启下拉刷新 | Boolean | `false` | `true` \| `false` |
| refresherConfig | 下拉刷新组件配置（`refreshText`、`refreshingText`、`textSize`、`textColor`、`icon`、`iconSize`、`iconColor`） | `SnRefresherParams` | `{}` | - |
| refresherThreshold | 下拉刷新阈值（单位 px） | Number | `45` | - |
| refresherMaxDragDistance | 下拉最大拖拽距离（单位 px） | Number | `0` | - |
| refresherBackground | 下拉刷新区域背景颜色 | String | `transparent` | - |
| refresherDefaultStyle | 下拉刷新默认样式；开启下拉刷新时组件强制使用自定义刷新条 | String | `black` | `white` \| `black` \| `none` |
| loadmore | 是否开启加载更多 | Boolean | `true` | `true` \| `false` |
| showLoadmore | 是否显示底部加载状态条（为 `false` 时隐藏条目但加载逻辑照常生效） | Boolean | `true` | `true` \| `false` |
| loadmoreConfig | 加载更多组件配置（`loadmoreText`、`nomoreText`、`loadingText`、`textSize`、`textColor`、`iconSize`、`iconColor`、`lineHeight`、`lineColor`、`dashed`、`disabled`） | `SnLoadmoreParams` | `{}` | - |
| backtop | 是否内置回到顶部按钮 | Boolean | `false` | `true` \| `false` |
| backtopTarget | 内置回到顶部按钮的绑定目标（ref 名或元素 id） | String | `''` | - |
| backtopTop | 内置回到顶部按钮的显示阈值（滚动距离，单位 px） | Number | `400` | - |
| backtopRight | 内置回到顶部按钮距右边界距离（单位 px） | Number | `30` | - |
| backtopBottom | 内置回到顶部按钮距下边界距离（单位 px） | Number | `100` | - |
| bounces | 是否启用回弹效果（App 端） | Boolean | `true` | `true` \| `false` |
| associativeContainer | 关联的滚动容器（App 端嵌套滚动场景使用） | String | `''` | - |
| maxCrossAxisExtent | 单列最大宽度（单位 px，超过则自动增加列数；iOS / HarmonyOS 端生效） | String \| Number | `0` | - |
| upperThreshold | 距顶部多远时（单位 px）触发 `scrolltoupper` 事件 | Number | `50` | - |
| lowerThreshold | 距底部多远时（单位 px）触发 `scrolltolower` 事件并触发加载更多 | Number | `50` | - |
| scrollTop | 设置竖向滚动条位置 | Number | `0` | - |
| scrollLeft | 设置横向滚动条位置 | Number | `0` | - |
| scrollIntoView | 值应为某子元素 id（id 不能以数字开头），滚动到该元素 | String | `''` | - |
| scrollWithAnimation | 设置滚动条位置时是否使用滚动动画 | Boolean | `true` | `true` \| `false` |
| showScrollbar | 是否显示滚动条 | Boolean | `true` | `true` \| `false` |
| androidOverscroll | Android 端是否开启弹簧回弹效果 | Boolean | `false` | `true` \| `false` |
| androidScrollbarDraggable | Android 端滚动条是否可拖拽 | Boolean | `false` | `true` \| `false` |
| androidRefresherColor | Android 端下拉刷新默认样式颜色 | String | `''` | - |
| enableBackToTop | 点击状态栏回到顶部（iOS 端生效） | Boolean | `false` | `true` \| `false` |
| enablePassive | Web 端原生滚动监听是否使用 passive 模式 | Boolean | Web 端 `true`，其他端 `false` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 自定义根节点外部样式类 | String | `''` | - |

> 类型字段：SnRefresherParams（见 https://sinleui.pages.dev/api/types/component#snrefresherparams）

> 类型字段：SnLoadmoreParams（见 https://sinleui.pages.dev/api/types/component#snloadmoreparams）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| refresh | () => Void | 下拉刷新被触发时触发（下拉手势或调用 `refresh` 方法），App 端与 `refresherrefresh` 同步触发 |
| scrolltoupper | (e: UniScrollToUpperEvent) => Void | 滚动到顶部时触发，同时内部复位下拉刷新条（App 端） |
| scrolltolower | (e: UniScrollToLowerEvent) => Void | 滚动到底部时触发，开启 `loadmore` 时自动触发加载（App 端） |
| scroll | (e: UniScrollEvent) => Void | 滚动时触发（App 端） |
| scrollend | (e: UniScrollEvent) => Void | 滚动结束时触发（App 端） |
| refresherpulling | (e: UniRefresherEvent) => Void | 下拉刷新控件被下拉时触发（App 端） |
| refresherrefresh | (e: UniRefresherEvent) => Void | 下拉刷新被触发时触发（App 端） |
| refresherrestore | (e: UniRefresherEvent) => Void | 下拉刷新被复位时触发（App 端） |
| refresherabort | (e: UniRefresherEvent) => Void | 下拉刷新被中止时触发（App 端） |
| loadmore | () => Void | 触底或点击加载状态条时触发，仅在开启 `loadmore` 且状态为 `loadmore` 时生效，触发后状态自动变为 `loading`（App / Web 端均生效） |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| scrollTo | top: Number, left: Number（默认 0） | - | 滚动到指定位置（单位 px），Web 端带平滑动画 |
| refresh | - | - | 主动触发下拉刷新，进入刷新中状态并置位 `refresher-triggered`，同时触发 `refresh` 事件 |
| stopRefresh | - | - | 结束下拉刷新，恢复可下拉状态并复位 `refresher-triggered` |
| loadMore | - | - | 主动触发一次加载更多（等同触底效果） |
| registerBacktop | update: (scrollTop: Number) => Void | - | 注册滚动位置更新回调，供 `sn-backtop` 绑定（一般无需手动调用） |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 作用域插槽，渲染每一条数据，作用域参数：`item`（当前数据项）、`index`（当前索引）；App 端同 `type` 数据项共用此模板复用回收 |

<DemoPhone name="sn-waterflow" />

# Footer 页脚

## 基础用法

页脚组件，常用于页面底部展示品牌 Logo、导航链接与版权信息。

- Logo、链接与版权三部分均可选，按需组合
- Logo 支持图标名或图片路径，地址按形态自动识别为图片
- 链接间自动添加竖向分隔线，点击链接 / Logo 后按打开方式自动跳转

```vue
<template>
	<sn-footer text="Copyright © 2026 SinleUI. All Rights Reserved."></sn-footer>
</template>
```

**更多演示请下载 demo 查看**

## 注意事项

Logo 图标支持图标名或图片路径：`http` 开头、以 `/`、`./`、`../` 开头或包含 `.` 的地址按图片处理。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| links | 导航链接列表，字段见下方 `SnFooterLink` | Array<`SnFooterLink`> | `[]` | - |
| logo | 品牌 Logo 配置，字段见下方 `SnFooterLogo` | `SnFooterLogo` | `null` | - |
| text | 页脚文字（一般为版权信息） | String | `''` | - |
| color | Logo 标题颜色 | String | `$title` | - |
| linkColor | 链接文字颜色 | String | `$primary` | - |
| lineColor | 链接分隔线颜色 | String | `$line` | - |
| textColor | 页脚文字颜色 | String | `$textLight` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 自定义根节点样式类 | String | `''` | - |
| linkClass | 链接文字样式类 | String | `''` | - |
| textClass | 页脚文字样式类 | String | `''` | - |

> 类型字段：SnFooterLink（见 https://sinleui.pages.dev/api/types/component#snfooterlink）

> 类型字段：SnFooterLogo（见 https://sinleui.pages.dev/api/types/component#snfooterlogo）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| linkclick | (link: `SnFooterLink`, index: number) => Void | 点击链接时触发，携带链接数据与索引（跳转仍会执行，可用 `openType: 'none'` 阻止默认跳转自行处理） |
| logoclick | () => Void | 点击 Logo 时触发（Logo 配置了 `url` 时跳转仍会执行） |

<DemoPhone name="sn-footer" />

# Topbar 导航栏

> [查看 sn-topbar 的 2.0 版本差异](/differences/components/sn-topbar)

## 基础用法

页面顶部导航栏，包含标题、返回按钮与右侧功能区。

- 固定与非固定模式共用一个根容器，默认固定在页面顶部
- 支持背景模糊；可让根容器背景向上延伸覆盖状态栏区域，避免顶部露底或状态栏与内容重叠
- 返回按钮点击时派发事件，页面栈大于 1 时自动返回；导航栏高度默认取全局配置，可单独指定

```vue
<template>
	<sn-topbar title="标题"></sn-topbar>
</template>
```

**更多演示请下载 demo 查看**

## 功能按钮与下拉菜单

`features` 配置右侧功能按钮，每项通过 `icon`（图标）或 `text`（文字）定义内容。`menuButton` 显示"更多"按钮，`menuData` 配置下拉菜单项（配置后菜单按钮自动显示），菜单项选中时触发 `menuselect`。

```vue
<template>
	<sn-topbar
		title="导航"
		:features="[{ icon: 'search-line' }, { text: '发布' }]"
		:menu-data="[{ text: '刷新', icon: 'refresh-line' }]"
		@featureclick="onFeatureClick"
		@menuselect="onMenuSelect"
	></sn-topbar>
</template>
```

## 自定义样式

`bg-color` 设置背景色，`title-style` / `title-class` 定制标题，`button-style` 定制按钮，`hover-button-style` 定制按钮按压态，适配主题色或深色导航背景。

```vue
<template>
	<sn-topbar
		title="主题色导航"
		bg-color="var(--sn-primary)"
		title-style="color: #ffffff;"
		button-style="background-color: rgba(255, 255, 255, 0.18); border-width: 0;"
		button-icon-style="color: #ffffff;"
		hover-button-style="background-color: rgba(255, 255, 255, 0.25);"
	></sn-topbar>
</template>
```

## 背景模糊与布局

`blur` 在整体根容器上设置 `backdrop-filter: blur(...)`，Web 同时设置 `-webkit-backdrop-filter`。不创建额外背景层、状态栏层或占位层；`statusBar` 开启时根容器向上覆盖状态栏区域，模糊同样作用于状态栏区域。

菜单弹层独立于导航栏根容器，避免 `backdrop-filter` 改变 Web 固定定位弹层的包含块，影响遮罩范围和菜单锚点定位。

未传 `bgColor` 时，启用模糊会将主题页面背景色转换为半透明颜色，透明度由 `blurOpacity` 控制。显式传入 `bgColor` 时保留该颜色自身的透明度，例如 `rgba(255, 255, 255, 0.58)`；不透明背景会遮住背景模糊效果。

Demo 首页 `pages/index/index.uvue` 的顶部与底部导航栏均启用模糊，半径为 `20px`、背景透明度为 `0.68`；不显式传入背景色，随亮暗主题自动切换。首页顶部导航栏根容器随 `statusBar` 向上覆盖状态栏区域，安全距离和内容占位仍由页面管理。

固定导航栏不会撑开文档流，请在使用方为内容设置间距；`statusBar` 默认开启（背景覆盖状态栏、内容预留状态栏高度），内容间距应取 `$snui.topbarHeightResolved` 加状态栏高度，最简做法是在导航栏后叠加一个 `<sn-gap mode="statusbar" />`。使用 `sn-page` 的内置导航栏时，这些布局由 `sn-page` 处理。非固定模式导航栏本身占据文档流，同样会预留状态栏高度。

未显示返回按钮且未提供 `header` 插槽时，根容器仍保留 `16 × paddingFactor` px 左内边距；有左侧内容时为 `8 × paddingFactor` px。不通过空侧栏实现留白。

```vue
<sn-topbar title="毛玻璃导航" :blur="true" :blur-radius="20"
	bg-color="rgba(255, 255, 255, 0.58)" />
```


## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| title | 标题文本 | String | `''` | - |
| backButton | 是否显示返回按钮 | Boolean | `true` | `true` \| `false` |
| backButtonIcon | 返回按钮图标名 | String | `'arrow-left-s-line'` | - |
| fixed | 是否固定在页面顶部，不生成占位 | Boolean | `true` | `true` \| `false` |
| statusBar | 是否向上覆盖状态栏区域并为内容预留状态栏高度 | Boolean | `true` | `true` \| `false` |
| titleAlign | 标题对齐方式 | String | `'left'` | `left` \| `center` \| `right` |
| features | 右侧功能按钮数据，每项可配置 icon（图标）或 text（文字） | Array<`SnDataItem`> | `[]` | - |
| menuButton | 是否显示"更多"菜单按钮（menuData 非空时自动显示） | Boolean | `false` | `true` \| `false` |
| menuData | 下拉菜单数据，点击菜单按钮弹出内置菜单 | Array<`SnDataItem`> | `[]` | - |
| bgColor | 背景颜色 | String | `$page` | - |
| blur | 是否启用背景高斯模糊 | Boolean | `false` | `true` \| `false` |
| blurRadius | 背景高斯模糊半径（单位 px） | Number | `15` | - |
| blurOpacity | 未传 bgColor 时的模糊背景透明度，取值 0~1，不影响标题和按钮 | Number | `0.78` | - |
| height | 导航栏内容区高度（不含状态栏，Number 单位 px），取全局配置 `$snui.topbarHeight`（Web 端 + 8px，其他端直接使用该值）；`statusBar` 开启时根容器总高度为该值加状态栏高度 | String \| Number | - | - |
| zIndex | 固定定位时的层级 | Number | `998` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部样式类，通过 custom-class 传入 | String | `''` | - |
| titleStyle | 自定义标题样式 | SnStyleValue | `''` | - |
| titleClass | 标题外部样式类 | String | `''` | - |
| buttonStyle | 自定义返回/功能/菜单按钮样式 | SnStyleValue | `''` | - |
| hoverButtonStyle | 自定义按钮按压态样式 | SnStyleValue | `''` | - |
| buttonTextStyle | 自定义按钮文字样式（features 中纯文字按钮） | SnStyleValue | `''` | - |
| buttonIconStyle | 自定义按钮图标样式 | SnStyleValue | `''` | - |

> 类型字段：SnDataItem（见 https://sinleui.pages.dev/api/types/component#sndataitem）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| back | () => Void | 点击返回按钮时触发；页面栈大于 1 时组件会自动执行返回 |
| featureclick | (item: `SnDataItem`, index: number) => Void | 点击功能按钮时触发；点击"更多"菜单按钮且未配置菜单数据时也会触发（item 仅含 icon，index 为 -1） |
| menuselect | (item: `SnDataItem`, index: number) => Void | 选择下拉菜单项时触发 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| header | 替换左侧返回按钮区域 |
| default | 替换中间标题区域 |
| footer | 替换右侧功能按钮区域 |

<DemoPhone name="sn-topbar" />

# Tabbar 底部导航栏

> [查看 sn-tabbar 的 2.0 版本差异](/differences/components/sn-tabbar)

## 基础用法

底部导航栏，用于在页面底部切换子页面，支持文字、字体图标与图片子项，样式可自由定制。

- 子项由数据项配置自动渲染，无需手动引入子项组件，支持拦截鉴权与角标
- 支持固定底部与内嵌两种模式，可开启毛玻璃背景，图标与文字保持清晰
- 为每个子项提供子页面插槽，最多 10 项

```vue
<template>
	<sn-tabbar :data="data"></sn-tabbar>
</template>
```

**更多演示请下载 demo 查看**

## 实现原理

固定底部（`fixed`）与内嵌（`fixed=false`）模式共用一个主体容器，定位、背景、边框、圆角与模糊均作用于该容器。

## 子页面与占位高度

推荐给固定 Tabbar 设置 `tabbar-key="home"`，子页面调用 [useTabbarHeights](/api/hooks/use-tabbar-heights)，通过 `tabbarHeights['home']` 读取实际高度。每个 `sn-page` 的登记表独立，不同页面同名 key 不冲突；同页不同 Tabbar 需使用不同 key。默认 key 为空，不登记。

**占位必须放在子页面 scroll-view 的滚动内容末尾，而不是子组件外侧或页面根布局的底部。** 外侧占位会缩短滚动视口，使 Tabbar 背后一直是空白，无法采样滚动内容形成毛玻璃。首页三个子页面已采用滚动内容末尾占位，首页不再保留外层 `tabbar-safe`。

`fixed` 模式使用固定定位，组件不会自动占位或添加安全区 padding。通过 `v-model:height` 拿到主体实际高度自行放置占位（如 sn-gap），不要手动修改组件输出的高度；该高度包含主体内边距和边框，但不包含外边距、底部偏移或额外安全距离。需要安全距离时，可通过 `customStyle` 设置 `bottom`，并在使用方占位高度中另加安全距离与底部外边距。

`tab1` ~ `tab10` 的页面容器独立于导航栏主体，不受主体的固定定位或背景模糊影响。首次切换到某页才挂载，后续切换保留状态；`showPages=false` 时不渲染子页面。组件不为这些页面自动添加底部间距，需在页面滚动内容末尾自行处理。

```vue
<template>
	<sn-page fill-content>
		<scroll-view direction="vertical" class="page-scroll">
			<text>页面内容</text>
			<sn-gap :height="tabbarHeight"></sn-gap>
		</scroll-view>
		<sn-tabbar v-model:height="tabbarHeight" :data="data"></sn-tabbar>
	</sn-page>
</template>

<script lang="ts" setup>
import type { SnTabbarItem } from '@/uni_modules/sinle-ui'
const tabbarHeight = ref('0px')
const data: SnTabbarItem[] = [{ icon: 'home-5-line', text: '首页' }]
</script>

<style lang="scss">
.page-scroll {
	flex: 1;
	flex-direction: column;
}
</style>
```

## 毛玻璃背景

设置 `blur` 后，只在主体容器上设置 `backdrop-filter: blur(...)`，Web 同时设置 `-webkit-backdrop-filter`。关闭时设置 `none`，不创建额外背景层或原生模糊层。

未传 `bgColor` 时使用主题 `front` 色，启用模糊后由 `blurOpacity` 控制背景透明度。显式传入 `bgColor` 时保留该颜色自身的透明度，例如 `rgba(255, 255, 255, 0.58)`；不透明背景会遮住模糊效果。不会通过容器 `opacity` 降低图标和文字的透明度。

Demo 首页 `pages/index/index.uvue` 的顶部与底部导航栏均使用 `blur=true`、`blurRadius=20`、`blurOpacity=0.68`，未显式设置背景色以便随亮暗主题切换；安全距离与占位由首页管理。

```vue
<sn-tabbar :data="data" :blur="true" :blur-radius="18" :blur-opacity="0.58" />
<sn-tabbar :data="data" :fixed="false" :blur="true"
	bg-color="rgba(255, 255, 255, 0.58)" border-radius="$18" />
```

App 毛玻璃依赖蒸汽模式的 `backdrop-filter` 支持，不再提供 VDOM 原生模糊层回退。固定模式和内嵌模式均保留 `padding` 指定的内部边距，默认 `$10`，包括首尾子项到容器边缘的距离；不会用空子项来制造边距。

## 数据项 SnTabbarItem

`data` 为 SnTabbarItem[]，字段如下：

> 类型字段：SnTabbarItem（见 https://sinleui.pages.dev/api/types/component#sntabbaritem）


---

:::

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model:height | 导航栏主体实际高度，供外部占位，不含外边距、底部偏移或自动安全区 | String | `''` | - |
| data | 底部导航栏数据，每一项与插槽一 一匹配，最多 10 项 | Array<`SnTabbarItem`> | `[]` | - |
| index | 首次加载时显示的页面索引（从 1 开始） | Number | `1` | - |
| fixed | 是否固定底部 | Boolean | `true` | `true` \| `false` |
| tabbarKey | 固定 Tabbar 高度登记键；在最近的 sn-page 作用域内唯一，空值不登记，子页面通过 useTabbarHeights 读取 | String | `''` | - |
| showPages | 是否显示子页面插槽内容 | Boolean | `true` | `true` \| `false` |
| imageSize | 子项图片大小（`$` 简写乘字体乘数） | String \| Number | `''` | - |
| padding | 导航栏内边距（`$` 简写乘内边距乘数） | String \| Number | `'$10'` | - |
| margin | 导航栏外边距 | String \| Number | `'0px'` | - |
| bgColor | 导航栏背景颜色 | String | `$front` | - |
| blur | 是否启用背景高斯模糊 | Boolean | `false` | `true` \| `false` |
| blurRadius | 背景高斯模糊半径（单位 px） | Number | `15` | - |
| blurOpacity | 未传 bgColor 时的模糊背景透明度，取值 0~1，不影响图标和文字 | Number | `0.78` | - |
| itemBorderRadius | 子项圆角大小，组件根据导航栏圆角自动计算最合适值 | String \| Number | - | - |
| itemPadding | 子项内边距，透传到 sn-tabbar-item 的 padding，支持 `$` 简写 | String \| Number | `'$5 0'` | - |
| itemSpacing | 各子项之间的间距 | String \| Number | `'0px'` | - |
| itemBgColor | 子项背景颜色 | String | `var(--sn-transparent)` | - |
| itemActiveBgColor | 选中子项的背景颜色 | String | `var(--sn-transparent)` | - |
| border | 导航栏边框 | String | `1px solid var(--sn-line)` | - |
| borderRadius | 导航栏圆角大小 | String \| Number | `'0'` | - |
| textColor | 子项文本颜色 | String | `$text` | - |
| textSize | 子项文本大小 | String \| Number | `$11` | - |
| activeTextColor | 选中子项文本颜色 | String | `$primary` | - |
| iconColor | 子项图标颜色 | String | `$text` | - |
| iconSize | 子项图标大小 | String \| Number | `$22` | - |
| activeIconColor | 选中子项图标颜色 | String | `$primary` | - |
| disabled | 是否禁用整个导航栏 | Boolean | `false` | `true` \| `false` |
| hoverStyle | 子项按压态样式 | SnStyleValue | `'background: var(--sn-info);'` | - |
| hoverStartTime | 按压生效延迟（单位 ms） | Number | `50` | - |
| hoverStayTime | 按压保持时长（单位 ms） | Number | `0` | - |
| hoverTransTime | 按压过渡时长（单位 ms，`$` 简写乘动画乘数） | String \| Number | `''` | - |
| hoverStopPropagation | 按压事件是否阻止冒泡 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义导航栏样式 | SnStyleValue | `''` | - |
| customClass | 导航栏主体外部样式类，通过 custom-class 传入 | String | `''` | - |
| customContainStyle | 子页面容器样式；未提供子页面插槽时，兼容旧调用合并到主体，后置 customStyle 优先 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (index: number) => Void | 页面切换时触发，index 从 1 开始 |
| heightchange | (height: number) => Void | 导航栏主体实际高度变化时触发，不包含外边距、底部偏移或自动安全区 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| changeToIndex | `(index: number)` | - | 切换到指定索引的页面，索引值即为插槽名称（如 #tab1 的索引为 1） |

## 插槽

| 名称 | 说明 |
| --- | --- |
| tab1 ~ tab10 | 第 n 个子页面，须与 data 项一 一对应 |

## sn-tabbar-item 属性 <Badge type="warning" text="内部使用" />

`sn-tabbar` 的子项组件，由 `data` 自动渲染，无需手动引入；下列属性均由 `sn-tabbar` 按组配置逐项下发。

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| data | 该项的数据对象 | [SnTabbarItem](/api/types/component#sntabbaritem) | `null` | - |
| index | 该项在 `data` 中的索引 | Number | `0` | - |
| active | 是否为当前选中项 | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用该项（禁用后不触发 click） | Boolean | `false` | `true` \| `false` |
| isFirst | 是否为第一项（首尾圆角与间距处理用） | Boolean | `false` | `true` \| `false` |
| isLast | 是否为最后一项（首尾圆角与间距处理用） | Boolean | `false` | `true` \| `false` |
| padding | 子项内边距，默认上下 5 × paddingFactor px、左右 0，支持 `$` 简写 | String \| Number | `'$5 0'` | - |
| itemPadding | 兼容旧调用的子项内边距，非空时优先于 padding，支持 `$` 简写 | String \| Number | `''` | - |
| itemBorderRadius | 子项圆角（支持 `$` 简写） | String | `0px` | - |
| itemBgColor | 子项背景颜色 | String | `''` | - |
| itemActiveBgColor | 选中子项背景颜色 | String | `''` | - |
| textColor | 子项文本颜色 | String | `''` | - |
| activeTextColor | 选中子项文本颜色 | String | `''` | - |
| textSize | 子项文本大小（支持 `$` 简写） | String | `''` | - |
| iconColor | 子项图标颜色 | String | `''` | - |
| activeIconColor | 选中子项图标颜色 | String | `''` | - |
| iconSize | 子项图标大小（支持 `$` 简写） | String | `''` | - |
| imageSize | 子项图片大小（`data` 项设置 `image` 时生效，支持 `$` 简写） | String | `35px` | - |
| itemSpacingHalf | 子项间距的一半（首尾对齐用，支持 `$` 简写） | String | `0px` | - |
| hoverStyle | 子项按压态样式 | SnStyleValue | `background: var(--sn-info);` | - |
| hoverStartTime | 按压生效延迟（单位 ms） | Number | `50` | - |
| hoverStayTime | 按压保持时长（单位 ms） | Number | `0` | - |
| hoverTransTime | 按压过渡时长（单位 ms，`$` 简写乘动画乘数） | String \| Number | `''` | - |
| hoverStopPropagation | 按压事件是否阻止冒泡 | Boolean | `false` | `true` \| `false` |

## sn-tabbar-item 事件 <Badge type="warning" text="内部使用" />

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| click | (index: number) => Void | 点击子项时触发，`index` 为该项在 `data` 中的索引（禁用项不触发） |

<DemoPhone name="sn-tabbar" />

# Sidebar 侧边栏

> [查看 sn-sidebar 的 2.0 版本差异](/differences/components/sn-sidebar)

## 基础用法

侧边导航栏，适用于商城选购等场景。

- 左侧为选项列表，选中索引支持双向绑定
- 右侧为内容区，可通过默认插槽自定义
- 支持锚点定位与选中线

```vue
<template>
	<sn-sidebar v-model="index" :data="items">
		<view>右侧内容区</view>
	</sn-sidebar>
</template>
```

**更多演示请下载 demo 查看**

## 锚点定位

`anchor` 为 true 时，选中项变化会驱动内容区滚动到对应 `id` 的节点（scroll-into-view），需在内容区放置带相同 `id` 的节点。

```vue
<template>
	<sn-sidebar v-model="index" :data="items" anchor>
		<scroll-view>
			<view :id="items[0].id">模块一</view>
			<view :id="items[1].id">模块二</view>
		</scroll-view>
	</sn-sidebar>
</template>
```

## 外部样式

`bar-class` / `bar-style` 定制左侧侧边栏，`item-class` / `item-style` 定制选项，`content-class` / `content-style` 定制内容区。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 当前选中的选项索引 | Number | `0` | - |
| data | 侧边栏选项数据数组 | Array<`SnDataItem`> | `[]` | - |
| width | 侧边栏宽度，支持 `$` 前缀按间距乘数缩放 | String | `'100px'` | - |
| itemWidth | 选项宽度，支持 `$` 前缀按间距乘数缩放 | String | `'100px'` | - |
| itemPadding | 选项内边距（支持 1~4 值简写），支持 `$` 前缀按间距乘数缩放 | String | `'15px 0'` | - |
| itemTextColor | 选项文字颜色 | String | `$text` | - |
| itemTextSize | 选项文字大小 | String \| Number | `$16` | - |
| activeItemTextColor | 选中选项文字颜色 | String | `$primary` | - |
| itemBgColor | 选项背景颜色 | String | `var(--sn-transparent)` | - |
| itemBorderRadius | 选项圆角大小 | String \| Number | `'0'` | - |
| activeItemBgColor | 选中选项背景颜色 | String | `$front` | - |
| disabled | 是否禁用所有选项 | Boolean | `false` | `true` \| `false` |
| anchor | 是否使用锚点定位，选中时内容区滚动到对应 id | Boolean | `false` | `true` \| `false` |
| showLine | 是否显示选中线 | Boolean | `true` | `true` \| `false` |
| lineColor | 选中线颜色 | String | `$primary` | - |
| customStyle | 自定义容器样式 | SnStyleValue | `''` | - |
| itemStyle | 自定义选项样式 | SnStyleValue | `''` | - |
| itemClass | 选项外部样式类 | String | `''` | - |
| barStyle | 自定义侧边栏（左侧列表）样式 | SnStyleValue | `''` | - |
| barClass | 侧边栏外部样式类 | String | `''` | - |
| contentStyle | 自定义内容区样式 | SnStyleValue | `''` | - |
| contentClass | 内容区外部样式类 | String | `''` | - |

> 类型字段：SnDataItem（见 https://sinleui.pages.dev/api/types/component#sndataitem）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: number) => Void | 选项改变时触发 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 放置侧边栏右侧的内容区域 |

<DemoPhone name="sn-sidebar" />

# Tabs 标签页

> [查看 sn-tabs 的 2.0 版本差异](/differences/components/sn-tabs)

## 基础用法

标签页组件，用于切换不同标签内容，一般用于顶部导航。

- 支持滚动模式与滑动式 / 推压式两种指示线动画
- 支持子项单独禁用与徽标
- 支持左右插槽

```vue
<template>
	<sn-tabs v-model="current" :data="tabs"></sn-tabs>
</template>
```

**更多演示请下载 demo 查看**

## 滚动与动画

`scrollable` 开启后标签可横向滚动，子项自动计算宽度并将选中项居中；`mode` 选择指示线动画方式：`swipe` 滑动式、`push` 推压式。

```vue
<template>
	<sn-tabs v-model="current" scrollable mode="push" :data="tabs"></sn-tabs>
</template>
```

## 徽标

data 项通过 `badgeConfig` 配置徽标（value/max/size/offset/mode/text/showZero/textColor/bgColor），支持 number/text/dot 三种模式。

```vue
<template>
	<sn-tabs v-model="current" :data="tabs"></sn-tabs>
</template>

<script setup>
const tabs = [
	{ id: 't1', text: '选项1' },
	{ id: 't2', text: '选项2', badgeConfig: { value: 6 } },
	{ id: 't3', text: '选项3', disabled: true }
] as SnTabParams[]
</script>
```

## 数据项 SnTabParams

| 字段 | 说明 | 类型 |
| --- | --- | --- |
| text | 标签文本（必需） | String |
| id | 标签唯一标识（必需，用于指示线定位与滚动） | String |
| disabled | 是否禁用该标签 | Boolean |
| badgeConfig | 徽标配置 | `SnBadgeParams` |

> 类型字段：SnBadgeParams（见 https://sinleui.pages.dev/api/types/component#snbadgeparams）


类型中还声明了 icon、checked、showBadge 字段，当前渲染未使用。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 当前激活的标签页索引 | Number | `0` | - |
| scrollable | 标签是否可滚动 | Boolean | `false` | `true` \| `false` |
| data | 标签页数据数组 | Array<`SnTabParams`> | `[]` | - |
| mode | 指示线动画模式 | String | `'swipe'` | `swipe` \| `push` |
| width | 标签宽度，支持 `$` 前缀按间距乘数缩放 | String | `'100%'` | - |
| height | 标签高度，支持 `$` 前缀按间距乘数缩放 | String | `'40px'` | - |
| bgColor | 标签背景颜色 | String | `$front` | - |
| textColor | 标签文本颜色 | String | `$title` | - |
| textSize | 标签文本大小 | String \| Number | `$14` | - |
| borderRadius | 标签圆角 | String \| Number | `$12` | - |
| disabledTextColor | 禁用标签文本颜色 | String | `$disabledText` | - |
| activeTextColor | 选中标签文本颜色 | String | `$primary` | - |
| itemPadding | 标签内边距（可滚动时作为左右内边距），支持 `$` 前缀按间距乘数缩放 | String | `'12px'` | - |
| lineColor | 指示线颜色 | String | `$primary` | - |
| lineWidth | 指示线宽度，取标签宽度的 60%，支持 `$` 前缀按间距乘数缩放 | String | - | - |
| lineHeight | 指示线高度，支持 `$` 前缀按间距乘数缩放 | String | `'2px'` | - |
| aniTime | 标签及指示线动画时长（单位 ms，`$` 简写乘动画乘数） | String \| Number | `$normal` | - |
| itemStyle | 选中标签样式 | SnStyleValue | `''` | - |
| itemClass | 选中标签外部样式类 | String | `''` | - |
| textStyle | 标签文本样式 | SnStyleValue | `''` | - |
| textClass | 标签文本外部样式类 | String | `''` | - |
| activeItemStyle | 非选中标签样式 | SnStyleValue | `''` | - |
| activeItemClass | 非选中标签外部样式类 | String | `''` | - |
| customStyle | 自定义样式 | SnStyleValue | `''` | - |

> 类型字段：SnTabParams（见 https://sinleui.pages.dev/api/types/component#sntabparams）


:::

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (index: number) => Void | 标签页切换时触发，index 为标签页索引 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| left | 在标签页左侧放置内容 |
| right | 在标签页右侧放置内容 |

<DemoPhone name="sn-tabs" />

# Subsection 分段器

> [查看 sn-subsection 的 2.0 版本差异](/differences/components/sn-subsection)

## 基础用法

分段器，用于用户从几个选项中选择某一个，常作为视图切换控件。

- 分段文本由数据数组驱动，选中索引支持双向绑定
- 滑块随选中项平移并带动画
- 滑块尺寸按容器实际尺寸动态计算，容器尺寸变化时自动重新测量

```vue
<template>
	<sn-subsection v-model="current" :data="list"></sn-subsection>
</template>

<script lang="ts" setup>
const current = ref<number>(0)
const list = ['已付款', '已发货', '已收货', '已评价']
</script>
```

**更多演示请下载 demo 查看**

## 自定义样式

分段项、滑块、文本均支持外部样式类与自定义样式，可深度改造外观，例如把滑块改为下划线样式：

```vue
<template>
	<sn-subsection v-model="current" :data="list" block-bg-color="transparent"
		block-style="border-radius:0; border-bottom:2px solid var(--sn-primary);"></sn-subsection>
</template>

<script lang="ts" setup>
const current = ref<number>(0)
const list = ['已付款', '已发货', '已收货', '已评价']
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值，当前选中的分段索引 | Number | `0` | - |
| data | 分段数据，数组中的每个元素代表一个分段的文本 | `Array<String>` | `[]` | - |
| disabled | 是否禁用分段选择器 | Boolean | `false` | `true` \| `false` |
| padding | 分段器内边距 | String \| Number | `'3px'` | - |
| blockPadding | 每个分段项的内边距 | String \| Number | `'10px'` | - |
| borderRadius | 分段器圆角 | String \| Number | `$12` | - |
| textSize | 分段文本大小 | String \| Number | `$14` | - |
| bgColor | 分段器背景颜色 | String | `$info` | - |
| disabledBgColor | 禁用时分段器背景颜色，亮色主题为 `$disabled`、暗黑主题为 `$disabledDark` | String | - | - |
| blockBgColor | 滑块背景颜色 | String | `$front` | - |
| disabledBlockBgColor | 禁用时滑块背景颜色，亮色主题为 `$disabledDark`、暗黑主题为 `$disabled` | String | - | - |
| textColor | 未选中分段文本颜色 | String | `$text` | - |
| activeTextColor | 选中分段文本颜色 | String | `$primaryDark` | - |
| disabledTextColor | 禁用时文本颜色 | String | `$disabledText` | - |
| customStyle | 自定义分段器根节点样式 | SnStyleValue | `''` | - |
| customClass | 分段器根节点的外部样式类 | String | `''` | - |
| itemClass | 分段项的外部样式类 | String | `''` | - |
| itemStyle | 自定义分段项样式 | SnStyleValue | `''` | - |
| blockClass | 滑块的外部样式类 | String | `''` | - |
| blockStyle | 自定义滑块样式 | SnStyleValue | `''` | - |
| textClass | 分段文本的外部样式类 | String | `''` | - |
| textStyle | 自定义分段文本样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: number) => Void | 选中分段变化时触发，携带新的分段索引 |

<DemoPhone name="sn-subsection" />

# Steps 步骤条

## 基础用法

步骤条，用于展示流程进度，由 `sn-steps`（容器）与 `sn-step`（步骤项）组合使用。

- 支持横向 / 竖向与两种步骤形态
- 支持点击切换与当前步骤状态
- 容器属性（尺寸、颜色、外部样式等）统一下发给各步骤项

```vue
<template>
	<sn-steps v-model="current">
		<sn-step title="买家下单" content="等待商家确认"></sn-step>
		<sn-step title="商家接单" content="正在备货中"></sn-step>
		<sn-step title="交易完成" content="感谢您的购买"></sn-step>
	</sn-steps>
</template>
```

**更多演示请下载 demo 查看**

## 点状步骤条

`type` 设为 `dot` 使用小圆点的简略模式。

```vue
<template>
	<sn-steps v-model="current" type="dot">
		<sn-step title="提交订单"></sn-step>
		<sn-step title="付款成功"></sn-step>
		<sn-step title="确认收货"></sn-step>
	</sn-steps>
</template>
```

## 竖向步骤条

`vertical` 属性改为纵向排列，适合物流详情等场景。

```vue
<template>
	<sn-steps v-model="current" vertical>
		<sn-step title="包裹已下单" content="08月26日 10:24"></sn-step>
		<sn-step title="运输中" content="08月26日 15:47"></sn-step>
		<sn-step title="已签收"></sn-step>
	</sn-steps>
</template>
```

## 自定义样式

`active-color` 定制激活色，`circle-size` / `text-size` / `content-size` 定制尺寸，`title-style` / `title-class` 等外部样式/类定制各部分。

```vue
<template>
	<sn-steps v-model="current" active-color="$success" circle-size="$28px"
		title-style="font-weight:normal;" content-class="my-content">
		<sn-step title="已支付" content="08月25日"></sn-step>
		<sn-step title="已发货" content="08月26日"></sn-step>
	</sn-steps>
</template>
```

## sn-steps 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 当前步骤索引 | Number | `0` | - |
| vertical | 是否竖向排列 | Boolean | `false` | `true` \| `false` |
| type | 展示形态 | String | `'default'` | `default` \| `dot` |
| status | 当前步骤（激活步骤）的状态 | String | `'process'` | `wait` \| `finish` \| `process` \| `error` |
| selectable | 是否允许点击步骤切换 | Boolean | `true` | `true` \| `false` |
| activeColor | 激活色 | String | `$primary` | - |
| circleSize | 圆形节点大小 | String \| Number | `'$22'` | - |
| textSize | 标题文字大小 | String \| Number | `$14` | - |
| contentSize | 内容文字大小 | String \| Number | `$12` | - |
| stepStyle | 自定义步骤项样式 | SnStyleValue | `''` | - |
| stepClass | 步骤项外部样式类 | String | `''` | - |
| titleStyle | 自定义标题样式 | SnStyleValue | `''` | - |
| titleClass | 标题外部样式类 | String | `''` | - |
| contentStyle | 自定义内容样式 | SnStyleValue | `''` | - |
| contentClass | 内容外部样式类 | String | `''` | - |
| lineStyle | 自定义连接线样式 | SnStyleValue | `''` | - |
| lineClass | 连接线外部样式类 | String | `''` | - |
| customStyle | 自定义容器样式 | SnStyleValue | `''` | - |
| customClass | 容器外部样式类 | String | `''` | - |

## sn-steps 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: number) => Void | 步骤改变时触发 |

## sn-steps 插槽

| 名称 | 说明 |
| --- | --- |
| default | 放置 sn-step 步骤项 |

## sn-step 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| title | 步骤标题 | String | `''` | - |
| content | 步骤内容 | String | `''` | - |
| icon | 自定义图标名，finish 显示 check-line、error 显示 close-line | String | - | - |
| status | 单独覆盖该步骤的状态，由索引与容器 status 自动推导 | String | - | `wait` \| `finish` \| `process` \| `error` |
| stepClass | 步骤项外部样式类（与容器的 stepClass 合并） | String | `''` | - |
| titleClass | 标题外部样式类（与容器的 titleClass 合并） | String | `''` | - |
| contentClass | 内容外部样式类（与容器的 contentClass 合并） | String | `''` | - |
| lineClass | 连接线外部样式类（与容器的 lineClass 合并） | String | `''` | - |

## sn-step 插槽

| 名称 | 说明 |
| --- | --- |
| icon | 替换圆形节点内容，作用域插槽可访问当前状态 status |
| title | 替换标题内容 |
| content | 替换内容区文本 |
| extra | 在内容区底部追加额外内容 |

<DemoPhone name="sn-steps" />

# Menu 菜单

> [查看 sn-menu 的 2.0 版本差异](/differences/components/sn-menu)

## 基础用法

锚点菜单，在触发元素（按钮、图标等）旁弹出一组操作选项，常用于「更多操作」场景。

- 菜单项由数组驱动，支持文字、图标、右侧内容、文字颜色与禁用
- 自动定位到锚点下方，下方空间不足时改为上方弹出，三角箭头随之翻转
- 点击菜单项派发事件并自动关闭，遮罩可关闭或自定义

::: danger 必须放在 sn-page 下
本组件为弹出层，需直接放在 `sn-page` 根节点下使用，否则主题颜色与动画时长等 CSS 变量无法作用到组件内部。
:::

::: info 平台差异
HarmonyOS 端菜单透明度由入退场动画控制，遮罩独立淡入淡出。
:::

```vue
<template>
	<sn-page>
		<sn-button id="menu-btn" text="打开菜单" @click="show = true"></sn-button>
		<sn-menu v-model:show="show" target="#menu-btn" :items="items"
			@select="onSelect"></sn-menu>
	</sn-page>
</template>

<script lang="ts" setup>
import type { SnDataItem } from '@/uni_modules/sinle-ui/core/types/index.ts'

const show = ref<boolean>(false)
const items: SnDataItem[] = [
	{ text: '编辑', icon: 'edit-line' },
	{ text: '分享', icon: 'share-line' },
	{ text: '删除', icon: 'delete-bin-line' }
]

function onSelect(index: number, item: SnDataItem): void {
	console.log(item.text)
}
</script>
```

**更多演示请下载 demo 查看**

## 对齐方式与箭头

```vue
<template>
	<sn-menu v-model:show="show" target="#menu-btn" align="center"
		:width="220" :show-arrow="false" :items="items"></sn-menu>
</template>

<script lang="ts" setup>
const show = ref<boolean>(false)
const items: SnDataItem[] = [
	{ text: '选项一' },
	{ text: '选项二' }
]
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model:show | 菜单显示状态绑定值 | Boolean | `false` | `true` \| `false` |
| target | 锚点元素选择器（如 `#menu-btn`），菜单将定位到该元素旁 | String | `''` | - |
| align | 菜单相对锚点的对齐方式 | String | `left` | `left` \| `center` \| `right` |
| items | 菜单项数组，每项支持 `text`、`icon`、`value`、`color`、`disabled` 字段 | Array<`SnDataItem`> | `[]` | - |
| width | 菜单宽度（px），支持 `$` 前缀按间距乘数缩放 | String \| Number | `160px` | - |
| zIndex | 弹出层层级 | Number | `999` | - |
| showArrow | 是否显示指向锚点的三角箭头 | Boolean | `true` | `true` \| `false` |
| overlay | 是否显示遮罩 | Boolean | `true` | `true` \| `false` |
| overlayOpacity | 遮罩透明度，`overlay` 为 `false` 时不显示遮罩 | Number | `0.3` | - |
| overlayStyle | 自定义遮罩样式 | SnStyleValue | `''` | - |
| overlayClass | 遮罩外部类 | String | `''` | - |
| menuStyle | 自定义菜单容器样式 | SnStyleValue | `''` | - |
| menuClass | 菜单容器外部类 | String | `''` | - |
| aniTime | 显示 / 关闭动画时长（ms），支持 `$` 简写 | String \| Number | `200` | - |
| cellStyle | 自定义菜单项样式（透传内部 sn-cell） | SnStyleValue | `''` | - |
| cellClass | 菜单项外部类（透传内部 sn-cell） | String | `''` | - |
| cellBorder | 是否显示菜单项之间的分隔线 | Boolean | `true` | `true` \| `false` |
| closeOnClickOverlay | 点击遮罩时是否关闭菜单 | Boolean | `true` | `true` \| `false` |

> 类型字段：SnDataItem（见 https://sinleui.pages.dev/api/types/component#sndataitem）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| update:show | (value: boolean) => Void | 菜单显示状态变化时触发，配合 `v-model:show` 使用 |
| select | (index: number, item: `SnDataItem`) => Void | 点击菜单项时触发，参数为索引与所选菜单项，随后自动关闭 |
| clickoverlay | () => Void | 点击遮罩时触发 |
| beforeenter | () => Void | 入场动画开始前触发 |
| enter | () => Void | 入场动画开始时触发 |
| afterenter | () => Void | 入场动画结束后触发 |
| beforeleave | () => Void | 离场动画开始前触发 |
| leave | () => Void | 离场动画开始时触发 |
| afterleave | () => Void | 离场动画结束后触发 |

<DemoPhone name="sn-menu" />

# Search 搜索框

> [查看 sn-search 的 2.0 版本差异](/differences/components/sn-search)

## 基础用法

基于 `sn-input` 二次封装的搜索框，键盘确认按钮固定为 search，开箱即用。

- 聚焦时右侧取消按钮平滑展开，点击取消会清空输入内容并派发事件
- 输入值变化时派发事件，可显示一键清空按钮
- 前后图标可更换，也可用插槽自定义

```vue
<template>
	<sn-search v-model="keyword" @change="onChange" @confirm="onConfirm" @cancel="onCancel"></sn-search>
</template>

<script lang="ts" setup>
const keyword = ref<string>('')

function onChange(value: string): void {
	console.log(value)
}

function onConfirm(e: UniInputConfirmEvent): void {
	console.log(e.detail.value)
}

function onCancel(): void {
	console.log('取消搜索')
}
</script>
```

**更多演示请下载 demo 查看**

## 自定义取消按钮

通过 `showCancel` 控制是否显示取消按钮（默认隐藏，聚焦时展开），`fixCancel` 让其常驻显示，文案与样式可用 `cancelText` / `cancelTextSize` / `cancelTextColor` 或 `cancelClass` / `cancelStyle` 定制。

```vue
<template>
	<sn-search v-model="keyword" fix-cancel cancel-text="搜索"
		cancel-text-color="$error"></sn-search>
</template>

<script lang="ts" setup>
const keyword = ref<string>('')
</script>
```

## 自定义图标与插槽

```vue
<template>
	<sn-search v-model="keyword" suffix-icon="scan-line" @suffix-click="onScan">
		<template #prefix>
			<sn-icon name="emotion-laugh-line" :size="20" color="$primary"></sn-icon>
		</template>
	</sn-search>
</template>

<script lang="ts" setup>
const keyword = ref<string>('')

function onScan(): void {
	console.log('扫码')
}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值 | String | `''` | - |
| placeholder | 占位文本 | String | `请输入搜索内容` | - |
| type | 输入框键盘类型 | String | `text` | `text` \| `number` \| `digit` \| `tel` \| `idcard` \| `nickname` |
| padding | 输入框内边距 | String | `8px 12px` | - |
| textColor | 输入文本颜色 | String | `''` | - |
| textSize | 输入文本大小 | String \| Number | `''` | - |
| loading | 是否显示加载状态 | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用输入框 | Boolean | `false` | `true` \| `false` |
| readonly | 是否只读 | Boolean | `false` | `true` \| `false` |
| clearable | 是否显示清除按钮 | Boolean | `false` | `true` \| `false` |
| focus | 是否获得焦点 | Boolean | `false` | `true` \| `false` |
| showBorder | 是否显示边框 | Boolean | `true` | `true` \| `false` |
| showActiveBorder | 聚焦时是否切换为激活边框颜色 | Boolean | `true` | `true` \| `false` |
| showCancel | 是否显示取消按钮（聚焦时平滑展开） | Boolean | `false` | `true` \| `false` |
| fixCancel | 取消按钮是否常驻显示（不随聚焦收起） | Boolean | `false` | `true` \| `false` |
| cancelText | 取消按钮文本 | String | `取消` | - |
| cancelTextSize | 取消按钮文本大小 | String \| Number | `$14` | - |
| cancelTextColor | 取消按钮文本颜色 | String | `$primaryDark` | - |
| bgColor | 输入框背景颜色 | String | `$info` | - |
| activeBgColor | 聚焦时的背景颜色 | String | `$info` | - |
| activeBorderColor | 聚焦时的边框颜色 | String | `'$line'` | - |
| borderRadius | 输入框圆角大小 | String \| Number | `''` | - |
| borderColor | 输入框边框颜色 | String | `'$line'` | - |
| borderWidth | 输入框边框宽度 | String \| Number | `1px` | - |
| cursorColor | 光标颜色 | String | `''` | - |
| prefixIcon | 前置图标名称，存在 prefix 插槽时不显示 | String | `search-2-line` | - |
| suffixIcon | 后置图标名称，存在 suffix 插槽时不显示 | String | `''` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| inputStyle | 自定义内部输入框样式 | SnStyleValue | `''` | - |
| inputClass | 内部输入框的外部类 | String | `''` | - |
| cancelStyle | 自定义取消按钮样式 | SnStyleValue | `''` | - |
| cancelClass | 取消按钮的外部类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: string) => Void | 绑定值变化时触发，参数为当前输入内容 |
| focus | (event: UniInputFocusEvent) => Void | 输入框聚焦时触发 |
| blur | (event: UniInputBlurEvent) => Void | 输入框失去焦点时触发 |
| confirm | (event: UniInputConfirmEvent) => Void | 点击键盘搜索按钮时触发 |
| cancel | () => Void | 点击取消按钮时触发，同时会清空输入内容 |
| suffix-click | () => Void | 点击后置图标时触发 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| prefix | 自定义前置内容，使用后前置图标不显示 |
| suffix | 自定义后置内容，使用后后置图标不显示 |

<DemoPhone name="sn-search" />

# Collapse 折叠面板

> [查看 sn-collapse 的 2.0 版本差异](/differences/components/sn-collapse)

## 基础用法

折叠面板，用于收纳内容区域。

- 由折叠组与折叠项组合使用，点击子项头部展开 / 收起
- 默认多个子项独立展开，也可改为同一时间仅展开一个
- 子项支持标题、右侧说明文本与左侧图标，内容区高度自适应并带展开动画

```vue
<template>
	<sn-collapse-group>
		<sn-collapse-item title="如何联系客服？" note="FAQ">
			<sn-text text="点击右下角在线客服图标，或在「我的-帮助中心」提交工单。"></sn-text>
		</sn-collapse-item>
		<sn-collapse-item title="支持哪些支付方式？" note="FAQ">
			<sn-text text="支持微信支付、支付宝、银行卡以及余额支付。"></sn-text>
		</sn-collapse-item>
		<sn-collapse-item title="退换货政策说明" note="FAQ">
			<sn-text text="签收后 7 天内支持无理由退换货（不影响二次销售）。"></sn-text>
		</sn-collapse-item>
	</sn-collapse-group>
</template>
```

**更多演示请下载 demo 查看**

## 手风琴模式

开启 `accordion` 后，同一时间只展开一个子项，展开新子项时其余子项自动收起。

```vue
<template>
	<sn-collapse-group accordion>
		<sn-collapse-item title="账户安全" icon="shield-check-line">
			<sn-text text="建议开启双重验证，绑定手机与邮箱，定期更换密码。"></sn-text>
		</sn-collapse-item>
		<sn-collapse-item title="隐私设置" icon="lock-line">
			<sn-text text="可管理个人资料可见范围、消息通知偏好。"></sn-text>
		</sn-collapse-item>
	</sn-collapse-group>
</template>
```

## 自定义头部

通过 `header` 插槽可整体替换子项头部区域（替换标题、说明文本与展开箭头）。

```vue
<template>
	<sn-collapse-group>
		<sn-collapse-item>
			<template #header>
				<sn-icon name="vip-2-fill" :size="22" color="$warning"></sn-icon>
				<sn-text bold :font-size="15" text="SVIP 超级会员"></sn-text>
			</template>
			<sn-text text="开通 SVIP 年卡立享全年免运费、专属客服等权益。"></sn-text>
		</sn-collapse-item>
	</sn-collapse-group>
</template>
```

## 属性

**sn-collapse-group**

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| accordion | 是否开启手风琴模式（同一时间仅展开一个子项，展开新项时其余自动收起） | Boolean | `false` | `true` \| `false` |
| aniTime | 展开/收起动画时长，支持 `$` 简写 | String \| Number | `$snui.aniTimeNormal` | - |
| bgColor | 面板背景颜色 | String | `$front` | - |
| titleSize | 子项标题字体大小，支持 `$` 简写 | String \| Number | `15px × fontsizeFactor` | - |
| titleColor | 子项标题颜色 | String | `$title` | - |
| activeTitleColor | 展开状态子项标题颜色 | String | `$primary` | - |
| noteSize | 子项说明文本字体大小，支持 `$` 简写 | String \| Number | `13px × fontsizeFactor` | - |
| noteColor | 子项说明文本颜色（同时是展开箭头颜色） | String | `$lineText` | - |
| borderRadius | 面板圆角大小，支持 `$` 简写 | String \| Number | `8px × radiusFactor` | - |
| showBorder | 是否显示子项之间的分割线（末尾子项不显示） | Boolean | `true` | `true` \| `false` |
| titleStyle | 子项标题样式，作用于所有子项 | SnStyleValue | `''` | - |
| noteStyle | 子项说明文本样式，作用于所有子项 | SnStyleValue | `''` | - |
| holderStyle | 子项内容区容器样式，作用于所有子项 | SnStyleValue | `''` | - |
| titleClass | 子项标题外部样式类，透传至所有子项 | String | `''` | - |
| noteClass | 子项说明文本外部样式类，透传至所有子项 | String | `''` | - |
| holderClass | 子项内容区外部样式类，透传至所有子项 | String | `''` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |

**sn-collapse-item**

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| :--- | :--- | :--- | :--- | :--- |
| title | 子项标题 | String | `''` | - |
| note | 子项说明文本，显示在标题右侧 | String | `''` | - |
| icon | 子项标题左侧图标名称 | String | `''` | - |
| open | 初始状态是否展开 | Boolean | `false` | `true` \| `false` |
| disabled | 是否禁用（禁用后不可点击展开，标题与箭头显示禁用色） | Boolean | `false` | `true` \| `false` |
| titleClass | 当前子项标题外部样式类，与 group 级 `titleClass` 合并 | String | `''` | - |
| noteClass | 当前子项说明文本外部样式类，与 group 级 `noteClass` 合并 | String | `''` | - |
| holderClass | 当前子项内容区外部样式类（external-class：`holder-class`），与 group 级 `holderClass` 合并 | String | `''` | - |
| customStyle | 自定义子项根节点样式 | SnStyleValue | `''` | - |

子项未单独传入的标题/说明颜色与字号，继承 group 上设置的对应值。

## 方法

以下方法可通过模板 ref 调用，其中 `register`、`setOrder` 主要供组件内部协调使用，一般无需手动调用。

**sn-collapse-group**

| 名称 | 参数 | 返回值 | 描述 |
| :--- | :--- | :--- | :--- |
| closeAll | - | - | 收起所有子项（仅手风琴模式下生效） |
| register | node: ComponentPublicInstance | Void | 注册子项（供 sn-collapse-item 挂载时内部调用） |

**sn-collapse-item**

| 名称 | 参数 | 返回值 | 描述 |
| :--- | :--- | :--- | :--- |
| close | - | - | 收起当前子项 |
| setOrder | index: Number, border: Boolean | Void | 设置子项序号与是否显示底部分割线（供 sn-collapse-group 内部调用） |

## 插槽

**sn-collapse-group**

| 名称 | 说明 |
| :--- | :--- |
| default | 在这里放置子组件 `sn-collapse-item` |

**sn-collapse-item**

| 名称 | 说明 |
| :--- | :--- |
| default | 子项内部放置收纳的内容 |
| header | 自定义子项头部区域（替换标题、说明文本与展开箭头） |

<DemoPhone name="sn-collapse" />

# Sorter 排序

## 基础用法

排序组件，常用于列表排序切换。

- 点击在无序、升序、降序之间循环切换，也可仅在升序与降序之间切换
- 支持控制首次点击进入的方向
- 箭头通过颜色区分激活方向，激活与未激活颜色均可自定义

```vue
<template>
	<sn-sorter v-model="value" label="发布时间" @change="onChange"></sn-sorter>
</template>
```

**更多演示请下载 demo 查看**

## 自定义内容

默认插槽可替换标签内容，`arrow` 作用域插槽可完全自定义箭头区域（作用域参数 `{ value: number }`）。

```vue
<template>
	<sn-sorter v-model="value" allow-reset>
		<view class="slot-label">
			<sn-icon name="filter-3-line" :size="16" color="$primary" />
			<text>筛选结果</text>
		</view>
	</sn-sorter>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 排序状态：`0` 无序、`1` 升序、`-1` 降序 | Number | `0` | `0` \| `1` \| `-1` |
| label | 排序标签文本 | String | `''` | - |
| allowReset | 是否允许重置为无序（开启后按无序、升序、降序三态循环） | Boolean | `false` | `true` \| `false` |
| descFirst | 首次点击是否进入降序 | Boolean | `false` | `true` \| `false` |
| activeColor | 激活方向箭头的颜色 | String | `` `$primary` `` | - |
| inactiveColor | 非激活方向箭头的颜色 | String | `` `$textLight` `` | - |
| arrowSize | 箭头尺寸 | String \| Number | `$20` | - |
| disabled | 是否禁用 | Boolean | `false` | `true` \| `false` |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 自定义根节点样式类 | String | `''` | - |
| labelStyle | 自定义标签样式 | SnStyleValue | `''` | - |
| labelClass | 自定义标签样式类 | String | `''` | - |
| arrowStyle | 自定义箭头区域样式 | SnStyleValue | `''` | - |
| arrowClass | 自定义箭头区域样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: number) => Void | 排序状态变化时触发，携带新状态值（`0` 无序、`1` 升序、`-1` 降序） |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 替换标签文本内容 |
| arrow | 替换箭头区域，作用域参数 `{ value: number }` 为当前排序状态 |

<DemoPhone name="sn-sorter" />

# Timer 计时器

> [查看 sn-timer 的 2.0 版本差异](/differences/components/sn-timer)

## 基础用法

正向计时器，从 0 开始累计计时。

- 可自动开始，也可手动控制开始、暂停与重置
- 基于动画帧驱动，走秒平滑，可开启毫秒级刷新
- 计时变化时派发事件返回已计时数据；重置会停止当前计时并归零

```vue
<template>
	<sn-timer format="HH:mm:ss"></sn-timer>
</template>
```

**更多演示请下载 demo 查看**

## 时间格式

`format` 中支持以下占位符，某个单位占位符缺省时，该单位会自动进位到上一级（如格式中没有 `DD`，天数会折算进小时显示）：

| 占位符 | 说明 |
| :--- | :--- |
| `DD` | 天数，两位数补齐 |
| `HH` | 小时，两位数 |
| `mm` | 分钟，两位数 |
| `ss` | 秒，两位数 |
| `SSS` | 毫秒，三位数 |
| `SS` | 十毫秒，两位数 |
| `S` | 百毫秒，一位数 |

使用毫秒占位符（`SSS` / `SS` / `S`）时请开启 `millisecond`，否则毫秒部分不会随帧刷新。

## 自定义布局

使用默认插槽后，组件不再渲染内部文本，可配合 `change` 事件自行布局（参数为包含 `d`、`h`、`m`、`s`、`ms` 字段的 `SnTime` 对象），例如分段数字样式：

```vue
<template>
	<sn-timer format="HH:mm:ss" @change="onChange">
		<text>{{ h }}:{{ m }}:{{ s }}</text>
	</sn-timer>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| format | 时间格式，占位符见上方"时间格式" | String | `HH:mm:ss` | - |
| autoplay | 初始化后自动开始计时 | Boolean | `true` | `true` \| `false` |
| millisecond | 开启毫秒级刷新（显示毫秒占位符时务必开启） | Boolean | `false` | `true` \| `false` |
| textSize | 文本字体大小，支持 `$` 动态尺寸 | String \| Number | `$14` | - |
| textColor | 文本颜色，支持 `$` 主题色简写 | String | `$text` | - |
| selectable | 文本是否可选中复制 | Boolean | `false` | `true` \| `false` |
| bold | 文本是否加粗 | Boolean | `false` | `true` \| `false` |
| textClass | 文本节点外部样式类 | String | `''` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: `SnTime`) => Void | 计时时间变化时触发，参数为包含 `d`、`h`、`m`、`s`、`ms` 字段的 `SnTime` 对象 |

> 类型字段：SnTime（见 https://sinleui.pages.dev/api/types/component#sntime）


## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| start | - | - | 开始计时（或从暂停处继续） |
| pause | - | - | 暂停计时 |
| reset | - | - | 停止当前计时并归零；`autoplay` 为 `true` 时自动重新开始，为 `false` 时等待调用 `start()` |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 自定义计时内容，接管内部文本渲染，可配合 `change` 事件实现分段数字等布局 |

<DemoPhone name="sn-timer" />

# Countdown 倒计时

> [查看 sn-countdown 的 2.0 版本差异](/differences/components/sn-countdown)

## 基础用法

倒计时组件，用于展示一段剩余时间。

- 基于动画帧驱动，走秒平滑不跳秒，可开启毫秒级刷新
- 提供开始、暂停、重置与停止控制
- 剩余时间变化时派发事件返回时间数据

```vue
<template>
	<sn-countdown :time="3600000" format="HH:mm:ss" @finish="onFinish"></sn-countdown>
</template>
```

**更多演示请下载 demo 查看**

## 时间格式

`format` 中支持以下占位符，某个单位占位符缺省时，该单位会自动进位到上一级（如格式中没有 `DD`，天数会折算进小时显示）：

| 占位符 | 说明 |
| :--- | :--- |
| `DD` | 天数，两位数补齐 |
| `HH` | 小时，两位数 |
| `mm` | 分钟，两位数 |
| `ss` | 秒，两位数 |
| `SSS` | 毫秒，三位数 |
| `SS` | 十毫秒，两位数 |
| `S` | 百毫秒，一位数 |

使用毫秒占位符（`SSS` / `SS` / `S`）时请开启 `millisecond`，否则毫秒部分不会随帧刷新。

## 自定义布局

使用默认插槽后，组件不再渲染内部文本，可配合 `change` 事件自行布局（参数为包含 `d`、`h`、`m`、`s`、`ms` 字段的 `SnTime` 对象）：

```vue
<template>
	<sn-countdown :time="3661000" format="HH:mm:ss" @change="onChange">
		<text>{{ h }}时{{ m }}分{{ s }}秒</text>
	</sn-countdown>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| time | 倒计时总时长（单位 ms），变化时自动重置 | Number | `0` | - |
| format | 时间格式，占位符见上方"时间格式" | String | `HH:mm:ss` | - |
| autoplay | 初始化及重置后自动开始计时 | Boolean | `true` | `true` \| `false` |
| millisecond | 开启毫秒级刷新（显示毫秒占位符时务必开启） | Boolean | `false` | `true` \| `false` |
| textSize | 文本字体大小，支持 `$` 动态尺寸 | String \| Number | `$14` | - |
| textColor | 文本颜色，支持 `$` 主题色简写 | String | `$text` | - |
| selectable | 文本是否可选中复制 | Boolean | `false` | `true` \| `false` |
| bold | 文本是否加粗 | Boolean | `false` | `true` \| `false` |
| textClass | 文本节点外部样式类 | String | `''` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (value: `SnTime`) => Void | 剩余时间变化时触发，参数为包含 `d`、`h`、`m`、`s`、`ms` 字段的 `SnTime` 对象 |
| finish | () => Void | 倒计时归零时触发 |

> 类型字段：SnTime（见 https://sinleui.pages.dev/api/types/component#sntime）


## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| start | - | - | 开始计时（或从暂停处继续） |
| pause | - | - | 暂停计时 |
| reset | - | - | 重置为 `time` 设定的剩余时长，`autoplay` 为 `true` 时自动重新开始 |
| stop | - | - | 停止计时并归零，触发 `finish` 事件 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 自定义倒计时内容，接管内部文本渲染，可配合 `change` 事件实现个性化布局 |

<DemoPhone name="sn-countdown" />

# Countto 数字滚动

> [查看 sn-countto 的 2.0 版本差异](/differences/components/sn-countto)

## 基础用法

数字滚动组件，常用于数据大屏、经营数据展示等场景。

- 数字从起始值滚动到目标值，动画时长可配置
- 支持结束前减速的缓动效果
- 可控制小数位数并按位插入千分位式分隔符

```vue
<template>
	<sn-countto :end-val="6666"></sn-countto>
</template>
```

**更多演示请下载 demo 查看**

## 分割数字

`separate` 设为非 0 值后，整数部分每隔几位会用 `,` 分隔（小数部分不受影响），常用于金融场景：

```vue
<template>
	<sn-countto :end-val="1000000" :separate="3"></sn-countto>
</template>
```

## 自定义样式

通过 `text-size` / `text-color` / `bold` 与 `custom-style` 定制数字文本表现：

```vue
<template>
	<sn-countto :end-val="7777" text-size="$30" text-color="$successDark" bold></sn-countto>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| startVal | 开始值，变化时自动重新播放 | Number | `0` | - |
| endVal | 结束值，变化时自动重新播放 | Number | `0` | - |
| duration | 动画时长（单位 ms） | Number | `2000` | - |
| decimals | 小数位数（大于 0 时滚动过程数字带随机跳动效果） | Number | `0` | - |
| separate | 分割位数（整数部分每隔几位插入一次 `,`，`0` 为不分割） | Number | `0` | - |
| autoplay | 初始化后自动播放 | Boolean | `true` | `true` \| `false` |
| easing | 以 easeOutSine 缓动动画代替默认的 linear 动画，使动画在结束前减速 | Boolean | `false` | `true` \| `false` |
| textSize | 数字文本字体大小，支持 `$` 动态尺寸 | String \| Number | `$14` | - |
| textColor | 数字文本颜色，支持 `$` 主题色简写 | String | `$text` | - |
| selectable | 文本是否可选中复制 | Boolean | `false` | `true` \| `false` |
| bold | 文本是否加粗 | Boolean | `false` | `true` \| `false` |
| textClass | 文本节点外部样式类 | String | `''` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| finish | () => Void | 动画播放完成时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| play | - | - | 播放动画（从当前进度继续） |
| pause | - | - | 暂停动画 |
| stop | - | - | 停止动画并直接显示 `endVal`，触发 `finish` 事件 |
| reset | - | - | 重置到 `startVal`，`autoplay` 为 `true` 时自动重新播放 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 自定义数字内容，接管内部文本渲染 |

<DemoPhone name="sn-countto" />

# Fullscreen 原位展开全屏

## 基础用法

让一块内容“原位”拉伸占满整个视口的容器（如卡片、模拟播放器），收起时动画回到原位置。

- 展开期间原位置由等高占位节点撑住，页面布局不塌陷
- 默认点击内容即可展开
- 全屏时点击是否关闭可配置，也提供打开、关闭与切换方法

```vue
<template>
	<sn-fullscreen layer-style="width:100px;height:40px;" :click-close="true">
		<text>点我全屏</text>
	</sn-fullscreen>
</template>
```

**更多演示请下载 demo 查看**

## 进阶用法

### 关闭按钮模式

设置 `trigger-click="false"` 关闭点击自动展开，改由按钮或内容内关闭图标控制，适合播放器等场景。

```vue
<template>
	<sn-fullscreen ref="fsRef" :trigger-click="false">
		<view>
			<view @click="closeFs">
				<sn-icon name="close-line" :size="18" color="#fff" />
			</view>
		</view>
	</sn-fullscreen>
</template>
<script lang="ts" setup>
	const fsRef = ref<SnFullscreenComponentPublicInstance | null>(null)
	function openFs() {
		fsRef.value?.$callMethod('open')
	}
	function closeFs() {
		fsRef.value?.$callMethod('close')
	}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| triggerClick | 非全屏状态下点击内容层时自动展开全屏 | Boolean | `true` | `true` \| `false` |
| clickClose | 全屏状态下点击内容层时收起回到原位 | Boolean | `false` | `true` \| `false` |
| aniTime | 展开与收起的动画时长，`0` 为瞬时切换，支持 `$short`/`$normal`/`$long`（也接受不带 `$` 的同名写法），数字单位为 ms | String \| Number | `$long` | - |
| zIndex | 全屏时内容层的层级 | Number | `999` | - |
| disabled | 是否禁用（禁用后点击与方法均不生效） | Boolean | `false` | `true` \| `false` |
| layerClass | 内容层外部样式类 | String | `''` | - |
| layerStyle | 自定义内容层样式（通常用它设置内容的初始宽高） | SnStyleValue | `''` | - |
| customClass | 根节点外部样式类 | String | `''` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| open | () => Void | 开始展开全屏时触发 |
| close | () => Void | 开始收起（关闭全屏）时触发 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| open | - | - | 展开全屏；正在动画或已全屏、或内容层尺寸无效时不执行 |
| close | - | - | 收起并动画回到原位置；非全屏或正在动画时不执行 |
| toggle | - | - | 在全屏与原位之间切换 |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 内容层内容，全屏时随容器拉伸重新布局 |

<DemoPhone name="sn-fullscreen" />

# Clipper 图片裁剪

## 基础用法

内置完整裁剪交互的图片裁剪器，可卡片内嵌，也可作为整页裁剪器使用。

- 支持手势拖动 / 双指缩放图片与 8 向手柄调整裁剪框
- 底部提供比例预设、旋转 / 镜像与还原工具
- 导出结果为 PNG（base64），并返回尺寸、比例与旋转信息

```vue
<template>
	<sn-clipper image-url="/static/images/photo.png" @confirm="onConfirm"></sn-clipper>
</template>
```

**更多演示请下载 demo 查看**

## 进阶用法

### 作为整页裁剪器

设置 `fill-viewport` 后裁剪区自动占满父容器剩余空间，适合放在全屏页面中。

```vue
<template>
	<sn-page fill-content>
		<sn-clipper image-url="/static/images/photo.png" fill-viewport @cancel="onCancel"
			@confirm="onConfirm"></sn-clipper>
	</sn-page>
</template>
```

### 自定义比例预设

通过 `ratio-list` 自定义比例按钮，`ratio` 为 `0` 表示自由比例；`initial-ratio-id` 指定初始选中项。

> 说明：比例预设为横向排列，超出宽度时可横向滑动；Web / PC 端除滚动条外还支持按住鼠标左右拖动该区域滚动。

```vue
<template>
	<sn-clipper image-url="/static/images/photo.png" initial-ratio-id="id-card"
		:ratio-list="ratios"></sn-clipper>
</template>
<script lang="ts" setup>
	const ratios = [
		{ id: 'free', text: '自由', ratio: 0 },
		{ id: 'id-card', text: '身份证', ratio: 85.6 / 54.0 }
	] as SnClipperRatioItem[]
</script>
```

### 通过 ref 控制

```vue
<template>
	<sn-clipper ref="clipperRef" image-url="/static/images/photo.png"></sn-clipper>
</template>
<script lang="ts" setup>
	const clipperRef = ref<SnClipperComponentPublicInstance | null>(null)
	function rotate() {
		clipperRef.value?.$callMethod('rotateClockwise')
	}
	function exportImage() {
		clipperRef.value?.$callMethod('crop')
	}
</script>
```

## 实现原理

导出会等待图片、画布尺寸和绘制帧完成，首次进入页面即可得到有效裁剪结果。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| imageUrl | 要裁剪的图片路径，为空时显示“请传入图片”占位 | String | `''` | - |
| bgColor | 裁剪预览区背景颜色，支持 `$` 主题色简写 | String | `$page` | - |
| previewHeight | 预览区高度，数字单位为 px；`fill-viewport` 为 `true` 时忽略此值 | String \| Number | `360` | - |
| fillViewport | 是否让预览区撑满父容器剩余空间（整页裁剪模式） | Boolean | `false` | `true` \| `false` |
| tabBodyHeight | 底部工具面板主体区高度（预留，当前未生效，实际高度随字体大小乘数固定） | String \| Number | `''` | - |
| minCropWidth | 裁剪框最小宽度，数字单位为 px，为空时不限制 | String \| Number | `''` | - |
| minCropHeight | 裁剪框最小高度，数字单位为 px，为空时不限制 | String \| Number | `''` | - |
| minScale | 图片最小缩放比例 | Number | `1` | - |
| minCropPixels | 裁剪框对应原图的最小像素边长，用于限制最大放大倍数 | Number | `4` | - |
| outputScale | 输出倍率，导出图片尺寸 = 裁剪框尺寸 × 该倍率（再乘设备像素比） | Number | `1` | - |
| quality | 导出图片质量（0-1），当前导出固定为 PNG 格式 | Number | `1` | - |
| initialRatioId | 初始选中的比例项 id | String | `ratio-1-1` | - |
| ratioList | 比例预设列表 | SnClipperRatioItem[] | `自由、1:1、3:4、4:3、9:16、16:9 六项` | - |
| borderColor | 裁剪框边框与四角颜色 | String | `#FFFFFF` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部样式类 | String | `''` | - |

> 类型字段：SnClipperRatioItem（见 https://sinleui.pages.dev/api/types/component#snclipperratioitem）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| ready | (detail: SnClipperReadyDetail) => Void | 图片加载成功时触发，`detail` 包含 `width`、`height`（图片原始尺寸）与 `ratio`（当前比例） |
| change | (detail: SnClipperChangeDetail) => Void | 裁剪状态变化时触发（拖动、缩放、旋转、镜像、切换比例等），`detail` 包含 `rotation`、`flipX`、`flipY`、`scale`、`translateX`、`translateY`、`cropLeft`、`cropTop`、`cropWidth`、`cropHeight`、`ratio` |
| confirm | (detail: SnClipperConfirmDetail) => Void | 裁剪导出成功时触发 |
| cancel | () => Void | 点击取消（×）按钮时触发 |
| error | (error: SnClipperErrorDetail) => Void | 图片加载失败或导出失败时触发，`error.message` 为错误信息 |

> 类型字段：SnClipperConfirmDetail（见 https://sinleui.pages.dev/api/types/component#snclipperconfirmdetail）

> 类型字段：SnClipperReadyDetail（见 https://sinleui.pages.dev/api/types/component#snclipperreadydetail）

> 类型字段：SnClipperChangeDetail（见 https://sinleui.pages.dev/api/types/component#snclipperchangedetail）

> 类型字段：SnClipperErrorDetail（见 https://sinleui.pages.dev/api/types/component#snclippererrordetail）


## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| crop | - | - | 执行裁剪导出，成功后触发 `confirm` 事件；图片/画布未就绪时 toast 提示 |
| restore | - | - | 还原所有变换（旋转、镜像、缩放、平移、比例）至初始状态 |
| rotateCounterclockwise | - | - | 逆时针旋转 90°（别名 `rotateLeft`） |
| rotateClockwise | - | - | 顺时针旋转 90°（别名 `rotateRight`） |
| flipHorizontal | - | - | 左右镜像 |
| flipVertical | - | - | 上下镜像 |
| setRatio | (item: SnClipperRatioItem) | - | 切换为指定比例项并最大化裁剪框 |

<DemoPhone name="sn-clipper" />

# Signature 签名

> [查看 sn-signature 的 2.0 版本差异](/differences/components/sn-signature)

## 基础用法

手写签名板，适用于电子签署与自由书写。

- 提供多种笔触和画布背景、网格设置
- 支持撤销、重做、清空、导出与横竖屏切换
- 设置面板支持分类切换与滚动操作

::: details 设置面板与笔触说明
设置面板为组件内部自实现的覆盖层（非 `sn-drawer`），左右滑出动画只做 `transform` 过渡、显隐交给 `visibility`，无打开闪动；面板展开期间画布区不响应落笔，面板内 Tabs、滑块、开关等交互在横竖屏下一致可用；App 端面板内容区为组件内自实现的拖动滚动与横向 Tabs 切换，避免原生全屏容器内 `scroll-view` 子元素点击/触摸异常。

内置 17 种笔触（钢笔、毛笔、蜡笔、喷漆等），设置面板采用 Tabs 分类：「笔触」（笔触类型、线条颜色与粗细）与「画布」（画布背景、网格背景），点选标签或左右滑动内容区切换分类，面板内容区可上下拖动滚动；滚动后仍可点击当前可见的笔触按钮、色块和滑块。通过 ref 调用 `undo`、`redo`、`clear`、`exportImage`、`setLandscape` 方法可编程控制签名板。
:::

```vue
<template>
	<sn-signature @exported="onExported"></sn-signature>
</template>
```

**更多演示请下载 demo 查看**

## 进阶用法

### 自定义笔触

通过 `brush` 属性指定初始笔触，设置面板内也可实时切换；`show-brush-settings` 为 `false` 时隐藏面板中的笔触选项。

```vue
<template>
	<sn-signature brush="pen" height="220" :show-brush-settings="true"></sn-signature>
</template>
```

### 横屏签名

点击操作栏的横屏图标可全屏横置签名板（Web 端铺满视口，App 端调用原生全屏横屏）；也可通过 ref 调用 `setLandscape` 方法控制。横屏后签名板按当前窗口高度铺满屏幕，画布自动占据操作栏之外的全部空间。

App 端原生全屏（`requestFullscreen`）容器内，`scroll-view` 的子元素收不到点击/触摸事件（只有原生滚动仍生效），因此设置面板内容区在 App 端改为组件内自实现的拖动滚动与横向 Tabs 切换，横屏下 Tabs、滑块、开关、取色块均正常响应。

```vue
<template>
	<sn-signature ref="sigRef"></sn-signature>
</template>
<script lang="ts" setup>
	const sigRef = ref<SnSignatureComponentPublicInstance | null>(null)
	function toLandscape() {
		sigRef.value?.$callMethod('setLandscape', true)
	}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| width | 签名板宽度，支持 `$` 动态尺寸语法 | String \| Number | `100%` | - |
| height | 签名板（画布区）高度，数字单位为 px，支持 `$` 动态尺寸语法 | String \| Number | `280` | - |
| bgColor | 画布背景颜色，同时作为导出图片的背景色 | String | `#FFFFFF` | - |
| lineColor | 签名线条颜色 | String | `#1F1F1F` | - |
| lineWidth | 线条粗细（px） | Number | `3` | - |
| brush | 笔触样式 | `SnSignatureBrush` | `default` | `default`(默认) \| `pen`(钢笔) \| `gel`(中性笔) \| `pencil`(铅笔) \| `brush`(毛笔) \| `marker`(马克笔) \| `crayon`(蜡笔) \| `fur`(毛皮) \| `ink`(墨水) \| `longfur`(长绒毛) \| `ribbon`(丝带) \| `shaded`(阴影) \| `sketchy`(速写) \| `spray`(喷漆) \| `squares`(方格) \| `circle`(圆泡) \| `web`(蛛网) |
| showBrushSettings | 设置面板中是否显示笔触选项 | Boolean | `true` | `true` \| `false` |
| gridEnabled | 是否显示网格背景 | Boolean | `false` | `true` \| `false` |
| gridStyle | 网格样式，`gridEnabled` 为 `true` 时生效 | `SnSignatureGridStyle` | `square` | `dot` \| `square` \| `line` |
| gridColor | 网格线颜色 | String | `#B8B8B8` | - |
| gridLineWidth | 网格线宽（px） | Number | `1` | - |
| gridDensity | 网格密度，即网格间距（px） | Number | `20` | - |
| maxHistory | 最大撤销历史记录数 | Number | `20` | - |
| showActionBar | 是否显示底部操作栏（横竖屏、撤销、重做、清空、设置、导出） | Boolean | `true` | `true` \| `false` |
| drawerPosition | 设置面板滑出的方向 | String | `right` | `left` \| `right`（`top`/`bottom` 视为 `right`） |
| drawerWidth | 设置面板宽度 | String \| Number | `300px` | - |
| aniTime | 设置面板动画时长，支持 `$` 动态时长语法 | String \| Number | `''` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部样式类 | String | `''` | - |
| canvasWrapClass | 画布容器外部样式类 | String | `''` | - |
| canvasWrapStyle | 自定义画布容器样式 | SnStyleValue | `''` | - |
| barClass | 操作栏外部样式类 | String | `''` | - |
| barStyle | 自定义操作栏样式 | SnStyleValue | `''` | - |
| toolClass | 操作栏工具按钮外部样式类 | String | `''` | - |

> 类型字段：SnSignatureBrush（见 https://sinleui.pages.dev/api/types/component#snsignaturebrush）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | (data: SignatureData) => Void | 签名内容变化时触发（一笔结束、撤销、重做、清空），`data.dataUrl` 为空字符串，`width`/`height` 为当前画布尺寸 |
| exported | (data: SignatureData) => Void | 导出签名图片成功后触发，`data.dataUrl` 为 base64 图片数据，`width`/`height` 为图片实际像素尺寸（已乘设备像素比） |
| undo | () => Void | 撤销签名时触发 |
| redo | () => Void | 重做签名时触发 |
| clear | () => Void | 清空签名板时触发 |
| orientationchange | (landscape: boolean) => Void | 横竖屏切换时触发，参数为是否横屏 |

> 类型字段：SnSignatureGridStyle（见 https://sinleui.pages.dev/api/types/component#snsignaturegridstyle）

> 类型字段：SignatureData（见 https://sinleui.pages.dev/api/types/component#signaturedata）


## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| undo | - | - | 撤销上一笔签名 |
| redo | - | - | 重做上一笔撤销的签名 |
| clear | - | - | 清空签名板 |
| exportImage | - | - | 将签名导出为 base64 图片并通过 `exported` 事件返回；画布未就绪或无内容时以 toast 提示且不导出 |
| setLandscape | (land: Boolean) | - | 设置横屏（全屏）模式，`true` 进入横屏、`false` 退出 |

<DemoPhone name="sn-signature" />

# Sketchpad 画板

## 基础用法

独立的手写画板组件，适用于签名、涂鸦、笔记等自由绘制场景。

- 支持画笔、橡皮与取色器，内置 18 种笔触与侧面色板
- 支持撤销 / 重做、清空与导出图片，可随时新建指定尺寸画布
- 支持网格背景与漫游模式（拖动画布、捏合缩放、松手惯性滑行），配色跟随主题

```vue
<template>
	<sn-sketchpad @exported="onExported" />
</template>
```

**更多演示请下载 demo 查看**

## 笔触与操作栏

内置 18 种笔触（含橡皮），完整取值可在属性表 `brush` 行展开查看。画笔与橡皮的粗细相互独立：切换工具后，颜色与粗细弹层、设置面板中的粗细滑块会自动指向当前工具的独立数值，互不干扰。画笔粗细范围为 1–128px、橡皮为 2–128px；蜡笔等笔触的粗细已与铅笔对齐，小尺寸下不再异常粗重。

顶部悬浮操作组提供漫游模式、重置视图、撤销、重做、清空、横竖屏切换与导出。竖屏底部控制区分为两行：上排为可横向拖动的紧凑笔触按钮，选中时显示主题色描边、浅色背景，图标与文字同步高亮；下排的画笔、橡皮、取色器与设置入口采用图标在上、文字在下的无底框布局，图标缩小但保持原有触控区域，中间保留圆形颜色与粗细入口。横屏时快捷笔触栏并入工具行，留出更多绘图区；横向拖动后可继续点击可见的笔触按钮。

设置面板采用抽屉样式与 Tabs 分类：「笔触」（全部笔触、线条颜色与粗细、端点样式）、「画布」（画布尺寸、画布背景、网格样式与参数、最大撤销步骤数）与「功能」（漫游模式、取色器、侧面色板、多指绘制开关与缩放控制）；点选标签或左右滑动内容区切换分类。内容区和选项按钮采用紧凑内边距；各分类的内容可纵向惯性滚动并独立保留滚动位置，滚动后可继续操作当前可见的按钮、色块、滑块与开关；底部完成按钮保持紧凑高度。

操作栏和设置面板中的按钮、色块均由原生视图实现；设置按钮通过统一点击态机制提供按下反馈。

`lineCap`（默认 `round`）控制笔触端点形状：`butt` 平头、`square` 方头、`round` 圆头，设置面板「笔触」分类内以「平头 / 方头 / 圆头」显示并可切换。它对线型笔触（默认、钢笔、中性笔、马克笔、铅笔、毛笔等以线条描边为主的笔触）生效，每笔落笔时固定，改变设置只影响之后的笔画。

`multiTouch`（默认 `false`）控制多指绘制：开启后可用多根手指同时在画布上绘制，多笔并行互不干扰；关闭时仅响应第一根手指。漫游模式下点击画笔 / 橡皮 / 取色器按钮或任一画笔类型（即使点击的是当前已选中的笔刷）都会自动退出漫游模式并切回绘制模式，仅调整颜色与粗细不会退出。

## 全屏画板

将 `height` 设为 `fill`，并配合 `sn-page` 的 `fill-content` 属性（内容区填满剩余高度、不滚动）即可让画板铺满整个页面：

绘制事件仅在实际画布范围内生效。自适应画布已有内容时，页面可用空间变化会同步调整逻辑画布并迁移已有笔迹。

::: warning 横竖屏切换
如果需要切换横竖屏后保持绘制内容不变形，必须选定画布尺寸（同时指定 `canvasWidth` 和 `canvasHeight`，或在设置面板选择固定尺寸），不要使用「适应组件」。
:::

```vue
<template>
	<sn-page title="画板" :show-back="true" fill-content>
		<sn-sketchpad height="fill" />
	</sn-page>
</template>
```

Demo 页收到导出成功事件后，竖屏直接以 `sn-popup` 展示导出图片；横屏先调用 `setLandscape(false)` 退出全屏，待 `orientationchange(false)` 后再打开弹窗。预览使用 `image` 的 `aspectFit` 模式，点击关闭按钮或遮罩可返回画板。

## 横屏模式

点击顶部悬浮栏的横屏图标可进入原生全屏横屏，再次点击退出；也可通过 ref 调用 `setLandscape` 方法控制。横屏后画板根据原生全屏事件获取当前窗口尺寸，绘图区自动占据底部工具栏之外的全部空间；默认底部设置抽屉在横屏下适当增高，左右两侧叠加屏幕安全区和固定留白，避开刘海、挖孔区域（自定义抽屉尺寸保持原值）；组件卸载时会自动退出全屏。

横屏时首次触发页面返回会退出横屏并留在当前页面；恢复竖屏后再次返回，由页面按默认行为处理。iOS 侧滑返回默认不触发页面返回事件，不在此拦截范围内。

```vue
<template>
	<sn-sketchpad ref="padRef" />
</template>
<script lang="ts" setup>
	import type { ComponentPublicInstance } from 'vue'

	const padRef = ref<ComponentPublicInstance | null>(null)
	function toLandscape() {
		padRef.value?.$callMethod('setLandscape', true)
	}
</script>
```

## 网格样式

`gridStyle` 支持 `dot`（点阵）、`square`（方格）、`line`（横线）三种样式，与「无网格」组成设置面板中的四态选择；`gridEnabled` 为 `false` 时等同于「无」，不显示网格。

```vue
<template>
	<sn-sketchpad grid-enabled grid-style="dot" :grid-density="24"></sn-sketchpad>
	<sn-sketchpad grid-enabled grid-style="line" :grid-density="30"></sn-sketchpad>
</template>
```

## 画布尺寸

通过 `canvasWidth` / `canvasHeight` 指定画布逻辑尺寸（px，取值 64–4096），需同时大于 0 才生效；任一为 0（默认）时画布自动适应组件尺寸。画布尺寸大于组件显示区域时会等比缩放适配显示，导出位图的 `width` / `height` 以实际渲染倍率为准；该倍率只由画布尺寸、组件显示尺寸与设备像素比决定，**与当前漫游缩放倍率无关**，因此同一画布在不同缩放下导出结果一致。

也可通过 ref 调用 `newCanvas(width, height)` 随时新建指定尺寸画布，新画布会清空当前笔画与历史（`width`、`height` 传 0 或省略时恢复自适应尺寸）：

```vue
<template>
	<sn-sketchpad ref="padRef" :canvas-width="1080" :canvas-height="1440" />
	<sn-button text="新建 512×512 画布" @click="onNewCanvas"></sn-button>
</template>

<script lang="uts" setup>
	const padRef = ref<SnSketchpadComponentPublicInstance | null>(null)

	function onNewCanvas() {
		padRef.value?.$callMethod('newCanvas', 512, 512)
	}
</script>
```

设置面板「画布」分类内置 `适应组件`、`1:1`、`4:3`、`16:9`、`9:16` 比例预设与自定义宽高输入。

画布之外会露出垫层（底色）：垫层颜色可在设置面板「画布」→「画布垫层」中配置，或通过 `underlayColor` 属性指定，画布自身带一圈可见边界线，便于区分画布范围；橡皮擦除只作用在笔画层，擦掉处露出画布背景与网格。

## 漫游模式

`roamEnabled` 为 `true`（默认）时，左上角悬浮操作组首位显示漫游开关；开启后单指拖动画布、双指捏合缩放（缩放范围 25%–800%），拖动松手后按松手速度惯性滑行并指数阻尼减速，撞到平移边界立即停止；此时画布不接受落笔；点击画笔 / 橡皮 / 取色器，或切换笔触（快捷笔刷栏与设置面板中的笔触选项）会自动退出漫游模式，仅调整颜色或粗细不会退出。漫游中悬浮组会依次显示「重置视图」、缩小、放大按钮（每次缩放步长由 `zoomStep` 控制，默认 10%），设置面板「功能」分类也提供缩小、重置、放大控制与当前缩放比例显示（缩放比例在松手后更新，避免手势中反复刷新面板）。

平移范围受限，画布不会被移出屏幕：画布边角最远只能移动到视口中心，即画布始终覆盖视口中心点——因此拖动可以露出画布边界外的垫层，但画布始终有一部分留在视口内、不会被整体移出。缩小 / 放大以视口中心为锚点（捏合则以两指中点为锚点），视角不会因缩放而跳动。

### 渲染与清晰度

画板由底图层和笔画层组成，两层同处一个合成层（漫游时只改这一层的合成变换、不做任何重绘），因此手势始终跟手：

- **底图**：画布背景与网格，整幅画布尺寸；
- **笔画层**：全部笔画的全幅画布，内容变化时仅重绘该层，手势过程不触发整幅位图重建。

画布位图尺寸由画布尺寸、组件显示尺寸与设备像素比决定：App 平台画布位图尺寸只读、由平台按画布元素布局尺寸决定（`canvas.width/height` 赋值不生效），Web 端由框架按设备像素比设置。绘制倍率始终按画布**实际位图尺寸**反推（`canvas.width / 画布逻辑宽度`），保证屏幕坐标与画布内容坐标严格一致。

App 端笔画层在创建时与画布尺寸变化时按位图像素预算一次性预留放大分辨率（通过画布元素的布局尺寸实现，位图随布局自动放大到该分辨率），因此放大后笔画依然清晰。漫游缩放与平移全程只做合成变换，不重建位图、不改变画布尺寸与内容，手势期间无闪动、无偏移。

::: info
放大分辨率受位图像素预算（约 800 万像素）封顶，极大画布或极高倍率下会优先保证稳定性；App 平台画布位图尺寸只读，清晰度上限由设备像素比与画布布局尺寸决定。
:::

拖动 / 缩放过程中只对整个 stage 做合成变换；快速连续拖动或缩放不会重绘画布。

### 大画布与大量笔画

笔画较多时，整幅重建会被拆成按帧预算（约 8ms）执行的分片任务，在 `requestAnimationFrame` 回调间推进：UI 线程不会被一次重建长时间占住，按钮、面板等交互全程可用，画面则从旧内容平滑地补全为新内容。笔画很少时（不超过 150 笔）仍然一次性同步完成，避免无谓的分帧开销。同一时刻只存在一个重建任务，新的手势、撤销重做、清空、导出都会正确接管或取消它。

笔画渲染本身的复杂度也已收敛：`shaded`、`sketchy`、`fur`、`longfur`、`web` 这类"纤维"笔刷原先对每一段都回溯该笔画此前的**全部**点（长笔画退化为 O(n²)），现在改为只回溯弧长范围内的邻近点，长笔画的开销与点数线性相关。

```vue
<template>
	<sn-sketchpad roam-enabled :canvas-width="2000" :canvas-height="2000" />
</template>
```

## 取色器与侧面色板

`eyedropperEnabled`（默认 `true`）控制工具栏吸管工具，点击画布任意位置吸取颜色：吸取结果会设为当前笔触颜色、触发 `pick` 事件，并在侧面色板开启时自动加入色板。橡皮工具旁的吸管图标仅在开启时显示。

`paletteEnabled`（默认 `true`）控制画布侧边的色板：色点为圆形排列，点击应用为当前笔触颜色（可快速切换笔刷颜色），长按删除色点；「+」按钮打开颜色选择器（弹窗内同时展示内置预设颜色），横屏下会先退出横屏、待布局恢复后再打开颜色选择器，点击已有色点则保持横屏并直接选色。色板同步展示在弹窗底部的 `extra` 插槽中——点击色点将该颜色载入取色面板（再点「确定」生效），长按色点删除，直接用取色面板选好颜色后点「确定」即可把新颜色加入色板，色板为空时插槽内会显示空状态提示；`palettePosition` 可设为 `left` 或 `right`（默认）决定色板所在侧，`paletteColors` 提供初始色板颜色。色板容量随画布显示高度自适应，超出时不再允许添加。

:::tip 提示
uvue 的事件系统不提供右键事件（`UniMouseEvent` 无按键信息），色点删除统一使用长按（触屏）或按住鼠标左键（Web）约 0.65 秒实现。
:::

```vue
<template>
	<sn-sketchpad :palette-colors="['#1F1F1F', '#EF4444', '#3B82F6']" palette-position="left"
		@pick="onPick" @palettechange="onPaletteChange" />
</template>
```

## 撤销与重做

撤销/重做的历史由框架的 [`useHistory`](/api/hooks/use-history) 增量操作日志引擎驱动，理解它的存储模型有助于正确设置 `maxHistory`：

- **一笔即一步**：每一笔完整笔画（含橡皮笔画与点按产生的短笔画）记录为一步，不做按时间窗口的连笔合并，撤销语义与「撤销上一笔」完全一致。
- **不存快照**：历史只记录每一步在笔画池中的下标与权重，既不复制笔画，也不缓存画布位图，因此历史内存与「笔画的点数」成正比，而不是与步数 × 画布面积成正比。
- **两步预算**：`maxHistory` 是步数上限；此外引擎还有 12 万点的权重预算，笔画特别密集时实际可撤销步数会少于 `maxHistory`，但内存占用始终有上限。
- **可在设置面板调节**：设置面板「画布」分类底部提供「最大撤销步骤数」滑块，范围 1–100（`maxHistory` 传入大于 100 时滑块上限随之扩展）；面板改动即时生效，调小后立刻回收多余的历史步骤，`maxHistory` prop 变化时也会同步回面板。
- **重做失效时机**：只有「当前笔结束、产生新的一步」会清空重做；切换工具、改颜色、改网格、横竖屏切换都不会丢弃已撤销的内容。
- **清空会重置历史**：调用 `clear` 方法（或点击清空按钮）后撤销栈一并清空，此前的内容无法再撤销。
- **落笔期间不接受撤销**：手指未离开画布时调用 `undo`、`redo` 或 `clear` 会被忽略，避免历史与画布内容不同步。

撤销只对受影响的区域做增量重绘：先清掉被撤销笔画的包围盒，再按顺序重放与之相交的笔画；重做则只补画被恢复的那一笔。因此撤销、重做的开销与「相交笔画数」相关，而不是与总笔画数相关。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| width | 画板宽度，支持 `$` 动态尺寸语法 | String \| Number | `100%` | - |
| height | 画布高度，数字单位为 px，传入 `fill` 时画布占满组件剩余高度（配合 `sn-page` 的 `fill-content` 可铺满全屏） | String \| Number | `280` | - |
| canvasWidth | 指定画布逻辑宽度（px，64–4096），需与 `canvasHeight` 同时大于 0；任一为 0 时画布自适应组件尺寸 | Number | `0` | - |
| canvasHeight | 指定画布逻辑高度（px，64–4096），需与 `canvasWidth` 同时大于 0；任一为 0 时画布自适应组件尺寸 | Number | `0` | - |
| bgColor | 画布背景和导出图片背景颜色，为空时跟随主题（亮色 `#FFFFFF`、暗色 `#28292A`） | String | `跟随主题` | - |
| underlayColor | 画布垫层（画布边界之外的底衬）颜色，为空时跟随主题（亮色 `#E5E7EB`、暗色 `#141416`） | String | `跟随主题` | - |
| lineColor | 笔触颜色，为空时跟随主题（亮色 `#1F1F1F`、暗色 `#F1F1F1`） | String | `跟随主题` | - |
| lineWidth | 笔触粗细，单位 px | Number | `3` | - |
| eraserWidth | 橡皮粗细，单位 px | Number | `16` | - |
| brush | 初始笔触类型 | `SnSketchpadBrush` | `default` | - |
| lineCap | 笔触端点样式，设置面板「笔触」分类内可切换 | String | `round` | `butt` \| `square` \| `round` |
| showBrushSettings | 是否显示快捷笔刷栏与设置面板中的笔触选项 | Boolean | `true` | `true` \| `false` |
| multiTouch | 是否开启多指绘制（设置面板「功能」分类内可切换） | Boolean | `false` | `true` \| `false` |
| gridEnabled | 是否显示网格背景 | Boolean | `false` | `true` \| `false` |
| gridStyle | 网格样式，`gridEnabled` 为 `true` 时生效 | `SnSketchpadGridStyle` | `square` | `dot` \| `square` \| `line` |
| gridColor | 网格颜色 | String | `#B8B8B8` | - |
| gridLineWidth | 网格线宽，单位 px | Number | `1` | - |
| gridDensity | 网格间距，单位 px | Number | `20` | - |
| maxHistory | 最大撤销步骤数，设置面板内可直接调节（默认上限 100） | Number | `20` | - |
| roamEnabled | 是否启用漫游模式（左上角悬浮按钮与设置面板开关） | Boolean | `true` | `true` \| `false` |
| eyedropperEnabled | 是否启用取色器（工具栏吸管工具与设置面板开关） | Boolean | `true` | `true` \| `false` |
| paletteEnabled | 是否启用侧面色板 | Boolean | `true` | `true` \| `false` |
| palettePosition | 侧面色板位置 | String | `right` | `left` \| `right` |
| paletteColors | 侧面色板初始颜色 | Array\<String\> | `空` | - |
| zoomStep | 漫游缩放按钮每次放大 / 缩小的百分比步长 | Number | `10` | - |
| showActionBar | 是否显示操作栏（顶部悬浮按钮与底部控制区） | Boolean | `true` | `true` \| `false` |
| drawerPosition | 设置面板方向 | String | `bottom` | `top` \| `right` \| `bottom` \| `left` |
| drawerWidth | 设置面板尺寸，`left`/`right` 为宽度、`top`/`bottom` 为高度，支持百分比 | String \| Number | `70%` | - |
| aniTime | 设置面板动画时长 | String \| Number | `''` | - |
| customStyle | 根节点样式 | UTSJSONObject \| String | `''` | - |
| customClass | 根节点外部样式类 | String | `''` | - |
| canvasWrapClass | 画布容器外部样式类 | String | `''` | - |
| canvasWrapStyle | 画布容器样式 | UTSJSONObject \| String | `''` | - |
| barClass | 底部控制区外部样式类 | String | `''` | - |
| barStyle | 底部控制区样式 | UTSJSONObject \| String | `''` | - |
| toolClass | 操作按钮外部样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| change | `(data: SketchpadData) => Void` | 一笔结束、撤销、重做、清空或画布尺寸变化后触发 |
| exported | `(data: SketchpadData) => Void` | 导出图片成功后触发，`dataUrl` 为 base64 图片数据 |
| undo | `() => Void` | 撤销成功后触发 |
| redo | `() => Void` | 重做成功后触发 |
| clear | `() => Void` | 清空成功后触发 |
| pick | `(color: string) => Void` | 取色器吸取颜色后触发 |
| palettechange | `(colors: Array<String>) => Void` | 侧面色板颜色增删后触发 |
| orientationchange | `(landscape: Boolean) => Void` | 横竖屏模式切换后触发 |

## 方法

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| undo | - | 撤销上一笔 |
| redo | - | 重做上一笔撤销的内容 |
| clear | - | 清空画板 |
| exportImage | - | 导出为 base64 图片并触发 `exported` |
| setLandscape | `land: Boolean` | 设置横屏或竖屏模式 |
| newCanvas | `width?: Number, height?: Number` | 新建指定尺寸画布并覆盖当前画布（清空笔画与历史）；传 0 或省略恢复自适应尺寸 |
| resetView | - | 重置漫游视图（缩放恢复 100%、平移归零） |

> 类型字段：SnSketchpadBrush（见 https://sinleui.pages.dev/api/types/component#snsketchpadbrush）

> 类型字段：SnSketchpadGridStyle（见 https://sinleui.pages.dev/api/types/component#snsketchpadgridstyle）

> 类型字段：SketchpadData（见 https://sinleui.pages.dev/api/types/component#sketchpaddata）


<DemoPhone name="sn-sketchpad" />

# CalendarPunch 签到日历

## 基础用法

签到打卡日历，是日历组件的打卡形态。

- 已打卡、可补签与今天分别以圆点或文字高亮区分
- 可关闭补签；周起始日与标题格式可配置
- 组件不执行签到，业务在日期选择回调中处理打卡 / 补签

```vue
<template>
	<sn-calendar-punch v-model="selected" :signed-dates="signedDates" @select="onSelect"></sn-calendar-punch>
</template>

<script lang="ts" setup>
	import { dayuts } from '@/uni_modules/sinle-ui/index.ts'
	import type { SnCalendarPunchDay, SnCalendarValue } from '@/uni_modules/sinle-ui/index.ts'

	const signedDates = ref<string[]>([dayuts().format('YYYY-MM-06'), dayuts().format('YYYY-MM-09')])
	const selected = ref<SnCalendarValue>(null)

	function onSelect(day: SnCalendarPunchDay): void {
		if (day.signed) return
		signedDates.value.push(day.fullDate)
	}
</script>
```

**更多演示请下载 demo 查看**

## 进阶用法

### 关闭补签

```vue
<template>
	<sn-calendar-punch v-model="selected" :signed-dates="signedDates" :can-supplement="false"></sn-calendar-punch>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| v-model | 绑定值（type 固定为 single，实际为当天零点时间戳或 null） | SnCalendarValue | `null` | - |
| signedDates | 已打卡日期列表（YYYY-MM-DD，无效值自动忽略，按天匹配） | String[] | `[]` | - |
| canSupplement | 是否允许补签（为 true 时未打卡且不晚于今天的日期显示补签圆点） | Boolean | `true` | `true \| false` |
| signedDotColor | 已打卡圆点颜色，支持 $ 简写 | String | `$primary` | - |
| unsignedDotColor | 可补签圆点颜色，支持 $ 简写 | String | `$warning` | - |
| todayText | 今天日期显示的文字，空时显示原始日期 | String | `今天` | - |
| todayTextColor | 今天文字颜色，支持 $ 简写 | String | `$warning` | - |
| minDate | 最小可选日期（毫秒时间戳），默认 6 个月前的当月 1 号 | Number | - | - |
| maxDate | 最大可选日期（毫秒时间戳），默认当天起 6 个月 | Number | - | - |
| firstDayOfWeek | 每周第一天（0 为周日） | Number | `1` | `0~6` |
| readonly | 是否只读（禁用切换与选择） | Boolean | `false` | `true \| false` |
| titlePicker | 点击标题是否展开年月选择面板 | Boolean | `false` | `true \| false` |
| switchLongpress | 长按左右切换按钮是否连续切换 | Boolean | `true` | `true \| false` |
| showWatermark | 是否显示月份水印数字 | Boolean | `false` | `true \| false` |
| rowHeight | 单行日期高度 | String \| Number | `$48` | - |
| height | 视图整体高度 | String \| Number | `$420` | - |
| dayFontSize | 日期字号 | String \| Number | `$14` | - |
| dayRadius | 日期气泡圆角 | String \| Number | `$6` | - |
| dayGap | 日期气泡与单元格边缘的间距 | String \| Number | `$2` | - |
| selectedDayBgColor | 选中日期背景色，支持 $ 简写 | String | `$line` | - |
| selectedDayTextColor | 选中日期文字颜色，支持 $ 简写 | String | `$text` | - |
| dayTextColor | 日期文字颜色 | String | `$text` | - |
| adjacentDayTextColor | 非当前月日期文字颜色 | String | `$lineText` | - |
| disabledDayTextColor | 禁用日期文字颜色 | String | `$disabledText` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | `''` | - |
| customClass | 外部样式类 | String | `''` | - |
| headerStyle | 自定义头部样式 | SnStyleValue | `''` | - |
| headerClass | 外部样式类 | String | `''` | - |
| switchStyle | 自定义月份切换按钮样式 | SnStyleValue | `''` | - |
| switchClass | 外部样式类 | String | `''` | - |
| weekdaysStyle | 自定义星期标题行样式 | SnStyleValue | `''` | - |
| weekdaysClass | 外部样式类 | String | `''` | - |
| weekdayStyle | 自定义单个星期标题样式 | SnStyleValue | `''` | - |
| weekdayClass | 外部样式类 | String | `''` | - |
| monthTitleStyle | 自定义月份标题文字样式 | SnStyleValue | `''` | - |
| monthTitleClass | 外部样式类 | String | `''` | - |

> 类型字段：SnCalendarValue（见 https://sinleui.pages.dev/api/types/component#sncalendarvalue）


## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| select | (day: `SnCalendarPunchDay`) => Void | 点击选中日期时触发，返回打卡信息（`SnCalendarPunchDay`，见下方类型） |
| panel-change | (detail: `SnCalendarPanelChangeDetail`) => Void | 面板所在月份变化时触发 |

> 类型字段：SnCalendarPunchDay（见 https://sinleui.pages.dev/api/types/component#sncalendarpunchday）

> 类型字段：SnCalendarPanelChangeDetail（见 https://sinleui.pages.dev/api/types/component#sncalendarpanelchangedetail）


## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| scrollToDate | (value: Number) | - | 选中指定日期（毫秒时间戳）并跳转到其所在月份 |

## 类型

`SnCalendarPanelChangeDetail` 与 `format` 相关的 `SnCalendarDay` 等类型见 `sn-calendar-view` 文档的「类型」一节。

<DemoPhone name="sn-calendar-punch" />

# Barcode 一维码

> [查看 sn-barcode 的 2.0 版本差异](/differences/components/sn-barcode)

## 基础用法

纯 Canvas 自绘的一维码组件，不依赖原生条码库。

- 支持 9 种常见一维码格式，可旋转与圆角化显示
- 可在条码下方显示编码文本
- 编码内容按 UTF-8 字节数计算，上限 300 字节，超出自动截断

::: info 首帧渲染
组件在画布取得实际尺寸后绘制首帧，首次进入页面即可正常显示，无需再次进入。
:::

```vue
<template>
	<sn-barcode value="SN-20260820" code-type="code128"></sn-barcode>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| value | 条形码数据 | String | `SN-20260820` | - |
| codeType | 条形码格式 | `SnBarcodeFormat` | `code128` | `code128` \| `code39` \| `code93` \| `codabar` \| `ean8` \| `ean13` \| `upca` \| `upce` \| `itf` |
| width | 条码区域宽度，最小 48px | String \| Number | `280` | - |
| height | 条码区域高度，最小 24px | String \| Number | `96` | - |
| padding | 左右留白边距 | String \| Number | `8` | - |
| rotation | 旋转方向 | String | `N` | `N` 正常 \| `L` 左转 \| `R` 右转 \| `I` 倒转 |
| showValue | 是否在条码下方显示编码文本 | Boolean | `true` | `true` \| `false` |
| valueAlign | 编码文本对齐方式 | String | `center` | `left` \| `center` \| `right` |
| valueFontSize | 编码文本字体大小，最小 8px | String \| Number | `14` | - |
| valueSpacing | 编码文本与条码间距 | String \| Number | `8` | - |
| barColor | 条纹（前景）颜色，支持 `$` 主题色与 `var(--sn-*)` | String | `#111111` | - |
| backgroundColor | 背景颜色，支持 `$` 主题色与 `var(--sn-*)` | String | `transparent` | - |
| valueColor | 编码文本颜色，跟随 `barColor` | String | - | - |
| barShape | 条纹形状 | String | `flat` | `flat` \| `rounded` |
| barRadius | 条纹圆角（仅 `barShape=rounded` 生效） | String \| Number | `6` | - |
| moduleMinWidth | 最小模块宽（px），保证密集码型可辨认 | String \| Number | `1` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| codeStyle | 自定义条码画布样式 | SnStyleValue | - | - |
| valueStyle | 自定义编码文本样式 | SnStyleValue | - | - |
| customClass | 自定义根节点类名 | String | - | - |
| codeClass | 自定义条码画布类名 | String | - | - |
| valueClass | 自定义编码文本类名 | String | - | - |

> 类型字段：SnBarcodeFormat（见 https://sinleui.pages.dev/api/types/component#snbarcodeformat）


## 类型

> 类型字段：SnBarcodeBarElement（见 https://sinleui.pages.dev/api/types/component#snbarcodebarelement）

> 类型字段：SnBarcodeData（见 https://sinleui.pages.dev/api/types/component#snbarcodedata）


<DemoPhone name="sn-barcode" />

# Qrcode 二维码

> [查看 sn-qrcode 的 2.0 版本差异](/differences/components/sn-qrcode)

## 基础用法

纯 Canvas 自绘的二维码组件，不依赖任何原生二维码库，跨平台可用。

- 支持自定义信息点 / 定位点 / 校准点 / 时序点的形状、缩放、圆角与颜色
- 支持在二维码中央叠加 Logo，并可指定二维码版本与掩码图样
- 编码内容按 UTF-8 字节数计算，上限 300 字节，超出自动截断且不拆分多字节字符

::: info 首帧渲染
组件在画布取得实际尺寸后绘制首帧，首次进入页面即可正常显示，无需再次进入。
:::

```vue
<template>
	<sn-qrcode value="https://sinleui.pages.dev"></sn-qrcode>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| value | 二维码内容数据 | String | https://sinleui.pages.dev | - |
| size | 画板尺寸（宽高一致），最小 96px | String \| Number | `200` | - |
| padding | 留白边距（模块数） | Number | `2` | - |
| errorCorrectionLevel | 纠错等级 | `QrEcLevel` | `medium` | `low` \| `medium` \| `quartile` \| `high` |
| qrVersion | 二维码版本（1-40），0 表示自动选择 | Number | `0` | - |
| maskPattern | 掩码图样（0-7），-1 表示自动选择最优 | Number | `-1` | - |
| infoDotShape | 信息点形状 | `QrModuleShape` | `square` | `square` \| `rounded` \| `circle` \| `diamond` |
| locateDotShape | 定位点（点阵模式）形状 | `QrModuleShape` | `square` | `square` \| `rounded` \| `circle` \| `diamond` |
| locateDotPattern | 定位点绘制图样 | String | `dots` | `dots` \| `square` \| `rounded-square` \| `circle` |
| infoDotScale | 信息点缩放（0.1-1.3） | Number | `1` | - |
| locateDotScale | 定位点缩放（0.1-1.3） | Number | `1` | - |
| infoDotRadius | 信息点圆角系数（0-0.5） | Number | `0.22` | - |
| locateDotRadius | 定位点圆角系数（0-0.5） | Number | `0.28` | - |
| infoDotGap | 信息点间隙（0-0.6） | Number | `0` | - |
| infoDotColor | 信息点颜色 | String | `#111111` | - |
| locateDotColor | 定位点颜色，跟随 `infoDotColor` | String | - | - |
| alignDotColor | 校准点颜色，依次跟随 `locateDotColor`、`infoDotColor` | String | - | - |
| timingDotColor | 时序点颜色，跟随 `infoDotColor` | String | - | - |
| backgroundColor | 背景颜色 | String | `#ffffff` | - |
| showBackground | 是否绘制背景层 | Boolean | `true` | `true` \| `false` |
| logoSrc | 中央 Logo 图片路径，留空不显示 | String | - | - |
| logoSize | Logo 尺寸，自动限制在画板的 16px ~ 45% 之间 | String \| Number | `52` | - |
| logoPadding | Logo 内边距，自动限制不超过尺寸的 1/3 | String \| Number | `8` | - |
| logoRadius | Logo 圆角 | String \| Number | `14` | - |
| logoBackgroundColor | Logo 背景颜色 | String | `#ffffff` | - |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| backgroundStyle | 自定义背景层样式 | SnStyleValue | - | - |
| customClass | 自定义根节点类名 | String | - | - |
| backgroundClass | 自定义背景层类名 | String | - | - |

> 类型字段：QrEcLevel（见 https://sinleui.pages.dev/api/types/component#qreclevel）

> 类型字段：QrModuleShape（见 https://sinleui.pages.dev/api/types/component#qrmoduleshape）


<DemoPhone name="sn-qrcode" />

# Scan 扫码

> [查看 sn-scan 的 2.0 版本差异](/differences/components/sn-scan)

## 基础用法

基于 `sn-e-scan-provider` 扩展插件重构的一体化扫码组件，内置完整扫码界面，支持二维码 / 条码识别。

- 内置导航栏、扫描线动效、提示文字、手电筒、相册入口与识别点
- 支持双击还原缩放、双指捏合缩放、相册图片识别、只扫一次与连续扫描
- 浮层相对组件自身区域定位，可整页使用，也可嵌入页面局部区域（如半屏扫码）

::: info 平台支持
- 当前在 **App 全平台**（Android / iOS / HarmonyOS）端渲染与生效，其余平台渲染为空视图
- **平台差异**：iOS 端由底层 `sn-scan-provider`（zcscan）拉起整页扫码界面，手电筒、手势缩放、初始缩放、识别间隔不生效（相机扫码由其整页界面接管）；HarmonyOS 端由 Scan Kit 自定义界面扫码实现，能力与 Android 端一致
:::

```vue
<template>
	<sn-scan />
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| title | 扫码页面标题 | String | `扫一扫` | - |
| titleSize | 标题字体大小 | String \| Number | `$18` | - |
| titleColor | 标题颜色 | String | `#fff` | - |
| tip | 扫码提示文字；按 `scanType` 自动显示（二维码 / 条码 / 二维码或条码） | String | - | - |
| tipColor | 提示文字颜色，跟随 `titleColor` | String | - | - |
| tipSize | 提示文字字体大小 | String \| Number | `$14` | - |
| torchText | 手电筒提示文字 | String | `轻触点亮或关闭` | - |
| torchTextColor | 手电筒提示文字颜色 | String | `#fff` | - |
| torchTextSize | 手电筒提示文字字体大小 | String \| Number | `$12` | - |
| dotSize | 识别点大小 | String \| Number | `35px` | - |
| scanType | 扫码类型 | SnScanType | `all` | `qrcode` \| `barcode` \| `all` |
| lineAniTime | 扫描线动画时长（单位：ms） | String \| Number | `5000ms` | - |
| enableDing | 是否开启识别成功声音提示 | Boolean | `true` | `true` \| `false` |
| dingFileSrc | 自定义提示声音文件路径 | String | - | - |
| scanOnlyOnce | 是否只扫描一次（与 `continuous` 不可同为 `true`） | Boolean | `false` | `true` \| `false` |
| continuous | 是否连续扫描（与 `scanOnlyOnce` 不可同为 `true`） | Boolean | `false` | `true` \| `false` |
| continuousSleep | 连续扫描间隔时间（单位：ms） | Number | `2000` | - |
| showTorch | 是否显示手电筒按钮，iOS 端不生效 | Boolean | `true` | `true` \| `false` |
| showAlbum | 是否显示相册按钮 | Boolean | `true` | `true` \| `false` |
| showBackButton | 是否显示返回按钮 | Boolean | `true` | `true` \| `false` |
| showTitle | 是否显示标题（隐藏时导航栏两侧的占位按钮同步隐藏） | Boolean | `true` | `true` \| `false` |
| showTip | 是否显示提示文字 | Boolean | `true` | `true` \| `false` |
| showAni | 是否显示扫描线动效 | Boolean | `true` | `true` \| `false` |
| enableZoom | 是否允许手势缩放，iOS 端不生效 | Boolean | `true` | `true` \| `false` |
| initZoomScale | 初始缩放比例，iOS 端不生效 | Number | `0` | - |
| recognizeInterval | 识别间隔（单位：ms，取值 0 ~ 5000，为 `0` 时每帧识别），iOS 端不生效 | Number | `0` | - |
| cameraPermTip | 相机权限请求提示文案 | String | `相机权限默认文案` | - |
| albumPermTip | 相册权限请求提示文案 | String | `相册权限默认文案` | - |
| customDotStyle | 自定义识别点样式 | SnStyleValue | - | - |
| customDotIconStyle | 自定义识别点图标样式 | SnStyleValue | - | - |
| customTitleStyle | 自定义标题样式 | SnStyleValue | - | - |
| customTipStyle | 自定义提示文字样式 | SnStyleValue | - | - |
| customStyle | 自定义组件根节点样式 | SnStyleValue | - | - |
| customClass | 自定义组件根节点类名 | String | - | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| button-click | (name: string) => Void | 点击界面按钮时触发，`name` 可选值为 `return`（返回）、`album`（相册）、`torch`（手电筒） |
| scanned | (res: SnScanResult) => Void | 扫码成功时触发，结构见下方类型 |
| goin | (value: string) => Void | 选择识别点时触发，`value` 为识别的文本数据 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| rescan | - | - | 重新开始扫描 |
| setTorchStatus | (value: boolean) | - | 设置手电筒开关状态 |
| scanImageByURI | (src: string) | - | 通过图片 URI 识别图片中的码 |
| setZoomRatio | (zoomRatio: number) | - | 设置相机缩放比例 |
| getZoomRatio | - | number | 获取当前相机缩放比例 |

## 类型

> 类型字段：SnScanType（见 https://sinleui.pages.dev/api/types/component#snscantype）

> 类型字段：SnScanMode（见 https://sinleui.pages.dev/api/types/component#snscanmode）

> 类型字段：SnScanDataPosition（见 https://sinleui.pages.dev/api/types/component#snscandataposition）

> 类型字段：SnScanData（见 https://sinleui.pages.dev/api/types/component#snscandata）

> 类型字段：SnScanResult（见 https://sinleui.pages.dev/api/types/component#snscanresult）


`SnScanType`、`SnScanResult` 等类型由扩展插件 `sn-e-scan-provider` 导出；`SnScanParams` 为传参参数类型，由 SinleUI 框架导出（结构同上方属性表）。

<DemoPhone name="sn-scan" />

# Scankit 华为扫码

> [查看 sn-e-scankit 的 2.0 版本差异](/differences/components/sn-e-scankit)

## 基础用法

基于华为统一扫码服务（Scan Kit）封装的扩展插件，当前仅支持 Android 平台。

- 针对反光、暗光、污损、小码、大角度等复杂场景做了识别优化，扫码成功率较高
- 提供全屏扫码能力，支持相机扫码与导入图片扫码
- 附带码图生成组件，可将字符串转换为一维码 / 二维码

::: info 权限申请
- 相机与相册权限由插件内部申请：未授权时先弹出 `permTip` 说明弹窗，确认后请求系统权限，拒绝后跳转系统权限设置页。
:::

::: details 扫码 API 与码图生成组件
- **扫码 API `scan`**：调用 Scan Kit 的 Default View Mode，弹出华为标准全屏扫码界面（支持相机扫码与导入图片扫码），扫完通过回调返回码值；
- **码图生成组件 `sn-e-scankit-code`**：基于 `ScanUtil.buildBitmap` 将字符串转换为一维码 / 二维码（EAN-8、EAN-13、UPC-A、UPC-E、Codabar、Code 39、Code 93、Code 128、ITF14、QR、DataMatrix、PDF417、Aztec），支持自定义前后景色、容错级别与 QR 中部 Logo。
:::


## 兼容性

| Web | Android |
| --- | ------- |
| ×   | √       |

> Web 端调用 `scan` 会提示平台不支持；Web 端 `sn-e-scankit-code` 渲染为空节点，请使用 `sn-qrcode` / `sn-barcode` 代替。

**更多演示请下载 demo 查看**

---

## scan()  华为扫码

### **弹出华为标准全屏扫码界面并返回识别结果**

调用华为 Scan Kit Default View Mode 进行扫码，支持相机扫码与导入图片扫码。

### 属性

| 名称 | 类型 | 必备 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| configs | UTSJSONObject | 否 | `{}` | 扫码配置，字段见下表 |
| callback | (res: ScanResult) => Void | 是 | - | 扫码结果回调 |

`configs` 支持字段（蒸汽模式下类型化对象经桥接会降级，故此处传入 UTSJSONObject，插件内部解析字段）：

| 字段 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| scanTypes | string 数组 | `全部 14 种码` | 需要识别的码制式（`'QRCODE'` / `'EAN_13'` 等，见[下文类型](#scantype)），限定制式可提高扫码速度 |
| titleType | Number | `0` | 扫码界面标题：`0` = "扫描二维码/条码"，`1` = "扫描二维码" |
| permTip | String | `　 本应用正在请求您的相机、相册权限，仅用于条码、二维码识别，且通过系统途径读取数据，不会将任何数据上传至云端。如不提供此权限，则无法正常使用扫码功能。` | 权限申请弹窗提示语，仅在权限未授予时弹出 |

### 返回值

无（结果经 `callback` 返回 `ScanResult`：`format` 为码值类型（text / url / telephone 等），`data` 为码值字符串）。

### 示例

```typescript
import { snu } from '@/uni_modules/sinle-ui'
import { scan } from '@/uni_modules/sn-e-scankit'
import type { ScanResult } from '@/uni_modules/sn-e-scankit'

scan({}, (res: ScanResult) => {
	snu.showModal({
		title: '扫码结果',
		content: `格式：${res.format}\n内容：${res.data}`
	})
})

scan({ scanTypes: ['QRCODE'] }, (res: ScanResult) => {
	console.log(res.format, res.data)
})
```

---

# ScankitCode  华为码图

`sn-e-scankit-code` 将字符串转换为一维码 / 二维码码图。组件基于 `native-view` 绑定原生 ImageView，按自身尺寸实时生成高清码图，随尺寸变化自动重新生成。使用时需给组件**显式设置宽高**。

```vue
<template>
	<sn-e-scankit-code data="https://sinleui.pages.dev" type="QRCODE" style="width: 200px;height: 200px;"></sn-e-scankit-code>
</template>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| data | 需要编码的数据，内容变化时码图实时刷新 | String | `''` | - |
| type | 码图类型（`MULTI_FUNCTIONAL` 仅用于扫码识别，生成码图无效） | ScanType | `'QRCODE'` | 见[下文类型](#scantype) |
| margin | 码图边框宽度 | Number | `1` | - |
| bgColor | 码图背景色（具体色值，由原生 `Color.parseColor` 解析） | String | `'#ffffff'` | - |
| frontColor | 码图前景色 | String | `'#000000'` | - |
| qrErrorLevel | QR 码容错级别，仅对 QR 码生效 | String | `'M'` | `'L'` \| `'M'` \| `'Q'` \| `'H'` |
| qrLogo | QR 码中部 Logo 图片路径（支持项目内路径 / 绝对路径 / `file://`），仅 QR 码生效 | String | `''` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部样式类 | String | `''` | - |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| refresh | - | - | 手动触发重新生成码图 |

---

# ScanType

> 类型字段：ScanType（见 https://sinleui.pages.dev/api/types/component#scantype）

> 类型字段：ScanTypes（见 https://sinleui.pages.dev/api/types/component#scantypes）

> 类型字段：ScanTitleType（见 https://sinleui.pages.dev/api/types/component#scantitletype）

> 类型字段：ScanConfigs（见 https://sinleui.pages.dev/api/types/component#scanconfigs）

> 类型字段：ScanResultFormat（见 https://sinleui.pages.dev/api/types/component#scanresultformat）

> 类型字段：ScanResult（见 https://sinleui.pages.dev/api/types/component#scanresult）


## 环境要求

- HBuilderX 5.21+，uni-app x 蒸汽模式项目。
- 插件依赖 `com.huawei.hms:scanplus:2.12.0.301` 与华为 maven 仓 https://developer.huawei.com/repo/ ，依赖变更需重新打包自定义基座后生效。
- Scan Kit 不强制要求 `agconnect-services.json`；仅当应用在 AppGallery Connect 开通了相关服务并已放置该文件时，才需额外配置 AGC 插件。
- 请确保应用未关闭硬件加速（`hardwareAccelerated` 为 `true`），否则个别机型扫码界面可能黑屏。

<DemoPhone name="sn-e-scankit-code" />

# Blurview 高斯模糊

> [查看 sn-e-blurview 的 2.0 版本差异](/differences/components/sn-e-blurview)

## 基础用法

毛玻璃（高斯模糊）容器，对组件背后的内容进行模糊处理。

- 插槽内的内容悬浮在毛玻璃之上，本身不会被模糊
- 一般需设置为固定或绝对定位，并配合半透明背景色，模糊效果才明显
- 圆角、宽高、边距等样式可自由定制

```vue
<template>
	<sn-e-blurview :radius="50" custom-style="position: fixed;top: 0;right: 0;left: 0;height: 100px;background-color: rgba(255,255,255,0.2);">
		<sn-text text="内部内容不会被模糊处理，而是会悬浮在毛玻璃上"></sn-text>
	</sn-e-blurview>
</template>
```

**更多演示请下载 demo 查看**

## 实现机制

不同平台与引擎下自动采用不同实现（编译期确定，运行时零开销）：

| 场景 | 实现 |
| --- | --- |
| Web 等非 APP 端 | CSS `backdrop-filter: blur(radius)` |
| Android · 非蒸汽模式（VDOM） | `com.eightbitlab:blurview` + `RenderScriptBlur` 原生模糊 |
| Android · 蒸汽模式（uniVersion < 5.25） | 退化为普通 view（不引入原生代码，避免崩溃） |
| Android · 蒸汽模式（uniVersion >= 5.25） | CSS `backdrop-filter: blur(radius)` |

> 注意：Android 非蒸汽（VDOM）分支依赖 `com.eightbitlab:blurview`，使用该分支的工程需打包自定义基座。

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| radius | 模糊半径（px） | Number | `15` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部样式类 | String | `''` | - |

## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 放置毛玻璃上的内容，不会被模糊处理 |

<DemoPhone name="sn-e-blurview" />

# Gesture 手势

> [查看 sn-gesture 的 2.0 版本差异](/differences/components/sn-gesture)

## 基础用法

SinleUI 手势库组件，基于 AlloyFinger 实现，Web 与 Android 均可用。

- 内置点击、双击、长按、手指按下 / 移动 / 抬起 / 打断、双指缩放与滑动等手势识别
- 事件回调返回框架定义的具名类型，而非普通对象

```vue
<template>
	<sn-gesture @click="onClick" @scale="onScale" @fling="onFling">
		<view>内容</view>
	</sn-gesture>
</template>
```

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| customStyle | 自定义根节点样式 | SnStyleValue | - | - |
| customClass | 自定义根节点类名 | String | - | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| click | (event: `SnPointerEvent`) => Void | 单击事件 |
| dbclick | (event: `SnPointerEvent`) => Void | 双击事件（250ms 内两次点击且位移小于阈值） |
| longpress | (event: `SnTouchEvent`) => Void | 长按事件（按下 750ms 触发） |
| touchstart | (event: `SnTouchEvent`) => Void | 手指落下事件 |
| touchmove | (event: `SnTouchEvent`) => Void | 手指移动事件 |
| touchend | (event: `SnTouchEvent`) => Void | 手指抬起事件 |
| touchcancel | (event: `SnTouchEvent`) => Void | 触摸打断事件 |
| scale | (event: `SnScaleEvent`) => Void | 双指缩放事件 |
| fling | (event: `SnFlingEvent`) => Void | 滑动事件（位移超过阈值触发） |

> 类型字段：SnPointerEvent（见 https://sinleui.pages.dev/api/types/component#snpointerevent）

> 类型字段：SnTouchEvent（见 https://sinleui.pages.dev/api/types/component#sntouchevent）

> 类型字段：SnScaleEvent（见 https://sinleui.pages.dev/api/types/component#snscaleevent）

> 类型字段：SnFlingEvent（见 https://sinleui.pages.dev/api/types/component#snflingevent）


## 插槽

| 名称 | 说明 |
| --- | --- |
| default | 放置手势监听区域内的内容 |

## 类型

> 类型字段：SnTouch（见 https://sinleui.pages.dev/api/types/component#sntouch）


<DemoPhone name="sn-gesture" />

# Markdown 富文本

> [查看 sn-e-markdown 的 2.0 版本差异](/differences/components/sn-e-markdown)

## 基础用法

Markdown 渲染组件，Web 端与 Android 端使用各自的解析与渲染引擎。

- 支持标题、列表、表格、引用、代码块等基础 Markdown 语法
- 内置上标 / 下标 / 高亮、自定义容器、脚注、数学公式、任务列表与 Emoji 等扩展语法
- 两端语法保持一致

::: info 平台差异
- Web 端使用 UTS 移植的 markdown-it 解析引擎（含插件机制）渲染为 HTML；
- Android 端使用 Markwon 原生库渲染为原生 TextView（链接可点击）；
:::

::: details 支持的完整语法
- 支持基础 Markdown：标题（ATX / Setext）、段落、强调（粗体 / 斜体 / 粗斜体）、删除线、有序 / 无序 / 嵌套列表、链接（行内 / 引用式 / 自动链接）、图片、行内代码、代码块、表格（含对齐）、引用（含嵌套）、分割线、转义、硬换行。
- 内置扩展语法：上标 `x^2^`、下标 `H~2~O`、标记 `==高亮==`、自定义容器 `::: tip 标题`（支持嵌套）、对齐 `::: center`（left / center / right / justify）、脚注 `[^label]` 与 `^[行内脚注]`、数学公式 `$e^{i\pi}$` / `$$公式$$`（KaTeX 语法，轻量等宽渲染）、GFM 任务列表 `- [ ]` / `- [x]`、Emoji（直接 Unicode 与 `:smile:` 等常见短码自动替换）以及多语言代码高亮（js / ts / uts / uvue / ucss / html / xml / vue / svg / css / scss / less / json / yaml / python / java / kotlin / c / cpp / go / bash / php / powershell / rust / swift / lua / c# / r / perl / objective-c / sql）。
:::

```vue
<template>
	<sn-e-markdown :text="md"></sn-e-markdown>
</template>
<script lang="ts" setup>
const md = ref<string>('# Hello World\n\nThis is **markdown** content.')
</script>
```

**更多演示请下载 demo 查看**

## 自定义样式

通过 `baseFontSize` 控制基础字号（标题、代码等按比例缩放），`lineHeight` 控制行高倍数；`textColor` 与 `linkColor` 支持 `$primary`、`$text` 主题色简写及 `var(--sn-*)` 写法，留空时分别使用主题文字色与主题主色。

```vue
<template>
	<sn-e-markdown :text="md" :base-font-size="16" :line-height="1.8" text-color="$text" link-color="$primary"></sn-e-markdown>
</template>
```

## 链接点击事件

点击 Markdown 中的链接时触发 `linkclick` 事件（Android 端同时会用系统浏览器打开链接）。

```vue
<template>
	<sn-e-markdown :text="md" @linkclick="onLinkClick"></sn-e-markdown>
</template>
<script lang="ts" setup>
import type { SnMarkdownLinkEvent } from '@/uni_modules/sn-e-markdown/index.uts'
function onLinkClick(e: SnMarkdownLinkEvent): void {
	console.log(e.href)
}
</script>
```

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| text | Markdown 源文本 | String | `''` | - |
| baseFontSize | 基础字号（px），标题 / 代码等按比例缩放 | String \| Number | `15` | - |
| textColor | 正文颜色，支持 `$主题色` 简写 | String | `$text` | - |
| linkColor | 链接颜色，支持 `$主题色` 简写 | String | `$primary` | - |
| lineHeight | 行高倍数 | String \| Number | `1.6` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| linkclick | (value: SnMarkdownLinkEvent) => Void | 点击 Markdown 链接时触发，`value.href` 为链接地址 |

## 类型

- `SnMarkdownLinkEvent`：`{ href: string }`，链接点击事件回调参数。
- `SnMarkdownOptions`：渲染配置（`text`、`baseFontSize`、`textColor`、`linkColor`、`lineHeight`），一般由组件内部使用。

> 说明：Android 端自定义容器以 Blockquote 风格呈现、对齐使用原生对齐 Span；Web 端输出更完整的样式。数学公式为轻量渲染，如需 KaTeX / JLaTeXMath 深度渲染可自行接入。

<DemoPhone name="sn-e-markdown" />

# Scan Provider 扫码核心

> [查看 sn-e-scan-provider 的 2.0 版本差异](/differences/components/sn-e-scan-provider)

## 基础用法

SinleUI 扫码插件的核心模块，基于 CameraX + ML Kit 实现摄像头预览与扫码解析，仅支持 Android 平台。

- 支持二维码、条形码全格式识别，并可返回识别点坐标
- 支持图片扫码、手势缩放、双击对焦与手电筒
- 扫码成功后停止预览并释放相机资源，继续扫描需调用方法重新启动

::: danger 必须打包自定义基座
插件使用了第三方依赖，导入插件后必须打包自定义基座后运行。
:::

::: info 自定义界面
如需自带界面的扫码场景，可参考 `sn-scan` 对本组件进行再封装。
:::

```vue
<template>
	<sn-e-scan-provider ref="scanEle" scan-type="all" enable-zoom @scanned="onScanned" @error="onError"></sn-e-scan-provider>
</template>
<script lang="ts" setup>
import { SnScanResult } from '@/uni_modules/sn-e-scan-provider'

function onScanned(res: SnScanResult): void {
	console.log(res.data, res.scanMode)
}

function onError(err: SnScanProviderErrorImpl): void {
	console.log(err.errCode, err.errMsg)
}
</script>
```

## 兼容性

| Web | Android |
| --- | ------- |
| ×   | √       |

**更多演示请下载 demo 查看**

## 属性

| 参数 | 说明 | 类型 | 默认值 | 可选值 |
| --- | --- | --- | --- | --- |
| scanType | 扫码类型 | SnScanType | `'all'` | `'qrcode'` \| `'barcode'` \| `'all'` |
| enableDing | 是否开启扫码成功提示音 | Boolean | `true` | `true` \| `false` |
| dingFileSrc | 自定义提示音音频路径，使用内置提示音 | String | - | - |
| enableZoom | 是否允许手势缩放（捏合缩放、双击对焦并复位缩放） | Boolean | `true` | `true` \| `false` |
| initZoomScale | 初始缩放比例（线性缩放，0 ~ 1） | Number | `0` | - |
| autoStart | 组件初始化后是否自动启动相机并请求权限 | Boolean | `true` | `true` \| `false` |
| cameraPermTip | 相机权限请求说明文案 | String | `　本应用正在请求您的相机权限，仅用于条码、二维码识别，且不会将任何数据上传至云端。如不提供此权限，则无法正常使用扫码功能。` | - |
| customStyle | 根节点自定义样式 | SnStyleValue | `''` | - |
| customClass | 根节点外部样式类 | String | `''` | - |

## 事件

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| scanned | (result: SnScanResult) => Void | 扫码成功时触发，`result` 结构见[下文类型](#类型) |
| error | (error: SnScanProviderErrorImpl) => Void | 扫码出错时触发（权限被拒、相机初始化失败、图片识别失败等），错误码见[下文错误码](#错误码) |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| start | - | - | 启动相机开始扫码（自动请求相机权限）；auto-start 为 false 时需手动调用 |  
| stop | - | - | 停止扫码并释放相机资源 |  
| rescan | - | - | 扫码成功画面静止后，重新启动相机继续扫描 |  
| setTorchStatus | (status: boolean) | - | 设置手电筒开关状态 |  
| scanImageByURI | (uri: String) | - | 识别指定图片中的一 / 二维码，相对路径会自动转为绝对路径 |  
| setZoomRatio | (zoomRatio: number) | - | 设置缩放比例，自动约束在相机支持的最小 / 最大变焦范围内 |  
| getZoomRatio | - | Number | 获取当前缩放比例，未启动相机时返回 1 |  

## 类型

`@scanned` 事件返回 `SnScanResult` 对象，相关类型均由本插件导出：

> 类型字段：SnScanType（见 https://sinleui.pages.dev/api/types/component#snscantype）

> 类型字段：SnScanMode（见 https://sinleui.pages.dev/api/types/component#snscanmode）

> 类型字段：SnScanDataPosition（见 https://sinleui.pages.dev/api/types/component#snscandataposition）

> 类型字段：SnScanData（见 https://sinleui.pages.dev/api/types/component#snscandata）

> 类型字段：SnScanResult（见 https://sinleui.pages.dev/api/types/component#snscanresult）


```typescript
import { SnScanResult } from '@/uni_modules/sn-e-scan-provider'
```

## 错误码

`@error` 事件返回 `SnScanProviderErrorImpl`（`UniError` 子类），错误码定义：

| 错误码 | 说明 |
| --- | --- |
| 1602001 | 相机权限被拒绝 |
| 1602002 | 相机初始化失败 |
| 1602003 | 图片扫码失败 |
| 1602004 | 无效的图片 URI |
| 1602005 | 内部错误 |

# SnUI 工具库

`snu` 是 SinleUI 提供的工具库聚合门面（facade）。它把分布在多个分组静态类中的工具方法统一收敛到一个入口，使用户只需从一个地方导入即可调用全部工具方法，无需关心各方法所属的分组。

## 导入方式

```typescript
import { snu } from '@/uni_modules/sinle-ui'

// 调用示例
let id = snu.randomComId()
let rounded = snu.roundAmount('123.456', 2, 'round')
let isUrl = snu.isURL('https://example.com')
```

## 分组结构

`snu` 门面下的方法按业务/功能划分为以下分组（对应 `uni_modules/sinle-ui/core/utils/` 下的分组静态类）。组件内部通常直接导入分组类调用；用户侧则统一经 `snu` 门面调用。本页只介绍各分组的定位，具体方法清单见各分组文档。

| 分组静态类 | 模块文件 | 功能描述 | 文档 |
| --- | --- | --- | --- |
| `Random` | `random.ts` | 提供各类随机数据的生成能力，供界面开发与测试场景取用 | [Random](/libs/utils/random) |
| `Basic` | `basic.ts` | 提供节流、防抖与数值范围约束等基础控制能力，服务于高频交互与数值收窄场景 | [Basic](/libs/utils/basic) |
| `Easing` | `easing.ts` | 提供缓动函数集合，供动画与过渡的插值计算使用 | [Easing](/libs/utils/easing) |
| `ObjectUtils` | `object.ts` | 提供对象与数组的通用处理能力，覆盖数值格式化、拷贝、类型判断与元素 dataset 读写 | [ObjectUtils](/libs/utils/object) |
| `System` | `platform.ts` | 封装系统级能力（链接、提示、剪贴板、主题等），屏蔽各平台差异 | [System](/libs/utils/platform) |
| `Sort` | `sort.ts` | 提供常用排序算法的实现，供列表数据排序使用 | [Sort](/libs/utils/sort) |
| `Text` | `text.ts` | 提供文本处理能力，覆盖命名风格转换、金额处理、敏感信息脱敏与数字分段 | [Text](/libs/utils/text) |
| `Ui` | `ui.ts` | 提供界面开发辅助能力，覆盖单位换算、几何计算、节点查找与全局弹窗调用 | [Ui](/libs/utils/ui) |
| `Perm` | `perm.ts` | 负责系统权限的检查、申请、设置页跳转，以及权限提示气泡的内容配置、样式配置和申请监听 | [Perm](/libs/utils/permission) |
| `Verify` | `verify.ts` | 提供常见数据格式的合法性校验能力，覆盖日期、网络、号码、证件等类型 | [Verify](/libs/utils/verify) |

# ColorLib 颜色库

颜色库是 SinleUI 内置的一套轻量级颜色处理工具，基于 TinyColor 思路实现，提供颜色的解析、计算、格式转换、变换与配色方案生成等能力，并附带 APCA 对比度计算与基于主色的色板生成功能。

## 特性

- **统一入口**：ColorLib 静态类提供 5 个便捷静态方法；TinyColor 类可独立操作单个颜色。
- **强大解析**：支持 HEX、RGB、HSL、HSV/HSB、百分比 RGB、CSS 颜色名、数字等多种格式输入。
- **色彩变换**：提供变亮/变暗、混合、饱和度调整、色调旋转等变换方法。
- **配色方案**：内置类似色、互补色、单色、分裂互补、三色、四色等色轮配色算法。
- **可访问性**：内置 APCA 对比度计算，辅助选择可读性良好的前景/背景组合。

## 导入方式

颜色库从插件统一入口导出，可直接按需引入：

```typescript
import { ColorLib, TinyColor } from '@/uni_modules/sinle-ui'
```

- `ColorLib`：静态工具类，包含 `tinyColor`、`calcAPCA`、`generate`、`mean`、`random` 五个静态方法（详见 [methods](./methods)）。
- `TinyColor`：颜色实例类，封装对单个颜色的解析、计算与变换（详见 [tinycolor](./TinyColor)）。

## ColorLib 静态方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| tinyColor | color: any = '' / opts?: LColorOptions | TinyColor | 创建 TinyColor 实例，传入 TinyColor 时返回其克隆 |
| calcAPCA | frontColor: any / bgColor: any / round? : boolean = true | number | 计算两个颜色之间的 APCA 对比度 |
| generate | color: any / opts?: LGenerateOptions | string[] | 基于主色生成一组色板（HEX 数组） |
| mean | colors: any[] | TinyColor | 计算一组颜色的平均颜色 |
| random | - | TinyColor | 生成一个随机颜色 |

每个方法的详细说明见 [ColorLib 方法文档](./methods)。

## TinyColor 类

`TinyColor` 是一个封装单个颜色的实例类，所有计算后的方法返回新实例（不修改原对象）。主要能力包括：

- **明暗亮度**：`isDark` / `isLight` / `getBrightness` / `getLuminance` / `isMonochrome`。
- **格式输出**：`toRgb` / `toHex` / `toHsl` / `toHsv` / `toHsb` / `toRgbString` / `toHexString` / `toName` / `toNumber` 等。
- **颜色变换**：`lighten` / `darken` / `brighten` / `tint` / `shade` / `saturate` / `desaturate` / `greyscale` / `spin` / `mix` / `onBackground`。
- **色轮配色**：`analogous` / `complement` / `monochromatic` / `splitcomplement` / `triad` / `tetrad` / `polyad`。

完整方法清单见 [TinyColor 类文档](./TinyColor)。

## 类型定义

颜色库内置若干类型别名，详见 [类型定义](./types)：

- `LColorOptions`：`TinyColor` 构造选项（`format`、`gradientType`）。
- `LGenerateOptions`：`ColorLib.generate` 色板生成选项（`theme`、`backgroundColor`）。
- 相关颜色结构类型：`RGB` / `RGBA` / `HSLA` / `HSVA` / `HSBA` 等。

# TinyColor 颜色实例

`TinyColor` 是颜色库中对单个颜色的实例化封装，用于颜色的解析、计算与变换。构造后可读取 r/g/b/a 等通道，并调用方法获取指定格式或完成颜色运算。

```typescript
import { TinyColor } from '@/uni_modules/sinle-ui'

let c = new TinyColor('rgb(255, 0, 0)', {})
```

实例方法按功能可分为六类：**解析与比较**（`toString` / `equals`）、**明暗与亮度**（`isDark` / `isLight` / `getBrightness` / `getLuminance` / `isMonochrome`）、**Alpha 通道**（`getAlpha` / `setAlpha`）、**格式输出**（`toRgb` / `toHex` / `toHsl` / `toHsv` / `toHsb` / `toName` / `toNumber` 等系列）、**颜色变换**（明暗与饱和度调整、混合叠加）、**色轮配色**（类似色、互补色、三角/四角色等）。除颜色变换与色轮配色类方法返回新实例（不修改原对象）外，其余方法仅读取计算或返回自身。

## 属性

以下实例属性在构造时解析填充：

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| r | number | 红色通道（0-255） |
| g | number | 绿色通道（0-255） |
| b | number | 蓝色通道（0-255） |
| a | number | 透明度（0-1） |
| format | LColorFormats? | 输入颜色格式 |
| originalInput | LColorInput | 原始输入值 |
| isValid | boolean | 输入是否为有效颜色 |
| gradientType | string? | 渐变类型 |
| roundA | number | 舍入后的透明度值 |

## 方法

| 名称 | 参数 | 返回值 | 描述 |
| --- | --- | --- | --- |
| toString | format?: LColorFormats | string | 解析与比较。按指定格式输出字符串，缺省时用解析到的 format；未识别格式时回退为 `#hex` |
| equals | other?: LColorInput | boolean | 解析与比较。判断两个颜色是否相等 |
| isDark | - | boolean | 明暗与亮度。是否为深色（亮度 < 128） |
| isLight | - | boolean | 明暗与亮度。是否为浅色（!isDark） |
| getBrightness | - | number | 明暗与亮度。感知亮度（加权 RGB 亮度，0-255） |
| getLuminance | - | number | 明暗与亮度。相对亮度（WCAG 相对亮度 0-1） |
| isMonochrome | - | boolean | 明暗与亮度。是否单色（饱和度 0） |
| getAlpha | - | number | Alpha 通道。获取透明度（0-1） |
| setAlpha | alpha?: string \| number | TinyColor | Alpha 通道。设置透明度，返回自身，可链式调用 |
| toRgb | - | RGBA | 格式输出。输出 RGB 对象（r/g/b/a） |
| toRgbString | - | string | 格式输出。输出 `rgb()` / `rgba()` 字符串 |
| toPercentageRgb | - | RGBAString | 格式输出。输出百分比 RGB 对象 |
| toPercentageRgbString | - | string | 格式输出。输出百分比 `rgb()%` / `rgba()%` 字符串 |
| toHex | allow3Char = false | string | 格式输出。输出 HEX（可选 3 位缩写） |
| toHexString | allow3Char = false | string | 格式输出。输出带 `#` 的 HEX 字符串 |
| toHex8 | allow4Char = false | string | 格式输出。输出含透明度的 8 位 HEX |
| toHex8String | allow4Char = false | string | 格式输出。输出 `#` + 8 位 HEX |
| toHexShortString | allowShortChar = false | string | 格式输出。根据透明度输出 6 或 8 位 HEX |
| toHsl | - | HSLA | 格式输出。输出 HSL 对象 |
| toHslString | - | string | 格式输出。输出 `hsl()` / `hsla()` 字符串 |
| toHsv | - | HSVA | 格式输出。输出 HSV 对象 |
| toHsvString | - | string | 格式输出。输出 `hsv()` / `hsva()` 字符串 |
| toHsb | - | HSBA | 格式输出。输出 HSB 对象 |
| toHsbString | - | string | 格式输出。输出 `hsb()` / `hsba()` 字符串 |
| toName | - | string \| null | 格式输出。输出 CSS 颜色名（无对应名称时为 null） |
| toNumber | - | number | 格式输出。输出数字（0xRRGGBB） |
| lighten | amount = 10 | TinyColor | 颜色变换。提高明度（amount 为百分比数值） |
| darken | amount = 10 | TinyColor | 颜色变换。降低明度 |
| brighten | amount = 10 | TinyColor | 颜色变换。向白方向提亮 |
| tint | amount = 10 | TinyColor | 颜色变换。与白色混合 amount% |
| shade | amount = 10 | TinyColor | 颜色变换。与黑色混合 amount% |
| saturate | amount = 10 | TinyColor | 颜色变换。提高饱和度 |
| desaturate | amount = 10 | TinyColor | 颜色变换。降低饱和度 |
| greyscale | - | TinyColor | 颜色变换。转为灰度（desaturate 100） |
| spin | amount: number | TinyColor | 颜色变换。旋转色相（按角度，支持负值） |
| mix | color: LColorInput / amount = 50 | TinyColor | 颜色变换。与另一颜色按比例混合（amount 为混合比例） |
| onBackground | background: LColorInput | TinyColor | 颜色变换。将当前色叠加到背景色上（alpha 合成） |
| clone | - | TinyColor | 颜色变换。克隆当前实例 |
| analogous | results = 6 / slices = 30 | TinyColor[] | 色轮配色。类似色（相邻色相配色） |
| complement | - | TinyColor | 色轮配色。互补色（色相 +180°） |
| monochromatic | results = 6 | TinyColor[] | 色轮配色。单色系（同色相不同亮度） |
| splitcomplement | - | TinyColor[] | 色轮配色。分裂互补色（含当前色的 3 色） |
| triad | - | TinyColor[] | 色轮配色。三色配色 |
| tetrad | - | TinyColor[] | 色轮配色。四色配色 |
| polyad | n: number | TinyColor[] | 色轮配色。多色配色（按 n 均分色相环） |

> 备注：`toHexString()` 默认只取 r/g/b；含透明度时请使用 `toHex8String()` / `toHexShortString()` 获取带 alpha 的 HEX。

## 示例

```typescript
let c = new TinyColor('rgb(255, 0, 0)')
c.toString()              // 'rgb(255, 0, 0)'
c.toString('hex')         // '#ff0000'
c.equals('#ff0000')       // true

let dark = new TinyColor('#333333')
dark.isDark()             // true
dark.getBrightness()      // 约 51
dark.getLuminance()       // 约 0.04

let alpha = new TinyColor('#ff0000')
alpha.getAlpha()          // 1
alpha.setAlpha(0.5).toString()  // 返回自身，可链式调用

let rgba = new TinyColor('rgba(255, 0, 0, 0.5)')
rgba.toRgbString()        // 'rgba(255, 0, 0, 0.5)'
rgba.toHexString()        // 默认只取 r/g/b：'#ff0000'
rgba.toHslString()        // 'hsla(0, 100%, 50%, 0.5)'
rgba.toName()             // null（含透明度时无颜色名）

let base = new TinyColor('#1890ff')
base.lighten(20)          // 变亮
base.darken(10)           // 变暗
base.saturate(20)         // 更饱和
base.spin(120)            // 色相旋转 120°
base.mix('#0000ff', 50)   // 与蓝色各半混合
base.onBackground('#ffffff')  // 叠加到白色背景
base.clone()              // 克隆实例

let wheel = new TinyColor('#ff0000')
wheel.complement()        // 青色
wheel.analogous()         // 6 个类似色
wheel.triad()             // 3 个三色配色
wheel.polyad(5)           // 5 个均分布配色
wheel.splitcomplement()   // 3 个分裂互补色
wheel.monochromatic()     // 6 个单色系
```

# LColorOptions

### **TinyColor 构造选项**

`TinyColor` 构造函数与 `ColorLib.tinyColor()` 方法可接收的选项对象，用于指定颜色格式与渐变类型。

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| format | LColorFormats? | 输入颜色的格式，影响 `toString()` 的默认输出 |
| gradientType | string? | 渐变类型描述 |

`format` 可选值与含义：

| 值 | 含义 |
| --- | --- |
| rgb | RGB 格式（rgb()/rgba()） |  
| prgb | 百分比 RGB 格式 |  
| hex | HEX 格式 |  
| hex3 | 3/4/6/8 位 HEX 格式 |  
| hex4 | 3/4/6/8 位 HEX 格式 |  
| hex6 | 3/4/6/8 位 HEX 格式 |  
| hex8 | 3/4/6/8 位 HEX 格式 |  
| name | CSS 颜色名 |  
| hsl | HSL 格式 |  
| hsv | HSV 格式 |  
| hsb | HSB 格式（与 HSV 同义） |  

---

# LGenerateOptions

### **色板生成选项**

`ColorLib.generate()` 方法可接收的选项对象，用于控制色板主题与暗色背景。

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| theme | 'dark' \| 'default'? | 色板主题：`'default'` 返回常规色阶；`'dark'` 返回适配暗色背景的色阶 |
| backgroundColor | string? | 暗色主题下混合用的背景色（默认 `'#141414'`） |

> 说明：`backgroundColor` 仅在 `theme: 'dark'` 时参与计算，用于将色阶与所选背景色混合。

# 日期库 Date

SinleUI 内置的日期/时间处理库，基于 uni-app x 原生能力构建，提供日期解析、格式化、加减、区间计算、相对时间、国际化等能力。整个库分为三层：

- **`Dayuts` 类**：核心日期实例，封装所有日期运算与格式化方法。
- **`dayuts()` 工厂函数**：创建 `Dayuts` 实例的入口，支持多种日期入参。
- **`DateLib` 静态工具类**：提供 `toDate`/`fmtDate`/`now`/`today`/`weeks` 等面向业务场景的便捷方法。
- **`dayutsIntl`**：语言注册与切换的国际化管理器，内置 `en`、`zh-cn` 两套语言。

## 导出项

| 导出名 | 类型 | 说明 |
| --- | --- | --- |
| `Dayuts` | 类 | 日期实例类，含全部日期运算与格式化方法 |
| `dayuts` | 函数 | 工厂函数，创建 `Dayuts` 实例 |
| `isDayuts` | 函数 | 判断传入值是否为 `Dayuts` 实例 |
| `dayutsIntl` | 对象 | 国际化管理器（语言注册/切换） |
| `DateLib` | 类 | 静态日期工具类 |
| `DayutsConfig` | 类型 | 创建实例的配置对象类型 |
| `DayutsUnit` | 类型 | 时间单位联合类型 |
| `DayutsFormats` | 类型 | 本地化格式模板类型 |
| `DayutsRelativeTime` | 类型 | 相对时间文案类型 |
| `DayutsLocale` | 类型 | 语言包类型 |
| `DayutsObject` | 类型 | `toObject()` 返回的对象类型 |

## 导入方式

```typescript
import {
	Dayuts,
	dayuts,
	isDayuts,
	dayutsIntl,
	DateLib
} from '@/uni_modules/sinle-ui'
```

## 基本用法

### 创建实例

```typescript
const now = dayuts()                                   // 当前时间
const d1 = dayuts('2024-05-20 10:30:00')               // 解析日期字符串
const d2 = dayuts(1716191400000)                       // 时间戳（毫秒）
const d3 = dayuts([2024, 5, 20, 10, 30, 0])            // 数组 [年, 月, 日, 时, 分, 秒]
const d4 = dayuts('2024-05-20', 'YYYY-MM-DD', 'zh-cn') // 指定格式与语言
```

### 格式化

```typescript
const d = dayuts('2024-05-20 10:30:00', undefined, 'zh-cn')
d.format('YYYY-MM-DD HH:mm:ss')  // "2024-05-20 10:30:00"
d.format('YYYY年M月D日 dddd')     // "2024年5月20日 星期一"
```

### 加减与区间

```typescript
const d = dayuts('2024-05-20')
d.add(3, 'day')        // 2024-05-23
d.subtract(1, 'month') // 2024-04-20
d.startOf('week')      // 本周一（zh-cn 语言下周一为周起始）
d.endOf('month')       // 2024-05-31
```

### 相对时间

```typescript
const d = dayuts().subtract(3, 'day')
d.fromNow(true)   // "3 天"（zh-cn 语言，不带前后缀）
d.fromNow()       // "3 天前"
```

### 工具方法

```typescript
const lib = new DateLib()
lib.now()                          // "2024-05-20 10:30:00"
lib.today(-1)                      // 昨天 "2024-05-19"
lib.toDate('2024-05-20')           // Date 对象
lib.fmtDate('2024-05-20', 'yyyy年MM月dd日')  // "2024年05月20日"
```

## 语言

库默认语言为 `en`，内置 `zh-cn`。可通过 `dayutsIntl.locale` 切换全局默认语言，也可在创建实例时通过第三个参数指定语言。

```typescript
dayutsIntl.locale = 'zh-cn'
dayuts('2024-05-20').format('YYYY年MM月DD日')  // "2024年05月20日"
```

# 日期库 Dayuts

`Dayuts` 是 SinleUI 日期库的核心实例类，封装了日期解析、格式化、读取/设置、加减运算、区间计算、相对时间、类型转换与本地化等全部能力。推荐通过 `dayuts()` 工厂函数创建实例，而非直接 `new Dayuts()`。

```typescript
import { dayuts, Dayuts, isDayuts } from '@/uni_modules/sinle-ui'
```

实例方法按功能可分为七类：**创建与克隆**（`clone`）、**有效性判断**（`isValid` / `isSame` / `isAfter` / `isBefore` / `isSameOrBefore` / `isSameOrAfter` / `isBetween` / `isLeapYear` / `isToday` / `unix` / `utcOffset`）、**格式化**（`format`）、**读取与设置**（`get` / `set` / `year` / `month` / `day` / `date` / `hour` / `minute` / `second` / `millisecond` / `dayOfYear` / `daysInMonth`）、**加减与区间边界**（`add` / `subtract` / `startOf` / `endOf`）、**时间差与相对时间**（`diff` / `from` / `to` / `fromNow` / `toNow`）、**类型转换与本地化**（`toDate` / `toJSON` / `toISOString` / `toObject` / `toArray` / `valueOf` / `toString` / `locale`）。所有返回新实例的方法均不修改原实例。

---

# Dayuts

### 属性

| 名称 | 类型 | 只读 | 描述 |
| :--- | :--- | ---- | :--- |
| $L | String | 否 | 当前实例使用的语言名（如 `'en'`、`'zh-cn'`） |

### 方法

| 名称 | 参数 | 返回值 | 描述 |
| :--- | :--- | :--- | :--- |
| clone | - | Dayuts | 创建与克隆。返回当前实例的深拷贝，共享相同的时间戳与语言 |
| isValid | - | Boolean | 有效性判断。是否为有效日期，解析失败（如无法识别的字符串）时无效 |
| isSame | input: any, units: DayutsUnit = `'millisecond'` | Boolean | 有效性判断。按指定时间单位判断是否与目标时间处于同一区间，未传单位时按毫秒精确比较；目标值支持 `string` / `Number` / `Date` / `Dayuts` / 普通对象 |
| isAfter | input: any, units: DayutsUnit = `'millisecond'` | Boolean | 有效性判断。当前实例是否晚于目标时间 |
| isBefore | input: any, units: DayutsUnit = `'millisecond'` | Boolean | 有效性判断。当前实例是否早于目标时间 |
| isSameOrBefore | input: any, units: DayutsUnit = `'millisecond'` | Boolean | 有效性判断。是否相同于或早于目标时间（`isSame \|\| isBefore`） |
| isSameOrAfter | input: any, units: DayutsUnit = `'millisecond'` | Boolean | 有效性判断。是否相同于或晚于目标时间（`isSame \|\| isAfter`） |
| isBetween | input: any, input2: any, units: DayutsUnit = `'millisecond'`, interval: String = `'()'` | Boolean | 有效性判断。是否落在 `input` 与 `input2` 构成的区间内；`interval` 遵循数学区间记法：`'('` / `')'` 开区间（不含端点）、`'['` / `']'` 闭区间（含端点） |
| isLeapYear | - | Boolean | 有效性判断。所在年份是否为闰年 |
| isToday | - | Boolean | 有效性判断。日期部分（`YYYY-MM-DD`）是否与今天相同 |
| unix | - | Number | 有效性判断。Unix 秒级时间戳（`Math.floor(毫秒值 / 1000)`） |
| utcOffset | - | Number | 有效性判断。相对 UTC 的分钟偏移量；Web 端由 `getTimezoneOffset` 计算，APP-ANDROID / APP-IOS 端恒为 `0` |
| format | formatStr: string \| null = `'YYYY-MM-DDTHH:mm:ssZ'` | String | 格式化。按格式模板输出字符串，模板中英文字母识别为 token（详见 [format 模板说明](./format)），可使用中文作为字面量；无效日期返回 `'Invalid Date'` |
| get | units: DayutsUnit | Number | 读取与设置。按时间单位读取对应数值，如 `'year'` / `'month'` / `'day'` / `'date'` / `'hour'` / `'minute'` / `'second'` / `'millisecond'` / `'week'` |
| set | units: DayutsUnit, int: Number | Dayuts | 读取与设置。设置指定时间单位的值，返回新实例 |
| year / month / date / day / hour / minute / second / millisecond | 无参读取 / 传参写入 | Number / Dayuts | 读取与设置。同名读写方法：不传参数返回对应单位数值，传参设置并返回新实例。注意 `day()` 读的是星期几（0 起，0=周日），`date()` 读的是日（1 起），`month()` 月份 0 起 |
| dayOfYear | input: number \| null = null | Number / Dayuts | 读取与设置。不传参数返回当年第几天（1 起），传参设置并返回新实例 |
| daysInMonth | - | Number | 读取与设置。当月总天数 |
| add | number: Number, units: DayutsUnit | Dayuts | 加减与区间边界。增加指定数量的时间单位，返回新实例；如 `add(1, 'month')` 自动封顶到月末 |
| subtract | number: Number, units: DayutsUnit | Dayuts | 加减与区间边界。减少指定数量的时间单位，等价于 `add(number * -1, units)` |
| startOf | units: DayutsUnit, startOf: Boolean = `true` | Dayuts | 加减与区间边界。归一到指定单位的起始点（`startOf` 为 `false` 时取终点），支持 `year` / `month` / `week` / `day` / `hour` / `minute` / `second` 等，周以语言配置的 `weekStart` 为起始（zh-cn 为周一） |
| endOf | units: DayutsUnit | Dayuts | 加减与区间边界。归一到指定单位的结束点，等价于 `startOf(units, false)` |
| diff | input: any, units: DayutsUnit = `'millisecond'`, float: Boolean = `false` | Number | 时间差。计算与目标时间的差值；月份差按日历月、年份差按 12 个月计算，其余单位按毫秒差转换；`float` 为 `true` 时返回浮点值，否则取整 |
| from | input: any, withoutSuffix: Boolean = `false` | String | 相对时间。返回相对目标时间的人类可读描述，`withoutSuffix` 为 `true` 时省略「前 / 后」等前后缀，文案随语言变化（zh-cn 如 `"3 天前"`） |
| to | input: any, withoutSuffix: Boolean = `false` | String | 相对时间。从目标时间视角描述当前实例，语义与 `from` 相反 |
| fromNow | withoutSuffix: Boolean = `false` | String | 相对时间。描述当前实例相对此刻的时间（等价于 `from(dayuts(), withoutSuffix)`） |
| toNow | withoutSuffix: Boolean = `false` | String | 相对时间。描述从现在到当前实例的相对时间（等价于 `to(dayuts(), withoutSuffix)`） |
| toDate | - | Date | 类型转换。返回对应的原生 `Date` 对象（新实例，互不影响） |
| toObject | - | DayutsObject | 类型转换。返回含各时间单位字段的 `DayutsObject` 对象 |
| toArray | - | Number[] | 类型转换。返回 `[年, 月(0起), 日, 时, 分, 秒, 毫秒]` 数值数组 |
| valueOf | - | Number | 类型转换。毫秒时间戳（`getTime()`） |
| toISOString | - | String | 类型转换。ISO 8601 字符串；Web 端为标准 `toISOString()`，APP-ANDROID / APP-IOS 端返回 `Date.toString()` |
| toJSON | - | String \| null | 类型转换。有效日期返回 ISO 字符串（等价于 `toISOString()`），无效日期返回 `null` |
| toString | - | String | 类型转换。返回 `Date.toString()` 字符串表示 |
| locale | preset: string \| DayutsLocale, object: DayutsLocale \| null = null | Dayuts | 本地化。以当前实例为基础返回指定语言副本；`preset` 为已注册语言名或语言包对象，`object` 为配套语言包（传字符串语言名时可选） |

### 示例

```typescript
const d = dayuts('2024-05-20 15:30:00')
d.clone()                                   // 克隆实例
d.isValid()                                 // true
d.isSame('2024-05-20 20:00:00', 'day')      // true
d.isAfter('2024-05-19')                     // true
d.isBetween('2024-05-19', '2024-05-21', 'day', '[)')  // true
d.format('YYYY年M月D日 dddd')               // "2024年5月20日 星期一"
d.get('year')                               // 2024
d.month()                                   // 4（0 起，5 月为 4）
d.day()                                     // 1（周一）
d.date()                                    // 20
d.hour(22)                                  // 2024-05-20 22:30:00
d.add(1, 'month')                           // 2024-06-20
d.subtract(1, 'month')                      // 2024-04-20
d.startOf('day')                            // 2024-05-20 00:00:00
d.endOf('month')                            // 2024-05-31 23:59:59.999
dayuts('2024-05-23').diff('2024-05-20', 'day')  // 3
d.from('2024-05-23')                        // "3 天前"
d.subtract(3, 'day').fromNow()              // "3 天前"
d.toArray()                                 // [2024, 4, 20, 15, 30, 0, 0]
d.valueOf()                                 // 毫秒时间戳
dayuts('2024-05-20').locale('zh-cn').format('dddd')  // "星期一"
dayuts('2020-01-01').isLeapYear()           // true
dayuts().isToday()                          // true
dayuts('2024-05-20').unix()                 // 1716163200
dayuts('2024-02-01').daysInMonth()          // 29
dayuts('2024-01-01').dayOfYear()            // 1
```

---

# dayuts()

### **创建 Dayuts 实例**

工厂函数，根据传入的日期值创建一个新的 `Dayuts` 实例。支持字符串、时间戳、日期数组、原生 `Date`、普通对象、`Dayuts` 及空值（当前时间）等多种入参。若传入的是 `Dayuts` 实例，则返回其克隆。

原生端（APP-ANDROID / APP-IOS）`fact.format` 参数不生效；Web 端 `format` 参数参与字符串解析。

### 属性

| 名称 | 类型 | 必备 | 默认值 | 描述 |
| ---- | ---- | ---- | ------ | ---- |
| date | any \| null | 否 | `null` | 日期值。支持 `string`、`Date`、`Number`（毫秒时间戳）、日期数组、普通对象、`Dayuts`；为 `null` 时取当前时间 |
| format | string \| null | 否 | `null` | 解析格式（仅 Web 端生效） |
| locale | string \| null | 否 | `null` | 指定实例语言，未指定时使用全局默认语言 |

### 返回值

| 类型 | 必备 | 描述 |
| ---- | ---- | ---- |
| Dayuts | 是 | 返回一个 `Dayuts` 实例 |

### 示例

```typescript
dayuts()                              // 当前时间
dayuts('2024-05-20 10:30:00')         // 解析日期字符串
dayuts(1716191400000)                 // 毫秒时间戳
dayuts([2024, 5, 20, 10, 30, 0])      // [年, 月, 日, 时, 分, 秒]
dayuts('2024-05-20', 'YYYY-MM-DD')    // 指定格式（Web 端）
dayuts('2024-05-20', undefined, 'zh-cn')  // 指定语言
```

---

# isDayuts()

### **判断是否 Dayuts 实例**

判断传入值是否为 `Dayuts` 实例。

### 属性

| 名称 | 类型 | 必备 | 默认值 | 描述 |
| ---- | ---- | ---- | ------ | ---- |
| date | any \| null | 否 | `null` | 待判断的值 |

### 返回值

| 类型 | 必备 | 描述 |
| ---- | ---- | ---- |
| Boolean | 是 | 是 `Dayuts` 实例返回 `true`，否则 `false` |

### 示例

```typescript
isDayuts(dayuts())  // true
isDayuts('2024')   // false
```

# format 格式模板说明

`Dayuts.format(formatStr)` 通过格式模板将日期渲染为字符串。模板中的英文字母序列会被识别为 token，其余字符（中文、`-`、` `、`:`、`/`、`年` 等）作为原样字面量输出。

未传模板时使用默认模板 `'YYYY-MM-DDTHH:mm:ssZ'`。

同一种 token 的不同长度控制补零（`MM`/`MM`）与完整/缩写形式（`MMMM`/`MMM`）等细节，具体见下表。以下示例均以 `2024-05-20 15:03:07`（zh-cn 语言，周一）为例。

## Token 表

### 年 Y

| Token | 输出示例 | 说明 |
| --- | --- | --- |
| `YYYY` | `2024` | 4 位年份，不足补 0 |
| `YY` | `24` | 年份后两位 |

### 月 M

| Token | 输出示例 | 说明 |
| --- | --- | --- |
| `MMMM` | `五月` | 月份全名（zh-cn 为 `五月`，en 为 `May`） |
| `MMM` | `5月` | 月份缩写，取全名后 3 位 / 本地化缩写 |
| `MM` | `05` | 2 位月份，不足补 0 |
| `M` | `5` | 月份，不补 0 |

### 日 DD 与星期 d

| Token | 输出示例 | 说明 |
| --- | --- | --- |
| `DD` | `20` | 2 位日期，不足补 0 |
| `D` | `20` | 日期，不补 0 |
| `dddd` | `星期一` | 星期全名 |
| `ddd` | `周一` | 星期缩写 |
| `dd` | `一` | 星期最小形式 |
| `d` | `1` | 星期几数字（`getDay()`，0=周日，6=周六） |

### 时 24 小时制 H 与 12 小时制 h

| Token | 输出示例 | 说明 |
| --- | --- | --- |
| `HH` | `15` | 24 小时制，不足补 0 |
| `H` | `15` | 24 小时制，不补 0 |
| `hh` | `03` | 12 小时制（`${H % 12 == 0 ? 12 : H % 12}`），不足补 0 |
| `h` | `3` | 12 小时制，不补 0 |

### 分 m、秒 s、毫秒 SSS

| Token | 输出示例 | 说明 |
| --- | --- | --- |
| `mm` | `03` | 分钟，不足补 0 |
| `m` | `3` | 分钟，不补 0 |
| `ss` | `07` | 秒，不足补 0 |
| `s` | `7` | 秒，不补 0 |
| `SSS` | `007` | 毫秒，3 位补 0 |

### 上午/下午 A a

| Token | 输出示例 | 说明 |
| --- | --- | --- |
| `A` | `下午` | 上午/下午，随语言变化（en 为 `AM`/`PM`） |
| `a` | `下午` | 上午/下午小写形式（en 为 `am`/`pm`） |

zh-cn 语言的 `A`/`a` 按时间段输出本地称谓：凌晨（<6点）、早上（<9点）、上午（<11点）、中午（<13点）、下午（<18点）、晚上（其余）。

### 时区 Z

| Token | 输出示例 | 说明 |
| --- | --- | --- |
| `Z` | `+08:00` | UTC 偏移，格式 `±HH:mm`（如 `+08:00`、`-05:00`） |

### 转义 [ ]

在模板中使用 `[方括号]` 包裹的内容按字面量输出，不参与 token 解析。

| Token | 输出示例 | 说明 |
| --- | --- | --- |
| `[YYYY]` | `YYYY` | 方括号内按字面量输出 |

## 用法示例

```typescript
const d = dayuts('2024-05-20 15:03:07', undefined, 'zh-cn')

d.format('YYYY-MM-DD HH:mm:ss')   // "2024-05-20 15:03:07"
d.format('YYYY年M月D日 dddd')      // "2024年5月20日 星期一"
d.format('MM/DD [Year] YYYY')     // "05/20 Year 2024"
d.format('YYYY-MM-DDTHH:mm:ssZ')  // "2024-05-20T15:03:07+08:00"
d.format('hh:mm a')               // "03:07 下午"
```

## 与 DateLib.fmtDate 的区别

> 注意：`DateLib.fmtDate` 使用另一套**小写** token 体系（`y`/`M`/`d`/`H`/`m`/`s`），默认模板为 `'yyyy-MM-dd'`，并额外支持在模板中出现 `周`/`星期`/`礼拜` 时追加星期文案。两套 token 互不通用，详见 [DateLib 方法](./methods.md)。

# 日期库 dayutsIntl

`dayutsIntl` 是日期库的国际化管理器，负责语言包的注册与全局默认语言的切换。库内置 `en`（默认）与 `zh-cn` 两套语言包，除通过 `dayutsIntl` 管理外，也可在创建实例时用第三个参数临时指定语言，或用 `Dayuts.locale()` 为单个实例切换语言。

```typescript
import { dayutsIntl } from '@/uni_modules/sinle-ui'
```

---

# DayutsIntl

全局单例 `dayutsIntl` 为 `DayutsIntl` 类的实例。

### 属性

| 名称 | 类型 | 只读 | 描述 |
| :--- | :--- | ---- | :--- |
| locale | String | 否 | 全局默认语言名，读取当前语言，赋值即切换全局语言 |

> 说明：`locale` 是 `DayutsIntl` 的读/写属性。读取返回当前默认语言（初始为 `'en'`）；赋值时若该语言已注册则切换为默认语言，若未注册则打印警告并列出已注册语言、不生效。

### 方法

| 名称 | 参数 | 返回值 | 描述 |
| ---- | ---- | ------ | ---- |
| `use` | (locale: DayutsLocale) | DayutsIntl | 注册一个语言包，返回自身以支持链式调用 |
| `set` | (name: string, locale: DayutsLocale) | Void | 以指定名称注册一个语言包 |
| `has` | (name: string) | Boolean | 判断指定语言是否已注册 |

---

# dayutsIntl.use()

### **注册语言包**

注册一个 `DayutsLocale` 语言包，以该语言包的 `name` 字段作为注册名，返回 `dayutsIntl` 自身以便链式调用。注册后可通过 `locale` 赋值或 `locale()` 使用。

### 属性

| 名称 | 类型 | 必备 | 默认值 | 描述 |
| ---- | ---- | ---- | ------ | ---- |
| locale | DayutsLocale | 是 | - | 语言包对象，含 `name` 及各文案字段 |

### 返回值

| 类型 | 必备 | 描述 |
| ---- | ---- | ---- |
| DayutsIntl | 是 | 返回自身（支持链式调用） |

### 示例

```typescript
dayutsIntl.use({
	name: 'zh-tw',
	weekdays: ['星期日', ...],
	months: [...],
	ordinal: (n: number, period: string): string => `${n}日`
} as DayutsLocale)
```

---

# dayutsIntl.set()

### **按名称注册语言包**

以显式传入的名称注册一个语言包（`name` 参数不必与语言包内 `name` 字段一致）。

### 属性

| 名称 | 类型 | 必备 | 默认值 | 描述 |
| ---- | ---- | ---- | ------ | ---- |
| name | String | 是 | - | 注册使用的语言名 |
| locale | DayutsLocale | 是 | - | 语言包对象 |

### 返回值

无

### 示例

```typescript
dayutsIntl.set('zh-tw', zhTwLocale)
```

---

# dayutsIntl.has()

### **判断语言是否已注册**

判断指定语言名是否已在 `dayutsIntl` 中注册。

### 属性

| 名称 | 类型 | 必备 | 默认值 | 描述 |
| ---- | ---- | ---- | ------ | ---- |
| name | String | 是 | - | 语言名 |

### 返回值

| 类型 | 必备 | 描述 |
| ---- | ---- | ---- |
| Boolean | 是 | 已注册返回 `true`，否则 `false` |

### 示例

```typescript
dayutsIntl.has('en')      // true
dayutsIntl.has('zh-cn')   // true
dayutsIntl.has('ja')      // false
```

---

# dayutsIntl.locale（属性）

### **切换全局默认语言**

读取当前默认语言，或通过赋值切换默认语言。仅当目标语言已注册时切换生效。

### 示例

```typescript
dayutsIntl.locale            // "en"（初始）
dayutsIntl.locale = 'zh-cn'  // 切换全局默认语言为中文
dayuts('2024-05-20').format('YYYY年M月D日')  // "2024年5月20日"
```

## 内置语言包

| 语言名 | 说明 |
| --- | --- |
| `en` | 英文（默认语言） |
| `zh-cn` | 简体中文 |

# 日期库 类型定义

本篇列出日期库导出的全部类型定义。类型从 `@/uni_modules/sinle-ui` 导入：

```typescript
import type {
	DayutsConfig,
	DayutsUnit,
	DayutsFormats,
	DayutsRelativeTime,
	DayutsLocale,
	DayutsObject
} from '@/uni_modules/sinle-ui'
```

---

# DayutsConfig

创建 `Dayuts` 实例时使用的配置对象类型。

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| date | any \| null | 日期值，支持 `string`/`Date`/`Number`/数组/普通对象/`Dayuts`；`null` 表示当前时间 |
| format | string \| null | 解析格式（仅 Web 端生效） |
| locale | string \| null | 实例语言名 |

---

# DayutsUnit

时间单位联合类型，用于 `add`/`subtract`/`diff`/`startOf`/`endOf`/`get`/`set` 等方法。

值为以下字符串之一：

- `'year'` — 年
- `'month'` — 月
- `'day'` — 日
- `'week'` — 周
- `'date'` — 日期（同日）
- `'hour'` — 时
- `'minute'` — 分
- `'second'` — 秒
- `'millisecond'` — 毫秒
- `'quarter'` — 季度

> 在方法调用时也接受对应单字符别名（如 `'y'`·`'M'`·`'d'`·`'w'`·`'h'`·`'m'`·`'s'`·`'ms'`·`'Q'`），并自动忽略末尾的 `s`。

---

# DayutsFormats

本地化预设格式模板类型，供语言包 `formats` 字段使用。

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| LT | String | 时间格式，如 `HH:mm` |
| LTS | String | 带秒时间格式，如 `HH:mm:ss` |
| L | String | 短日期格式，如 `YYYY/MM/DD` |
| LL | String | 长日期格式，如 `YYYY年M月D日` |
| LLL | String | 长日期+时间格式，如 `YYYY年M月D日Ah点mm分` |
| LLLL | String | 完整日期+时间格式，如 `YYYY年M月D日ddddAh点mm分` |
| l | String | 更短日期格式，如 `YYYY/M/D` |
| ll | String | 精简长日期格式 |
| lll | String | 精简长日期+时间格式 |
| llll | String | 精简完整日期+时间格式 |

---

# DayutsRelativeTime

相对时间文案类型，供语言包 `relativeTime` 字段使用。除 `future`/`past` 外，各字段可使用 `%d` 占位符表示数字。

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| future | String | 未来时间前缀模板，如 `in %s` / `%s内` |
| past | String | 过去时间前缀模板，如 `%s ago` / `%s前` |
| s | String | 几秒（`a few seconds` / `几秒`） |
| m | String | 1 分钟 |
| mm | String | 多分钟，如 `%d minutes` / `%d 分钟` |
| h | String | 1 小时 |
| hh | String | 多小时 |
| d | String | 1 天 |
| dd | String | 多天 |
| M | String | 1 个月 |
| MM | String | 多个月 |
| y | String | 1 年 |
| yy | String | 多年 |

---

# DayutsLocale

语言包类型，传入 `dayutsIntl.use()` / `dayutsIntl.set()` 或 `Dayuts.locale()` 使用。

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| name | String | 语言名（注册名） |
| weekdays | String[] | 星期全名数组（7 项，周日起始） |
| weekdaysShort? | String[] | 星期缩写数组 |
| weekdaysMin? | String[] | 星期最小形式数组 |
| months | String[] | 月份全名数组（12 项） |
| monthsShort? | String[] | 月份缩写数组 |
| ordinal | (number: Number, period: String) => String | 序数格式化函数 |
| weekStart? | Number | 周起始日（0=周日），如 zh-cn 为 `1`（周一） |
| yearStart? | Number | 年初所在周（1-4 月），如 zh-cn 为 `4` |
| formats? | [DayutsFormats](#dayutsformats) | 预设格式模板 |
| relativeTime? | [DayutsRelativeTime](#dayutsrelativetime) | 相对时间文案 |
| meridiem? | (hour: Number, minute: Number, isLowercase: Boolean) => String | 上午/下午文案函数 |

---

# DayutsObject

`Dayuts.toObject()` 的返回类型。

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| years | Number | 年 |
| months | Number | 月（0 起） |
| date | Number | 日 |
| hours | Number | 时 |
| minutes | Number | 分 |
| seconds | Number | 秒 |
| milliseconds | Number | 毫秒 |

# Store 状态管理库

一个轻量简洁的全局响应式状态管理库。以键值对形式存储应用状态，支持**持久化存储**（重启后恢复）与**过期机制**（自动清理失效数据），并提供变更订阅能力。框架简单状态管理无需引入 pinia，直接使用本库即可。

## 导入方式

```typescript
import { store, frameStore, StoreLib } from '@/uni_modules/sinle-ui'
```

与 `ColorLib` / `DateLib` 等核心库一致，store 不再挂载在 `$snui` 上，请直接按命名导入使用。

### 内置实例

| 实例 | storeKey | 使用场景 |
| --- | --- | --- |
| `store` | `app_store` | 应用全局状态，推荐在业务中使用 |
| `frameStore` | `sinle_ui_store` | 框架内部状态（主题、风格、灰模等），不建议业务直接使用 |

固定 Tabbar 的高度登记也保存在 `frameStore`：每个 `sn-page` 使用独立的 `tabbarHeights:<实例 uid>` 键，存储纯数值与归属记录，不持久化；页面或登记组件卸载时清理。业务通过 [useTabbarHeights](/api/hooks/use-tabbar-heights) 获得当前页面的高度字典，不直接修改内部记录。不同页面的同名 Tabbar key 互不影响。

## 快速上手

```typescript
import { store } from '@/uni_modules/sinle-ui'

// 存储数据（不持久化，仅内存响应式）
store.set('count', 10)

// 存储数据（持久化，App 重启后自动恢复）
store.set('userName', 'Aaron', true)

// 读取数据；不存在时返回 null，也可指定默认值
let name = store.get('userName')
let score = store.get('score', 0)

// 判断是否存在
let exists = store.has('userName')

// 删除数据（持久化数据会同步从本地存储移除）
store.delete('userName')

// 订阅指定键的变化，set 时收到新值，delete 时收到 null
const unsubscribe = store.subscribe('count', (value: any | null, key: string) => {
	// value: 变更后的值；delete 时为 null
})
unsubscribe()
```

## 核心特性

### 响应式

数据存放在响应式存储中，页面模板或 `computed` 中读取该键时，后续对该键的修改会自动驱动界面更新，无需手动刷新：

```vue
<template>
	<text>{{ count }}</text>
</template>

<script setup lang="ts">
	import { store } from '@/uni_modules/sinle-ui'

	const count = computed(() => store.get('count', 0))
</script>
```

### 持久化（lasting）

`set(key, value, true, ...)` 将数据写入本地 Storage（基于 uni-app x 的 [storage API](https://doc.dcloud.net.cn/uni-app-x/api/storage.html)）。持久化键以 `snui_store_{storeKey}_` 为前缀，不同实例互不干扰。需要移除持久化数据时调用 `delete(key)`，会同步清理本地存储。

### 过期机制（expire）

`set(key, value, lasting, expire)` 的第 4 个参数为过期秒数（`0` 表示永不过期）。过期判断采用**惰性删除**策略：仅在访问（`get` / `has` / `keys`）或初始化时检查并清理过期键，不依赖定时器，兼顾性能：

```typescript
// 设置 10 秒后过期（不持久化）。过期后 get 返回 null
store.set('captcha', '123456', false, 10)

// 已存在过期的键被重新 set 且不传过期时间时，旧过期记录会被清除，变为永不过期
store.set('captcha', '234567')
```

### 变更订阅（subscribe）

对不渲染到界面的逻辑（如接口联动、界面外状态同步），可通过 `subscribe` 监听指定键的变更。订阅返回取消函数，组件销毁时请及时取消，避免内存泄漏。

## 创建自定义实例

应用内需要多个互不干扰的存储库时，可创建新的 `StoreLib` 实例：

```typescript
import { StoreLib } from '@/uni_modules/sinle-ui'

const myStore = new StoreLib('my_own_storelib')
```

- `storeKey` 仅允许字母、数字、下划线、中划线，且不能与已有实例重复，否则创建无效并输出警告日志。
- 每个实例的持久化键、过期列表、持久化列表均独立命名空间，互不影响。

## 注意事项

- **复杂对象类型**：Storage 序列化后读取到的复杂类型为普通对象，若原值为自定义 `type` 对象，回读后需自行转换（如 `JSON.parse<T>(JSON.stringify(obj))`，可参考 [类型数据的存取说明](https://doc.dcloud.net.cn/uni-app-x/api/storage.html#gettypedata)）。
- **空字符串持久化**：持久化读取依赖同步 storage API，空字符串按「未存储」处理；请勿将空字符串作为持久化值。
- **过期时间以秒为单位**；`expire` 与 `lasting` 相互独立，可组合使用。
## 更多文档

- [用法](/libs/store/usage)：典型使用场景与最佳实践
- [过期策略](/libs/store/expire)：过期机制详解
- [方法](/libs/store/methods)：StoreLib 全量方法说明

# Store 用法

本文档介绍 `StoreLib` 的典型使用场景与最佳实践。所有示例均以 `store`（`@/uni_modules/sinle-ui` 导出的应用级实例）演示。

## 基础存取（仅内存）

默认情况下数据只保存在内存中，适合临时状态：

```typescript
import { store } from '@/uni_modules/sinle-ui'

store.set('count', 10)
let count = store.get('count', 0) // 默认值兜底

store.delete('count')
```

## 持久化存储

需要 App 重启后依然保留的数据（用户偏好、业务配置等），将第三个参数 `lasting` 置为 `true`：

```typescript
store.set('userName', 'Aaron', true)
store.set('themePreference', 'dark', true)

// 删除时会同步清理本地存储
store.delete('userName')
```

持久化底层依赖 uni-app 的本地 [storage API](https://doc.dcloud.net.cn/uni-app-x/api/storage.html)，以 `snui_store_{storeKey}_` 前缀隔离各实例，不同 `StoreLib` 之间互不干扰。

## 过期数据

一次性、有时效的数据（验证码、临时票据等）可设置过期秒数，过期后自动视为不存在：

```typescript
// 10 秒后过期
store.set('captcha', '123456', false, 10)

// 过期后返回 null（或指定的默认值）
let v = store.get('captcha')
```

过期策略的详细说明见[过期策略](/libs/store/expire)。

## 跨页面共享状态

`store` 是全局单例，任意页面读写同一键即可实现跨页面状态共享，替代手动传参或 `storage` 中转：

```vue
<template>
	<text>{{ nick }}</text>
</template>

<script lang="ts" setup>
	import { computed } from 'vue'
	import { store } from '@/uni_modules/sinle-ui'

	// 与 store 内部响应式存储联动，其他页面修改后本页自动更新
	const nick = computed(() => store.get('nick', ''))
</script>
```

## 订阅数据变化

不依赖界面渲染的逻辑（如接口联动、缓存刷新、事件转发），可通过 `subscribe` 监听键的变更：

```typescript
const unsubscribe = store.subscribe('userInfo', (value: any | null, key: string) => {
	if (value != null) {
		// value 为写入的新值
		refreshUser(value as UserInfo)
	} else {
		// 键被 delete 时 value 为 null
		onUserLogout()
	}
})

// 不需要时务必取消订阅
unsubscribe()
```

### 组件中使用规范

订阅返回的取消函数应在组件卸载时调用，避免内存泄漏：

```vue
<script lang="ts" setup>
	import { onUnmounted } from 'vue'
	import { store } from '@/uni_modules/sinle-ui'

	let unsubscribe: () => void = () => {}

	onMounted(() => {
		unsubscribe = store.subscribe('count', (value: any | null, key: string) => {
			// ...
		})
	})

	onUnmounted(() => {
		unsubscribe()
	})
</script>
```

## 独立实例管理模块状态

不同业务模块之间需要彻底隔离时，可创建专属的 `StoreLib` 实例（含独立的持久化命名空间与过期列表）：

```typescript
import { StoreLib } from '@/uni_modules/sinle-ui'

const cartStore = new StoreLib('cart_store')
cartStore.set('items', [], true)
```

`storeKey` 仅允许 `[A-Za-z0-9_-]`，且不能与已有实例重名（重名或非法时创建无效并输出警告日志）。

## 与框架状态的配合

框架自身的状态（主题、风格、灰模等）已统一由 `frameStore` 管理并通过 `$snui` 暴露，业务代码直接读写 `$snui` 即可，无需操作存储细节。业务侧如需沿用框架的持久化能力，推荐使用 `store` 实例而不要直接调用 `uni.setStorageSync`。

# Store 过期策略

Store 库内置数据过期机制，用于管理验证码、临时票据、限时缓存等带时效性的数据。

## 设置过期

`set` 的第 4 个参数为过期秒数，`0`（默认）表示永不过期：

```typescript
// 10 秒后过期
store.set('captcha', '123456', false, 10)

// 30 分钟后过期的持久化数据
store.set('accessToken', token, true, 1800)

// 不传 expire，永不过期
store.set('userName', 'Aaron', true)
```

过期时间点 = 写入时刻 + `expire × 1000` 毫秒，写入后不可修改；如需调整，重新 `set` 写入新的过期时间即可。

## 惰性删除

过期判断采用**惰性删除**策略：库内不设任何定时器，仅在以下时机检查并清理过期键：

- 访问该键时（`get` / `has`）
- 遍历键名时（`keys` / `size`）
- 存储库初始化时（一次性清理全部过期项）

因此：

- 已过期的键在**被访问前仍存在于内存中**，但访问时会被清理并视为不存在；
- `get` 对过期键返回默认值（无默认值时为 `null`），`has` 返回 `false`；
- 该策略无定时器开销，适合数据量小、偶发访问的轻量状态库。

## 初始化清理

每次应用启动、`StoreLib` 实例被创建时，会先恢复持久化数据，再遍历过期列表，将已过期的键（含其持久化对应条目）一次性清除，避免过期数据在启动后被残留读取。

## 重新写入清除过期

对存在过期记录的键执行 `set` 且不带 `expire` 时，旧的过期记录会被自动清除，该键恢复为永不过期：

```typescript
store.set('captcha', '123456', false, 10)
store.set('captcha', '234567') // 清除过期记录，此后永不过期
```

只有显式传入 `expire > 0` 才重新建立过期记录。

## 持久化与过期组合

`lasting` 与 `expire` 相互独立，可自由组合：

| lasting | expire | 行为 |
| --- | --- | --- |
| `false` | 0 | 仅内存，不持久化、不过期 |
| `true` | 0 | 持久化，重启后恢复 |
| `false` | > 0 | 仅内存，存活期内可读 |
| `true` | > 0 | 持久化且有过期时间；重启后若仍在存活期内则恢复，否则清除 |

持久化 + 过期时，过期列表同样会随实例持久化保存，重启后过期判断依然生效。

## 注意事项

- 过期的清理只发生在库的访问路径上（惰性），不要依赖「立刻消失」：读取前即使已过期，也需通过 `get` / `has` / `keys` 等 API 才会触发清除。
- 过期时间不随系统时间校准；与所有本地存储一致，清理精度受应用运行生命周期影响。
- 请通过 Store 库 API 读写数据；绕过库直接操作底层 storage 键不会建立/清除过期记录。

# 更新日志

## 2.0.0（2026-09-19）

- 【重要】插件推荐运行版本为 HBuilder X Alpha 5.25 及以上（蒸汽模式在此版本之前存在比较严重的问题）
- 【重要】新增 框架全面重构为 uni-app x 蒸汽模式（vapor），VDOM 模式由于性能原因不再支持。
- 新增 多风格（Style）系统：内置 default / ink / chinese / new-year / morandi-green / orange 六套风格，支持自由修改增删内置风格，或者为应用添加自定义风格，并支持一键切换。
- 新增 五乘数体系（`fontsizeFactor` / `radiusFactor` / `marginFactor` / `paddingFactor` / `aniTimeFactor`）与三基础动画时长 `baseAniTimeShort` / `Normal` / `Long`，修改自动持久化并实时驱动页面
- 新增 `SnColorBase.shadow` 阴影色字段，随主题自动切换
- 新增 全局弹窗 `showLoading` / `hideLoading`；`showToast` 新增 `title` 兼容写法与 `passThrough` 点击穿透，`showModal` / `showActionsheet` 新增 `openAnimation` / `closeAnimation` 自定义开合动画
- 新增 `snu` 金额工具 `roundAmount` / `numToUpperAmount`（字符串级舍入，规避浮点陷阱）与全新 Resolve、Perm 方法分组
- 新增 `$snui.logging` 日志开关与 `log` / `info` / `debug` / `warn` / `error` 统一日志接口，组件内部不再直接 `console` 来报日志。
- 新增 Utils 工具库 `hideToast` 隐藏轻提示
- 新增 Utils 工具库 `clamp` 夹具函数，对所给值限制范围
- 新增 `$snui.colors` 颜色 `light`，与 `dark` 相对应。亮色模式下，`light` 即 `#fff`，`dark` 即 `#000`；暗黑模式下，两者颜色互换，`light` 即 `#000`，`dark` 即 `#fff`
- 新增 `syncStatusBarColor` / `createCalendarDayPaint` / `createCalendarDayContent` 全局函数与 `SN_DEFAULT_STYLE_ID` 常量
- 新增 `sn-agreement` 协议勾选：支持链接文本与勾选状态双向绑定
- 新增 `sn-album` 相册：网格宫格展示图片组并支持点击预览
- 新增 `sn-amount` 金额展示：字符串级精确舍入、千分位分隔与中文大写金额
- 新增 `sn-arc-progress` 环形进度：基于 canvas 绘制，支持自定义起止角度
- 新增 `sn-arc-slider` 圆弧滑块：圆弧形态滑动选择器，含 hue 颜色模式
- 新增 `sn-calendar` 日历选择器：底部弹出，支持单选 / 区间 / 多选三种模式
- 新增 `sn-calendar-view` 月历视图：可滑动的月历面板，供日历系列组件复用
- 新增 `sn-calendar-punch` 打卡日历：签到打卡记录日历
- 新增 `sn-calendar-week` 周日历：一次展示一周并支持滑动切周
- 新增 `sn-cascader` 级联选择：支持静态 data 与异步 loadData 双数据源
- 新增 `sn-cell` 列表项：通用单元格组件，框架内部列表布局统一复用
- 新增 `sn-clipper` 图片裁剪：可视裁剪框拖拽缩放，导出区域与预览一致
- 新增 `sn-code-input` 验证码输入：支持掩码、光标与粘贴识别
- 新增 `sn-color-picker` 颜色选择器：支持 alpha 透明度与预设色
- 新增 `sn-color-picker-view` 颜色视图：颜色选择的滑动面板视图
- 新增 `sn-drag` 拖拽排序：长按拖拽交换排序
- 新增 `sn-drag-item` 拖拽项：配合 `sn-drag` 使用的可拖拽子项
- 新增 `sn-drawer-list` 抽屉长列表：底部抽屉形态的长列表容器
- 新增 `sn-ellipsis` 文本省略：超长文本省略并支持展开 / 收起
- 新增 `sn-footer` 页脚：Logo + 导航链接 + 版权三段式布局
- 新增 `sn-fullscreen` 全屏：原位展开全屏容器
- 新增 `sn-form-field` 表单项容器：标签、内容、必填标与校验注册的基座
- 新增 `sn-input-field` 标签输入框：表单项 + 输入框组合，内置错误提示
- 新增 `sn-textarea-field` 标签文本域：表单项 + 文本域组合，含字数统计
- 新增 `sn-highlight-text` 高亮文本：关键词高亮显示
- 新增 `sn-keyboard` 安全键盘：数字 / 整数 / 密码 / 身份证 / 车牌五种类型
- 新增 `sn-mention` 提及输入：@ 提及选择输入框
- 新增 `sn-message` 消息条：全局消息队列，六方向弹出与分组计数
- 新增 `sn-notification` 通知：带标题内容与类型图标，支持进度条与拖动关闭
- 新增 `sn-pagination` 分页器：简洁 / 完整两种模式，支持快速跳转
- 新增 `sn-popover` 气泡卡片：锚点定位的轻量气泡弹层
- 新增 `sn-post-card` 帖子卡片：动态 / 帖子信息展示卡片
- 新增 `sn-region-picker` 省市区选择：内置中国区划数据，省 / 市 / 县模式
- 新增 `sn-scroll-view` 滚动容器：与长列表共用刷新 / 加载更多 / 回到顶部机制
- 新增 `sn-slide-captcha` 滑块验证：拖拽滑块完成验证
- 新增 `sn-slider-double` 双向滑块：区间范围选择
- 新增 `sn-sorter` 排序：字段排序选择器
- 新增 `sn-steps` 步骤条：横 / 竖排布，圆点 / 点状两种形态
- 新增 `sn-step` 步骤项：配合 `sn-steps` 的步骤节点
- 新增 `sn-table` 表格：支持固定表头与固定列
- 新增 `sn-tr` 表格行：配合 `sn-table` 的行节点
- 新增 `sn-td` 表格单元格：配合 `sn-table` 的单元格节点
- 新增 `sn-tree` 树：多模式选择与懒加载
- 新增 `sn-watermark` 水印：页面或局部水印覆盖，不影响其他组件，无副作用。
- 新增 `Demo` 手势库实例，结合可视化元素演示手势库应用
- 新增 `sn-e-toast` 插件：替换 `snu.showToast` 基于 `dialogPage ` 实现的不可透穿手势的 Toast 轻提示，原生弹层实现同官方 `uni.showToast` 基本一致的体验。同时相对于官方的 UI 新增了动画和丰富的样式支持。
- 优化 `$` 动态变量解析，在原有的仅支持基础上支持解析任意尺寸，自动计算符合当前框架尺寸乘数的结果。新增 `Resolve` 相关解析 API （详见文档）暴露给开发者使用以适配框架样式。
- 优化 动画统一由 UniElement DOM animate / transition + `--ani-time-*` 变量实现，支持 `$` 简写并随 `aniTimeFactor` 全局调速
- 优化 点击态统一为 `useHover` + `hover-style` 机制，替代旧 `hover-class`，配套 `hover-start-time` / `hover-stay-time` / `hover-trans-time`
- 优化 内部列表项 / 子项布局统一复用 `sn-cell`，子元素样式经 `itemStyle` / `itemHoverStyle` / `itemTextStyle` / `itemIconStyle` / `itemClass` / `itemBorder` 传递链透传
- 优化 长列表组件（`sn-list-view` / `sn-waterflow`）改为数据驱动 + 作用域插槽渲染，条目按数据项 type 分组复用回收，避免了直接传入 `list-item` / `flow-item` 组件被渲染为普通view 而引发的内存泄露问题
- 优化 重新设计了 `sn-input` 和 `sn-textarea` 的默认样式。如需原来的样式可以通过丰富的属性来实现。
- 优化 跟手组件触摸交互改为 DOM 直操作，APP 端拖动更顺滑
- 优化 `sn-select`、`sn-menu` 支持触底上移，即如果触发点位于页面底部，将自动将弹出层上移，避免触底。
- 优化 各组件尺寸类统一支持联合类型 `String | Number`
- 优化 `sn-datetime-picker` 的性能问题。
- 优化 禁用态统一使用主题禁用色，Web 端条件编译设置 `cursor: not-allowed`
- 优化 `sn-select` 滚动模式下打开将自动定位到当前选中项。
- 优化 sn-waterflow Web 端启用虚拟滚动，长列表滚动更流畅
- 优化 sn-picker-view 在 APP端使用拍平，极大提升了载入大量数据时的性能，卡顿大幅减轻
- 优化 sn-upload-media 及 sn-upload-media-unicloud 在非 Web 端平台改用系统提供的选择器，无需再向系统申请媒体权限
- 优化 sn-scan 从相册中选择图片时改用系统提供的选择器，无需再向系统申请媒体权限，且不会产生大量缓存文件而导致占用空间膨胀
- 优化 Demo 新特性速览跳转到工具库 Demo 时出现的卡顿问题
- 优化 `sn-e-markdown` 改 Android 原生渲染，消除 WebView 卡顿
- 优化 按钮 / 输入框 / 开关加载态指示器延迟 100ms 显示，避免闪烁
- 优化 `sn-rate` 只读态改为双层裁剪渲染，提升性能
- 【重要】更改【破坏性变更】重构原有 API 架构，具体见文档。
- 更改【破坏性变更】 全部组件样式扩展统一为 `customStyle` + `{语义}Style` / `Class` 透传体系，适配蒸汽模式样式隔离 2.0
- 更改 【破坏性变更】错误体系统一为 uni 错误规范：`SnError` 移除，统一改用 `UniError`（errSubject / errCode / errMsg / cause），多级模块 errSubject 以 `::` 分割；日志与错误码查询迁至 `sinle-logger` 插件
- 更改 【破坏性变更】`$snui.setColorSet` 更名 `setColorBase`，颜色键校验更严格
- 更改 组件 v-model 规范化：旧 `vModel` / `modelValue` 统一为 `v-model`（`sn-checkbox` / `sn-radio` / `sn-switch` / `sn-rate` / `sn-slider` / `sn-progress` 等）
- 更改 【破坏性变更】弹出层组件 `open` / `close` 事件改为六段动画生命周期事件 `beforeenter` / `enter` / `afterenter` / `beforeleave` / `leave` / `afterleave`，`clickMask` 统一更名 `clickoverlay`
- 更改 【破坏性变更】扩展插件收编为内置组件：`sn-e-gesture` → `sn-gesture`、`sn-e-qrcode` → `sn-qrcode`、`sn-e-barcode` → `sn-barcode`
- 更改 【破坏性变更】 `sn-waterfall` 更名重写为 `sn-waterflow`，并进行了重构。在APP 端封装官方内置组件 `waterflow`，在 `Web` 端采用自实现的虚拟列表。
- 更改 【破坏性变更】`sn-markdown` 迁移为独立插件 `sn-e-markdown`
- 更改 【破坏性变更】 `sn-longlist` 重构为 `sn-list-view`，`refresher-triggered` 改为 v-model 双向绑定
- 更改 【破坏性变更】 `sn-form-item` 拆分为 `sn-form-field` / `sn-input-field` / `sn-textarea-field`，`submited` 事件更名 `submit`
- 更改 【破坏性变更】`sn-menu` 菜单类组件的子组件从 `sn-menu-item` 改为 `sn-cell`  ，移除插槽并新增 `select` 事件。
- 更改 重新设计 `sn-signature` 组件布局，适配横屏模式。
- 更改 尺寸 / 时间类 props 统一放宽为 `String | Number` 并接入 `$` 乘数语法，颜色类 props 使用 `String` 支持 `$` 主题色
- 更改 【破坏性变更】字号板（`font.baseSize` + size 等级）、圆角等级板、动画等级板，改为乘数体系
- 更改 【破坏性变更】各组件 `customXxxStyle`（UTSJSONObject）更名去 `custom` 前缀为 `{语义}Style` 并成对新增 `{语义}Class`，`customStyle` 类型放宽为 `UTSJSONObject | String`
- 更改 【破坏性变更】`$snui.configs` 六大子配置体系，改为 `$snui` 扁平属性直接读写
- 修复 Android 端跟手组件拖动卡顿问题，触摸交互改 DOM 直写保证帧率
- 修复 `sn-notice` 组件在横屏或宽屏场景下文字完全隐藏后需要等待较长时间才会再次显示的问题
- 修复 `sn-notice` 组件过长文本会被截断的问题
- 修复 弹出层类组件未置于 `sn-page` 根节点时 `--sn-*` 颜色与 `--ani-time-*` 动画时长变量失效的问题
- 修复 非法 type / level 导致异常的问题，当前自动回退默认主题
- 修复 sn-timer / sn-countdown 等组件类型过度收窄导致的传参报错
- 修复 Date 日期库部分情况下报空指针异常的问题
- 修复 Utils 工具库 isDate 在高版本 uni-app x 上报空指针异常的问题
- 修复 sn-scan 图片扫描成功后预览图与识别点错位的问题
- 修复 sn-scan 手指在扫描线上无法触发缩放事件的问题（即缩放具有明显的卡顿感的问题）
- 更改 【破坏性变更】Store 状态管理库回归：旧版挂载于 `$snui.store` 的实现废弃重建，2.0 改为独立导出 `StoreLib` / `store` / `frameStore`，不再挂载 `$snui`（蒸汽模式也可直接使用 `pinia`）。
- 移除 【破坏性变更】`configs.font.mainFamily` 内置字体配置与 `configs.app.grayMode` 哀悼置灰模式
- 移除 【破坏性变更】`snu` 方法：`makePhoneCall`、`vibrate`、`addPx`、`share`、`chooseMedia`、`previewImage`、`showToasty`。上述方法官方基本已有实现或已不实用。
- 移除 废弃类型：`SnShareConfig`、`SnChooseMediaOptions`、`SnPreviewImageConfig`、`SnPreviewImageLongPressActions`、`SnToastyConfig`
- 移除  【破坏性变更】 栅格布局组件 `sn-col` / `sn-row` 与过渡组件 `sn-transition`。上述组件已不实用。
- 移除 【破坏性变更】SVG 组件 `sn-e-svg`。官方内置 `image` 已支持 `svg` 格式。
- 移除 `sn-list-item`、`sn-list-chat` 、 `sn-menu-item` 静态列表子组件，改由 `sn-cell` 实现
- 移除 【破坏性变更】 `sn-perm-listener` 组件标签形态，权限提示能力迁移为 `snu.setPermTips` / `registerPermListener` 等全局 API。

# API 新旧版本差异

## 总览

SinleUI 2.0 对框架 API 做了**结构性重构**：旧版以 `$snui` 挂载 `configs / utils / store / libs` 四大子对象；新版改为**扁平化属性 + 独立命名导出**。核心变化：

- `$snui.utils` → 独立导出 `snu`（工具库门面）
- `$snui.libs.color` / `$snui.libs.date` → 独立导出 `ColorLib/TinyColor` 与 `DateLib/Dayuts/dayuts/isDayuts/dayutsIntl`
- `$snui.store` → **独立导出 `store` / `frameStore` / `StoreLib`**（不再挂载 `$snui`，与 `snu` / `ColorLib` / `DateLib` 一致）
- `$snui.configs`（App/Page/Font/Radius/AniTime/zIndex 六大子配置）→ **移除**，改为 `$snui` 上的扁平属性直接读写（theme、autoTheme、currentStyleId、topbarHeight 等），并新增多风格切换与乘数体系
- 入口导出：旧版根 `index.uts` 几乎只导出 `$snui` 与少量类型；新版导出 18 个值（对象/hooks/工具/常量/函数）+ 大量类型

## $snui 差异明细

| 旧版 | 新版 | 说明 |
| :--- | :--- | :--- |
| `colors`（只读） | `colors`（只读） | 保留，语义不变 |
| `utils` | 移除 | 改为独立导出 `snu` |
| `store` | 独立导出 | Store 库重建为独立导出（`store` / `frameStore` / `StoreLib`），不再挂载 `$snui` |
| `libs` | 移除 | 颜色/日期库改为独立导出 |
| `configs` | 移除 | 见下方配置体系差异 |
| - | `theme`（可写） | 新增，切换亮/暗主题，自动关闭 autoTheme |
| - | `autoTheme`（可写） | 新增，跟随系统外观 |
| - | `currentStyleId`（可写） | 新增，多风格切换 |
| - | `topbarHeight` / `lightBgColor` / `darkBgColor`（可写） | 新增，旧 PageConfig 扁平化 |
| - | `topbarHeightResolved`（只读） | 新增，当前平台实际渲染的导航栏高度：Web 端为 `topbarHeight` + 8px，其他端等于 `topbarHeight` |
| - | `logging`（可写） | 新增，框架日志开关 |
| - | `marginFactor` / `paddingFactor` / `radiusFactor` / `fontsizeFactor` / `aniTimeFactor`（可写） | 新增，五尺寸/动画乘数体系 |
| - | `aniTimeShort` / `aniTimeNormal` / `aniTimeLong`（可写） | 新增，基础时长 × 加速乘数的计算结果；赋值按当前乘数反算写入基础时长并持久化 |
| - | `baseAniTimeShort` / `baseAniTimeNormal` / `baseAniTimeLong`（可写） | 新增，三个基础动画时长（150/250/400ms） |
| `setColorSet(theme, colorSet)` | `setColorBase(theme, colorBase)` | **更名**，功能一致（整体替换某主题颜色集） |
| - | `syncSystemTheme()` | 新增，autoTheme 开启时应用系统主题，一般不需要开发者调用，框架内部会自动管理 |

## 导出清单变化

旧版插件入口仅导出 `$snui`、及各种类型。

新版 `@/uni_modules/sinle-ui` 直接导出：

- **对象**：`$snui`、`snu`
- **核心库**：`ColorLib`、`TinyColor`、`DateLib`、`Dayuts`、`dayuts`、`isDayuts`、`dayutsIntl`
- **钩子**：`useTheme`、`useStyle`、`useFactors`、`useHover`
- **全局函数**：`syncStatusBarColor`、`createCalendarDayPaint`、`createCalendarDayContent`
- **常量**：`SN_DEFAULT_STYLE_ID`（`'default'`）
- **错误**：`UniError`（uni-app x 运行时内置，遵循 uni 错误规范；日志与错误码查询经 `sinle-logger`）
- **类型**：`SnColorBase`、`SnStyle`、`SnThemeMode`、`SnFunctionalColor`、`UseHoverOptions`、全部手势事件类型、全局弹窗配置类型等 90+ 个

钩子体系为 2.0 全新引入：`useTheme` / `useStyle` / `useFactors` / `useHover` 让组件与开发者以组合式方式响应式获取框架状态，详见 [钩子](/api/hooks/index)。

相关差异：- [配置体系差异](./config.md) - [类型差异](./types.md) - [错误体系差异](./error.md)

# 配置体系差异

## 总览

旧版将全局配置收敛在 `$snui.configs` 下的六个子配置对象中（`app / page / font / radius / aniTime / zIndex`），其中字号、圆角、动画采用"基本值 + 固定等级板"的静态结构。

新版**移除了 `Configs` 体系**，全部配置改为 `$snui` 直接属性，并且：

- 由"子配置对象 + 等级板"改为"**全局乘数 + 基础值**"的响应式体系
- 新增**多风格（Style）切换**维度（`currentStyleId`），配置项归属到 `SnStyle` 对象并整体持久化
- 配置修改自动持久化并实时生效：乘数与动画时长变量由 `sn-page` 差量写入，颜色变量随系统外观媒体查询切换

## 逐项差异

| 旧版配置 | 旧版内容 | 新版对应 | 说明 |
| :--- | :--- | :--- | :--- |
| `configs.app.theme` | 主题模式 | `$snui.theme` | 直接属性，写法变化 |
| `configs.app.autoTheme` | 跟随系统 | `$snui.autoTheme` | 直接属性，默认开启 |
| `configs.app.grayMode` | 哀悼置灰模式（1.1.4 新增） | `$snui.grayMode`（+ `$snui.grayLevel`） | 改为 `$snui` 直接属性；旧版写 `$snui.configs.app.grayMode`，新版写 `$snui.grayMode`；另新增 `$snui.grayLevel`（0-100）控制灰度程度，默认 `100` 全灰 |
| `configs.page.topbarHeight` | 导航栏高度，默认 `80px` | `$snui.topbarHeight` | 默认值改为 **`48px`**（Web 端导航栏实际渲染高度再 +8px） |
| `configs.page.lightBgColor` | 亮色页面背景，默认 `#f9f9f9` | `$snui.lightBgColor` | 默认值改为 `#EEF2FF` |
| `configs.page.darkBgColor` | 暗色页面背景，默认 `#262628` | `$snui.darkBgColor` | 默认值改为 `#0F172A` |
| `configs.font.baseSize` + `size(level)` | 基础字号 `14px` + 11 级字号板 | `$snui.fontsizeFactor` | **字号板移除**，改为全局字号乘数 |
| `configs.font.mainFamily` | 全局字体名（misans-normal） | - | **移除**（内置字体已不再随框架分发） |
| `configs.radius.baseSize` + 8 固定等级 | 基础圆角 `12px` + xxsmall~xxlarge/circle 等级板 | `$snui.radiusFactor` | **等级板移除**，改为全局圆角乘数 |
| `configs.aniTime.baseTime` + short/normal/long/xlong | 基础时长 `100ms` + 4 级 | `$snui.baseAniTimeShort/Normal/Long` + `aniTimeFactor` | 4 级改 3 级（short/normal/long），新增时长乘数 |
| `configs.zIndex` | navTabBar/badge/float/overlay/popup/toast 六项层级 | - | **移除**，层级改由组件自身控制 |

## 初始化方式差异

- **旧版**：在 `main.uts` 中通过 `$snui.configs.xxx = xxx` 逐项配置初始化，如：

```typescript
$snui.configs.page.topbarHeight = '88px'
$snui.configs.font.baseSize = '16px'
```

- **新版**：直接读写 `$snui` 属性，或切换整套风格：

```typescript
$snui.fontsizeFactor = 1.2
$snui.radiusFactor = 1
$snui.setColor('light', 'primary', '#4d82ff')
$snui.currentStyleId = 'ink'
```

## 行为变化要点

- 旧版 configs 修改**不持久化**（仅 app.theme/autoTheme 例外）；新版所有属性修改（theme、autoTheme、style、factors、baseAniTime 等）**一律自动写入 storage**，重启恢复。
- 旧版字号/圆角/动画为固定等级板（离散取值）；新版为连续乘数（任意数值），且 `$` 动态尺寸语法（`resolveSize`）可直接按组件 props 乘以对应乘数。
- 多风格切换为新版独有能力：`currentStyleId` 可从内置 6 套风格（default/ink/chinese/new-year/morandi-green/orange）或自定义风格间切换。

# 类型体系差异

## 导入方式变化

| 旧版 | 新版 |
| :--- | :--- |
| 框架本体类型从 `@/uni_modules/sinle-ui` 导入；**组件专属类型从组件自身 `interface.uts` 导入**（如 `SnActionsheetItem` 等） | 全部类型统一**从 `@/uni_modules/sinle-ui` 重导出**，不再要求从组件目录导入 |
| 旧版部分类型需手动 `import` 或 `as` 处理（如 `SnToastConfig` 从 `sn-native` 导入） | 新版编译器可自动推导，类型经插件入口统一导出 |

## SnColorBase 差异

字段整体保持不变，仅 **新增 `shadow`（阴影色）字段**：

> 旧版 `transparent / page / front / dark / disabled / disabledText / disabledDark / disabledDarkText / line / lineDark / lineText / title / text / textLight` + 五功能色 × 9 + `toast`
>
> 新版相同 + **`shadow`**

5 种功能色（`primary/info/success/error/warning`）× 亮/暗两套颜色集、每种含原色/`Light`/`Dark` + `Active`/`Text` 的结构完全保留，未变。

## 手势事件类型差异

| 类型 | 变化 |
| :--- | :--- |
| `SnPointerEvent` | 保留（type/x/y/event） |
| `SnTouch` | 保留（x/y/diffX/diffY/direction/id），旧版 **direction 字段为独立 `SnTouch` 属性、含义为"手指移动方向"**，保持不变 |
| `SnTouchEvent` | 保留 |
| `SnScaleEvent` | 保留 |
| `SnRotateEvent` | **不再单独导出**，旋转事件在新版中由组件事件内联携带角度（以组件文档为准） |
| `SnFlingEvent` | 保留 |

## 全局弹窗配置类型差异

| 类型 | 变化 |
| :--- | :--- |
| `SnShowToastConfig` | 保留并扩展：新增 `title` 兼容字段（仅有 `title` 时当 `text` 用）、`passThrough`（点击穿透）；余字段基本一致 |
| `SnShowModalConfig` | 保留并扩展：新增 `openAnimation` / `closeAnimation`（`SnModalAnimationFn` 自定义开合动画）；新增 `position` 支持 `left/right` |
| `SnShowActionsheetConfig` | `actions` 类型由旧 `SnActionsheetItem[]` 改为 **`SnDataItem[]`**；新增 `wrapStyle/wrapClass`、`panelStyle/panelClass`、`itemStyle/itemBorder/itemHoverStyle` 样式链字段；新增 `openAnimation/closeAnimation` |
| `SnShowLoadingConfig` | 新增（旧版仅有 `showLoading` 但未独立成文档类型） |
| `SnToastParams` | 新增（`sn-toast` 参数型轻提示配置） |
| `SnModalAnimationFn` | 新增（自定义动画函数类型） |

## 废弃类型清理

旧版已标注废弃的类型在新版中**全部移除**：

- `SnShareConfig`（1.1.5 废弃，`snu.share` 移除）
- `SnChooseMediaOptions`（1.1.7 废弃，`snu.chooseMedia` 移除）
- `SnPreviewImageLongPressActions`、`SnPreviewImageConfig`（1.1.7 废弃，`snu.previewImage` 移除）
- `SnToastyConfig`（旧 showToasty 参数类型）

## 权限类型

`SnRequestSystemPermissionOptions`、`SnRequestMediaPermissionOptions`、`SnRequestMediaPermissionOptionsType` 完全保留，现由 `sinle-api` 定义、`sinle-ui` 重导出。

## 新增类型（新版独有）

- 通用数据项 `SnDataItem`、`SnTime`（计时/倒计时事件返回）
- 权限提示：`SnPermTipConfig`、`SnPermTipsStyleConfig`
- 消息与通知：`SnMessageType/Level/Position/Params`、`SnNotificationType/Level/Position/Params`
- 核心类型：`SnStyle`（完整风格对象）、`SnColorBases`、`SnThemeMode`、`SnFunctionalColor`、`SnResolveType`、`UseHoverOptions`、`SN_DEFAULT_STYLE_ID`
- 组件专属类型大量扩充（`SnAvatarConfig`、`SnTreeData`、`SnCalendar*`、`SnRegion*`、`SnFormItemRule`、`SnFooterLink`、`SnBarcodeFormat`、`QrEncodeOptions`、`SnSignatureBrush` 等），均随组件文档说明

# 错误与日志体系差异

## 错误类型迁移至 UniError（破坏性变更）

旧版错误类型为 `SnError`（自定义类），2.0 起移除，统一遵循 [uni 错误规范](https://doc.dcloud.net.cn/uni-app-x/err-spec.html) 使用运行时内置 `UniError` 对象。

| 项目 | 旧版（1.x） | 新版（2.0 beta） |
| :--- | :--- | :--- |
| 错误类型 | `SnError`（自定义类） | `UniError`（uni-app x 运行时内置） |
| 构造 | `new SnError(moduleName, apiname, errCode, cause?)` | `new UniError(errSubject, errCode, errMsg)` |
| 属性 | `errSubject`（`moduleName-apiname` 拼接） / `errMsg` / `cause` | `errSubject` / `errCode` / `errMsg` / `cause` / `data` |
| errSubject 规则 | 单段拼接（如 `'ui-showToast'`） | 多级模块以 `::` 分割（如 `'sinle-ui::component::sn-avatar'`、`'sinle-ui::api::utils::showToast'`） |
| 源错误 | `cause` 为 `Error` | `cause` 为 `SourceError`（多个时为 `UniAggregateError`） |
| 导入来源 | `@/uni_modules/sinle-ui`（重导出） | 无需导入（运行时全局对象） |

> **兼容性影响**：所有依赖 `SnError` 类型、构造参数与 `errSubject` 拼接规则的代码全部失效，需迁移为 `UniError` 构造与 `::` 分割的 errSubject。

## 插件收敛至 sinle-logger（破坏性变更）

旧版错误与日志由 `sinle-error` 插件提供，2.0 起收敛为 `sinle-logger` 插件统一管理：

| 项目 | 旧版（1.x） | 新版（2.0 beta） |
| :--- | :--- | :--- |
| 日志开关 | `$snui.configs` 无专门日志开关 | `$snui.logging`（默认开启），`setLogging` / `getLogging` |
| 日志方法 | `log / info / debug / warn / error`（`[Snui]` 前缀） | 同左（经 `sinle-logger` 提供，`warn` / `error` 接收 `UniError` 并抛出） |
| 错误码查询 | `getErrMsg` 语义错误码表 | 保留（迁至 `sinle-logger`） |
| 使用约束 | 组件内可随意 | **禁止组件内直接 `console`**，一律经框架日志接口（`core/private/logger.ts`） |

## 错误码标准

错误码对照表（成功、撤销、权限、文件、平台、组件参数、Store key 重复、扫描等场景）仍保留，见[错误码对照表](/api/error/standard)。2.0 起各模块失败时通过 `UniError.errMsg` 直接提供错误信息，亦可经 `sinle-logger` 的 `getErrMsg(errCode)` 查询。

## 对应关系

- 旧 `snu.showToasty` → 新版 `snu.showSysToast`（调用系统原生 Toast）
- 全局弹窗（`showToast/showModal/showActionsheet/showLoading`）失败回调统一返回 `UniError`

# 组件差异索引

SinleUI 2.0 各组件相对 1.x 版本的差异说明索引。各组件的完整用法请见[组件文档](/components/index)。

## 已有组件差异

以下组件在 1.x 中已存在，2.0 对其进行了属性、事件、方法或行为上的调整。

- [sn-actionsheet](./sn-actionsheet)
- [sn-alert](./sn-alert)
- [sn-avatar](./sn-avatar)
- [sn-backtop](./sn-backtop)
- [sn-badge](./sn-badge)
- [sn-barcode](./sn-barcode)
- [sn-button](./sn-button)
- [sn-card](./sn-card)
- [sn-checkbox](./sn-checkbox)
- [sn-collapse](./sn-collapse)
- [sn-countdown](./sn-countdown)
- [sn-countto](./sn-countto)
- [sn-dateformat](./sn-dateformat)
- [sn-datetime-picker](./sn-datetime-picker)
- [sn-drawer](./sn-drawer)
- [sn-e-blurview](./sn-e-blurview)
- [sn-e-markdown](./sn-e-markdown)
- [sn-e-scan-provider](./sn-e-scan-provider)
- [sn-e-scankit](./sn-e-scankit)
- [sn-empty](./sn-empty)
- [sn-float-board](./sn-float-board)
- [sn-float-button](./sn-float-button)
- [sn-form](./sn-form)
- [sn-gap](./sn-gap)
- [sn-gesture](./sn-gesture)
- [sn-grid](./sn-grid)
- [sn-icon](./sn-icon)
- [sn-image](./sn-image)
- [sn-input](./sn-input)
- [sn-label-checkbox](./sn-label-checkbox)
- [sn-label-radio](./sn-label-radio)
- [sn-line](./sn-line)
- [sn-link](./sn-link)
- [sn-list-view](./sn-list-view)
- [sn-loading](./sn-loading)
- [sn-loading-page](./sn-loading-page)
- [sn-loadmore](./sn-loadmore)
- [sn-menu](./sn-menu)
- [sn-modal](./sn-modal)
- [sn-more](./sn-more)
- [sn-notice-bar](./sn-notice-bar)
- [sn-overlay](./sn-overlay)
- [sn-page](./sn-page)
- [sn-perm-listener](./sn-perm-listener)
- [sn-picker](./sn-picker)
- [sn-popup](./sn-popup)
- [sn-progress](./sn-progress)
- [sn-qrcode](./sn-qrcode)
- [sn-radio](./sn-radio)
- [sn-rate](./sn-rate)
- [sn-refresher](./sn-refresher)
- [sn-result](./sn-result)
- [sn-scan](./sn-scan)
- [sn-search](./sn-search)
- [sn-select](./sn-select)
- [sn-sidebar](./sn-sidebar)
- [sn-signature](./sn-signature)
- [sn-skeleton](./sn-skeleton)
- [sn-slider](./sn-slider)
- [sn-stepper](./sn-stepper)
- [sn-subsection](./sn-subsection)
- [sn-swipe-action](./sn-swipe-action)
- [sn-switch](./sn-switch)
- [sn-tabbar](./sn-tabbar)
- [sn-tabs](./sn-tabs)
- [sn-tag](./sn-tag)
- [sn-text](./sn-text)
- [sn-textarea](./sn-textarea)
- [sn-timer](./sn-timer)
- [sn-toast](./sn-toast)
- [sn-tooltip](./sn-tooltip)
- [sn-topbar](./sn-topbar)
- [sn-upload-media](./sn-upload-media)
- [sn-view](./sn-view)
- [sn-waterflow](./sn-waterflow)

## 已删除组件

以下组件在 1.x 中存在，2.0 已移除。点击可查看删除原因与替代方案。

- [sn-col](./sn-col)
- [sn-e-svg](./sn-e-svg)
- [sn-form-item](./sn-form-item)
- [sn-list](./sn-list)
- [sn-list-chat](./sn-list-chat)
- [sn-list-item](./sn-list-item)
- [sn-longlist](./sn-longlist)
- [sn-markdown](./sn-markdown)
- [sn-menu-item](./sn-menu-item)
- [sn-row](./sn-row)
- [sn-transition](./sn-transition)
- [sn-waterfall](./sn-waterfall)
- [sn-waterfall-item](./sn-waterfall-item)

## 说明

- 2.0 新增的组件不属于「差异」范畴，其用法请直接查阅[组件文档](/components/index)，本索引不再收录。
- 被更名或重构的组件（如 `sn-longlist` → `sn-list-view`、`sn-waterfall` → `sn-waterflow`、`sn-form-item` → `sn-form-field`）在新旧两侧名称下均有说明：新名称页面描述差异明细，旧名称页面描述删除原因与替代方案。

# 工具库（snu）差异

## 使用方式变化

| 项目 | 旧版 | 新版 |
| :--- | :--- | :--- |
| 获取入口 | `import { $snui } from '@/uni_modules/sinle-ui'` → `const snu = $snui.utils` | `import { snu } from '@/uni_modules/sinle-ui'`（独立命名导出） |
| 分组 | 分组不对外强调 | 10 个分组静态类 + `snu` 聚合门面，三层架构 |

## 方法级差异

### 保留不变（全部同签名）

| 分组 | 方法 |
| :--- | :--- |
| Random | `randint` / `randomNumber` / `uuid` |
| Basic | `throttle(fun, wait, id='default')` / `debounce` / `clamp(value, min, max=null)` |
| Easing | 全部 31 个缓动方法（sine~bounce 缓入/缓出/缓入缓出 + linear） |
| ObjectUtils | `formatNumber` / `deepClone` / `reArray` / `shuffle` / `isNumber` / `setDataset` / `getDataset` |
| System | `openLink` / `showSysToast` / `viewUrlByWebview` / `getOsTheme` / `setClipboardData` / `getClipboardData` |
| Sort | 8 个排序算法（冒泡/选择/插入/快排/归并/堆/希尔/桶） |
| Text | `isEmpty` / `len` / `kebabCaseToCamelCase` / `camelCaseToKebabCase` / `numToUpper` / `encryptName` / `encryptPhone` / `encryptIDCard` / `encryptEmail` / `encryptBankCard` / `separateNumber` |
| Ui | `getPx` / `addUnit` / `getInnerRadius` / `getDistance` / `getRotateAngle` / `findParent` / `findBrother` / `showToast` / `hideToast` / `showModal` / `showActionsheet` |
| Verify | 全部 17 个校验方法（isDate~isFloat） |

### 新增方法

| 分组 | 新增 | 说明 |
| :--- | :--- | :--- |
| Text | `roundAmount(value, decimals=2, mode='round')` | 字符串级金额舍入（round/ceil/floor/trunc），避免 toFixed 浮点陷阱 |
| Text | `numToUpperAmount(value)` | 金额中文大写转换（符合央行票据规范） |
| Ui | `showLoading(config)` / `hideLoading()` | 全局加载弹层（旧版无独立 loading 弹窗 API） |
| [useResolve](/api/hooks/use-resolve)（钩子） | `resolveSize` / `resolveSizeNum` / `resolveColor` | **2.0 起由 Utils 分组迁移为钩子**（`core/private/use-resolve.ts`），不再属于 `snu` 分组；`$` 动态尺寸/颜色解析（驱动组件尺寸乘数与主题色语法） |
| Perm | `setPermTips` / `setPermTipsStyle` / `registerPermListener` / `unregisterPermListener` / `hidePermTips` | **全新分组**，权限用途提示配置与监听（配套 `sn-perm-listener` 插件）；另有自 platform 分组迁入的 `checkSystemPermissionGranted` / `getSystemPermissionDenied` / `requestSystemPermission` / `gotoSystemPermissionActivity` / `requestMediaPermission` / `checkMediaPermission`（签名不变） |

### 移除方法

| 方法 | 旧版状态 | 新版 | 替代建议 |
| :--- | :--- | :--- | :--- |
| `makePhoneCall` | platform 分组 | 移除 | 使用 `uni.makePhoneCall` |
| `vibrate` | os 分组 | 移除 | 使用 `uni.vibrateLong` / `uni.vibrateShort` |
| `addPx` | ui 分组 | 移除 | 使用 `getPx` / `addUnit` |
| `share` | os 分组（1.1.5 已废弃） | 移除 | `uni.shareWithSystem` |
| `chooseMedia` | os 分组（1.1.7 已废弃） | 移除 | `uni.chooseMedia` |
| `previewImage` | 全局（1.1.7 已废弃） | 移除 | `uni.previewImage` |
| `showToasty` | 全局（更名产物） | 移除 | 新版统一为 `showSysToast`（系统 Toast）与 `showToast`（框架轻提示） |

### 更名/归属调整

- `randomComId`：旧版归入 Basic 分组，新版归入 **Random** 分组（对外用法不变）。
- `getOsTheme`：旧 platform 分组，新版归入 System 分组（`core/utils/platform.ts`）。
- 权限相关方法旧版分散在 `permission.md`/`platform.md`，新版统一归入 **Perm 分组**（`core/utils/perm.ts`）。

## 行为变化要点

- `resolveColor`/`resolveSize` 由新版组件内部大量依赖，配合 `sn-page` CSS 变量注入实现 `$primary` 等 $ 语法（旧版组件无此机制）。
- 全局弹窗配置类型签名有变（见 API 类型差异）：`showActionsheet` 的 `actions` 改为 `SnDataItem[]`，并新增样式链字段。

# 颜色库（Color）差异

## 使用方式变化

| 项目 | 旧版 | 新版 |
| :--- | :--- | :--- |
| 获取入口 | `$snui.libs.color`（文档以 `colorLib` 代称） | `import { ColorLib, TinyColor } from '@/uni_modules/sinle-ui'` |
| 实现基础 | 基于第三方 `lime-color` | **完全自研**（`core/color/`，无三方依赖） |

## ColorLib 静态方法差异

| 方法 | 旧版 | 新版 | 说明 |
| :--- | :--- | :--- | :--- |
| `tinyColor(input, opts)` | √ | √ | 创建 TinyColor 实例 |
| `calcAPCA(...)` | √ | √ | APCA 对比度计算 |
| `generate(...)` | √ | √ | 色板生成（默认 10 阶 + 暗色模式支持） |
| `mean(...)` | √ | √ | 颜色平均 |
| `random()` | √ | √ | 随机颜色 |

方法名与主要行为保留，实现全部重写。

## TinyColor 方法差异

### 保留（签名不变或以等价实现保留）

`getBrightness` / `getLuminance` / `isLight` / `isDark` / `getAlpha` / `setAlpha` / `toHsv` / `toHsl` / `toRgb` / `toHex` / `toName` / `toNumber` / `toString` / `clone` / `lighten` / `brighten` / `darken` / `tint` / `shade` / `desaturate` / `saturate` / `greyscale` / `spin` / `mix` / `analogous` / `monochromatic` / `splitcomplement` / `complement` / `equals` / `onBackground` / `triad` / `tetrad` / `polyad`

### 新增

| 方法 | 说明 |
| :--- | :--- |
| toRgbString | 各类格式字符串输出（旧版仅 toString 间接支持） |  
| toHslString | 各类格式字符串输出（旧版仅 toString 间接支持） |  
| toHsvString | 各类格式字符串输出（旧版仅 toString 间接支持） |  
| toHsbString | 各类格式字符串输出（旧版仅 toString 间接支持） |  
| toPercentageRgbString | 各类格式字符串输出（旧版仅 toString 间接支持） |  
| toHex8 | 含透明度 8 位 HEX 输出（旧版须自行处理 alpha） |  
| toHex8String | 含透明度 8 位 HEX 输出（旧版须自行处理 alpha） |  
| toHexShortString | 含透明度 8 位 HEX 输出（旧版须自行处理 alpha） |  
| toHsb | HSB 对象输出 |  
| toPercentageRgb | 百分比 RGB 对象输出 |  
| isMonochrome | 判断是否单色（饱和度 0） |  

### 移除

| 方法 | 旧版状态 | 说明 |
| :--- | :--- | :--- |
| `contrasting` | 旧版存在（返回对比色） | 新版移除（可用 `onBackground`、`getLuminance` 组合实现或自取色调） |

### 输出行为差异

- `toHexString()` 默认仅取 r/g/b，含透明度时需使用 `toHex8String()` / `toHexShortString()`（旧版行为未严格区分）。

## 类型差异

- 旧版颜色类型从 `libs/color/types` 引入；新版 `LColorOptions`、`LGenerateOptions` 等颜色类型经 `sinle-ui` 插件入口重导出，`TinyColor` 内部结构类型（`RGBA`/`HSLA`/`HSVA`/`RGBAString` 等）命名保持不变。

# 日期库（Date）差异

## 使用方式变化

| 项目 | 旧版 | 新版 |
| :--- | :--- | :--- |
| 获取入口 | `$snui.libs.date.dayuts(...)` | `import { dayuts, DateLib, Dayuts, isDayuts, dayutsIntl } from '@/uni_modules/sinle-ui'` |
| 实现基础 | 旧版封装 | **完全自研**（`core/date/`） |

> 旧版统一经 `dateLib.dayuts()` 创建 `Dayuts` 实例；新版提供同名 `dayuts()` 工厂函数直接导出，同时暴露 `DateLib` 静态工具入口。

## DateLib 静态方法（新增，旧版无此类入口）

| 方法 | 说明 |
| :--- | :--- |
| `dayuts(input, config)` | 创建 Dayuts 实例 |
| `newDate(...)` | 创建原生 Date |
| `toDate(...)` | 多种入参解析为 Date（支持字符串/数字/Date/Dayuts 等） |
| `fmtDate(...)` | 小写 token 格式化（`yyyy/MM/dd HH:mm` 风格，支持 周/星期/礼拜） |
| `now()` / `today()` | 当前时间 / 今日实例 |
| `weeks(...)` / `weekName(...)` | 周相关工具 |

## Dayuts 方法差异

### 保留不变

`isValid` / `isSame` / `isAfter` / `isBefore` / `isSameOrBefore` / `isSameOrAfter` / `isBetween` / `isLeapYear` / `isToday` / `unix` / `startOf` / `endOf` / `set` / `get` / `year` / `month` / `day` / `date` / `hour` / `minute` / `second` / `millisecond` / `add` / `subtract` / `format` / `utcOffset` / `diff` / `toDate` / `toJSON` / `toISOString` / `toObject` / `toArray` / `valueOf` / `daysInMonth` / `locale` / `clone` / `toString` / `dayOfYear` / `to` / `from` / `toNow` / `fromNow`

### 移除

| 方法 | 说明 |
| :--- | :--- |
| `fromToBase` | 从基础时间点计算相对时间的内部辅助方法，新版不再暴露 |

### format 模板差异

| 项目 | 旧版 | 新版 |
| :--- | :--- | :--- |
| token 体系 | 大写 token（`YYYY-MM-DD HH:mm:ss` 等，token 较少） | 大写 token 保留并扩展；**新增 `DateLib.fmtDate` 小写 token 体系**（`yyyy/MM/dd` 风格），支持 `周` / `星期` / `礼拜` 中文星期表述 |
| 相对时间 | 英文文案 | **支持本地化文案**（经语言包） |

## 国际化（新增）

- **`dayutsIntl`**：新版独有。提供 locale 注册（`use`）、切换（`set`）、检测（`has`），内置中文（zh-cn）与英文（en）语言包，驱动 `format` 中的周/月名称与相对时间文案。
- `Dayuts` 实例提供 `locale()` 设置实例语言。

## 类型差异

`DayutsConfig` / `DayutsUnit` / `DayutsFormats` / `DayutsRelativeTime` / `DayutsLocale` / `DayutsObject` 类型保留（字段以新版为准），经 `sinle-ui` 入口重导出。

## 平台行为说明

- `utcOffset`：原生端恒为 `0`（仅 Web 有实际含义）——与旧版同平台差异。
- `toISOString`：原生端走 `toString` 实现。

# Store 状态管理库差异

## 结论

旧版的 Store 状态管理库在 SinleUI 2.0 中以 **新实现回归**（此前曾随 2.0 重构整体移除）。核心 API（`get / set / delete`、持久化、过期机制）保持兼容，同时修复了旧版的安全风险与若干 bug，并拓展了订阅、批量查询等能力。框架自身的状态持久化（主题 / 风格 / 灰模等）也已重构为基于新 store 库管理。

## 使用方式变化

| 项目 | 旧版 | 新版 |
| :--- | :--- | :--- |
| 入口 | `$snui.store`（另有插件内 `store` / `frameStore` 导出） | `import { store, frameStore, StoreLib } from '@/uni_modules/sinle-ui'` 独立导出，不再挂载 `$snui`（与 `ColorLib` / `DateLib` 一致） |
| 内置实例 | `store`（`app_store`）、`frameStore`（`sinle_ui_store`） | 同旧版 |
| 存储键前缀 | `sinle_ui_store_lib_*`、`{storeKey}_key_*` | `snui_store_{storeKey}_*`（实例级隔离） |

## 方法差异

### 保留（签名兼容）

`get(key)` / `set(key, value, lasting?, expire?)` / `delete(key)` 行为与旧版一致。

| 方法 | 旧版 | 新版 | 说明 |
| :--- | :--- | :--- | :--- |
| `get(key)` | √ | √ | 新增可选 `defaultValue` 参数 |

### 新增

| 方法 | 说明 |
| :--- | :--- |
| `get(key, defaultValue)` | 支持指定键不存在/过期时返回的默认值 |
| `has(key)` | 判断键是否存在且未过期 |
| `keys()` | 返回全部未过期键名 |
| `clear()` | 清空全部数据（含持久化数据） |
| `size` | 当前未过期键数量 |
| `subscribe(key, listener)` | 订阅指定键变更，返回取消函数 |
| `unsubscribe(key, listener)` | 手动取消订阅 |

### 移除

无（旧版三个方法全部保留）。

## 修复的旧版问题

| 问题 | 旧版表现 | 新版处理 |
| :--- | :--- | :--- |
| 多实例持久化键冲突 | 过期/持久化列表使用全局固定键 `sinle_ui_store_lib_expireslist` / `...lastinglist`，多个 `StoreLib` 实例互相同步互踩，与「互不干扰」承诺相悖 | 各实例的元数据键按 `snui_store_{storeKey}_*` 独立命名空间 |
| 初始化异步竞态 | `init()` 内 `uni.getStorage` 异步回调链读取列表，存在初始化未完成即被访问、持续数据丢失的风险 | 改为同步 storage API，初始化确定性完成 |
| 异步写入乱序 | `uni.setStorage` 异步写入，连续写入同键可能乱序丢失 | 改为 `uni.setStorageSync` 同步写入，保证顺序 |
| 过期键重新 set 残留旧过期 | 已过期/设过过期时间的键以 `expire=0` 重新 set 后，旧过期记录未清除 | 重新 set 不带过期时间时自动清除旧过期记录 |
| 过期后取值为 `''` | `getStorageSync` 缺键返回 `''`，`data ?? ''` 兜底失效，缺键被当作空串值写入 | 缺键/空串按「未存储」处理，持久化列表自愈清理 |
| H5 风格恢复失效 | 读取风格用 `UTSJSONObject.hasKey`（H5 不可用）导致已保存风格无法恢复 | 改用直接属性访问，全平台一致恢复 |
| 空值判断污染 | `getStorageSync` 缺键返回 `''`，`loadBoolean` 会误把 `''` 当 `true` | store 缺键返回 `null`，避免隐式误判 |
| storeKey 无校验 | 任意非法字符可注入存储键 | storeKey 仅允许 `[A-Za-z0-9_-]`，非法/重复实例创建无效并告警 |

## 行为差异

- 持久化存储键命名空间变化，旧版（`sinle_ui_store_lib_*`）持久化数据不会被新版自动读取；框架配置类状态由 `state.ts` 提供**一次性旧键迁移**。
- 过期与持久化判断为惰性（访问时清理），与旧版一致，无定时器开销。
- 持久化复杂 `type` 对象回读仍为普通对象，需自行转换（与旧版一致，属 storage API 固有行为）。

## 迁移建议

- 原使用 `$snui.store.get / set / delete` 的代码改为 `import { store } from '@/uni_modules/sinle-ui'` 后直接调用（`$snui.store` 已移除），方法签名兼容，仅注意持久化键命名空间变化导致的旧数据不可见。
- 若使用过 `storeKeys` 之外的旧版持久化键名，需手动迁移一次数据。
- 框架内部（主题 / 风格 / 灰模、dialog 弹窗配置）已统一使用 `frameStore` 或基于 `StoreLib` 的实例管理，无需业务介入。