快速上手

本页用一个完整示例串起 jzfw-ui 的常见用法：页面基座、按钮、表单、反馈服务、主题切换与多语言。

最小页面

<template>
  <jz-page>
    <view class="p-3">
      <jz-text :value="t('你好，jzfw-ui')" :size="18" :bold="true"></jz-text>
      <jz-button type="primary" class="mt-3" @click="onTap">{{ t('点我') }}</jz-button>
    </view>
  </jz-page>
</template>

<script setup lang="uts">
  import { t, useUi } from "@/uni_modules/jzfw-ui";
  import type { JzToastOptions } from "@/uni_modules/jzfw-ui/types/index.uts";

  const ui = useUi();

  function onTap() {
    ui.showToast({ message: t("操作成功") } as JzToastOptions);
  }
</script>

要点：

1. <jz-page> 作为根节点，自动提供主题背景与滚动容器，并挂载反馈服务。
2. 组件无需 import（easycom 自动注册）。
3. 运行时能力（t、useUi）从 @/uni_modules/jzfw-ui import。
4. useUi() 是命令式反馈入口，可弹 toast / confirm / loading。

v-model 双向绑定

表单类组件普遍支持 v-model（内部即 modelValue + update:modelValue）：

<template>
  <jz-page>
    <view class="p-3">
      <jz-input v-model="name" :placeholder="t('请输入昵称')"></jz-input>
      <jz-switch v-model="enabled" class="mt-3"></jz-switch>
      <jz-slider v-model="score" :min="0" :max="100" class="mt-3"></jz-slider>
      <jz-text class="mt-3" :value="`name=${name}, enabled=${enabled}, score=${score}`"></jz-text>
    </view>
  </jz-page>
</template>

<script setup lang="uts">
  import { ref } from "vue";
  import { t } from "@/uni_modules/jzfw-ui";

  const name = ref<string>("");
  const enabled = ref<boolean>(false);
  const score = ref<number>(30);
</script>

表单与校验

<template>
  <jz-page>
    <view class="p-3">
      <jz-form :ref="refs.set('form')" v-model="form" :rules="rules">
        <jz-form-item :label="t('手机号')" prop="phone">
          <jz-input v-model="form.phone" type="number" :maxlength="11"></jz-input>
        </jz-form-item>
        <jz-form-item :label="t('密码')" prop="password">
          <jz-input v-model="form.password" :password="true"></jz-input>
        </jz-form-item>
      </jz-form>

      <jz-button type="primary" class="mt-3" @click="submit">{{ t('提交') }}</jz-button>
    </view>
  </jz-page>
</template>

<script setup lang="uts">
  import { ref, reactive } from "vue";
  import { useRefs, t } from "@/uni_modules/jzfw-ui";
  import type { JzFormRule } from "@/uni_modules/jzfw-ui/types/index.uts";

  const refs = useRefs();

  type LoginForm = { phone: string; password: string };

  const form = reactive<LoginForm>({ phone: "", password: "" });

  const rules = new Map<string, JzFormRule[]>();
  rules.set("phone", [{ required: true, message: t("请输入手机号") } as JzFormRule]);
  rules.set("password", [{ required: true, min: 6, max: 20 } as JzFormRule]);

  function submit() {
    // 调用 jz-form 暴露的 validate 方法
    refs.callMethod("form", "validate");
  }
</script>

命令式调用组件方法

对弹窗、选择器、键盘等组件，用 useRefs() 管理引用并命令式调用 open / close：

<template>
  <jz-page>
    <jz-button @click="refs.open('popup')">{{ t('打开弹层') }}</jz-button>
    <jz-popup :ref="refs.set('popup')" direction="bottom" :title="t('标题')">
      <view class="p-4"><jz-text value="弹层内容"></jz-text></view>
    </jz-popup>
  </jz-page>
</template>

<script setup lang="uts">
  import { useRefs, t } from "@/uni_modules/jzfw-ui";
  const refs = useRefs();
</script>

refs.open(name) / refs.close(name) 会调用对应组件暴露的 open / close 方法；也可用 refs.callMethod(name, method, data) 调用任意暴露方法。

主题与语言

import { setTheme, toggleTheme, isDark, setLocale, t } from "@/uni_modules/jzfw-ui";

toggleTheme();          // 明暗切换
setTheme("dark");       // 指定主题
console.log(isDark.value);

setLocale("en");        // 切换语言
t("暂无数据");           // 英文环境返回 "No data available"

详见 [主题系统](/guide/ 与 [多语言](/guide/。

下一步

• 浏览 基础组件
• 了解 [透传 API](/guide/ 深度定制样式