企业官网建设流程全解析

• 示例工程

本篇以 charting-library-examples 仓库根目录的总览文档为主线，梳理 TradingView Charting Library 与 React、Vue、Angular、Next.js、Nuxt、SvelteKit、Solid.js、Ruby on Rails 以及 Android / iOS / React Native 等各技术栈的集成示例。读完本文，你将了解每个示例目录的适用版本范围、统一的库文件拷贝流程，以及各示例中widget初始化选项与原生 WebView 桥接的关键实现细节。

一、Charting Library 与这个仓库的定位

根据仓库根 README 的定义，Charting Library 是一个独立的图表展示解决方案：它是免费、可下载的库文件，托管在你自己的服务器上，通过连接你的数据源（data feed）用于网站或 App 中。整个charting-library-examples仓库的定位则是：列出 Charting Library 与常用各类库/框架的组合集成示例，供开发者参考移植。

这里有一条贯穿所有示例的重要前提，原文档以警告形式强调：所有示例都需要已授权的 Charting Library 访问权限（该库位于私有仓库中）。如果尚未获得授权，需要先向 TradingView 官方申请；在等待授权期间，可以参考官方的 demo 站点和文档站点。下文所有启动步骤都以“已能获取库文件”为前提。

二、示例清单与各技术栈的适用版本

根 README 的 “Content” 一节列出了仓库覆盖的全部集成方向。结合各目录 README 中声明的库版本边界，整理如下（适用版本以各目录 README 为准）：

值得注意的是 Next.js 被拆成了两个目录：nextjs/覆盖 v13 起的写法，nextjs-javascript/覆盖 v12 及以前的写法，两者逻辑不同，选型时先确认自己的 Next.js 大版本。Nuxt 同理，v2 与 v3 分列 nuxtjs 和 nuxtjs3 两个目录。

三、统一的启动流程：权限检查 → 安装依赖 → 拷贝库文件 → 运行

所有示例的 “How to start” 步骤高度一致，可以归纳为四步：

1. 确认已拥有 Charting Library 仓库的访问权限，没有则先申请；
2. 安装依赖：Web 项目执行npm install；Android 项目按 android/README.md 的说明准备开发环境；
3. 拷贝 Charting Library 文件到项目内指定位置，两种途径：
   • 运行示例目录下的copy_charting_library_files.sh脚本，自动拉取当前稳定版文件；
   • 无法运行 bash 脚本时，手动把私有仓库中的charting_library与datafeeds两个目录拷贝到各示例指定位置；
4. 运行开发命令（各框架不同，见下文）。

3.1 自动拷贝脚本的工作原理

以 android/copy_charting_library_files.sh 为例（各目录脚本逻辑一致），核心逻辑是：

BRANCH="master" REPOSITORY='https://github.com/tradingview/charting_library/' LATEST_HASH=$(git ls-remote $REPOSITORY $BRANCH | grep -Eo '^[[:alnum:]]+') git clone -q --depth 1 -b "$BRANCH" $REPOSITORY "$LATEST_HASH" # 清除目标目录后，把 clone 下来的内容复制进 app/src/main/assets/charting_library

脚本先用git ls-remote取出master分支最新的 commit hash，再以浅克隆（--depth 1）方式只拉取该版本，然后删除旧的目标目录并把文件复制到 Android 工程的assets/charting_library/下。各 Web 示例的脚本只是目标路径不同。

3.2 各框架的库文件目标位置对照

一个容易踩坑的差异点：react-native/README.md 明确指出，与多数 Web 示例只拷charting_library和datafeeds两个目录不同，React Native 示例需要拷贝仓库的全部文件（包括index.html），因为它是直接以本地 HTML 文件驱动 WebView 的。仓库中 react-native/android/app/src/main/assets/index.html 就是这种本地入口页的模板。

3.3 运行命令速查

• React 系列（CRA）：npm start，构建后自动打开默认浏览器（react-javascript/README.md）；
• Next.js：npm run build+npm run start，开发时用npm run dev（nextjs/README.md）；
• Nuxt / Vue / Solid / SvelteKit：npm run dev起开发服务，SvelteKit 另可用npm run build与npm run preview预览生产构建（sveltekit/README.md）；
• Angular：./node_modules/.bin/ng serve（Windows 下用"./node_modules/.bin/ng" serve），访问http://localhost:4200/（angular/README.md）；
• Ruby on Rails：bundle install后rails s，访问http://localhost:3000（ruby-on-rails/README.md）；
• Android：配置好环境后用 Android Studio 打开工程运行；React Native：npx react-native run-android/npx react-native run-ios。

四、Web 示例核心实现：widget 初始化与生命周期管理

4.1 以 React 示例为基准的初始化选项

各 Web 示例的图表容器组件都围绕new widget(options)展开。以 react-javascript/src/components/TVChartContainer/index.jsx 为基准，组件内定义了如下默认配置：

组件在useEffect中创建 widget，并演示了 API 验证的典型写法：监听onChartReady，再等待headerReady()后调用createButton()创建一个 “Check API” 按钮，点击时通过showNoticeDialog弹出通知对话框——这是示例用来直观验证 “TradingView Charting Library API works correctly” 的自检手段。卸载时通过tvWidget.remove()清理，避免图表实例泄漏：

return () => { tvWidget.remove(); };

Vue 2 示例 vuejs/src/components/TVChartContainer.vue 把同样的选项暴露为 props（symbol、interval、datafeedUrl等，默认值与上表一致），在mounted()钩子中构建widgetOptions并实例化，destroyed()钩子中执行tvWidget.remove()——与 React 的useEffect清理完全对应。Vue 2 版直接从/public/datafeeds/udf/src/udf-compatible-datafeed导入UDFCompatibleDatafeed，说明构建工具需要允许从public目录做模块导入，这是与 Next.js 等框架写法不同的细节。

4.2 各框架的生命周期差异

• Next.js（v13+，TypeScript）：nextjs/components/TVChartContainer/index.tsx 组件接收Partial<ChartingLibraryWidgetOptions>作为 props，从@/public/static/charting_library导入widget及类型定义；其 UDF 数据源还额外传入了{ maxResponseLength: 1000, expectedOrder: 'latestFirst' }配置。useEffect的依赖数组为[props]，props 变化时会重新初始化。
• Nuxt v2：nuxtjs/plugins/TVChart.js 用一个极简插件把widget注入到全局TVChart键上，页面组件再消费；Nuxt v3 则改用 nuxtjs3/plugins/TVChart.js 的defineNuxtPlugin+provide方式，同时注入了widget和datafeeds两个模块。
• SvelteKit：sveltekit/src/components/TVChartContainer.svelte 在onMount中初始化，container直接传字符串"tv-chart-container"（即模板中<div>的 id），数据源与 Next.js 示例一样带maxResponseLength/expectedOrder参数。
• Solid.js：solidjs-typescript/src/components/TVChartContainer/index.tsx 使用onMount+onCleanup管理 widget 的创建与remove()，并完整使用了ChartingLibraryWidgetOptions、IChartingLibraryWidget等类型——TypeScript 示例中可以确认charting_library目录自带类型声明。

4.3 Rails 示例：为何绕开 Asset Pipeline

ruby-on-rails/README.md 中有一条容易被忽略但很重要的说明：Charting Library 文件被故意排除在 Rails Asset Pipeline 之外。原因是 Asset Pipeline 的文件指纹（fingerprinting）机制会给资源文件添加 hash 后缀，而 Charting Library 内部依赖原始的相对文件路径，指纹化会直接破坏库的运行，因此文件被直接放入public/。开发模式下由 Rails 直接提供这些静态文件；生产环境则需自行确保 Web 服务器能正常分发public/下的文件。这提醒所有使用构建管线的框架：如果构建过程会改写/重命名charting_library目录内的文件，都需要像 Rails 示例这样特殊处理。

五、原生平台示例：Android、iOS 与 React Native

5.1 Android：WebView 配置与 JS 桥

android/app/src/main/java/com/tradingview/android/MainActivity.kt 是纯原生 Android 集成的核心，关键配置包括：

webView.settings.javaScriptEnabled = true webView.settings.allowFileAccessFromFileURLs = true // to prevent scaling text（防止 WebView 缩放文字导致图表错位） webView.settings.textZoom = 100 val chartingLibraryUrl = "file:///android_asset/charting_library/index.html" webView.addJavascriptInterface(jsBridge, "ApplicationBridge")

要点解读：

• 库文件位于assets/charting_library/，通过file:///android_asset/协议加载本地index.html，这正是拷贝脚本把文件放入 android/app/src/main/assets/charting_library 的原因；
• textZoom = 100是为了解决 WebView 跟随系统字体缩放而导致图表文字被缩放的问题（源码注释引用了官方 issue 讨论）；
• 通过evaluateJavascript注入脚本，把 Charting Library 的tvWidget.chart().onIntervalChanged()事件桥接回原生端；
• 桥接的落地实现在 android/app/src/main/java/com/tradingview/android/JSApplicationBridge.kt：用@JavascriptInterface标注onIntervalChanged(newInterval)方法，收到前端周期切换后以 Toast 展示 “New chart widget interval is $newInterval”，演示了 JS → Native 的完整回调链路；
• 源码中还预留了WebView.setWebContentsDebuggingEnabled(true)的注释行，需要时用 Chrome DevTools 调试 WebView。

5.2 iOS：WKWebView 的必要偏好设置

ios-swift/App/ViewController.swift 演示了 Swift 原生集成。WKWebViewConfiguration中有几个必须设置的项：

configuration.preferences.setValue(true, forKey: "allowFileAccessFromFileURLs") configuration.preferences.isElementFullscreenEnabled = true // ... webView.isInspectable = true // 允许 Safari Web Inspector 调试

即：开启 file URL 之间的文件访问（本地加载index.html所必需）、启用元素全屏（图表的全屏按钮依赖它）、开启可检查性。布局上通过viewDidLayoutSubviews依据safeAreaInsets计算 WebView 的 frame，保证刘海屏/手势条区域不遮挡图表。另外两个代理实现也值得注意：WKNavigationDelegate中把指向www.tradingview.com域名的.other类型导航交给系统UIApplication.open处理并在 App 内取消该导航（外链用系统浏览器打开）；WKUIDelegate中处理window.open产生的新窗口请求。

5.3 React Native：整体拷贝与 folder references

react-native/README.md 的流程与纯原生示例最接近，因为 WebView 加载的同样是本地文件：

• Android 端：把私有仓库的全部文件（含index.html、charting_library/、datafeeds/）拷入android/app/src/main/assets/，目录结构形如android/app/src/main/assets/index.html；
• iOS 端：在 Xcode 中把文件加入工程时必须选择Create folder references（蓝色文件夹引用）。源码注释给出理由：库内不同文件夹存在同名文件，只有文件夹引用才能保持完整的目录结构进入 app bundle（iOS 侧的占位目录见 react-native/ios/charting_library）；之后执行pod install再npx react-native run-ios；
• 故障排查：如果曾在同一目录构建过旧版本的示例，README 给出清理命令git clean -fdxq .删除未跟踪的构建产物，避免旧文件残留导致异常。

六、小结：选型与移植建议

回到 README 本身给出的信息脉络：这个仓库的价值在于“按你的技术栈找到对应的最小可运行集成样本”，而真正的库能力边界（API、数据源协议、配置项全集）应到官方私有仓库及其文档中确认——这也是根文档反复强调“所有示例都要求已授权访问”的原因。移植时的三条通用经验可以直接从各示例源码中提炼：

1. 静态资源路径是契约：library_path必须指向未被打乱、未被指纹化的原始目录（Rails 示例已说明原因）；
2. 生命周期必须闭环：React 的useEffect清理、Vue 的destroyed、Solid 的onCleanup都显式调用了tvWidget.remove()，图表组件在框架卸载时同样要销毁 widget 实例；
3. 原生 WebView 有额外前置条件：file://访问权限、字体缩放锁定、全屏支持、外链处理，这些在 MainActivity.kt 与 ViewController.swift 中都有对应代码可逐行对照。

掌握以上内容后，无论你的项目是 Web 前端还是原生移动应用，都可以从对应示例目录出发，替换数据源（把UDFCompatibleDatafeed指向自己的 UDF 兼容接口）与存储配置（charts_storage_url、client_id、user_id），完成 Charting Library 的正式接入。

• 示例工程