@xiao-ying/miniapp-ui-pro

面向业务的 UI 组件库，基于 @xiao-ying/miniapp-ui，用于承载更高阶的业务组件与业务场景组件。

注意：本包不再 re-export 基础组件，请直接从 @xiao-ying/miniapp-ui 引入。

安装

pnpm add @xiao-ying/miniapp-ui-pro @xiao-ying/miniapp-ui

使用

基础组件请从 @xiao-ying/miniapp-ui 引入：

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

业务组件（如有）从 @xiao-ying/miniapp-ui-pro 引入：

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

例如悬浮 CTA 横幅：

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

<FloatingActionBanner
  title="闲置想快出？进群发布更高效"
  subtitle="群内实时推送，校友秒看，快速成交"
  buttonText="👉 进群发布"
  onButtonPress={() => {
    // open group link
  }}
/>

例如通用头像、Markdown 与图片能力：

import {
  Avatar,
  ImagePickerField,
  ImagePreviewGroup,
  MarkdownView
} from '@xiao-ying/miniapp-ui-pro'

<Avatar name="小应同学" src={profile.avatarUrl} />

<MarkdownView markdown={noticeContent} />

<ImagePickerField
  title="上传图片"
  value={images}
  onChange={setImages}
  uploadImage={(filePath) => uploadImage(filePath)}
/>

<ImagePreviewGroup images={images} layout="grid" />

颜色使用约定

miniapp-ui-pro 与业务代码应统一使用 @xiao-ying/miniapp-ui 提供的颜色 alias，不直接写 CSS 变量。

• 推荐文本类： text-on-surface、text-on-surface-variant、text-primary、text-error、text-warning、text-success
• 推荐背景类： bg-surface、bg-surface-container-high、bg-primary-container、bg-error-container、bg-warning-container、bg-success-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)]

错误、警告、成功等业务状态优先使用 error、warning、success 语义色；不要新增 danger / info 项目别名。NoticeCallout、ImagePickerGrid、DraftRestoreBanner 等组件已按这些语义色适配。

业务语义色

miniapp-ui-pro 额外提供少量跨业务小程序共用的业务语义色。它们不由宿主 themeSeedColor 生成，避免价格、性别、热度等业务重点信息随主题色漂移。

• 价格/金额/预算/赏金文本：使用 text-price
• 价格强调背景：使用 bg-price-container text-on-price-container
• 价格描边或图标：使用 border-price / text-price
• 男性/女性图标：使用 text-gender-male / text-gender-female
• 性别强调背景：使用 bg-gender-male-container text-on-gender-male-container 或 bg-gender-female-container text-on-gender-female-container
• 热度、浏览量、热榜等人气信息：使用 text-heat
• 热度强调背景：使用 bg-heat-container text-on-heat-container
• 热度描边或图标：使用 border-heat / text-heat

可用 Tailwind color alias：

• price
• on-price
• price-container
• on-price-container
• gender-male
• on-gender-male
• gender-male-container
• on-gender-male-container
• gender-female
• on-gender-female
• gender-female-container
• on-gender-female-container
• heat
• on-heat
• heat-container
• on-heat-container

对应 CSS 变量：

• --xy-pro-price
• --xy-pro-on-price
• --xy-pro-price-container
• --xy-pro-on-price-container
• --xy-pro-gender-male
• --xy-pro-on-gender-male
• --xy-pro-gender-male-container
• --xy-pro-on-gender-male-container
• --xy-pro-gender-female
• --xy-pro-on-gender-female
• --xy-pro-gender-female-container
• --xy-pro-on-gender-female-container
• --xy-pro-heat
• --xy-pro-on-heat
• --xy-pro-heat-container
• --xy-pro-on-heat-container

业务小程序开发时，凡是表达商品价格、预算、赏金、费用、金额核对总额等“钱”的重点信息，都优先使用 text-price，不要复用 text-primary / text-tertiary。 展示性别 icon 时优先使用 text-gender-male / text-gender-female，未知或未设置性别继续使用 text-on-surface-variant。 展示浏览数、热度、热门榜、火热程度等人气信息时优先使用 text-heat 或 bg-heat-container text-on-heat-container，不要把它们映射成 warning / error。

组件清单

• InfiniteScroll / InfiniteMasonry / CachedCoverImage：列表与瀑布流辅助。
• Avatar：圆角矩形头像，支持图片与名称 fallback。
• MarkdownView：基于 Tailwind CSS Typography 的 Material 3 风格 Markdown 渲染，默认启用 GFM，并随 data-theme="dark" 自动适配暗色模式。
• ImagePickerGrid：图片选择网格，支持可选移动端长按排序。
• ImagePickerField：带标题、辅助文案与默认压缩策略的图片选择表单区块。
• ImagePreviewGroup：图片预览组，基于 react-photo-view，多图默认支持左右切换。
• SchoolGateOverlay / SchoolSelectPage 已废弃：请改用 @xiao-ying/miniapp-xy-kit 的 createXyKit({ apiClient }).useSchoolGate，由 xy-kit 统一处理门禁 Dialog、选校 Sheet 与小应后端学校列表请求。
• FullScreenLoading / LoadingState / NoMoreMessage：加载与空态提示。
• InfoBanner / FloatingActionBanner / NoticeCallout / FeatureEntryCard / MetricsSummary / SectionHeader / PageHeader：信息展示组件。
• EmptyState / ErrorPage / NotFoundPage：错误与空状态。
• ErrorState 已废弃：请改用 NoticeCallout，并设置 tone="error"。
• PullToRefresh：下拉刷新交互。
• DraftRestoreBanner / DraftSaveHint / useFormDraft / saveDraft / loadDraft / clearDraft：草稿提示与持久化。

MarkdownView 默认输出 prose prose-xy 容器，size 支持 sm / base / lg / xl / 2xl。业务页面需要微调时，优先通过 className 传入 prose-* 元素修饰符；确需替换节点渲染时，可继续传入 components。

Tailwind 配置

miniapp-ui-pro 的插件输出业务语义色 token、Tailwind color alias，并注册 Tailwind CSS Typography 的 prose / prose-xy 样式。你仍需先加载 @xiao-ying/miniapp-ui 的插件来提供基础的 Material 3 tokens 与工具类，再追加 miniapp-ui-pro 插件。

• Tailwind v4（CSS-first）：

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

• Tailwind v3+（配置文件）：

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