neo-cmp-cli 1.12.7 → 1.12.9

package/template/develop/neoGlobalSearchInput /347/273/204/344/273/266/347/232/204/350/257/246/347/273/206/345/210/206/346/236/220/346/226/207/346/241/243.md"

@@ -1,497 +0,0 @@
-# neoGlobalSearchInput 组件详细分析文档
-
-## 一、组件概述
-
-### 1.1 组件简介
-
-`neoGlobalSearchInput` 是一个全局搜索输入框组件，用于 H5 端（移动端）的全局搜索功能入口。该组件提供了一个可点击的搜索框，用户点击后会跳转到全局搜索页面进行搜索操作。
-
-### 1.2 组件定位
-
-- **组件类型**：业务组件（H5 端）
-- **组件分类**：List 组件下的 GlobalSearchList 子组件
-- **组件名称**：`neoGlobalSearchInput`
-- **注册名称**：`neoGlobalSearchInput`（在 Neo UI 框架中的唯一标识）
-- **别名映射**：`xsyGlobalSearchInput` → `neoGlobalSearchInput`（用于首页组件映射）
-
-### 1.3 核心特性
-
-1. **权限控制**：根据用户权限动态显示/隐藏搜索框
-2. **点击跳转**：点击搜索框跳转到全局搜索页面
-3. **新旧版本兼容**：支持新旧两种全局搜索模式切换
-4. **国际化支持**：支持多语言显示
-5. **Amis 集成**：基于 Amis 框架的 ScopedContext 机制
-
-## 二、目录结构
-
-```
-neoGlobalSearchInput/
-├── index.tsx          # 组件注册文件
-├── component.tsx       # 组件主实现文件
-├── interface.tsx      # 接口定义文件
-└── styled.ts          # 样式定义文件
-```
-
-### 2.1 文件说明
-
-| 文件名 | 说明 | 关键内容 |
-|--------|------|----------|
-| `index.tsx` | 组件注册入口 | 使用 `NeoRegister` 注册组件 |
-| `component.tsx` | 组件核心实现 | 包含组件逻辑、生命周期、渲染方法 |
-| `interface.tsx` | 接口定义 | 定义组件的 Props 接口 |
-| `styled.ts` | 样式定义 | 使用 styled-components 定义样式 |
-
-## 三、核心功能分析
-
-### 3.1 组件注册
-
-组件通过 `NeoRegister` 进行注册，注册名称为 `neoGlobalSearchInput`：
-
-```typescript
-import { NeoRegister } from 'neo-ui-common'
-NeoRegister({
-  name: 'neoGlobalSearchInput'
-})(() => import('./component'))
-```
-
-### 3.2 组件类结构
-
-```typescript
-export default class GlobalSearchInput<T> extends React.Component<
-  GlobalSearchInputProps & T, 
-  ObjectFormState
->
-```
-
-- **泛型参数**：`T` - 支持扩展的 Props 类型
-- **继承**：`React.Component`
-- **Props**：`GlobalSearchInputProps & T`
-- **State**：`ObjectFormState`（空对象）
-
-### 3.3 ScopedContext 集成
-
-组件集成了 Amis 的 `ScopedContext`，用于组件注册和注销：
-
-```typescript
-static contextType = ScopedContext
-
-componentWillMount() {
-  const scoped = this.context as IScopedContext
-  scoped.registerComponent(this)
-}
-
-componentWillUnmount() {
-  const scoped = this.context as IScopedContext
-  scoped.unRegisterComponent(this)
-}
-```
-
-**作用**：
-- 在组件挂载时注册到 Amis 的作用域上下文
-- 在组件卸载时从作用域上下文中注销
-- 便于 Amis 框架管理组件生命周期和通信
-
-### 3.4 搜索框配置（pageScheme）
-
-组件通过 `pageScheme` 方法返回搜索框的配置：
-
-```typescript
-pageScheme = () => {
-  return {
-    type: 'neoSearchBar',           // 使用 neoSearchBar 组件
-    backgroundColor: '#FFFFFF',      // 背景色为白色
-    disableCancel: true,            // 禁用取消按钮
-    disabled: true,                 // 禁用输入（仅作为入口）
-    onClick: () => {                // 点击事件处理
-      const isNewGlobal = getNeoContext('globalSearchUpgrade2024Enabled')
-      NeoNavigator.openUniversalPage({
-        pageType: 'GlobalSearchHome',
-        stateParams: {
-          type: isNewGlobal ? 'neoGlobalSearchHome' : 'GlobalSearchHome'
-        }
-      })
-    },
-    placeholder: kiwiIntl('neo.global.search', '全局搜索')
-  }
-}
-```
-
-**配置说明**：
-
-| 属性 | 类型 | 说明 |
-|------|------|------|
-| `type` | `string` | 组件类型，使用 `neoSearchBar` |
-| `backgroundColor` | `string` | 搜索框背景颜色 |
-| `disableCancel` | `boolean` | 是否禁用取消按钮 |
-| `disabled` | `boolean` | 是否禁用输入框（设置为 true，仅作为入口） |
-| `onClick` | `function` | 点击搜索框时的回调函数 |
-| `placeholder` | `string` | 搜索框占位符文本（支持国际化） |
-
-### 3.5 权限控制
-
-组件在渲染时会检查用户的全局搜索权限：
-
-```typescript
-render() {
-  // 没有全局搜索职能权限时，隐藏搜索框
-  const globalSearchPermission = getNeoContext('globalSearchPermission')
-  if (!globalSearchPermission) {
-    return null
-  }
-  // ... 正常渲染
-}
-```
-
-**权限检查逻辑**：
-- 通过 `getNeoContext('globalSearchPermission')` 获取权限配置
-- 如果没有权限，组件返回 `null`，不渲染任何内容
-- 有权限时，正常渲染搜索框
-
-### 3.6 新旧版本兼容
-
-组件支持新旧两种全局搜索模式的切换：
-
-```typescript
-const isNewGlobal = getNeoContext('globalSearchUpgrade2024Enabled')
-NeoNavigator.openUniversalPage({
-  pageType: 'GlobalSearchHome',
-  stateParams: {
-    // 旧的全局搜索，企微入口用的是GlobalSearchHome组件，APP用的GlobalSearchList组件
-    // 新的全局搜索，统一使用neoGlobalSearchHome
-    type: isNewGlobal ? 'neoGlobalSearchHome' : 'GlobalSearchHome'
-  }
-})
-```
-
-**版本切换逻辑**：
-- 通过 `globalSearchUpgrade2024Enabled` 配置项判断是否启用新版本
-- **新版本**：使用 `neoGlobalSearchHome` 组件（统一入口）
-- **旧版本**：使用 `GlobalSearchHome` 组件（企微入口）或 `GlobalSearchList` 组件（APP入口）
-
-### 3.7 渲染逻辑
-
-```typescript
-render() {
-  const globalSearchPermission = getNeoContext('globalSearchPermission')
-  if (!globalSearchPermission) {
-    return null
-  }
-  const { render } = this.props
-  return <Styled>{render('GlobalSearchInput', this.pageScheme())}</Styled>
-}
-```
-
-**渲染流程**：
-1. 检查权限，无权限则返回 `null`
-2. 获取 `render` 函数（由 Amis 框架注入）
-3. 使用 `render` 函数渲染 `GlobalSearchInput` 组件
-4. 传入 `pageScheme()` 返回的配置对象
-5. 使用 `Styled` 组件包裹，应用样式
-
-## 四、技术实现细节
-
-### 4.1 依赖项
-
-组件依赖以下模块：
-
-```typescript
-import * as React from 'react'
-import { GlobalSearchInputProps } from './interface'
-import { Styled } from './styled'
-import { kiwiIntl, NeoNavigator, getNeoContext } from 'neo-ui-common'
-import { ScopedContext, IScopedContext } from 'amis'
-```
-
-**依赖说明**：
-
-| 模块 | 用途 |
-|------|------|
-| `react` | React 框架 |
-| `neo-ui-common` | Neo UI 公共工具库 |
-| `amis` | Amis 低代码框架 |
-| `styled-components` | CSS-in-JS 样式方案 |
-
-### 4.2 接口定义
-
-```typescript
-export interface GlobalSearchInputProps {
-  [key: string]: any
-}
-```
-
-**接口特点**：
-- 使用索引签名，允许接收任意属性
-- 灵活性高，但类型安全性较低
-- 实际使用时主要依赖框架注入的 `render` 属性
-
-### 4.3 样式定义
-
-```typescript
-import styled from 'styled-components'
-export const Styled = styled.div`
-  width: 100%;
-`
-```
-
-**样式特点**：
-- 使用 `styled-components` 定义样式
-- 当前样式较简单，仅设置宽度为 100%
-- 注释掉的代码显示了之前可能的样式配置
-
-### 4.4 国际化支持
-
-组件使用 `kiwiIntl` 进行国际化：
-
-```typescript
-placeholder: kiwiIntl('neo.global.search', '全局搜索')
-```
-
-**国际化机制**：
-- `kiwiIntl(key, defaultValue)` 函数
-- `key`: 国际化键值 `'neo.global.search'`
-- `defaultValue`: 默认值 `'全局搜索'`
-- 如果找不到对应的国际化文本，使用默认值
-
-## 五、使用场景
-
-### 5.1 典型使用场景
-
-1. **首页搜索入口**：在首页顶部放置全局搜索输入框
-2. **导航栏搜索**：在导航栏中集成搜索功能
-3. **列表页搜索**：在列表页面提供全局搜索入口
-
-### 5.2 组件映射
-
-组件在首页组件映射中的配置：
-
-```typescript
-// packages/neo-ui-component-h5/src/utils/widgetMap.tsx
-export const HomeMappingWidgets = {
-  xsyGlobalSearchInput: 'neoGlobalSearchInput', // 全局搜索组件
-  // ... 其他组件映射
-}
-```
-
-**映射说明**：
-- 后台配置使用 `xsyGlobalSearchInput`
-- 前端实际渲染 `neoGlobalSearchInput` 组件
-- 通过映射表实现前后端组件名称的解耦
-
-## 六、使用示例
-
-### 6.1 基础使用示例
-
-#### 6.1.1 在 Amis Schema 中使用
-
-```json
-{
-  "type": "page",
-  "body": [
-    {
-      "type": "neoGlobalSearchInput"
-    }
-  ]
-}
-```
-
-#### 6.1.2 在首页配置中使用
-
-```json
-{
-  "type": "xsyGlobalSearchInput",
-  "keyIdentifier": "global-search-input-001"
-}
-```
-
-### 6.2 完整页面示例
-
-```json
-{
-  "type": "page",
-  "title": "首页",
-  "body": [
-    {
-      "type": "neoGlobalSearchInput",
-      "keyIdentifier": "home-global-search"
-    },
-    {
-      "type": "neoMenuList",
-      "keyIdentifier": "home-menu-list"
-    }
-  ]
-}
-```
-
-### 6.3 在 React 组件中使用（不推荐）
-
-虽然组件导出了 `GlobalSearchInput`，但通常不直接在 React 组件中使用，而是通过 Amis Schema 配置使用：
-
-```typescript
-// 不推荐直接使用
-import { GlobalSearchInput } from 'neo-ui-component-h5'
-
-// 推荐通过 Amis Schema 配置使用
-const schema = {
-  type: 'neoGlobalSearchInput'
-}
-```
-
-### 6.4 权限配置示例
-
-在使用组件前，需要确保配置了全局搜索权限：
-
-```typescript
-// 在应用初始化时配置
-setNeoContext('globalSearchPermission', true)
-setNeoContext('globalSearchUpgrade2024Enabled', true) // 启用新版本
-```
-
-## 七、相关组件
-
-### 7.1 关联组件
-
-| 组件名称 | 说明 | 关系 |
-|---------|------|------|
-| `neoGlobalSearchHome` | 新版本全局搜索首页 | 点击搜索框后跳转的目标页面 |
-| `GlobalSearchHome` | 旧版本全局搜索首页（企微入口） | 旧版本跳转目标 |
-| `GlobalSearchList` | 旧版本全局搜索列表（APP入口） | 旧版本跳转目标 |
-| `neoSearchBar` | 搜索框基础组件 | 实际渲染的 UI 组件 |
-
-neoSearchBar 组件源码位置：packages/neo-ui-component-h5/src/baseUIElement/neoSearchBar。
-备注：neoGlobalSearchHome 是搜索页面（含结果页）
-
-### 7.2 组件调用链
-
-```
-用户点击搜索框
-    ↓
-neoGlobalSearchInput (onClick)
-    ↓
-NeoNavigator.openUniversalPage
-    ↓
-根据配置跳转到：
-  - neoGlobalSearchHome (新版本)
-  - GlobalSearchHome (旧版本-企微)
-  - GlobalSearchList (旧版本-APP)
-```
-
-## 八、注意事项
-
-### 8.1 权限要求
-
-- **必须配置权限**：使用组件前必须通过 `getNeoContext('globalSearchPermission')` 配置权限
-- **无权限处理**：如果没有权限，组件不会渲染任何内容（返回 `null`）
-- **权限检查时机**：在每次 `render` 时都会检查权限
-
-### 8.2 版本兼容性
-
-- **新版本启用**：通过 `globalSearchUpgrade2024Enabled` 配置项控制
-- **版本切换**：切换版本时需要确保对应的目标页面组件已正确配置
-- **向后兼容**：组件同时支持新旧两种模式，保证平滑升级
-
-### 8.3 样式定制
-
-- **当前样式简单**：组件样式定义较简单，主要通过 `neoSearchBar` 组件控制样式
-- **样式扩展**：如需定制样式，可以修改 `styled.ts` 文件或通过 CSS 覆盖
-
-### 8.4 性能考虑
-
-- **权限检查**：每次渲染都会调用 `getNeoContext`，建议确保该函数性能良好
-- **组件注册**：组件会在挂载时注册到 ScopedContext，卸载时会注销，避免内存泄漏
-
-### 8.5 国际化
-
-- **占位符文本**：搜索框占位符支持国际化，键值为 `'neo.global.search'`
-- **默认值**：如果找不到国际化文本，会使用默认值 `'全局搜索'`
-
-## 九、代码注释说明
-
-### 9.1 已注释的代码
-
-组件中存在一段已注释的代码，展示了之前的实现方式：
-
-```typescript
-// return {
-//   type: 'neoSearch',
-//   label: kiwiIntl('neo.global.search', '全局搜索'),
-//   onClick: () => {
-//     NeoNavigator.openUniversalPage({
-//       pageType: 'GlobalSearchHome',
-//       stateParams: {
-//         type: 'GlobalSearchHome'
-//       }
-//     })
-//   }
-// }
-```
-
-**说明**：
-- 这是旧版本的实现方式
-- 使用 `neoSearch` 组件类型
-- 没有版本切换逻辑
-- 保留可能是为了参考或回退
-
-### 9.2 样式注释
-
-`styled.ts` 文件中也有注释掉的样式代码，可能是之前的样式配置：
-
-```typescript
-/* .menu-header-search {
-  -webkit-box-pack: center;
-  justify-content: flex-start;
-  height: 40px;
-  width: 100%;
-  border-radius: 20px;
-  color: rgba(48, 48, 48, 100);
-  font-size: 16px;
-  font-family: PingFangSC-Regular;
-  background-color: white;
-} */
-```
-
-## 十、扩展建议
-
-### 10.1 功能扩展
-
-1. **搜索历史**：可以添加搜索历史功能
-2. **快捷搜索**：可以添加快捷搜索入口
-3. **搜索建议**：可以添加搜索建议功能
-4. **自定义样式**：可以添加更多样式配置选项
-
-### 10.2 代码优化
-
-1. **类型安全**：改进 `GlobalSearchInputProps` 接口定义，提高类型安全性
-2. **性能优化**：考虑使用 `useMemo` 优化 `pageScheme` 方法
-3. **错误处理**：添加错误处理和边界情况处理
-4. **单元测试**：添加完整的单元测试覆盖
-
-### 10.3 文档完善
-
-1. **API 文档**：完善组件的 API 文档
-2. **使用指南**：提供更详细的使用指南和最佳实践
-3. **示例代码**：提供更多实际使用场景的示例代码
-
-## 十一、总结
-
-`neoGlobalSearchInput` 是一个功能简洁但重要的全局搜索入口组件。它通过权限控制、版本兼容、国际化支持等特性，为 H5 端提供了统一的全局搜索入口。组件设计遵循了 Neo UI 框架的规范，与 Amis 框架良好集成，可以方便地在页面配置中使用。
-
-### 11.1 核心优势
-
-1. **简单易用**：配置简单，开箱即用
-2. **权限控制**：内置权限检查机制
-3. **版本兼容**：支持新旧版本平滑切换
-4. **国际化**：支持多语言显示
-
-### 11.2 适用场景
-
-- 首页搜索入口
-- 导航栏搜索功能
-- 列表页搜索入口
-- 任何需要全局搜索功能的页面
-
----
-
-**文档版本**：v1.0  
-**最后更新**：2024年  
-**维护者**：Neo UI 团队
-