newui 使用文档
本文档随插件发行。各组件的详细教程（说明 / 平台兼容性 / 示例代码 / API 属性·事件·插槽表） 位于
uni_modules/new-ui/components/<组件名>/readme.md，配合 IDE 提示即查即用。 版本变更见changelog.md（最新版）与changeloglist.md（完整历史）。
🧭 三步上手
| 步骤 | 做什么 |
|---|---|
| ① 导入 | HBuilderX 中将插件导入 uni-app x 工程，组件经 easycom 自动注册，模板直接写 n-xxx 标签，无需导入语句 |
| ② 搭骨架 | 页面用 n-page 起步：深浅主题自动挂载、原生滚动、常驻底栏与安全区自动处理 |
| ③ 接主题 | App.uvue 样式区（声明 scss）引入插件 styles 目录全局入口一次，即得全局主题类与全部设计令牌 |
深色跟随系统需在 manifest.json 开启暗黑支持（darkmode），未开启时恒为浅色； 原生导航栏 / tabbar 联动配合 theme.json 使用。
📦 组件矩阵（106 个）
各组件的详细教程（说明 / 平台兼容性 / 示例代码 / API 属性·事件·插槽表）在对应目录的 readme.md：
uni_modules/new-ui/components/<组件名>/readme.md
🧱 基础
| 组件 | 能力 |
|---|---|
| n-text | 原生 text 单根：色调/字号/加粗/装饰线，多行省略，可选中复制 |
| n-tag | 状态小标签：五功能色 × 填充/镂空/浅色、胶囊/半圆标记、四档尺寸、可关闭 |
| n-badge | 徽标 / 角标双形态：99+ 截断、圆点模式、骑角定位微调 |
| n-avatar | 头像：插槽 / 图片 / 文字 / 图标四级回退，圆 / 方与三档尺寸或数值定制，功能色稳定配色，失败备份图与 error 事件 |
| n-avatar-group | 头像组：叠放（重叠比例可调，+N 折叠）+ 拼合群组头像（单框 1/2/4/9 宫格铺成员小图）双形态 |
| n-image | 图片：矩形 / 圆形画布，加载中 / 失败占位（插槽可替换），点击全屏预览（多图 + 起始下标），默认插槽叠放水印 / 角标，懒加载 / 淡入 / 长按菜单 |
| n-icon | 599 个矢量图标内置离线可用，支持自有图标字体与图片模式 |
| n-button | 原生 button 单根：6 类型 4 尺寸、镂空渐变加载节流，微信开放能力全集 |
📐 布局与页面
| 组件 | 能力 |
|---|---|
| n-page | 页面骨架：原生滚动 + 底栏钉底 + 安全区垫高 + 自带主题，推荐作为所有页面起点 |
| n-safe-area | 上下安全区真实高度占位，透明/实色/渐变背景与装饰插槽；与页面自动补偿明确互斥 |
| n-gap | 间距块：三档高度、定高/随内容、左右内边距、上下外间距、背景圆角、默认插槽和点击回执 |
| n-status-bar | 状态栏占位：系统高度、透明/实色/渐变背景、固定与等高占位、层级、装饰插槽及 init 高度回执 |
| n-no-network | 无网络提示：自动监听断网，全屏不透明覆盖层（图形/图片 + 提示语 + 重试按钮），恢复自动隐藏，App 端附去设置入口 |
| n-card | 卡片：头 / 体 / 底三段容器，缩略图 + 标题 + 右侧区头部，描边 / 投影 / 通栏形态，区域点击，媒体数据列表、字段映射、图片左右排列、来源与时间、逐项点击及按压反馈 |
| n-grid | 宫格：等分列、方形 / 自适应高度、间距与边框、圆角、末行对齐与占位 |
| n-grid-item | 宫格项：默认插槽、背景覆盖、按压反馈、业务标识与父子点击回传 |
| n-row | 栅格行：24 分栏，排列/对齐/换行/列间距，响应式断点 |
| n-col | 栅格列：占栏/空栏/视觉换位/断点（xs-sm-md-lg-xl 五档），与 n-row 配对 |
| n-cell | 列表行：图标/标题/说明/值/箭头一行排开，设置页利器 |
| n-list | 普通纵向列表：自然高度或限高滚动、固定行高窗口、8 个内容及状态插槽、原生刷新完整事件、触底分页衔接和稳定标识；复用单元格、加载提示与回顶按钮，stopRefresh/scrollToTop 类型明确直接调用 |
| n-divider | 分割线：横向嵌字三段式（左/中/右位置、圆点极简、插槽图标与文字并排、虚实/粗细两档），竖向纯线分栏，定宽短分隔居中 |
| n-data-tag | 数据驱动的标签选择：自动管理或绑定值的单选/多选，数量限制与互斥选项，保留业务对象、字段映射、禁用项和角标，支持主题与单行滚动组合 |
| n-section | 分组标题栏：标题 + 描述 + 右侧操作区（#right 推到行尾），左侧装饰竖条（实色/渐变、圆头/方头、上下缩进与标题间距），标题与描述间距可单项调整，独立字重与行高、竖条负值外移，点击回传标题 |
| n-steps | 步骤条：行向/竖向流程回显，已完成/当前/等待/错误四态，连线按段上色，图标/圆点/#icon 插槽三档节点，#title/#desc 作用域插槽富内容（item/index/status），逐项图标覆盖，行向平分居中、竖向步距连线连续 |
| n-timeline | 时间轴：独立轴宽/左列宽/线宽、逐项线色与断轴；圆点/图标/自定义节点、left/content/right 插槽，文字样式通道；进度更新保留业务内容，实时完整代码复制 |
| n-table | 表格：类型化嵌套列、固定表头与左右列、稳定排序、选择与禁用、图片/操作列、条件颜色；四插槽、主题令牌和完整示例代码 |
| n-pagination | 分页器：全宽等分格（上一页/页码区/下一页），multi 数字页码（首末页+居中窗口+省略号）/ simple 简约页码，受控双事件通道，方向按钮插槽>文案>箭头三档，边界与禁用降透明拦截 |
| n-collapse | 折叠面板：组容器，手风琴/多开双模式，name 数组受控 + change/open/close 事件，组外框描边 |
| n-collapse-item | 折叠面板成员：标题行/说明/值/箭头（单元格同构）+ 高度过渡折叠区（内容常驻状态保留），禁用只锁收展，独立使用为布尔受控单面板，#title 作用域 + #icon/#value 插槽 |
| n-skeleton | 骨架屏：头像/标题条/段落行声明式组合占位，末行自动收窄与数组逐行宽高，呼吸动画（页面隐藏/切后台停帧），loading 翻切真实内容 |
| n-search | 搜索框：灰底圆角搜索条（前置分类 / 搜索图标 / 一键清除 / 右侧动作按钮），键盘搜索键触发 search，禁用态静态入口跳页 |
| n-upload | 上传：图片九宫格 / 视频列表，数量·大小·扩展名校验，进度与失败重试，自动（返回体自动解析回填）/ 手动（afterRead + ref 回报）双模式，图片系统全屏预览 / 视频事件接管，删除可确认 |
| n-tabs | 标签页：下划线/滑块指示条随选中项移动，角标与禁用项，配合轮播联动 |
| n-swiper | 轮播图：list 驱动（字符串/对象数组键名映射）图片轮播，自动播放/衔接循环/手势滑切/卡片边距原生承接；卡片式露出（前后边距 + 非当前项缩放）；指示器点/线/数字/标题/页码五形态（点按跳页）+ #default/#indicator 插槽整体接管；current 受控（越界钳制）、change/click 事件与 loading 覆盖态 |
| n-segmented | 分段器：等分受控选择，卡片/描边/文字底线，业务字段映射、禁用、滑块、项插槽与图标布局 |
| n-dropdown | 下拉菜单：筛选标题栏多列单开互斥，列型覆盖菜单/排序/开关/视图切换/筛选入口，coexist 选中值共存，选项列表与自定义面板插槽、透明遮罩点击即关，ref 编程控制 |
| n-dropdown-item | 下拉菜单列：menu 面板选择 / sort 三态排序 / toggle 文字开关 / switch 图标二态 / filter 筛选入口；在 n-dropdown 内使用，值绑定选中态，面板限高滚动，选项数据整体判错 |
| n-popover | 气泡提示与操作菜单：12 方位 + auto，items / content 插槽、独立遮罩关闭开关、动态尺寸适配、v-model:visible 受控 |
| n-swipe-action | 滑动单元格组容器：成员注册与微信式单开互斥（auto-close），组级禁用与吸附距离，closeAll 一键收起，切页/切后台收起 |
| n-swipe-action-item | 滑动单元格：direction 配置左滑或右滑展开主菜单，reverseOptions/reverseButton 反向菜单一行双向滑动，方向锁手势（横向跟手阻断滚动/纵向让位）、阻尼拖动、滞回吸附，可选 v-model、click/change/error 事件（side 区分菜单）、自动尺寸监听，button/reverseButton 插槽两侧接管 |
| n-loadmore | 加载更多：status 三态（loadmore 点击翻页 / loading 指示器 / nomore 文字或圆点），三态均支持两侧线条，支持横竖排、轨道色与底部安全区，五种指示器与插槽旋转复用 n-loading，三态文案随语言包 |
| n-index-list | 索引列表：v-model 控制索引，v-model:list 回写勾选；默认项支持主副文字/图片/复选框，标准行及逐组标题样式，item/section 插槽定制；header/footer 前后内容及独立固定，select/change/init/click 与触底事件，自动布局检测、scrollTo/refresh 方法 |
| n-sticky | 粘性布局：Web / 微信原生吸附、App 事件定位，scrollViewId 指定局部容器；bounded 分组让位，change/error 与 default/content 插槽；默认调用无需滚动监听与测量 |
| n-scroll-list | 横向滚动列表：scroll 开关与指示器独立，尺寸支持 px/rpx/% 和主题令牌；隐藏原生滚动条，底部滑动指示器随滚动位移，left/right 到边事件；内容放插槽自行排布，内容不足自动隐藏指示器 |
| n-vtabs | 垂直选项卡：左侧分类轨道 + 右侧滚动内容区，双向滚动联动，图标/角标/禁用项 |
| n-vtabs-content | 垂直选项卡内容分区：在 n-vtabs 内使用，自动注册分区及高度，支持异步内容重测 |
| n-fab | 悬浮动作按钮：四角停驻、四向展开菜单、auto/free/none 拖拽，v-model:active 受控，trigger/item/default 插槽与微信能力回调 |
| n-back-top | 返回顶部：页面滚动自动显隐与受控双模式，阈值/时长/形状/图标文字可配，n-page 底栏自动避让，default 插槽整钮替换 |
| n-waterfall | 瀑布流：多列不等高排版，#item 插槽逐条渲染，新条目按实时列高放最短列（图片后加载自动纠正），v-model 数据源与 append/remove/update/clear 命令式方法双通道，头插重排回源序，readyKey 就绪门协调 end/init/error 事件，间距四面（gutter/leftGap/rightGap/itemGap） |
| n-navbar | 自定义导航栏：状态栏占位 + 返回箭头 + 标题 + 左右操作区，微信端避让胶囊，init 上报布局，fixed + placeholder 防塌陷，左右图标样式通道对称透传（几何守卫），left/center/right/default 四插槽 |
| n-tabbar | 底部标签栏：list 驱动（对象数组或字符串数组简写）+ 受控切换（change 不回写即拦截），fixed + placeholder + 安全区，图标角标 / 红点 / 中间凸起按钮 / url 跳页，悬浮胶囊与标签模式，#item / #middle 插槽，init 高度回报 + getRect() 随时查询栏体几何 |
💬 弹层与反馈
| 组件 | 能力 |
|---|---|
| n-popup | 通用弹层：五方向弹出、半屏档位面板、拖拽关闭、三插槽自由组装 |
| n-modal | 对话框：标题/正文/确认取消，过渡与遮罩关闭内置 |
| n-action-sheet | 动作面板：普通列表 / 单行与多行分享，card 圆角卡片 / line 满宽细线双外观，逐项禁用与加载、字段映射、六插槽、受控关闭与微信开放能力 |
| n-toast | 轻提示：命令式 open/close，深色块（图标/加载圈 + 文案，三档定位）与顶部通知条双形态，八预设类型，单实例替换式 |
| n-loading | 加载指示器：圆环（可带轨道）/半圆弧/花瓣/三点/三竖条五形态，JS 帧循环驱动行内样式（无 CSS 动画），text/插槽说明文字（图文横竖排），loading 关闭即停不空转 |
| n-loading-page | 整屏加载页：不透明遮罩盖住页面，加载圈/品牌图 + 文案居中，show 受控 |
| n-progress | 进度条：轨道 + 进度条铺满容器，percent 驱动动画（每 1% 毫秒可调、0 关），百分比文字随条滚动或条内悬浮（双层叠字对比色自动分割），label / text 插槽，实色 / 渐变进度色，pill / square 两档，activeend 到位事件 |
| n-count-to | 数值插值与逐位滚轮：起止值、缓动、精度与格式字符、暂停续播、目标续接、页面隐藏冻结、点击与业务参数、整体插槽 |
| n-countdown | 倒计时 / 累计计时：总时长与分单位输入、截止日期、上限、格式进位与前导零隐藏、真实毫秒、开始 / 暂停 / 继续 / 重置 / 结束，显隐补算、本次运行 / 本地恢复，整体 / 逐项插槽 |
| n-circle-progress | 环形进度条：纯 view 半圆遮罩双弧（无 canvas），中心悬浮百分比（unit 可换）/ 插槽整位替换，起始角与顺逆时针，轨道随主题，activeend 到位事件 |
| n-empty | 空状态：18 场景预设（14 空态 + 4 结果态兼作结果页），品牌淡盘/功能色实盘双视觉，场景文案随语言包，双行文案与操作区插槽，#icon 插画整位替换，贴屏垂直居中档 |
✏️ 表单与输入
| 组件 | 能力 |
|---|---|
| n-input | 输入框：尺寸/边框/形状齐备，前后缀插槽、一键清除、字数统计 |
| n-code-input | 验证码输入：分格显示 + 自动前进回退 + 粘贴整段填充，输满即发 finish 并收键盘；打码 / 下划线 / 发丝线形态，可关系统键盘搭自定义键盘，内置重发行倒计时重发闭环，clear / start / reset 方法 |
| n-form | 表单容器：标签布局统一（位置/对齐/宽度）+ 规则校验 + 四通道错误展示，整表禁用透明遮罩 |
| n-form-item | 表单行：标签 + 控件插槽 + 错误展示，条目级规则与布局覆盖表单级默认值 |
| n-textarea | 多行输入框：auto-height 自动增高（height 即让位）、字数统计独立行、下划线/无边框双形态、聚焦光标/选区、hold-keyboard 防误触收起，与 n-input 同一套外观 |
| n-picker | 选择器：触发器 + 自绘弹层（picker-view 滚轮 + 工具栏），select 单列/多列/级联（columns 形状自动识别，级联联动内置）+ date/time/region 四模式同根滚轮，触发器/弹层内插槽，确认回写、取消不落库 |
| n-radio | 单选项：纯 CSS 自绘，独立受控或入组使用 |
| n-radio-group | 单选组：统一管理成员选中值与整组禁用 |
| n-checkbox | 复选项：方形盒 + 勾选形纯 CSS 自绘，半选形态，独立受控或入组使用 |
| n-checkbox-group | 复选组：值数组统一管理成员选中集合与整组禁用 |
| n-switch | 开关：完全受控（点击只派发目标值，异步确认不回写即不切）+ 轨道内文双形态 + loading 圆钮 + 圆钮内 #icon 图标插槽（作用域 checked） |
| n-number-box | 步进器：长按连发、固定小数位，整数空间运算无浮点误差 |
| n-rate | 评分：点选/横滑、半星支持，星形/图标/插槽三档换形 |
| n-slider | 滑块：单 / 区间双滑块，步进取整，横向 / 竖向、反向、防交叉，点按取值 + 拖动联动，数值回显，滑块插槽全定制 |
| n-color | 色板点选：选中环 + 对勾，按色值亮度自适应黑白 |
🎯 选择器
| 组件 | 能力 |
|---|---|
| n-cascader | 多级联动面板：层级 tab 逐级下钻、对勾回显 |
| n-cascader-picker | 多级联动选择：触发器 + 底部弹层，选中回填完整路径 |
| n-date-time-picker | 日期时间滚轮：大小月闰年自动处理，列间范围联动收紧 |
| n-color-picker | 颜色选择：预设色板 + 色相滑杆取色 + 当前值回显 |
| n-calendar | 日历：单选 / 多选 / 范围，单月 / 滑动 / 连续月份，年月快捷选择、农历、日期说明与角标；可组合 n-popup 使用草稿确认 |
⌨️ 虚拟键盘
| 组件 | 能力 |
|---|---|
| n-keyboard-number | 虚拟数字键盘：支付金额、验证码录入免调系统输入法 |
| n-keyboard-plate | 车牌键盘：省份 + 字母数字双页键区，停车缴费场景 |
🌗 主题
| 组件 | 能力 |
|---|---|
| n-theme-provider | 主题容器：为任意子树装配完整主题变量集（小程序组件样式隔离下自带类定义），跟随全局主题同步切换；局部换肤走 custom-style 覆盖令牌 |
🧰 函数工具集
微信小程序分包说明
组件库为标准 easycom 源码结构，随使用者的项目由其本地编译器编译。若使用者的工程采用多分包且分包页面使用了本库组件，微信开发者工具「代码质量分析」可能出现「主包内不应存在主包未使用的JS文件」提示（列出组件附属模块文件）。成因是 uni-app x 编译器的分包放置策略（组件本体已随分包放置、附属依赖留在主包 uni_modules），并非组件库或使用方式问题；该提示为体积优化建议，不影响小程序的功能、预览、上传与发布。单分包工程不会出现。已在 HBuilderX 5.34 实测并向 DCloud 官方反馈，待编译器修复后自然消除。
| 函数 | 用途 |
|---|---|
| useTheme | 主题状态单例：跟随系统/浅色/深色三态切换，持久化保存，全局响应 |
| useLocale | 语言状态单例：手选/跟随系统、运行时注册新语种、翻译取词 |
| useFormat | 格式化纯函数：手机号/姓名/银行卡/邮箱脱敏，金额千分位两位小数 |
| useSafeArea | 底部安全区单例：小白条/手势条高度，弹层垫底不再踩坑 |
| useIconFont | 图标字体注册：接入自有 iconfont，注册后与内置图标同用法 |
🌗 深色模式，三种粒度
| 粒度 | 说明 |
|---|---|
| 跟随系统 | manifest 开启暗黑支持后自动跟随；原生导航栏 / tabbar 配合 theme.json 联动 |
| 手动切换 | 浅色 / 深色 / 跟随系统三态任切，持久化保存，重启保留、跨页面生效 |
| 局部深色域 | 某块区域独立深色（深色卡片、键盘面板）：n-theme-provider 的 custom-style 整组覆盖中性色令牌（组件颜色全部走 var() 令牌，覆盖即生效） |
实现机制为 CSS 变量双主题：深色主题只重定义中性色，组件全部取变量值——切换零闪烁、无多余节点。
🌍 国际化
- 组件内所有文案（含弹层按钮、键盘键）统一走语言包，简体中文、英文随库发行
- 三层回退：手选语言 → 应用/系统语言 → 内置中文，任何缺失键都回落中文，界面永不出现裸键
- 运行时注册新语种是正式扩展通道（标准 BCP 47 标签），库加密发行也不锁死语言
- 与 vue-i18n 等方案可共存：监听应用语言变化同步给库即可，库不依赖任何 i18n 框架
🎨 主题定制，三层覆盖
| 层级 | 手段 | 适用 |
|---|---|---|
| 运行时 | 节点上直接写 CSS 变量 | 动态换肤、局部微调 |
| 编译期 | 工程全局样式覆盖令牌默认值 | 整库品牌定制（主色、圆角、字号体系） |
| 默认值 | 库内置令牌表（styles/variable.scss，明文发行） | 直接使用，也是定制的参考底本 |
定制通道边界清晰：组件根节点用 custom-class / custom-style 命中；内部节点开放行内样式属性；插槽内容天然在页面作用域。哪些能改、怎么改，每个组件的文档写明白，不猜。
📱 支持环境
| 环境 | 支持 |
|---|---|
| uni-app x（HBuilderX 5.26+） | ✔ |
| App：Android / iOS | ✔ |
| Web | ✔ |
| 微信小程序 | ✔ |
| 经典 uni-app（vue2 / vue3） | ✘（组件为 .uvue 形态，仅面向 uni-app x） |
⚠️ 已知限制
- 0.5px 发丝边框在部分 Android 设备上因屏幕密度取整，实际渲染为 1px（平台渲染特性，非实现缺陷）
- App 端原生导航栏标题、tabbar 文字不受库内语言切换控制（平台限制），需应用自行调用 setNavigationBarTitle / setTabBarItem 同步