Webwidget使用说明
1. Web Widget概述
1.1 前提条件
1.2 应用场景示例——在列表页无缝创建生产单
您无需从零开始构建权限认证和页面布局。只需使用我们的 Widget 模板，开发一个简单的表单组件，并通过几行配置将其挂载到 Top Bar，即可为您的用户提供流畅的体验。
Web Widget 前端插件效果图
1.3 快速开始（Quickstart）
克隆项目模板
git clone https://gitee.com/newcore2014/newcore-widget-template.git安装依赖并启动开发环境
# 安装依赖
pnpm install
# 启动开发服务器（含热更新）
pnpm run devpnpm run dev命令启用了热模块替换(HMR)，您对代码的修改将立即生效而无需手动刷新页面，极大提升开发体验。配置应用清单
/src/manifest.json文件进行编辑（参考3.1 manifest.json配置指南）修改
name 为你的应用名（如 "Hello World Widget"）修改
author.name 为你自己的名字或团队名。检查
location.topBar 的尺寸是否合适。修改代码（实时生效）
/src/app/locations/TopBarPlugin.tsx 目录中的文件进行编辑。TopBarPlugin.tsx）：<span style=
{{
padding: '4px',
backgroundColor: 'green',
color: '#fff',
borderRadius: '8px'
}}>
{t('app.hello xhy')}
</span>QuickOrderPage.tsx）,请参考 3.2 Location 组件开发。构建生产版本
pnpm run build/dist目录, 将/dist目录压缩 zip 文件如：dist.zipdist.zip上传至新核云插件平台（参考4.2 上传应用） 并开启应用状态（如已开启请忽略）不建议修改打包产物的配置文件！
2. 核心架构与概念
2.1 项目结构详解
2.2 理解 SDK (@newcoretech/widget-react)
核心交互功能
| 功能模块 | 作用描述 | 使用场景示例 |
|---|---|---|
| 数据操作 | 安全的平台数据读写 | 获取工单数据、提交表单 |
| 事件系统 | 跨组件/应用通信 | 通知其他组件数据更新 |
| 跨域请求 | 代理三方 api 请求 | 请求三方服务系统数据 |
SDK 架构设计
典型工作流
SDK 使用详见 README
3. 详细配置与开发指南
3.1 manifest.json 配置指南
{
"name": "应用名称",
"author": {
"name": "作者名称"
},
"location": {
"topBar": {
"size": {
"width": "220px",
"height": "100px"
}
}，
"navBar": {
}，
"sideBar": {
"paths": ["/workOrder"],
"size": {
"width": "__px",
"height": "__px"
}
},
"background": {
"paths": ["/workOrder"],
}
},
"version": "应用版本",
"frameworkVersion": "框架版本要求"
}| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 应用名称 |
| author | object | 是 | 应用作者信息 |
| author.name | string | 是 | 作者名称 |
| location | object | 是 | 应用显示位置配置 |
| location.topBar | object | 否 | 顶部栏位置配置 |
| location.navBar | object | 否 | 导航栏位置配置 |
| location.sideBar | object | 否 | 侧边栏位置配置 |
| location.background | object | 否 | 后台配置 |
| paths | array | 否 | widget可部署页面的路由地址 |
| size | object | 是 | 容器尺寸配置 |
| size.width | string | 是 | 容器宽度(如"220px") |
| size.height | string | 是 | 容器高度(如"100px") |
| version | string | 是 | 应用版本号 |
| frameworkVersion | string | 是 | 所需框架最低版本 |
3.2 Location组件开发
3.2.1 组件代码逻辑
i. 核心功能架构
const XINHE_CONFIG = {
appkey: 'cbd489e2-c888-4477-95a4-4b0d4b2ff935',
appsecret: 'Zu.1I1&+q7q7<0uC',
tokenUrl: 'https://c2.xinheyun.com/api/open/v2/token',
refreshUrl: 'https://c2.xinheyun.com/api/open/v2/token'
};
// Token管理类（封装认证逻辑）
class TokenManager {
// Token获取、刷新和清理实现
static async getAccessToken(): Promise<string> { /* ... */ }
}
// 生产单快速创建组件
const QuickOrderPage: React.FC = () => {
// 国际化支持
const { t } = useI18n();
// 全局参数获取
const { globalParams } = useGlobalParams();
// Ant Design消息组件
const { message } = App.useApp();
// 表单控制
const [form] = Form.useForm<QuickOrderForm>();
// 状态管理
const [materials, setMaterials] = useState<Material[]>([]);
const [loading, setLoading] = useState(false);
const [submitting, setSubmitting] = useState(false);
// 搜索与分页状态
const [searchKeyword, setSearchKeyword] = useState<string>('');
const [currentPage, setCurrentPage] = useState<number>(0);
const [hasMore, setHasMore] = useState<boolean>(true);
// API交互方法
const fetchMaterials = async () => { /* ... */ };
const handleSubmit = async (values: QuickOrderForm) => { /* ... */ };
// UI渲染
return ( /* ... */ );
};实际开发中应使用环境变量
TokenManager类封装OAuth2.0认证流程fetchMaterials和handleSubmit实现核心业务逻辑ii. 核心功能实现
// 物料获取逻辑
const fetchMaterials = async (page: number = 0, keyword: string = '', append: boolean = false) => {
setLoading(true);
try {
// 获取access_token
const accessToken = await TokenManager.getAccessToken();
// API调用（带认证头）
const response = await request.post('https://c2.xinheyun.com/api/open/v3/items/page/query', {
body: { /* 查询参数 */ }
}, {
headers: { 'Authorization': `Bearer ${accessToken}` }
});
// 数据处理与状态更新
setMaterials(/* ... */);
} catch (error) {
// 错误处理与降级方案
if (error.response?.status === 401) {
TokenManager.clearTokens(); // 认证失败清理token
}
// 使用模拟数据降级
setMaterials(/* 模拟数据 */);
} finally {
setLoading(false);
}
};
// 生产单提交
const handleSubmit = async (values: QuickOrderForm) => {
setSubmitting(true);
try {
const accessToken = await TokenManager.getAccessToken();
// 构造生产单数据
const productionOrder = {
code: `WO${Date.now()}`,
itemCode: /* 物料编码 */,
planQty: values.plannedQuantity,
endTime: new Date(values.plannedEndDate).getTime(),
// ...其他字段
};
// 提交到新核云API
const resp = await request.post('https://c2.xinheyun.com/api/open/v4/workOrder/create', {
body: productionOrder
}, {
headers: { 'Authorization': `Bearer ${accessToken}` }
});
// 成功反馈
message.success(t('app.quickOrder.submitSuccess'));
form.resetFields();
} catch (error) {
// 错误处理
message.error(t('app.quickOrder.submitError'));
} finally {
setSubmitting(false);
}
};1.
TokenManager处理OAuth2.0令牌获取与刷新2.
request库发起API请求3.
4.
iii. UI交互实现
// 表单渲染
<Form form={form} onFinish={handleSubmit}>
{/* 物料选择（带搜索和分页） */}
<Form.Item name="materialId">
<Select
showSearch
onSearch={handleSearch}
options={materials.map(m => ({
value: m.id,
label: `${m.name} (${m.code}) - ${m.unit}`
}))}
dropdownRender={(menu) => (
<div onScroll={handleScroll}> {/* 无限滚动容器 */}
{menu}
{loading && <div>加载中...</div>}
</div>
)}
/>
</Form.Item>
{/* 数量输入 */}
<Form.Item name="plannedQuantity">
<InputNumber min={1} precision={0} />
</Form.Item>
{/* 日期选择 */}
<Form.Item name="plannedEndDate">
<DatePicker disabledDate={current => current < moment().startOf('day')} />
</Form.Item>
{/* 操作按钮 */}
<Button type="primary" htmlType="submit" loading={submitting}>
{t('app.quickOrder.submit')}
</Button>
</Form>debouncedSearch减少API请求频率handleScroll实现分页加载t()函数实现国际化示例中的硬编码密钥仅用于演示，实际生产环境必须使用环境变量存储敏感信息
3.2.2 环境变量与安全配置
安全配置最佳实践
# .env.production - 生产环境配置
VITE_XHY_APP_KEY=your_actual_app_key
VITE_XHY_APP_SECRET=your_actual_app_secret
VITE_XHY_API_BASE=https://api.xinheyun.com
VITE_XHY_TOKEN_PATH=/api/open/v2/token代码中安全使用环境变量
// 从环境变量获取敏感信息
const XINHE_CONFIG = {
appkey: import.meta.env.VITE_XHY_APP_KEY,
appsecret: import.meta.env.VITE_XHY_APP_SECRET,
tokenUrl: `${import.meta.env.VITE_XHY_API_BASE}${import.meta.env.VITE_XHY_TOKEN_PATH}`
};
// API调用示例
const fetchMaterials = async () => {
const response = await request.post(
`${import.meta.env.VITE_XHY_API_BASE}/api/open/v3/items/page/query`,
{ /* ... */ }
);
};安全配置要点
1.
2.
import.meta.env访问变量3.
4.
5.
安全审计清单
| 检查项 | 安全要求 | 检查方法 |
|---|---|---|
| 密钥存储 | 使用环境变量 | 代码扫描 |
| 版本控制 | 排除.env文件 | 检查.gitignore |
| API权限 | 最小必要权限 | 开放平台审计 |
| 错误处理 | 不泄露敏感信息 | 测试错误响应 |
| 传输安全 | 全程HTTPS | 网络抓包检查 |
| 令牌管理 | 定期刷新机制 | TokenManager测试 |
生产环境强制要求：所有接入新核云API的Web Widget必须通过安全评审，未使用环境变量管理密钥的应用将不予上架
3.3 SDK 使用详解
安装SDK（必需）
pnpm add @newcoretech/widget-reactSDK导入
在应用入口文件(如index.tsx)中添加导入语句：
import { useClient } from "@newcoretech/widget-react";SDK初始化
使用 hooks 方法获取实例：
核心功能使用
// 获取数据
client.get("staff.email").then((res) => {
if (typeof res.data === "string") {
setEmailValue(res.data);
}
});
// 设置数据
client.set("staff.email", "test@example.com"); 3.4 样式与UI开发
3.4.1 核心原则
响应式设计：确保在不同位置(topBar/SideBar)自适应
平台一致性：遵循新核云 设计规范
主题适配：支持亮色/暗色双模式
3.4.2 样式实现方式
// 推荐使用CSS Modules（示例：TopBarWidget.module.css）
.widgetContainer {
padding: 12px;
border-radius: 8px;
background-color: var(--xhy-bg-primary); /* 使用设计系统变量 */
}
.flexLayout {
display: flex;
gap: 8px;
align-items: center;
}
// 暗色模式适配
@media (prefers-color-scheme: dark) {
.widgetContainer {
border: 1px solid var(--xhy-border-dark);
}
}3.4.3 伪代码示例
响应式布局技巧
使用设计系统组件（补充）
动画交互最佳实践
// React动画组件
import { motion } from 'framer-motion';
function AnimatedCard() {
return (
<motion.div
initial={{ scale: 0.9 }}
animate={{ scale: 1 }}
transition={{ duration: 0.2 }}
whileHover={{ boxShadow: '0 4px 12px rgba(0,0,0,0.1)' }}
>
<CardContent />
</motion.div>
);
}3.5 国际化 (i18n)
3.5.1 实现原理
/src/lib/i18n.ts模块提供的t函数实现多语言支持。系统会自动检测用户的语言偏好并加载对应的翻译文件。3.5.2 核心流程
3.5.3 语言文件配置
/src/translations/目录文件命名规范：
zh-CN.jsonen-US.json[语言代码]-[国家代码].json// zh-CN.json
{
"app": {
"title": "员工管理系统",
"welcome": "欢迎回来, {name}",
"buttons": {
"submit": "提交",
"cancel": "取消"
}
},
"errors": {
"required": "{field} 是必填项"
}
}
// en-US.json
{
"app": {
"title": "Employee Management",
"welcome": "Welcome back, {name}",
"buttons": {
"submit": "Submit",
"cancel": "Cancel"
}
},
"errors": {
"required": "{field} is required"
}
}3.5.4 在代码中使用翻译
import { useI18n } from "../hooks/useI18n";
// 在组件中使用
function WelcomeBanner() {
const { t } = useI18n();
const { user } = useUser(); // 假设从上下文中获取用户信息
return (
<div className="welcome-container">
<h1>{t('app.title')}</h1>
{/* 带参数的翻译 */}
<p>{t('app.welcome', { name: user.firstName })}</p>
{/* 嵌套属性访问 */}
<div className="action-buttons">
<button>{t('app.buttons.submit')}</button>
<button>{t('app.buttons.cancel')}</button>
</div>
</div>
);
}3.5.5 高级用法
复数形式处理：
// 在语言文件中
{
"notifications": {
"count": "您有 {count} 条通知 | 您有 {count} 条通知"
}
}
// 在组件中
const notificationCount = 3;
const text = t('notifications.count', { count: notificationCount });
// 根据数量自动选择单复数形式格式化日期/数字：
// 语言文件中定义格式
{
"formats": {
"date": "YYYY年MM月DD日",
"currency": "¥{amount}"
}
}
// 在组件中使用
const today = new Date();
const formattedDate = t('formats.date', { value: today });
const price = 99.9;
const formattedPrice = t('formats.currency', { amount: price.toFixed(2) });3.6 Sidebar方法
3.6.1 通用 API
client.get(path)
/**
* 获取字段数据
* @param path 字段路径（如 "staff.email"）
*/
get(path: string): Promise<{
success: boolean;
message?: string;
data?: unknown;
}>;const res = await client.get("staff.email");
if (res.success && typeof res.data === "string") {
setEmailValue(res.data);
}client.set(path, value)
/**
* 设置字段数据
* @param path 字段路径
* @param value 字段值
*/
set(path: string, value: unknown): Promise<{
success: boolean;
message?: string;
}>;await client.set("staff.email", "test@example.com");client.trigger(eventName, data)
/**
* 触发事件（向主页面或其他组件广播）
* @param eventName 事件名称
* @param data 事件数据
*/
trigger(eventName: string, data: unknown): void;client.trigger("refreshWorkOrders", { source: "quickCreate" });client.invoke(path, ...args)
/**
* 调用方法（请求-响应式）
* @param path 方法路径（如 "workOrder.create"）
* @param args 方法参数
*/
invoke(path: string, ...args: unknown[]): Promise<{
success: boolean;
message?: string;
data: unknown;
}>;const resp = await client.invoke("workOrder.create", {
code: "WO20251016",
itemCode: "STEEL_A",
planQty: 100
});
if (resp.success) {
// 后续处理
}client.on(eventName, handler)
/**
* 订阅事件（监听）
* @param eventName 事件名称
* @param handler 事件处理函数 (payload: unknown) => void
*/
on(eventName: string, handler: (payload: unknown) => void): void;useEffect(() => {
const handleDataChange = (payload: unknown) => {
setOnValue(payload);
};
client.on("dataChange", handleDataChange);
return () => {
client.off("dataChange", handleDataChange);
};
}, [client]);jbkSuccess、formSaved、dataChange）。trigger/宿主内置事件形成发布-订阅模式。client.off(eventName, handler)
/**
* 取消订阅事件
* @param eventName 事件名称
* @param handler 与 on 注册时同一个函数引用
*/
off(eventName: string, handler: (payload: unknown) => void): void;on 成对使用，在组件卸载或不再需要监听时移除监听，防止内存泄漏或重复回调。on 的 React 代码中 return 的清理函数。⚠️ 注意事项 off传入的handler必须与on时的引用一致（不要每次都 new 一个函数）。在 React 中，建议将 handler用useCallback包装并放入依赖，确保引用稳定：const handleDataChange = useCallback((payload: unknown) => { setOnValue(payload); }, []); useEffect(() => { client.on("dataChange", handleDataChange); return () => client.off("dataChange", handleDataChange); }, [client, handleDataChange]);
3.6.2 已支持页面的参数与事件
场景：现场工位报工
jbkSuccess —— 报工成功后触发ℹ️ 说明
平台在报工成功时会触发jbkSuccess。如果你的 Widget 需要在报工完成后进行联动（如刷新列 表、弹出提示等），请使用on/off进行订阅与清理；trigger用于你主动告知宿主做事；invoke用于调用宿主方法并取得返回。
场景：SOP集成PLM图纸
onGetData —— 页面加载完成后触发传输数据实例值{'itemId':"7194275789660209152",'itemCode':"000103.1",'procedureId':"20000773",'procedureCode':"1232",}
ℹ️ 说明
页面加载完成后会触发onGetData。请使用on/off进行订阅与清理；
场景：APP销售出库任务列表页出库自定义校验
onConfirmPreCheck —— 点击批量出库时触发传输数据实例值
{'outRecordList': [{"recordId":1234,"orderNumber":"xxx","delivery":{},"item":{}}]}
ℹ️ 说明
勾选任务，点击批量出库时会触发onConfirmPreCheck获取自定义的校验结果，校验失败时终止出库流程，弹出错误信息。请使用on/off进行订阅与清理；
4. 上传与发布
4.1 构建与部署流程
执行构建命令
pnpm run build验证内容
压缩构建产物
模板项目中构建好应用产物 /dist 并压缩 .zip 文件app.zip
备份当前版本压缩包
备份压缩包以便后续回滚
部署应用
登录新核云开放平台 https://c2.xinheyun.com/ 并上传应用（参考4.2详细步骤）
部署后验证
| 测试项 | 预期结果 | 检查方法 |
|---|---|---|
| 应用加载速度 | ≤N 秒完成 | 浏览器网络面板 |
| SDK初始化 | 无错误日志 | 控制台监控 |
| 多语言支持 | 正确显示当前语言 | 切换系统语言 |
| 主题适配 | 跟随系统主题变化 | 切换亮/暗模式 |
回滚机制（如遇到问题）
将之前备份的压缩包重新上传进行回滚。
4.2 部署应用详细步骤
登录新核云系统进入应用管理页面
新建应用
上传应用
/dist并压缩 .zip 文件，在应用详情页面，点击右上角“上传”，在上传应用页面将.zip上传到系统中部署验证
5. 获取帮助
修改于 2025-11-07 05:38:03