@mvtcode/vue3-querybuilder

v0.1.21

Published

8 days ago

A powerful and flexible query builder component for Vue 3 with Element Plus

Downloads

555

0High
0Medium
0Low

mvtcode

vue vue3 query-builder element-plus typescript

🛡️ Vue 3 QueryBuilder (Element Plus)

A powerful, highly flexible, and type-safe query builder component for Vue 3, built with Element Plus.

Thành phần query builder mạnh mẽ, linh hoạt và type-safe cho Vue 3, được xây dựng với Element Plus.

✨ Features / Tính năng

🚀 Modern Vue 3: Native Composition API and TypeScript support. / Composition API gốc và hỗ trợ TypeScript.
🎨 Element Plus Design: Beautiful, enterprise-grade UI out of the box. / Giao diện đẹp, chuẩn enterprise ngay khi cài đặt.
🌐 i18n Built-in: Support for English (en) and Vietnamese (vi). / Hỗ trợ sẵn tiếng Anh (en) và tiếng Việt (vi).
🧩 Dynamic Slots: Customize inputs for any field with rich slot props (isBetween, widthValueInput, rule, filter). / Tùy chỉnh input cho mọi field với các slot prop đầy đủ.
🔄 Multi-format Converters: Export to SQL, MongoDB, or parse from them. / Xuất sang SQL, MongoDB, hoặc phân tích ngược lại.
🌳 Nested Groups: Build complex AND/OR logic with configurable depth limits. / Xây dựng logic AND/OR lồng nhau với giới hạn độ sâu tùy chỉnh.
📏 Configurable Widths: Control field/operator/value column widths. / Điều chỉnh độ rộng cột field/operator/value.

📦 Installation / Cài đặt

npm install @mvtcode/vue3-querybuilder
# or / hoặc
pnpm add @mvtcode/vue3-querybuilder

Peer Dependencies: vue >= 3.0.0, element-plus >= 2.0.0, @element-plus/icons-vue >= 2.0.0

🔗 Repository

git clone [email protected]:mvtcode/vue3-querybuilder.git

🚀 Quick Start / Bắt đầu nhanh

main.ts

import '@mvtcode/vue3-querybuilder/style.css'

.vue file

<script setup lang="ts">
import { ref } from 'vue'
import { QueryBuilder, FilterType, Operator } from '@mvtcode/vue3-querybuilder'
import type { QueryBuilderGroup, QueryBuilderFilter } from '@mvtcode/vue3-querybuilder'

const rules = ref<QueryBuilderGroup>({
  condition: 'AND',
  rules: [],
})

const filters: QueryBuilderFilter[] = [
  {
    field: 'name',
    label: 'Name',
    type: FilterType.STRING,
    operators: [Operator.EQUAL, Operator.CONTAINS, Operator.NOT_CONTAINS],
  },
  {
    field: 'age',
    label: 'Age',
    type: FilterType.INTEGER,
    operators: [Operator.GREATER, Operator.LESS, Operator.BETWEEN],
  },
]
</script>

<template>
  <QueryBuilder v-model="rules" :filters="filters" language="en" @change="console.log(rules)" size="small" />
</template>

🛠️ API Reference / Tài liệu API

Props

Events / Sự kiện

🔗 Enums & Types / Kiểu dữ liệu

FilterType

enum FilterType {
  STRING = 'string',
  NUMBER = 'number',
  INTEGER = 'integer',
  DATE = 'date',
  DATETIME = 'datetime',
  BOOLEAN = 'boolean',
  EMAIL = 'email',
}

Operator

enum Operator {
  EQUAL = 'equal',
  NOT_EQUAL = 'not_equal',
  CONTAINS = 'contains',
  NOT_CONTAINS = 'not_contains',
  BEGINS_WITH = 'begins_with',
  NOT_BEGINS_WITH = 'not_begins_with',
  ENDS_WITH = 'ends_with',
  NOT_ENDS_WITH = 'not_ends_with',
  IS_EMPTY = 'is_empty',
  IS_NOT_EMPTY = 'is_not_empty',
  GREATER = 'greater',
  GREATER_OR_EQUAL = 'greater_or_equal',
  LESS = 'less',
  LESS_OR_EQUAL = 'less_or_equal',
  IN = 'in',
  NOT_IN = 'not_in',
  BETWEEN = 'between',
  NOT_BETWEEN = 'not_between',
}

QueryBuilderFilter

interface QueryBuilderFilter {
  field: string           // Field name / Tên field
  label: string           // Display label / Nhãn hiển thị
  type: FilterType        // Data type / Kiểu dữ liệu
  operators: Operator[]   // Allowed operators / Các operator được phép
  input?: string          // Input type: 'select' | 'radio' | 'checkbox' | 'date' | 'email'
  values?: Array<{        // Options for select/radio / Tuỳ chọn cho select/radio
    value: string
    text: string
  }>
  validation?: {
    format?: string       // Date format e.g. 'YYYY-MM-DD'
    min?: number          // Minimum value / Giá trị tối thiểu
    max?: number          // Maximum value / Giá trị tối đa
    step?: number         // Step for number input / Bước nhảy
  }
  maxOccurrences?: number // Max times this field can appear in a group / Số lần tối đa field xuất hiện trong nhóm
}

QueryBuilderGroup / QueryBuilderRule

interface QueryBuilderGroup {
  type?: 'group'
  condition: 'AND' | 'OR'
  rules: (QueryBuilderRule | QueryBuilderGroup)[]
}

interface QueryBuilderRule {
  type: 'rule'
  field: string
  operator: Operator
  value: any
}

🧩 Dynamic Slots / Slot tùy chỉnh

Customize the input for any field by naming the slot after the field's field value.

Tùy chỉnh input cho bất kỳ field nào bằng cách đặt tên slot theo giá trị field.

[!TIP] v-model inside a slot / Dùng v-model trong slot
To bind v-model to a component inside a slot, always use rule.value — it is the reactive source of truth for the current rule's value.
Khi muốn bind v-model cho component bên trong slot, hãy luôn dùng rule.value — đây là nguồn dữ liệu reactive đại diện cho giá trị của rule đó.

<template #name="{ rule, widthValueInput }">
  <el-input v-model="rule.value" :style="{ width: `${widthValueInput}px` }" />
</template>



<template #age="{ rule, isBetween, widthValueInput }">
  <el-input-number v-if="!isBetween" v-model="rule.value" />
  <div v-else>
    <el-input-number v-model="(rule.value as number[])[0]" />
    <el-input-number v-model="(rule.value as number[])[1]" />
  </div>
</template>

Example / Ví dụ:

<QueryBuilder v-model="rules" :filters="filters">
  <!-- Custom age input with between support / Input age tùy chỉnh hỗ trợ BETWEEN -->
  <template #age="{ rule, isBetween, widthValueInput }">
    <el-input-number
      v-if="!isBetween"
      v-model="rule.value"
      :min="0"
      :max="100"
      :style="{ width: `${widthValueInput}px` }"
    />
    <div v-else style="display: flex; align-items: center; gap: 10px">
      <el-input-number v-model="(rule.value as number[])[0]" :min="0" :max="100" :style="{ width: `${widthValueInput}px` }" />
      <span>and</span>
      <el-input-number v-model="(rule.value as number[])[1]" :min="0" :max="100" :style="{ width: `${widthValueInput}px` }" />
    </div>
  </template>

  <!-- Custom date picker / Date picker tùy chỉnh -->
  <template #birthdate="{ rule, isBetween, widthValueInput }">
    <el-date-picker
      v-model="rule.value"
      :type="isBetween ? 'daterange' : 'date'"
      placeholder="Select date"
      :style="{ width: `${widthValueInput}px` }"
    />
  </template>

  <!-- Custom select dropdown / Dropdown tùy chỉnh -->
  <template #status="{ rule, widthValueInput }">
    <el-select
      v-model="rule.value"
      :multiple="[Operator.IN, Operator.NOT_IN].includes(rule.operator)"
      :style="{ width: `${widthValueInput}px` }"
    >
      <el-option label="Pending" value="pending" />
      <el-option label="Completed" value="completed" />
    </el-select>
  </template>
</QueryBuilder>

🔄 Query Conversion / Chuyển đổi Query

To SQL / Xuất SQL

import { toSQL } from '@mvtcode/vue3-querybuilder'

const sql = toSQL(rules.value)
// Result: name LIKE '%John%' AND age >= 18

To MongoDB / Xuất MongoDB

import { toMongo } from '@mvtcode/vue3-querybuilder'

const mongo = toMongo(rules.value)
// Result: { $and: [{ name: { $regex: 'John', $options: 'i' } }, { age: { $gte: 18 } }] }

From SQL / Nhập từ SQL

import { fromSQL } from '@mvtcode/vue3-querybuilder'

const rules = fromSQL("name = 'John' AND age >= 18")

From MongoDB / Nhập từ MongoDB

import { fromMongo } from '@mvtcode/vue3-querybuilder'

const rules = fromMongo({ $and: [{ name: { $eq: 'John' } }, { age: { $gte: 18 } }] })

Operator Mapping / Bảng ánh xạ Operator

| QueryBuilder Operator | SQL Operator | MongoDB Operator | | :-------------------- | :----------- | :--------------- | | EQUAL | = | $eq | | NOT_EQUAL | != | $ne | | CONTAINS | LIKE | $regex | | NOT_CONTAINS | NOT LIKE | $not | | BEGINS_WITH | LIKE | $regex | | ENDS_WITH | LIKE | $regex | | GREATER | > | $gt | | GREATER_OR_EQUAL | >= | $gte | | LESS | < | $lt | | LESS_OR_EQUAL | <= | $lte | | IN | IN | $in | | NOT_IN | NOT IN | $nin | | BETWEEN | BETWEEN | $and | | NOT_BETWEEN | NOT BETWEEN| $nor | | IS_EMPTY | IS NULL | $exists: false | | IS_NOT_EMPTY | IS NOT NULL| $exists: true |

📋 Filter Type Examples / Ví dụ theo loại Filter

1. Text (STRING)

{
  field: 'name',
  label: 'Name',
  type: FilterType.STRING,
  operators: [
    Operator.EQUAL, Operator.NOT_EQUAL,
    Operator.CONTAINS, Operator.NOT_CONTAINS,
    Operator.BEGINS_WITH, Operator.ENDS_WITH,
    Operator.IS_EMPTY, Operator.IS_NOT_EMPTY,
  ],
}

2. Email — with auto validation / tự động validate

{
  field: 'email',
  label: 'Email',
  type: FilterType.EMAIL,
  operators: [Operator.EQUAL, Operator.NOT_EQUAL, Operator.CONTAINS, Operator.NOT_CONTAINS,
              Operator.IS_EMPTY, Operator.IS_NOT_EMPTY],
  input: 'email',
}

3. Integer — with min/max and BETWEEN / có min/max và BETWEEN

{
  field: 'age',
  label: 'Age',
  type: FilterType.INTEGER,
  validation: { min: 0, max: 100 },
  operators: [
    Operator.EQUAL, Operator.NOT_EQUAL,
    Operator.GREATER, Operator.GREATER_OR_EQUAL,
    Operator.LESS, Operator.LESS_OR_EQUAL,
    Operator.BETWEEN, Operator.NOT_BETWEEN,
  ],
}

4. Date — with date picker and range / có date picker và range

{
  field: 'birthdate',
  label: 'Birth Date',
  type: FilterType.DATE,
  input: 'date',
  validation: { format: 'YYYY-MM-DD' },
  operators: [
    Operator.EQUAL, Operator.NOT_EQUAL,
    Operator.GREATER, Operator.LESS,
    Operator.BETWEEN, Operator.NOT_BETWEEN,
  ],
}

5. Boolean — with checkbox / với checkbox

{
  field: 'active',
  label: 'Active',
  type: FilterType.BOOLEAN,
  input: 'checkbox',
}

6. Select (Dropdown) — with multiple / hỗ trợ multiple

{
  field: 'status',
  label: 'Status',
  type: FilterType.STRING,
  input: 'select',
  operators: [Operator.EQUAL, Operator.NOT_EQUAL, Operator.IN, Operator.NOT_IN],
  values: [
    { value: 'pending', text: 'Pending' },
    { value: 'completed', text: 'Completed' },
  ],
}

📸 Screenshot

Vue 3 QueryBuilder Screenshot

🧑‍💻 Example Code / Code ví dụ đầy đủ

Full example code can be found in the App.vue file.

Xem code ví dụ đầy đủ trong file App.vue.

🔗 Related Project / Dự án liên quan