组件使用约定

本文档说明 xtf-linkui 各组件的通用使用方式，包括 easycom 引入、双向绑定、样式覆盖、命令式 API 与表单集成。具体 API 以对应组件文档为准。

---

引入方式

得益于 uni-app 的 easycom 机制，将 xtf-linkui 放入 uni_modules/ 后，所有 xtf- 前缀组件无需手动 import 或注册，在模板中直接使用即可：

<template>
  <view>
    <xtf-button label="确定" theme="primary" />
    <xtf-switch v-model="checked" />
  </view>
</template>

如果需要在 <script> 中调用组件的方法或使用命令式 API，则从入口显式导入：

import { themeManager, toastManager } from '@/uni_modules/xtf-linkui'

---

双向绑定约定

组件库优先使用 Vue 3 的 v-model 语法。不同组件绑定的字段不同，常见三种：

绑定形式	典型组件	说明
v-model="value"	xtf-input、xtf-switch、xtf-rate、xtf-search	绑定值
v-model:show="visible"	xtf-popup、xtf-dialog、xtf-drawer、xtf-action-sheet	绑定显隐
v-model:checked="checked"	xtf-tag、xtf-checkbox、xtf-radio	绑定选中态

<template>
  <view>
    <!-- 值绑定 -->
    <xtf-input v-model="keyword" placeholder="请输入" />
    <!-- 显隐绑定 -->
    <xtf-popup v-model:show="showPopup" position="bottom">
      <view>弹层内容</view>
    </xtf-popup>
    <!-- 选中绑定 -->
    <xtf-tag v-model:checked="selected" text="筛选标签" checkable />
  </view>
</template>

<script>
export default {
  data() {
    return { keyword: '', showPopup: false, selected: true }
  }
}
</script>

同时，多数组件保留了对应的 change / confirm / select / update:xxx 事件，便于在值变化时做业务处理。

---

样式覆盖约定

组件通常提供两个通用样式属性，以及针对复杂组件的区域级样式属性。

通用属性

属性	类型	说明
customClass	String	追加自定义类名，用于批量样式覆盖
customStyle	String | Object	追加内联样式，用于精确/动态覆盖

<template>
  <xtf-button
    label="自定义"
    custom-class="my-button"
    :custom-style="{ borderRadius: '4rpx' }"
  />
</template>

区域级样式属性

xtf-popup、xtf-calendar、xtf-picker、xtf-action-sheet、xtf-dialog 等复杂组件会暴露 *Class / *Style 系列属性，用于控制内部区域（如遮罩、面板、内容区）。

建议：优先使用公开的样式属性覆盖，不直接覆盖组件内部选择器，以免升级后失效。

---

命令式 API

部分反馈类组件提供命令式调用（Manager），采用发布-订阅模式：Manager 维护全局状态，宿主组件负责渲染。

使用前提

命令式调用需要先挂载对应的宿主组件，并将其 service 属性设为 true。建议放在应用根节点（如 App.vue 的模板中无法直接使用，通常放在首页或公共页面）：

<template>
  <view>
    <xtf-toast service />
    <xtf-notify service />
    <xtf-dialog service />
    <xtf-loading service />
    <xtf-action-sheet service />
    <xtf-picker service />
  </view>
</template>

注：宿主组件的 service 模式会订阅对应的 Manager，自动渲染状态。若未挂载宿主组件，命令式调用不会产生视觉反馈。

各 Manager 常用方法

能力	导出	常用方法
Toast	toastManager	show(options) / success(message) / error(message) / warning(message) / loading(message) / clear() / update(options)
Dialog	dialogManager	alert(options) / confirm(options) / prompt(options) / textarea(options) / select(options) / actions(options) / multiSelect(options) / close()
Loading	loadingManager	show(options) / hide() / update(options)
Notify	notifyManager	show(options) / success(options) / warning(options) / danger(options) / info(options) / primary(options) / remove(id) / clear()
ActionSheet	actionSheetManager	show(options) / close() / update(options)
Picker	pickerManager	show(options) / popup(options) / close() / update(options)

Toast 示例

import { toastManager } from '@/uni_modules/xtf-linkui'

toastManager.success('操作成功')
toastManager.error('操作失败')

toastManager.show({
  message: '自定义提示',
  type: 'warning',
  position: 'top',      // center / top / bottom
  duration: 3000,
  styleType: 'light'    // solid / light / outline / glass
})

Dialog 示例

dialogManager.confirm 等返回当前状态快照，业务通过宿主组件的事件/回调处理结果：

import { dialogManager } from '@/uni_modules/xtf-linkui'

dialogManager.confirm({
  title: '确认删除？',
  message: '此操作不可撤销',
  confirmText: '删除',
  cancelText: '取消'
})

dialogManager.prompt({
  title: '请输入昵称',
  placeholder: '昵称'
})

dialogManager.select({
  title: '选择分类',
  options: [
    { label: '手机', value: 'phone' },
    { label: '电脑', value: 'pc' }
  ]
})

Loading 示例

import { loadingManager } from '@/uni_modules/xtf-linkui'

loadingManager.show({
  text: '加载中...',
  type: 'spinner',      // spinner / ring / orbit / pulse / bars / neon ...
  mode: 'fullscreen',   // fullscreen / inline
  overlay: true
})

// 业务完成后
loadingManager.hide()

Notify 示例

import { notifyManager } from '@/uni_modules/xtf-linkui'

notifyManager.success({ title: '保存成功', message: '数据已保存到本地' })
notifyManager.danger({ message: '网络异常，请重试', actionText: '重试', onAction: retry })

---

表单集成

组件库提供一套完整的表单体系，推荐组合使用：

• xtf-form — 表单容器，负责收集与校验
• xtf-form-item — 表单项，包裹单个控件并展示校验结果
• 各类输入组件 — xtf-input / xtf-select / xtf-picker / xtf-switch / xtf-rate / xtf-upload 等

<template>
  <xtf-form ref="formRef" :model="formData" :rules="rules">
    <xtf-form-item label="姓名" prop="name">
      <xtf-input v-model="formData.name" placeholder="请输入姓名" />
    </xtf-form-item>
    <xtf-form-item label="性别" prop="gender">
      <xtf-radio-group v-model="formData.gender">
        <xtf-radio :value="'male'" label="男" />
        <xtf-radio :value="'female'" label="女" />
      </xtf-radio-group>
    </xtf-form-item>
    <xtf-button form-type="submit" label="提交" />
  </xtf-form>
</template>

xtf-button 提供 form-type="submit" / form-type="reset"，可配合 xtf-form 触发提交/重置。

---

平台注意事项

• 不要对原生 input / textarea 设置 box-sizing: border-box，会影响原生组件布局
• 涉及滚动锁定、固定定位、触摸拖动和 CSS 毛玻璃（backdrop-filter）时，应在目标平台分别验证
• 组件库支持平台为 H5、App、微信小程序（见 package.json）