@xiao-ying/miniapp-ui

面向 XiaoYing miniapp 的 React UI 组件库，遵循 Material 3 设计语言，并提供 Tailwind CSS 插件支持。组件与 @xiao-ying/miniapp-sdk、@xiao-ying/miniapp-hooks 打通，可自动获取宿主亮度、震动等能力。

安装

pnpm add @xiao-ying/miniapp-ui

Tailwind 配置

请添加插件并扫描本包，以确保组件使用到的工具类被正确输出。

• Tailwind v4（CSS-first）：

  /* e.g. src/index.css */
  @import "tailwindcss";
  @source "./src/**/*.{ts,tsx}", "./node_modules/@xiao-ying/miniapp-ui/**/*.{js,ts,tsx}";
  @plugin "@xiao-ying/miniapp-ui/tailwind-plugin";

• Tailwind v3+（配置文件）：

  // tailwind.config.ts
  import { xyMaterial3Plugin } from '@xiao-ying/miniapp-ui/tailwind-plugin'
  
  export default {
    content: ['./index.html', './src/**/*.{ts,tsx}', './node_modules/@xiao-ying/miniapp-ui/**/*.{js,ts,tsx}'],
    plugins: [xyMaterial3Plugin()]
  }

插件默认会在 :root 注入浅色变量、在 [data-theme="dark"] 注入深色变量。插件还会提供 Material 3 的颜色语义、圆角、海拔阴影等 CSS 变量，并映射 Tailwind 的颜色/圆角/阴影别名（例如 text-error、bg-surface、rounded-md、shadow-lg）到对应的 M3 语义。

颜色别名与使用规范

请优先使用 text-* / bg-* / border-* 颜色别名，不要在 className 中直接写 var(...)。

• 推荐文本类： text-on-surface、text-on-surface-variant、text-primary、text-error
• 推荐背景类： bg-surface、bg-surface-container、bg-surface-container-high、bg-primary-container
• 推荐边框类： border-outline、border-outline-variant、border-border、border-border-strong
• 禁止写法： text-[var(--xy-m3-on-surface-variant)]、bg-[var(--xy-m3-surface-container-high)]、border-[var(--xy-m3-outline-variant)]

主题与变量

你可以在自己的 index.css 中覆盖变量来自定义配色与圆角：

:root {
  --xy-m3-primary: #2f5cf3;
  --xy-m3-on-primary: #ffffff;
  /* ...其他 Material 3 tokens... */
  --xy-radius-md: 14px;
}

[data-theme="dark"] {
  --xy-m3-primary: #b7c5ff;
  --xy-m3-on-primary: #0a225f;
  /* ...dark tokens... */
}

Tailwind 插件会生成 shadow-xy-*、rounded-xy-* 等工具类并读取这些变量。若需完全手动控制，可使用 xyMaterial3Plugin({ emitBase: false }) 关闭默认注入。

按钮与震动反馈

import { Button, IconButton } from '@xiao-ying/miniapp-ui'

// onPressed 为 undefined/null 时视为禁用（Flutter 风格）
<Button variant="filled" tone="primary" onPressed={() => xy.showToast({ title: 'Clicked' })}>
  触发操作
</Button>

// IconButton 示例，支持自定义 tone 与 className
<IconButton
  variant="tonal"
  tone="secondary"
  className="shadow-xy-2"
  onPressed={() => xy.vibrate({ impact: 'medium' })}
>
  <SomeIcon />
</IconButton>

Button 与 IconButton 默认会在点击时调用 xy.vibrate（可通过 vibrateImpact 指定具体 XYVibrateImpact 或传入 false 禁用）。

Tooltip

import { Tooltip, IconButton } from '@xiao-ying/miniapp-ui'
import { IconInfoCircle } from '@tabler/icons-react'

<Tooltip content="这是一个提示">
  <IconButton onPressed={() => {}}>
    <IconInfoCircle />
  </IconButton>
</Tooltip>

Surface 与卡片

import { Card, Surface } from '@xiao-ying/miniapp-ui'

<Card title="存储状态" subtitle="Miniapp storage powered by xy">
  <p className="text-sm text-on-surface-variant">将内容放在这里。</p>
</Card>

<Surface tone="container-high" elevation="level2" className="p-6">
  <p>自定义外壳与内容区域</p>
</Surface>

TextArea 自动高度

import { TextArea } from '@xiao-ying/miniapp-ui'

<TextArea
  label="描述"
  value={content}
  onValueChange={setContent}
  rows={2}      // autoHeight=true 时表示最小行数
  autoHeight    // 默认 false
  maxRows={8}   // 可选：达到 8 行后内部滚动
/>

• autoHeight 默认关闭，不影响现有固定高度行为。
• rows 在 autoHeight=false 时仍是固定行数；在 autoHeight=true 时为最小行数。
• maxRows 仅在 autoHeight=true 生效，不传表示不限制增长。

Tabs 与选择控件

import { Tabs, SegmentedButton, Slider } from '@xiao-ying/miniapp-ui'

<Tabs
  items={[
    { label: '概览', value: 'overview' },
    { label: '媒体', value: 'media' },
    { label: '存储', value: 'storage' }
  ]}
  value={tab}
  onValueChange={setTab}
/>

<SegmentedButton
  items={[
    { label: '全部', value: 'all' },
    { label: '进行中', value: 'active' },
    { label: '已完成', value: 'done' }
  ]}
  value={filter}
  onValueChange={setFilter}
  fullWidth
/>

<Slider label="音量" value={volume} onValueChange={setVolume} />

Divider

import { Divider } from '@xiao-ying/miniapp-ui'

<Divider />
<Divider>OR</Divider>
<Divider inset />

工具与组件清单

• xyMaterial3Plugin（默认导出）：Tailwind 插件，输出 Material 3 tokens、圆角、海拔阴影和颜色变量（默认注入，可 emitBase: false 关闭）。
• defaultMaterial3Theme / schemeToCssVars / shapeToCssVars / xyElevations / defaultStateOpacity：主题与变量工具。
• cn：基于 clsx + tailwind-merge 的 className 合并工具。
• Button / IconButton / FloatingActionButton：按钮与悬浮按钮。
• Surface / Card / Scaffold：容器与结构组件。
• TextField / TextArea / Select / Checkbox / Radio / Switch / Slider / SegmentedButton：表单与输入控件。
• Tabs / ListTile / BottomNavigationBar / NavBadge / Badge / Divider：导航与展示组件。
• LinearProgress / CircularProgress：进度指示。
• Tooltip：悬浮提示，默认使用 portal 置于最顶层。
• SafeArea：安全区内边距封装（CSS 变量 + env() 回退）。
• useHapticFeedback（别名 useHapticPress）：对 xy.vibrate 的通用封装。