@mvtcode/vue3-querybuilder-naive-ui

v0.0.8

Published

7 days ago

A powerful and flexible query builder component for Vue 3 with Naive UI

Downloads

1,884

0High
0Medium
0Low

mvtcode

naive-ui query-builder typescript vue vue3

🛡️ Vue 3 QueryBuilder (Naive UI)

A powerful, highly flexible, and type-safe query builder component for Vue 3, elegantly crafted with Naive UI.

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 Naive UI.

[!NOTE] This project is a specialized port of @mvtcode/vue3-querybuilder. While the original version is built for Element Plus, this version is rebuilt from the ground up to utilize Naive UI, providing a more refined, premium aesthetic and deeper integration with Naive UI's component ecosystem.
Dự án này là phiên bản chuyên biệt của @mvtcode/vue3-querybuilder. Trong khi phiên bản gốc được xây dựng cho Element Plus, phiên bản này được xây dựng lại hoàn toàn với Naive UI, mang lại giao diện tinh tế hơn và tích hợp sâu hơn với hệ sinh thái Naive UI.

✨ Features / Tính năng

🚀 Modern Vue 3: Native Composition API and TypeScript support. / Composition API gốc và hỗ trợ TypeScript.
🎨 Naive UI Design: Premium look and feel out of the box. / Giao diện cao cấp ngay khi cài đặt.
🌐 Deep i18n Integration: Built-in support for English and Vietnamese. / Hỗ trợ sẵn tiếng Anh và tiếng Việt.
🧩 Advanced Slots: Dynamic slots for every field with rich context (isBetween, widthValueInput, rule, filter). / Slot động cho mọi field với đầy đủ context.
🔄 Multi-format Converters: Export to SQL, MongoDB, MNP, or parse from SQL/MongoDB. / Xuất sang SQL, MongoDB, MNP hoặc phân tích ngược.
📱 Responsive & Fluid: Adaptive layouts using Naive UI's Flex and Grid systems. / Layout linh hoạt dùng Flex và Grid của Naive UI.
🛡️ Rule Limits: maxOccurrences to control how many times a field can appear. / Kiểm soát số lần một field được lọc.
🌳 Nested Groups: Build complex AND/OR logic with configurable depth limits. / AND/OR logic lồng nhau với giới hạn độ sâu tùy chỉnh.

📦 Installation / Cài đặt

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

🔗 Repository

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

🚀 Quick Start / Bắt đầu nhanh

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

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

const filters: QueryBuilderFilter[] = [
  {
    field: 'name',
    label: 'Full Name',
    type: FilterType.STRING,
    operators: [Operator.EQUAL, Operator.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)" />
</template>

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

Props

Events / Sự kiện

| Event | Payload | Description (EN) | Mô tả (VI) | | :------- | :------ | :--------------------------------------------------------------------------- | :------------------------------------------------ | | change | — | Fired when any part of the query changes (add/remove rule, field, operator). | Kích hoạt khi bất kỳ phần nào của query thay đổi. |

🔗 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 inputs for specific fields using slots named after the field's field value.

Tùy chỉnh input cho field cụ thể 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 }">
  <n-input v-model:value="rule.value" :style="{ width: `${widthValueInput}px` }" />
</template>



<template #age="{ rule, isBetween, widthValueInput }">
  <n-input-number v-if="!isBetween" v-model:value="rule.value" />
  <div v-else>
    <n-input-number v-model:value="(rule.value as number[])[0]" />
    <n-input-number v-model:value="(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 }">
    <n-input-number
      v-if="!isBetween"
      v-model:value="rule.value"
      :min="0"
      :max="100"
      :style="{ width: widthValueInput + 'px' }"
    />
    <div v-else style="display: flex; align-items: center; gap: 10px">
      <n-input-number v-model:value="(rule.value as number[])[0]" :min="0" :max="100" :style="{ width: widthValueInput + 'px' }" />
      <span>and</span>
      <n-input-number v-model:value="(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 }">
    <n-date-picker
      v-model:value="rule.value"
      :type="isBetween ? 'daterange' : 'date'"
      :style="{ width: widthValueInput + 'px' }"
    />
  </template>

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

🔄 Query Conversion / Chuyển đổi Query

To SQL / Xuất SQL

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

const sql = toSQL(rules.value)
// Result: `age` >= 18 AND `status` = 'active'

To MongoDB / Xuất MongoDB

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

const mongo = toMongo(rules.value)
// Result: { $and: [{ age: { $gte: 18 } }, { status: { $eq: 'active' } }] }

To MNP (Custom) / Xuất MNP

import { toMnpQuery } from '@mvtcode/vue3-querybuilder-naive-ui'

const mnp = toMnpQuery(rules.value, filters)
// Result: {age} >= 18 AND {status} == '''active'''

From SQL / Nhập từ SQL

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

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

From MongoDB / Nhập từ MongoDB

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

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' },
  ],
}

📸 Screenshots / Ảnh chụp màn hình

Vietnamese / Tiếng Việt

Screenshot VI

English / Tiếng Anh

Screenshot EN

🧑‍💻 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 Projects / Dự án liên quan