@ithinkdt/ui

@ithinkdt/ui

许可证

MIT

安装

npm i @ithinkdt/ui

需要您自行安装 peer 依赖 vue@>=3.5、vue-router@>=4.5 与 ithinkdt-ui@>=1.5。如果使用页面渲染适配能力，需要安装 @ithinkdt/page@>=4.0；如果使用 UnoCSS 预设，需要安装 unocss@>=66。

介绍

@ithinkdt/ui 提供 iThinkDT 应用 UI 层的组件、指令与渲染适配能力，包括：

• 应用布局、侧栏、菜单、面包屑、页签、通知、租户、账号、语言、外观切换组件
• 数据表单、查询筛选、数据表格、分页、批量选择、列自定义、详情描述组件
• 单选、多选、人员/部门选择、国际化输入、状态按钮等业务组件
• v-spin、v-tooltip 指令
• 与 @ithinkdt/page 对接的表单项、详情、模态框渲染器
• UnoCSS 主题色、圆角、快捷类与命名空间隔离预设
• 自动导入配置

初始化

注册 UI 上下文与指令 Provider

UIProvider 用于注入 UI 文案国际化能力；SpinDirectiveProvider 与 TooltipDirectiveProvider 用于挂载 v-spin、v-tooltip 所需的全局样式与浮层。

import { createApp } from 'vue'
import {
    SpinDirectiveProvider,
    TooltipDirectiveProvider,
    UIProvider,
    vSpin,
    vTooltip,
} from '@ithinkdt/ui'

import App from './App.vue'

const app = createApp({
    setup() {
        return () => (
            <UIProvider>
                <SpinDirectiveProvider />
                <TooltipDirectiveProvider />
                <App />
            </UIProvider>
        )
    },
})

app.directive('spin', vSpin)
app.directive('tooltip', vTooltip)
app.mount('#app')

如果项目已经使用 @ithinkdt/vite 的自动导入能力，可以直接使用 @ithinkdt/ui/auto-imports。

import ImportsUI, { UIComponents, UIDirectives } from '@ithinkdt/ui/auto-imports'

export default {
    plugins: [
        presets({
            components: {
                resolvers: [
                    ...UIComponents,
                    ...UIDirectives,
                ],
            },
            autoImport: {
                imports: [
                    ...ImportsUI,
                ],
            },
        }),
    ],
}

UnoCSS 预设

import ithinkdt from '@ithinkdt/ui/unocss'
import { defineConfig } from 'unocss'

export default defineConfig({
    presets: [
        ithinkdt(),
    ],
})

开启命名空间隔离时，UnoCSS 变量和选择器会被限定在指定容器内：

export default defineConfig({
    presets: [
        ithinkdt({ namespace: 'my-app' }),
    ],
})

应用布局

基础布局

import {
    AppAccount,
    AppContent,
    AppHeader,
    AppLayout,
    AppLogo,
    AppMenu,
    AppSidebar,
} from '@ithinkdt/ui'

const menus = [
    {
        type: 'view',
        key: 'home',
        name: '首页',
        path: '/',
    },
    {
        type: 'group',
        key: 'system',
        name: '系统管理',
        children: [
            { type: 'view', key: 'user', name: '用户管理', path: '/users' },
            { type: 'view', key: 'role', name: '角色管理', path: '/roles' },
        ],
    },
]

export default {
    setup() {
        const collapsed = ref(false)

        return () => (
            <AppLayout layout="left2right">
                <AppSidebar v-model:collapsed={collapsed.value}>
                    <AppLogo name="管理后台" collapsed={collapsed.value} />
                    <AppMenu menus={menus} current="home" collapsed={collapsed.value} />
                </AppSidebar>
                <AppLayout>
                    <AppHeader>
                        <AppAccount
                            username="zhangsan"
                            nickname="张三"
                            onLogout={() => console.log('logout')}
                        />
                    </AppHeader>
                    <AppContent>
                        <RouterView />
                    </AppContent>
                </AppLayout>
            </AppLayout>
        )
    },
}

常用应用组件

数据组件

数据组件需要从 @ithinkdt/ui/components 导入。

数据表单

DataForm 负责渲染 @ithinkdt/page 的表单项定义。

import { DataForm } from '@ithinkdt/ui/components'
import { useFormHelper } from '@ithinkdt/page'

export default {
    setup() {
        const { model, items, validate, reset } = useFormHelper(
            ({ it }) => [
                it('name', '姓名', 'input', { required: true }),
                it('age', '年龄', 'number'),
                it('status', '状态', 'select', {
                    selectProps: {
                        options: [
                            { label: '启用', value: '1' },
                            { label: '禁用', value: '0' },
                        ],
                    },
                }),
            ],
            { initial: { name: '', status: '1' } },
        )

        async function submit() {
            const [valid] = await validate()
            if (valid) {
                console.log(model)
            }
        }

        return () => (
            <DataForm
                model={model}
                items={items}
                grid={{ cols: 12 }}
                showColon
                onSubmit={submit}
                onReset={reset}
            />
        )
    },
}

查询筛选

import { DataFilter } from '@ithinkdt/ui/components'
import { useFilterHelper } from '@ithinkdt/page'

const { model, items, reset } = useFilterHelper(({ it }) => [
    it('keyword', '关键字', 'input'),
    it('status', '状态', 'select', {
        selectProps: {
            options: statusOptions,
        },
    }),
])

return () => (
    <DataFilter
        model={model}
        items={items}
        collapsible
        onFilter={(filter) => ds.pull({ currentPage: 1 }, filter)}
        onReset={reset}
    />
)

数据表格与分页

import { DataPagination, DataTable } from '@ithinkdt/ui/components'
import { useDs, useTableHelper } from '@ithinkdt/page'

const ds = useDs(userApi.page, { pagination: 'remote' })

const { columns } = useTableHelper(({ col }) => [
    col('name', '姓名', { width: 140 }),
    col('email', '邮箱', { width: 220 }),
    col('status', '状态', 'dict', {
        dictParams: {
            options: [
                { label: '启用', value: '1' },
                { label: '禁用', value: '0' },
            ],
        },
    }),
])

return () => (
    <>
        <DataTable
            data={ds.data}
            columns={columns.value}
            sorter={ds.sorter}
            selectedKeys={selectedKeys.value}
            onSort={ds.sort}
            onSelect={(keys) => selectedKeys.value = keys}
        />
        <DataPagination
            page={ds.page}
            total={ds.total}
            onChange={ds.pull}
        />
    </>
)

其他数据组件

与 @ithinkdt/page 集成

@ithinkdt/ui/page 提供 @ithinkdt/page 所需的渲染器，建议在 @ithinkdt/page 插件初始化时注册。

import pagePlugin from '@ithinkdt/page'
import { DataActions } from '@ithinkdt/ui/components'
import {
    createDescriptionHelper,
    createFormHelper,
    createFormItemHelper,
    createModalHelper,
} from '@ithinkdt/ui/page'

app.use(pagePlugin, {
    getFormRenderer: createFormHelper(),
    getModalRenderer: createModalHelper(),
    getFormItemRenderer: createFormItemHelper({
        uploadFile: async (file) => {
            const formData = new FormData()
            formData.append('file', file)
            const res = await fetch('/api/files', { method: 'POST', body: formData })
            return await res.text()
        },
        getFileInfos: async (ids) => {
            return await fetch('/api/files/info', {
                method: 'POST',
                body: JSON.stringify(ids),
            }).then(res => res.json())
        },
        getUserGroups: async () => [],
        getUsersByGroup: async () => [],
        getUsersByDept: async () => [],
        getUsersByUsername: async () => [],
        getDeptsByCode: async () => [],
    }),
    getDescriptionRenderer: createDescriptionHelper({
        getFileInfos: async ids => [],
        previewFileUrl: id => `/api/files/${id}/preview`,
        getUsersByUsername: async usernames => [],
        getDeptsByCode: async codes => [],
    }),
    getTableActionsRenderer: () => actions => <DataActions options={actions} />,
})

内置表单项类型

内置详情类型

指令

v-spin

<template>
    <section v-spin="loading" data-spin-tip="加载中...">
        ...
    </section>

    <section v-spin.dark="submitting">
        ...
    </section>
</template>

支持 light、dark 修饰符；data-spin-tip 可设置提示文字。

v-tooltip

<template>
    <span v-tooltip.auto="'完整内容'">
        很长的内容
    </span>

    <p v-tooltip.auto.expandable.ell3="detail">
        {{ detail }}
    </p>

    <button v-tooltip.bottom="'保存'">
        保存
    </button>
</template>

常用修饰符：

组合式 API

useDataTableDrag

用于给 DataTable 或其他表格 DOM 添加拖拽排序能力。

import { useTemplateRef } from 'vue'
import { useDataTableDrag } from '@ithinkdt/ui/composables'

const tableRef = useTemplateRef<HTMLElement>('table')
const data = ref([
    { id: '1', name: '张三' },
    { id: '2', name: '李四' },
])

useDataTableDrag(tableRef, {
    data,
    handle: '.drag-handle',
    onSort({ from, to }) {
        const [item] = data.value.splice(from, 1)
        data.value.splice(to, 0, item)
    },
})

样式工具

@ithinkdt/ui/use-style 重新导出 ithinkdt-ui 的 CSSR 工具，并提供常用样式对象。

import useStyle, {
    c,
    cB,
    cE,
    cM,
    flexCenter,
    fullWH,
    useClsPrefix,
} from '@ithinkdt/ui/use-style'

常用导出：

导入路径

// 应用布局、指令 Provider、根 UIProvider
import { AppLayout, UIProvider, vSpin, vTooltip } from '@ithinkdt/ui'

// 数据组件
import { DataForm, DataTable, DataPagination } from '@ithinkdt/ui/components'

// 指令
import { vSpin, vTooltip } from '@ithinkdt/ui/directives'

// 与 @ithinkdt/page 集成的渲染器
import { createFormItemHelper } from '@ithinkdt/ui/page'

// 组合式 API
import { useDataTableDrag } from '@ithinkdt/ui/composables'

// 样式工具
import useStyle from '@ithinkdt/ui/use-style'

// UnoCSS 预设
import ithinkdt from '@ithinkdt/ui/unocss'