hoson-ui

Hoson 统一 UI 组件库，基于 shadcn/ui + TanStack Table 的二次封装。

安装

# 配置 GitLab npm registry（一次性）
echo "@hoson:registry=https://git.hoson.com/api/v4/packages/npm/" >> .npmrc

# 安装
pnpm add hoson-ui

使用

import { Button, DataTable, DataTableColumnHeader, cn } from "hoson-ui"

DataTable 示例

import { DataTable, DataTableColumnHeader } from "hoson-ui"
import type { ColumnDef } from "@tanstack/react-table"

interface Product {
  id: string
  name: string
  price: number
  status: "draft" | "published"
}

const columns: ColumnDef<Product>[] = [
  {
    accessorKey: "name",
    header: ({ column }) => <DataTableColumnHeader column={column} title="产品" />,
  },
  {
    accessorKey: "price",
    header: ({ column }) => <DataTableColumnHeader column={column} title="价格" />,
  },
]

export function ProductTable({ data }: { data: Product[] }) {
  return (
    <DataTable
      columns={columns}
      data={data}
      searchableColumns={[{ id: "name", placeholder: "搜索产品..." }]}
    />
  )
}

Peer Dependencies

使用前需确保项目中已安装：

• react >= 18
• react-dom >= 18
• tailwind-merge >= 2
• lucide-react >= 0.400
• @tanstack/react-table >= 8（使用 DataTable 时）

Tailwind CSS 配置

在消费项目的 Tailwind 配置中包含组件库的路径：

// tailwind.config.ts 或 CSS 中
@source "../node_modules/hoson-ui/dist";

包含组件

基础 UI

Button, Badge, Input, Label, Card, Dialog, DropdownMenu, Select, Checkbox, Table, Skeleton, Tooltip, Popover, Command, Sheet, Separator, Breadcrumb, Avatar, Sidebar...

业务组件

• DataTable - 统一表格（排序/筛选/分页/行选择/空状态/加载态）
• DataTableColumnHeader - 可排序列头
• DataTablePagination - 分页控制
• DataTableToolbar - 工具栏（搜索/筛选/列显隐）
• DataTableFacetedFilter - 分面筛选
• DataTableViewOptions - 列显隐切换
• SearchFilterForm - 通用搜索筛选表单，适用于后台列表页查询区
• DynamicForm - 通用录入型表单，支持 input / select / textarea
• Form / FormField / FormMessage - react-hook-form 桥接组件
• ImageUpload - 通用图片上传交互组件，适合自定义上传逻辑
• CosImageUpload - 内置腾讯云 COS 上传逻辑，支持直接传接口地址或自定义临时密钥获取函数

表单组件说明

如果你要使用 DynamicForm 或 Form 系列组件，请确保消费项目已安装：

• react-hook-form >= 7

如果你要使用 CosImageUpload，hoson-ui 已内置 cos-js-sdk-v5，业务项目只需要提供获取临时密钥的配置即可。

CosImageUpload 示例

import {
  CosImageUpload,
  normalizeCosStsCredentials,
  type CosCredentialsConfig,
} from 'hoson-ui'

const credentialsConfig: CosCredentialsConfig = {
  cacheKey: 'merchant-admin',
  async getCredentials(module?: string) {
    const response = await fetch(
      `/api/upload/cos-sts?prefix=${encodeURIComponent(module ?? '')}`,
      { method: 'POST' }
    )

    if (!response.ok) {
      throw new Error('获取 COS 临时密钥失败')
    }

    return normalizeCosStsCredentials(await response.json())
  },
}

export function MerchantLogoUpload() {
  return (
    <CosImageUpload
      module='merchant/logo'
      maxCount={1}
      credentialsConfig={credentialsConfig}
      onValueChange={(urls) => console.log(urls)}
    />
  )
}

如果你希望业务代码里不再重复传 credentialsConfig，建议在项目内再封一层统一的 ImageUpload 包装组件，只在这一层注入项目级配置。

DynamicForm 示例

import { DynamicForm, type DynamicFormFieldConfig } from 'hoson-ui'
import { useForm } from 'react-hook-form'

interface MerchantFormValues {
  companyName: string
  accountStatus: string
}

const fields: DynamicFormFieldConfig<MerchantFormValues>[] = [
  {
    name: 'companyName',
    label: '公司名称',
    placeholder: '请输入公司名称',
    required: true,
  },
  {
    name: 'accountStatus',
    label: '账号状态',
    placeholder: '请选择账号状态',
    kind: 'select',
    options: [
      { label: '激活', value: 'ACTIVE' },
      { label: '禁用', value: 'DISABLED' },
    ],
  },
]

const form = useForm<MerchantFormValues>({
  defaultValues: {
    companyName: '',
    accountStatus: 'ACTIVE',
  },
})

export function MerchantDialogForm() {
  return <DynamicForm form={form} fields={fields} onSubmit={console.log} />
}

开发

pnpm install
pnpm dev    # 监听模式构建
pnpm build  # 生产构建