@zfqh/uniapp 0.1.1

package/docs/components/g-back-button.md

@@ -0,0 +1,76 @@
+# g-back-button 返回/首页按钮
+
+::: tip 组件名
+`g-back-button`
+
+发布路径：`@zfqh/uniapp/lib/components/g-back-button/g-back-button.vue`
+:::
+
+自定义返回/首页按钮，适合透明导航栏、沉浸式页面或小程序胶囊左侧区域。
+
+## 平台兼容性
+
+| App（vue） | App（nvue） | H5 | 小程序 | Vue 2 | Vue 3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | 依赖源码条件编译 | √ | √ | - | √ |
+
+## 使用前提
+
+- 已安装并注册 `@zfqh/uniapp` 插件。
+- 已按 [项目接入](./usage) 配置 easycom，或手动从构建产物导入组件。
+- 尺寸类属性通常支持数字或带单位字符串；数字值会在组件内部通过 `uni.$uv.addUnit` 转成样式单位。
+- 样式类属性中，`customStyle`、`xxxStyle` 接收对象，`customClass`、`xxxClass` 接收 class 字符串。
+
+## 基本使用
+
+```vue
+<template>
+  <view class="login-page">
+    <g-back-button :show-home="false" color="#333" />
+
+    <view class="login-card">手机号登录</view>
+  </view>
+</template>
+```
+
+## API
+
+### 返回/首页按钮 Props
+
+| 属性 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `showLine` | `Boolean` | `true` | 否 | 是否显示按钮或导航区域的分割线。 |
+| `showHome` | `Boolean` | `true` | 否 | 是否显示返回首页按钮。 |
+| `iconType` | `String` | `''` | 否 | 传给 g-icon 的图标类型，用于区分内置图标或图标库类型。 |
+| `iconFont` | `String` | `''` | 否 | 图标字体类名前缀或字体族配置。 |
+| `iconName` | `String` | `'arrow-left'` | 否 | 主图标名称。 |
+| `homeIconName` | `String` | `'home-fill'` | 否 | 首页图标名称。 |
+| `iconSize` | `[String, Number]` | `0` | 否 | 主图标尺寸，数字会按 uni.$uv.addUnit 转成 rpx/px。 |
+| `homeIconSize` | `[String, Number]` | `0` | 否 | 首页图标尺寸。 |
+| `fixed` | `Boolean` | `true` | 否 | 是否 fixed 定位。 |
+| `color` | `String` | `'#fff'` | 否 | 文字或图标主色。 |
+| `customStyle` | `Object` | `() => ({})` | 否 | 最外层自定义 style 对象。 |
+
+### 返回/首页按钮 Events
+
+无显式组件事件。
+
+### 返回/首页按钮 Slots
+
+无显式插槽。
+
+### 返回/首页按钮 Methods
+
+| 方法 | 说明 |
+| --- | --- |
+| `goBack()` | 执行返回上一页逻辑。 |
+| `goHome()` | 跳转到首页配置页。 |
+
+### 返回/首页按钮 Internal State
+
+| 类型 | 名称 | 说明 |
+| --- | --- | --- |
+| computed | `systemInfo` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |
+| computed | `_customStyle` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |
+| computed | `showIcon` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |
+| computed | `type` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |

package/docs/components/g-checkbox-list.md

@@ -0,0 +1,101 @@
+# g-checkbox-list 选择列表
+
+::: tip 组件名
+`g-checkbox-list`
+
+发布路径：`@zfqh/uniapp/lib/components/g-checkbox-list/g-checkbox-list.vue`
+:::
+
+轻量选择列表，支持单选/多选、禁用、重复点击取消和字段映射。
+
+## 平台兼容性
+
+| App（vue） | App（nvue） | H5 | 小程序 | Vue 2 | Vue 3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | 依赖源码条件编译 | √ | √ | - | √ |
+
+## 使用前提
+
+- 已安装并注册 `@zfqh/uniapp` 插件。
+- 已按 [项目接入](./usage) 配置 easycom，或手动从构建产物导入组件。
+- 尺寸类属性通常支持数字或带单位字符串；数字值会在组件内部通过 `uni.$uv.addUnit` 转成样式单位。
+- 样式类属性中，`customStyle`、`xxxStyle` 接收对象，`customClass`、`xxxClass` 接收 class 字符串。
+
+## 基本使用
+
+```vue
+<template>
+  <g-checkbox-list
+    v-model="selected"
+    :list="options"
+    multiple
+    label-field="name"
+    value-field="id"
+    :item-style="{ padding: '24rpx 0' }"
+    @change="onChange"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const selected = ref(['sleep']);
+const options = [
+  { id: 'sleep', name: '睡眠不佳' },
+  { id: 'appetite', name: '食欲下降' },
+  { id: 'cold', name: '畏寒怕冷' },
+];
+
+function onChange(value, checked) {
+  console.log(value, checked);
+}
+</script>
+```
+
+## API
+
+### 选择列表 Props
+
+| 属性 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `list` | `Array` | `() => []` | 否 | 数据列表。具体 item 字段由组件或字段映射 props 决定。 |
+| `customStyle` | `Object` | `() => ({})` | 否 | 最外层自定义 style 对象。 |
+| `itemStyle` | `Object` | `() => ({})` | 否 | 自定义 item 区域 style 对象。 |
+| `itemHeight` | `[String, Number]` | `32` | 否 | 组件公开属性 itemHeight，用于控制该组件对应的渲染、交互或业务参数。 |
+| `iconName` | `String` | `'checkmark'` | 否 | 主图标名称。 |
+| `fontSize` | `[String, Number]` | `14` | 否 | 字体大小。 |
+| `iconSize` | `[String, Number]` | `14` | 否 | 主图标尺寸，数字会按 uni.$uv.addUnit 转成 rpx/px。 |
+| `iconColor` | `String` | `() => color.primary` | 否 | icon 颜色。 |
+| `border` | `Boolean` | `true` | 否 | 是否显示边框。 |
+| `disabled` | `Boolean` | `false` | 否 | 是否禁用交互。 |
+| `multiple` | `Boolean` | `false` | 否 | 是否允许多选。 |
+| `toggle` | `Boolean` | `true` | 否 | 重复选择已选项时是否取消选择。 |
+| `labelField` | `String` | `'label'` | 否 | 列表项展示文本字段名。 |
+| `valueField` | `String` | `'value'` | 否 | 列表项取值字段名。 |
+
+### 选择列表 Events
+
+| 事件 | 说明 |
+| --- | --- |
+| `change` | 值或状态变化时触发。 |
+
+### 选择列表 Slots
+
+| 插槽 | 说明 |
+| --- | --- |
+| `default` | 默认内容区域。 |
+
+### 选择列表 Methods
+
+| 方法 | 说明 |
+| --- | --- |
+| `select(item)` | 处理选中/取消选中逻辑并触发 change。 |
+
+### 选择列表 Internal State
+
+| 类型 | 名称 | 说明 |
+| --- | --- | --- |
+| computed | `dataList` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |
+| computed | `icon` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |
+| computed | `style` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |
+| data | `checked` | 内部响应式状态，通常不建议由外部直接依赖。 |

package/docs/components/g-container.md

@@ -0,0 +1,93 @@
+# g-container 页面基础容器
+
+::: tip 组件名
+`g-container`
+
+发布路径：`@zfqh/uniapp/lib/components/g-container/g-container.vue`
+:::
+
+页面基础容器，统一处理背景、内容区、底部固定栏、安全区、加载态和 tabBar 底部间距。
+
+## 平台兼容性
+
+| App（vue） | App（nvue） | H5 | 小程序 | Vue 2 | Vue 3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | 依赖源码条件编译 | √ | √ | - | √ |
+
+## 使用前提
+
+- 已安装并注册 `@zfqh/uniapp` 插件。
+- 已按 [项目接入](./usage) 配置 easycom，或手动从构建产物导入组件。
+- 尺寸类属性通常支持数字或带单位字符串；数字值会在组件内部通过 `uni.$uv.addUnit` 转成样式单位。
+- 样式类属性中，`customStyle`、`xxxStyle` 接收对象，`customClass`、`xxxClass` 接收 class 字符串。
+
+## 基本使用
+
+```vue
+<template>
+  <g-container
+    has-navbar
+    show-footer
+    bg-color="#f7f8fa"
+    content-class="g-p-24"
+    :footer-style="{ padding: '20rpx 24rpx' }"
+  >
+    <view class="g-bg-fff g-radius-16 g-p-24">订单内容</view>
+
+    <template #footer>
+      <uv-button type="primary" shape="circle" text="提交订单" @click="submit" />
+    </template>
+  </g-container>
+</template>
+
+<script setup>
+function submit() {
+  uni.showToast({ title: '已提交', icon: 'success' });
+}
+</script>
+```
+
+## API
+
+### 页面基础容器 Props
+
+| 属性 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `loading` | `[String, Boolean]` | `false` | 否 | 外部加载状态；组件内部也可能通过 setLoading 控制。 |
+| `bgColor` | `String` | `() => color.bgColor` | 否 | 背景颜色。 |
+| `footerSafeArea` | `Boolean` | `true` | 否 | 底部是否追加安全区高度。 |
+| `showFooter` | `Boolean` | `false` | 否 | 是否显示底部区域。 |
+| `hasTabbar` | `Boolean` | `false` | 否 | 是否预留 tabBar 底部高度。 |
+| `footerBorder` | `Boolean` | `true` | 否 | 底部栏是否显示上边框。 |
+| `footerShadow` | `Boolean` | `false` | 否 | 底部栏是否显示阴影。 |
+| `customClass` | `String` | `''` | 否 | 最外层自定义 class。 |
+| `contentClass` | `String` | `''` | 否 | 自定义 content 区域 class。 |
+| `footerClass` | `String` | `''` | 否 | 自定义 footer 区域 class。 |
+| `customStyle` | `Object` | `() => ({})` | 否 | 最外层自定义 style 对象。 |
+| `contentStyle` | `Object` | `() => ({})` | 否 | 自定义 content 区域 style 对象。 |
+| `footerStyle` | `Object` | `() => ({})` | 否 | 自定义 footer 区域 style 对象。 |
+
+### 页面基础容器 Events
+
+无显式组件事件。
+
+### 页面基础容器 Slots
+
+| 插槽 | 说明 |
+| --- | --- |
+| `default` | 默认内容区域。 |
+| `footer` | 底部固定栏内容。 |
+
+### 页面基础容器 Methods
+
+| 方法 | 说明 |
+| --- | --- |
+| `setLoading(loading)` | 切换内部 loading 状态。 |
+
+### 页面基础容器 Internal State
+
+| 类型 | 名称 | 说明 |
+| --- | --- | --- |
+| computed | `systemInfo` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |
+| computed | `style` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |
+| computed | `_footerStyle` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |

package/docs/components/g-data-list.md

@@ -0,0 +1,106 @@
+# g-data-list 分页数据列表
+
+::: tip 组件名
+`g-data-list`
+
+发布路径：`@zfqh/uniapp/lib/components/g-data-list/g-data-list.vue`
+:::
+
+分页数据加载容器，把 request、page/pageSize、加载状态和 loadmore 插槽集中管理。
+
+## 平台兼容性
+
+| App（vue） | App（nvue） | H5 | 小程序 | Vue 2 | Vue 3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | 依赖源码条件编译 | √ | √ | - | √ |
+
+## 使用前提
+
+- 已安装并注册 `@zfqh/uniapp` 插件。
+- 已按 [项目接入](./usage) 配置 easycom，或手动从构建产物导入组件。
+- 尺寸类属性通常支持数字或带单位字符串；数字值会在组件内部通过 `uni.$uv.addUnit` 转成样式单位。
+- 样式类属性中，`customStyle`、`xxxStyle` 接收对象，`customClass`、`xxxClass` 接收 class 字符串。
+
+## 基本使用
+
+```vue
+<template>
+  <g-data-list ref="listRef" :request="queryGoods" :page-size="10" init-load loading>
+    <template #default="{ data }">
+      <view v-for="item in data" :key="item.id" class="goods-row">
+        <image :src="item.picUrl" class="cover" />
+        <view class="name">{{ item.name }}</view>
+      </view>
+    </template>
+
+    <template #empty>
+      <uv-empty text="暂无商品" mode="list" />
+    </template>
+  </g-data-list>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const listRef = ref(null);
+
+async function queryGoods({ page, pageSize }) {
+  const result = await goodsApi.page({ page, pageSize, keyword: '养生茶' });
+  return {
+    data: result.list,
+    total: result.total,
+  };
+}
+</script>
+```
+
+## API
+
+### 分页数据列表 Props
+
+| 属性 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `request` | `Function` | `() => {}` | 否 | 异步请求函数，通常返回包含 data/list/total 的接口响应。 |
+| `initLoad` | `Boolean` | `false` | 否 | 是否在 mounted 后立即发起首次加载。 |
+| `loading` | `Boolean` | `false` | 否 | 外部加载状态；组件内部也可能通过 setLoading 控制。 |
+| `loadingLine` | `Boolean` | `true` | 否 | 组件公开属性 loadingLine，用于控制该组件对应的渲染、交互或业务参数。 |
+| `loadingTop` | `[String, Number]` | `10` | 否 | 组件公开属性 loadingTop，用于控制该组件对应的渲染、交互或业务参数。 |
+| `loadingBottom` | `[String, Number]` | `0` | 否 | 组件公开属性 loadingBottom，用于控制该组件对应的渲染、交互或业务参数。 |
+| `customStyle` | `Object` | `() => ({})` | 否 | 最外层自定义 style 对象。 |
+| `pageSize` | `Number` | `12` | 否 | 分页大小。 |
+| `status` | `String` | `'nomore'` | 否 | 加载状态，常见值为 loadmore、loading、nomore。 |
+
+### 分页数据列表 Events
+
+无显式组件事件。
+
+### 分页数据列表 Slots
+
+| 插槽 | 说明 |
+| --- | --- |
+| `default` | 默认内容区域。 |
+| `empty` | 空数据内容。 |
+| `loadmore` | 分页加载状态内容。 |
+
+### 分页数据列表 Methods
+
+| 方法 | 说明 |
+| --- | --- |
+| `getParent()` | 组件内部公开方法 getParent()；通过 ref 调用前需要确认组件平台条件和当前状态。 |
+| `loadData(page = 0, pageSize = 0)` | 组件内部公开方法 loadData(page = 0, pageSize = 0)；通过 ref 调用前需要确认组件平台条件和当前状态。 |
+| `loadMore()` | 组件内部公开方法 loadMore()；通过 ref 调用前需要确认组件平台条件和当前状态。 |
+| `updateData()` | 刷新分页列表数据。 |
+| `initData()` | 组件内部公开方法 initData()；通过 ref 调用前需要确认组件平台条件和当前状态。 |
+
+### 分页数据列表 Internal State
+
+| 类型 | 名称 | 说明 |
+| --- | --- | --- |
+| computed | `loadingStyle` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |
+| data | `stat` | 内部响应式状态，通常不建议由外部直接依赖。 |
+| data | `page` | 内部响应式状态，通常不建议由外部直接依赖。 |
+| data | `total` | 内部响应式状态，通常不建议由外部直接依赖。 |
+| data | `data` | 内部响应式状态，通常不建议由外部直接依赖。 |
+| data | `rawData` | 内部响应式状态，通常不建议由外部直接依赖。 |
+| data | `showLoading` | 内部响应式状态，通常不建议由外部直接依赖。 |
+| data | `timer` | 内部响应式状态，通常不建议由外部直接依赖。 |

package/docs/components/g-dot-text.md

@@ -0,0 +1,79 @@
+# g-dot-text 点状文本
+
+::: tip 组件名
+`g-dot-text`
+
+发布路径：`@zfqh/uniapp/lib/components/g-dot-text/g-dot-text.vue`
+:::
+
+圆点加文本的状态展示组件，可用于标签、图例、提示项和行内说明。
+
+## 平台兼容性
+
+| App（vue） | App（nvue） | H5 | 小程序 | Vue 2 | Vue 3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | 依赖源码条件编译 | √ | √ | - | √ |
+
+## 使用前提
+
+- 已安装并注册 `@zfqh/uniapp` 插件。
+- 已按 [项目接入](./usage) 配置 easycom，或手动从构建产物导入组件。
+- 尺寸类属性通常支持数字或带单位字符串；数字值会在组件内部通过 `uni.$uv.addUnit` 转成样式单位。
+- 样式类属性中，`customStyle`、`xxxStyle` 接收对象，`customClass`、`xxxClass` 接收 class 字符串。
+
+## 基本使用
+
+```vue
+<template>
+  <g-dot-text color="var(--primary)" width="8rpx" height="32rpx" border-radius="0" :plain="false">
+    今日待办
+  </g-dot-text>
+</template>
+```
+
+## API
+
+### 点状文本 Props
+
+| 属性 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `type` | `String` | `-` | 否 | 组件公开属性 type，用于控制该组件对应的渲染、交互或业务参数。 |
+| `space` | `[String, Number]` | `6` | 否 | 组件公开属性 space，用于控制该组件对应的渲染、交互或业务参数。 |
+| `size` | `[String, Number]` | `6` | 否 | 组件尺寸。 |
+| `width` | `[String, Number]` | `0` | 否 | 宽度。 |
+| `height` | `[String, Number]` | `0` | 否 | 高度。 |
+| `fontSize` | `[String, Number]` | `13` | 否 | 字体大小。 |
+| `color` | `String` | `''` | 否 | 文字或图标主色。 |
+| `textColor` | `String` | `''` | 否 | text 颜色。 |
+| `borderRadius` | `[String, Number]` | `'50%'` | 否 | 圆角。 |
+| `top` | `[String, Number]` | `0` | 否 | 组件公开属性 top，用于控制该组件对应的渲染、交互或业务参数。 |
+| `plain` | `Boolean` | `false` | 否 | 组件公开属性 plain，用于控制该组件对应的渲染、交互或业务参数。 |
+| `show` | `Boolean` | `true` | 否 | 是否显示组件。 |
+| `customClass` | `String` | `-` | 否 | 最外层自定义 class。 |
+| `textClass` | `String` | `-` | 否 | 自定义 text 区域 class。 |
+| `textStyle` | `Object` | `() => ({})` | 否 | 自定义 text 区域 style 对象。 |
+| `customStyle` | `Object` | `() => ({})` | 否 | 最外层自定义 style 对象。 |
+| `dotStyle` | `Object` | `() => ({})` | 否 | 自定义 dot 区域 style 对象。 |
+| `align` | `String` | `'center'` | 否 | 组件公开属性 align，用于控制该组件对应的渲染、交互或业务参数。 |
+
+### 点状文本 Events
+
+无显式组件事件。
+
+### 点状文本 Slots
+
+| 插槽 | 说明 |
+| --- | --- |
+| `default` | 默认内容区域。 |
+
+### 点状文本 Methods
+
+无 Options API methods。
+
+### 点状文本 Internal State
+
+| 类型 | 名称 | 说明 |
+| --- | --- | --- |
+| computed | `_color` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |
+| computed | `_dotStyle` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |
+| computed | `txtStyle` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |

package/docs/components/g-env.md

@@ -0,0 +1,75 @@
+# g-env 环境显示
+
+::: tip 组件名
+`g-env`
+
+发布路径：`@zfqh/uniapp/lib/components/g-env/g-env.vue`
+:::
+
+环境切换入口，主要给 H5/Electron 调试环境使用，用于查看和切换当前 env。
+
+## 平台兼容性
+
+| App（vue） | App（nvue） | H5 | 小程序 | Vue 2 | Vue 3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | 依赖源码条件编译 | √ | √ | - | √ |
+
+## 使用前提
+
+- 已安装并注册 `@zfqh/uniapp` 插件。
+- 已按 [项目接入](./usage) 配置 easycom，或手动从构建产物导入组件。
+- 尺寸类属性通常支持数字或带单位字符串；数字值会在组件内部通过 `uni.$uv.addUnit` 转成样式单位。
+- 样式类属性中，`customStyle`、`xxxStyle` 接收对象，`customClass`、`xxxClass` 接收 class 字符串。
+
+## 基本使用
+
+```vue
+<template>
+  <view class="user-version">
+    当前环境
+    <g-env :env="env" prefix="（" suffix="）" />
+  </view>
+</template>
+
+<script setup>
+import { config } from '@zfqh/uniapp';
+
+const env = config.env;
+</script>
+```
+
+## API
+
+### 环境显示 Props
+
+| 属性 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `env` | `Object` | `() => ({})` | 否 | 组件公开属性 env，用于控制该组件对应的渲染、交互或业务参数。 |
+| `data` | `Array` | `() => [ { name: '开发环境', key: 'dev', }, { name: '测试环境', key: 'sit', }, { name: '演示环境', key: 'uat', }, { name: '预生产环境', key: 'pre', }, ]` | 否 | 组件渲染或业务计算使用的数据源。 |
+| `prefix` | `String` | `''` | 否 | 组件公开属性 prefix，用于控制该组件对应的渲染、交互或业务参数。 |
+| `suffix` | `String` | `''` | 否 | 组件公开属性 suffix，用于控制该组件对应的渲染、交互或业务参数。 |
+| `switchable` | `Boolean` | `true` | 否 | 组件公开属性 switchable，用于控制该组件对应的渲染、交互或业务参数。 |
+
+### 环境显示 Events
+
+无显式组件事件。
+
+### 环境显示 Slots
+
+| 插槽 | 说明 |
+| --- | --- |
+| `default` | 默认内容区域。 |
+
+### 环境显示 Methods
+
+| 方法 | 说明 |
+| --- | --- |
+| `open()` | 打开组件或弹层；部分组件支持传入选项覆盖当前展示内容。 |
+| `select(e)` | 处理选中/取消选中逻辑并触发 change。 |
+
+### 环境显示 Internal State
+
+| 类型 | 名称 | 说明 |
+| --- | --- | --- |
+| computed | `show` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |
+| computed | `list` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |

package/docs/components/g-float.md

@@ -0,0 +1,83 @@
+# g-float 悬浮入口
+
+::: tip 组件名
+`g-float`
+
+发布路径：`@zfqh/uniapp/lib/components/g-float/g-float.vue`
+:::
+
+悬浮操作按钮，滚动时可自动淡出，点击后可跳转或抛出 goto 事件。
+
+## 平台兼容性
+
+| App（vue） | App（nvue） | H5 | 小程序 | Vue 2 | Vue 3 |
+| --- | --- | --- | --- | --- | --- |
+| √ | 依赖源码条件编译 | √ | √ | - | √ |
+
+## 使用前提
+
+- 已安装并注册 `@zfqh/uniapp` 插件。
+- 已按 [项目接入](./usage) 配置 easycom，或手动从构建产物导入组件。
+- 尺寸类属性通常支持数字或带单位字符串；数字值会在组件内部通过 `uni.$uv.addUnit` 转成样式单位。
+- 样式类属性中，`customStyle`、`xxxStyle` 接收对象，`customClass`、`xxxClass` 接收 class 字符串。
+
+## 基本使用
+
+```vue
+<template>
+  <g-float has-tabbar :offset="[30, 10]" url="/pages/goods/shopCart/shopCart">
+    <view class="cart-badge">{{ cartCount }}</view>
+  </g-float>
+</template>
+
+<script setup>
+const cartCount = 3;
+</script>
+```
+
+## API
+
+### 悬浮入口 Props
+
+| 属性 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `size` | `[String, Number]` | `40` | 否 | 组件尺寸。 |
+| `show` | `[String, Number]` | `8` | 否 | 是否显示组件。 |
+| `offset` | `Array` | `() => [10]` | 否 | 组件公开属性 offset，用于控制该组件对应的渲染、交互或业务参数。 |
+| `hasTabbar` | `Boolean` | `false` | 否 | 是否预留 tabBar 底部高度。 |
+| `scrollTop` | `Number` | `0` | 否 | 组件公开属性 scrollTop，用于控制该组件对应的渲染、交互或业务参数。 |
+| `iconName` | `String` | `''` | 否 | 主图标名称。 |
+| `iconFont` | `String` | `''` | 否 | 图标字体类名前缀或字体族配置。 |
+| `iconSize` | `[String, Number]` | `20` | 否 | 主图标尺寸，数字会按 uni.$uv.addUnit 转成 rpx/px。 |
+| `customStyle` | `Object` | `() => ({})` | 否 | 最外层自定义 style 对象。 |
+| `iconColor` | `String` | `() => color.mainColor` | 否 | icon 颜色。 |
+| `bgColor` | `String` | `'#fff'` | 否 | 背景颜色。 |
+| `url` | `String` | `''` | 否 | 目标地址或图片地址，具体含义取决于组件。 |
+| `delay` | `Number` | `1000` | 否 | 组件公开属性 delay，用于控制该组件对应的渲染、交互或业务参数。 |
+| `opacity` | `Number` | `0.5` | 否 | 组件公开属性 opacity，用于控制该组件对应的渲染、交互或业务参数。 |
+
+### 悬浮入口 Events
+
+| 事件 | 说明 |
+| --- | --- |
+| `goto` | 悬浮按钮准备跳转或被点击时触发。 |
+
+### 悬浮入口 Slots
+
+| 插槽 | 说明 |
+| --- | --- |
+| `default` | 默认内容区域。 |
+
+### 悬浮入口 Methods
+
+| 方法 | 说明 |
+| --- | --- |
+| `scrolling()` | 组件内部公开方法 scrolling()；通过 ref 调用前需要确认组件平台条件和当前状态。 |
+| `click()` | 处理点击逻辑；可能触发跳转、自定义函数或对外事件。 |
+
+### 悬浮入口 Internal State
+
+| 类型 | 名称 | 说明 |
+| --- | --- | --- |
+| computed | `style` | 内部计算属性，用于把 props、平台信息或样式配置转换为模板可用值。 |
+| data | `isScroll` | 内部响应式状态，通常不建议由外部直接依赖。 |