fusion-help-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fusion Help Integration

Fusion Help集成

Wire the Fusion Help Center into app pages so users can open contextual help articles via the PageLayout help button.

将Fusion Help Center集成到应用页面中，让用户可以通过PageLayout的帮助按钮打开上下文帮助文章。

When to use

适用场景

User wants to add a help button to a page
User wants to wire
```
useHelpCenter
```
into a page component
User wants to create or update the help articles constants file for an app
User asks how to connect
```
PageLayout
```
to the Fusion Help Center
Agent detects a page using
```
PageLayout
```
without
```
openHelpArticle
```
User wants to add help support to an app that doesn't have it yet
User asks "how do I open a specific help article from my page?"

用户希望为页面添加帮助按钮
用户希望将
```
useHelpCenter
```
关联到页面组件
用户希望为应用创建或更新帮助文章常量文件
用户询问如何将
```
PageLayout
```
与Fusion Help Center关联
Agent检测到页面使用
```
PageLayout
```
但未配置
```
openHelpArticle
```
用户希望为尚未支持帮助功能的应用添加该支持
用户询问“如何从我的页面打开特定的帮助文章？”

When not to use

不适用场景

Authoring markdown help article content → use
```
fusion-help-docs
```
skill
Making direct REST API calls to the Help service → use
```
fusion-help-api
```
skill

Modifying

@fra/ui

shared components (

PageLayout

PageHeader

FusionHelpButton

)

Non-Fusion-framework apps or apps outside this monorepo

编写Markdown帮助文章内容 → 使用
```
fusion-help-docs
```
技能
直接向Help服务发起REST API调用 → 使用
```
fusion-help-api
```
技能

修改

@fra/ui

共享组件（

PageLayout

、

PageHeader

、

FusionHelpButton

）

非Fusion框架应用或此单体仓库外的应用

Required inputs

必要输入信息

Collect before making changes:

Input	Required	Default	Description
App name	Yes	—	The app directory name under `apps/` (e.g., `fra-app-management` )
Target pages	Yes	—	Which page(s) to wire up, or `"all"` for every page using `PageLayout`
Article slugs	Yes	Auto-derive	Slug strings for each page. If not provided, derive as `{app-name}-{page-kebab}`
Include release notes	No	`true`	Whether to also pass `openReleaseNotes` to `PageLayout`
Constants file location	No	`src/constants/helpArticles.ts`	Path for the `FUSION_HELP_ARTICLES` object

If article slugs are auto-derived, confirm them with the user before applying — slugs must match articles published via the

fhelp

CLI.

进行修改前需收集以下信息：

输入项	是否必填	默认值	描述
应用名称	是	—	`apps/` 目录下的应用目录名称（例如： `fra-app-management` ）
目标页面	是	—	要关联的页面，或使用 `"all"` 表示所有使用 `PageLayout` 的页面
文章Slug	是	自动推导	每个页面的Slug字符串。如果未提供，将按 `{app-name}-{page-kebab}` 格式推导
包含发布说明	否	`true`	是否同时将 `openReleaseNotes` 传递给 `PageLayout`
常量文件位置	否	`src/constants/helpArticles.ts`	`FUSION_HELP_ARTICLES` 对象的路径

如果Slug是自动推导的，在应用前需与用户确认——Slug必须与通过

fhelp

CLI发布的文章匹配。

Instructions

操作步骤

1. Check existing help integration

1. 检查现有帮助集成

Search the target app for existing help wiring:

apps/{app-name}/src/**/helpArticles.ts
apps/{app-name}/src/**/fusionHelpArticles.ts

Also search for

useHelpCenter

imports. If the app already has partial integration, extend it rather than duplicating.

在目标应用中搜索已有的帮助关联代码：

apps/{app-name}/src/**/helpArticles.ts
apps/{app-name}/src/**/fusionHelpArticles.ts

同时搜索

useHelpCenter

导入语句。如果应用已有部分集成，请扩展现有代码而非重复实现。

2. Determine slug convention

2. 确定Slug命名规范

Check if the app already has a constants file with slugs:

Has existing slugs → follow its naming pattern (prefixed vs. unprefixed)
No existing slugs → use
```
{app-name}-{page-kebab}
```
convention

Reference existing conventions:

App	Convention	Example
`fra-access-manager`	`{app-name}-{page-kebab}`	`fra-access-manager-access-groups`
`fra-app-management`	Unprefixed page name	`overview` , `requests`
`personnel-allocation`	`{app-name}-{page-kebab}`	`personnel-allocation-overview`

Prefer the prefixed convention for new apps — it avoids slug collisions across apps.

检查应用是否已存在包含Slug的常量文件：

已有Slug → 遵循其命名模式（带前缀或不带前缀）
无现有Slug → 使用
```
{app-name}-{page-kebab}
```
规范

参考现有规范：

应用	规范	示例
`fra-access-manager`	`{app-name}-{page-kebab}`	`fra-access-manager-access-groups`
`fra-app-management`	无前缀页面名称	`overview` , `requests`
`personnel-allocation`	`{app-name}-{page-kebab}`	`personnel-allocation-overview`

对于新应用，优先使用带前缀的规范——可避免跨应用的Slug冲突。

3. Create or update the constants file

3. 创建或更新常量文件

Create

src/constants/helpArticles.ts

(or the app's chosen location):

typescript

export const FUSION_HELP_ARTICLES = {
    PAGE_NAME: '{app-name}-{page-kebab}',
};

Keys are

SCREAMING_SNAKE_CASE

matching the page concept. Values are kebab-case slug strings.

See references/wiring-pattern.md for the full canonical pattern with real examples.

创建

src/constants/helpArticles.ts

（或应用指定的路径）：

typescript

export const FUSION_HELP_ARTICLES = {
    PAGE_NAME: '{app-name}-{page-kebab}',
};

键为与页面概念匹配的大写下划线命名（SCREAMING_SNAKE_CASE）。值为短横线分隔（kebab-case）的Slug字符串。

请参考references/wiring-pattern.md获取完整的标准模式及实际示例。

4. Wire each target page

4. 关联目标页面

For each page component that uses

PageLayout

a. Add imports (respecting the project's import order — externals first, then

@fra/*

, then

@/*

aliases, then relative):

typescript

import { useHelpCenter } from '@equinor/fusion-framework-react-app/help-center';

import { PageLayout } from '@fra/ui';

import { FUSION_HELP_ARTICLES } from '@/constants/helpArticles';

b. Destructure the hook inside the component body:

typescript

const { openArticle, openReleaseNotes } = useHelpCenter();

If release notes are not needed, destructure only

{ openArticle }

c. Pass props to
PageLayout
:

tsx

<PageLayout
    title="Page Title"
    openHelpArticle={() => openArticle(FUSION_HELP_ARTICLES.PAGE_NAME)}
    openReleaseNotes={openReleaseNotes}
>

Important:

openHelpArticle

must be a callback wrapper

() => openArticle(slug)

, not a direct reference —

openArticle

requires the slug argument.

对于每个使用

PageLayout

的页面组件：

a. 添加导入语句（遵循项目的导入顺序——外部依赖优先，然后是

@fra/*

，再是

@/*

别名，最后是相对路径）：

typescript

import { useHelpCenter } from '@equinor/fusion-framework-react-app/help-center';

import { PageLayout } from '@fra/ui';

import { FUSION_HELP_ARTICLES } from '@/constants/helpArticles';

b. 在组件内部解构钩子：

typescript

const { openArticle, openReleaseNotes } = useHelpCenter();

如果不需要发布说明，仅解构

{ openArticle }

即可。

c. 向
PageLayout
传递属性：

tsx

<PageLayout
    title="Page Title"
    openHelpArticle={() => openArticle(FUSION_HELP_ARTICLES.PAGE_NAME)}
    openReleaseNotes={openReleaseNotes}
>

重要提示：

openHelpArticle

必须是一个回调包装函数

() => openArticle(slug)

，而非直接引用——

openArticle

需要传入Slug参数。

5. Verify the integration

5. 验证集成效果

After wiring:

Run TypeScript check:

pnpm --filter {app-name} exec tsc --noEmit

Confirm no lint errors:

pnpm --filter {app-name} exec eslint src/

Visually verify: the page header should show an info-circle (ⓘ) icon button. Clicking it opens the Fusion Help sidesheet.

关联完成后：

运行TypeScript检查：

pnpm --filter {app-name} exec tsc --noEmit

确认无代码检查错误：

pnpm --filter {app-name} exec eslint src/

视觉验证：页面头部应显示一个信息圆圈（ⓘ）图标按钮。点击该按钮将打开Fusion Help侧边栏。

6. Cross-reference with published content

6. 与已发布内容交叉核对

Remind the user that each slug in

FUSION_HELP_ARTICLES

must correspond to a published article. If the articles don't exist yet:

Point to the
```
fusion-help-docs
```
skill for authoring content
The slug in the constants file must exactly match the
```
slug
```
field in the
```
help-articles.json
```
config
Articles are published per-environment via the
```
fhelp
```
CLI

提醒用户

FUSION_HELP_ARTICLES

中的每个Slug必须对应一篇已发布的文章。如果文章尚未存在：

引导用户使用
```
fusion-help-docs
```
技能编写内容
常量文件中的Slug必须与
```
help-articles.json
```
配置中的
```
slug
```
字段完全匹配
文章通过
```
fhelp
```
CLI按环境发布

Expected output

预期输出

Constants file created/updated with article slug mappings
Target page(s) wired with
```
useHelpCenter
```
hook and
```
PageLayout
```
props
TypeScript compilation passes
List of slugs that need corresponding help articles (for handoff to
```
fusion-help-docs
```
)

创建/更新包含文章Slug映射的常量文件
目标页面已关联
```
useHelpCenter
```
钩子和
```
PageLayout
```
属性
TypeScript编译通过
需要对应帮助文章的Slug列表（交接给
```
fusion-help-docs
```
使用）

Safety & constraints

安全与约束

Never invent slug names without user confirmation — slugs must match published articles
Don't modify
@fra/ui
components —
```
PageLayout
```
,
```
PageHeader
```
, and
```
FusionHelpButton
```
already support help props
Don't add new dependencies —
```
@equinor/fusion-framework-react-app
```
is already a dependency of every app
Follow the app's existing import alias convention — most apps use
```
@/*
```
→
```
src/*
```
Respect existing code style — use
```
type
```
keyword for type-only imports, maintain import group ordering
Don't duplicate help wiring — if a page already has
```
useHelpCenter
```
, extend rather than re-add
Confirm auto-derived slugs before applying — a wrong slug silently fails (no article shown)

未经用户确认，切勿自行创建Slug名称——Slug必须与已发布的文章匹配
不要修改
@fra/ui
组件——
```
PageLayout
```
、
```
PageHeader
```
和
```
FusionHelpButton
```
已支持帮助属性
不要添加新依赖——
```
@equinor/fusion-framework-react-app
```
已是所有应用的依赖项
遵循应用现有的导入别名规范——大多数应用使用
```
@/*
```
→
```
src/*
```
尊重现有代码风格——使用
```
type
```
关键字进行仅类型导入，保持导入组的顺序
不要重复添加帮助关联代码——如果页面已集成
```
useHelpCenter
```
，请扩展而非重新添加
应用前确认自动推导的Slug——错误的Slug会导致静默失败（不显示文章）