【泛微Ecode新手实践-01】从零到一：构建你的第一个自定义页面
1. 认识泛微Ecode平台
第一次接触泛微Ecode的朋友可能会有点懵，这到底是个啥？简单来说，它就像是一个专门为企业OA系统打造的"乐高积木箱"。想象一下，你要搭建一个玩具城堡，Ecode就是给你提供各种标准积木块（组件）和搭建工具（开发环境）的平台。
我刚开始用的时候也犯嘀咕：这玩意儿和普通前端开发有啥区别？后来发现最大的特点就是开箱即用。比如你要做个审批表单，传统开发得从零写表单组件、设计数据流，但在Ecode里直接调用现成的WeaFormItem组件就行。不过代价就是要适应它特有的项目结构和开发规范。
举个真实案例：去年我们公司HR要做一个员工信息登记页面，传统开发至少要3天，用Ecode我只花了半天就搞定了——这效率差距主要就体现在：
- 内置的UI组件库（antd二次封装）
- 封装好的状态管理方案（mobx集成）
- 现成的路由配置体系
2. 开发环境准备
2.1 账号与权限配置
很多新手容易卡在第一步——登录。注意！必须用管理员账号登录OA系统的Ecode子站点，通常地址是你的OA地址/ecode。如果普通账号登录会看到404，别问我怎么知道的...
建议提前让IT同事给你配置好以下权限：
- Ecode开发者权限
- 应用发布权限
- 测试环境部署权限
2.2 项目结构规划
Ecode的项目结构有点像React项目，但有自己特殊的约定。建议先建好这几个文件夹：
/你的项目 ├── /coms # 组件目录 │ └── index.js # 组件入口 ├── /stores # 状态管理 │ └── index.js ├── register.js # 路由注册文件 └── index.js # 项目主入口我刚开始总把组件随便放，结果发布时各种报错。后来发现必须严格按这个结构，否则Ecode的自动打包会找不到依赖。
3. 创建第一个页面
3.1 基础页面搭建
让我们从最简单的"Hello World"开始。在coms/index.js里写入：
const { Button } = antd; const { WeaText } = ecCom; class MyFirstPage extends React.Component { render() { return ( <div style={{ padding: 20 }}> <WeaText type="h1">欢迎来到Ecode!</WeaText> <Button type="primary">点我测试</Button> </div> ) } } ecodeSDK.exp(MyFirstPage);注意几个关键点：
- 必须用
ecodeSDK.exp导出组件 - WeaText是Ecode封装好的文本组件
- 样式建议直接用行内style，避免CSS冲突
3.2 状态管理集成
Ecode默认使用mobx做状态管理。在stores/index.js中添加：
class PageStore { @observable counter = 0; @action increment = () => { this.counter++; } } ecodeSDK.exp(PageStore);然后在组件中注入store：
@inject("pageStore") @observer class MyFirstPage extends React.Component { handleClick = () => { this.props.pageStore.increment(); } render() { return ( <Button onClick={this.handleClick}> 点击次数: {this.props.pageStore.counter} </Button> ) } }4. 路由配置详解
4.1 基本路由注册
register.js是Ecode最特殊的部分，它的路由配置像这样：
const routes = [ { name: "myPage", desc: "我的第一个页面", path: "/hr/employee" // 自定义访问路径 } ]; routes.forEach(route => { ecodeSDK.rewriteRouteQueue.push({ fn: params => { const cpParams = { path: route.path || 'main/default', appId: '${appId}', name: route.name, Route: params.Route, nextState: params.nextState }; if(ecodeSDK.checkPath(cpParams)) { return ecodeSDK.getAsyncCom({ appId: cpParams.appId, name: cpParams.name, isPage: true }); } return null; }, order: 1 }); });4.2 路由调试技巧
调试路由时我常用这几个方法：
- 在浏览器控制台输入
ecodeSDK.router查看当前路由状态 - 用
ecodeSDK.checkPath({path:'你的路径'})测试路径匹配 - 在路由配置里加debugger语句逐步调试
5. 项目发布实战
5.1 本地测试
发布前务必先右击项目文件夹选"本地调试"，这会在你的浏览器打开测试页面。我建议：
- 测试所有路由路径
- 检查控制台有无报错
- 验证各功能模块状态
5.2 正式发布
点击发布按钮后，会生成一个类似"46fxxxxxx0ebe87351"的发布ID。访问地址组合规则是：
OA地址/spa/custom/static/index.html#/main/cs/app/[发布ID]_[页面名称]比如你的发布ID是123，页面名是myPage，那么访问地址就是：
http://your-oa.com/spa/custom/static/index.html#/main/cs/app/123_myPage6. 常见问题排查
6.1 页面空白问题
遇到页面空白先检查这三处：
- 浏览器控制台是否有JS错误
- 组件是否正确定义并导出（ecodeSDK.exp）
- 路由配置中的appId是否与项目ID一致
6.2 样式不生效
Ecode的样式隔离比较严格，解决方法：
- 使用Ecode提供的Wea前缀组件
- 重要样式加!important
- 在register.js中设置noCss:false
7. 进阶技巧分享
7.1 动态路由配置
可以通过API获取动态路由：
ecodeSDK.get('/api/routes').then(routes => { routes.forEach(route => { ecodeSDK.rewriteRouteQueue.push({...}); }); });7.2 混合开发模式
如果需要引入外部React组件，可以这样处理：
const ExternalComponent = React.lazy(() => import('external-module').then(module => ({ default: ecodeSDK.wrapCom(module.Component) })) );最后提醒新手朋友，Ecode的文档确实不太友好，但社区很活跃。遇到问题可以去官方论坛搜索，我踩过的坑基本都能找到解决方案。刚开始可能会觉得约束多，但熟悉后开发效率真的很高，特别是做OA类常规功能时。