Hooks 组合式函数

jzfw-ui 内置一组组合式函数（hooks），从统一入口 @/uni_modules/jzfw-ui 导出，涵盖反馈服务、组件引用、分页、字号、手势、层级、表单上下文、缓存与画布。

useUi — 全局反馈服务

见 [全局服务 useUi](/guide/。返回反馈服务单例，命令式唤起 toast / confirm / tips / loading。

const ui = useUi();
ui.showToast({ message: "已保存" } as JzToastOptions);

useRefs — 组件引用管理

集中管理模板 ref，便于命令式调用子组件暴露的方法（open / close 等）。内部用 Map 存储实例，仅做存取、不参与渲染。

const refs = useRefs();

方法	签名	说明
set	(name: string) => (el) => void	生成模板 ref 绑定函数
get	(name: string) => Instance	获取实例，不存在返回 null
callMethod	(name, method, data?: UTSJSONObject | null) => void	调用实例暴露的方法
open	(name, data?) => void	调用组件的 open 方法
close	(name) => void	调用组件的 close 方法

<jz-popup :ref="refs.set('popup')"></jz-popup>
<jz-button @click="refs.open('popup')">打开</jz-button>

usePager — 分页器

封装列表分页的加载 / 刷新 / 追加逻辑，回调由调用方发起真实请求，结果经 render 归一化写入 list。与 jz-list-view、jz-page 配合使用。

const pager = usePager((params, ctx) => {
  request(params).then((res) => ctx.render(res));
});

实例字段 / 方法：

成员	类型	说明
page / size / total	number	当前页 / 每页数量（默认 20）/ 总数
list	Ref<UTSJSONObject[]>	列表数据
loading	Ref<boolean>	加载状态
refreshing	Ref<boolean>	刷新状态
finished	Ref<boolean>	是否加载完成
params	UTSJSONObject	累积的请求参数
render(res)	(res: any) => void	渲染响应：第一页覆盖，其余追加，并更新分页信息
refresh(params)	(params) => Promise<void>	合并参数后发起请求
loadMore()	() => void	加载下一页（loading 或 finished 时忽略）
done()	() => void	结束加载态
clear()	() => void	清空数据与状态

render 期望的响应结构：{ list: UTSJSONObject[]; pagination: { page; size; total } }。

useSize — 字号缩放

读取全局 config.fontSize 缩放系数，对组件默认字号做缩放。

方法	说明
getScale()	获取全局字号缩放系数，未配置时为 1
toScale(val)	按全局系数缩放字号 = getScale() * val

const sz = useSize();
const finalSize = sz.toScale(14);

useTouch — 手势判定

提供横向 / 纵向滑动判定，横向滑动时阻止默认行为以防页面滚动。

方法	说明
start(e: UniTouchEvent)	记录起始坐标，重置横向标记
move(e: UniTouchEvent)	判定方向；横向时 preventDefault()
end()	重置状态

useLongPress — 长按连续触发

按下立即执行一次，超过延迟后按固定间隔重复执行，松手停止。供 jz-input-number 加减按钮长按连续增减使用。

const lp = useLongPress(300, 100); // delay, step
lp.start(() => { /* 增减 */ });
lp.stop();

useZIndex — 弹层层级分配

每次调用返回当前 config.zIndex 基数并自增，保证后打开的弹层始终在上层。

const z = useZIndex(); // 例如 600，随后 config.zIndex 变为 601

useParent — 父组件查找

沿组件实例的 $parent 链向上查找指定名称的父组件，供跨层级通信（如 jz-col 查找 jz-row 读取 gutter）。

const row = useParent<JzRowComponentPublicInstance>("jz-row");

表单上下文

输入组件用它们读取所属表单 / 表单项的状态：

函数	说明
useForm()	获取所属 jz-form 实例，不在表单内返回 null
useFormItem()	获取所属 jz-form-item 实例，不在表单项内返回 null
useFormDisabled()	ComputedRef<boolean>，表单禁用态，脱离表单恒为 false
useFormItemError()	ComputedRef<boolean>，所属字段是否校验错误

useCache — 缓存刷新键

组件内联 style 由 TS 计算，主题或 props 变化后需强制重渲染，通过递增 :key 触发。返回 { cache: { key: number } }，key 随传入的数据源或 isDark 变化自增（仅当仍在创建时的页面）。

const { cache } = useCache(() => [props.value, props.color]);
// 模板：<view :key="cache.key" :style="computedStyle"></view>

useCanvas — 画布

配合 jz-canvas 组件的绘制能力（文本 / 图片 / 矩形 / 变换 / 导出）。相关绘制参数类型见 公共类型 · Canvas 绘制。