※(注記)JavaScriptが無効なため、一部機能が制限されています。
ブラウザの設定でJavaScriptを有効にしてください。
JUSTSYSTEMS.
ATOK.com

HOME > さらに使いこなす > ATOKダイレクト API > ATOK for Windows向け(プラグイン作成)

ATOK for WindowsATOKダイレクト API プラグイン作成手順

共通事項

Perl 、Ruby 、Python を用いてプラグインを作成するには

  • スクリプトファイル( Perl またはRuby 、Python で作成。UTF-8 で記述すること。)
  • プラグインの名前などを記述する、XML 形式の情報ファイル

を用意する必要があります。
ATOK ダイレクトで検索を実行した場合、入力中の文字列をプラグインで受け取ることができます。
スクリプトプラグインでは、入力中の文字列に対応する候補情報(候補表記、コメント、ツールチップ候補とその種類)を生成し、出力することができます。

TOPへ戻る

Perlスクリプトプラグイン

Perlで記述したプラグインを作成する場合、そのスクリプトファイルに記述しなければならない情報は、以下の通りです。

ソース記述例

#################################################
#
# Perlモジュール用のプラグインインターフェイス
#
# ※(注記)このテキストは必ずUTF-8で記述すること
# 扱う文字列は全てUTF-8前提であるとする
#
#################################################

package Atok_plugin;

#################################################

# 宣言

use strict;
use utf8;


#################################################
#
# 取得処理を実行する
# ・設定した候補を返すことが可能
# ・最大で100個の候補を返すことができる
# ・候補には、
# 1.表記
# 2.コメント(プレーンテキストかXHTML)
# 3.ツールチップ(確定文字列かURLジャンプ文字列とそのエイリアス文字列)
# を設定できる
# ・何もセットしなかった場合、処理結果は何もないと判断される
# ・引数で渡される情報に含まれる文字列は、全てUTF8フラグが付いている
# ・返す情報に含める文字列は必ずUTF8にする必要がある
# (UTF8フラグは付いていなくても問題ない)

sub run_process
{
my( $a_request_data ) = @_;

my %result_data;

my @candidate_array;

push( @candidate_array , { 'hyoki' => "候補1" } );

push( @candidate_array , { 'hyoki' => "候補2" ,
'comment' => "コメント(候補2)" } );


# コメントとして返すXHTMLを定義
# (UTF-8のXHTMLとして指定する必要がある)
my $comment_xhtml = <<"END_OF_STRING";
<?xml version="1.0" encoding="UTF-8" ?>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja" lang="ja">
<head><title>AtokDirect</title></head>
<body>XHTMLコメント<b style="color: #ff0000">(候補3)</b></body>
</html>
END_OF_STRING


push( @candidate_array , { 'hyoki' => "候補3" ,
'comment_xhtml' => $comment_xhtml } );


push( @candidate_array , {
'hyoki' => "通知された表記:" . $a_request_data->{ 'composition_string' } ,
'comment' => "コメント(" . $a_request_data->{ 'composition_string' } . ")" ,
'alternative' => "確定文字(" . $a_request_data->{ 'composition_string' } . ")" ,
'alternative_type' => 'definite_string' } );


push( @candidate_array , { 'hyoki' => "ATOK.comを開く1" ,
'alternative' => "http://www.atok.com/" ,
'alternative_type' => 'url_jump_string' } );


push( @candidate_array , { 'hyoki' =>"ATOK.comを開く2" ,
'alternative' => "http://www.atok.com/" ,
'alternative_alias'=> "ATOK.comを既定のブラウザで開く",
'alternative_type' => 'url_jump_string' } );

$result_data{ 'candidate' } = \@candidate_array;

return( %result_data );
}

#################################################

1; # 重要:モジュールは必ず真と解釈される値を返さなければならない

※(注記)「Atok_plugin」パッケージ内に「run_process」を実装する必要があります。

サブルーチン、パッケージ、引数

サブルーチン名
run_process
パッケージ名
Atok_plugin
引数
「run_process 」の引数で受け取るオブジェクトはハッシュであり、その構造は以下の通りです。
(『文字列』は全てUTF-8 で通知され、UTF8 フラグが付いています)
キー 種類 値
composition_string 文字列 入力中の文字列
proxy_name 文字列 プロキシサーバー名
  • ATOK ダイレクト環境設定で設定されている場合のみ通知します。
proxy_port 文字列 プロキシボート番号
  • ATOK ダイレクト環境設定で設定されている場合のみ通知します。
proxy_username 文字列 プロキシ認証で使用するユーザ名
  • ATOK ダイレクト環境設定で設定されている場合のみ通知します。
proxy_password 文字列 プロキシ認証で使用するパスワード
  • ATOK ダイレクト環境設定で設定されている場合のみ通知します。

処理結果の格納

プラグインの処理結果として返すオブジェクトはハッシュであり、その構造は以下の通りです。

キー 種類 値
candidate 配列 候補として設定する内容を格納します。

「candidate」で表される配列の個々の内容はハッシュであり、その構造は以下の通りです。
(『文字列』は全てUTF-8 で指定します。UTF-8 フラグは付いていなくてもかまいません)

キー 種類 値
hyoki 文字列 候補文字列
  • 最大100文字
comment 文字列 候補に対応するコメント文字列(テキスト)
  • 最大1024文字
  • comment_xhtmlが設定されているときは無視されます。
comment_xhtml 文字列 候補に対応するコメント文字列( XHTML)
alternative 文字列 候補に対応するコメント文字列(XHTML)
  • 最大512文字
alternative_type 文字列 候補に対応するツールチップの種類を表す文字列
以下のいずれかを設定します。
  • definite_string
    →確定文字列
  • url_jump_string
    → URL 文字列
alternative_alias 文字列 実際にツールチップに表示する文字列
  • 最大100文字
  • 設定のない場合は、alternative に設定された文字列でツールチップを表示します。

※(注記)文字列が最大値を超える場合、超過した文字列は破棄します。
※(注記)URL文字列についてはhttp:// から始まらない場合や最大値を超える場合はツー ルチップ文字列は使用しません。

戻り値

処理結果を格納して返すオブジェクト
(結果なしの場合は空のオブジェクトを返します)

TOPへ戻る

Rubyスクリプトプラグイン

ソース記述例

Rubyで記述したプラグインを作成する場合、そのスクリプトファイルに記述しなければならない情報は、以下の通りとなります。

#! /usr/bin/ruby -Ku

#################################################
#
# ATOKダイレクトRubyスクリプトモジュールインターフェイス
#
# ※(注記)このテキストは必ずUTF-8で記述すること
# 扱う文字列は全てUTF-8前提であるとする
#
#################################################


module Atok_plugin


#################################################
# 取得処理を実行する
# ・設定した候補を返すことが可能
# ・最大で100個の候補を返すことができる
# ・候補には、
# 1.表記
# 2.コメント(プレーンテキストかXHTML)
# 3.ツールチップ(確定文字列かURLジャンプ文字列とそのエイリアス文字列)
# を設定できる
# ・何もセットしなかった場合、処理結果は何もないと判断される
# ・引数で渡される情報に含まれる文字列は、全てUTF-8である
# ・返す情報に含める文字列は必ずUTF-8にする必要がある

def run_process( a_request_data )

result_data = Hash.new

candidate_array = Array.new

candidate_array.push( { 'hyoki' => "候補1" } )

candidate_array.push( { 'hyoki' => "候補2" ,
'comment' => "コメント(候補2)" } )

# コメントとして返すXHTMLを定義
# (UTF-8のXHTMLとして指定する必要がある)
comment_xhtml = <<END_OF_STRING
<?xml version="1.0" encoding="UTF-8" ?>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja" lang="ja">
<head><title>AtokDirect</title></head>
<body>XHTMLコメント<b style="color: #ff0000">(候補3)</b></body>
</html>
END_OF_STRING


candidate_array.push( { 'hyoki' => "候補3" ,
'comment_xhtml' => comment_xhtml } )

candidate_array.push( {
'hyoki' => "通知された表記:" + a_request_data[ 'composition_string' ] ,
'comment' => "コメント(" + a_request_data[ 'composition_string' ] + ")" ,
'alternative'=> "確定文字(" + a_request_data[ 'composition_string' ] + ")" ,
'alternative_type'=> "definite_string" } )

candidate_array.push( { 'hyoki' => "ATOK.comを開く1" ,
'alternative' => "http://www.atok.com/" ,
'alternative_type' => "url_jump_string" } )

candidate_array.push( { 'hyoki' => "ATOK.comを開く2" ,
'alternative' => "http://www.atok.com/" ,
'alternative_alias'=> "ATOK.comを既定のブラウザで開く",
'alternative_type' => "url_jump_string" } )

result_data[ 'candidate' ] = candidate_array

result_data

end

#################################################

end

※(注記)「Atok_plugin 」モジュール内に「run_process 」を実装する必要があります。

メソッド、モジュール、引数

メソッド名
run_process
モジュール名
Atok_plugin
引数
「run_process 」の引数で受け取るオブジェクトはHashであり、その構造は以下の通りです。
(『String 』は全てUTF-8で通知されます)
キー 種類 値
composition_string String 入力中の文字列
proxy_name String プロキシサーバ名
  • ATOK ダイレクト環境設定で設定されている場合のみ通知します。
proxy_port String プロキシポート番号
  • ATOK ダイレクト環境設定で設定されている場合のみ通知します。
proxy_username String プロキシ認証で使用するユーザ名
  • ATOK ダイレクト環境設定で設定されている場合のみ通知します。
proxy_password String プロキシ認証で使用するパスワード
  • ATOK ダイレクト環境設定で設定されている場合のみ通知します。

処理結果の格納

プラグインの処理結果として返すオブジェクトはHashであり、その構造は以下の通りです 。

キー 種類 値
candidate Array 候補として設定する内容を格納します。

「candidate」で表される配列の個々の内容はHashであり、その構造は以下の通りです。
(『String 』は全てUTF-8で指定する必要があります。)

キー 種類 値
hyoki String 候補文字列
  • 最大100文字
comment String 候補に対応するコメント文字列
  • 最大1024文字
  • comment_xhtmlが設定されているときは無視されます。
comment_xhtml String 候補に対応するコメント文字列(XHTML)
  • ×ばつ10文字(10240 文字)
  • UTF-8 のXHTML として指定する必要があります。(XHTML の記述については後述)
alternative String 候補に対応するツールチップ文字列
  • 最大512 文字
alternative_type String 候補に対応するツールチップの種類を表す文字列
以下のいずれかを設定します。
  • definite_string
    →確定文字列
  • url_jump_string
    →URL 文字列
alternative_alias String 実際にツールチップに表示する文字列
  • 最大100 文字
  • 設定のない場合は、alternative に設定された文字列でツ ールチップを表示します。

※(注記)文字列が最大値を超える場合、超過した文字列は破棄します。
※(注記)URL 文字列についてはhttp:// から始まらない場合や最大値を超える場合はツールチップ文字列は使用しません。

戻り値

処理結果を格納して返すオブジェクト
(結果なしの場合は空のオブジェクトを返します)

TOPへ戻る

Pythonスクリプトプラグイン

ソース記述例

Python で記述したプラグインを作成する場合、そのスクリプトファイルに記述しなければならない情報は、以下の通りとなります。

#! /usr/bin/env python
# coding:utf-8

#################################################
#
# Pythonモジュール用のプラグインインターフェイス
#
# ※(注記)このテキストは必ずUTF-8で記述すること
# 扱う文字列は全てUTF-8前提であるとする
#
#################################################



#################################################
# 取得処理を実行する
# ・設定した候補を返すことが可能
# ・最大で100個の候補を返すことができる
# ・候補には、
# 1.表記
# 2.コメント(プレーンテキストかXHTML)
# 3.ツールチップ(確定文字列かURLジャンプ文字列とそのエイリアス文字列)
# を設定できる
# ・何もセットしなかった場合、処理結果は何もないと判断される
# ・引数で渡される情報に含まれる文字列は、全てunicodeである
# ・返す情報に含める文字列は必ずunicodeにする必要がある

def atok_plugin_run_process( a_request_data ):


result_data = {}

candidate_array = []


candidate_array.append( { 'hyoki' : u"候補1" } )

candidate_array.append( { 'hyoki' : u"候補2" ,
'comment' : u"コメント(候補2)" } )

# コメントとして返すXHTMLを定義
# (unicode文字列で作成するが、記述はUTF-8のXHTMLとして指定する必要がある)
comment_xhtml1 = u'''<?xml version="1.0" encoding="UTF-8" ?>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja" lang="ja">
<head><title>AtokDirect</title></head>
<body>XHTMLコメント<b style="color: #ff0000">(候補3)</b></body>
</html>'''


candidate_array.append( { 'hyoki' : u"候補3" ,
'comment_xhtml' : comment_xhtml1 } )


candidate_array.append( {
'hyoki' : u"通知された表記:" + a_request_data[ 'composition_string' ] ,
'comment' : u"コメント(" + a_request_data[ 'composition_string' ] + u")" ,
'alternative' : u"確定文字(" + a_request_data[ 'composition_string' ] + u")" ,
'alternative_type' : u"definite_string" } )

candidate_array.append( { 'hyoki' : u"ATOK.comを開く1" ,
'alternative' : u"http://www.atok.com/" ,
'alternative_type' : u"url_jump_string" } )

candidate_array.append( { 'hyoki' : u"ATOK.comを開く2" ,
'alternative' : u"http://www.atok.com/" ,
'alternative_alias':u"ATOK.comを既定のブラウザで開く" ,
'alternative_type' : u"url_jump_string" } )


result_data[ 'candidate' ] = candidate_array

return result_data

※(注記)「atok_plugin_run_process 」を実装する必要があります。

関数名、引数

関数名
atok_plugin_run_process
引数
「atok_plugin_run_process 」の引数で受け取るオブジェクトはdict であり、その構造は以下の通りです。
キー 種類 値
composition_string unicode 入力中の文字列
proxy_name unicode プロキシサーバ名
  • ATOK ダイレクト環境設定で設定されている場合のみ通知します。
proxy_port unicode プロキシポート番号
  • ATOK ダイレクト環境設定で設定されている場合のみ通知します。
proxy_username unicode プロキシ認証で使用するユーザ名
  • ATOK ダイレクト環境設定で設定されている場合のみ通知します。
proxy_password unicode プロキシ認証で使用するパスワード
  • ATOK ダイレクト環境設定で設定されている場合のみ通知します。

処理結果の格納

プラグインの処理結果として返すオブジェクトはdict であり、その構造は以下の通りです。

キー 種類 値
candidate list 候補として設定する内容を格納します。

「candidate 」で表される配列の個々の内容はHash であり、その構造は以下の通りです。

キー 種類 値
hyoki unicode 候補文字列
  • 最大100文字
comment unicode 候補に対応するコメント文字列
  • 最大1024文字
  • comment_xhtml が設定されているときは無視されます。
comment_xhtml unicode 候補に対応するコメント文字列(XHTML)
  • 最大1024 ×ばつ 10 文字(10240 文字)
  • UTF-8 のXHTML として指定する必要があります。(XHTML の記述については後述)
alternative unicode 候補に対応するツールチップ文字列
  • 最大512 文字
alternative_type unicode 候補に対応するツールチップの種類を表す文字列
以下のいずれかを設定します。
  • definite_string
    →確定文字列
  • url_jump_string
    →URL 文字列
alternative_alias unicode 実際にツールチップに表示する文字列
  • 最大100 文字
  • 設定のない場合は、alternative に設定された文字列でツールチップを表示します。

※(注記)文字列が最大値を超える場合、超過した文字列は破棄します。
※(注記)URL 文字列についてはhttp:// から始まらない場合や最大値を超える場合はツー ルチップ文字列は使用しません。

戻り値

処理結果を格納して返すオブジェクト
(結果なしの場合は空のオブジェクトを返します)

TOPへ戻る

XHTML コメントの記述について

ATOK 2010 以降のバージョンでは、候補に対応するコメントを、HTML 表示することができます。 処理結果を格納する際に、comment_xhtml にXHTML 形式( XHTML1.0 )でコメントを設定します。

使用可能な要素について

いくつかの要素については、使用できないなどの制限が存在します。 また、属性については、無視されるものもあります。

使用可能な要素

html , body , div , span , h1 , h2 , h3 , h4 , h5 , h6 , p , br , blockquote , q , cite , em , strong , dfn , abbr , acronym , sup , sub , pre , code , var , kbd , samp , ins , del , bdo , ruby , rb , rt , rp , rbc , rtc , hr , tt , i , b , big , small , u , strike , s , font , basefont , center , img , map , ul , ol , li , dl , dt , dd , dir , menu , table , caption , tr , th , td , thead , tfoot , tbody , colgroup , col

制限付きで使用可能な要素

a , area

上記要素については、href 属性が「http 」で始まっている必要があります。

使用できない要素

script 、iframe など、使用可能な要素として記載した要素以外はすべて無視されます。

指定方法について

有効なXHTML1.0 として処理できる形で、comment_xhtml に設定します。 実際のATOK ダイレクト解説表示では、設定されたXHTML のbody 要素以下を使用します。


例:

<?xml version="1.0" encoding="UTF-8" ?>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja" lang="ja">
<head>○しろまる○しろまる○しろまる○しろまる</head>
<body>●くろまる●くろまる●くろまる●くろまる●くろまる●くろまる</body>
</html>

なお、body 要素の属性を記述した場合、その属性値は無視されます。

ATOK ダイレクト解説に「正常なデータとして認識できません」と表示される

設定したXHTML が正常に解析できなかった場合、ATOK ダイレクト解説に「正常なデータとして認識できません」と表示されます。
設定したXHTML 文書が正確であるか確認ください。

TOPへ戻る

情報ファイル

プラグインの情報(プラグインの名前、解説、コピーライト、およびバージョン)を記述する XML ファイルを準備します。
情報ファイルのファイル名はスクリプトファイル名と同名のXML ファイル(スクリプトファイ ルの拡張子をのぞいた部分+拡張子XML のファイル)となります。

記述例

スクリプトファイルがplugin_sample.rb の場合、
情報ファイル名はplugin_sample.xml 。

<?xml version="1.0" encoding="UTF-8" ?>

<plugin_info>
<name>プラグインの名前</name>
<name_short>プラグインの省略名</name_short>
<description>プラグインの解説</description>
<copyright>プラグインのコピーライト</copyright>


<major_version>1</major_version>
<minor_version>0</minor_version>
</plugin_info>

タグの解説

情報ファイルのタグは、以下の内容を示します。

plugin_info
root タグ
name
プラグインの名前
  • 最大64 文字
name_short
プラグインの省略名(候補ウィンドウに表示する名称)
  • 最大16 文字
  • 設定しない場合、name に設定した名前の先頭から16 文字を使用します。
description
プラグインの解説
  • 最大256 文字
copyright
プラグインのコピーライト
  • 最大64 文字
major_version
プラグインのメジャーバージョン
  • 0 〜 100 (半角)
minor_version
プラグインのマイナーバージョン
  • 0 〜 100 (半角)

※(注記)文字列が最大値を超える場合、超過した文字列は破棄します。

TOPへ戻る
Update:2015年10月09日

AltStyle によって変換されたページ (->オリジナル) /