rj-grid 0.1.0 → 0.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 自研**零第三方依赖**的企业级数据网格（Vue 3 + TypeScript），功能规格对标 AG Grid：虚拟滚动、冻结列、行/列拖拽、分组透视、树形、编辑与撤销、公式引擎、SSRM 服务端行模型、主题与 i18n、打印/CSV/Excel 导出、离线自然语言查询（NLQ）。gzip 约 93 KB（不含 vue / echarts）。
 
-本仓库是该组件的**独立维护仓**：源码、单测、构建链、演示 playground、使用手册都在这里；宿主项目（如 join-cloud-vue3）经 npm 的 git URL 安装产物，不参与组件开发。
+本仓库是该组件的**独立维护仓**：源码、单测、构建链、演示 playground、使用手册都在这里；产物已发布到**公共 npm（包名 `rj-grid`）**，宿主项目（如 join-cloud-vue3）按版本号安装，不参与组件开发。
 
 ## 仓库布局
 
@@ -33,18 +33,24 @@ pnpm size      # 体积报告（可选）
 pnpm dev       # playground 演示页（默认 :5173，alias 走本地源码）
 ```
 
-改完源码的发布纪律：`pnpm build` → 让源码与 `dist/` 处在**同一个 commit** → 打 tag → push。
+发布新版本：改完源码 → `npm version patch|minor|major`（自动 bump + commit + tag）→ `git push --follow-tags` → `npm publish`（`prepublishOnly` 会自动 `pnpm build && pnpm test`，杜绝发出旧 dist）。
 
-## 宿主接入（git URL）
+## 宿主接入（npm 版本号）
 
 ```jsonc
-// 宿主 package.json
+// 宿主 package.json —— 从公共 npm 按语义化版本安装
 "dependencies": {
-  "rj-grid": "git+https://gitee.com/rjding/rj-grid.git#v0.1.0"
+  "rj-grid": "^0.1.0"
 }
 ```
 
-样式**不要**在 JS 里裸引 `rj-grid/style.css`：pnpm 会把 git 依赖装进带 `#<commit>` 的目录名，vite 输出的资源 URL 含裸 `#`，浏览器把 `#` 之后当片段丢掉 → dev 下 404。改走一层 CSS 垫片：
+```powershell
+pnpm add rj-grid           # 或 npm i rj-grid
+```
+
+> 仍保留 git URL 方式（离线内网 / 需锁 commit 时）：`"rj-grid": "git+https://gitee.com/rjding/rj-grid.git#v0.1.0"`。
+
+从 npm 安装时目录名规范（`node_modules/rj-grid`），样式可**直接**引：`import 'rj-grid/style.css'`。仅当走 git URL 时才需下面的 CSS 垫片——pnpm 会把 git 依赖装进带 `#<commit>` 的目录名，vite 输出的资源 URL 含裸 `#`，浏览器把 `#` 之后当片段丢掉 → dev 下 404：
 
 ```css
 /* 宿主 src/styles/rjgrid/index.css */
@@ -67,21 +73,21 @@ peer 依赖：`vue ^3.4.0` 必装；`echarts >=5.0.0` 可选（仅「集成图
 ## 升级与回滚
 
 ```powershell
-pnpm update rj-grid          # 跟到 URL 允许的最新 commit
-pnpm install --force         # 或改 #<tag> 后强制重装
+pnpm update rj-grid          # 在 ^0.1.0 范围内升到最新
+pnpm add rj-grid@latest      # 跨范围拉最新
 ```
 
-lockfile 里记录的是具体 commit（`specifier` 存 tag，`resolution` 存 commit），因此 CI / 他人 `pnpm install --frozen-lockfile` 可精确复现。本地联调可把 URL 临时换成 `"link:../rjGrid"`，调完记得换回 git URL 并重装。
+npm 安装的 lockfile 记录精确版本与 `integrity`，CI / 他人 `pnpm install --frozen-lockfile` 可复现。回滚只需把版本钉回旧号（如 `"rj-grid": "0.1.0"`）。本地联调可临时用 `"link:../rjGrid"`，调完换回版本号并重装。
 
 ## 为什么 dist 入库
 
-npm/pnpm 安装 git 依赖时按 `files` 字段（`["dist","README.md"]`）对仓库内容做 pack 式裁剪，**不会**在宿主机跑 `prepare` 重建。所以产物必须提交进仓库：只推源码不推 `dist/`，安装方会拿到空包。代价是 commit 里要带上产物，收益是安装期零工具链、跨机器结果一致。
+发布走 `prepublishOnly`（`pnpm build && pnpm test`）：`npm publish` 打的是**构建后磁盘上的 `dist/`**（按 `files` 字段 `["dist","README.md"]` 裁剪），所以公共 npm 消费方无需依赖仓库里的 dist。dist 仍入库只是为了兼容 **git URL 安装**那条路径（git 依赖不会在宿主机跑 `prepare` 重建）；保留 dist 入库能同时喂饱两条路。
 
 `build/rjDistCheck.mjs` 的五道守卫同时在把关：外部 import 只允许 `vue`/`echarts`；CSS 不引宿主资源；d.ts 不断链；dist 不得混入 `.vue/.ts/.scss` 源码；**不得带 sourcemap**——vite 的 `.map` 内嵌 `sourcesContent`（原始源码），一发包等于源码同步外流，因此 `vite.lib.config.ts` 里 `sourcemap: false` 是源码保护而非可选项。
 
 ## 私有仓注意
 
-本仓库为 gitee 私有仓时，安装方机器必须具备克隆凭据（HTTPS 走 credential manager 里的 gitee 账号，或改用有权限的部署密钥）；CI 环境需预先注入凭据，否则 `pnpm install` 会卡在 git 认证。
+已发布到**公共 npm**，按版本号安装无需任何 git 凭据。仅当某宿主仍走 git URL 且仓库为 gitee 私有仓时，安装机才需具备克隆凭据（HTTPS 走 credential manager 里的 gitee 账号或部署密钥），CI 需预置，否则会卡在 git 认证。
 
 ## 文档
 

package/dist/rj-grid.js

@@ -773,6 +773,22 @@ function deriveQueryFields(columns, override) {
   }
   return out;
 }
+function withCarrierOptions(fields, carrier) {
+  if (!fields.length || !carrier || !carrier.size)
+    return fields;
+  return fields.map((f) => {
+    if (f.options && f.options.length)
+      return f;
+    const hit = carrier.get(f.field);
+    if (!hit || !hit.list || !hit.list.length)
+      return f;
+    return {
+      ...f,
+      kind: "select",
+      options: hit.list.map((o) => ({ label: o.label, value: o.value }))
+    };
+  });
+}
 function queryOpsOfKind(kind) {
   if (kind === "number")
     return ["eq", "gt", "gte", "lt", "lte", "between"];
@@ -4506,6 +4522,125 @@ function translate(messages, key, params) {
 }
 const RJ_LOCALE_KEY = Symbol("rj-locale");
 const defaultTranslate = (key, params) => interpolate(zhCN[key] != null ? zhCN[key] : key, params);
+const RJ_OPTIONS_KEY = Symbol("rj-options");
+const defaultOptionsAccessor = {
+  list: () => void 0,
+  label: () => void 0
+};
+function pickValue(item, valueKey) {
+  if (valueKey)
+    return item[valueKey];
+  if (item.value !== void 0)
+    return item.value;
+  if (item.id !== void 0)
+    return item.id;
+  if (item.code !== void 0)
+    return item.code;
+  if (item.key !== void 0)
+    return item.key;
+  return void 0;
+}
+function pickLabel(item, labelKey, value) {
+  if (labelKey)
+    return String(item[labelKey] ?? value);
+  if (item.label !== void 0)
+    return String(item.label);
+  if (item.name !== void 0)
+    return String(item.name);
+  if (item.text !== void 0)
+    return String(item.text);
+  return String(value);
+}
+function normalizeOptions(raw, shape = {}) {
+  const out = [];
+  if (!Array.isArray(raw))
+    return out;
+  const ck = shape.childrenKey ?? "children";
+  const walk = (arr) => {
+    for (const it of arr) {
+      if (it == null || typeof it !== "object") {
+        if (it !== null && it !== void 0)
+          out.push({ label: String(it), value: it });
+        continue;
+      }
+      const item = it;
+      if (shape.map) {
+        out.push(shape.map(item));
+      } else {
+        const value = pickValue(item, shape.valueKey);
+        const label = pickLabel(item, shape.labelKey, value);
+        out.push({ label, value });
+      }
+      if (Array.isArray(item[ck]))
+        walk(item[ck]);
+    }
+  };
+  walk(raw);
+  return out;
+}
+async function resolveOptions(source, dict, loaders) {
+  var _a, _b, _c;
+  try {
+    if (dict)
+      return normalizeOptions(await ((_a = loaders.dictLoader) == null ? void 0 : _a.call(loaders, dict)));
+    if (!source)
+      return [];
+    if (Array.isArray(source))
+      return normalizeOptions(source);
+    if (typeof source === "function")
+      return normalizeOptions(await source());
+    const shape = source;
+    if (source.items)
+      return normalizeOptions(source.items, shape);
+    if (source.dict)
+      return normalizeOptions(await ((_b = loaders.dictLoader) == null ? void 0 : _b.call(loaders, source.dict)), shape);
+    if (source.ref)
+      return normalizeOptions(await ((_c = loaders.optionsLoader) == null ? void 0 : _c.call(loaders, source.ref)), shape);
+    if (source.load)
+      return normalizeOptions(await source.load(), shape);
+  } catch {
+  }
+  return [];
+}
+let _fnSeq = 0;
+const fnKeys = /* @__PURE__ */ new WeakMap();
+function fnKey(fn, prefix) {
+  let k = fnKeys.get(fn);
+  if (!k) {
+    k = `${prefix}:${++_fnSeq}`;
+    fnKeys.set(fn, k);
+  }
+  return k;
+}
+function sourceCacheKey(col) {
+  if (col.dict)
+    return "dict:" + col.dict;
+  const s = col.options;
+  if (!s)
+    return null;
+  if (Array.isArray(s))
+    return "static:" + colIdOf(col);
+  if (typeof s === "function")
+    return fnKey(s, "fn");
+  if (s.dict)
+    return "dict:" + s.dict;
+  if (s.ref)
+    return "ref:" + s.ref;
+  if (s.load)
+    return fnKey(s.load, "load");
+  if (s.items)
+    return "static:" + colIdOf(col);
+  return null;
+}
+function collectOptionCols(cols, out = []) {
+  for (const c of cols || []) {
+    if (c.dict || c.options)
+      out.push(c);
+    if (c.children && c.children.length)
+      collectOptionCols(c.children, out);
+  }
+  return out;
+}
 const NUM_OPS = [
   { k: "greater than or equal to", op: "gte" },
   { k: "more than or equal to", op: "gte" },
@@ -6184,6 +6319,7 @@ const _sfc_main$g = /* @__PURE__ */ defineComponent({
   emits: ["commit", "cancel"],
   setup(__props, { emit: __emit }) {
     const t = inject(RJ_LOCALE_KEY, defaultTranslate);
+    const optionsAccessor = inject(RJ_OPTIONS_KEY, defaultOptionsAccessor);
     const props = __props;
     const emit = __emit;
     const cfg = computed(() => {
@@ -6225,9 +6361,16 @@ const _sfc_main$g = /* @__PURE__ */ defineComponent({
     );
     const options = computed(() => {
       const o = cfg.value.options;
-      if (!o)
-        return [];
-      return typeof o === "function" ? o(props.row) : o;
+      if (typeof o === "function") {
+        const r = o(props.row);
+        if (Array.isArray(r) && r.length)
+          return r;
+      } else if (Array.isArray(o) && o.length) {
+        return o;
+      }
+      if (isSelectLike.value)
+        return optionsAccessor.list(props.column) || [];
+      return Array.isArray(o) ? o : [];
     });
     const filteredOptions = computed(() => {
       if (!isSelectLike.value)
@@ -6962,6 +7105,7 @@ const _sfc_main$c = /* @__PURE__ */ defineComponent({
   setup(__props, { emit: __emit }) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _i;
     const t = inject(RJ_LOCALE_KEY, defaultTranslate);
+    const optionsAccessor = inject(RJ_OPTIONS_KEY, defaultOptionsAccessor);
     const props = __props;
     const emit = __emit;
     const ops = computed(() => FILTER_OPS[props.filterType] || []);
@@ -6993,7 +7137,7 @@ const _sfc_main$c = /* @__PURE__ */ defineComponent({
     });
     const displayOf = (v) => {
       var _a2;
-      return ((_a2 = props.column.filterValueMap) == null ? void 0 : _a2[v]) ?? v;
+      return optionsAccessor.label(props.column, v) ?? ((_a2 = props.column.filterValueMap) == null ? void 0 : _a2[v]) ?? v;
     };
     const allChecked = computed(
       () => options.value.length > 0 && values.value.length >= options.value.length
@@ -9701,12 +9845,67 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     queryFields: { default: () => [] },
     queryActions: { default: () => [] },
     rowForm: { type: [Object, Boolean], default: true },
+    dictLoader: {},
+    optionsLoader: {},
     builtinViews: { default: () => [] }
   },
   emits: ["selection-change", "cell-click", "cell-dblclick", "cell-value-changed", "cells-changed", "sort-change", "filter-change", "row-group-change", "pivot-change", "page-change", "view-change", "detail-open", "row-drag-end", "row-form-submit", "row-form-add", "ready"],
   setup(__props, { expose: __expose, emit: __emit }) {
     var _a;
     const props = __props;
+    const optCache = reactive(/* @__PURE__ */ new Map());
+    async function resolveAllOptions() {
+      const pending = /* @__PURE__ */ new Map();
+      for (const col of collectOptionCols(props.columns)) {
+        const key = sourceCacheKey(col);
+        if (!key || optCache.has(key) || pending.has(key))
+          continue;
+        pending.set(key, col);
+      }
+      await Promise.all(
+        [...pending.entries()].map(async ([key, col]) => {
+          const list = await resolveOptions(col.options, col.dict, {
+            dictLoader: props.dictLoader,
+            optionsLoader: props.optionsLoader
+          });
+          optCache.set(key, list);
+        })
+      );
+    }
+    const colOptionsIndex = computed(() => {
+      const m = /* @__PURE__ */ new Map();
+      for (const col of collectOptionCols(props.columns)) {
+        const key = sourceCacheKey(col);
+        const list = key ? optCache.get(key) : void 0;
+        if (!list || !list.length)
+          continue;
+        const labelMap = /* @__PURE__ */ new Map();
+        for (const o of list)
+          labelMap.set(String(o.value), String(o.label));
+        m.set(colIdOf(col), { list, labelMap });
+      }
+      return m;
+    });
+    function colOptionList(col) {
+      var _a2;
+      return (_a2 = colOptionsIndex.value.get(colIdOf(col))) == null ? void 0 : _a2.list;
+    }
+    function colOptionLabel(col, value) {
+      var _a2;
+      if (value == null || value === "")
+        return void 0;
+      return (_a2 = colOptionsIndex.value.get(colIdOf(col))) == null ? void 0 : _a2.labelMap.get(String(value));
+    }
+    provide(RJ_OPTIONS_KEY, { list: colOptionList, label: colOptionLabel });
+    onMounted(() => {
+      void resolveAllOptions();
+    });
+    watch(
+      () => props.columns,
+      () => {
+        void resolveAllOptions();
+      }
+    );
     const emit = __emit;
     const busListeners = /* @__PURE__ */ new Map();
     function addEventListener(type, cb) {
@@ -9915,7 +10114,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     watch(pipelineCols, (v) => rowModel.setPipelineColumns(v), { immediate: true });
     const queryConditions = rowModel.queryConditions;
     const queryFieldDefs = computed(
-      () => deriveQueryFields(userColumns.value, props.queryFields)
+      () => withCarrierOptions(deriveQueryFields(userColumns.value, props.queryFields), colOptionsIndex.value)
     );
     const savedViews = useSavedViews(
       () => props.stateKey,
@@ -10588,11 +10787,16 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       const type = rowModel.filterTypeOf(col);
       let unique = [];
       if (type === "select") {
-        unique = Array.from(
-          new Set(
-            rowModel.sourceRows().slice(0, 5e3).map((r) => cellRawValue(col, r)).filter((v) => v != null)
-          )
-        ).map(String);
+        const optList = colOptionList(col);
+        if (optList && optList.length) {
+          unique = optList.map((o) => String(o.value));
+        } else {
+          unique = Array.from(
+            new Set(
+              rowModel.sourceRows().slice(0, 5e3).map((r) => cellRawValue(col, r)).filter((v) => v != null)
+            )
+          ).map(String);
+        }
       }
       const targetRect = el.target.getBoundingClientRect();
       const rootRect = (_a2 = rootRef.value) == null ? void 0 : _a2.getBoundingClientRect();
@@ -11090,6 +11294,9 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
           return formatByType(col, value, BOOL_LABELS.value);
         return s;
       }
+      const lab = colOptionLabel(col, value);
+      if (lab != null)
+        return lab;
       return formatByType(col, value, BOOL_LABELS.value);
     }
     function coveredByRowSpan(rows, i, leaf) {
@@ -12154,11 +12361,16 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       const type = rowModel.filterTypeOf(col);
       let unique = [];
       if (type === "select") {
-        unique = Array.from(
-          new Set(
-            rowModel.sourceRows().slice(0, 5e3).map((r) => cellRawValue(col, r)).filter((v) => v != null)
-          )
-        ).map(String);
+        const optList = colOptionList(col);
+        if (optList && optList.length) {
+          unique = optList.map((o) => String(o.value));
+        } else {
+          unique = Array.from(
+            new Set(
+              rowModel.sourceRows().slice(0, 5e3).map((r) => cellRawValue(col, r)).filter((v) => v != null)
+            )
+          ).map(String);
+        }
       }
       const ss = rowModel.sortStates.value.find((x) => x.field === colId || x.field === col.field);
       colMenu.value = {
@@ -12774,10 +12986,15 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
           filterType = "select";
         let options;
         let strictOptions = false;
+        const resolvedOpts = colOptionList(col);
         if (Array.isArray(eo) && eo.length) {
           filterType = "select";
           options = eo.map((o) => String((o == null ? void 0 : o.label) ?? (o == null ? void 0 : o.value) ?? o));
           strictOptions = true;
+        } else if (resolvedOpts && resolvedOpts.length) {
+          filterType = "select";
+          options = resolvedOpts.map((o) => String(o.label ?? o.value));
+          strictOptions = true;
         } else if (filterType === "select") {
           const set = /* @__PURE__ */ new Set();
           for (const r of src) {

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 import RjGrid from './src/RjGrid.vue';
 export { RjGrid };
-export type { RjColumn, RjRowData, RjCellParams, RjGridApi, RjGridState, RjDataMode, RjLoadServerParams, RjLoadServerResult, RjFilterModel, RjFilterCondition, RjFilterType, RjSortState, RjSortDir, RjFixed, RjMenuItem, RjMenuContext, RjCellEventParams, RjSelectionEventParams, RjPinnedRow, RjFindMatch, RjEditorType, RjEditorConfig, RjEditorOption, RjImageConfig, RjSparklineConfig, RjColStateItem, RjColumnFilterState, RjExportScope, RjExportScopeResolved, RjServerExportParams, RjTransaction, RjExportParams, RjPrintOptions, RjPrintParams, RjAgg, RjAggFunc, RjAggCustom, RjQueryCondition, RjQueryFieldDef, RjQueryFieldKind, RjQueryOperator, RjQueryAction, RjQueryActionCtx, RjRowFormConfig, RjSavedView } from './src/types';
+export type { RjColumn, RjRowData, RjCellParams, RjGridApi, RjGridState, RjDataMode, RjLoadServerParams, RjLoadServerResult, RjFilterModel, RjFilterCondition, RjFilterType, RjSortState, RjSortDir, RjFixed, RjMenuItem, RjMenuContext, RjCellEventParams, RjSelectionEventParams, RjPinnedRow, RjFindMatch, RjEditorType, RjEditorConfig, RjEditorOption, RjOptionSource, RjImageConfig, RjSparklineConfig, RjColStateItem, RjColumnFilterState, RjExportScope, RjExportScopeResolved, RjServerExportParams, RjTransaction, RjExportParams, RjPrintOptions, RjPrintParams, RjAgg, RjAggFunc, RjAggCustom, RjQueryCondition, RjQueryFieldDef, RjQueryFieldKind, RjQueryOperator, RjQueryAction, RjQueryActionCtx, RjRowFormConfig, RjSavedView } from './src/types';
 export type { RjThemeParams } from './src/theme';
 export type { RjIconName, RjIcons, RjIconsOverride } from './src/icons';
 export { deriveQueryFields, queryOpsOfKind, defaultQueryOperator, matchQueryValue } from './src/query';

package/dist/types/src/RjGrid.vue.d.ts

@@ -1,5 +1,5 @@
 import './styles/rj-grid.scss';
-import type { RjCellParams, RjColumn, RjDataMode, RjExportScopeResolved, RjFilterModel, RjGridState, RjLoadServerParams, RjMenuItem, RjPrintParams, RjRowData, RjServerExportParams, RjSortState, RjTransaction, RjQueryAction, RjQueryFieldDef, RjRowFormConfig, RjSavedView } from './types';
+import type { RjCellParams, RjColumn, RjDataMode, RjEditorOption, RjExportScopeResolved, RjFilterModel, RjGridState, RjLoadServerParams, RjMenuItem, RjPrintParams, RjRowData, RjServerExportParams, RjSortState, RjTransaction, RjQueryAction, RjQueryFieldDef, RjRowFormConfig, RjSavedView } from './types';
 import { type RjDisplayRow } from './useRowModel';
 import { type RjThemeParams } from './theme';
 import { type RjMessages } from './locale';
@@ -129,6 +129,10 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<im
     queryActions?: RjQueryAction[] | undefined;
     /** 内置行编辑/新增弹窗：false 关闭 openRowForm/openRowFormAdd 能力；对象可配 title/width/columns 与 addTitle/addColumns */
     rowForm?: boolean | RjRowFormConfig | undefined;
+    /** 网格级字典加载器：列上 dict:'x'（或 options:{dict:'x'}）时调用，返回 {label,value}[] 或原始数组（异步可） */
+    dictLoader?: ((key: string) => RjEditorOption[] | Promise<RjEditorOption[]>) | undefined;
+    /** 网格级命名源加载器：列上 options:{ref:'name'} 时调用，返回接口原始数组（异步可），字段归一交给列上的 labelKey/valueKey/map */
+    optionsLoader?: ((name: string) => unknown[] | Promise<unknown[]>) | undefined;
     /** 内置视图（只读，恒排在自建视图前） */
     builtinViews?: RjSavedView[] | undefined;
 }>, {
@@ -332,6 +336,10 @@ declare const _default: __VLS_WithTemplateSlots<import("vue").DefineComponent<im
     queryActions?: RjQueryAction[] | undefined;
     /** 内置行编辑/新增弹窗：false 关闭 openRowForm/openRowFormAdd 能力；对象可配 title/width/columns 与 addTitle/addColumns */
     rowForm?: boolean | RjRowFormConfig | undefined;
+    /** 网格级字典加载器：列上 dict:'x'（或 options:{dict:'x'}）时调用，返回 {label,value}[] 或原始数组（异步可） */
+    dictLoader?: ((key: string) => RjEditorOption[] | Promise<RjEditorOption[]>) | undefined;
+    /** 网格级命名源加载器：列上 options:{ref:'name'} 时调用，返回接口原始数组（异步可），字段归一交给列上的 labelKey/valueKey/map */
+    optionsLoader?: ((name: string) => unknown[] | Promise<unknown[]>) | undefined;
     /** 内置视图（只读，恒排在自建视图前） */
     builtinViews?: RjSavedView[] | undefined;
 }>, {

package/dist/types/src/optionsSource.d.ts

@@ -0,0 +1,42 @@
+import type { InjectionKey } from 'vue';
+import type { RjColumn, RjEditorOption, RjOptionSource } from './types';
+/** 列字段归一选项（对象式源携带 map/labelKey/valueKey/childrenKey 时生效） */
+interface RjOptionShape {
+    map?: (item: any) => RjEditorOption;
+    labelKey?: string;
+    valueKey?: string;
+    childrenKey?: string;
+}
+/** 网格注入给子组件（RjEditor / RjFilterMenu）的只读访问器 */
+export interface RjOptionsAccessor {
+    /** 该列解析出的候选；未就绪或未声明时 undefined */
+    list: (col: RjColumn) => RjEditorOption[] | undefined;
+    /** 该列 value→label；未命中时 undefined */
+    label: (col: RjColumn, value: any) => string | undefined;
+}
+/** 注入键：网格根 provide 访问器，子组件 inject 消费（仿 RJ_LOCALE_KEY / RJ_ICONS_KEY） */
+export declare const RJ_OPTIONS_KEY: InjectionKey<RjOptionsAccessor>;
+/** 子组件默认访问器（单独使用、未 inject 到时回退，全部返回 undefined 不影响原行为） */
+export declare const defaultOptionsAccessor: RjOptionsAccessor;
+/**
+ * 把任意接口返回归一成 RjEditorOption[]：
+ * - map 命中优先（完全自定义）；
+ * - 否则按 labelKey/valueKey（或默认字段）取；
+ * - childrenKey（默认 'children'）命中数组即递归拍平（depth 缩进不写进 label，保持干净 value→label 表）。
+ */
+export declare function normalizeOptions(raw: unknown, shape?: RjOptionShape): RjEditorOption[];
+/** 解析选项源所需的网格级加载器 */
+export interface RjOptionLoaders {
+    dictLoader?: (key: string) => unknown | Promise<unknown>;
+    optionsLoader?: (name: string) => unknown | Promise<unknown>;
+}
+/** 解析一个列的选项源为候选数组（异步；失败静默回落空数组 → 显示原样回落原始值） */
+export declare function resolveOptions(source: RjOptionSource | undefined, dict: string | undefined, loaders: RjOptionLoaders): Promise<RjEditorOption[]>;
+/**
+ * 计算列选项源的缓存键：dict/ref 按 key 归并（两列同字典只加载一次），
+ * 静态数组 / 函数按列或函数身份。返回 null 表示该列无选项载体。
+ */
+export declare function sourceCacheKey(col: RjColumn): string | null;
+/** 递归收集声明了 options/dict 的列（含多级表头子列） */
+export declare function collectOptionCols(cols: RjColumn[], out?: RjColumn[]): RjColumn[];
+export {};

package/dist/types/src/query.d.ts

@@ -9,6 +9,14 @@ export declare function optionsOfColumn(col: RjColumn): RjEditorOption[];
  * - 用 override 覆盖标题、类别或候选（宿主可为枚举列补 options）。
  */
 export declare function deriveQueryFields(columns: RjColumn[], override?: RjQueryFieldDef[]): RjQueryFieldDef[];
+/**
+ * 把统一选项载体（异步解析出的候选）并入查询字段池：仅在该字段自身无候选
+ * （editor.options / filterValueMap / override 都缺位）时，用载体候选填充并升级为 select 类别。
+ * 向后兼容：已有 options 的字段原样保留；carrier 未命中/为空不动。carrier 以 colIdOf 为键。
+ */
+export declare function withCarrierOptions(fields: RjQueryFieldDef[], carrier: Map<string, {
+    list: RjEditorOption[];
+}>): RjQueryFieldDef[];
 /** 各类别对应的合理运算符集合 */
 export declare function queryOpsOfKind(kind: RjQueryFieldKind): RjQueryOperator[];
 /** 新增字段时的默认运算符（取该类别最常用的一项） */

package/dist/types/src/types.d.ts

@@ -109,6 +109,28 @@ export interface RjEditorOption {
     label: string;
     value: any;
 }
+/**
+ * 统一选项载体：一份数据源同时驱动 显示(value→label) / select 筛选候选 / select 编辑器 / NLQ 枚举。
+ * 数组＝静态候选；函数＝工厂（可同步/异步，网格级按列只解析一次）；对象＝按 load/ref/dict 取数，
+ * 再用 map 或 labelKey/valueKey 归一，childrenKey（默认 'children'）命中即递归拍平树（label 不加缩进）。
+ */
+export type RjOptionSource = RjEditorOption[] | ((row?: RjRowData) => RjEditorOption[] | Promise<RjEditorOption[]>) | {
+    /** 静态候选（对象式） */
+    items?: RjEditorOption[];
+    /** 宿主直接给的接口函数（返回原始数组，交给 labelKey/valueKey/map 归一） */
+    load?: () => unknown[] | Promise<unknown[]>;
+    /** 命名源：交网格级 optionsLoader(name) 解析 */
+    ref?: string;
+    /** 字典 key：交网格级 dictLoader(key) 解析 */
+    dict?: string;
+    /** 自定义映射：接口单项 → {label,value} */
+    map?: (item: any) => RjEditorOption;
+    /** 字段映射（默认 label/name → label，value/id/code → value） */
+    labelKey?: string;
+    valueKey?: string;
+    /** 传入即递归拍平树（默认 'children'） */
+    childrenKey?: string;
+};
 /** 编辑器配置 */
 export interface RjEditorConfig {
     type?: RjEditorType;
@@ -223,6 +245,13 @@ export interface RjColumn<T = RjRowData> {
     headerComponent?: any;
     editable?: boolean | ((row: T) => boolean);
     editor?: RjEditorConfig | RjEditorType;
+    /**
+     * 统一选项载体：一处声明同时喂给 显示 / select 筛选 / select 编辑器 / NLQ（异步自动加载 + 按源缓存）。
+     * 向后兼容：显式 col.formatter / editor.options / filterValueMap 一律优先，本载体仅在其缺位时填充。
+     */
+    options?: RjOptionSource;
+    /** options 的糖：等价 options:{dict}，走网格级 dictLoader 按字典 key 取候选 */
+    dict?: string;
     /** 编辑值新旧合并钩子 */
     onCellValueChanged?: (params: {
         newValue: any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rj-grid",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "零第三方依赖的自研 Vue3 虚拟表格：虚拟滚动 / 冻结列 / 行拖拽 / 分组透视 / 公式 / SSRM / 主题 i18n / 自然语言查询",
   "type": "module",
   "license": "MIT",