ProEssentialsJS v11 チュートリアル

入り口は 2 つあり、書くページはどちらでも同じです。違うのはパスだけです。

スターター リポジトリをクローンする — 画面にチャートを出すまでの最短経路です。ライブラリはページの隣にコミットされているので、解決するものも、インストールするものもありません。

手順はこれだけです。このパッケージには依存関係がなく、定義されている 1 つのスクリプトが小さな静的サーバーを起動します。理由は下に書いたとおりです。

あるいは npm から、ご自身のプロジェクトで:

どちらの場合も、ページはスクリプトタグ 2 つです。 1 つ目がエンジンで、クラシック スクリプトです。2 つ目がご自身のコードで、モジュールとして読み込みます。

app.js の中で、使いたいチャートのプロパティ サーフェスを import します。これはご自身の JavaScript の中の import であって、もう 1 つの include ではありません。

1 つのタグにはできませんが、これはパッケージングの不備ではありません。プロパティ サーフェスは本物の ES モジュールであり、クラシック スクリプトはモジュールを収められないからです。両方の形式を提供するチャート ライブラリも、同じ線で分かれます。npm からインストールした場合、2 つのパスは代わりに node_modules/proessentials/dist/ を指します — 先頭の ./ は必ず残してください。先頭の / も URL としては正しく、ブラウザーでは問題なく動作しますが、エディターの補完だけが静かに失われます。

それ以外に設定するものはありません。 バンドラーも、import map も、jsconfig.json も、アセットのコピーも不要です。ライブラリは自身の WebAssembly バイナリと組み込みビットマップを、ページではなく自身のスクリプト URL を基準に解決するため、ライブラリがどこにあっても見つかります。エディターの補完が効くのも同じ理由で、TypeScript の型定義が、対応するモジュールの隣に置かれているからです。

ページはサーバー経由で配信してください。ディスクから直接開かないでください。 file:// の URL にはオリジンがなく、ブラウザーはオリジンのないページのために WebAssembly モジュールを取得しません — ページは白いままになりますが、ページ自体に問題はありません。静的サーバーであれば何でもよく、上の npm start もその 1 つです。ディスクから開けるライブラリから来た方がここでつまずきます。モジュールも取得するものもない素のスクリプトなら問題なく開くからです。こちらは 2.9 MB のエンジンを取得する必要があり、試せばその旨が表示されます。

以上のいずれにもライセンス キーは必要ありません。 アクティベーションも、ドメイン登録も、外部への通信もありません。

要素は 1 つです。チャートはその大きさに合わせて自身を調整します。

エンジンは WebAssembly なので、読み込みは一度だけ、非同期で行われます。それ以降はすべて同期的なプロパティ設定です。

3 つのオブジェクトがあり、それぞれに役割があります。 m はエンジンで、以後触れることはありません。ctl はコントロールで、キャンバス、メニュー、スクロールバー、イベントを所有します。Pego1 はプロパティ サーフェスで、このウォークスルーの残りはすべてここで行われます。

なぜ Pego1 なのか。 あらゆるプラットフォームの、あらゆる ProEssentials のサンプルで、30 年前からこのオブジェクトはそう呼ばれてきたからです。お好きな名前で構いませんが、この名前のままにしておけば、当社のサンプルも AI アシスタントの出力も、そのままプロジェクトに貼り付けられます。

ここは二度読む価値のある唯一のステップです。 ProEssentials はプロパティを決まった順序で受け取ります。

Subsets、次に Points、次にデータ、次にそれ以外すべて、そして最後に render()。

理由は、データへの書き込みがすべて Subsets × Points に対して境界チェックされるからです。チャートに大きさを伝える前にデータを設定すると、書き込みは拒否されます — それでもチャートは既定のデータで描画され、まったく問題なさそうに見えます。これはどのプラットフォームでも最も多い間違いであり、知ってさえいれば簡単に避けられます。

添字の書き方にご注意ください。 C# では PeData.Y[s, p] と書きますが、JavaScript には 2 次元の添字がないので PeData.Y[s][p] となります。API 全体を通じて、形が異なるのはここだけです。

軸のスケーリングは既定で自動です。固定する必要があるとき — リアルタイム チャートではほぼ必ずそうなります。自動スケーリングの軸はフレームごとに再調整され、トレースが呼吸しているように見えてしまうからです — 手動制御に切り替えます。

Graph オブジェクトがスケーリングするのは Y 軸だけです。 点は左から右へ等間隔に配置されるため、固定すべき X スケールはなく、ManualMinX もありません。X の値自体に意味がある場合、たとえばタイムスタンプや不規則なサンプリング間隔であれば、それは Scientific Graph であり、同じ名前で X 側の一式が揃っています。API は終始同じです。両方ともサンプルブラウザでご覧いただけます。

列挙値は E の下にあり、.NET の列挙型と同じ名前を持ちます。

ズーム、スクロールバー、右クリック メニュー、追従カーソルは、いずれも組み込みです。書くコードではなく、プロパティです。

呼び出しは 1 回、すべてのプロパティを設定したあと、最後に行います。

リアルタイムには 2 つの形があり、どちらが必要かを知っておく価値があります。

追加 — 伸びていくトレースに新しいサンプルを足していきます。負荷が軽く、ストリップ チャートでは通常こちらを選びます。

置換 — フレームごとにまったく新しいデータセットをチャートに渡します。オシロスコープが掃引のたびに行っていることであり、描画前にデータをフィルタリングまたは再計算するアプリケーションが行っていることでもあります。こちらが難しいケースであり、エンジンがそのために作られたケースでもあります。下のサンプルは、100,000 点の Subset 4 つ — 合計 400,000 点 — を毎フレーム置き換えています。

身につける価値のある習慣が 2 つあります。 軸は自動スケーリングに任せず固定してください。さもないとチャートはフレームごとに再調整され、トレースが呼吸して見えます。そして 1 点ずつ代入するのではなく、load() で型付き配列をまるごとエンジンに渡してください — 境界を越えるのが 1 回で済みます。

X 系列が実在する Scientific Graph には 3 つ目があります。Y だけが変化する場合に PeData.ReuseDataX = true とすると、動いていない X 系列をエンジンが作り直さなくなります。Graph オブジェクトには X 系列がないため、ここでは該当しません。

ステップ 7 でデータのホットスポットを有効にしました。こちらがそのハンドラーです。

バーをクリックしてみてください。エンジンはマウス ダウン時にヒットテストを行い、ホットスポット レコードを埋め、対応するイベントを発生させます。ev.subset と ev.point はすでにデコード済みです。クリック リスナーを取り付ける必要も、型コードをデコードする必要もありません。

.add は C# の += であり、.remove は -= です。 JavaScript にはオーバーロードできる演算子がないため、イベントはメソッドになっています。.NET の元のイベントと同じくマルチキャストで、2 回目の .add は 1 つ目を置き換えるのではなく、2 つ目のハンドラーを追加します。各ハンドルは .count と .clear() も備えています。

Graph は 37 個のイベントを持ち、.NET と同じ綴りです — PeSubsetHotSpot、PeGraphHotSpot、PeMainTitle、PeZoomIn、PeCursorMoved ほか。あるコントロールが発生させられないイベントは、死んだ状態で存在するのではなく、そもそもありません。購読する先のハンドルが存在しないので、決して発火しない購読は実行時の沈黙ではなく、それを書いた行での TypeError になります。

受け手にご注意ください。 プロパティは Pego1 に、イベントはコントロールそのものである ctl にあります。WinForms ではどちらも pego1 にあります。Web ではイベントをコントロール側に置いているため、プロパティ サーフェスを一度もバインドしないページでもイベントを受け取れます — クリックするだけのチャートなら attach() はまったく必要ありません。

同じチャートを 2 通りで。これがこの API の主張のすべてであり、説明するより見せるほうが早いところです。

C# — WinForms、WPF、WinUI:

JavaScript — ブラウザー:

同じプロパティ名、同じ順序、同じエンジン。違いは 5 つで、それがすべてです。2 次元の添字、列挙型の接頭辞、+= に代わる .add、イベントの受け手、そして最後の呼び出し。ProEssentials についてご存じのことはすべてそのまま活かせます。当社の AI アシスタントが知っていることも同様です — 同じプロパティ モデルから答えているからです。

既存のデスクトップ コードを移植中ですか。 最後の行はそのまま動きます。Pego1.PeFunction.ReinitializeResetImage() は JavaScript のコントロールにもあり、Reinitialize、Reset、GetRectGraph ほか PeFunction の残りも同様です。これは render() と同じ呼び出しで、新しいブラウザー向けコードでは短いほうの綴りを使っています。

• ライブのサンプルブラウザ — デスクトップ デモと同じサンプル群を、それぞれソース付きで。
• PE-Query — 必要なプロパティを尋ねると、ドキュメントを検索した結果ではなく、コンパイル済みエンジンに対して検証された答えが返ります。
• API エクスプローラー — すべてのコントロールの、すべてのプロパティ。
• 他製品との比較 — Highcharts、SciChart.js、LightningChart JS ほかとの比較。
• お問い合わせ — サポートは無料・無制限で、エンジンを書いた本人が回答します。