更新记录

1.0.58（2026-07-15） 下载此版本

优化用户体验

1.0.57（2026-07-08） 下载此版本

优化用户体验

1.0.56（2026-06-29） 下载此版本

优化用户体验

平台兼容性

uni-app(4.0)

NG-UI（ng-view）组件库使用文档

NG-UI 是一套轻量级的 uni-app UI 组件库（当前仓库的 uni_modules 插件：ng-view），包含常用基础组件 + 一套可选的全局工具库（路由、请求、存储、音频、hooks、工具函数等）。

本组件库的组件源码使用了 <script setup>，更推荐在 uni-app Vue3 项目中使用。

目录

• 1. 安装与引入
• 2. 推荐的全局初始化（可选）
• 3. 全局配置说明
• 4. 通用样式 Props（allProps）
• 5. 组件文档
• 6. 工具库（libs）API 文档

1. 安装与引入

1.1 作为 uni_modules 插件使用

将本目录发布到 uni-app 插件市场后，用户在 HBuilderX 中“下载并导入”即可。

1.2 开启 easycom（推荐）

为了能够直接在页面中使用 <ng-button /> 这类标签，建议在项目根目录 pages.json 中配置 easycom 自动引入：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^ng-(.*)$": "@/uni_modules/ng-view/components/ng-$1/ng-$1.vue"
    }
  }
}

配置完成后，即可在任意页面直接使用组件标签，无需手动 import。

2. 推荐的全局初始化（可选）

NG-UI 提供了一个可选的“全局能力注入”，用于统一维护主题色、组件预设、图片路径拼接、request 默认配置等，并在运行时注入到：

• uni.$ng（全局对象）
• this.$ng（Options API）
• app.config.globalProperties.$ng（Vue3 全局属性）
• app.provide("$ng", ng)（Composition API 注入）

2.1 Vue3（uni-app）main.js 示例

import { createSSRApp } from "vue";
import App from "./App.vue";
import NgUI from "@/uni_modules/ng-view/index.js";

export function createApp() {
  const app = createSSRApp(App);

  app.use(NgUI, {
    color: {
      primary: "#2979ff",
      danger: "#fa3534",
    },
    button: {
      primary: {
        backgroundColor: "#2979ff",
        color: "#fff",
      },
    },
    text: {
      primary: {
        color: "#fff",
        fontSize: "20rpx",
      },
    },
    image: {
      getServer: "https://static.example.com/",
    },
  });

  return { app };
}

2.2 不装插件也能用（按需引入）

你也可以只使用组件（easycom）而不做全局安装；此时：

• getColor（主题色映射）已从运行时配置模块读取，easycom 模式下主题色功能正常可用，不会静默失效。
• ng-image 的 image.getServer 图片路径拼接、ng-button / ng-text 的 preset 预设样式，仍依赖 app.use(NgUI, config) 注入的配置，未安装插件时这些功能将使用空配置（不报错，但预设不生效）。

3. 全局配置说明

📖 详细配置文档：CONFIG.md（包含所有组件 Props 默认值完整列表）

NG-UI 通过 app.use(NgUI, config) 接收全局配置，config 包含三大配置区域：

3.1 快速示例

app.use(NgUI, {
  // 组件 Props 默认值覆盖（必须放在 props 字段下）
  props: {
    navbar: { titleColor: "#ffffff", bgColor: "#1a1a2e" },
    button: { fontSize: 28, round: 8 },
  },
  // 组件层级配置
  zIndex: { toast: 10090, popup: 10075 },
  // 基础配置
  primary: "#00a361",
  color: { primary: "#2979ff", danger: "#fa3534" },
  text: { primary: { color: "#fff", fontSize: "20rpx" } },
  button: { primary: { backgroundColor: "#2979ff", color: "#fff" } },
  image: { getServer: "https://static.example.com/" },
});

3.2 基础配置（defaultConfig）

默认配置定义在：default.js

• primary: string — 主色调，默认 "#00a361"
• color: Record<string, string> — 主题色映射表，配合 getColor() 使用
• text: Record<string, object> — 文本预设，ng-text 的 preset 会读取这里
• button: Record<string, object> — 按钮预设，ng-button 的 preset 会读取这里
• image: { getServer: string | (path)=>string } — 图片路径拼接策略（ng-image 使用）
• radio: { activeColor, inactiveColor } — 单选框颜色配置

3.3 组件 Props 默认值覆盖（props）

通过 props 字段覆盖组件默认值，无需逐个组件传值。必须放在 props 字段下：

// ❌ 错误 —— 放在顶层不会生效
app.use(NgUI, { navbar: { titleColor: "#fff" } });

// ✅ 正确
app.use(NgUI, { props: { navbar: { titleColor: "#fff" } } });

运行时也可通过 setConfig / resetConfig 动态修改或重置：

import { setConfig, resetConfig } from "@/uni_modules/ng-view/index.js";

// 覆盖某个组件默认值
setConfig({ navbar: { bgColor: "#333" } });

// 重置全部组件默认值
resetConfig();

// 仅重置指定组件
resetConfig(['button', 'navbar']);

优先级：组件直接传值 > props 全局配置 > defaults.js 默认值

所有 33 个组件的完整 Props 默认值列表见 CONFIG.md

4. 通用样式 Props（allProps）

部分布局组件（ng-view/ng-flex/ng-grid）支持 ...allProps，这些属性用于快速组装通用布局样式。

实现位置：props.js

4.1 背景类（backgroundProps）

4.2 外边距（marginProps）

注意：当你使用 margin 简写时，组件不会自动补单位，请传入完整 CSS 值（如 "10px 0"）。

4.3 内边距（paddingProps）

注意：当你使用 padding 简写时，组件不会自动补单位，请传入完整 CSS 值（如 "16rpx 24rpx"）。

4.4 定位（positionProps）

4.5 装饰（decorationProps）

4.6 单位规则（非常重要）

• addUnit(number) 默认会补 rpx，例如 addUnit(20) => "20rpx"
• 如果你需要 px，请直接传字符串："20px"
• 组件中大量 props（宽高、圆角、间距等）都会走 addUnit，因此 数值默认视为 rpx

5. 组件文档

本插件包含以下组件（均在 uni_modules/ng-view/components）：

布局与容器

• ng-view 通用容器
• ng-flex Flex 布局
• ng-grid Grid 布局
• ng-gap 间隔/占位
• ng-sticky 吸顶
• ng-footer 底部操作栏
• ng-status-bar 状态栏占位
• ng-safe-bottom 底部安全区占位

基础展示

• ng-text 文本
• ng-image 图片
• ng-avatar 头像
• ng-icon 图标
• ng-price 价格显示
• ng-tag 标签
• ng-divider 分割线
• ng-empty 空状态

表单与交互

• ng-button 按钮
• ng-switch 开关
• ng-checkbox 复选框
• ng-checkbox-group 复选框组
• ng-radio 单选
• ng-radio-group 单选框组
• ng-upload 上传
• ng-tabs 选项卡

弹层与导航

• ng-overlay 遮罩层
• ng-transition 过渡动画
• ng-popup 弹出层容器
• ng-toolbar 弹出层工具栏
• ng-modal 模态框
• ng-navbar 导航栏

选择器（依赖关系见各组件章节）

• ng-picker 通用滚轮选择器
• ng-area 省市区选择器（内部使用 ng-picker）
• ng-datetime 日期时间选择器（内部使用 ng-picker）
• ng-calendar 日历选择器（内部使用 ng-popup）

大多数组件通过 props + 事件交互；带 ref 方法的组件会在各章节中单独说明。 ng-ui 为空占位组件，当前无业务逻辑。

5.1 ng-button 按钮

源码：ng-button.vue

基础用法

<template>
  <ng-button preset="primary" text="确定" @click="onSubmit" />
  <ng-button text="去详情" path="/pages/detail/detail?id=1" />
  <ng-button :loading="loading" :disabled="disabled">自定义插槽文字</ng-button>
</template>

Props

Events

• click(e)：按钮点击（配置 path 时不会触发，仅执行跳转）
• getphonenumber/detail、getuserinfo/detail、error/detail、opensetting/detail、launchapp/detail、contact/detail、chooseavatar/detail、addgroupapp/detail、chooseaddress/detail、subscribe/detail、login/detail、im/detail、agreeprivacyauthorization/detail：原生事件转发（emit 的参数为 e.detail）

Slots

• 默认插槽：存在时替换默认的 <text>{{text}}</text>

5.2 ng-divider 分割线

源码：ng-divider.vue

用法

<template>
  <ng-divider text="我是分割线" />
  <ng-divider dashed />
  <ng-divider dot />
  <ng-divider text-position="left">插槽文字</ng-divider>
</template>

Props

Events

• click：点击分割线触发（原生 tap）

Slots

• 默认插槽：分割线中间内容（优先于 text）

5.3 ng-flex Flex 布局

源码：ng-flex.vue

用法

<template>
  <ng-flex jc="space-between" ai="center" :cg="16">
    <ng-text text="左" />
    <ng-text text="右" />
  </ng-flex>
</template>

Props

除下表外，还支持通用样式 Props：见 allProps

Slots

• 默认插槽

5.4 ng-grid Grid 布局

源码：ng-grid.vue

用法

<template>
  <ng-grid :col="3" :gap="16" @click="onGridClick">
    <ng-view v-for="n in 6" :key="n" bgColor="#f5f5f5" height="100rpx" />
  </ng-grid>
</template>

Props

除下表外，还支持通用样式 Props：见 allProps

Events

• click(e)：点击触发（配置 path 时不会触发，仅执行跳转）

Slots

• 默认插槽

5.5 ng-view 通用容器

源码：ng-view.vue

用法

<template>
  <ng-view
    bgColor="#fff"
    bgSrc="/static/example/banner.png"
    padding="24rpx"
    round="16"
    shadow="0 6rpx 20rpx rgba(0,0,0,0.08)">
    <ng-text text="内容区" />
  </ng-view>
</template>

Props

支持通用样式 Props：见 allProps

Events

• click(e)：点击触发（配置 path 时不会触发，仅执行跳转）

Slots

• 默认插槽

5.6 ng-text 文本

源码：ng-text.vue

用法

<template>
  <ng-text text="标题" preset="h1" bold />
  <ng-text text="可点击" path="/pages/detail/detail" />
</template>

Props

Events

• click(e)：点击触发（配置 path 时不会触发，仅执行跳转）

5.7 ng-image 图片

源码：ng-image.vue

用法

<template>
  <ng-image src="https://example.com/a.png" wh="200 200" round="16" />

  <ng-image
    server-src="/images/a.png"
    :preview="true"
    :preview-list="['https://example.com/a.png', 'https://example.com/b.png']"
    :preview-current="0"
    wh="200 200" />

  <ng-image src="https://example.com/a.png" show-mask>
    <template #mask>
      <ng-text text="遮罩内容" color="#fff" />
    </template>
  </ng-image>
</template>

Props

支持外边距 Props（margin/mt/mb/ml/mr）

Events

• click(e)：点击触发（当 preview=false 且未配置 path）
• load(e)：image load
• error(e)：image error

Slots

• mask：自定义遮罩内容（showMask=true 时显示）

5.8 ng-icon 图标

源码：ng-icon.vue

用法

<template>
  <ng-icon name="arrow-right" />
  <ng-icon name="close" :size="40" color="#fa3534" bold @click="onClose" />
</template>

Props

Events

• click(e)

5.9 ng-overlay 遮罩

源码：ng-overlay.vue

用法

<template>
  <ng-overlay :show="show" @click="show = false" />
</template>

Props

Events

• click

Slots

• 默认插槽：遮罩内容（会通过 transition 渲染）

5.10 ng-transition 过渡动画

源码：ng-transition.vue

用法

<template>
  <ng-transition
    :show="show"
    mode="fade-zoom"
    @afterEnter="onOpen"
    @afterLeave="onClose">
    <ng-view bgColor="#fff" padding="24rpx">内容</ng-view>
  </ng-transition>
</template>

Props

mode 可选值

动画映射定义在：nvue.ani-map.js

• fade
• fade-up
• fade-down
• fade-left
• fade-right
• slide-up
• slide-down
• slide-left
• slide-right
• zoom
• fade-zoom

Events

• click(e)
• beforeEnter / enter / afterEnter
• beforeLeave / leave / afterLeave

5.11 ng-popup 弹出层

源码：ng-popup.vue

用法

<template>
  <ng-button text="打开" @click="show = true" />
  <ng-popup
    :show="show"
    mode="bottom"
    round="24"
    closeable
    @open="onOpen"
    @close="show = false">
    <ng-view padding="24rpx">弹窗内容</ng-view>
  </ng-popup>
</template>

Props

Events

• open：弹窗动画进入完成后触发
• close：请求关闭（点击遮罩/关闭按钮会 emit；真正关闭由外部将 show=false 完成）
• click：点击弹窗区域触发（center 模式下会触发 overlayClick 逻辑）

Slots

• 默认插槽：弹窗内容

5.11.1 ng-toolbar 弹出层工具栏

源码：ng-toolbar.vue

用法

<template>
  <ng-popup :show="show" mode="bottom" round="20" @close="show = false">
    <ng-toolbar title="请选择" @cancel="show = false" @confirm="onConfirm" />
    <ng-view padding="24rpx">弹窗内容</ng-view>
  </ng-popup>
</template>

Props

Events

• cancel：点击取消按钮
• confirm：点击确认按钮

Slots

• title：自定义中间标题区域

5.12 ng-modal 模态框

源码：ng-modal.vue

用法（同步关闭）

<template>
  <ng-modal
    :show="show"
    title="提示"
    content="确定删除吗？"
    :show-cancel-button="true"
    @confirm="onConfirm"
    @cancel="show = false"
    @close="show = false" />
</template>

用法（asyncClose）

当 asyncClose=true 时，点击“确认”会进入 loading 状态，但不会自动关闭，你需要在异步成功后将 show=false：

<template>
  <ng-modal
    :show="show"
    title="提交中"
    content="请稍候..."
    :async-close="true"
    @confirm="submit"
    @close="show = false" />
</template>

Props

Events

• confirm：点击确认
• cancel：点击取消
• close：点击遮罩请求关闭（需 closeOnClickOverlay=true）

Slots

• 默认插槽：内容区（替代 content）
• title：标题区
• footer：底部整块替换
• confirmButton：仅一个确认按钮区域
• cancel：取消按钮自定义
• confirm：确认按钮自定义

5.13 ng-navbar 导航栏

源码：ng-navbar.vue

用法

<template>
  <ng-navbar title="首页" @leftClick="onBack" />
  <ng-navbar>
    <template #center>
      <ng-text text="自定义标题" />
    </template>
    <template #right>
      <ng-icon name="close" @click="onClose" />
    </template>
  </ng-navbar>
</template>

Props

Events

• leftClick：点击左侧区域触发

Slots

• 默认插槽：整体自定义（覆盖默认 left/center/right 结构）
• center：中间区域
• right：右侧区域

5.14 ng-tabs 选项卡

源码：ng-tabs.vue

用法

<template>
  <ng-tabs :list="list" v-model="current" @change="onChange" />
</template>

<script setup>
const current = ref(0);
const list = ref([{ name: "推荐" }, { name: "热门" }, { name: "最新" }]);
const onChange = (index) => {
  console.log("当前选中：", index);
};
</script>

Props

Events

• change：点击标签时触发，返回索引
• click：点击标签时触发，返回标签对象
• longPress：长按标签时触发，返回索引

5.15 ng-radio 单选

源码：ng-radio.vue

用法

<template>
  <ng-radio v-model="checked" :name="true" label="同意协议" />
</template>

Props

Events

• update:modelValue(value)
• change(value)

5.16 ng-radio-group 单选框组

源码：ng-radio-group.vue

用法

<template>
  <ng-radio-group v-model="value" :gap="24" @change="onChange">
    <ng-radio name="home" label="家装" />
    <ng-radio name="work" label="工装" />
  </ng-radio-group>
</template>

Props

Events

• update:modelValue(value)
• change({ value, name })

5.17 ng-checkbox 复选框

源码：ng-checkbox.vue

用法

<template>
  <ng-checkbox v-model="checked" label="同意协议" />

  <ng-checkbox-group v-model="selected">
    <ng-checkbox name="apple" label="苹果" />
    <ng-checkbox name="banana" label="香蕉" />
  </ng-checkbox-group>
</template>

Props

Events

• update:modelValue(value)
• change({ value, name, checked })

5.18 ng-checkbox-group 复选框组

源码：ng-checkbox-group.vue

Props

Events

• update:modelValue(array)
• change({ value, name, checked })

5.19 ng-switch 开关

源码：ng-switch.vue

用法

<template>
  <ng-switch v-model="checked" @change="onChange" />
  <ng-switch
    v-model="checked2"
    :loading="loading"
    active-color="#19be6b"
    inactive-color="#dcdfe6"
    :size="36" />
</template>

Props

Events

• update:modelValue(boolean)
• change(boolean)
• click(boolean, event)

5.20 ng-price 价格显示

源码：ng-price.vue

用法

<template>
  <ng-price price="99.9" prefix="¥" suffix="元" color="#ff0000" :intSize="40" />
</template>

Props

Events

• click：点击价格时触发

5.21 ng-status-bar 状态栏占位

源码：ng-status-bar.vue

Props

5.22 ng-safe-bottom 底部安全区占位

源码：ng-safe-bottom.vue

Props

5.23 ng-sticky 吸顶

源码：ng-sticky.vue

用法

<template>
  <ng-sticky :offset-top="0" bg-color="#fff">
    <ng-view padding="24rpx">吸顶内容</ng-view>
  </ng-sticky>
</template>

Props

Slots

• 默认插槽

5.24 ng-footer 底部栏

源码：ng-footer.vue

用法

<template>
  <ng-footer>
    <ng-button preset="primary" text="提交" />
  </ng-footer>
</template>

Props

Slots

• 默认插槽

5.25 ng-gap 间隔

源码：ng-gap.vue

Props

5.26 ng-area 省市区选择器

源码：ng-area.vue

组件依赖：ng-area 内部使用了 ng-picker。开启 easycom 后自动解析；手动引入时请确保同时引入 ng-picker。

用法

<template>
  <ng-button text="选择地区" @click="show = true" />
  <ng-area
    v-model:show="show"
    v-model="areaNames"
    title="选择地区"
    @confirm="onConfirm" />
</template>

<script setup>
import { ref } from "vue";
const show = ref(false);
const areaNames = ref([]); // 形如 ["广东省","深圳市","南山区"]
const onConfirm = (result) => {
  // result.value: 名称数组
  // result.code: 代码数组
  // result.province/city/district: 对象
};
</script>

Props

Events

• update:show(boolean)：关闭/打开
• update:modelValue(array)：确认时更新名称数组
• confirm(result)：确认选择（包含 province/city/district/value/code）
• cancel：取消或未确认关闭触发
• change(payload)：picker 滚动变化

Slots / Methods

• toolbarTitle：自定义顶部工具栏标题区域
• bottom：透传 ng-picker 的底部扩展区作用域
• 通过 ref 可调用：close()、cancel()、confirm()

5.27 ng-picker 通用选择器

源码：ng-picker.vue

用法

<template>
  <!-- 单列 -->
  <ng-picker v-model:show="show1" :columns="columns1" @confirm="onConfirm" />

  <!-- 多列联动 -->
  <ng-picker v-model:show="show2" :columns="columns2" @confirm="onConfirm" />
</template>

<script setup>
import { ref } from "vue";
const show1 = ref(false);
const columns1 = ref([["中国", "美国", "日本"]]);

const show2 = ref(false);
const columns2 = ref([
  {
    text: "中国",
    children: [{ text: "北京" }, { text: "上海" }],
  },
  {
    text: "美国",
    children: [{ text: "纽约" }, { text: "洛杉矶" }],
  },
]);
</script>

Props

Events

• update:show(boolean)：显示状态改变
• update:modelValue(array)：索引变化
• confirm(result)：点击确定，返回 { value, indexs, values }
• cancel：点击取消
• change(payload)：选项改变，返回 { value, indexs, values, columnIndex, index }

Slots

• bottom：底部扩展区，作用域参数包含 onCancel/onConfirm/onClose/indexs/value/values
• toolbarTitle：自定义顶部工具栏标题区域

Methods

通过 ref 可调用：close()、cancel()、confirm()、setIndexs(indexs, setLastIndex)、setColumnValues(columnIndex, values)、getColumnValues(columnIndex)、getIndexs()、getValues()。

5.28 ng-datetime 日期时间选择器

源码：ng-datetime.vue

组件依赖：ng-datetime 内部使用了 ng-picker。开启 easycom 后自动解析；手动引入时请确保同时引入 ng-picker。

ng-datetime 基于 ng-picker 封装，支持 datetime、date、year-month、time 四种模式，并支持 minDate/maxDate、minTime/maxTime 范围限制。

用法

<template>
  <ng-button text="选择时间" @click="show = true" />
  <ng-datetime
    v-model:show="show"
    v-model="value"
    mode="datetime"
    :min-date="'2026-01-01 00:00:00'"
    :max-date="'2026-12-31 23:59:59'"
    @confirm="onConfirm" />
</template>

<script setup>
import { ref } from "vue";
const show = ref(false);
const value = ref("");
const onConfirm = (res) => {
  // res: { value, date, parts }
};
</script>

<ng-datetime v-model:show="show" v-model="dateValue" mode="date" />
<ng-datetime v-model:show="show" v-model="monthValue" mode="year-month" />
<ng-datetime
  v-model:show="show"
  v-model="timeValue"
  mode="time"
  min-time="09:00"
  max-time="18:30" />

Props

Events

• update:show(boolean)：显示状态改变
• update:modelValue(string)：确认或滚动更新时触发
• confirm(res)：确认选择，返回 { value, date, parts, mode }
• change(res)：滚动变化，返回 { value, date, parts, mode }
• cancel / close

Slots / Methods

• toolbarTitle：自定义顶部工具栏标题区域
• bottom：透传 ng-picker 的底部扩展区作用域
• 通过 ref 可调用：close()、cancel()、confirm()、setFormatter(formatter)

5.29 ng-upload 上传（选择文件 + 预览）

源码：ng-upload.vue

用法（自动上传）

传入 v-model 和 action 后，组件会自动选择、上传、维护状态和删除列表。

<template>
  <ng-upload
    v-model="fileList"
    :action="uploadUrl"
    :max-count="9"
    :max-size="2 * 1024 * 1024"
    upload-text="上传"
    @oversize="onOversize" />
</template>

<script setup>
import { ref } from "vue";

const fileList = ref([]);
const uploadUrl = "https://your-domain.com/api/upload";

const onOversize = () => {
  uni.showToast({ title: "文件过大", icon: "none" });
};
</script>

Props

fileList 每项支持 status/message/deletable/thumb/url/type/response，其中 status="uploading" 会显示加载遮罩，status="failed" 显示失败状态，status="success" 显示成功角标。

如果需要完全自己接管上传流程，也可以继续使用 :file-list、@afterRead、@delete 的旧受控写法。

Events

• beforeRead({ file, name, index, callback })：当 useBeforeRead=true 时触发；你需要手动调用 callback(true/false) 决定是否继续
• afterRead({ file, name, index })：选择文件后触发（未超限）
• oversize({ file, name, index })：超出 maxSize 触发
• delete({ file, name, index })：点击删除触发
• success({ file, response, name, index })：自动上传成功触发
• fail({ file, error, name, index })：自动上传失败触发
• clickPreview(payload)：点击预览触发
• error(error)：chooseFile 失败或其他错误

Slots

• 默认插槽：自定义上传按钮区域（替换默认上传按钮）

图片会调用 uni.previewImage 预览；微信环境下视频会优先调用 wx.previewMedia 预览。

5.30 ng-empty 空状态

源码：ng-empty.vue

用法

<template>
  <!-- 默认样式 -->
  <ng-empty />

  <!-- 自定义文案与图标 -->
  <ng-empty text="暂无订单" icon="empty-2" icon-color="#ccc" />

  <!-- 带外边距 -->
  <ng-empty text="暂无数据" :mt="40" />
</template>

Props

支持外边距 Props（margin/mt/mb/ml/mr）

5.31 ng-tag 标签

源码：ng-tag.vue

用法

<template>
  <!-- 默认填充标签 -->
  <ng-tag text="新品" />

  <!-- 镂空描边标签 -->
  <ng-tag text="促销" plain color="#ff6b35" />

  <!-- 自定义圆角、尺寸 -->
  <ng-tag text="推荐" :round="999" :size="22" bgColor="#e8f5e9" color="#2e7d32" />

  <!-- 点击跳转 -->
  <ng-tag text="查看详情" path="/pages/detail/index" />
</template>

Props

除下表外，还支持通用样式 Props：见 allProps

Events

• click(e)：点击标签（配置 path 时不触发）

Slots

• 默认插槽：存在时替换 text prop 的内容

5.32 ng-calendar 日历选择器

源码：ng-calendar.vue

组件依赖：ng-calendar 内部使用了 ng-popup。开启 easycom 后自动解析；手动引入时请确保同时引入 ng-popup。

用法

<template>
  <ng-button text="选择日期" @click="show = true" />

  <!-- 区间选择（默认） -->
  <ng-calendar
    v-model:show="show"
    v-model="dateRange"
    mode="range"
    @confirm="onConfirm" />

  <!-- 单日选择 -->
  <ng-calendar
    v-model:show="showSingle"
    v-model="singleDate"
    mode="single"
    @confirm="onConfirm" />
</template>

<script setup>
import { ref } from "vue";
const show = ref(false);
const dateRange = ref([]);   // ["2024-01-01", "2024-01-07"]

const showSingle = ref(false);
const singleDate = ref("");

const onConfirm = ({ value, start, end, night }) => {
  console.log(value, start, end, night);
};
</script>

Props

Events

• update:show(boolean)：显示状态变化
• update:modelValue(value)：日期变化时同步（可配合 v-model）
• confirm({ value, start, end, night })：点击确认按钮时触发
• cancel：点击关闭按钮
• close：弹窗关闭（cancel / 遮罩点击均触发）
• change({ value, start, end, night })：选择日期变化时实时触发

Methods

通过 ref 可调用：close()、confirm()。

6. 工具库（libs）API 文档

工具库的入口导出见：libs/index.js

你可以通过两种方式使用工具库：

1. 全局安装后：

const ng = uni.$ng; // 或 this.$ng / inject("$ng")
ng.request.get("/user");

2. 按需导入：

import {
  request,
  router,
  storage,
  systemInfo,
} from "@/uni_modules/ng-view/index.js";

6.1 createNGUI / install（插件入口）

入口文件：index.js

createNGUI(config?)

• 作用：创建 $ng 实例并挂载到 uni.$ng
• 返回：ngui 对象（仅暴露业务层高频 API，低层工具函数通过 import 按需引入）：
  • sys（getter → 始终返回最新系统信息，调用 refreshSysInfoCache() 后立即生效）
  • router、push、back（路由快捷方法）
  • storage、request、createRequest（存储与请求）
  • audioManager（音频管理）
  • toast（轻提示）
  • config、version、setConfig、resetConfig（配置管理）

install(app, config?)

• 作用：Vue3 插件安装函数（内部调用 createNGUI）
• 额外行为：
  • app.config.globalProperties.$ng = ngui
  • app.provide("$ng", ngui)

6.2 systemInfo()

源码：system.js

用法

import { systemInfo, refreshSysInfoCache } from "@/uni_modules/ng-view/index.js";

// 获取系统信息（内部使用单例缓存，整个生命周期只调用一次 getSystemInfoSync）
const info = systemInfo();

// 横竖屏切换后强制刷新缓存（下次访问 uni.$ng.sys 或调用 systemInfo() 时重新获取）
refreshSysInfoCache();

返回字段（常用）

• windowWidth/windowHeight
• screenWidth/screenHeight
• statusBarHeight
• safeArea/safeAreaInsets
• dpr
• scaleFactor
• 微信小程序额外：menuButtonHeight/menuButtonWidth/menuButtonTop/menuButtonRight/menuButtonBottom/menuButtonLeft

6.3 storage（带过期时间的存储）

源码：storage.js

默认前缀：NG_（仅影响 storage 工具自身，不影响 uni.setStorageSync 的其他 key）

API

• storage.set(key, value, expireSeconds?) => boolean
  设置同步存储；expireSeconds 为秒，传入则会记录过期时间
• storage.get(key, defaultValue?) => any
  获取同步存储；过期会自动清理并返回 defaultValue
• storage.setAsync(key, value, expireSeconds?) => Promise<boolean>
• storage.getAsync(key, defaultValue?) => Promise<any>
• storage.remove(key) => boolean
• storage.has(key) => boolean
• storage.setMultiple({k:v,...})
• storage.getMultiple(keys: string[]) => Record<string, any>
• storage.clear() => boolean
  仅清除带 NG_ 前缀的 key（同步逐条删除）
• storage.clearAsync() => Promise<boolean>
  并行异步清除带 NG_ 前缀的 key，key 数量多时性能显著优于 clear()
• storage.getInfo() => { keys, size, limit }

6.4 router（轻量路由封装）

源码：router.js

特性：

• 支持 push/replace/reLaunch/back
• 支持 query 序列化（数组/对象会做特殊处理）
• 支持 params（通过 storage 临时存储，跳转后调用 router.getParams() 取出并自动清理）
• 支持导航守卫：beforeEach/afterEach/onError
• 自动识别 tabBar：如果目标 path 是 tabBar 页面，会自动切换为 switchTab

API

• router.push(path, options?) => Promise
  • options.mode：navigateTo（默认）/redirectTo/reLaunch/switchTab/preloadPage
  • options.query：对象，会拼进 url
  • options.params：对象，不拼接到 url，通过 storage 透传
  • 其余字段（animationType 等）透传到 uni 跳转方法
• router.replace(path, options?) => Promise（等价于 mode=redirectTo）
• router.reLaunch(path, options?) => Promise
• router.back(delta=1)：返回；当栈深不足时回到首页 tabBar 或 pages[0]
• router.getParams() => any：获取并清理通过 params 传递的数据
• router.isTab(path) => boolean：判断是否 tabBar
• router.beforeEach((to, next, redirect) => void | Promise)：注册前置守卫，返回取消函数
• router.afterEach((to)=>void)：注册后置回调，返回取消函数
• router.onError((error, to)=>void)：注册错误回调，返回取消函数

push 示例（params 传对象）

router.push("/pages/detail/detail", {
  query: { id: 1 },
  params: { foo: "bar", deep: { a: 1 } },
});

// 在目标页 onLoad/onShow 中：
const params = router.getParams();

6.5 audioManager（全局音频控制器）

源码：audioController.js

事件名称

API

• audioManager.set(list, options?) - 设置播放列表
  • list：音频数组，每项至少包含 { src }
  • options.index：开始播放索引（默认 0）
  • options.playMode：播放模式（order/loop/random/single）
  • options.debug：是否输出调试日志
  • options.itemEndedAt：触发结束回调的时间点数组（毫秒）
  • options.waitMs：列表级默认播放后等待时间（毫秒）
  • 顶层回调：如 onStart(){}, onItemEnded(){} 等
• audioManager.play(index?, isManualAction?) - 播放指定索引
• audioManager.toggle() - 切换播放/暂停
• audioManager.pause() - 暂停
• audioManager.stop() - 停止并清空状态
• audioManager.seek(time) - 跳转到指定时间（秒）
• audioManager.next() - 下一首
• audioManager.prev() - 上一首
• audioManager.setMode(mode) - 设置播放模式（order/loop/random/single）
• audioManager.setLoop(times) - 设置循环次数
• audioManager.setPlaybackRate(rate) - 设置播放倍速（0.5-3.0）
• audioManager.on(eventName, callback) - 订阅事件
• audioManager.off(eventName, callback?) - 取消订阅
• audioManager.getState() - 获取当前状态

6.6 request / createRequest

源码：request.js

导出形式：

• request：默认实例（export default createRequest()）
• createRequest(instanceConfig)：创建独立实例（独立拦截器、独立 baseURL 等）

配置来源

request 会合并以下配置（后者覆盖前者）：

1. 内置默认配置（DEFAULT_REQUEST_CONFIG）
2. 实例级配置（createRequest(instanceConfig) 传入）
3. 单次请求 options（request({ ... }) 传入）

request(options) 扩展字段

在 uni.request 官方参数基础上，额外支持：

• baseURL：覆盖本次请求的 baseURL
• returnType: "data" | "response"：默认返回 res.data；传 "response" 则返回完整 response
• validateStatus(statusCode) => boolean：自定义状态码成功判定

get/post/put/delete 快捷方法

• request.get(url, data?, options?)
• request.post(url, data?, options?)
• request.put(url, data?, options?)
• request.delete(url, data?, options?)

拦截器

request 同时支持两种拦截器：

1. 配置数组形式（全局/实例配置中）：

• requestInterceptors: Function[]：入参为 requestOptions，返回可选的 requestOptions（支持 Promise）
• responseInterceptors: Function[]：入参为 response，返回可选的 response（支持 Promise）

2. 类 axios 形式（每个实例自带）：

• request.interceptors.request.use(onFulfilled, onRejected?) => id
• request.interceptors.request.eject(id)
• request.interceptors.request.clear()
• request.interceptors.response.use(...)

abort（取消请求）

request.request() 返回的是 Promise，并附带：

• promise.task：可拿到 RequestTask
• promise.abort()：内部调用 RequestTask.abort()

示例：

const p = request.get("/list");
// 取消
p.abort();

6.7 hooks

useCountDown(options?)

源码：useCountDown.js

• 入参：{ onFinish?, interval=1000 }
• 返回：
  • timeData：computed，包含 day/hour/minute/second/milliseconds/remain
  • remain：ref，剩余毫秒
  • start(ms)：启动
  • stop()：停止
  • reset(ms)：重置

useAppUpdate(options)

源码：useAppUpdate.js

• 入参：
  • api(params) => Promise<any>：请求版本信息的 API（必传，仅 APP-PLUS 下生效）
  • shouldUpdate(res) => boolean：判断是否需要更新（必传）
  • downloadUrlField: string：下载地址字段名（必传）
• 返回状态：
  • versionData/hasUpdate/updating/downloadProgress/updateStatus/errorMessage/updateType
• 返回方法：
  • checkUpdate({ currentVersion? }) => Promise<boolean>
  • handleUpdate() => Promise<boolean>
  • cancelUpdate()
  • resetUpdate()
  • 工具方法：normalizeDownloadUrl/isWgtUrl/isApkUrl/isAppStoreUrl/isIOS

useWechatLogin(options)

源码：useWechatLogin.js

• 入参（关键）：
  • miniProgramLoginApi：小程序登录 API（必传）
  • appLoginApi：APP/H5 微信登录 API（必传）
  • appleLoginApi：苹果登录 API（可选）
  • storageKeys: { tokenKey: string }（必传）
  • onLoginSuccess(res)（必传）
  • onLoginError(err)（可选）
• 返回：
  • 状态：loading/error/isIOS
  • 小程序：getMiniProgramCode()、handlePhoneAuth(authResult, agreedToTerms?)
  • APP/H5：handleAppLogin(agreedToTerms?)、detectIOS()
  • iOS：handleAppleLogin(agreedToTerms?)
  • 工具：checkAgreement/checkPhoneAuthResult/showError

6.8 utils（工具函数）

libs/index.js 已全量导出所有工具函数，源码见：utils/index.js

单位与布局

• px2rpx(px)：px 转 rpx
• rpx2px(rpx)：rpx 转 px
• addUnit(value, unit="rpx")：给数字补单位
• getWH(wh, width, height) => { w, h }：解析宽高快捷值

颜色与配置

• toHex(color)：颜色转十六进制
• convertColor(color)：颜色格式转换
• getColor(val)：主题色映射（从运行时配置 color 表中匹配别名，easycom 模式下也可用）
• getPrimaryColor()：读取主色调（config.primary），easycom 模式下返回 defaultConfig.primary，不依赖 uni.$ng
• getComponentConfig(componentName, presetName)：读取组件预设

样式

• addStyle(styleValue, target="object")：样式格式转换
• trim(str, pos="both")：去空格

校验

• isEmpty(value)：判断空
• isObject(val)：是否对象
• isPhone(str)：是否手机号
• isEmail(str)：是否邮箱
• isIdCard(str)：是否身份证
• isNumber(value)：是否数值
• isPureNumber(str)：是否纯数字

数据

• deepMerge(target, ...sources)：深度合并
• deepClone(obj)：深克隆
• removeEmpty(obj, isDeep=false)：过滤空值

辅助

• padZero(num, length=2)：补零
• guid(len=32)：生成 GUID
• toast(title, options)：显示提示
• sleep(ms=30)：延迟

DOM

• getRect(context, selector, all=false)：获取节点信息

函数式

• throttle(fn, wait=500, immediate=true)：节流
• debounce(fn, wait=500, immediate=false)：防抖

文件

• base64ToTempPath(base64)：base64 转临时路径

日历

• calendar：农历/公历转换工具

设备与时间

• getDevice()：获取设备信息
• timeFormat(date, fmt?)：时间格式化
• timeFrom(date, option?)：相对时间

6.9 样式 Props 工具函数（props.js）

源码：props.js

• backgroundStyle(props) => object
• marginStyle(props) => object
• paddingStyle(props) => object
• positionStyle(props) => object
• getAllStyles(props) => object：汇总以上样式
• allProps：上述所有 props 的聚合对象（供组件 ...allProps 使用）

6.10 utils 全量导出

libs/index.js 已全量导出所有工具函数，可直接使用：

import { rpx2px, timeFormat, calendar, isPhone } from "@/uni_modules/ng-view";

完整列表见：utils/index.js

新增组件文档（v1.0.56+）

以下组件为 v1.0.56 版本新增，遵循三件套规范，通过 easycom 自动引入。

5.33 ng-cell 单元格

源码：ng-cell.vue

用法

<template>
  <ng-cell title="收货地址" icon="location" arrow @click="goAddress" />
  <ng-cell title="手机号" value="138****8888" :arrow="false" />
  <ng-cell title="推送通知" :arrow="false">
    <template #right><ng-switch v-model="notify" /></template>
  </ng-cell>
  <ng-cell title="必填项" required label="请填写完整信息" />
</template>

Props

Events

• click：点击单元格（配置 path 时不触发）

Slots

• 默认插槽：右侧内容区
• title：自定义标题区
• right：自定义右侧区域（替换 value + arrow）

5.34 ng-input 输入框

源码：ng-input.vue

用法

<template>
  <ng-input v-model="phone" placeholder="请输入手机号" type="number" clearable />
  <ng-input v-model="pwd" placeholder="请输入密码" password />
  <ng-input v-model="name" prefix-icon="user" suffix-icon="edit" />
  <ng-input v-model="amount" prefix="¥" suffix="元" />
</template>

Props

Events

• update:modelValue(val)：值变化
• input(val)：输入事件
• focus(e) / blur(e) / confirm(e)
• clear：点击清除
• click-suffix-icon：点击右侧图标

5.35 ng-form 表单容器

源码：ng-form.vue

搭配 ng-form-item 使用，通过 provide/inject 通信。

用法

<template>
  <ng-form :model="form" :rules="rules" ref="formRef">
    <ng-form-item label="姓名" prop="name">
      <ng-input v-model="form.name" />
    </ng-form-item>
    <ng-form-item label="手机" prop="phone">
      <ng-input v-model="form.phone" type="number" />
    </ng-form-item>
    <ng-button text="提交" @click="submit" />
  </ng-form>
</template>

<script setup>
const form = ref({ name: "", phone: "" });
const rules = { name: [{ required: true, message: "姓名不能为空" }] };
const formRef = ref();
const submit = async () => {
  const valid = await formRef.value.validate();
  if (valid) console.log("通过");
};
</script>

ng-form Props

ng-form Methods

• validate() => Promise<boolean>：校验全部字段
• clearValidate(props?) ：清除校验
• resetFields()：重置并清除

ng-form-item Props

规则格式

// required 必填
{ required: true, message: "不能为空" }
// 长度限制
{ min: 2, max: 20, message: "2~20个字符" }
// 正则
{ pattern: /^\d+$/, message: "只能输入数字" }
// 自定义
{ validator: (rule, value, callback) => { callback(value ? undefined : new Error("不能为空")); } }

5.36 ng-loading 全屏加载

源码：ng-loading.vue

用法

<template>
  <ng-loading :show="loading" text="加载中..." />
</template>

Props

5.37 ng-badge 角标

源码：ng-badge.vue

用法

<template>
  <ng-badge :value="5">
    <ng-icon name="message" size="48" />
  </ng-badge>
  <ng-badge :value="100" :max="99">...</ng-badge>
  <ng-badge dot><ng-icon name="bell" /></ng-badge>
</template>

Props

Slots

• 默认插槽：被角标包裹的内容

5.38 ng-notice-bar 通知栏

源码：ng-notice-bar.vue

用法

<template>
  <ng-notice-bar text="限时活动：全场满300减50" />
  <ng-notice-bar :list="notices" mode="closeable" @close="onClose" />
  <ng-notice-bar text="点击查看详情" mode="link" @click="goDetail" />
</template>

Props

Events

• close：点击关闭按钮
• click：点击通知（mode="link" 时）

5.39 ng-action-sheet 操作菜单

源码：ng-action-sheet.vue

依赖：内部使用 ng-popup、ng-safe-bottom。

用法

<template>
  <ng-action-sheet
    v-model:show="show"
    title="请选择操作"
    :actions="[
      { name: '拍照', icon: 'camera' },
      { name: '从相册选择', icon: 'image' },
      { name: '删除', color: '#ee0a24', subname: '删除后不可恢复' },
    ]"
    @select=""
  />
</template>

Props

actions 格式：{ name, icon?, color?, subname?, disabled? }

Events

• update:show(boolean)
• select({ action, index })：点击某项
• cancel / close

5.40 ng-skeleton 骨架屏

源码：ng-skeleton.vue

用法

<template>
  <ng-skeleton :loading="pageLoading" :rows="3" avatar>
    <!-- loading=false 时渲染实际内容 -->
    <view>真实内容</view>
  </ng-skeleton>
</template>

Props

Slots

• 默认插槽：loading=false 时渲染的真实内容

5.41 ng-collapse 折叠面板

源码：ng-collapse.vue

搭配 ng-collapse-item 使用，通过 provide/inject 通信。

用法

<template>
  <ng-collapse v-model="active" accordion>
    <ng-collapse-item title="退款说明" name="1">退款在7个工作日内处理完成…</ng-collapse-item>
    <ng-collapse-item title="运费说明" name="2">满99元包邮…</ng-collapse-item>
    <ng-collapse-item title="发货时间" name="3" disabled>暂不支持</ng-collapse-item>
  </ng-collapse>
</template>

<script setup>
const active = ref(null); // accordion 模式：string；多选模式：array
</script>

ng-collapse Props

ng-collapse-item Props

Events（ng-collapse）

• update:modelValue(val) / change(val)

5.42 ng-steps 步骤条

源码：ng-steps.vue

用法

<template>
  <ng-steps :current="2" :steps="[
    { title: '提交订单' },
    { title: '付款', desc: '已付款' },
    { title: '发货' },
    { title: '完成' },
  ]" />

  <ng-steps :current="1" direction="vertical" :steps="[...]" />
</template>

Props

5.43 ng-progress 进度条

源码：ng-progress.vue

用法

<template>
  <ng-progress :percent="75" show-info />
  <ng-progress :percent="uploadPercent" status="active" />
  <ng-progress :percent="100" status="success" />
</template>

Props

5.44 ng-swipe-action 侧滑操作

源码：ng-swipe-action.vue

用法

<template>
  <ng-swipe-action
    :right-actions="[
      { text: '标记', color: '#2979ff', textColor: '#fff' },
      { text: '删除', color: '#f04035', textColor: '#fff' },
    ]"
    @click="onSwipeClick"
  >
    <ng-cell title="可侧滑的列表项" />
  </ng-swipe-action>
</template>

Props

Events

• click({ side, btn, index })：点击操作按钮
• open(side) / close

Methods

通过 ref 可调用：close()（手动关闭）

5.45 ng-rate 评分

源码：ng-rate.vue

用法

<template>
  <ng-rate v-model="score" @change="onChange" />
  <ng-rate v-model="halfScore" :allow-half="true" />
  <ng-rate v-model="readonlyScore" :readonly="true" />
</template>

Props

Events

• update:modelValue(val) / change(val)

5.46 ng-search 搜索框

源码：ng-search.vue

用法

<template>
  <ng-search v-model="keyword" @search="onSearch" />
  <ng-search v-model="keyword" :show-action="false" shape="square" />
</template>

Props

Events

• update:modelValue(val) / input(val)
• search(val)：点击搜索按钮或键盘确认
• clear：清除

5.47 ng-count-down 倒计时

源码：ng-count-down.vue

用法

<template>
  <!-- 默认文本展示 -->
  <ng-count-down :time="3 * 60 * 60 * 1000" />

  <!-- 自定义插槽 -->
  <ng-count-down :time="time" v-slot="{ timeData }">
    <text>{{ timeData.hours }}:{{ timeData.minutes }}:{{ timeData.seconds }}</text>
  </ng-count-down>

  <!-- 手动控制 -->
  <ng-count-down ref="countRef" :time="60000" :auto-start="false" />
</template>

<script setup>
const countRef = ref();
countRef.value.start();  // 开始
countRef.value.pause();  // 暂停
countRef.value.reset();  // 重置
</script>

Props

Events

• finish：倒计时结束
• change(timeData)：时间变化

Methods

start() / pause() / reset(newTime?)

5.48 ng-circle 环形进度

源码：ng-circle.vue

用法

<template>
  <ng-circle :value="75" />
  <ng-circle :value="score" size="160" stroke-width="12">
    <template #default>
      <text>{{ score }}分</text>
    </template>
  </ng-circle>
</template>

Props

Slots

• 默认插槽：圆心内容（默认显示百分比数字）

5.49 ng-textarea 多行输入

源码：ng-textarea.vue

用法

<template>
  <ng-textarea v-model="content" placeholder="请输入备注..." :rows="4" />
  <ng-textarea v-model="comment" :maxlength="200" show-word-limit auto-height />
</template>

Props

Events

• update:modelValue(val) / input(val)
• focus(e) / blur(e) / confirm(e)

5.50 ng-avatar 头像

源码：ng-avatar.vue

用法

<template>
  <ng-avatar src="https://example.com/avatar.png" />
  <ng-avatar server-src="user/1.png" size="96" />
  <ng-avatar text="张三" bg-color="primary" />
  <ng-avatar default-src="/static/default-avatar.png" src="/a.png" />
  <ng-avatar text="OK" shape="square" :round="12" />
</template>

图片地址优先使用 src；也可传 serverSrc，会复用全局 image.getServer 做路径拼接。无图或加载失败时先展示 defaultSrc，再回退到 text（中文取 1 字，英文取 2 字大写）。默认插槽可完全自定义内容。

全局默认图可在 main.js 通过 props.avatar.defaultSrc 配置：

app.use(NgUI, {
  props: {
    avatar: {
      defaultSrc: "/static/default-avatar.png",
    },
  },
});

Props

Events

• click：点击头像（未配置 path 时）
• load：图片加载成功
• error：图片加载失败

Slots

• 默认插槽：自定义头像内容（传入后不再渲染内置图片/文字）