HOME > さらに使いこなす > ATOKダイレクト API > ATOK 2013 for Mac向け（プラグイン作成）

ATOKダイレクト API プラグイン作成手順（Mac 2013 向け）

共通事項

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 フラグが付いています）

引数

「run_process 」の引数で受け取るオブジェクトはハッシュであり、その構造は以下の通りです。
（『文字列』は全てUTF-8 で通知され、UTF8 フラグが付いています）。

キー 種類 値
composition_string 文字列 入力中の文字列

処理結果の格納

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

キー 種類 値
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個の候補を返すことができる
  #   ・候補には、
  #     １．表記
  #     ２．コメント（プレーンテキストかXHTML）
  #     ３．ツールチップ（確定文字列か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 入力中の文字列

処理結果の格納

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

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

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

キー 種類 値
hyoki String 候補文字列
  • 最大100文字
comment String 候補に対応するコメント文字列
  • 最大1024文字
  • comment_xhtmlが設定されているときは無視されます。
comment_xhtml String 候補に対応するコメント文字列（XHTML）
  • 最大1024×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個の候補を返すことができる
#   ・候補には、
#     １．表記
#     ２．コメント（プレーンテキストかXHTML）
#     ３．ツールチップ（確定文字列か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 入力中の文字列

処理結果の格納

プラグインの処理結果として返すオブジェクトは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 コメントの記述について

候補に対応するコメントを、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