@origen-ui/admin-cli 2.0.2 → 3.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (892) hide show
  1. package/README.md +25 -12
  2. package/bin/contract-sync.mjs +112 -0
  3. package/bin/lib/errors.mjs +8 -0
  4. package/bin/lib/fs-json.mjs +18 -0
  5. package/bin/lib/hash.mjs +9 -0
  6. package/bin/og-admin.mjs +165 -35
  7. package/bin/sync-project.mjs +717 -0
  8. package/package.json +21 -18
  9. package/templates/current/clean/.agents/skills/admin-component-usage/SKILL.md +27 -0
  10. package/templates/current/clean/.agents/skills/admin-component-usage/references/component-directory.md +232 -0
  11. package/templates/current/clean/.agents/skills/build-admin-feature/SKILL.md +20 -0
  12. package/templates/current/clean/.agents/skills/build-admin-feature/references/component-selection.md +42 -0
  13. package/templates/current/{examples/.codex → clean/.agents}/skills/use-og-form/SKILL.md +1 -1
  14. package/templates/current/{examples/.codex → clean/.agents}/skills/use-og-form-table/SKILL.md +4 -3
  15. package/templates/current/clean/{.codex → .agents}/skills/use-og-search/SKILL.md +3 -3
  16. package/templates/current/clean/.agents/skills/use-og-table/SKILL.md +22 -0
  17. package/templates/current/{examples/.codex → clean/.agents}/skills/use-og-upload/SKILL.md +6 -5
  18. package/templates/current/clean/.api-client-e2e.config.ts +13 -0
  19. package/templates/current/clean/.claude/rules/01-feature-architecture.md +10 -0
  20. package/templates/current/clean/.claude/rules/02-vue-typescript.md +10 -0
  21. package/templates/current/clean/.claude/rules/03-component-policy.md +31 -0
  22. package/templates/current/clean/.claude/rules/04-api-auth-router.md +10 -0
  23. package/templates/current/clean/.claude/rules/05-style.md +10 -0
  24. package/templates/current/clean/.claude/rules/06-quality.md +10 -0
  25. package/templates/current/clean/.claude/skills/admin-component-usage/SKILL.md +27 -0
  26. package/templates/current/clean/.claude/skills/admin-component-usage/references/component-directory.md +232 -0
  27. package/templates/current/clean/.claude/skills/build-admin-feature/SKILL.md +20 -0
  28. package/templates/current/clean/.claude/skills/build-admin-feature/references/component-selection.md +42 -0
  29. package/templates/current/clean/{.codex → .claude}/skills/use-og-form/SKILL.md +1 -1
  30. package/templates/current/clean/{.codex → .claude}/skills/use-og-form-table/SKILL.md +4 -3
  31. package/templates/current/{examples/.codex → clean/.claude}/skills/use-og-search/SKILL.md +3 -3
  32. package/templates/current/clean/.claude/skills/use-og-table/SKILL.md +22 -0
  33. package/templates/current/clean/{.codex → .claude}/skills/use-og-upload/SKILL.md +6 -5
  34. package/templates/current/clean/.codebuddy/rules/01-feature-architecture.md +2 -2
  35. package/templates/current/clean/.codebuddy/rules/03-component-policy.md +4 -1
  36. package/templates/current/clean/.codebuddy/skills/admin-component-usage/SKILL.md +30 -0
  37. package/templates/current/clean/.codebuddy/skills/admin-component-usage/references/component-directory.md +232 -0
  38. package/templates/current/clean/.codebuddy/skills/build-admin-feature/SKILL.md +11 -5
  39. package/templates/current/clean/.codebuddy/skills/build-admin-feature/references/component-selection.md +42 -0
  40. package/templates/current/clean/.codebuddy/skills/use-og-form/SKILL.md +1 -1
  41. package/templates/current/clean/.codebuddy/skills/use-og-form-table/SKILL.md +4 -3
  42. package/templates/current/clean/.codebuddy/skills/use-og-search/SKILL.md +3 -3
  43. package/templates/current/clean/.codebuddy/skills/use-og-table/SKILL.md +16 -10
  44. package/templates/current/clean/.codebuddy/skills/use-og-upload/SKILL.md +6 -5
  45. package/templates/current/clean/.codex/AGENTS.md +55 -8
  46. package/templates/current/clean/.codex/rules/01-feature-architecture.md +2 -2
  47. package/templates/current/clean/.codex/rules/03-component-policy.md +4 -1
  48. package/templates/current/clean/.cursor/rules/.generated +5 -0
  49. package/templates/current/clean/.cursor/rules/01-feature-architecture.mdc +2 -2
  50. package/templates/current/clean/.cursor/rules/03-component-policy.mdc +4 -1
  51. package/templates/current/clean/.cursor/skills/admin-component-usage/SKILL.md +27 -0
  52. package/templates/current/clean/.cursor/skills/admin-component-usage/references/component-directory.md +232 -0
  53. package/templates/current/clean/.cursor/skills/build-admin-feature/SKILL.md +11 -5
  54. package/templates/current/clean/.cursor/skills/build-admin-feature/references/component-selection.md +42 -0
  55. package/templates/current/clean/.cursor/skills/use-og-form/SKILL.md +1 -1
  56. package/templates/current/clean/.cursor/skills/use-og-form-table/SKILL.md +4 -3
  57. package/templates/current/clean/.cursor/skills/use-og-search/SKILL.md +3 -3
  58. package/templates/current/clean/.cursor/skills/use-og-table/SKILL.md +16 -10
  59. package/templates/current/clean/.cursor/skills/use-og-upload/SKILL.md +6 -5
  60. package/templates/current/clean/{.env.example → .env.dev} +3 -2
  61. package/templates/current/clean/.env.mock +4 -0
  62. package/templates/current/clean/.env.production +5 -0
  63. package/templates/current/clean/.env.test +4 -0
  64. package/templates/current/clean/.prettierignore +28 -0
  65. package/templates/current/clean/.prettierrc +8 -0
  66. package/templates/current/clean/.qoder/rules/01-feature-architecture.md +3 -4
  67. package/templates/current/clean/.qoder/rules/02-vue-typescript.md +1 -2
  68. package/templates/current/clean/.qoder/rules/03-component-policy.md +5 -3
  69. package/templates/current/clean/.qoder/rules/04-api-auth-router.md +1 -2
  70. package/templates/current/clean/.qoder/rules/05-style.md +1 -2
  71. package/templates/current/clean/.qoder/rules/06-quality.md +1 -2
  72. package/templates/current/clean/.qoder/skills/admin-component-usage/SKILL.md +27 -0
  73. package/templates/current/clean/.qoder/skills/admin-component-usage/references/component-directory.md +232 -0
  74. package/templates/current/clean/.qoder/skills/build-admin-feature/SKILL.md +11 -5
  75. package/templates/current/clean/.qoder/skills/build-admin-feature/references/component-selection.md +42 -0
  76. package/templates/current/clean/.qoder/skills/use-og-form/SKILL.md +1 -1
  77. package/templates/current/clean/.qoder/skills/use-og-form-table/SKILL.md +4 -3
  78. package/templates/current/clean/.qoder/skills/use-og-search/SKILL.md +3 -3
  79. package/templates/current/clean/.qoder/skills/use-og-table/SKILL.md +16 -10
  80. package/templates/current/clean/.qoder/skills/use-og-upload/SKILL.md +6 -5
  81. package/templates/current/clean/.zcode/skills/admin-component-usage/SKILL.md +27 -0
  82. package/templates/current/clean/.zcode/skills/admin-component-usage/references/component-directory.md +232 -0
  83. package/templates/current/clean/.zcode/skills/build-admin-feature/SKILL.md +20 -0
  84. package/templates/current/clean/.zcode/skills/build-admin-feature/references/component-selection.md +42 -0
  85. package/templates/current/clean/.zcode/skills/style-og-origen-ui/SKILL.md +11 -0
  86. package/templates/current/clean/.zcode/skills/use-og-dialog/SKILL.md +12 -0
  87. package/templates/current/clean/.zcode/skills/use-og-editor/SKILL.md +25 -0
  88. package/templates/current/clean/.zcode/skills/use-og-form/SKILL.md +12 -0
  89. package/templates/current/clean/.zcode/skills/use-og-form-table/SKILL.md +26 -0
  90. package/templates/current/clean/.zcode/skills/use-og-http/SKILL.md +13 -0
  91. package/templates/current/clean/.zcode/skills/use-og-router-tabs/SKILL.md +11 -0
  92. package/templates/current/clean/.zcode/skills/use-og-search/SKILL.md +14 -0
  93. package/templates/current/clean/.zcode/skills/use-og-table/SKILL.md +22 -0
  94. package/templates/current/clean/.zcode/skills/use-og-upload/SKILL.md +26 -0
  95. package/templates/current/clean/AGENTS.md +55 -9
  96. package/templates/current/clean/CHANGELOG.md +128 -0
  97. package/templates/current/clean/CLAUDE.md +3 -0
  98. package/templates/current/clean/README.md +58 -88
  99. package/templates/current/clean/component-catalog.json +766 -348
  100. package/templates/current/clean/component-catalog.v2.json +2040 -0
  101. package/templates/current/clean/docs/components/dialog.md +405 -0
  102. package/templates/current/clean/docs/components/editor-viewer.md +87 -0
  103. package/templates/current/clean/docs/components/editor.md +275 -0
  104. package/templates/current/clean/docs/components/form-table.md +222 -0
  105. package/templates/current/clean/docs/components/form.md +750 -0
  106. package/templates/current/clean/docs/components/index.md +44 -0
  107. package/templates/current/clean/docs/components/router.md +452 -0
  108. package/templates/current/clean/docs/components/search.md +1205 -0
  109. package/templates/current/clean/docs/components/svg-icon.md +124 -0
  110. package/templates/current/clean/docs/components/table-local.md +176 -0
  111. package/templates/current/clean/docs/components/table-with-search.md +207 -0
  112. package/templates/current/clean/docs/components/table.md +813 -0
  113. package/templates/current/clean/docs/components/tabs.md +440 -0
  114. package/templates/current/clean/docs/components/upload.md +349 -0
  115. package/templates/current/clean/eslint.config.js +89 -0
  116. package/templates/current/clean/index.html +1 -1
  117. package/templates/current/clean/openapi.json +10048 -999
  118. package/templates/current/clean/package.json +47 -35
  119. package/templates/current/clean/playwright.config.ts +20 -6
  120. package/templates/current/clean/playwright.mock.config.ts +42 -0
  121. package/templates/current/clean/pnpm-workspace.yaml +19 -3
  122. package/templates/current/clean/recipes/remote-crud-dialog-form.vue +15 -13
  123. package/templates/current/clean/scaffold.lock.json +164 -4
  124. package/templates/current/clean/scripts/api-codegen.config.ts +35 -0
  125. package/templates/current/clean/scripts/api-codegen.ts +2015 -0
  126. package/templates/current/clean/scripts/api-templates/http-client.ejs +359 -0
  127. package/templates/current/clean/scripts/check-admin-scaffold.mjs +315 -30
  128. package/templates/current/clean/scripts/generate-api.ts +290 -85
  129. package/templates/current/clean/scripts/lib/admin-component-catalog.mjs +514 -0
  130. package/templates/current/clean/scripts/lib/admin-skill-inventory.mjs +18 -0
  131. package/templates/current/clean/scripts/lib/repository-root.mjs +9 -0
  132. package/templates/current/clean/scripts/mock-api.ts +1356 -0
  133. package/templates/current/clean/scripts/remove-examples.mjs +9 -34
  134. package/templates/current/clean/src/App.vue +9 -18
  135. package/templates/current/clean/src/api/generated/data-contracts.ts +23 -265
  136. package/templates/current/clean/src/api/generated/http-client.ts +351 -180
  137. package/templates/current/clean/src/api/generated/index.ts +22 -0
  138. package/templates/current/clean/src/api/generated/services/auth.ts +123 -0
  139. package/templates/current/clean/src/api/generated/services/common/files.ts +111 -0
  140. package/templates/current/clean/src/api/generated/services/monitor/cache.ts +164 -0
  141. package/templates/current/clean/src/api/generated/services/monitor/job.ts +195 -0
  142. package/templates/current/clean/src/api/generated/services/monitor/jobLog.ts +126 -0
  143. package/templates/current/clean/src/api/generated/services/monitor/logininfor.ts +126 -0
  144. package/templates/current/clean/src/api/generated/services/monitor/online.ts +66 -0
  145. package/templates/current/clean/src/api/generated/services/monitor/operlog.ts +106 -0
  146. package/templates/current/clean/src/api/generated/services/monitor/server.ts +41 -0
  147. package/templates/current/clean/src/api/generated/services/system/configs.ts +190 -0
  148. package/templates/current/clean/src/api/generated/services/system/departments.ts +173 -0
  149. package/templates/current/clean/src/api/generated/services/system/dictionaries/data.ts +169 -0
  150. package/templates/current/clean/src/api/generated/services/system/dictionaries/types.ts +187 -0
  151. package/templates/current/clean/src/api/generated/services/system/index.ts +158 -0
  152. package/templates/current/clean/src/api/generated/services/system/menus.ts +193 -0
  153. package/templates/current/clean/src/api/generated/services/system/notices.ts +221 -0
  154. package/templates/current/clean/src/api/generated/services/system/posts.ts +168 -0
  155. package/templates/current/clean/src/api/generated/services/system/roles.ts +354 -0
  156. package/templates/current/clean/src/api/generated/services/system/users.ts +425 -0
  157. package/templates/current/clean/src/api/generated/services/tool/code-generator.ts +304 -0
  158. package/templates/current/clean/src/api/generated/types/auth.types.ts +132 -0
  159. package/templates/current/clean/src/api/generated/types/common/files.types.ts +57 -0
  160. package/templates/current/clean/src/api/generated/types/common.ts +174 -0
  161. package/templates/current/clean/src/api/generated/types/enum-dict.ts +94 -0
  162. package/templates/current/clean/src/api/generated/types/enums.ts +155 -0
  163. package/templates/current/clean/src/api/generated/types/monitor/cache.types.ts +149 -0
  164. package/templates/current/clean/src/api/generated/types/monitor/job.types.ts +207 -0
  165. package/templates/current/clean/src/api/generated/types/monitor/jobLog.types.ts +134 -0
  166. package/templates/current/clean/src/api/generated/types/monitor/logininfor.types.ts +135 -0
  167. package/templates/current/clean/src/api/generated/types/monitor/online.types.ts +80 -0
  168. package/templates/current/clean/src/api/generated/types/monitor/operlog.types.ts +126 -0
  169. package/templates/current/clean/src/api/generated/types/monitor/server.types.ts +205 -0
  170. package/templates/current/clean/src/api/generated/types/system/configs.types.ts +200 -0
  171. package/templates/current/clean/src/api/generated/types/system/departments.types.ts +145 -0
  172. package/templates/current/clean/src/api/generated/types/system/dictionaries/data.types.ts +210 -0
  173. package/templates/current/clean/src/api/generated/types/system/dictionaries/types.types.ts +221 -0
  174. package/templates/current/clean/src/api/generated/types/system/index.types.ts +19 -0
  175. package/templates/current/clean/src/api/generated/types/system/menus.types.ts +234 -0
  176. package/templates/current/clean/src/api/generated/types/system/notices.types.ts +270 -0
  177. package/templates/current/clean/src/api/generated/types/system/posts.types.ts +198 -0
  178. package/templates/current/clean/src/api/generated/types/system/roles.types.ts +410 -0
  179. package/templates/current/clean/src/api/generated/types/system/users.types.ts +413 -0
  180. package/templates/current/clean/src/api/generated/types/tool/code-generator.types.ts +388 -0
  181. package/templates/current/clean/src/api/index.ts +44 -39
  182. package/templates/current/clean/src/app/__tests__/api-generated.types.ts +24 -0
  183. package/templates/current/clean/src/app/api.ts +6 -0
  184. package/templates/current/clean/src/app/authorization/permission.ts +9 -0
  185. package/templates/current/{examples/src/app → clean/src/app/config}/runtimeConfig.ts +44 -12
  186. package/templates/current/clean/src/app/errors/errorMessage.ts +80 -0
  187. package/templates/current/clean/src/app/http/client.ts +141 -0
  188. package/templates/current/clean/src/app/http/http-adapter.ts +71 -0
  189. package/templates/current/{examples/src/app → clean/src/app/i18n}/adminLocale.ts +25 -19
  190. package/templates/current/clean/src/app/{localeFormat.ts → i18n/localeFormat.ts} +29 -6
  191. package/templates/current/clean/src/app/i18n/origenUiLocale.ts +15 -0
  192. package/templates/current/clean/src/app/menu/menu.ts +175 -0
  193. package/templates/current/clean/src/app/menu/menuTypes.ts +20 -0
  194. package/templates/current/clean/src/{features → app}/security/devtoolsProtection.ts +8 -7
  195. package/templates/current/clean/src/app/ui/createAdminUi.ts +31 -0
  196. package/templates/current/clean/src/app/ui/iconCatalog.ts +71 -0
  197. package/templates/current/clean/src/assets/icons/appearance.svg +1 -0
  198. package/templates/current/clean/src/assets/icons/arrow-right.svg +1 -0
  199. package/templates/current/clean/src/assets/icons/check.svg +1 -0
  200. package/templates/current/clean/src/assets/icons/circle-check.svg +1 -0
  201. package/templates/current/clean/src/assets/icons/default.svg +4 -0
  202. package/templates/current/clean/src/assets/icons/directory/setting.svg +1 -0
  203. package/templates/current/clean/src/assets/icons/expand.svg +1 -0
  204. package/templates/current/clean/src/assets/icons/fold.svg +1 -0
  205. package/templates/current/clean/src/assets/icons/key.svg +1 -0
  206. package/templates/current/clean/src/assets/icons/lock.svg +1 -0
  207. package/templates/current/clean/src/assets/icons/monitor.svg +1 -0
  208. package/templates/current/clean/src/assets/icons/moon.svg +11 -0
  209. package/templates/current/clean/src/assets/icons/page/department.svg +1 -0
  210. package/templates/current/clean/src/assets/icons/page/dictionary.svg +1 -0
  211. package/templates/current/clean/src/assets/icons/page/menus.svg +1 -0
  212. package/templates/current/clean/src/assets/icons/page/user.svg +1 -0
  213. package/templates/current/clean/src/assets/icons/page/users.svg +1 -0
  214. package/templates/current/clean/src/assets/icons/plus.svg +1 -0
  215. package/templates/current/clean/src/assets/icons/profile.svg +1 -0
  216. package/templates/current/clean/src/assets/icons/refresh.svg +1 -0
  217. package/templates/current/clean/src/assets/icons/roles.svg +1 -0
  218. package/templates/current/clean/src/assets/icons/search.svg +1 -0
  219. package/templates/current/clean/src/assets/icons/sunny.svg +1 -0
  220. package/templates/current/clean/src/assets/icons/system.svg +1 -0
  221. package/templates/current/clean/src/assets/icons/theme-auto.svg +14 -0
  222. package/templates/current/clean/src/assets/icons/tune.svg +13 -0
  223. package/templates/current/clean/src/{features/shell/components → components}/RouteProgress.vue +2 -2
  224. package/templates/current/{examples/src/features/system/access → clean/src}/composables/useAuthorizationRefresh.ts +6 -1
  225. package/templates/current/clean/src/composables/useSystemTableSearchVisibility.ts +33 -0
  226. package/templates/current/clean/src/{features/appearance/composables → composables}/useTheme.ts +1 -1
  227. package/templates/current/clean/src/env.d.ts +6 -19
  228. package/templates/current/clean/src/layouts/AdminLayout.vue +7 -9
  229. package/templates/current/clean/src/{features/shell/components → layouts}/AdminWatermark.vue +2 -2
  230. package/templates/current/clean/src/layouts/BreadcrumbBar.vue +9 -1
  231. package/templates/current/clean/src/layouts/SideMenu.vue +7 -15
  232. package/templates/current/clean/src/{features/appearance/components → layouts}/ThemePanel.vue +39 -11
  233. package/templates/current/clean/src/layouts/TopBar.vue +60 -28
  234. package/templates/current/clean/src/layouts/WorkspaceTabs.vue +10 -1
  235. package/templates/current/clean/src/layouts/topBarMenuSearch.ts +25 -4
  236. package/templates/current/clean/src/locales/en-US.json +227 -219
  237. package/templates/current/clean/src/locales/index.ts +72 -32
  238. package/templates/current/clean/src/locales/messages-types.ts +15 -10
  239. package/templates/current/clean/src/locales/vue-i18n.d.ts +1 -1
  240. package/templates/current/clean/src/locales/zh-CN.json +226 -218
  241. package/templates/current/clean/src/locales/zh-TW.json +222 -214
  242. package/templates/current/clean/src/main.ts +59 -30
  243. package/templates/current/clean/src/router/bootstrap.ts +69 -24
  244. package/templates/current/clean/src/router/dynamic/componentLoader.ts +150 -0
  245. package/templates/current/clean/src/router/{dynamicMenuRefresh.ts → dynamic/dynamicMenuRefresh.ts} +6 -2
  246. package/templates/current/clean/src/router/dynamic/dynamicRoutes.ts +247 -0
  247. package/templates/current/clean/src/router/navigation/guards.ts +12 -0
  248. package/templates/current/clean/src/router/navigation/paths.ts +28 -0
  249. package/templates/current/clean/src/router/navigation/staticRoutes.ts +109 -0
  250. package/templates/current/clean/src/router/{queryEncryption.ts → query/queryEncryption.ts} +29 -12
  251. package/templates/current/clean/src/router/query/routeQuery.ts +29 -0
  252. package/templates/current/clean/src/router/{useRouteQueryDefaults.ts → query/useRouteQueryDefaults.ts} +9 -8
  253. package/templates/current/clean/src/router/query/useRouteQueryDefaults.types.ts +28 -0
  254. package/templates/current/clean/src/router/{runtimeErrorRecovery.ts → recovery/runtimeErrorRecovery.ts} +21 -3
  255. package/templates/current/clean/src/{features/auth/store → store}/auth.ts +97 -62
  256. package/templates/current/clean/src/store/dictionaries.ts +86 -0
  257. package/templates/current/clean/src/{features/shell/store → store}/sidebar.ts +9 -2
  258. package/templates/current/{examples/src/features/appearance → clean/src}/store/theme.ts +8 -4
  259. package/templates/current/clean/src/styles/layout.css +51 -0
  260. package/templates/current/clean/src/templates/og-form.ts +7 -2
  261. package/templates/current/clean/src/templates/og-table.ts +86 -20
  262. package/templates/current/clean/src/templates/router.ts +11 -2
  263. package/templates/current/clean/src/utils/color-mix.ts +6 -2
  264. package/templates/current/clean/src/utils/download.ts +11 -0
  265. package/templates/current/clean/src/utils/permissions.ts +1 -1
  266. package/templates/current/clean/src/utils/retryableDialog.ts +46 -0
  267. package/templates/current/clean/src/{features → views}/errors/pages/Forbidden.vue +6 -2
  268. package/templates/current/clean/src/views/errors/pages/MethodNotAllowed.vue +34 -0
  269. package/templates/current/clean/src/{features → views}/errors/pages/NotFound.vue +6 -2
  270. package/templates/current/clean/src/{features → views}/errors/pages/ServerError.vue +6 -2
  271. package/templates/current/clean/src/{features/auth/pages/Login.vue → views/login/pages/index.vue} +99 -10
  272. package/templates/current/clean/src/views/system/access/services/admin-repository.ts +489 -0
  273. package/templates/current/clean/src/views/system/access/services/rbac.ts +317 -0
  274. package/templates/current/clean/src/views/system/dept/components/DepartmentEditorForm.vue +87 -0
  275. package/templates/current/clean/src/views/system/dept/composables/useDepartmentManagement.ts +314 -0
  276. package/templates/current/clean/src/views/system/dept/pages/index.vue +44 -0
  277. package/templates/current/clean/src/views/system/dept/services/departments.ts +168 -0
  278. package/templates/current/clean/src/views/system/dict/components/DictionaryDataEditorForm.vue +98 -0
  279. package/templates/current/clean/src/views/system/dict/components/DictionaryDataPreview.vue +233 -0
  280. package/templates/current/clean/src/views/system/dict/components/DictionaryTypeEditorForm.vue +66 -0
  281. package/templates/current/clean/src/views/system/dict/composables/useDictionaryDataManagement.ts +406 -0
  282. package/templates/current/clean/src/views/system/dict/composables/useDictionaryTypeManagement.ts +329 -0
  283. package/templates/current/clean/src/views/system/dict/data/pages/index.vue +134 -0
  284. package/templates/current/clean/src/views/system/dict/pages/index.vue +113 -0
  285. package/templates/current/clean/src/views/system/dict/services/dictionaries.ts +239 -0
  286. package/templates/current/clean/src/views/system/menu/components/MenuEditorForm.vue +252 -0
  287. package/templates/current/clean/src/views/system/menu/composables/useMenuManagement.ts +357 -0
  288. package/templates/current/clean/src/views/system/menu/menuDraft.ts +45 -0
  289. package/templates/current/clean/src/views/system/menu/pages/ExternalLink.vue +37 -0
  290. package/templates/current/clean/src/views/system/menu/pages/index.vue +75 -0
  291. package/templates/current/clean/src/views/system/post/components/PostEditorForm.vue +69 -0
  292. package/templates/current/clean/src/views/system/post/composables/usePostManagement.ts +245 -0
  293. package/templates/current/clean/src/views/system/post/pages/index.vue +92 -0
  294. package/templates/current/clean/src/views/system/post/services/posts.ts +100 -0
  295. package/templates/current/clean/src/views/system/role/auth-users/pages/index.vue +100 -0
  296. package/templates/current/clean/src/views/system/role/components/RoleDataScopeForm.vue +167 -0
  297. package/templates/current/clean/src/views/system/role/components/RoleEditorForm.vue +165 -0
  298. package/templates/current/clean/src/views/system/role/components/RoleUserSelectForm.vue +129 -0
  299. package/templates/current/clean/src/views/system/role/composables/useRoleManagement.ts +422 -0
  300. package/templates/current/clean/src/views/system/role/composables/useRoleUserManagement.ts +233 -0
  301. package/templates/current/clean/src/views/system/role/pages/index.vue +110 -0
  302. package/templates/current/clean/src/views/system/role/services/roleAccess.ts +162 -0
  303. package/templates/current/clean/src/views/system/user/auth-roles/pages/index.vue +209 -0
  304. package/templates/current/clean/src/views/system/user/components/UserDetailsForm.vue +108 -0
  305. package/templates/current/clean/src/views/system/user/components/UserEditorForm.vue +207 -0
  306. package/templates/current/clean/src/views/system/user/components/UserImportDialog.vue +80 -0
  307. package/templates/current/clean/src/views/system/user/components/UserResetPasswordForm.vue +56 -0
  308. package/templates/current/clean/src/views/system/user/composables/useUserManagement.ts +502 -0
  309. package/templates/current/clean/src/views/system/user/pages/index.vue +459 -0
  310. package/templates/current/clean/tests/e2e/admin-access-business.spec.ts +33 -0
  311. package/templates/current/clean/tests/e2e/admin-shell.spec.ts +50 -0
  312. package/templates/current/clean/tests/e2e/fixtures/adminMockBackend.ts +95 -0
  313. package/templates/current/clean/tests/e2e/fixtures/labelGeometry.ts +52 -0
  314. package/templates/current/clean/tests/e2e/mock-api-generation.spec.ts +27 -0
  315. package/templates/current/clean/tests/e2e/mock-business.spec.ts +555 -0
  316. package/templates/current/clean/tests/e2e/mock-menu-retry-form-label.spec.ts +100 -0
  317. package/templates/current/clean/tests/e2e/mock-shell.spec.ts +25 -0
  318. package/templates/current/clean/tests/e2e/mock-tree-selection-layout.spec.ts +113 -0
  319. package/templates/current/clean/tests/unit/api/api-codegen.spec.ts +893 -0
  320. package/templates/current/clean/tests/unit/api/client.spec.ts +145 -0
  321. package/templates/current/clean/tests/unit/api/generated-http-client.spec.ts +290 -0
  322. package/templates/current/{examples/src → clean/tests/unit}/api/http-adapter.spec.ts +3 -3
  323. package/templates/current/clean/tests/unit/api/system-apis.spec.ts +118 -0
  324. package/templates/current/clean/tests/unit/app/createAdminUi.spec.ts +79 -0
  325. package/templates/current/clean/{src → tests/unit}/app/errorMessage.spec.ts +1 -1
  326. package/templates/current/clean/tests/unit/app/iconCatalog.spec.ts +12 -0
  327. package/templates/current/clean/tests/unit/app/menu.spec.ts +215 -0
  328. package/templates/current/{examples/src → clean/tests/unit}/app/origenUiLocale.spec.ts +1 -1
  329. package/templates/current/{examples/src → clean/tests/unit}/app/permission.spec.ts +4 -5
  330. package/templates/current/clean/tests/unit/app/runtimeConfig.spec.ts +36 -0
  331. package/templates/current/{examples/src/features → clean/tests/unit/app}/security/devtoolsProtection.spec.ts +17 -7
  332. package/templates/current/{examples/src/features/shell → clean/tests/unit}/composables/useRouteProgress.spec.ts +1 -1
  333. package/templates/current/{examples/src/features/shell/components → clean/tests/unit/layouts}/AdminWatermark.spec.ts +5 -7
  334. package/templates/current/{examples/src → clean/tests/unit}/layouts/topBarMenuSearch.spec.ts +25 -8
  335. package/templates/current/clean/{src → tests/unit}/locales/messages.spec.ts +43 -17
  336. package/templates/current/clean/tests/unit/router/dynamicMenuRefresh.spec.ts +151 -0
  337. package/templates/current/clean/tests/unit/router/dynamicRoutes.spec.ts +374 -0
  338. package/templates/current/clean/tests/unit/router/paths.spec.ts +103 -0
  339. package/templates/current/clean/{src → tests/unit}/router/queryEncryption.spec.ts +49 -12
  340. package/templates/current/{examples/src → clean/tests/unit}/router/routeQuery.spec.ts +8 -1
  341. package/templates/current/clean/{src → tests/unit}/router/runtimeErrorRecovery.spec.ts +11 -6
  342. package/templates/current/{examples/src → clean/tests/unit}/router/useRouteQueryDefaults.spec.ts +46 -12
  343. package/templates/current/clean/tests/unit/scripts/mock-api.spec.ts +440 -0
  344. package/templates/current/clean/{scripts → tests/unit/scripts}/vite-build-policy.spec.ts +35 -6
  345. package/templates/current/clean/{src/features/auth → tests/unit}/store/auth.spec.ts +100 -15
  346. package/templates/current/clean/tests/unit/store/dictionaries.spec.ts +106 -0
  347. package/templates/current/{examples/src → clean/tests/unit}/templates/templates.spec.ts +58 -16
  348. package/templates/current/clean/{src/utils/__tests__ → tests/unit/utils}/color-mix.spec.ts +1 -1
  349. package/templates/current/clean/tests/unit/utils/retryableDialog.spec.ts +61 -0
  350. package/templates/current/{examples/src/features/errors/pages → clean/tests/unit/views/errors}/error-pages.spec.ts +11 -7
  351. package/templates/current/clean/tests/unit/views/feature-composables.spec.ts +233 -0
  352. package/templates/current/clean/tests/unit/views/system/access/admin-repository.spec.ts +353 -0
  353. package/templates/current/clean/tests/unit/views/system/access/rbac.spec.ts +329 -0
  354. package/templates/current/clean/tests/unit/views/system/dept/departments.spec.ts +104 -0
  355. package/templates/current/clean/tests/unit/views/system/dict/dictionaries.spec.ts +234 -0
  356. package/templates/current/clean/tests/unit/views/system/menu/menuDraft.spec.ts +77 -0
  357. package/templates/current/clean/tests/unit/views/system/menu/useMenuManagement.spec.ts +339 -0
  358. package/templates/current/clean/tests/unit/views/system/user/searchControl.spec.ts +128 -0
  359. package/templates/current/clean/tsconfig.json +4 -19
  360. package/templates/current/clean/vite.build-policy.ts +97 -22
  361. package/templates/current/clean/vite.config.ts +50 -7
  362. package/templates/current/examples/.agents/skills/admin-component-usage/SKILL.md +27 -0
  363. package/templates/current/examples/.agents/skills/admin-component-usage/references/component-directory.md +232 -0
  364. package/templates/current/examples/.agents/skills/build-admin-feature/SKILL.md +20 -0
  365. package/templates/current/examples/.agents/skills/build-admin-feature/references/component-selection.md +42 -0
  366. package/templates/current/examples/.agents/skills/style-og-origen-ui/SKILL.md +11 -0
  367. package/templates/current/examples/.agents/skills/use-og-dialog/SKILL.md +12 -0
  368. package/templates/current/examples/.agents/skills/use-og-editor/SKILL.md +25 -0
  369. package/templates/current/examples/.agents/skills/use-og-form/SKILL.md +12 -0
  370. package/templates/current/examples/.agents/skills/use-og-form-table/SKILL.md +26 -0
  371. package/templates/current/examples/.agents/skills/use-og-http/SKILL.md +13 -0
  372. package/templates/current/examples/.agents/skills/use-og-router-tabs/SKILL.md +11 -0
  373. package/templates/current/examples/.agents/skills/use-og-search/SKILL.md +14 -0
  374. package/templates/current/examples/.agents/skills/use-og-table/SKILL.md +22 -0
  375. package/templates/current/examples/.agents/skills/use-og-upload/SKILL.md +26 -0
  376. package/templates/current/examples/.api-client-e2e.config.ts +13 -0
  377. package/templates/current/examples/.claude/rules/01-feature-architecture.md +10 -0
  378. package/templates/current/examples/.claude/rules/02-vue-typescript.md +10 -0
  379. package/templates/current/examples/.claude/rules/03-component-policy.md +31 -0
  380. package/templates/current/examples/.claude/rules/04-api-auth-router.md +10 -0
  381. package/templates/current/examples/.claude/rules/05-style.md +10 -0
  382. package/templates/current/examples/.claude/rules/06-quality.md +10 -0
  383. package/templates/current/examples/.claude/skills/admin-component-usage/SKILL.md +27 -0
  384. package/templates/current/examples/.claude/skills/admin-component-usage/references/component-directory.md +232 -0
  385. package/templates/current/examples/.claude/skills/build-admin-feature/SKILL.md +20 -0
  386. package/templates/current/examples/.claude/skills/build-admin-feature/references/component-selection.md +42 -0
  387. package/templates/current/examples/.claude/skills/style-og-origen-ui/SKILL.md +11 -0
  388. package/templates/current/examples/.claude/skills/use-og-dialog/SKILL.md +12 -0
  389. package/templates/current/examples/.claude/skills/use-og-editor/SKILL.md +25 -0
  390. package/templates/current/examples/.claude/skills/use-og-form/SKILL.md +12 -0
  391. package/templates/current/examples/.claude/skills/use-og-form-table/SKILL.md +26 -0
  392. package/templates/current/examples/.claude/skills/use-og-http/SKILL.md +13 -0
  393. package/templates/current/examples/.claude/skills/use-og-router-tabs/SKILL.md +11 -0
  394. package/templates/current/examples/.claude/skills/use-og-search/SKILL.md +14 -0
  395. package/templates/current/examples/.claude/skills/use-og-table/SKILL.md +22 -0
  396. package/templates/current/examples/.claude/skills/use-og-upload/SKILL.md +26 -0
  397. package/templates/current/examples/.codebuddy/rules/01-feature-architecture.md +2 -2
  398. package/templates/current/examples/.codebuddy/rules/03-component-policy.md +4 -1
  399. package/templates/current/examples/.codebuddy/skills/admin-component-usage/SKILL.md +30 -0
  400. package/templates/current/examples/.codebuddy/skills/admin-component-usage/references/component-directory.md +232 -0
  401. package/templates/current/examples/.codebuddy/skills/build-admin-feature/SKILL.md +11 -5
  402. package/templates/current/examples/.codebuddy/skills/build-admin-feature/references/component-selection.md +42 -0
  403. package/templates/current/examples/.codebuddy/skills/use-og-form/SKILL.md +1 -1
  404. package/templates/current/examples/.codebuddy/skills/use-og-form-table/SKILL.md +4 -3
  405. package/templates/current/examples/.codebuddy/skills/use-og-search/SKILL.md +3 -3
  406. package/templates/current/examples/.codebuddy/skills/use-og-table/SKILL.md +16 -10
  407. package/templates/current/examples/.codebuddy/skills/use-og-upload/SKILL.md +6 -5
  408. package/templates/current/examples/.codex/AGENTS.md +55 -8
  409. package/templates/current/examples/.codex/rules/01-feature-architecture.md +2 -2
  410. package/templates/current/examples/.codex/rules/03-component-policy.md +4 -1
  411. package/templates/current/examples/.cursor/rules/.generated +5 -0
  412. package/templates/current/examples/.cursor/rules/01-feature-architecture.mdc +2 -2
  413. package/templates/current/examples/.cursor/rules/03-component-policy.mdc +4 -1
  414. package/templates/current/examples/.cursor/skills/admin-component-usage/SKILL.md +27 -0
  415. package/templates/current/examples/.cursor/skills/admin-component-usage/references/component-directory.md +232 -0
  416. package/templates/current/examples/.cursor/skills/build-admin-feature/SKILL.md +11 -5
  417. package/templates/current/examples/.cursor/skills/build-admin-feature/references/component-selection.md +42 -0
  418. package/templates/current/examples/.cursor/skills/use-og-form/SKILL.md +1 -1
  419. package/templates/current/examples/.cursor/skills/use-og-form-table/SKILL.md +4 -3
  420. package/templates/current/examples/.cursor/skills/use-og-search/SKILL.md +3 -3
  421. package/templates/current/examples/.cursor/skills/use-og-table/SKILL.md +16 -10
  422. package/templates/current/examples/.cursor/skills/use-og-upload/SKILL.md +6 -5
  423. package/templates/current/examples/{.env.example → .env.dev} +3 -2
  424. package/templates/current/examples/.env.mock +4 -0
  425. package/templates/current/examples/.env.production +5 -0
  426. package/templates/current/examples/.env.test +4 -0
  427. package/templates/current/examples/.prettierignore +28 -0
  428. package/templates/current/examples/.prettierrc +8 -0
  429. package/templates/current/examples/.qoder/rules/01-feature-architecture.md +3 -4
  430. package/templates/current/examples/.qoder/rules/02-vue-typescript.md +1 -2
  431. package/templates/current/examples/.qoder/rules/03-component-policy.md +5 -3
  432. package/templates/current/examples/.qoder/rules/04-api-auth-router.md +1 -2
  433. package/templates/current/examples/.qoder/rules/05-style.md +1 -2
  434. package/templates/current/examples/.qoder/rules/06-quality.md +1 -2
  435. package/templates/current/examples/.qoder/skills/admin-component-usage/SKILL.md +27 -0
  436. package/templates/current/examples/.qoder/skills/admin-component-usage/references/component-directory.md +232 -0
  437. package/templates/current/examples/.qoder/skills/build-admin-feature/SKILL.md +11 -5
  438. package/templates/current/examples/.qoder/skills/build-admin-feature/references/component-selection.md +42 -0
  439. package/templates/current/examples/.qoder/skills/use-og-form/SKILL.md +1 -1
  440. package/templates/current/examples/.qoder/skills/use-og-form-table/SKILL.md +4 -3
  441. package/templates/current/examples/.qoder/skills/use-og-search/SKILL.md +3 -3
  442. package/templates/current/examples/.qoder/skills/use-og-table/SKILL.md +16 -10
  443. package/templates/current/examples/.qoder/skills/use-og-upload/SKILL.md +6 -5
  444. package/templates/current/examples/.zcode/skills/admin-component-usage/SKILL.md +27 -0
  445. package/templates/current/examples/.zcode/skills/admin-component-usage/references/component-directory.md +232 -0
  446. package/templates/current/examples/.zcode/skills/build-admin-feature/SKILL.md +20 -0
  447. package/templates/current/examples/.zcode/skills/build-admin-feature/references/component-selection.md +42 -0
  448. package/templates/current/examples/.zcode/skills/style-og-origen-ui/SKILL.md +11 -0
  449. package/templates/current/examples/.zcode/skills/use-og-dialog/SKILL.md +12 -0
  450. package/templates/current/examples/.zcode/skills/use-og-editor/SKILL.md +25 -0
  451. package/templates/current/examples/.zcode/skills/use-og-form/SKILL.md +12 -0
  452. package/templates/current/examples/.zcode/skills/use-og-form-table/SKILL.md +26 -0
  453. package/templates/current/examples/.zcode/skills/use-og-http/SKILL.md +13 -0
  454. package/templates/current/examples/.zcode/skills/use-og-router-tabs/SKILL.md +11 -0
  455. package/templates/current/examples/.zcode/skills/use-og-search/SKILL.md +14 -0
  456. package/templates/current/examples/.zcode/skills/use-og-table/SKILL.md +22 -0
  457. package/templates/current/examples/.zcode/skills/use-og-upload/SKILL.md +26 -0
  458. package/templates/current/examples/AGENTS.md +55 -9
  459. package/templates/current/examples/CHANGELOG.md +128 -0
  460. package/templates/current/examples/CLAUDE.md +3 -0
  461. package/templates/current/examples/README.md +58 -88
  462. package/templates/current/examples/component-catalog.json +766 -348
  463. package/templates/current/examples/component-catalog.v2.json +2040 -0
  464. package/templates/current/examples/docs/components/dialog.md +405 -0
  465. package/templates/current/examples/docs/components/editor-viewer.md +87 -0
  466. package/templates/current/examples/docs/components/editor.md +275 -0
  467. package/templates/current/examples/docs/components/form-table.md +222 -0
  468. package/templates/current/examples/docs/components/form.md +750 -0
  469. package/templates/current/examples/docs/components/index.md +44 -0
  470. package/templates/current/examples/docs/components/router.md +452 -0
  471. package/templates/current/examples/docs/components/search.md +1205 -0
  472. package/templates/current/examples/docs/components/svg-icon.md +124 -0
  473. package/templates/current/examples/docs/components/table-local.md +176 -0
  474. package/templates/current/examples/docs/components/table-with-search.md +207 -0
  475. package/templates/current/examples/docs/components/table.md +813 -0
  476. package/templates/current/examples/docs/components/tabs.md +440 -0
  477. package/templates/current/examples/docs/components/upload.md +349 -0
  478. package/templates/current/examples/eslint.config.js +89 -0
  479. package/templates/current/examples/index.html +1 -1
  480. package/templates/current/examples/openapi.json +10048 -999
  481. package/templates/current/examples/package.json +47 -35
  482. package/templates/current/examples/playwright.config.ts +20 -6
  483. package/templates/current/examples/playwright.mock.config.ts +42 -0
  484. package/templates/current/examples/pnpm-workspace.yaml +19 -3
  485. package/templates/current/examples/recipes/remote-crud-dialog-form.vue +15 -13
  486. package/templates/current/examples/scaffold.lock.json +164 -4
  487. package/templates/current/examples/scripts/api-codegen.config.ts +35 -0
  488. package/templates/current/examples/scripts/api-codegen.ts +2015 -0
  489. package/templates/current/examples/scripts/api-templates/http-client.ejs +359 -0
  490. package/templates/current/examples/scripts/check-admin-scaffold.mjs +315 -30
  491. package/templates/current/examples/scripts/generate-api.ts +290 -85
  492. package/templates/current/examples/scripts/lib/admin-component-catalog.mjs +514 -0
  493. package/templates/current/examples/scripts/lib/admin-skill-inventory.mjs +18 -0
  494. package/templates/current/examples/scripts/lib/repository-root.mjs +9 -0
  495. package/templates/current/examples/scripts/mock-api.ts +1356 -0
  496. package/templates/current/examples/scripts/remove-examples.mjs +9 -34
  497. package/templates/current/examples/src/App.vue +9 -18
  498. package/templates/current/examples/src/api/generated/data-contracts.ts +23 -265
  499. package/templates/current/examples/src/api/generated/http-client.ts +351 -180
  500. package/templates/current/examples/src/api/generated/index.ts +22 -0
  501. package/templates/current/examples/src/api/generated/services/auth.ts +123 -0
  502. package/templates/current/examples/src/api/generated/services/common/files.ts +111 -0
  503. package/templates/current/examples/src/api/generated/services/monitor/cache.ts +164 -0
  504. package/templates/current/examples/src/api/generated/services/monitor/job.ts +195 -0
  505. package/templates/current/examples/src/api/generated/services/monitor/jobLog.ts +126 -0
  506. package/templates/current/examples/src/api/generated/services/monitor/logininfor.ts +126 -0
  507. package/templates/current/examples/src/api/generated/services/monitor/online.ts +66 -0
  508. package/templates/current/examples/src/api/generated/services/monitor/operlog.ts +106 -0
  509. package/templates/current/examples/src/api/generated/services/monitor/server.ts +41 -0
  510. package/templates/current/examples/src/api/generated/services/system/configs.ts +190 -0
  511. package/templates/current/examples/src/api/generated/services/system/departments.ts +173 -0
  512. package/templates/current/examples/src/api/generated/services/system/dictionaries/data.ts +169 -0
  513. package/templates/current/examples/src/api/generated/services/system/dictionaries/types.ts +187 -0
  514. package/templates/current/examples/src/api/generated/services/system/index.ts +158 -0
  515. package/templates/current/examples/src/api/generated/services/system/menus.ts +193 -0
  516. package/templates/current/examples/src/api/generated/services/system/notices.ts +221 -0
  517. package/templates/current/examples/src/api/generated/services/system/posts.ts +168 -0
  518. package/templates/current/examples/src/api/generated/services/system/roles.ts +354 -0
  519. package/templates/current/examples/src/api/generated/services/system/users.ts +425 -0
  520. package/templates/current/examples/src/api/generated/services/tool/code-generator.ts +304 -0
  521. package/templates/current/examples/src/api/generated/types/auth.types.ts +132 -0
  522. package/templates/current/examples/src/api/generated/types/common/files.types.ts +57 -0
  523. package/templates/current/examples/src/api/generated/types/common.ts +174 -0
  524. package/templates/current/examples/src/api/generated/types/enum-dict.ts +94 -0
  525. package/templates/current/examples/src/api/generated/types/enums.ts +155 -0
  526. package/templates/current/examples/src/api/generated/types/monitor/cache.types.ts +149 -0
  527. package/templates/current/examples/src/api/generated/types/monitor/job.types.ts +207 -0
  528. package/templates/current/examples/src/api/generated/types/monitor/jobLog.types.ts +134 -0
  529. package/templates/current/examples/src/api/generated/types/monitor/logininfor.types.ts +135 -0
  530. package/templates/current/examples/src/api/generated/types/monitor/online.types.ts +80 -0
  531. package/templates/current/examples/src/api/generated/types/monitor/operlog.types.ts +126 -0
  532. package/templates/current/examples/src/api/generated/types/monitor/server.types.ts +205 -0
  533. package/templates/current/examples/src/api/generated/types/system/configs.types.ts +200 -0
  534. package/templates/current/examples/src/api/generated/types/system/departments.types.ts +145 -0
  535. package/templates/current/examples/src/api/generated/types/system/dictionaries/data.types.ts +210 -0
  536. package/templates/current/examples/src/api/generated/types/system/dictionaries/types.types.ts +221 -0
  537. package/templates/current/examples/src/api/generated/types/system/index.types.ts +19 -0
  538. package/templates/current/examples/src/api/generated/types/system/menus.types.ts +234 -0
  539. package/templates/current/examples/src/api/generated/types/system/notices.types.ts +270 -0
  540. package/templates/current/examples/src/api/generated/types/system/posts.types.ts +198 -0
  541. package/templates/current/examples/src/api/generated/types/system/roles.types.ts +410 -0
  542. package/templates/current/examples/src/api/generated/types/system/users.types.ts +413 -0
  543. package/templates/current/examples/src/api/generated/types/tool/code-generator.types.ts +388 -0
  544. package/templates/current/examples/src/api/index.ts +44 -39
  545. package/templates/current/examples/src/app/__tests__/api-generated.types.ts +24 -0
  546. package/templates/current/examples/src/app/api.ts +6 -0
  547. package/templates/current/examples/src/app/authorization/permission.ts +9 -0
  548. package/templates/current/{clean/src/app → examples/src/app/config}/runtimeConfig.ts +44 -12
  549. package/templates/current/examples/src/app/errors/errorMessage.ts +80 -0
  550. package/templates/current/examples/src/app/http/client.ts +141 -0
  551. package/templates/current/examples/src/app/http/http-adapter.ts +71 -0
  552. package/templates/current/{clean/src/app → examples/src/app/i18n}/adminLocale.ts +25 -19
  553. package/templates/current/examples/src/app/{localeFormat.ts → i18n/localeFormat.ts} +29 -6
  554. package/templates/current/examples/src/app/i18n/origenUiLocale.ts +15 -0
  555. package/templates/current/examples/src/app/menu/menu.ts +175 -0
  556. package/templates/current/examples/src/app/menu/menuTypes.ts +20 -0
  557. package/templates/current/examples/src/{features → app}/security/devtoolsProtection.ts +8 -7
  558. package/templates/current/examples/src/app/ui/createAdminUi.ts +31 -0
  559. package/templates/current/examples/src/app/ui/iconCatalog.ts +71 -0
  560. package/templates/current/examples/src/assets/icons/appearance.svg +1 -0
  561. package/templates/current/examples/src/assets/icons/arrow-right.svg +1 -0
  562. package/templates/current/examples/src/assets/icons/check.svg +1 -0
  563. package/templates/current/examples/src/assets/icons/circle-check.svg +1 -0
  564. package/templates/current/examples/src/assets/icons/default.svg +4 -0
  565. package/templates/current/examples/src/assets/icons/directory/setting.svg +1 -0
  566. package/templates/current/examples/src/assets/icons/expand.svg +1 -0
  567. package/templates/current/examples/src/assets/icons/fold.svg +1 -0
  568. package/templates/current/examples/src/assets/icons/key.svg +1 -0
  569. package/templates/current/examples/src/assets/icons/lock.svg +1 -0
  570. package/templates/current/examples/src/assets/icons/monitor.svg +1 -0
  571. package/templates/current/examples/src/assets/icons/moon.svg +11 -0
  572. package/templates/current/examples/src/assets/icons/page/department.svg +1 -0
  573. package/templates/current/examples/src/assets/icons/page/dictionary.svg +1 -0
  574. package/templates/current/examples/src/assets/icons/page/menus.svg +1 -0
  575. package/templates/current/examples/src/assets/icons/page/user.svg +1 -0
  576. package/templates/current/examples/src/assets/icons/page/users.svg +1 -0
  577. package/templates/current/examples/src/assets/icons/plus.svg +1 -0
  578. package/templates/current/examples/src/assets/icons/profile.svg +1 -0
  579. package/templates/current/examples/src/assets/icons/refresh.svg +1 -0
  580. package/templates/current/examples/src/assets/icons/roles.svg +1 -0
  581. package/templates/current/examples/src/assets/icons/search.svg +1 -0
  582. package/templates/current/examples/src/assets/icons/sunny.svg +1 -0
  583. package/templates/current/examples/src/assets/icons/system.svg +1 -0
  584. package/templates/current/examples/src/assets/icons/theme-auto.svg +14 -0
  585. package/templates/current/examples/src/assets/icons/tune.svg +13 -0
  586. package/templates/current/examples/src/{features/shell/components → components}/RouteProgress.vue +2 -2
  587. package/templates/current/{clean/src/features/system/access → examples/src}/composables/useAuthorizationRefresh.ts +6 -1
  588. package/templates/current/examples/src/composables/useSystemTableSearchVisibility.ts +33 -0
  589. package/templates/current/examples/src/{features/appearance/composables → composables}/useTheme.ts +1 -1
  590. package/templates/current/examples/src/env.d.ts +6 -19
  591. package/templates/current/examples/src/layouts/AdminLayout.vue +7 -9
  592. package/templates/current/examples/src/{features/shell/components → layouts}/AdminWatermark.vue +2 -2
  593. package/templates/current/examples/src/layouts/BreadcrumbBar.vue +9 -1
  594. package/templates/current/examples/src/layouts/SideMenu.vue +7 -15
  595. package/templates/current/examples/src/{features/appearance/components → layouts}/ThemePanel.vue +39 -11
  596. package/templates/current/examples/src/layouts/TopBar.vue +60 -28
  597. package/templates/current/examples/src/layouts/WorkspaceTabs.vue +10 -1
  598. package/templates/current/examples/src/layouts/topBarMenuSearch.ts +25 -4
  599. package/templates/current/examples/src/locales/en-US.json +227 -219
  600. package/templates/current/examples/src/locales/index.ts +72 -32
  601. package/templates/current/examples/src/locales/messages-types.ts +15 -10
  602. package/templates/current/examples/src/locales/vue-i18n.d.ts +1 -1
  603. package/templates/current/examples/src/locales/zh-CN.json +226 -218
  604. package/templates/current/examples/src/locales/zh-TW.json +222 -214
  605. package/templates/current/examples/src/main.ts +50 -40
  606. package/templates/current/examples/src/router/bootstrap.ts +69 -24
  607. package/templates/current/examples/src/router/dynamic/componentLoader.ts +150 -0
  608. package/templates/current/examples/src/router/{dynamicMenuRefresh.ts → dynamic/dynamicMenuRefresh.ts} +6 -2
  609. package/templates/current/examples/src/router/dynamic/dynamicRoutes.ts +247 -0
  610. package/templates/current/examples/src/router/navigation/guards.ts +12 -0
  611. package/templates/current/examples/src/router/navigation/paths.ts +28 -0
  612. package/templates/current/examples/src/router/navigation/staticRoutes.ts +109 -0
  613. package/templates/current/examples/src/router/{queryEncryption.ts → query/queryEncryption.ts} +29 -12
  614. package/templates/current/examples/src/router/query/routeQuery.ts +29 -0
  615. package/templates/current/examples/src/router/{useRouteQueryDefaults.ts → query/useRouteQueryDefaults.ts} +9 -8
  616. package/templates/current/examples/src/router/query/useRouteQueryDefaults.types.ts +28 -0
  617. package/templates/current/examples/src/router/{runtimeErrorRecovery.ts → recovery/runtimeErrorRecovery.ts} +21 -3
  618. package/templates/current/examples/src/{features/auth/store → store}/auth.ts +97 -62
  619. package/templates/current/examples/src/store/dictionaries.ts +86 -0
  620. package/templates/current/examples/src/{features/shell/store → store}/sidebar.ts +9 -2
  621. package/templates/current/{clean/src/features/appearance → examples/src}/store/theme.ts +8 -4
  622. package/templates/current/examples/src/styles/layout.css +51 -0
  623. package/templates/current/examples/src/templates/og-form.ts +7 -2
  624. package/templates/current/examples/src/templates/og-table.ts +86 -20
  625. package/templates/current/examples/src/templates/router.ts +11 -2
  626. package/templates/current/examples/src/utils/color-mix.ts +6 -2
  627. package/templates/current/examples/src/utils/download.ts +11 -0
  628. package/templates/current/examples/src/utils/permissions.ts +1 -1
  629. package/templates/current/examples/src/utils/retryableDialog.ts +46 -0
  630. package/templates/current/{clean/scripts/clean-overlay/src/features → examples/src/views}/errors/pages/Forbidden.vue +6 -2
  631. package/templates/current/examples/src/views/errors/pages/MethodNotAllowed.vue +34 -0
  632. package/templates/current/examples/{scripts/clean-overlay/src/features → src/views}/errors/pages/NotFound.vue +6 -2
  633. package/templates/current/examples/{scripts/clean-overlay/src/features → src/views}/errors/pages/ServerError.vue +6 -2
  634. package/templates/current/examples/src/{features/auth/pages/Login.vue → views/login/pages/index.vue} +99 -10
  635. package/templates/current/examples/src/views/system/access/services/admin-repository.ts +489 -0
  636. package/templates/current/examples/src/views/system/access/services/rbac.ts +317 -0
  637. package/templates/current/examples/src/views/system/dept/components/DepartmentEditorForm.vue +87 -0
  638. package/templates/current/examples/src/views/system/dept/composables/useDepartmentManagement.ts +314 -0
  639. package/templates/current/examples/src/views/system/dept/pages/index.vue +44 -0
  640. package/templates/current/examples/src/views/system/dept/services/departments.ts +168 -0
  641. package/templates/current/examples/src/views/system/dict/components/DictionaryDataEditorForm.vue +98 -0
  642. package/templates/current/examples/src/views/system/dict/components/DictionaryDataPreview.vue +233 -0
  643. package/templates/current/examples/src/views/system/dict/components/DictionaryTypeEditorForm.vue +66 -0
  644. package/templates/current/examples/src/views/system/dict/composables/useDictionaryDataManagement.ts +406 -0
  645. package/templates/current/examples/src/views/system/dict/composables/useDictionaryTypeManagement.ts +329 -0
  646. package/templates/current/examples/src/views/system/dict/data/pages/index.vue +134 -0
  647. package/templates/current/examples/src/views/system/dict/pages/index.vue +113 -0
  648. package/templates/current/examples/src/views/system/dict/services/dictionaries.ts +239 -0
  649. package/templates/current/examples/src/views/system/menu/components/MenuEditorForm.vue +252 -0
  650. package/templates/current/examples/src/views/system/menu/composables/useMenuManagement.ts +357 -0
  651. package/templates/current/examples/src/views/system/menu/menuDraft.ts +45 -0
  652. package/templates/current/examples/src/views/system/menu/pages/ExternalLink.vue +37 -0
  653. package/templates/current/examples/src/views/system/menu/pages/index.vue +75 -0
  654. package/templates/current/examples/src/views/system/post/components/PostEditorForm.vue +69 -0
  655. package/templates/current/examples/src/views/system/post/composables/usePostManagement.ts +245 -0
  656. package/templates/current/examples/src/views/system/post/pages/index.vue +92 -0
  657. package/templates/current/examples/src/views/system/post/services/posts.ts +100 -0
  658. package/templates/current/examples/src/views/system/role/auth-users/pages/index.vue +100 -0
  659. package/templates/current/examples/src/views/system/role/components/RoleDataScopeForm.vue +167 -0
  660. package/templates/current/examples/src/views/system/role/components/RoleEditorForm.vue +165 -0
  661. package/templates/current/examples/src/views/system/role/components/RoleUserSelectForm.vue +129 -0
  662. package/templates/current/examples/src/views/system/role/composables/useRoleManagement.ts +422 -0
  663. package/templates/current/examples/src/views/system/role/composables/useRoleUserManagement.ts +233 -0
  664. package/templates/current/examples/src/views/system/role/pages/index.vue +110 -0
  665. package/templates/current/examples/src/views/system/role/services/roleAccess.ts +162 -0
  666. package/templates/current/examples/src/views/system/user/auth-roles/pages/index.vue +209 -0
  667. package/templates/current/examples/src/views/system/user/components/UserDetailsForm.vue +108 -0
  668. package/templates/current/examples/src/views/system/user/components/UserEditorForm.vue +207 -0
  669. package/templates/current/examples/src/views/system/user/components/UserImportDialog.vue +80 -0
  670. package/templates/current/examples/src/views/system/user/components/UserResetPasswordForm.vue +56 -0
  671. package/templates/current/examples/src/views/system/user/composables/useUserManagement.ts +502 -0
  672. package/templates/current/examples/src/views/system/user/pages/index.vue +459 -0
  673. package/templates/current/examples/tests/e2e/admin-access-business.spec.ts +33 -0
  674. package/templates/current/examples/tests/e2e/admin-shell.spec.ts +50 -0
  675. package/templates/current/examples/tests/e2e/fixtures/adminMockBackend.ts +95 -0
  676. package/templates/current/examples/tests/e2e/fixtures/labelGeometry.ts +52 -0
  677. package/templates/current/examples/tests/e2e/mock-api-generation.spec.ts +27 -0
  678. package/templates/current/examples/tests/e2e/mock-business.spec.ts +555 -0
  679. package/templates/current/examples/tests/e2e/mock-menu-retry-form-label.spec.ts +100 -0
  680. package/templates/current/examples/tests/e2e/mock-shell.spec.ts +25 -0
  681. package/templates/current/examples/tests/e2e/mock-tree-selection-layout.spec.ts +113 -0
  682. package/templates/current/examples/tests/unit/api/api-codegen.spec.ts +893 -0
  683. package/templates/current/examples/tests/unit/api/client.spec.ts +145 -0
  684. package/templates/current/examples/tests/unit/api/generated-http-client.spec.ts +290 -0
  685. package/templates/current/{clean/src → examples/tests/unit}/api/http-adapter.spec.ts +3 -3
  686. package/templates/current/examples/tests/unit/api/system-apis.spec.ts +118 -0
  687. package/templates/current/examples/tests/unit/app/createAdminUi.spec.ts +79 -0
  688. package/templates/current/examples/{src → tests/unit}/app/errorMessage.spec.ts +1 -1
  689. package/templates/current/examples/tests/unit/app/iconCatalog.spec.ts +12 -0
  690. package/templates/current/examples/tests/unit/app/menu.spec.ts +215 -0
  691. package/templates/current/{clean/src → examples/tests/unit}/app/origenUiLocale.spec.ts +1 -1
  692. package/templates/current/{clean/src → examples/tests/unit}/app/permission.spec.ts +4 -5
  693. package/templates/current/examples/tests/unit/app/runtimeConfig.spec.ts +36 -0
  694. package/templates/current/{clean/src/features → examples/tests/unit/app}/security/devtoolsProtection.spec.ts +17 -7
  695. package/templates/current/{clean/src/features/shell → examples/tests/unit}/composables/useRouteProgress.spec.ts +1 -1
  696. package/templates/current/{clean/src/features/shell/components → examples/tests/unit/layouts}/AdminWatermark.spec.ts +5 -7
  697. package/templates/current/{clean/src → examples/tests/unit}/layouts/topBarMenuSearch.spec.ts +25 -8
  698. package/templates/current/examples/{src → tests/unit}/locales/messages.spec.ts +43 -17
  699. package/templates/current/examples/tests/unit/router/dynamicMenuRefresh.spec.ts +151 -0
  700. package/templates/current/examples/tests/unit/router/dynamicRoutes.spec.ts +374 -0
  701. package/templates/current/examples/tests/unit/router/paths.spec.ts +103 -0
  702. package/templates/current/examples/{src → tests/unit}/router/queryEncryption.spec.ts +49 -12
  703. package/templates/current/{clean/src → examples/tests/unit}/router/routeQuery.spec.ts +8 -1
  704. package/templates/current/examples/{src → tests/unit}/router/runtimeErrorRecovery.spec.ts +11 -6
  705. package/templates/current/{clean/src → examples/tests/unit}/router/useRouteQueryDefaults.spec.ts +46 -12
  706. package/templates/current/examples/tests/unit/scripts/mock-api.spec.ts +440 -0
  707. package/templates/current/examples/{scripts → tests/unit/scripts}/vite-build-policy.spec.ts +35 -6
  708. package/templates/current/examples/{src/features/auth → tests/unit}/store/auth.spec.ts +100 -15
  709. package/templates/current/examples/tests/unit/store/dictionaries.spec.ts +106 -0
  710. package/templates/current/{clean/src → examples/tests/unit}/templates/templates.spec.ts +58 -16
  711. package/templates/current/examples/{src/utils/__tests__ → tests/unit/utils}/color-mix.spec.ts +1 -1
  712. package/templates/current/examples/tests/unit/utils/retryableDialog.spec.ts +61 -0
  713. package/templates/current/examples/{scripts/clean-overlay/src/features/errors/pages → tests/unit/views/errors}/error-pages.spec.ts +12 -9
  714. package/templates/current/examples/tests/unit/views/feature-composables.spec.ts +233 -0
  715. package/templates/current/examples/tests/unit/views/system/access/admin-repository.spec.ts +353 -0
  716. package/templates/current/examples/tests/unit/views/system/access/rbac.spec.ts +329 -0
  717. package/templates/current/examples/tests/unit/views/system/dept/departments.spec.ts +104 -0
  718. package/templates/current/examples/tests/unit/views/system/dict/dictionaries.spec.ts +234 -0
  719. package/templates/current/examples/tests/unit/views/system/menu/menuDraft.spec.ts +77 -0
  720. package/templates/current/examples/tests/unit/views/system/menu/useMenuManagement.spec.ts +339 -0
  721. package/templates/current/examples/tests/unit/views/system/user/searchControl.spec.ts +128 -0
  722. package/templates/current/examples/tsconfig.json +4 -19
  723. package/templates/current/examples/vite.build-policy.ts +97 -22
  724. package/templates/current/examples/vite.config.ts +50 -7
  725. package/templates/current/clean/.codebuddy/AGENTS.md +0 -18
  726. package/templates/current/clean/.codex/skills/build-admin-feature/SKILL.md +0 -14
  727. package/templates/current/clean/.codex/skills/build-admin-feature/references/component-selection.md +0 -25
  728. package/templates/current/clean/.codex/skills/use-og-table/SKILL.md +0 -16
  729. package/templates/current/clean/.cursor/AGENTS.md +0 -18
  730. package/templates/current/clean/.env.production.example +0 -31
  731. package/templates/current/clean/.qoder/AGENTS.md +0 -15
  732. package/templates/current/clean/e2e/admin-shell.spec.ts +0 -156
  733. package/templates/current/clean/e2e/demo-shell.spec.ts +0 -372
  734. package/templates/current/clean/playwright.demo.config.ts +0 -25
  735. package/templates/current/clean/scripts/clean-overlay/src/features/errors/pages/NotFound.vue +0 -31
  736. package/templates/current/clean/scripts/clean-overlay/src/features/errors/pages/ServerError.vue +0 -31
  737. package/templates/current/clean/scripts/clean-overlay/src/features/errors/pages/error-pages.spec.ts +0 -41
  738. package/templates/current/clean/scripts/clean-overlay/src/main.ts +0 -100
  739. package/templates/current/clean/scripts/clean-overlay/src/router/componentCache.ts +0 -12
  740. package/templates/current/clean/scripts/clean-overlay/src/router/componentRegistry.ts +0 -14
  741. package/templates/current/clean/scripts/clean-overlay/src/router/dynamicRoutes.spec.ts +0 -77
  742. package/templates/current/clean/scripts/clean-overlay/src/router/paths.ts +0 -21
  743. package/templates/current/clean/scripts/clean-overlay/src/router/staticRoutes.ts +0 -63
  744. package/templates/current/clean/scripts/demo-api.ts +0 -873
  745. package/templates/current/clean/src/api/client.spec.ts +0 -66
  746. package/templates/current/clean/src/api/client.ts +0 -152
  747. package/templates/current/clean/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/345/206/205/345/256/271/346/226/207/347/253/240.ts +0 -144
  748. package/templates/current/clean/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/345/256/241/350/256/241.ts +0 -50
  749. package/templates/current/clean/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/346/226/207/344/273/266/344/270/212/344/274/240.ts +0 -63
  750. package/templates/current/clean/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/347/224/250/346/210/267.ts +0 -169
  751. package/templates/current/clean/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/350/217/234/345/215/225.ts +0 -180
  752. package/templates/current/clean/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/350/247/222/350/211/262.ts +0 -167
  753. package/templates/current/clean/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/350/256/242/345/215/225/350/215/211/347/250/277.ts +0 -168
  754. package/templates/current/clean/src/api/generated//350/256/244/350/257/201.ts +0 -95
  755. package/templates/current/clean/src/api/http-adapter.ts +0 -83
  756. package/templates/current/clean/src/app/createAdminUi.spec.ts +0 -166
  757. package/templates/current/clean/src/app/createAdminUi.ts +0 -63
  758. package/templates/current/clean/src/app/embedded-token.spec.ts +0 -40
  759. package/templates/current/clean/src/app/embedded.spec.ts +0 -135
  760. package/templates/current/clean/src/app/embedded.ts +0 -255
  761. package/templates/current/clean/src/app/errorMessage.ts +0 -53
  762. package/templates/current/clean/src/app/menu-host.spec.ts +0 -77
  763. package/templates/current/clean/src/app/menu.spec.ts +0 -320
  764. package/templates/current/clean/src/app/menu.ts +0 -308
  765. package/templates/current/clean/src/app/menuTypes.ts +0 -18
  766. package/templates/current/clean/src/app/origenUiLocale.ts +0 -10
  767. package/templates/current/clean/src/app/permission.ts +0 -9
  768. package/templates/current/clean/src/demo-api.spec.ts +0 -478
  769. package/templates/current/clean/src/features/errors/pages/error-pages.spec.ts +0 -41
  770. package/templates/current/clean/src/features/system/access/api/admin-repository.spec.ts +0 -14
  771. package/templates/current/clean/src/features/system/access/api/admin-repository.ts +0 -298
  772. package/templates/current/clean/src/features/system/access/api/rbac.spec.ts +0 -72
  773. package/templates/current/clean/src/features/system/access/api/rbac.ts +0 -292
  774. package/templates/current/clean/src/features/system/access/composables/useAuthorizationPolling.spec.ts +0 -134
  775. package/templates/current/clean/src/features/system/access/composables/useAuthorizationPolling.ts +0 -96
  776. package/templates/current/clean/src/features/workspace/pages/Profile.vue +0 -185
  777. package/templates/current/clean/src/router/componentCache.ts +0 -12
  778. package/templates/current/clean/src/router/componentRegistry.ts +0 -14
  779. package/templates/current/clean/src/router/dynamicMenuRefresh.spec.ts +0 -101
  780. package/templates/current/clean/src/router/dynamicRoutes.spec.ts +0 -77
  781. package/templates/current/clean/src/router/dynamicRoutes.ts +0 -177
  782. package/templates/current/clean/src/router/guards.ts +0 -5
  783. package/templates/current/clean/src/router/paths.spec.ts +0 -50
  784. package/templates/current/clean/src/router/paths.ts +0 -21
  785. package/templates/current/clean/src/router/routeQuery.ts +0 -6
  786. package/templates/current/clean/src/router/staticRoutes.ts +0 -63
  787. package/templates/current/clean/src/router/useRouteQueryDefaults.types.ts +0 -20
  788. package/templates/current/clean/tsconfig.node.json +0 -9
  789. package/templates/current/examples/.codebuddy/AGENTS.md +0 -18
  790. package/templates/current/examples/.codex/skills/build-admin-feature/SKILL.md +0 -14
  791. package/templates/current/examples/.codex/skills/build-admin-feature/references/component-selection.md +0 -25
  792. package/templates/current/examples/.codex/skills/use-og-table/SKILL.md +0 -16
  793. package/templates/current/examples/.cursor/AGENTS.md +0 -18
  794. package/templates/current/examples/.env.production.example +0 -31
  795. package/templates/current/examples/.qoder/AGENTS.md +0 -15
  796. package/templates/current/examples/e2e/admin-shell.spec.ts +0 -156
  797. package/templates/current/examples/e2e/demo-shell.spec.ts +0 -372
  798. package/templates/current/examples/playwright.demo.config.ts +0 -25
  799. package/templates/current/examples/scripts/clean-overlay/src/features/errors/pages/Forbidden.vue +0 -31
  800. package/templates/current/examples/scripts/clean-overlay/src/main.ts +0 -100
  801. package/templates/current/examples/scripts/clean-overlay/src/router/componentCache.ts +0 -12
  802. package/templates/current/examples/scripts/clean-overlay/src/router/componentRegistry.ts +0 -14
  803. package/templates/current/examples/scripts/clean-overlay/src/router/dynamicRoutes.spec.ts +0 -77
  804. package/templates/current/examples/scripts/clean-overlay/src/router/paths.ts +0 -21
  805. package/templates/current/examples/scripts/clean-overlay/src/router/staticRoutes.ts +0 -63
  806. package/templates/current/examples/scripts/demo-api.ts +0 -873
  807. package/templates/current/examples/src/api/client.spec.ts +0 -66
  808. package/templates/current/examples/src/api/client.ts +0 -152
  809. package/templates/current/examples/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/345/206/205/345/256/271/346/226/207/347/253/240.ts +0 -144
  810. package/templates/current/examples/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/345/256/241/350/256/241.ts +0 -50
  811. package/templates/current/examples/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/346/226/207/344/273/266/344/270/212/344/274/240.ts +0 -63
  812. package/templates/current/examples/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/347/224/250/346/210/267.ts +0 -169
  813. package/templates/current/examples/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/350/217/234/345/215/225.ts +0 -180
  814. package/templates/current/examples/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/350/247/222/350/211/262.ts +0 -167
  815. package/templates/current/examples/src/api/generated//347/263/273/347/273/237/347/256/241/347/220/206/350/256/242/345/215/225/350/215/211/347/250/277.ts +0 -168
  816. package/templates/current/examples/src/api/generated//350/256/244/350/257/201.ts +0 -95
  817. package/templates/current/examples/src/api/http-adapter.ts +0 -83
  818. package/templates/current/examples/src/app/createAdminUi.spec.ts +0 -166
  819. package/templates/current/examples/src/app/createAdminUi.ts +0 -63
  820. package/templates/current/examples/src/app/embedded-token.spec.ts +0 -40
  821. package/templates/current/examples/src/app/embedded.spec.ts +0 -135
  822. package/templates/current/examples/src/app/embedded.ts +0 -255
  823. package/templates/current/examples/src/app/errorMessage.ts +0 -53
  824. package/templates/current/examples/src/app/menu-host.spec.ts +0 -77
  825. package/templates/current/examples/src/app/menu.spec.ts +0 -320
  826. package/templates/current/examples/src/app/menu.ts +0 -308
  827. package/templates/current/examples/src/app/menuTypes.ts +0 -18
  828. package/templates/current/examples/src/app/origenUiLocale.ts +0 -10
  829. package/templates/current/examples/src/app/permission.ts +0 -9
  830. package/templates/current/examples/src/demo-api.spec.ts +0 -478
  831. package/templates/current/examples/src/features/errors/pages/Forbidden.vue +0 -31
  832. package/templates/current/examples/src/features/errors/pages/NotFound.vue +0 -31
  833. package/templates/current/examples/src/features/errors/pages/ServerError.vue +0 -31
  834. package/templates/current/examples/src/features/feature-composables.spec.ts +0 -245
  835. package/templates/current/examples/src/features/system/access/api/admin-repository.spec.ts +0 -14
  836. package/templates/current/examples/src/features/system/access/api/admin-repository.ts +0 -298
  837. package/templates/current/examples/src/features/system/access/api/rbac.spec.ts +0 -72
  838. package/templates/current/examples/src/features/system/access/api/rbac.ts +0 -292
  839. package/templates/current/examples/src/features/system/access/composables/useAuthorizationPolling.spec.ts +0 -134
  840. package/templates/current/examples/src/features/system/access/composables/useAuthorizationPolling.ts +0 -96
  841. package/templates/current/examples/src/features/system/audit/composables/useAuditManagement.ts +0 -122
  842. package/templates/current/examples/src/features/system/audit/pages/AuditList.vue +0 -20
  843. package/templates/current/examples/src/features/system/menus/components/MenuEditorForm.vue +0 -279
  844. package/templates/current/examples/src/features/system/menus/composables/useMenuManagement.ts +0 -435
  845. package/templates/current/examples/src/features/system/menus/menuDraft.spec.ts +0 -204
  846. package/templates/current/examples/src/features/system/menus/menuDraft.ts +0 -116
  847. package/templates/current/examples/src/features/system/menus/menuTreePrecheck.spec.ts +0 -268
  848. package/templates/current/examples/src/features/system/menus/menuTreePrecheck.ts +0 -317
  849. package/templates/current/examples/src/features/system/menus/pages/MenuList.vue +0 -51
  850. package/templates/current/examples/src/features/system/roles/components/RoleEditorForm.vue +0 -116
  851. package/templates/current/examples/src/features/system/roles/composables/useRoleManagement.ts +0 -194
  852. package/templates/current/examples/src/features/system/roles/pages/RoleList.vue +0 -47
  853. package/templates/current/examples/src/features/system/users/components/UserEditorForm.vue +0 -104
  854. package/templates/current/examples/src/features/system/users/composables/useUserManagement.ts +0 -228
  855. package/templates/current/examples/src/features/system/users/pages/UserList.vue +0 -51
  856. package/templates/current/examples/src/features/workspace/pages/Dashboard.spec.ts +0 -41
  857. package/templates/current/examples/src/features/workspace/pages/Dashboard.vue +0 -325
  858. package/templates/current/examples/src/features/workspace/pages/Profile.vue +0 -185
  859. package/templates/current/examples/src/router/componentCache.ts +0 -18
  860. package/templates/current/examples/src/router/componentRegistry.ts +0 -66
  861. package/templates/current/examples/src/router/dynamicMenuRefresh.spec.ts +0 -101
  862. package/templates/current/examples/src/router/dynamicRoutes.spec.ts +0 -144
  863. package/templates/current/examples/src/router/dynamicRoutes.ts +0 -177
  864. package/templates/current/examples/src/router/guards.ts +0 -5
  865. package/templates/current/examples/src/router/paths.spec.ts +0 -50
  866. package/templates/current/examples/src/router/paths.ts +0 -21
  867. package/templates/current/examples/src/router/routeQuery.ts +0 -6
  868. package/templates/current/examples/src/router/staticRoutes.ts +0 -63
  869. package/templates/current/examples/src/router/useRouteQueryDefaults.types.ts +0 -20
  870. package/templates/current/examples/tsconfig.node.json +0 -9
  871. /package/templates/current/clean/{.codex → .agents}/skills/style-og-origen-ui/SKILL.md +0 -0
  872. /package/templates/current/clean/{.codex → .agents}/skills/style-og-origen-ui/agents/openai.yaml +0 -0
  873. /package/templates/current/clean/{.codex → .agents}/skills/use-og-dialog/SKILL.md +0 -0
  874. /package/templates/current/clean/{.codex → .agents}/skills/use-og-dialog/agents/openai.yaml +0 -0
  875. /package/templates/current/clean/{.codex → .agents}/skills/use-og-editor/SKILL.md +0 -0
  876. /package/templates/current/clean/{.codex → .agents}/skills/use-og-http/SKILL.md +0 -0
  877. /package/templates/current/clean/{.codex → .agents}/skills/use-og-http/agents/openai.yaml +0 -0
  878. /package/templates/current/clean/{.codex → .agents}/skills/use-og-router-tabs/SKILL.md +0 -0
  879. /package/templates/current/{examples/.codex → clean/.claude}/skills/style-og-origen-ui/SKILL.md +0 -0
  880. /package/templates/current/{examples/.codex → clean/.claude}/skills/use-og-dialog/SKILL.md +0 -0
  881. /package/templates/current/{examples/.codex → clean/.claude}/skills/use-og-editor/SKILL.md +0 -0
  882. /package/templates/current/{examples/.codex → clean/.claude}/skills/use-og-http/SKILL.md +0 -0
  883. /package/templates/current/{examples/.codex → clean/.claude}/skills/use-og-router-tabs/SKILL.md +0 -0
  884. /package/templates/current/clean/src/{features/security/components → components}/DevtoolsProtectionOverlay.vue +0 -0
  885. /package/templates/current/clean/src/{features/shell/composables → composables}/useRouteProgress.ts +0 -0
  886. /package/templates/current/clean/src/{features/workspace → views/fallback}/pages/Empty.vue +0 -0
  887. /package/templates/current/examples/{.codex → .agents}/skills/style-og-origen-ui/agents/openai.yaml +0 -0
  888. /package/templates/current/examples/{.codex → .agents}/skills/use-og-dialog/agents/openai.yaml +0 -0
  889. /package/templates/current/examples/{.codex → .agents}/skills/use-og-http/agents/openai.yaml +0 -0
  890. /package/templates/current/examples/src/{features/security/components → components}/DevtoolsProtectionOverlay.vue +0 -0
  891. /package/templates/current/examples/src/{features/shell/composables → composables}/useRouteProgress.ts +0 -0
  892. /package/templates/current/examples/src/{features/workspace → views/fallback}/pages/Empty.vue +0 -0
@@ -0,0 +1,1205 @@
1
+ ---
2
+ title: OgSearch
3
+ description: 面向后台查询条件的响应式搜索组件。
4
+ ---
5
+
6
+ # OgSearch
7
+
8
+ 根入口 Props 类型为 `OgSearchProps`。
9
+
10
+ `OgSearch` 将查询模型、字段校验、异步选项和响应式栅格收敛为独立组件。它不会发起请求;业务方在 `search` 事件中消费已转换的 `params`,`OgTableWithSearch` 组合组件可自动完成这一接线。
11
+
12
+ ## 何时使用
13
+
14
+ - 后台列表页需要一组可配置的查询条件,且希望与 OgTable 的 `request` 自动对接。
15
+ - 字段之间存在联动、异步选项或权限控制。
16
+ - 需要将查询条件折叠/展开,并适配不同容器宽度。
17
+ - 查询条件由 Schema 驱动,需要统一处理校验、参数转换和本地化。
18
+ - 需要快速搜索关键字 + 结构化字段的组合查询模式。
19
+
20
+ ### 与 OgForm 的区别
21
+
22
+ `OgSearch` 专注于查询场景,相比 `OgForm` 更轻量:无分组布局、无只读模式、无动态增删字段,但额外提供了快速搜索、折叠/展开、响应式列布局和 `search`/`reset` 事件载荷(含转换后的 `params`)。如果需要完整的表单能力(编辑、详情、分组),应使用 `OgForm`。
23
+
24
+ ## 基础用法
25
+
26
+ ```vue
27
+ <OgSearch
28
+ v-model="query"
29
+ v-model:og-keyword="keyword"
30
+ :og-config="{
31
+ fields: [{ prop: 'status', label: '状态', ogControl: { ogType: 'select' }, options }],
32
+ }"
33
+ @search="requestList($event.params)"
34
+ />
35
+ ```
36
+
37
+ <div id="search-independent"></div>
38
+ ### 独立查询
39
+
40
+ 输入关键字或选择条件后提交,观察范围字段被拆成服务端参数。
41
+
42
+ ## 典型用法
43
+
44
+ <div id="search-label-layout"></div>
45
+ <div id="search-label-width"></div>
46
+ ### 搜索标签布局
47
+
48
+ 合并控件内标签与固定标签宽度,直接比较两种标签布局。
49
+
50
+ <div id="search-state-commands"></div>
51
+ <div id="search-state"></div>
52
+ <div id="search-commands"></div>
53
+ ### 状态与命令式 API
54
+
55
+ 合并加载、禁用、重置和命令式提交,展示组件状态与实例 API。
56
+
57
+ ## 高级能力
58
+
59
+ <div id="search-collapsed-summary"></div>
60
+ ### 折叠条件摘要
61
+
62
+ 在窄容器中折叠多余字段,并保留已填写条件的可见摘要。
63
+
64
+ <div id="search-async-fields"></div>
65
+ <div id="search-async-options"></div>
66
+ <div id="search-permissions"></div>
67
+ <div id="search-all-fields"></div>
68
+ ### 异步选项、权限与字段类型
69
+
70
+ 合并异步选项取消、字段权限和全部内置字段类型,覆盖完整查询字段能力。
71
+
72
+ <p class="component-examples-link">跨组件组合见<a href="./table-with-search.md">OgTableWithSearch</a>和<a href="../../.agents/skills/admin-component-usage/references/component-directory.md">数据与查询场景</a>。</p>
73
+
74
+ <div id="search-renderer-registry"></div>
75
+ ### 注册业务控件
76
+
77
+ 通过实例注册表接入评分控件,复用搜索模型与提交载荷。
78
+
79
+ ## API
80
+
81
+ ### 安装
82
+
83
+ ```bash
84
+ pnpm add @origen-ui/search
85
+ ```
86
+
87
+ 也可通过聚合包 `origen-ui` 引入,无需单独安装。
88
+
89
+ ### 实例级控件注册表
90
+
91
+ 内置控件的属性、事件和插槽保持原有严格类型。扩展控件使用独立的 `custom:名称` 判别值;`custom` 本身仍表示 `field-{prop}` 插槽,不通过注册表,也不能注册为 renderer。`custom:名称` 必须有非空且不含空白的名称;未知、未注册或无效类型会明确报错,包括当前折叠、隐藏或无权限的字段。
92
+
93
+ `createSearchRendererRegistry<Query>()` 创建带九个内置控件的独立注册表。通过实例 `ogRendererRegistry` 传入;未传时,每个 OgSearch 创建自己的默认注册表,嵌套实例也如此。显式传入同一个对象才会共享注册和替换结果。`createOgSearch` 的应用级默认不接受注册表。
94
+
95
+ `register(type, renderer)` 新增扩展或替换内置 renderer,返回可重复调用的撤销函数。撤销恢复仍然有效的上一项,允许乱序撤销;撤销最后一个自定义注册后,该类型变为未知。注册、撤销和更换整个 prop 都会更新已挂载的控件,不重置查询模型。移除正在使用的类型前,先修改字段配置。快速搜索仍使用独立的 ElInput,不受注册表中的 input 替换影响。
96
+
97
+ `renderer(context)` 返回 Vue `VNodeChild`。`OgSearchRendererContext<T>` 包含 `field`、`model`、`value`、`update(value)`、`submit()`、`disabled`、`controlId`、`describedby`、`size`、`placeholder`、`datePickerId`、`options`、`loading` 和 `optionsError`。`loading` 表示异步选项正在加载;`disabled` 已合并实例与字段禁用条件。`describedby` 合并字段 aria-describedby 与选项错误说明。`model` 为浅快照,嵌套值及 `value` 保留原身份,须视为借用数据;通过 update 写回,不直接修改对象。原有 field 插槽继续获得自己的不可变快照。
98
+
99
+ 自定义 renderer 负责把 value/update、禁用、id 与 aria-describedby 绑定到实际控件,并自行适配其业务 props、ogEvents、ogSlots 和键盘操作;这些未知组件接口不会被自动猜测或透传。必须通过 `context.submit()` 提交,才能复用校验、禁用和并发提交约束。内置 renderer 的默认选项、官方 props/events/slots、日期范围 id 和受控回写仍由包内实现负责。自定义值的折叠摘要若需专用格式,使用字段 `summaryFormatter`。
100
+
101
+ `provideSearchRendererRegistry(registryOrRefOrGetter)` 与 `useSearchRendererRegistry<Query>()` 供明确的子树/provider 使用;后者返回只读 `ComputedRef<OgSearchRendererRegistry<Query>>`,无 provider 时抛错。OgSearch 会向自身后代提供当前选中的 registry,并随 prop 替换更新;它不会从祖先搜索实例继承 registry。注入 key 在运行时无法校验模型泛型,调用方必须保证 Query 一致。
102
+
103
+ 上述三个函数及 `OgSearchRenderer`、`OgSearchRendererContext`、`OgSearchRendererRegistry` 由 `@origen-ui/search` 根入口和 `origen-ui` 聚合入口导出;轻量 `@origen-ui/search/runtime` 继续只承载应用展示配置与 locale,不加载控件注册表。`OgTableWithSearch` 使用 `ogSearch.props.ogRendererRegistry` 接入。
104
+
105
+ ## 快速搜索
106
+
107
+ 快速搜索是组件内置的关键字输入框,独立于结构化字段,通过 `v-model:og-keyword` 双向绑定。提交时载荷仍以 `keyword` 作为查询关键字字段,由业务方决定如何使用。
108
+
109
+ ### 启用与配置
110
+
111
+ 快速搜索默认启用。通过 `ogConfig.quickSearch` 控制:
112
+
113
+ ```ts
114
+ // 启用(默认)
115
+ const config = { quickSearch: true }
116
+
117
+ // 自定义占位文本
118
+ const config = { quickSearch: { placeholder: '输入姓名或编号搜索' } }
119
+
120
+ // 禁用快速搜索
121
+ const config = { quickSearch: false }
122
+ ```
123
+
124
+ ### 关键字行为
125
+
126
+ - 输入时触发 `update:ogKeyword` 事件,但不会自动提交。
127
+ - 在任意原生表单输入内按 Enter 会走同一条表单提交路径(`ogSubmitOnEnter` 默认 `true`),不会与输入控件的键盘事件重复提交。
128
+ - 重置行为通过 `ogReset` 配置;默认会清空关键字并触发 `reset` 事件。
129
+ - 快速搜索占据一个栅格单元,折叠模式下仍然可见。
130
+
131
+ ### 在提交中使用
132
+
133
+ `search` 事件的载荷包含 `keyword` 字段:
134
+
135
+ ```vue
136
+ <OgSearch v-model="query" v-model:og-keyword="keyword" :og-config="config" @search="handleSearch" />
137
+ ```
138
+
139
+ ```ts
140
+ function handleSearch(payload: OgSearchSubmitPayload<MyQuery>) {
141
+ const { keyword, params } = payload
142
+ // 将关键字合并到请求参数
143
+ requestList({ ...params, keyword })
144
+ }
145
+ ```
146
+
147
+ ## 布局
148
+
149
+ `ogExpanded` 可选。未使用 `v-model:og-expanded` 时,更多/收起由组件内部状态驱动;使用后为严格受控模式,点击只触发 `update:ogExpanded`,父组件回写新值后界面才更新。解除受控时会保留最后一次受控值。
150
+
151
+ 快速搜索与配置字段均使用 Element Plus 表单项,并在独立字段栅格内排列。`columns` 始终表示每行字段数量,操作按钮不占字段列;桌面端按钮在字段区右侧与首行控件顶边对齐,单列时移到字段区下方并右对齐。展开后新增字段只会进入字段栅格,展开/收起按钮始终可双向切换。
152
+
153
+ 折叠状态下,有值且实际被隐藏的字段会在表单下方显示摘要。选择类字段优先显示 option label,日期范围显示起止值;多选默认展示前三项,其余值通过 `+N` 提示查看。点击摘要正文会展开并聚焦字段,清除按钮只更新当前搜索草稿,不会自动触发 `search`。展开搜索区后摘要隐藏。
154
+
155
+ 字段 `prop` 必须属于查询模型。`options` 与 `optionsApi(model, signal)` 二选一;异步选项只会在字段新增、加载器变更或其声明的依赖变化时刷新,并会取消隐藏、移除、替换或卸载字段的在途请求。搜索仅在点击查询或按 Enter 时提交,默认值仅用于首次初始化;重置清空所有搜索条件且不会自动请求。
156
+
157
+ 容器宽度默认按 1、2、3、4 列切换。`alwaysVisible` 可保证关键条件在折叠状态下可见,`span` 控制字段占列数;设置大于 `1` 的 `span` 会相应减少该行可显示的字段数量。
158
+
159
+ ### 标签布局
160
+
161
+ 标签超出的部分截断后把完整文本保留在 `title` 属性中:外部表单标签最多显示两行,控件内标签只显示一行。两种布局的宽度基线不同:
162
+
163
+ | 布局 | `ogLabelPlacement` | 宽度 | 对齐 |
164
+ | -------------------- | ------------------ | ------------------------------------------------------------------ | ------ |
165
+ | 外部表单标签(默认) | `'form'` | 固定 `--og-search-form-label-width`,默认 `88px` | 右对齐 |
166
+ | 控件内左侧标签 | `'control'` | 随内容自适应,最大 `--og-search-control-label-width`,默认 `100px` | 左对齐 |
167
+
168
+ 外部表单标签布局保留 Element Plus 内置控件的边框;控件内标签布局使用组合外框承接边框与焦点状态,内置控件不再重复显示边框。
169
+
170
+ 默认情况下标签由 Element Plus `ElFormItem` 在控件外部渲染,标签列固定 `88px` 以保证各字段控件左边界对齐。需要压缩搜索区域时,可以将标签放入控件左侧;此时标签宽度由内容决定,只有显式配置宽度才会变成固定列:
171
+
172
+ ```ts
173
+ app.use(
174
+ createOgSearch({
175
+ ogLabelPlacement: 'control',
176
+ // 需要对齐各字段控件左边界时再设置;不设置则标签贴合文字宽度
177
+ ogControlLabelWidth: 100,
178
+ ogControlLabelStyle: { color: 'var(--el-text-color-regular)' },
179
+ }),
180
+ )
181
+ ```
182
+
183
+ 实例 `ogLabelPlacement`、`ogControlLabelWidth`、`ogControlLabelStyle` 优先于全局配置。字段的 `labelWidth` 和 `labelStyle` 在两种布局下都生效,可覆盖各自默认值;数字宽度按像素处理,字符串宽度按 CSS 值处理。
184
+
185
+ 外部表单标签未配置宽度时使用 `--og-search-form-label-width`(默认 `88px`),可通过 CSS 变量统一调整,也可以用顶层 Element Plus `labelWidth` 设置表单级宽度,其优先级低于字段级 `labelWidth`。控件内标签宽度随内容自适应,默认以 `--og-search-control-label-width`(`100px`)为最大宽度;通过 `ogControlLabelWidth` 或该 CSS 变量可调整上限,设置后该值同时作为标签的宽度与最大宽度。
186
+
187
+ `label-{prop}` 插槽用于替换字段标签,`keyword-label` 插槽用于替换快速搜索标签;两者作用域均包含 `label` 和 `placement`,字段标签还包含 `field`。
188
+
189
+ ## Props
190
+
191
+ | 名称 | 类型 | 默认值 | 说明 |
192
+ | ---------------------- | -------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------- |
193
+ | modelValue | `Partial<T>` | — | 查询模型,与 `v-model` 双向绑定 |
194
+ | ogKeyword | `string` | `''` | 快速搜索关键字,与 `v-model:og-keyword` 双向绑定 |
195
+ | ogExpanded | `boolean` | 内部 `false` | 折叠状态;传入 `v-model:og-expanded` 后由父组件控制 |
196
+ | ogConfig | `OgSearchConfig<T>` | `{}` | 搜索字段、布局、本地化和摘要等实例配置 |
197
+ | ogLoading | `boolean` | `false` | 查询按钮加载状态 |
198
+ | ogSubmitOnEnter | `boolean` | `true` | 在任意字段输入框内按 Enter 触发 `search` |
199
+ | ogReset | `{ emit?: boolean, clearKeyword?: boolean }` | `{}` | 重置事件与关键字清理策略 |
200
+ | ogShowReset | `boolean` | `true` | 显示重置按钮 |
201
+ | ogShowToggle | `boolean` | `true` | 存在被折叠字段时显示展开/收起按钮;设为 `false` 时始终展示全部字段 |
202
+ | ogRendererRegistry | `OgSearchRendererRegistry<T, TField>` | 每实例独立默认 | 显式实例注册表;更换不重置模型 |
203
+ | ogPermissions | `OgSearchPermissions` | — | 权限检查器,包含 `has` 方法 |
204
+ | ogLabelPlacement | `'form' \| 'control'` | `'form'` | 标签放在表单标签区或控件左侧 |
205
+ | ogControlLabelWidth | `number \| string` | — | 控件内标签宽度;未设置时随内容自适应(最大 `100px`),设置后作为宽度与最大宽度 |
206
+ | ogControlLabelStyle | `SearchLabelStyle` | — | 控件内标签默认样式 |
207
+ | labelPosition | `FormProps['labelPosition']` | `ogForm` / `'left'` | Element Plus `ElForm` 标签位置;实例 prop 优先于应用级 `ogForm` 默认值。 |
208
+ | labelSuffix | `FormProps['labelSuffix']` | — | Element Plus `ElForm` 标签后缀;未设置时使用其原生默认行为。 |
209
+ | showMessage | `FormProps['showMessage']` | — | 是否显示校验错误信息;未设置时使用 Element Plus `ElForm` 的原生默认行为。 |
210
+ | inlineMessage | `FormProps['inlineMessage']` | `ogForm` / `true` | 表单级内联错误提示;实例 prop 优先于应用级 `ogForm` 默认值。 |
211
+ | statusIcon | `FormProps['statusIcon']` | `ogForm` / `false` | 是否在校验状态下显示图标;实例 prop 优先于应用级 `ogForm` 默认值。 |
212
+ | Element Plus Form 属性 | `FormProps` 中除 `model` 外的普通属性 | — | 直接使用官方名称放在组件根层,例如 `inline`、`labelWidth`、`rules`、`size`、`disabled` |
213
+
214
+ `model` 由 OgSearch 的 `modelValue` 接管。应用级 Element Plus Form 默认值通过 `createOgSearch({ ogForm })` 配置;`OgSearchFormProps` 是该应用级默认值类型,不是组件实例的 prop bag。
215
+
216
+ ## Config 配置项
217
+
218
+ `ogConfig` 属性类型为 `OgSearchConfig<T>`,控制字段列表、布局和本地化等。
219
+
220
+ | 名称 | 类型 | 默认值 | 说明 |
221
+ | ----------------- | -------------------------------------------------------------- | ------ | -------------------------------------------------------------------------- |
222
+ | fields | `OgSearchField<T>[]` | `[]` | 查询字段定义数组 |
223
+ | quickSearch | `boolean \| OgSearchQuickSearchConfig` | — | 启用快速搜索;对象直接接受 Element Plus Input 属性及 `ogEvents`、`ogSlots` |
224
+ | columns | `number` | — | 搜索控件响应式列数上限,默认上限为 4 列;不包含操作按钮 |
225
+ | responsiveColumns | `false \| ResponsiveColumnRule[]` | — | 自定义响应式列规则;`false` 固定列数,但窄于 640px 时始终单列 |
226
+ | collapsedRows | `number` | — | 折叠状态下保留的行数 |
227
+ | collapsedSummary | `boolean \| { maxValues?: number }` | `true` | 显示隐藏字段摘要;`maxValues` 默认为 `3` |
228
+ | locale | `Partial<SearchLocale>` | — | 覆盖默认文案 |
229
+ | modelTransform | `(params: Record<string, unknown>) => Record<string, unknown>` | — | 提交前对参数做最终转换 |
230
+
231
+ ## Field 字段配置
232
+
233
+ 每个字段定义的类型为 `OgSearchField<T>`,支持以下属性:
234
+
235
+ | 名称 | 类型 | 默认值 | 说明 |
236
+ | ----------------------- | ------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
237
+ | prop | `keyof T & string` | — | **必填**。对应模型中的字段名 |
238
+ | label | `string` | — | **必填**。字段标签 |
239
+ | labelWidth | `number \| string` | — | 字段级标签宽度,两种标签布局均生效;数字按像素处理 |
240
+ | labelStyle | `SearchLabelStyle` | — | 字段级标签样式,两种标签布局均生效,覆盖实例默认样式 |
241
+ | ogControl.ogType | `SearchFieldType` | `'input'` | 控件类型:`input`、`number`、`select`、`tree-select`、`cascader`、`date`、`daterange`、`datetime`、`datetimerange`、`custom` |
242
+ | defaultValue | `T[K]` | — | 首次初始化时的字段默认值;重置会清空字段,不恢复此值 |
243
+ | ogControl.placeholder | `string` | — | 控件占位文本 |
244
+ | ogControl.clearable | `boolean` | — | 是否显示清除按钮 |
245
+ | required | `boolean` | `false` | 是否必填,提交前会校验 |
246
+ | validator | `(value, model) => string \| void \| Promise<string \| void>` | — | 自定义校验函数,返回字符串表示错误信息 |
247
+ | visible | `boolean \| ((model) => boolean)` | `true` | 控制字段是否可见,支持函数动态判断 |
248
+ | disabled | `boolean \| ((model) => boolean)` | `false` | 控制字段是否禁用,支持函数动态判断 |
249
+ | permission | `Permission` | — | 字段级权限标识,配合 `permissions.has` 使用 |
250
+ | dependencies | `Array<keyof T & string>` | — | 依赖字段列表,依赖变化时刷新异步选项 |
251
+ | clearOnDependencyChange | `boolean` | `false` | 依赖字段变化时是否清空当前值 |
252
+ | alwaysVisible | `boolean` | `false` | 折叠状态下是否始终可见 |
253
+ | span | `number` | `1` | 字段占据的栅格列数 |
254
+ | startKey | `string` | — | 区间字段的起始键名,提交时拆为独立参数 |
255
+ | endKey | `string` | — | 区间字段的结束键名,提交时拆为独立参数 |
256
+ | transform | `(value, model) => Record<string, unknown>` | — | 自定义参数转换,返回值会合并到提交参数 |
257
+ | summaryFormatter | `(value, { model, options }) => string \| string[]` | — | 自定义折叠摘要文本;适用于 custom 字段或特殊对象值 |
258
+ | Element Plus 控件 props | `ogControl.ogType` 对应控件的官方属性 | — | 放入 ogControl,与 ogType 同级传入;只接受当前控件支持且未由 OgSearch 接管的普通属性。 |
259
+ | ogControl.ogEvents | 按 `ogType` 对应的 Element Plus 事件类型 | — | 类型化转发控件事件;`custom` 不接受此项。 |
260
+ | ogControl.ogSlots | 按 `ogType` 对应的 Element Plus 插槽类型 | — | 转发内置控件的具名插槽;Select 的 `default` 替换自动选项,Tree Select 的 `default` 自定义树节点内容。 |
261
+ | ogFormItem | `OgSearchFormItemProps` | — | 传递给当前字段 `<ElFormItem>` 的官方属性、HTML attrs 与 DOM 事件监听器;字段标签、路径、必填状态与布局由 OgSearch 控制。 |
262
+ | ogFormItemSlots | `OgSearchFormItemSlots` | — | 转发 `<ElFormItem>` 的 `error` 插槽;`label` 与默认插槽由 OgSearch 用于标签和控件内容。 |
263
+ | options | `SelectOption[]` | — | 静态选项列表,与 `optionsApi` 二选一 |
264
+ | optionsApi | `(model, signal) => Promise<SelectOption[]>` | — | 异步选项加载函数,支持 `AbortSignal` 取消 |
265
+
266
+ ### 字段类型与控件映射
267
+
268
+ `ogControl.ogType` 决定渲染的 Element Plus 控件;原生属性、`ogEvents`、`ogSlots` 放在同一个 `ogControl` 对象中。省略整个 `ogControl` 默认渲染 input;显式对象必须提供 `ogType`。字段级平铺的 `ogType`、`type`、原生控件属性及旧 `fieldProps` / `fieldSlots` / `formItemProps` 已移除,运行时明确报错。业务元数据、options/optionsApi、disabled 谓词与 `ogFormItem` / `ogFormItemSlots` 保留字段层。原生 Input 的 `type: 'password'` 放入 `ogControl`,不会被当作控件选择值。
269
+
270
+ ::: tip
271
+ 控件特有参数例如 `min`、`max`、`format` 或 `disabled-date` 放入 `ogControl`。`disabled`、必填状态和模型由 OgSearch 字段契约管理;支持清除的控件默认 `clearable: true`,可通过 `ogControl.clearable: false` 关闭。根级 Element Plus `size` 会传给控件。Select 和 Tree Select 的 `loading` 优先级见下方说明。
272
+
273
+ 对于 Select 和 Tree Select,`ogControl.loading` 在没有异步选项请求时会保留;`optionsApi` 请求进行期间,OgSearch 会将控件的 `loading` 设为 `true`,请求结束后恢复调用方传入的值。`ogControl['aria-describedby']` 会与 OgSearch 异步选项错误说明的 ID 合并并去重。
274
+
275
+ 控件普通属性会根据 `ogControl.ogType` 获得对应 Element Plus 控件的静态校验;`custom` 字段由外层 `field-{prop}` 插槽完整渲染,不使用 `ogEvents` 或 `ogSlots`。`ogFormItem` 只作用于该字段的 Element Plus `<ElFormItem>`,用于补充允许的官方属性、HTML attrs 与 DOM 事件监听器;Element Plus FormItem 没有声明组件事件。字段路径由 `field.prop` 绑定,字段必填与布局由 OgSearch 控制。字段 `ogFormItem.rules` 与根层 Element Plus `rules` 会对当前已挂载的字段项参与校验;折叠隐藏字段的 `ElFormItem` 未挂载,因此原生规则要等字段展开后才会参与校验。暴露的 `validate()` 和内置搜索提交会同时运行已挂载项的原生规则与 OgSearch 的 `required`/`validator` 校验;OgSearch 自有校验覆盖所有当前可用字段,包括折叠隐藏字段。两种校验同时命中同一字段时显示 OgSearch 字段校验错误。`ogFormItemSlots.error` 可替换原生错误内容;`label` 与默认插槽仍由 OgSearch 保留。官方属性和插槽详情参考 Element Plus 官方文档。
276
+
277
+ `ogSlots` 的插槽名与作用域参数按 `ogControl.ogType` 对应的 Element Plus 控件校验;`ogConfig.quickSearch` 对象支持直接 Input 属性以及 `ogEvents`、`ogSlots`,作用于内部 `<ElInput>`。Select 字段未提供 `ogControl.ogSlots.default` 时仍使用 `options` 或 `optionsApi` 生成选项;提供后由调用方接管选项内容。Element Plus Tree Select 的 `default` 插槽用于自定义树节点内容,作用域参数遵循 Element Plus Tree;Tree Select 仍负责树数据与缓存选项。官方插槽详情参考 Element Plus 官方文档。
278
+ :::
279
+
280
+ | `ogControl.ogType` | 控件 | 模型值类型 | 说明 |
281
+ | ------------------ | ------------------------------------- | ------------------------- | ---------------------------------------------------------------- |
282
+ | `input`(默认) | `<ElInput>` | `string` | 文本输入框 |
283
+ | `number` | `<ElInputNumber>` | `number \| undefined` | 数字输入框;`min`、`max`、`step` 等官方属性直接写在 ogControl 内 |
284
+ | `select` | `<ElSelect>` | `string \| number` | 下拉选择,选项由 `options` 或 `optionsApi` 提供 |
285
+ | `tree-select` | `<ElTreeSelect>` | `string \| number` | 树形选择,选项结构为树形 `data` |
286
+ | `cascader` | `<ElCascader>` | `Array<string \| number>` | 级联选择 |
287
+ | `date` | `<ElDatePicker type="date">` | `string` | 日期选择 |
288
+ | `daterange` | `<ElDatePicker type="daterange">` | `string[]` | 日期范围,配合 `startKey` / `endKey` 拆分为独立参数 |
289
+ | `datetime` | `<ElDatePicker type="datetime">` | `string` | 日期时间选择 |
290
+ | `datetimerange` | `<ElDatePicker type="datetimerange">` | `string[]` | 日期时间范围,同样支持 `startKey` / `endKey` |
291
+ | `custom` | 插槽 `field-{prop}` | 自定义 | 不渲染内置控件,由具名插槽完全自定义 |
292
+
293
+ ::: tip
294
+ 日期/时间类控件通过 `ogControl` 传递 Element Plus `DatePicker` 属性,如 `format`、`value-format`、`disabled-date` 等。
295
+ :::
296
+
297
+ 下方示例一次性渲染上表全部控件,并演示默认值、必填校验、依赖联动与区间拆分;默认使用**控件内标签布局**(`ogLabelPlacement="control"` + `ogControlLabelWidth`),可用开关切换到外部表单标签布局,直接对比两种标签样式:
298
+
299
+ ### 区间字段提交示例
300
+
301
+ 当字段声明了 `startKey` / `endKey` 时,模型值为数组,提交参数会被拆:
302
+
303
+ ```ts
304
+ { prop: 'dateRange', label: '日期', ogControl: { ogType: 'daterange' }, startKey: 'startDate', endKey: 'endDate' }
305
+ // 模型值 ['2024-01-01', '2024-12-31'] → 参数 { startDate: '2024-01-01', endDate: '2024-12-31' }
306
+ ```
307
+
308
+ ## 事件
309
+
310
+ | 名称 | 载荷类型 | 说明 |
311
+ | ----------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------- |
312
+ | update:modelValue | `Partial<T>` | 模型值变化时触发 |
313
+ | update:ogKeyword | `string` | 快速搜索关键字变化时触发 |
314
+ | search | `OgSearchSubmitPayload<T>` | 点击查询按钮或按 Enter 时触发,载荷包含 `keyword`、`model`、`params` |
315
+ | reset | `OgSearchSubmitPayload<T>` | 点击重置按钮后触发,载荷结构与 `search` 相同 |
316
+ | validate | `OgSearchFormValidateArgs` | 转发内部 Element Plus `ElForm` 的字段校验事件;一次表单校验可能按字段多次触发 |
317
+ | fieldChange | `{ prop: keyof T & string, value: unknown, model: Partial<T> }` | 任意字段值变化时触发 |
318
+ | optionsError | `{ prop: string, error: unknown }` | 异步选项加载失败时触发 |
319
+
320
+ ### 提交载荷
321
+
322
+ `search` 和 `reset` 事件的载荷类型为 `OgSearchSubmitPayload<T>`:
323
+
324
+ ```ts
325
+ interface OgSearchSubmitPayload<T> {
326
+ keyword: string // 当前快速搜索关键字
327
+ model: Partial<T> // 当前查询模型快照
328
+ params: Record<string, unknown> // 经转换后的服务端参数
329
+ }
330
+ ```
331
+
332
+ ## Expose API
333
+
334
+ 通过 `ref` 获取组件实例,可调用以下方法:
335
+
336
+ | 名称 | 类型 | 说明 |
337
+ | --------------- | ------------------------------------------------------ | ------------------------------------------ |
338
+ | validate | `() => Promise<boolean>` | 校验所有字段,返回是否通过 |
339
+ | submit | `() => Promise<OgSearchSubmitPayload<T> \| undefined>` | 执行校验并提交,校验失败返回 `undefined` |
340
+ | reset | `() => OgSearchSubmitPayload<T>` | 清空所有搜索字段并返回提交载荷 |
341
+ | getModel | `() => Partial<T>` | 获取当前查询模型快照 |
342
+ | getSubmitParams | `() => Record<string, unknown>` | 获取当前模型经转换后的提交参数 |
343
+ | setFieldValue | `(prop: K, value: T[K]) => void` | 设置单个字段的值 |
344
+ | setFields | `(value: Partial<T>) => void` | 批量设置字段值 |
345
+ | refreshOptions | `(props?) => Promise<void>` | 刷新指定字段(或全部)的异步选项 |
346
+ | cancelOptions | `(props?) => void` | 取消指定字段(或全部)的进行中异步选项请求 |
347
+ | focus | `(prop?) => void` | 聚焦指定字段,未传参时聚焦第一个无效字段 |
348
+ | getFieldError | `(prop) => string \| undefined` | 获取指定字段的校验错误信息 |
349
+ | clearErrors | `() => void` | 清除所有字段的校验错误 |
350
+ | isDirty | `() => boolean` | 判断当前值是否偏离默认值 |
351
+ | getDirtyFields | `() => Array<keyof T & string>` | 获取所有已修改字段的 prop 列表 |
352
+
353
+ ## 插槽自定义
354
+
355
+ 组件通过动态具名插槽支持字段级和错误级自定义渲染,所有插槽均接收类型化的作用域参数。
356
+
357
+ ### 自定义字段控件
358
+
359
+ 当字段 `ogControl.ogType` 为 `'custom'` 时,组件不渲染内置控件,改为使用具名插槽 `field-{prop}` 完全自定义:
360
+
361
+ ```vue
362
+ <OgSearch :og-config="config" v-model="query">
363
+ <template #field-dateRange="{ value, update, disabled }">
364
+ <MyDateRangePicker :value="value" :disabled="disabled" @change="update" />
365
+ </template>
366
+ </OgSearch>
367
+ ```
368
+
369
+ 对应的字段定义:
370
+
371
+ ```ts
372
+ const fields: OgSearchField<MyQuery>[] = [
373
+ { prop: 'dateRange', label: '日期范围', ogControl: { ogType: 'custom' } },
374
+ ]
375
+ ```
376
+
377
+ ::: tip
378
+ `ogControl: { ogType: 'custom' }` 的字段仍然参与模型管理、校验和提交参数生成。写值时应使用插槽参数中的 `update` 函数,确保联动流程完整执行。
379
+ :::
380
+
381
+ #### 字段插槽作用域 (`OgSearchFieldSlotProps<T>`)
382
+
383
+ | 属性 | 类型 | 说明 |
384
+ | -------- | ------------------------------------------------------ | ----------------------------------------- |
385
+ | field | `OgSearchField<T>` | 当前字段定义 |
386
+ | model | `Partial<T>` | 当前查询模型快照 |
387
+ | value | `unknown` | 当前字段值 |
388
+ | disabled | `boolean` | 是否禁用(综合组件级和字段级禁用状态) |
389
+ | update | `(value: unknown) => void` | 更新字段值,触发联动和 `fieldChange` 事件 |
390
+ | submit | `() => Promise<OgSearchSubmitPayload<T> \| undefined>` | 触发校验并提交 |
391
+
392
+ ### 自定义错误展示
393
+
394
+ 当字段的 `optionsApi` 加载失败时,可通过 `field-{prop}-error` 插槽自定义错误 UI:
395
+
396
+ ```vue
397
+ <OgSearch :og-config="config" v-model="query">
398
+ <template #field-department-error="{ prop, error }">
399
+ <div class="error-tip">
400
+ <ElIcon><WarningFilled /></ElIcon>
401
+ 部门加载失败,请
402
+ <a @click="refreshField(prop)">重试</a>
403
+ </div>
404
+ </template>
405
+ </OgSearch>
406
+ ```
407
+
408
+ #### 错误插槽作用域 (`OgSearchErrorSlotProps<T>`)
409
+
410
+ | 属性 | 类型 | 说明 |
411
+ | ----- | ------------------ | ------------------------------- |
412
+ | prop | `keyof T & string` | 出错的字段 prop |
413
+ | error | `unknown` | 错误对象(通常为 `Error` 实例) |
414
+
415
+ ### 插槽命名规则
416
+
417
+ | 插槽名 | 触发条件 | 用途 |
418
+ | -------------------- | ------------------------------------- | ------------------ |
419
+ | `field-{prop}` | 字段 `ogControl.ogType` 为 `'custom'` | 自定义字段控件渲染 |
420
+ | `field-{prop}-error` | 字段 `optionsApi` 加载失败且存在错误 | 自定义错误提示展示 |
421
+ | `label-{prop}` | 始终可用 | 自定义字段标签内容 |
422
+ | `keyword-label` | 启用快速搜索时 | 自定义快速搜索标签 |
423
+
424
+ 插槽名中的 `{prop}` 为字段的 `prop` 值。例如字段 `prop` 为 `status` 时,插槽名为 `field-status`、`field-status-error` 和 `label-status`。
425
+
426
+ 标签插槽示例:
427
+
428
+ ```vue
429
+ <OgSearch :og-config="config" og-label-placement="control">
430
+ <template #label-status="{ field, label, placement }">
431
+ <span :data-placement="placement">{{ field.label || label }}</span>
432
+ </template>
433
+ <template #keyword-label="{ label }">
434
+ <span>关键字:{{ label }}</span>
435
+ </template>
436
+ </OgSearch>
437
+ ```
438
+
439
+ ## optionsApi 错误处理
440
+
441
+ 字段的 `optionsApi` 加载失败时,组件会:
442
+
443
+ 1. 触发 `optionsError` 事件,载荷为 `{ prop, error }`。
444
+ 2. 渲染 `field-{prop}-error` 错误插槽(如已提供)。
445
+ 3. 自动中止过期请求——当依赖字段变化、字段隐藏或移除、加载器替换或组件卸载时,旧的 `AbortSignal` 会被取消。
446
+ 4. 每次调用都会传入当前模型的浅拷贝;静态 `options` 则直接读取当前字段定义,不会保留过期缓存。
447
+
448
+ ```ts
449
+ const fields: OgSearchField<MyQuery>[] = [
450
+ {
451
+ prop: 'department',
452
+ label: '部门',
453
+ ogControl: { ogType: 'select' },
454
+ optionsApi: async (model, signal) => {
455
+ const res = await fetch('/api/departments', { signal })
456
+ if (!res.ok) throw new Error('加载失败')
457
+ return res.json()
458
+ },
459
+ },
460
+ ]
461
+ ```
462
+
463
+ ## 校验规则
464
+
465
+ 组件在提交(`submit`)前自动执行校验,校验不通过则中止提交。校验支持两种声明方式:
466
+
467
+ ### 必填校验
468
+
469
+ 设置 `required: true`,空值(`undefined`、`null`、`''`、`[]`)会触发默认错误提示。可通过 `locale.requiredMessage(label)` 覆盖必填消息。
470
+
471
+ ```ts
472
+ { prop: 'status', label: '状态', ogControl: { ogType: 'select' }, required: true, options }
473
+ ```
474
+
475
+ ### 自定义校验
476
+
477
+ 通过 `validator` 函数实现同步或异步校验,返回字符串表示错误信息,返回 `void` 表示通过:
478
+
479
+ ```ts
480
+ {
481
+ prop: 'age',
482
+ label: '年龄',
483
+ ogControl: { ogType: 'number' },
484
+ validator: (value) => {
485
+ if (value !== undefined && value < 0) return '年龄不能为负数'
486
+ },
487
+ }
488
+ ```
489
+
490
+ 异步校验同样支持:
491
+
492
+ ```ts
493
+ {
494
+ prop: 'code',
495
+ label: '编码',
496
+ validator: async (value) => {
497
+ const exists = await checkCodeExists(value)
498
+ if (exists) return '编码已存在'
499
+ },
500
+ }
501
+ ```
502
+
503
+ ### 校验行为
504
+
505
+ - 校验仅针对**可见字段**执行,不可见字段(`visible` 为 `false`)会被跳过。
506
+ - 校验失败时,错误信息通过 `inlineMessage` 内联显示(默认开启),或配合 `statusIcon` 显示状态图标。
507
+ - 首个无效字段若位于折叠区域,组件会先展开再聚焦该字段。
508
+ - 异步校验期间若模型、字段或重置状态变化,旧校验结果会被丢弃;并发调用 `submit()` 会合并为一次提交。
509
+ - 可通过 Expose API 操作校验状态:
510
+
511
+ | 方法 | 说明 |
512
+ | --------------------- | ---------------------------------------------------------------------------------------------- |
513
+ | `validate()` | 手动触发当前可用字段校验;Element Plus 原生规则仅校验当前已挂载字段项,返回 `Promise<boolean>` |
514
+ | `getFieldError(prop)` | 获取指定字段的错误信息 |
515
+ | `clearErrors()` | 清除所有校验错误 |
516
+
517
+ ## 动态字段与联动
518
+
519
+ ### 字段可见性
520
+
521
+ `visible` 支持布尔值或函数。函数形式可根据当前模型动态控制字段显示:
522
+
523
+ ```ts
524
+ const fields: OgSearchField<MyQuery>[] = [
525
+ { prop: 'searchType', label: '搜索类型', ogControl: { ogType: 'select' }, options: typeOptions },
526
+ {
527
+ prop: 'userName',
528
+ label: '用户名',
529
+ visible: (model) => model.searchType === 'user',
530
+ },
531
+ {
532
+ prop: 'orderId',
533
+ label: '订单号',
534
+ visible: (model) => model.searchType === 'order',
535
+ },
536
+ ]
537
+ ```
538
+
539
+ 不可见的字段不会渲染,也不会参与校验和提交参数生成。
540
+
541
+ ### 字段禁用
542
+
543
+ `disabled` 同样支持函数形式,可根据模型状态动态禁用:
544
+
545
+ ```ts
546
+ {
547
+ prop: 'subCategory',
548
+ label: '子分类',
549
+ ogControl: { ogType: 'select' },
550
+ disabled: (model) => !model.category,
551
+ optionsApi: async (model, signal) => fetchSubCategories(model.category, signal),
552
+ }
553
+ ```
554
+
555
+ ### 依赖与异步选项刷新
556
+
557
+ `dependencies` 声明当前字段依赖的其他字段。当依赖字段的值变化时,组件会自动重新调用 `optionsApi` 加载选项:
558
+
559
+ ```ts
560
+ const fields: OgSearchField<MyQuery>[] = [
561
+ { prop: 'category', label: '分类', ogControl: { ogType: 'select' }, options: categoryOptions },
562
+ {
563
+ prop: 'subCategory',
564
+ label: '子分类',
565
+ ogControl: { ogType: 'select' },
566
+ dependencies: ['category'],
567
+ optionsApi: async (model, signal) => {
568
+ if (!model.category) return []
569
+ return fetchSubCategories(model.category, signal)
570
+ },
571
+ },
572
+ ]
573
+ ```
574
+
575
+ ### 依赖变化时清空值
576
+
577
+ 设置 `clearOnDependencyChange: true`,当依赖字段值变化时自动清空当前字段值。适合联动场景下避免残留无效选择:
578
+
579
+ ```ts
580
+ {
581
+ prop: 'city',
582
+ label: '城市',
583
+ ogControl: { ogType: 'select' },
584
+ dependencies: ['province'],
585
+ clearOnDependencyChange: true,
586
+ optionsApi: async (model, signal) => {
587
+ if (!model.province) return []
588
+ return fetchCities(model.province, signal)
589
+ },
590
+ }
591
+ // 切换省份后,城市字段自动清空并重新加载选项
592
+ ```
593
+
594
+ ### 折叠与始终可见
595
+
596
+ 当字段数量超出折叠行数时,默认隐藏溢出字段。设置 `alwaysVisible: true` 可确保关键字段在折叠状态下仍然可见:
597
+
598
+ ```ts
599
+ { prop: 'status', label: '状态', ogControl: { ogType: 'select' }, alwaysVisible: true, options }
600
+ ```
601
+
602
+ ## 字段权限
603
+
604
+ 通过 `permissions` prop 传入权限检查器,字段 `permission` 声明所需权限标识。无权限的字段不会渲染、校验或提交。
605
+
606
+ ```ts
607
+ const permissions: OgSearchPermissions = {
608
+ has: (permission: string) => permissionService.has(permission),
609
+ }
610
+
611
+ const fields: OgSearchField<MyQuery>[] = [
612
+ { prop: 'salary', label: '薪资范围', permission: 'report:salary:view' },
613
+ ]
614
+ ```
615
+
616
+ ```vue
617
+ <OgSearch :og-config="{ fields }" :og-permissions="permissions" v-model="query" />
618
+ ```
619
+
620
+ 权限仅约束前端展示与提交模型,服务端仍必须执行最终鉴权。
621
+
622
+ ## 国际化
623
+
624
+ 组件默认使用中文文案,通过 `config.locale` 覆盖。`locale` 接受 `Partial<SearchLocale>`,只需声明要覆盖的键。
625
+
626
+ 未配置 `field.ogControl.placeholder` 时,输入框和数字输入框默认使用 `inputPlaceholder`,选择、树选择、级联与日期控件默认使用 `selectPlaceholder`。控件显式 placeholder 始终优先于 locale 默认值。
627
+
628
+ ### 使用预置英文文案
629
+
630
+ ```ts
631
+ import { OG_SEARCH_LOCALE_EN_US } from '@origen-ui/search'
632
+
633
+ const config: OgSearchConfig<MyQuery> = {
634
+ locale: OG_SEARCH_LOCALE_EN_US,
635
+ fields: [/* ... */],
636
+ }
637
+ ```
638
+
639
+ ### 自定义部分文案
640
+
641
+ 只需覆盖个别键,其余保持默认:
642
+
643
+ ```ts
644
+ const config = {
645
+ locale: { search: '搜索', reset: '清空' },
646
+ }
647
+ ```
648
+
649
+ ### 多语言切换
650
+
651
+ 结合业务侧 i18n 方案,动态传入 locale:
652
+
653
+ ```ts
654
+ const config = computed(() => ({
655
+ locale: i18n.global.locale === 'zh-CN' ? OG_SEARCH_LOCALE_ZH_CN : OG_SEARCH_LOCALE_EN_US,
656
+ }))
657
+ ```
658
+
659
+ ### 文案键列表
660
+
661
+ | 键 | 默认值 | 说明 |
662
+ | ------------------ | -------- | ------------------------------ |
663
+ | keywordPlaceholder | `搜索` | 快速搜索占位文本 |
664
+ | inputPlaceholder | `请输入` | 输入与数字控件的默认占位文本 |
665
+ | selectPlaceholder | `请选择` | 选择与日期控件的默认占位文本 |
666
+ | search | `查询` | 查询按钮文案 |
667
+ | reset | `重置` | 重置按钮文案 |
668
+ | more | `展开` | 展开按钮文案 |
669
+ | less | `收起` | 收起按钮文案 |
670
+ | requiredMessage | 函数 | 接收字段标签并返回必填错误文案 |
671
+
672
+ ### 预置常量
673
+
674
+ | 常量 | 说明 |
675
+ | ------------------------ | ------------ |
676
+ | `OG_SEARCH_LOCALE_ZH_CN` | 简体中文文案 |
677
+ | `OG_SEARCH_LOCALE_EN_US` | 英文文案 |
678
+
679
+ ## 响应式列布局
680
+
681
+ 组件使用 CSS Grid 布局字段栅格,默认根据容器宽度自动切换列数。命令按钮(查询/重置/展开)位于字段栅格之外,不占字段单元。
682
+
683
+ **窄容器安全规则:组件容器宽度小于 640px 时始终使用单列,操作区移到字段区下方。** 此规则同样约束 `responsiveColumns: false` 和自定义断点;达到 640px 后继续遵循已有配置。判断依据是组件容器宽度,而非浏览器视口宽度。上方「折叠条件摘要」示例保留固定两列配置,可缩窄预览验证单列回退。
684
+
685
+ ### 默认断点
686
+
687
+ | 容器宽度 | 列数 |
688
+ | ---------- | ---- |
689
+ | `≥ 0px` | 1 列 |
690
+ | `≥ 640px` | 2 列 |
691
+ | `≥ 960px` | 3 列 |
692
+ | `≥ 1280px` | 4 列 |
693
+
694
+ 列数上限为 4,下限为 1,超出范围的值会被自动修正。
695
+
696
+ ### config.columns — 列数上限
697
+
698
+ `columns` 限制搜索控件能使用的最大列数,不包含查询、重置和展开/收起等操作按钮。未设置时上限为 4;容器变窄时仍会按默认断点收缩为 3、2 或 1 列:
699
+
700
+ ```ts
701
+ const config: OgSearchConfig<MyQuery> = {
702
+ columns: 3, // 宽容器最多 3 列,小容器自动收缩
703
+ fields: [/* ... */],
704
+ }
705
+ ```
706
+
707
+ ### config.responsiveColumns — 自定义断点
708
+
709
+ 传入自定义断点规则数组覆盖默认值。每条规则包含 `minWidth`(最小容器宽度)和 `columns`(对应列数):
710
+
711
+ ```ts
712
+ const config: OgSearchConfig<MyQuery> = {
713
+ responsiveColumns: [
714
+ { minWidth: 0, columns: 1 },
715
+ { minWidth: 768, columns: 2 },
716
+ { minWidth: 1200, columns: 4 },
717
+ ],
718
+ }
719
+ ```
720
+
721
+ 设为 `false` 时,容器宽度达到 640px 后列数由 `columns` 决定(默认为 4);窄于 640px 时仍回退为单列:
722
+
723
+ ```ts
724
+ const config = { responsiveColumns: false, columns: 2 }
725
+ ```
726
+
727
+ ### 字段 span 与列布局
728
+
729
+ 每个字段可通过 `span` 控制占据的列数。当字段 `span` 超过当前列数时,会被限制为当前列数:
730
+
731
+ ```ts
732
+ const fields: OgSearchField<MyQuery>[] = [
733
+ { prop: 'keyword', label: '关键词', span: 2 }, // 占 2 列
734
+ { prop: 'status', label: '状态', ogControl: { ogType: 'select' } }, // 占 1 列
735
+ ]
736
+ ```
737
+
738
+ ### alwaysVisible 与折叠布局
739
+
740
+ 当字段数量超出 `collapsedRows`(默认为 1 行)时,溢出字段在折叠状态下隐藏。设置 `alwaysVisible: true` 可确保字段在折叠时仍然可见:
741
+
742
+ ```ts
743
+ { prop: 'status', label: '状态', ogControl: { ogType: 'select' }, alwaysVisible: true, options }
744
+ ```
745
+
746
+ 折叠状态通过 `v-model:og-expanded` 统一控制。只要折叠状态隐藏了字段,组件就会显示展开按钮;设置 `ogShowToggle: false` 则不折叠字段,全部字段会随容器宽度自然换行。
747
+
748
+ ### useContainerColumns
749
+
750
+ `useContainerColumns` 是组件内部使用的响应式列数 composable,也可在外部独立使用:
751
+
752
+ ```ts
753
+ import { useContainerColumns, DEFAULT_RESPONSIVE_COLUMNS } from '@origen-ui/search'
754
+ import { ref } from 'vue'
755
+
756
+ const container = ref<HTMLElement | null>(null)
757
+ const { resolvedColumns } = useContainerColumns(
758
+ container,
759
+ () => 4, // maximum: 最大列数
760
+ () => undefined, // rules: 使用默认断点,或传入自定义 ResponsiveColumnRule[]
761
+ )
762
+ ```
763
+
764
+ | 参数 | 类型 | 说明 |
765
+ | --------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
766
+ | container | `Ref<HTMLElement \| null>` | 容器 DOM 元素引用;有 `ResizeObserver` 时监听容器宽度,否则按窗口尺寸和相关 DOM 变化重新测量 |
767
+ | maximum | `() => number \| undefined` | 返回最大列数上限 |
768
+ | rules | `() => false \| ResponsiveColumnRule[] \| undefined` | 返回断点规则,`false` 在容器达到 640px 后固定列数,`undefined` 使用默认值 |
769
+
770
+ | 返回值 | 类型 | 说明 |
771
+ | --------------- | --------------------- | -------------------------------- |
772
+ | resolvedColumns | `ComputedRef<number>` | 根据当前容器宽度计算出的实际列数 |
773
+
774
+ ### DEFAULT_RESPONSIVE_COLUMNS
775
+
776
+ 默认断点规则常量,可直接引用或作为自定义规则的参考:
777
+
778
+ ```ts
779
+ import { DEFAULT_RESPONSIVE_COLUMNS } from '@origen-ui/search'
780
+
781
+ // 值为:
782
+ // [
783
+ // { minWidth: 0, columns: 1 },
784
+ // { minWidth: 640, columns: 2 },
785
+ // { minWidth: 960, columns: 3 },
786
+ // { minWidth: 1280, columns: 4 },
787
+ // ]
788
+ ```
789
+
790
+ ## modelTransform 与参数转换
791
+
792
+ 参数转换分两层:字段级 `transform` 和全局 `modelTransform`。
793
+
794
+ ### 字段级 transform
795
+
796
+ 每个字段可声明 `transform` 函数,返回值会合并到最终提交参数中。适合将单个字段拆为多个服务端参数:
797
+
798
+ ```ts
799
+ {
800
+ prop: 'dateRange',
801
+ label: '日期范围',
802
+ ogControl: { ogType: 'daterange' },
803
+ transform: (value) => {
804
+ const [start, end] = Array.isArray(value) ? value : []
805
+ return { startDate: start, endDate: end }
806
+ },
807
+ }
808
+ ```
809
+
810
+ ::: tip
811
+ 如果同时声明了 `startKey` / `endKey` 和 `transform`,两者都会生效——`startKey`/`endKey` 先拆分,`transform` 的返回值随后合并。可根据需要选择其中一种方式。
812
+ :::
813
+
814
+ ### 全局 modelTransform
815
+
816
+ `config.modelTransform` 在所有字段转换完成后执行,对整份参数做最终处理。适合统一清理空值、添加公共参数或转换格式:
817
+
818
+ ```ts
819
+ const config: OgSearchConfig<MyQuery> = {
820
+ fields: [/* ... */],
821
+ modelTransform: (params) => {
822
+ // 移除空值参数
823
+ const cleaned: Record<string, unknown> = {}
824
+ for (const [key, value] of Object.entries(params)) {
825
+ if (value !== '' && value !== undefined && value !== null) {
826
+ cleaned[key] = value
827
+ }
828
+ }
829
+ return cleaned
830
+ },
831
+ }
832
+ ```
833
+
834
+ ### 转换流程
835
+
836
+ 提交参数的生成顺序如下:
837
+
838
+ 1. 遍历可见字段,取模型中对应值。
839
+ 2. 若字段声明了 `startKey`/`endKey`,将数组值拆为独立键。
840
+ 3. 否则以 `prop` 为键写入参数。
841
+ 4. 若字段声明了 `transform`,将其返回值合并到参数对象。
842
+ 5. 最后执行 `config.modelTransform`(如已声明),得到最终参数。
843
+
844
+ `createSearchPayload` 可在组件外构造与 `search` 事件完全一致的 `{ keyword, model, params }` 快照。它会移除不可见或被 `includeField` 排除的字段,适合需要在容器组件中重整已保存查询状态的场景。
845
+
846
+ ```ts
847
+ import { createSearchPayload } from '@origen-ui/search'
848
+
849
+ const payload = createSearchPayload({ model, keyword, fields, config: { modelTransform } })
850
+ ```
851
+
852
+ 可独立使用 `createSearchParams` 在组件外部执行相同的转换逻辑:
853
+
854
+ ```ts
855
+ import { createSearchParams } from '@origen-ui/search'
856
+
857
+ const params = createSearchParams(model, fields, { modelTransform })
858
+ ```
859
+
860
+ ## 辅助函数
861
+
862
+ ### createSearchModel
863
+
864
+ 根据字段定义创建带默认值的初始模型:
865
+
866
+ ```ts
867
+ import { createSearchModel } from '@origen-ui/search'
868
+
869
+ const model = createSearchModel(fields, { keyword: '' })
870
+ // 将 fields 中各 defaultValue 填充到 model(不覆盖已有值)
871
+ ```
872
+
873
+ ### createSearchParams
874
+
875
+ 将模型值按字段定义转换为提交参数,处理区间字段拆分和 `transform`:
876
+
877
+ ```ts
878
+ import { createSearchParams } from '@origen-ui/search'
879
+
880
+ const params = createSearchParams(model, fields, { modelTransform })
881
+ ```
882
+
883
+ ### isSearchFieldVisible
884
+
885
+ 判断字段在当前模型下是否可见(考虑 `visible` 属性):
886
+
887
+ ```ts
888
+ import { isSearchFieldVisible } from '@origen-ui/search'
889
+
890
+ const visible = isSearchFieldVisible(field, model)
891
+ ```
892
+
893
+ ### useSearchOptions
894
+
895
+ 管理异步选项加载、取消和错误状态的 composable。组件内部使用,也可独立调用:
896
+
897
+ ```ts
898
+ import { useSearchOptions } from '@origen-ui/search'
899
+
900
+ const { state, refresh, cancel, valuesFor, hasError, clearErrors } = useSearchOptions({
901
+ fields: computedFields,
902
+ model: queryModel,
903
+ onError: ({ prop, error }) => console.error(prop, error),
904
+ })
905
+ ```
906
+
907
+ | 返回值 | 类型 | 说明 |
908
+ | ----------- | ----------------------------- | ---------------------------------------------- |
909
+ | state | `Record<string, OptionState>` | 各字段选项状态(`loading`、`values`、`error`) |
910
+ | refresh | `(props?) => Promise<void>` | 刷新异步选项 |
911
+ | cancel | `(props?) => void` | 取消进行中的请求 |
912
+ | valuesFor | `(field) => SelectOption[]` | 获取字段选项值 |
913
+ | hasError | `(field) => boolean` | 判断字段选项是否加载失败 |
914
+ | clearErrors | `() => void` | 清除所有选项加载错误 |
915
+
916
+ ## 常用操作导航
917
+
918
+ 本节只提供命令入口索引;Props、事件、slots 和类型的详细定义以本页后续的完整 API 章节为准。
919
+
920
+ | 类别 | 可用能力 |
921
+ | ---------- | ----------------------------------------------------------- |
922
+ | 校验与提交 | `validate`、`submit`、`reset`、`isDirty`、`getDirtyFields` |
923
+ | 模型控制 | `getModel`、`getSubmitParams`、`setFieldValue`、`setFields` |
924
+ | 异步选项 | `refreshOptions`、`cancelOptions` |
925
+ | 校验错误 | `getFieldError`、`clearErrors` |
926
+ | 界面控制 | `v-model:og-expanded`、`focus` |
927
+
928
+ ::: tip 类型建议
929
+
930
+ 使用 `OgSearchField<T>`、`OgSearchConfig<T>` 与 `OgSearchExpose<T>` 让字段 prop、默认值和命令 API 都与业务模型保持一致。
931
+
932
+ :::
933
+
934
+ ## 主题与样式
935
+
936
+ ### CSS 类名
937
+
938
+ 组件使用 BEM 命名规范的类名,可通过外部样式覆盖:
939
+
940
+ | 类名 | 说明 |
941
+ | ----------------------- | -------------------------------- |
942
+ | `.search` | 组件根容器 |
943
+ | `.search__form` | 内部 `<ElForm>` 容器 |
944
+ | `.search__grid` | CSS Grid 栅格容器 |
945
+ | `.search__field` | 单个字段表单项 |
946
+ | `.search__field--error` | 存在校验错误或选项加载错误的字段 |
947
+ | `.search__commands` | 命令按钮区域(查询/重置/展开) |
948
+
949
+ ### CSS 变量
950
+
951
+ | 变量 | 说明 |
952
+ | --------------------- | -------------------------------------------- |
953
+ | `--og-search-columns` | 当前列数,由响应式逻辑自动计算并注入到根元素 |
954
+
955
+ ### 内置样式行为
956
+
957
+ - 外层按当前列数为字段创建等宽轨道,并为操作区保留自适应轨道:`repeat(var(--og-search-columns), minmax(0, 1fr)) max-content`;字段和操作区间距为 `12px`。单列时字段区改为单列轨道,操作区占据字段区下方的独立行。
958
+ - 所有控件(`ElInput`、`ElSelect`、`ElDatePicker` 等)宽度自动设为 100%。
959
+ - 字段标签采用顶部对齐(`padding: 0 0 4px`),字号 `13px`。
960
+ - 命令按钮区域右对齐,按钮间距 `8px`;在窄屏下自动换行。
961
+ - `<ElForm>` 的 `margin` 被重置为 `0`,避免额外外边距。
962
+
963
+ ### 自定义样式
964
+
965
+ 通过外部 CSS 覆盖即可修改样式,无需 `!important`:
966
+
967
+ ```css
968
+ /* 调整栅格间距 */
969
+ .my-search .search__grid {
970
+ gap: 16px;
971
+ }
972
+
973
+ /* 修改标签颜色 */
974
+ .my-search .search__field :deep(.el-form-item__label) {
975
+ color: var(--el-color-primary);
976
+ }
977
+ ```
978
+
979
+ ## 与 OgTable 集成
980
+
981
+ 基础 `OgTable` 不渲染搜索 UI。安装 `@origen-ui/table-search` 并使用 `OgTableWithSearch` 后,组合组件始终注入搜索 UI 并接管查询逻辑。即使没有配置 `config.search` 或没有提供 `config.search.fields`,也会默认显示关键字搜索;`config.search.fields` 用于追加结构化字段,`quickSearch: false` 可关闭关键字搜索。
982
+
983
+ ### 自动接线
984
+
985
+ OgTable 完成以下接线:
986
+
987
+ - `search` 事件 → 自动调用 `request` 发起查询,使用载荷中的 `params`。
988
+ - `reset` 事件 → 重置查询模型并重新请求。
989
+ - `loading` → 自动绑定请求加载状态。
990
+ - `optionsError` 事件 → 转发为 OgTable 的 `searchOptionsError` 事件。
991
+
992
+ ```ts
993
+ const tableConfig: OgTableConfig<User> = {
994
+ request: async (params) => fetchUsers(params),
995
+ search: {
996
+ fields: [
997
+ { prop: 'name', label: '姓名' },
998
+ { prop: 'status', label: '状态', ogControl: { ogType: 'select' }, options: statusOptions },
999
+ ],
1000
+ },
1001
+ }
1002
+ ```
1003
+
1004
+ ```vue
1005
+ <OgTableWithSearch :og-config="tableConfig" />
1006
+ ```
1007
+
1008
+ ### 自定义搜索插槽
1009
+
1010
+ OgTable 将 `ogControl.ogType: 'custom'` 的搜索字段插槽映射为 `search-{prop}`:
1011
+
1012
+ ```vue
1013
+ <OgTableWithSearch :og-config="tableConfig">
1014
+ <template #search-dateRange="{ value, update, disabled }">
1015
+ <MyDateRangePicker :value="value" :disabled="disabled" @change="update" />
1016
+ </template>
1017
+ </OgTableWithSearch>
1018
+ ```
1019
+
1020
+ ### 独立使用
1021
+
1022
+ 当不需要表格功能时,`OgSearch` 可独立使用,在 `search` 事件中手动处理查询逻辑(参见本文档开头的示例)。
1023
+
1024
+ ## 注意事项
1025
+
1026
+ ### 模型与字段 prop 对应
1027
+
1028
+ 字段的 `prop` 必须属于 `v-model` 绑定的查询模型。如果模型中缺少某个字段对应的键,可能导致绑定异常。建议使用 `createSearchModel` 初始化模型,确保所有字段都有正确的默认值。
1029
+
1030
+ ### 重置不会自动触发搜索
1031
+
1032
+ 点击重置按钮会清空所有搜索字段并触发 `reset` 事件,但不会自动发起查询请求。如需重置后自动搜索,应在 `reset` 事件处理中手动调用请求逻辑。
1033
+
1034
+ ### 异步选项的取消机制
1035
+
1036
+ `optionsApi` 接收 `AbortSignal` 参数。当依赖字段变化、字段被移除或组件卸载时,组件会自动调用 `signal.abort()` 取消旧请求。请确保 `optionsApi` 实现正确响应 `AbortSignal`,避免内存泄漏和无效请求。
1037
+
1038
+ ### 权限仅约束前端
1039
+
1040
+ `permissions` 和字段 `permission` 仅控制前端渲染与提交模型,不会阻止服务端接收未授权字段。服务端必须执行最终鉴权。
1041
+
1042
+ ### transform 与 startKey/endKey 共存
1043
+
1044
+ 如果字段同时声明了 `startKey`/`endKey` 和 `transform`,两者都会生效。`startKey`/`endKey` 先将数组拆为独立参数,`transform` 的返回值随后合并。如果两者产生同名键,`transform` 的返回值会覆盖。
1045
+
1046
+ ### 不可见字段不参与提交
1047
+
1048
+ `visible` 为 `false` 的字段不会出现在 `search` 事件的 `params` 中,但其值仍保留在 `model` 中。如果需要根据条件决定是否提交某个参数,应使用 `visible` 而非在 `transform` 中过滤。
1049
+
1050
+ ## 公开导出
1051
+
1052
+ | 分类 | 根入口导出 |
1053
+ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1054
+ | 应用与表单配置 | `createOgSearch`、`useOgSearchGlobalConfig`、`OgSearchGlobalConfig`、`OgSearchFormProps`、`OgSearchConfig` |
1055
+ | 字段与实例类型 | `OgSearchProps`、`OgSearchField`、`OgSearchExpose`、`OgSearchSubmitPayload`、`OgSearchFieldSlotProps`、`OgSearchLabelSlotProps`、`OgSearchKeywordLabelSlotProps`、`OgSearchErrorSlotProps`、`OgSearchResetOptions` |
1056
+ | 表单项透传类型 | `OgSearchFormItemProps`、`OgSearchFormItemSlots` |
1057
+ | 控件注册表 | `createSearchRendererRegistry`、`provideSearchRendererRegistry`、`useSearchRendererRegistry`、`OgSearchRenderer`、`OgSearchRendererContext`、`OgSearchRendererRegistry` |
1058
+ | 表单事件类型 | `OgSearchFormValidateArgs` |
1059
+ | 展示契约 | `SearchFieldType`、`SEARCH_FIELD_TYPES`、`SearchLabelStyle`、`SearchLabelWidth`、`SearchOptionSource`、`SearchSummaryFormatterContext`、`SearchSummarySeparator` |
1060
+ | 响应式与选项 | `useContainerColumns`、`useSearchOptions` |
1061
+ | 查询投影 | `areSearchValuesEqual`、`createSearchModel`、`createSearchParams`、`createSearchPayload`、`isSearchFieldVisible`、`CreateSearchPayloadOptions` |
1062
+ | 繁體中文预设 | `OG_SEARCH_LOCALE_ZH_TW` |
1063
+
1064
+ `@origen-ui/search` 包提供以下组件、类型、常量和辅助函数:
1065
+
1066
+ `OgSearchGlobalConfig` 描述应用级默认配置,`OgSearchFormProps` 是传给内部表单的公开受限属性集合,`CreateSearchPayloadOptions` 描述 `createSearchPayload()` 的投影选项。
1067
+
1068
+ 根入口辅助函数和类型索引:`useContainerColumns`、`useSearchOptions`、
1069
+ `areSearchValuesEqual`、`createSearchModel`、`createSearchParams`、
1070
+ `createSearchPayload`、`isSearchFieldVisible`、`OgSearchConfig`、
1071
+ `OgSearchErrorSlotProps`、`OgSearchExpose`、`OgSearchField`、
1072
+ `OgSearchFieldSlotProps`、`OgSearchLabelSlotProps`、
1073
+ `OgSearchKeywordLabelSlotProps`、`OgSearchProps` 与 `OgSearchSubmitPayload`。这些符号
1074
+ 分别由后续的响应式列数、选项、Props、Expose、字段与提交载荷章节说明。
1075
+
1076
+ ### 组件
1077
+
1078
+ | 导出 | 说明 |
1079
+ | ---------- | ---------------- |
1080
+ | `OgSearch` | 搜索组件默认导出 |
1081
+
1082
+ ### 类型
1083
+
1084
+ | 导出 | 说明 |
1085
+ | ------------------------------- | --------------------------------------- |
1086
+ | `OgSearchProps<T>` | 组件 Props 类型 |
1087
+ | `OgSearchConfig<T>` | `config` 配置项类型 |
1088
+ | `OgSearchField<T>` | 字段定义类型 |
1089
+ | `OgSearchExpose<T>` | 组件 Expose API 类型 |
1090
+ | `OgSearchSubmitPayload<T>` | `search` / `reset` 事件载荷类型 |
1091
+ | `OgSearchPermissions` | 权限检查器类型 |
1092
+ | `OgSearchLocale` | 本地化文案类型 |
1093
+ | `OgSearchFieldSlotProps<T>` | 字段插槽作用域类型 |
1094
+ | `OgSearchLabelSlotProps<T>` | 字段标签插槽作用域类型 |
1095
+ | `OgSearchKeywordLabelSlotProps` | 快速搜索标签插槽作用域类型 |
1096
+ | `OgSearchErrorSlotProps<T>` | 错误插槽作用域类型 |
1097
+ | `OgSearchFormItemProps` | 内部 `ElFormItem` 的属性与 DOM 事件类型 |
1098
+ | `OgSearchFormItemSlots` | 内部 `ElFormItem` 的插槽类型 |
1099
+ | `OgSearchFormValidateArgs` | 内部 `ElForm` `validate` 事件参数类型 |
1100
+
1101
+ ### 常量
1102
+
1103
+ | 导出 | 类型 | 说明 |
1104
+ | ---------------------------- | --------------------------------- | -------------------- |
1105
+ | `OG_SEARCH_LOCALE_ZH_CN` | `OgSearchLocale` | 简体中文文案 |
1106
+ | `OG_SEARCH_LOCALE_EN_US` | `OgSearchLocale` | 英文文案 |
1107
+ | `DEFAULT_RESPONSIVE_COLUMNS` | `readonly ResponsiveColumnRule[]` | 默认响应式列断点规则 |
1108
+
1109
+ `OG_SEARCH_LOCALE_EN_US`、`OG_SEARCH_LOCALE_ZH_CN` 与 `OG_SEARCH_LOCALE_ZH_TW` 均从根入口导出;实例 `config.locale` 会覆盖应用级 `localeSource` 提供的文案。
1110
+
1111
+ ### 辅助函数
1112
+
1113
+ | 导出 | 说明 |
1114
+ | ------------------------------------------------ | --------------------------------------------- |
1115
+ | `createSearchModel(fields, value?)` | 根据字段定义创建带默认值的初始模型 |
1116
+ | `createSearchParams(model, fields, config?)` | 将模型值按字段定义转换为提交参数 |
1117
+ | `isSearchFieldVisible(field, model)` | 判断字段在当前模型下是否可见 |
1118
+ | `useSearchOptions(options)` | 管理异步选项加载、取消和错误状态的 composable |
1119
+ | `useContainerColumns(container, maximum, rules)` | 响应式列数 composable |
1120
+ | `createSearchPayload(model, options?)` | 根据字段模型生成提交 payload |
1121
+ | `areSearchValuesEqual(left, right)` | 比较搜索值是否等价,处理数组和空值语义 |
1122
+
1123
+ `OgSearchResetOptions` 只控制 `reset()` 是否发出 reset 事件(`emit`)及是否清理 keyword(`clearKeyword`);`OgSearchExpose.reset()` 不接收参数,使用解析后的实例/全局 reset 配置。`createOgSearch`/`useOgSearchGlobalConfig` 用于安装和读取应用级展示默认值,未安装时 hook 返回 `undefined`;实例 Props 与 `config` 优先于全局值。
1124
+
1125
+ ### 导入示例
1126
+
1127
+ ```ts
1128
+ // 组件
1129
+ import { OgSearch } from '@origen-ui/search'
1130
+
1131
+ // 类型
1132
+ import type {
1133
+ OgSearchField,
1134
+ OgSearchConfig,
1135
+ OgSearchExpose,
1136
+ OgSearchFormValidateArgs,
1137
+ } from '@origen-ui/search'
1138
+
1139
+ // 常量与辅助函数
1140
+ import {
1141
+ createOgSearch,
1142
+ useOgSearchGlobalConfig,
1143
+ OG_SEARCH_LOCALE_EN_US,
1144
+ OG_SEARCH_LOCALE_ZH_CN,
1145
+ OG_SEARCH_LOCALE_ZH_TW,
1146
+ DEFAULT_RESPONSIVE_COLUMNS,
1147
+ createSearchModel,
1148
+ createSearchParams,
1149
+ createSearchPayload,
1150
+ areSearchValuesEqual,
1151
+ isSearchFieldVisible,
1152
+ useSearchOptions,
1153
+ useContainerColumns,
1154
+ } from '@origen-ui/search'
1155
+ ```
1156
+
1157
+ ## 原生 Element Plus 表单属性
1158
+
1159
+ Element Plus `<ElForm>` 的普通属性直接使用官方名称放在 OgSearch 根层,例如 `inline`、`labelSuffix`、`showMessage`、`rules`、`size` 和 `disabled`。`model` 由 OgSearch 的 `modelValue` 接管;应用级 Form 默认值通过 `createOgSearch({ ogForm })` 配置。调用方可通过暴露的 `formRef`(`FormInstance`)访问明确需要的原生 API。
1160
+
1161
+ ## 相关组合示例
1162
+
1163
+ 搜索模型接入表格请求时,查看 [OgTableWithSearch](./table-with-search.md);页面级组合见[数据与查询场景](../../.agents/skills/admin-component-usage/references/component-directory.md)。
1164
+
1165
+ <!-- component-contract:start -->
1166
+
1167
+ ## 公共契约
1168
+
1169
+ > 由组件目录生成;每条记录对应可公开导入的组件及其消费者 API 摘要。
1170
+
1171
+ ### Imports
1172
+
1173
+ - `search`: `import { OgSearch } from '@origen-ui/search'`
1174
+
1175
+ ### Props
1176
+
1177
+ - `search`: `modelValue`, `ogKeyword`, `ogExpanded`, `ogConfig`, `ogLoading`, `ogRendererRegistry`, `ogReset`, `inline`, `labelPosition`, `labelSuffix`, `showMessage`, `size`, `disabled`, `inlineMessage`, `statusIcon`, `ogPermissions`, `ogSubmitOnEnter`, `ogShowReset`, `ogShowToggle`, `ogLabelPlacement`, `ogControlLabelWidth`, `ogControlLabelStyle`
1178
+
1179
+ ### Events
1180
+
1181
+ - `search`: `update:modelValue`, `update:ogKeyword`, `update:ogExpanded`, `search`, `reset`, `validate`, `fieldChange`, `optionsError`
1182
+
1183
+ ### Slots
1184
+
1185
+ - `search`: `*`
1186
+
1187
+ ### Exposes
1188
+
1189
+ - `search`: `formRef`, `validate`, `submit`, `reset`, `getModel`, `getSubmitParams`, `setFieldValue`, `setFields`, `refreshOptions`, `cancelOptions`, `focus`, `getFieldError`, `clearErrors`, `isDirty`, `getDirtyFields`
1190
+
1191
+ ### Types
1192
+
1193
+ - `search`:属性类型:`OgSearchProps`;公开方法类型:`OgSearchExpose`
1194
+
1195
+ <!-- component-contract:end -->
1196
+
1197
+ ## 应用默认配置的快照与迁移
1198
+
1199
+ `createOgSearch(config)` 每次安装时复制并冻结根配置、`ogConfig`、quickSearch 属性包、responsiveColumns 数组及每条规则、collapsedSummary、locale、`ogForm`、`ogReset` 和 `ogControlLabelStyle`。`ogPermissions` 与 `ogLocaleSource` 保持原对象;quickSearch 的回调/插槽、原生属性包内部的第三方对象,以及 `ogConfig.locale.locale` 的 Intl 参数保持原值。
1200
+
1201
+ 这是 major 语义变化:安装后修改原始对象或注入配置,不再更新上述静态默认值。工厂创建后、安装前的修改仍会进入该次安装的快照;重复安装同一插件到不同应用会生成不同配置容器。调用者原对象保持可变。公开读取类型与实际冻结层级一致;保留身份的运行时对象及第三方嵌套值不承诺深层不可变。
1202
+
1203
+ 动态展示/行为改为绑定实例 props;动态语言通过原有语言源的 `.value` 更新。显式静态 locale 覆盖相应语言源文案、实例配置继续按组件既有优先级覆盖应用默认值。无需兼容别名、双写或重复安装插件。
1204
+
1205
+ Search 的独立插件语言源名为 `ogLocaleSource`;`createOrigenUi()` 已正确接入该字段,并保留 Search namespace 显式 `ogLocaleSource` 优先于聚合自动 source 的行为。查询 schema、默认查询值和 modelTransform 仍由实例持有。