@56os/search-fields 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @56os/search-fields
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+列表页检索字段统一定义共享包：类型、用户排序读写、`useSearchFieldSchema`、`BasicSearchFields`、`buildAdvancedQueryParentData`。
+
+> 不进包：各页 `searchFieldSchema`、业务接口、页内特殊插槽逻辑。  
+> 高级查询抽屉仍由主包 `Advancedquery` 维护。
+
+## 安装
+
+```bash
+pnpm add @56os/search-fields
+# 或
+npm install @56os/search-fields
+```
+
+本地联调源码（可选）：
+
+```bash
+pnpm add @56os/search-fields@file:../56os-search-fields
+```
+
+## 接入（子应用入口必须注入 API）
+
+包内**不**绑定某一子包的 `@/api`，需在应用启动时注入 `user-table-config`：
+
+```ts
+import { setupSearchFields } from '@56os/search-fields';
+import { getConfigList, saveConfig } from '@/api/chooseColumn/chooseColumn.js';
+
+setupSearchFields({
+  userTableConfigApi: {
+    getConfigList,
+    saveConfig
+  }
+});
+```
+
+## 页面用法
+
+```ts
+import {
+  useSearchFieldSchema,
+  BasicSearchFields,
+  buildAdvancedQueryParentData
+} from '@56os/search-fields';
+import type { SearchFieldSchemaItem } from '@56os/search-fields';
+```
+
+```vue
+<BasicSearchFields
+  :model="queryParams"
+  :fields="visibleBasicFields"
+  :show-advanced="showAdvancedQuery"
+  @search="handleSearch"
+  @reset="handleReset"
+  @advanced="openAdvancedQuery"
+/>
+```
+
+- 配置区标签 / 高级查询：全部可查字段（同序）
+- 页头：`orderedFields.slice(0, basicVisibleCount)`，默认前 4 个
+- **高级查询入口**：`showAdvancedQuery = orderedFields.length > basicVisibleCount`；字段全在页头（如仅 3 个条件）时隐藏「高级查询」
+- 排序落库：宿主 `Advancedquery` 负责；业务页只收 `onBasicOrderChange`
+
+## 版本
+
+遵循 semver。当前 `0.1.1`：新增 `showAdvancedQuery` / `BasicSearchFields.showAdvanced`（字段全在页头时隐藏高级查询）。

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@56os/search-fields",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "56os 列表检索字段统一定义：schema / 用户排序 / 页头 BasicSearchFields / 高级查询 parentdata 构建",
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "sideEffects": [
+    "**/*.vue",
+    "**/*.css"
+  ],
+  "peerDependencies": {
+    "element-plus": "^2.7.0",
+    "vue": "^3.4.0"
+  },
+  "keywords": [
+    "56os",
+    "search-fields",
+    "vue3",
+    "element-plus"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/basicSearchConfig.ts

@@ -0,0 +1,97 @@
+import { getSearchFieldsUserTableConfigApi } from './setup';
+import type { SearchFieldsUserTableConfigApi } from './types';
+
+/** 与表头筛选隔离的 url 后缀（禁止手拼 #） */
+export const BASIC_SEARCH_CONFIG_SUFFIX = '__basicSearch';
+
+/**
+ * 生成基础检索排序配置的 url
+ * @example toBasicSearchConfigUrl('/EnterpriseInformation') => '/EnterpriseInformation__basicSearch'
+ */
+export function toBasicSearchConfigUrl(pageUrl: string): string {
+  const url = String(pageUrl || '').trim();
+  if (!url) {
+    return url;
+  }
+  if (url.endsWith(BASIC_SEARCH_CONFIG_SUFFIX)) {
+    return url;
+  }
+  return `${url}${BASIC_SEARCH_CONFIG_SUFFIX}`;
+}
+
+const splitCsv = (value?: string | null): string[] =>
+  String(value || '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+
+/**
+ * 合并用户 sortconfig 与 schema 默认可查字段顺序。
+ * - 配置中未知 key 丢弃
+ * - schema 新增且配置中没有的 key 追加到末尾
+ */
+export function mergeBasicSearchOrder(defaultKeys: string[], sortconfig?: string | string[] | null): string[] {
+  const defaults = Array.isArray(defaultKeys) ? defaultKeys.filter(Boolean) : [];
+  const saved = Array.isArray(sortconfig) ? sortconfig.filter(Boolean) : splitCsv(sortconfig);
+  if (!saved.length) {
+    return [...defaults];
+  }
+  const defaultSet = new Set(defaults);
+  const ordered: string[] = [];
+  const seen = new Set<string>();
+  saved.forEach((key) => {
+    if (defaultSet.has(key) && !seen.has(key)) {
+      ordered.push(key);
+      seen.add(key);
+    }
+  });
+  defaults.forEach((key) => {
+    if (!seen.has(key)) {
+      ordered.push(key);
+      seen.add(key);
+    }
+  });
+  return ordered;
+}
+
+/**
+ * 读取当前用户的检索字段顺序（只读 sortconfig）
+ * @returns 有序 key 列表；无配置时返回 null
+ */
+export async function loadBasicSearchOrder(
+  pageUrl: string,
+  api?: SearchFieldsUserTableConfigApi
+): Promise<string[] | null> {
+  const url = toBasicSearchConfigUrl(pageUrl);
+  try {
+    const { getConfigList } = getSearchFieldsUserTableConfigApi(api);
+    const res: any = await getConfigList({ url });
+    if (res?.code === 200 && res.data?.sortconfig) {
+      const keys = splitCsv(res.data.sortconfig);
+      return keys.length ? keys : null;
+    }
+  } catch (error) {
+    console.error('[@56os/search-fields] 加载检索字段排序失败', error);
+  }
+  return null;
+}
+
+/**
+ * 保存检索字段顺序。
+ * 注意：业务页拖拽落库责任在宿主 Advancedquery；本方法供工具复用/兜底。
+ */
+export async function saveBasicSearchOrder(
+  pageUrl: string,
+  orderedKeys: string[],
+  api?: SearchFieldsUserTableConfigApi
+) {
+  const url = toBasicSearchConfigUrl(pageUrl);
+  const csv = (orderedKeys || []).filter(Boolean).join(',');
+  const { saveConfig } = getSearchFieldsUserTableConfigApi(api);
+  return saveConfig({
+    url,
+    config: csv,
+    sortconfig: csv,
+    withconfig: ''
+  });
+}

package/src/buildAdvancedQueryParentData.ts

@@ -0,0 +1,41 @@
+import type { AdvancedQueryFieldRuntime, SearchFieldViewItem } from './types';
+
+export type AdvancedQueryParentData = Record<string, Array<Record<string, unknown>>>;
+
+/** 页头组件用的 props，不应透传到高级查询 parentdata */
+const UI_ONLY_PROP_KEYS = new Set(['options', 'labelWidth']);
+
+/**
+ * 由 advancedFields + runtime 生成高级查询 parentdata。
+ * name 必须来自 schema label（已含 customLabel），禁止业务页再手写一套文案。
+ */
+export function buildAdvancedQueryParentData(
+  advancedFields: SearchFieldViewItem[],
+  runtime: Record<string, AdvancedQueryFieldRuntime | undefined> = {}
+): AdvancedQueryParentData {
+  const parentdata: AdvancedQueryParentData = {};
+  (advancedFields || []).forEach((field) => {
+    if (!field?.key) {
+      return;
+    }
+    const runtimeItem = runtime[field.key] || {};
+    const fieldProps = field.props || {};
+    const aqProps: Record<string, unknown> = {};
+    Object.keys(fieldProps).forEach((key) => {
+      if (!UI_ONLY_PROP_KEYS.has(key)) {
+        aqProps[key] = fieldProps[key];
+      }
+    });
+    const options = Array.isArray(fieldProps.options) ? (fieldProps.options as unknown[]) : null;
+    const base: Record<string, unknown> = {
+      type: field.type,
+      name: field.label,
+      val: runtimeItem.val,
+      data: runtimeItem.data ?? options,
+      ...aqProps,
+      ...(runtimeItem.extra || {})
+    };
+    parentdata[field.key] = [base];
+  });
+  return parentdata;
+}

package/src/components/BasicSearchFields.vue

@@ -0,0 +1,175 @@
+<template>
+  <el-form ref="formRef" :model="model" :label-width="labelWidth" label-position="left">
+    <el-row :gutter="10">
+      <el-col v-for="field in fields" :key="field.key" :span="resolvedFieldSpan">
+        <slot :name="field.key" :field="field" :model="model">
+          <el-form-item :label="field.label" :prop="field.key" :label-width="resolveLabelWidth(field)">
+            <el-input
+              v-if="field.type === 'input' || field.type === 'inputNumber'"
+              v-model="model[field.key]"
+              :type="field.type === 'inputNumber' ? 'number' : 'text'"
+              clearable
+              :placeholder="field.queryPlaceholder"
+              @keyup.enter="emit('search')"
+            />
+            <el-select
+              v-else-if="field.type === 'select'"
+              v-model="model[field.key]"
+              clearable
+              filterable
+              :placeholder="field.queryPlaceholder"
+              style="width: 100%"
+              @change="emit('search')"
+            >
+              <el-option
+                v-for="opt in resolveOptions(field)"
+                :key="String(opt[resolveOptionValueKey(field)])"
+                :label="String(opt[resolveOptionLabelKey(field)] ?? '')"
+                :value="opt[resolveOptionValueKey(field)]"
+              />
+            </el-select>
+            <el-date-picker
+              v-else-if="field.type === 'time'"
+              v-model="model[field.key]"
+              type="date"
+              value-format="YYYY-MM-DD"
+              format="YYYY-MM-DD"
+              clearable
+              :placeholder="field.queryPlaceholder"
+              style="width: 100%"
+            />
+            <el-date-picker
+              v-else-if="field.type === 'daterange'"
+              v-model="model[field.key]"
+              type="daterange"
+              range-separator="至"
+              start-placeholder="开始日期"
+              end-placeholder="结束日期"
+              value-format="YYYY-MM-DD"
+              format="YYYY-MM-DD"
+              clearable
+              style="width: 100%"
+            />
+            <el-input
+              v-else
+              v-model="model[field.key]"
+              clearable
+              :placeholder="field.queryPlaceholder"
+              @keyup.enter="emit('search')"
+            />
+          </el-form-item>
+        </slot>
+      </el-col>
+
+      <el-col :span="resolvedActionsSpan">
+        <el-form-item label-width="0">
+          <slot name="actions">
+            <el-button type="primary" @click="emit('search')">查 询</el-button>
+            <el-button @click="emit('reset')">重 置</el-button>
+            <el-button v-if="showAdvanced" @click="emit('advanced')">高级查询</el-button>
+          </slot>
+        </el-form-item>
+      </el-col>
+    </el-row>
+  </el-form>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import type { SearchFieldViewItem } from '../types';
+
+interface Props {
+  /** 已排序并截取前 N 的页头字段 */
+  fields: SearchFieldViewItem[];
+  /** 查询参数对象（与 queryParams 同源） */
+  model: Record<string, any>;
+  labelWidth?: string | number;
+  /**
+   * 每个字段占位；不传则自动计算，保证字段 + 查询/重置/高级查询同一行
+   */
+  fieldSpan?: number;
+  /** 操作按钮列宽；不传则自动计算 */
+  actionsSpan?: number;
+  /**
+   * 是否展示「高级查询」按钮。
+   * 约定：可查字段总数 ≤ basicVisibleCount（页头已全展示）时传 false。
+   * 由 useSearchFieldSchema 的 showAdvancedQuery 驱动。
+   */
+  showAdvanced?: boolean;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  fields: () => [],
+  labelWidth: '80',
+  fieldSpan: undefined,
+  actionsSpan: undefined,
+  showAdvanced: true
+});
+
+const emit = defineEmits<{
+  search: [];
+  reset: [];
+  advanced: [];
+}>();
+
+const formRef = ref();
+
+const resolvedActionsSpan = computed(() => {
+  if (props.actionsSpan != null) {
+    return props.actionsSpan;
+  }
+  const count = props.fields?.length || 0;
+  if (count <= 0) {
+    return 24;
+  }
+  if (count >= 4) {
+    return 4;
+  }
+  if (count === 3) {
+    return 6;
+  }
+  return 8;
+});
+
+const resolvedFieldSpan = computed(() => {
+  if (props.fieldSpan != null) {
+    return props.fieldSpan;
+  }
+  const count = props.fields?.length || 0;
+  if (count <= 0) {
+    return 6;
+  }
+  const remain = 24 - resolvedActionsSpan.value;
+  return Math.min(6, Math.max(4, Math.floor(remain / count)));
+});
+
+const resolveOptions = (field: SearchFieldViewItem) => {
+  const options = field.props?.options;
+  return Array.isArray(options) ? options : [];
+};
+
+const resolveOptionLabelKey = (field: SearchFieldViewItem) => {
+  const fieldProps = (field.props?.props as Record<string, string> | undefined) || {};
+  return fieldProps.label || 'label';
+};
+
+const resolveOptionValueKey = (field: SearchFieldViewItem) => {
+  const fieldProps = (field.props?.props as Record<string, string> | undefined) || {};
+  return fieldProps.value || 'value';
+};
+
+const resolveLabelWidth = (field: SearchFieldViewItem) => {
+  const custom = field.props?.labelWidth;
+  if (custom != null) {
+    return custom as string | number;
+  }
+  if ((field.label || '').length >= 5) {
+    return '100px';
+  }
+  return props.labelWidth;
+};
+
+defineExpose({
+  formRef
+});
+</script>

package/src/index.ts

@@ -0,0 +1,26 @@
+export type {
+  SearchFieldType,
+  SearchFieldSchemaItem,
+  SearchFieldViewItem,
+  BasicFieldTag,
+  SearchFieldsUserTableConfigApi,
+  UseSearchFieldSchemaOptions,
+  AdvancedQueryFieldRuntime
+} from './types';
+
+export { setupSearchFields, getSearchFieldsUserTableConfigApi } from './setup';
+
+export {
+  BASIC_SEARCH_CONFIG_SUFFIX,
+  toBasicSearchConfigUrl,
+  mergeBasicSearchOrder,
+  loadBasicSearchOrder,
+  saveBasicSearchOrder
+} from './basicSearchConfig';
+
+export { useSearchFieldSchema } from './useSearchFieldSchema';
+
+export { buildAdvancedQueryParentData } from './buildAdvancedQueryParentData';
+export type { AdvancedQueryParentData } from './buildAdvancedQueryParentData';
+
+export { default as BasicSearchFields } from './components/BasicSearchFields.vue';

package/src/setup.ts

@@ -0,0 +1,26 @@
+import type { SearchFieldsUserTableConfigApi } from './types';
+
+let userTableConfigApi: SearchFieldsUserTableConfigApi | null = null;
+
+/**
+ * 子应用启动时注入 user-table-config 读写能力。
+ * 包内不依赖任一业务仓的 `@/api`。
+ */
+export function setupSearchFields(options: { userTableConfigApi: SearchFieldsUserTableConfigApi }) {
+  if (!options?.userTableConfigApi?.getConfigList || !options?.userTableConfigApi?.saveConfig) {
+    throw new Error('[@56os/search-fields] setupSearchFields 需要传入 userTableConfigApi.getConfigList / saveConfig');
+  }
+  userTableConfigApi = options.userTableConfigApi;
+}
+
+export function getSearchFieldsUserTableConfigApi(
+  override?: SearchFieldsUserTableConfigApi
+): SearchFieldsUserTableConfigApi {
+  if (override?.getConfigList && override?.saveConfig) {
+    return override;
+  }
+  if (!userTableConfigApi) {
+    throw new Error('[@56os/search-fields] 请先调用 setupSearchFields 注入 user-table-config API');
+  }
+  return userTableConfigApi;
+}

package/src/shims-vue.d.ts

@@ -0,0 +1,5 @@
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue';
+  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, any>;
+  export default component;
+}

package/src/types.ts

@@ -0,0 +1,79 @@
+/** 检索控件类型（与高级查询 parentdata.type 对齐） */
+export type SearchFieldType =
+  | 'input'
+  | 'select'
+  | 'remoteSelect'
+  | 'customerSelect'
+  | 'time'
+  | 'daterange'
+  | 'inputNumber'
+  | 'hidden';
+
+/** 页面统一定义：检索字段 schema */
+export interface SearchFieldSchemaItem {
+  /** 与 queryParams / 列表 column.value 对齐 */
+  key: string;
+  /** 默认文案；可被菜单字段 customLabel 覆盖 */
+  label: string;
+  /** 控件类型 */
+  type: SearchFieldType;
+  /**
+   * 历史字段，可保留。
+   * 当前：全部可查字段都进标签/高级查询；页头由排序位置 + basicVisibleCount 决定。
+   */
+  basicEligible?: boolean;
+  /** @deprecated 不再把字段排除在标签区外 */
+  advancedOnly?: boolean;
+  /** 占位前缀，缺省「请输入/请选择」 */
+  queryPlaceholder?: string;
+  /** 控件扩展：options、partyType、multiple、props 等 */
+  props?: Record<string, unknown>;
+  /** 平台可见性；不传则全平台 */
+  platforms?: string[];
+}
+
+/** 合并文案与排序后的视图字段 */
+export interface SearchFieldViewItem {
+  key: string;
+  label: string;
+  type: SearchFieldType;
+  basicEligible?: boolean;
+  advancedOnly?: boolean;
+  queryPlaceholder: string;
+  props?: Record<string, unknown>;
+}
+
+/** 高级查询配置区拖拽标签 */
+export interface BasicFieldTag {
+  key: string;
+  name: string;
+}
+
+/** 子应用注入的 user-table-config API（避免包内强绑 @/api） */
+export interface SearchFieldsUserTableConfigApi {
+  getConfigList: (params: { url: string }) => Promise<any>;
+  saveConfig: (data: {
+    url: string;
+    config: string;
+    sortconfig: string;
+    withconfig: string;
+  }) => Promise<any>;
+}
+
+export interface UseSearchFieldSchemaOptions {
+  pageUrl: string;
+  /** 页面查询区展示前几个，默认 4 */
+  basicVisibleCount?: number;
+  platformType?: string;
+  /** 文案解析：优先菜单 customLabel */
+  resolveLabel?: (key: string, fallback: string) => string;
+  /** 可选：覆盖全局 setup 注入的 API */
+  userTableConfigApi?: SearchFieldsUserTableConfigApi;
+}
+
+/** 生成高级查询 parentdata 时的运行时值 */
+export interface AdvancedQueryFieldRuntime {
+  val?: unknown;
+  data?: unknown[];
+  extra?: Record<string, unknown>;
+}

package/src/useSearchFieldSchema.ts

@@ -0,0 +1,131 @@
+import { computed, onMounted, ref, toValue, type MaybeRefOrGetter } from 'vue';
+import { loadBasicSearchOrder, mergeBasicSearchOrder } from './basicSearchConfig';
+import type {
+  BasicFieldTag,
+  SearchFieldSchemaItem,
+  SearchFieldViewItem,
+  UseSearchFieldSchemaOptions
+} from './types';
+
+function isPlatformVisible(item: SearchFieldSchemaItem, platformType?: string): boolean {
+  if (!item.platforms || item.platforms.length === 0) {
+    return true;
+  }
+  if (!platformType) {
+    return true;
+  }
+  return item.platforms.includes(platformType);
+}
+
+function buildPlaceholder(item: SearchFieldSchemaItem, label: string): string {
+  if (item.queryPlaceholder) {
+    return `${item.queryPlaceholder}${label}`;
+  }
+  const selectLike = item.type === 'select' || item.type === 'remoteSelect' || item.type === 'customerSelect';
+  return `${selectLike ? '请选择' : '请输入'}${label}`;
+}
+
+function toViewItem(item: SearchFieldSchemaItem, label: string): SearchFieldViewItem {
+  return {
+    key: item.key,
+    label,
+    type: item.type,
+    basicEligible: item.basicEligible !== false && !item.advancedOnly,
+    advancedOnly: item.advancedOnly === true || item.basicEligible === false,
+    queryPlaceholder: buildPlaceholder(item, label),
+    props: item.props
+  };
+}
+
+/**
+ * 合并页面 searchFieldSchema + 文案 + 用户排序。
+ * - 配置区标签 / 高级查询表单：全部可查字段，顺序一致
+ * - 页头查询区：取排序后前 N 个（默认 4）
+ */
+export function useSearchFieldSchema(
+  schema: MaybeRefOrGetter<SearchFieldSchemaItem[]>,
+  options: UseSearchFieldSchemaOptions
+) {
+  const userBasicOrder = ref<string[]>([]);
+  const orderLoaded = ref(false);
+  const basicVisibleCount = options.basicVisibleCount ?? 4;
+
+  const resolveLabel = (key: string, fallback: string) => {
+    if (typeof options.resolveLabel === 'function') {
+      return options.resolveLabel(key, fallback) || fallback;
+    }
+    return fallback;
+  };
+
+  const platformFilteredSchema = computed(() => {
+    const list = toValue(schema) || [];
+    return list.filter((item) => isPlatformVisible(item, options.platformType) && item.type !== 'hidden');
+  });
+
+  const defaultOrderKeys = computed(() => platformFilteredSchema.value.map((item) => item.key));
+
+  const orderedFields = computed<SearchFieldViewItem[]>(() => {
+    const list = platformFilteredSchema.value;
+    const map = new Map(list.map((item) => [item.key, item]));
+    const orderedKeys = mergeBasicSearchOrder(defaultOrderKeys.value, userBasicOrder.value);
+    return orderedKeys
+      .map((key) => map.get(key))
+      .filter((item): item is SearchFieldSchemaItem => !!item)
+      .map((item) => toViewItem(item, resolveLabel(item.key, item.label)));
+  });
+
+  const orderedBasicFields = orderedFields;
+
+  const visibleBasicFields = computed(() => {
+    const count = Number(basicVisibleCount);
+    if (!Number.isFinite(count) || count <= 0) {
+      return [] as SearchFieldViewItem[];
+    }
+    return orderedFields.value.slice(0, count);
+  });
+
+  const advancedFields = orderedFields;
+
+  const basicFieldTags = computed<BasicFieldTag[]>(() =>
+    orderedFields.value.map((field) => ({
+      key: field.key,
+      name: field.label
+    }))
+  );
+
+  /**
+   * 可查字段总数 ≤ 页头 N（默认 4）时，页头已展示全部字段，不提供高级查询入口。
+   * 仅当存在第 N+1 及以后的字段时才展示「高级查询」。
+   */
+  const showAdvancedQuery = computed(() => orderedFields.value.length > basicVisibleCount);
+
+  const applyOrder = (orderedKeys: string[]) => {
+    userBasicOrder.value = Array.isArray(orderedKeys) ? [...orderedKeys] : [];
+  };
+
+  const loadOrder = async () => {
+    const saved = await loadBasicSearchOrder(options.pageUrl, options.userTableConfigApi);
+    if (saved?.length) {
+      userBasicOrder.value = saved;
+    }
+    orderLoaded.value = true;
+  };
+
+  onMounted(() => {
+    loadOrder();
+  });
+
+  return {
+    userBasicOrder,
+    orderLoaded,
+    orderedFields,
+    orderedBasicFields,
+    visibleBasicFields,
+    advancedFields,
+    basicFieldTags,
+    showAdvancedQuery,
+    applyOrder,
+    loadOrder,
+    basicVisibleCount
+  };
+}