@ithinkdt/page

@ithinkdt/page

许可证

MIT

安装

npm i @ithinkdt/page

需要您自行安装依赖 vue@3 与 vue-router@4。

介绍

@ithinkdt/page 提供 iThinkDT 页面开发的核心组合式 API，包括：

• 数据源管理（远程分页/本地数据）
• 前端分页
• 表单管理（查询筛选、编辑表单、表单弹窗）
• 表格列定义与自定义列
• CRUD 操作（新增、编辑、查看、删除）
• 描述详情展示
• 模态框（对话框/抽屉）
• 表单校验规则

初始化

注册插件

import { createApp } from 'vue'
import pagePlugin from '@ithinkdt/page'

const app = createApp(App)

app.use(pagePlugin, {
    i18n,
    getConfirmRenderer: () => renderConfirm,
    getModalRenderer: () => renderModal,
    getFormRenderer: () => renderForm,
    getFormItemRenderer: {
        text: () => renderTextInput,
    },
    getDescriptionRenderer: {
        text: () => (value) => value,
    },
    getTableActionsRenderer: () => renderTableActions,
    defaultPageSize: 20,
    defaultFilterCached: true,
})

组合式 API

useDs 数据源

用于管理远程分页数据或本地数据列表，支持增删改操作：

import { useDs } from '@ithinkdt/page'
import { userApi } from '@/api/user'

const ds = useDs(
    async ({ currentPage, pageSize, sortField, sortOrder }, filter) => {
        const res = await userApi.page({ currentPage, pageSize, sortField, sortOrder, filter })
        return res
    },
    { pagination: 'remote', defaultPageSize: 20 },
)

// 刷新数据
ds.pull({ currentPage: 1, pageSize: 20 })

// 本地插入一条
ds.insert({ id: 'new', name: '张三' })

// 本地更新一条
ds.set('id-xxx', { name: '李四' })

// 本地删除一条
ds.remove('id-xxx')

useFilterHelper 查询筛选表单

import { useFilterHelper } from '@ithinkdt/page'

const { model, items, reset, validate } = useFilterHelper(
    ({ it, model, validate }) => [
        it('name', '用户名', 'text', { placeholder: '请输入用户名' }),
        it('status', '状态', 'select', { selectProps: { options: statusOptions } }),
    ],
    { cached: true },
)

useFormHelper 表单管理

import { useFormHelper } from '@ithinkdt/page'

const { model, items, validate } = useFormHelper(
    ({ it, model, validate, group, reset }) => [
        it('name', '名称', 'text', { required: true }),
        it('email', '邮箱', 'text', { rule: email('请输入有效邮箱') }),
        group(computed(() => model.country === 'China'), [
            it('phone', '手机号', 'text'),
        ]),
    ],
    {
        initial: { name: '' },
        onChange(name, value) {
            console.log(`${name} changed:`, value)
        },
    },
)

// 校验
const [valid] = await validate()
if (valid) {
    await submit(model)
}

useFormModal 表单弹窗

将表单放入模态框中展示，常用于编辑场景：

import { useFormModal } from '@ithinkdt/page'

const { open, close } = useFormModal({
    title: '编辑用户',
    type: 'dialog',
    width: 600,
    items: ({ it, model }) => [
        it('name', '名称', 'text', { required: true }),
    ],
    onSubmit: async (data) => {
        await userApi.save(data)
    },
    initial: { name: '' },
})

// 打开弹窗，传入初始数据
await open({ id: '1', name: '张三' })

useSimpleCrud CRUD 操作

封装新增、编辑、查看、删除的标准流程：

import { useSimpleCrud } from '@ithinkdt/page'

const { onAdd, onEdit, onView, onDel } = useSimpleCrud({
    get: id => userApi.get(id),
    save: data => userApi.save(data),
    delete: id => userApi.delete(id),
    // 增删改查用统一的表单
    items: ({ it }) => [
        it('name', '名称', 'text', { required: true }),
        it('status', '状态', 'select'),
        it('name', '名称', 'text'),
        it('email', '邮箱', 'text'),
    ],
    // 差别较大的时候，可以分开定义
    createItems: ({ it }) => [
        it('name', '名称', 'text', { required: true }),
    ],
    editItems: ({ it, model }) => [
        it('name', '名称', 'text', { required: true }),
        it('status', '状态', 'select'),
    ],
    viewItems: ({ it }) => [
        it('name', '名称', 'text'),
        it('email', '邮箱', 'text'),
    ],
})

// 新增
await onAdd({ name: '张三' })

// 编辑
await onEdit('id-xxx')

// 查看
await onView('id-xxx')

// 删除（带确认弹窗）
await onDel('id-xxx')

useDeleteHelper 删除确认

import { useDeleteHelper } from '@ithinkdt/page'

const { onDel } = useDeleteHelper({
    delete: ids => Array.isArray(ids) ? userApi.deleteBatch(ids) : userApi.delete(id),
})

// 单个删除
await onDel('id-xxx')

// 批量删除
await onDel(['id-1', 'id-2'])

// 自定义提示
await onDel('id-xxx', '确认删除', '该操作不可撤销')

useTableHelper 表格列定义

import { useTableHelper, calcActionWidth } from '@ithinkdt/page'

const { columns, custom } = useTableHelper(
    ({ col, cols, group }) => [
        col('index', '#', (_, __, i) => i + 1, { width: 60 }),
        col('name', '用户名', { width: 120 }),
        col('email', '邮箱', 'text', { ellipsis: true }),
        col('status', '状态', { width: 100, render: v => v ? '启用' : '禁用' }),
        cols('操作', [
            col('$edit', '', (_, record) => h('Button', { onClick: () => onEdit(record) }, '编辑')),
            col('$delete', '', (_, record) => h('Button', { onClick: () => onDel(record) }, '删除')),
        ], { fixed: 'right' }),
    ],
    {
        index: i => i + (params.currentPage - 1) * params.pageSize,
        selectable: canSelect && (record) => record.status === 'selectable',
        customizable: true,
        actions: [
            { preset: 'edit', onClick: (record) => onEdit(record) },
            { preset: 'delete', onClick: (record) => onDel(record) },
        ],
    },
)

useDescriptionsHelper 描述详情

import { useDescriptionsHelper } from '@ithinkdt/page'

const { items, model, reset } = useDescriptionsHelper(
    ({ it, group }) => [
        it('name', '用户名', 'text'),
        it('email', '邮箱'),
        it('status', '状态', (value) => value ? '启用' : '禁用'),
        group('contact', '联系方式', [
            it('phone', '手机号', 'text'),
            it('address', '地址', 'text'),
        ]),
    ],
)

// 设置数据
reset({ name: '张三', email: 'zhangsan@example.com', phone: '13800000000' })

useModal 模态框

import { useModal, useModalRef } from '@ithinkdt/page'

const xxx = ref('123')
const modal = useModal({
    type: 'drawer',
    title: '编辑',
    width: 600,
    content: () => <MyForm xxx={xxx.value} />,
    onConfirm: async () => {
        await submit()
    },
})

// 打开
await modal.open()

// 关闭
modal.close()

useDataPagination 前端分页

import { useDataPagination } from '@ithinkdt/page'
import { ref } from 'vue'

const allData = ref([...])
const { data, pagination, paginate } = useDataPagination(allData, { pageSize: 10 })

// data 为当前页数据，pagination 为分页状态

校验规则

@ithinkdt/page/rules 提供常用的表单校验规则：

import { required, min, max, email, phone, url, idNo, chinese, noChinese } from '@ithinkdt/page/rules'

const rules = {
    name: required('请输入名称'),
    age: min(0, val => '年龄不能小于0'),
    email: email('请输入有效邮箱'),
    phone: phone('请输入有效手机号'),
}

API 参考

useDs(fetch, options?)

useFilterHelper(items, options?)

useFormHelper(items, options?)

useFormModal(options)

useSimpleCrud(options)

useDeleteHelper(options)

useTableHelper(columns, options?)

useDescriptionsHelper(items)

useModal(options)

useModalRef()

useDataPagination(data, options?)

校验规则（@ithinkdt/page/rules）

message 参数为 (value, params) => string，options.trigger 默认 'blur'（required 默认 ['input', 'blur', 'change']）。