示例框架

示例框架是 OpenLayers 的文档系统，用于生成具有实时演示、语法高亮和 CodePen 集成的交互式代码示例。该系统处理示例源文件，应用模板，并创建一个工作示例的可搜索库，演示 OpenLayers 功能。

有关主要构建系统和工具基础设施的信息，请参阅构建系统和工具。

目的和架构

示例框架将带有 YAML 前置元数据的单个示例文件转换为完全渲染的 HTML 页面，包含嵌入的地图、源代码显示和交互功能。该系统由一个构建时 webpack 插件组成，用于处理示例，以及运行时 JavaScript，用于提供搜索、过滤和外部编辑器集成。

构建管线概览

100%

模板系统

框架使用 Handlebars 模板从源数据生成示例页面。主模板处理前置元数据，并将其与 HTML 内容、JavaScript 源代码和 CSS 样式结合。

模板数据结构

属性	类型	描述
title	string	在导航中显示的示例标题
shortdesc	string	示例索引的简要描述
docs	string	Markdown 文档内容
tags	Array	用于分类和搜索的标签
layout	string	用于渲染的模板文件
experimental	boolean	显示实验性 API 警告
resources	Array	额外的 CSS/JS 依赖项
cloak	Array	用于隐藏敏感数据的键值对

模板处理流程

100%

ExampleBuilder 插件

ExampleBuilder 类是一个 webpack 插件，它在构建时协调整个示例生成过程。

核心处理方法

插件实现了几个关键处理方法：

• parseExample() - 从示例文件中提取 YAML 前置内容和 HTML 内容
• transformJsSource() - 修改导入路径并删除开发特定代码
• removeTypeComments() - 删除 TypeScript 类型注释以获得更清晰的显示
• cloakSource() - 用占位符值替换敏感密钥
• getDependencies() - 分析导入以生成 package.json 依赖项

100%

搜索和索引系统

示例索引通过基于词的索引系统提供客户端搜索功能，该系统根据词频和相关性对示例进行评分。

搜索实现

index.js 中的搜索系统实现：

• 词索引创建 - 对示例标题、描述和标签进行分词
• 模糊匹配 - 使用正则表达式支持部分词匹配
• 相关性评分 - 通过词频和匹配数对结果进行排名
• URL 状态管理 - 在浏览器历史记录中保留搜索词

100%

CodePen 集成

框架通过 common.js 资源管理系统与外部代码编辑器提供无缝集成。

导出过程

CodePen 集成处理：

• 源代码提取 - 从显示的示例中提取 JavaScript、HTML 和 CSS
• 依赖项解析 - 生成具有适当版本约束的 package.json
• 资源捆绑 - 获取本地资源并将其转换为外部使用
• 压缩 - 使用 LZ-String 压缩以实现高效的数据传输

100%

资源管理

框架处理示例所需的各种类型的资源和依赖项。

资源类型

资源类型	模式	处理
JavaScript	*.js	使用 webpack 捆绑，导入路径转换
CSS	*.css	在模板中链接，为外部导出处理
图像	.png、.jpg 等	通过 URL 引用，导出的二进制处理
数据文件	data/*	动态获取，嵌入在 CodePen 导出中

依赖项处理

getDependencies() 函数分析 JavaScript 导入，以自动生成具有正确版本约束的 package.json 文件：

100%

文件组织

示例框架遵循结构化的组织模式：

• examples/ - 带有前置元数据的源示例文件
• examples/templates/ - Handlebars 模板文件
• examples/resources/ - 共享的 JavaScript 和 CSS 资源
• examples/webpack/ - 构建系统集成
• build/examples/ - 生成的示例输出（构建期间）

每个示例由共享相同基本名称的协调文件组成：

• example-name.html - 带有 YAML 前置内容的 HTML 模板
• example-name.js - JavaScript 实现
• example-name.css - 可选的自定义样式