From e938118594ee0d5a13513942acc221c6e2d1cc35 Mon Sep 17 00:00:00 2001
From: windychen <windychen00n@gmail.com>
Date: Fri, 7 Aug 2026 16:42:01 +0800
Subject: [PATCH] =?UTF-8?q?chore:=20=E7=89=88=E6=9C=AC=200.1.0=20=E6=9B=B4?=
 =?UTF-8?q?=E6=96=B0=20=E9=BB=98=E8=AE=A4=20query-option=20=E6=B7=B1?=
 =?UTF-8?q?=E6=8B=B7=E8=B4=9D=E5=AF=BC=E5=87=BA=E4=B8=8E=20schema=20?=
 =?UTF-8?q?=E7=BC=BA=E7=9C=81=E5=9B=9E=E9=80=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/TransForm.vue             |  5 +-
 src/composables/useFilters.js | 20 +++++++-
 src/config.js                 | 37 +++++++++++++-
 src/index.js                  |  3 ++
 test/transForm.test.js        | 60 ++++++++++++++++++++++
 test/useFilters.test.js       | 93 ++++++++++++++++++++++++++++++++++-
 6 files changed, 212 insertions(+), 6 deletions(-)
 create mode 100644 test/transForm.test.js

diff --git a/src/TransForm.vue b/src/TransForm.vue
index b7944bd..2a4bd4d 100644
--- a/src/TransForm.vue
+++ b/src/TransForm.vue
@@ -6,6 +6,7 @@ import {
   buildFilters,
   createFieldState,
   groupRows,
+  resolveQueryOption,
 } from './composables/useFilters.js';
 import UnknownPlaceholder from './components/UnknownPlaceholder.vue';
 const props = defineProps({
@@ -114,7 +115,7 @@ defineExpose({ getFilters, setFilters, loadFilters, reset });
             :disabled="state[fieldDef.field]?.disabled"
           >
             <option
-              v-for="opt in fieldDef['query-option'] || []"
+              v-for="opt in resolveQueryOption(fieldDef)"
               :key="opt.value"
               :value="opt.value"
             >
@@ -131,7 +132,7 @@ defineExpose({ getFilters, setFilters, loadFilters, reset });
             :placeholder="fieldDef['field-name']"
             :field="fieldDef.field"
             :field-name="fieldDef['field-name']"
-            :query-option="fieldDef['query-option'] || []"
+            :query-option="resolveQueryOption(fieldDef)"
             :schema="fieldDef"
             :options="fieldDef.options || []"
           />
diff --git a/src/composables/useFilters.js b/src/composables/useFilters.js
index eb0b2f8..d5aba2b 100644
--- a/src/composables/useFilters.js
+++ b/src/composables/useFilters.js
@@ -15,6 +15,22 @@
  * @property {string} [query]
  */
 
+import { getDefaultQueryOption } from '../config.js';
+
+/**
+ * 解析字段的查询操作符列表：
+ * - schema 显式配置了 query-option 时，优先使用字段自己的；
+ * - 否则若配置了自定义 query-component（操作符由组件自己管理），返回空数组、不套默认；
+ * - 否则返回默认操作符列表（getDefaultQueryOption 深拷贝，调用方可安全修改）。
+ * @param {SchemaField} [fieldDef]
+ * @returns {Array<{value: string, label?: string}>}
+ */
+export function resolveQueryOption(fieldDef) {
+  if (fieldDef?.['query-option']) return fieldDef['query-option'];
+  if (fieldDef?.['query-component']) return [];
+  return getDefaultQueryOption();
+}
+
 /**
  * @param {SchemaField[]} schema
  */
@@ -26,7 +42,7 @@ export function createFieldState(schema) {
     const defaultQuery =
       item['default-query'] ??
       item.query ??
-      item['query-option']?.[0]?.value ??
+      resolveQueryOption(item)[0]?.value ??
       'EQ';
     state[item.field] = {
       value: item.value ?? '',
@@ -60,7 +76,7 @@ export function buildFilters(schema, state) {
     const row = {
       field: key,
       value: empty ? null : value,
-      query: current.query ?? fieldDef['query-option']?.[0]?.value ?? 'EQ',
+      query: current.query ?? resolveQueryOption(fieldDef)[0]?.value ?? 'EQ',
       hidden: current.hidden === true,
       disabled: current.disabled === true,
       readOnly: current.readOnly === true,
diff --git a/src/config.js b/src/config.js
index 63b406d..250493e 100644
--- a/src/config.js
+++ b/src/config.js
@@ -20,13 +20,35 @@ export const BUILTIN_COMPONENT_MAP = {
   between: HeadlessBetween,
 };
 
-/** @typedef {{ componentMap?: Record<string, import('vue').Component>, colRatio?: { name?: number, query?: number, value?: number }, changeEmit?: 'immediate'|'debounce'|'manual' }} TransFormConfig */
+/**
+ * 默认查询操作符全集（对应 DESIGN.md Q12/Q61 操作符码表）。
+ * 注意：这是共享常量，请通过 getDefaultQueryOption() 获取深拷贝后再修改，
+ * 不要直接改动本常量，以免污染全局配置。
+ */
+export const DEFAULT_QUERY_OPTION = [
+  { value: 'EQ', label: '=' },
+  { value: 'NE', label: '≠' },
+  { value: 'GT', label: '>' },
+  { value: 'GTE', label: '≥' },
+  { value: 'LT', label: '<' },
+  { value: 'LTE', label: '≤' },
+  { value: 'LIKE', label: 'LIKE' },
+  { value: 'IN', label: 'IN' },
+  { value: 'NOT_IN', label: 'NOT IN' },
+  { value: 'BETWEEN', label: 'BETWEEN' },
+  { value: 'IS_NULL', label: 'IS NULL' },
+  { value: 'IS_NOT_NULL', label: 'IS NOT NULL' },
+];
+
+/** @typedef {{ componentMap?: Record<string, import('vue').Component>, colRatio?: { name?: number, query?: number, value?: number }, changeEmit?: 'immediate'|'debounce'|'manual', queryOption?: Array<{value: string, label?: string}> }} TransFormConfig */
 
 /** @type {TransFormConfig & { componentMap: Record<string, import('vue').Component> }} */
 const globalConfig = {
   componentMap: { ...BUILTIN_COMPONENT_MAP },
   colRatio: { name: 3, query: 2, value: 7 },
   changeEmit: 'immediate',
+  // 默认操作符列表（深拷贝一份，避免外部修改 DEFAULT_QUERY_OPTION 常量污染配置）
+  queryOption: structuredClone(DEFAULT_QUERY_OPTION),
 };
 
 /**
@@ -43,6 +65,18 @@ export function setConfig(patch) {
     globalConfig.colRatio = { ...globalConfig.colRatio, ...patch.colRatio };
   }
   if (patch.changeEmit) globalConfig.changeEmit = patch.changeEmit;
+  // queryOption：整体替换整个数组（深拷贝存储，防止外部后续修改污染配置）
+  if (patch.queryOption) {
+    globalConfig.queryOption = structuredClone(patch.queryOption);
+  }
+}
+
+/**
+ * 获取默认查询操作符列表（始终返回深拷贝，调用方可安全修改，不影响全局配置）。
+ * @returns {Array<{value: string, label?: string}>}
+ */
+export function getDefaultQueryOption() {
+  return structuredClone(globalConfig.queryOption);
 }
 
 export function getConfig() {
@@ -53,4 +87,5 @@ export function resetConfig() {
   globalConfig.componentMap = { ...BUILTIN_COMPONENT_MAP };
   globalConfig.colRatio = { name: 3, query: 2, value: 7 };
   globalConfig.changeEmit = 'immediate';
+  globalConfig.queryOption = structuredClone(DEFAULT_QUERY_OPTION);
 }
diff --git a/src/index.js b/src/index.js
index 3f6065f..3e10d25 100644
--- a/src/index.js
+++ b/src/index.js
@@ -2,6 +2,9 @@ import './styles/trans-form.css';
 
 export { default as TransFormPlugin, TransForm, setConfig, getConfig } from './plugin.js';
 
+export { DEFAULT_QUERY_OPTION, getDefaultQueryOption, resetConfig } from './config.js';
+export { resolveQueryOption } from './composables/useFilters.js';
+
 export { default as HeadlessInput } from './components/HeadlessInput.vue';
 export { default as HeadlessTextarea } from './components/HeadlessTextarea.vue';
 export { default as HeadlessSelect } from './components/HeadlessSelect.vue';
diff --git a/test/transForm.test.js b/test/transForm.test.js
new file mode 100644
index 0000000..62cdd1e
--- /dev/null
+++ b/test/transForm.test.js
@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { mount } from '@vue/test-utils';
+import TransForm from '../src/TransForm.vue';
+import { resetConfig, setConfig } from '../src/config.js';
+
+// 每个用例后恢复全局配置，避免 setConfig 污染其它用例
+afterEach(() => {
+  resetConfig();
+});
+
+describe('TransForm 操作符下拉（默认 query-option）', () => {
+  it('无 query-option 的字段渲染默认操作符列表（12 项，第一项 EQ）', () => {
+    const wrapper = mount(TransForm, {
+      props: { schema: [{ row: 12, field: 'name', 'field-name': '名称' }] },
+    });
+    const opts = wrapper.find('select').findAll('option');
+    expect(opts).toHaveLength(12);
+    expect(opts[0].text()).toBe('=');
+    expect(opts[0].attributes('value')).toBe('EQ');
+    expect(opts[11].text()).toBe('IS NOT NULL');
+  });
+
+  it('有 query-option 的字段仍渲染 schema 自己的选项（不被默认覆盖）', () => {
+    const wrapper = mount(TransForm, {
+      props: {
+        schema: [
+          {
+            row: 12,
+            field: 'status',
+            'field-name': '状态',
+            'query-option': [{ value: 'NE', label: '≠' }],
+          },
+        ],
+      },
+    });
+    const opts = wrapper.find('select').findAll('option');
+    expect(opts).toHaveLength(1);
+    expect(opts[0].text()).toBe('≠');
+    expect(opts[0].attributes('value')).toBe('NE');
+  });
+
+  it('setConfig 自定义 queryOption 后，无 query-option 字段的下拉随之更新', () => {
+    setConfig({ queryOption: [{ value: 'GT', label: '>' }] });
+    const wrapper = mount(TransForm, {
+      props: { schema: [{ row: 12, field: 'age', 'field-name': '年龄' }] },
+    });
+    const opts = wrapper.find('select').findAll('option');
+    expect(opts).toHaveLength(1);
+    expect(opts[0].text()).toBe('>');
+  });
+
+  it('有 query-component 但无 query-option 的字段不套默认下拉（操作符由组件自己管理）', () => {
+    const wrapper = mount(TransForm, {
+      props: {
+        schema: [{ row: 12, field: 'custom', 'query-component': 'CustomQuery' }],
+      },
+    });
+    expect(wrapper.find('select').findAll('option')).toHaveLength(0);
+  });
+});
diff --git a/test/useFilters.test.js b/test/useFilters.test.js
index 4368ef2..dfa87bc 100644
--- a/test/useFilters.test.js
+++ b/test/useFilters.test.js
@@ -1,11 +1,18 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it } from 'vitest';
+import { getDefaultQueryOption, resetConfig, setConfig } from '../src/config.js';
 import {
   applyFilters,
   buildFilters,
   createFieldState,
   groupRows,
+  resolveQueryOption,
 } from '../src/composables/useFilters.js';
 
+// 每个用例后恢复全局配置，避免 setConfig 污染其它用例
+afterEach(() => {
+  resetConfig();
+});
+
 const schema = [
   {
     row: 6,
@@ -68,3 +75,87 @@ describe('groupRows', () => {
     expect(groups[1]).toHaveLength(1);
   });
 });
+
+describe('resolveQueryOption（默认 query-option 解析）', () => {
+  it('无 query-option 且无 query-component 时返回默认操作符列表', () => {
+    const opts = resolveQueryOption({ field: 'name' });
+    expect(opts).toHaveLength(12);
+    expect(opts[0]).toEqual({ value: 'EQ', label: '=' });
+    expect(opts.map((o) => o.value)).toEqual([
+      'EQ', 'NE', 'GT', 'GTE', 'LT', 'LTE',
+      'LIKE', 'IN', 'NOT_IN', 'BETWEEN', 'IS_NULL', 'IS_NOT_NULL',
+    ]);
+  });
+
+  it('有 query-option 的字段仍用 schema 自己的（不被默认覆盖）', () => {
+    const fieldDef = { field: 'name', 'query-option': [{ value: 'NE', label: '≠' }] };
+    expect(resolveQueryOption(fieldDef)).toEqual([{ value: 'NE', label: '≠' }]);
+  });
+
+  it('有 query-component 但无 query-option 时返回空数组（组件自己管理）', () => {
+    const fieldDef = { field: 'name', 'query-component': 'CustomQuery' };
+    expect(resolveQueryOption(fieldDef)).toEqual([]);
+  });
+
+  it('getDefaultQueryOption() 返回深拷贝：修改返回值不影响后续调用', () => {
+    const first = getDefaultQueryOption();
+    first.push({ value: 'X', label: 'x' });
+    first[0].label = '被改坏了';
+    first.splice(1, 1);
+
+    const second = getDefaultQueryOption();
+    expect(second).toHaveLength(12);
+    expect(second[0]).toEqual({ value: 'EQ', label: '=' });
+    expect(second[1]).toEqual({ value: 'NE', label: '≠' });
+  });
+
+  it('setConfig({ queryOption }) 后 getDefaultQueryOption() 返回新列表', () => {
+    setConfig({
+      queryOption: [
+        { value: 'EQ', label: '=' },
+        { value: 'GT', label: '>' },
+      ],
+    });
+    expect(getDefaultQueryOption()).toEqual([
+      { value: 'EQ', label: '=' },
+      { value: 'GT', label: '>' },
+    ]);
+  });
+
+  it('resetConfig() 恢复默认操作符列表', () => {
+    setConfig({ queryOption: [{ value: 'ONLY_EQ', label: '=' }] });
+    resetConfig();
+    expect(getDefaultQueryOption()).toHaveLength(12);
+    expect(getDefaultQueryOption()[0]).toEqual({ value: 'EQ', label: '=' });
+  });
+});
+
+describe('默认 query fallback（无 query-option 时取默认列表第一项）', () => {
+  it('createFieldState：无 query-option 且无 query-component 默认取默认列表第一项（EQ）', () => {
+    const state = createFieldState([{ field: 'name' }]);
+    expect(state.name.query).toBe('EQ');
+  });
+
+  it('buildFilters：无 query-option 且无 query-component 默认取默认列表第一项（EQ）', () => {
+    const state = createFieldState([{ field: 'name' }]);
+    const filters = buildFilters([{ field: 'name' }], state);
+    expect(filters[0].query).toBe('EQ');
+  });
+
+  it('setConfig 自定义 queryOption 后，默认 query 取新列表第一项', () => {
+    setConfig({ queryOption: [{ value: 'GT', label: '>' }] });
+    const state = createFieldState([{ field: 'age' }]);
+    expect(state.age.query).toBe('GT');
+    expect(buildFilters([{ field: 'age' }], state)[0].query).toBe('GT');
+  });
+
+  it('有 query-component 但无 query-option 时，默认 query 仍为 EQ', () => {
+    const state = createFieldState([{ field: 'custom', 'query-component': 'CustomQuery' }]);
+    expect(state.custom.query).toBe('EQ');
+  });
+
+  it('显式 default-query 优先级最高，覆盖默认列表第一项', () => {
+    const state = createFieldState([{ field: 'name', 'default-query': 'LIKE' }]);
+    expect(state.name.query).toBe('LIKE');
+  });
+});