
www.kruglov.ru / KLayers / KLayers: документация

KLayers: документация

Go to english page

По теме: Кроссбраузерный DHTML (статья)

KLayers
Документация

Что есть KLayers

Библиотека KLayers предназначена для облегчения работы с DHTML в различных браузерах. Она представляет собой набор функций и методов, написанных на JavaScript, которые унифицируют проведение различных операций с DHTML-объектами, т. е. позволяют программисту меньше задумываться о различных конкретных особенностях разных браузеров, что повышает продуктивность и уменьшает количество ошибок.

К примеру, чтобы узнать высоту содержимого документа, программист должен обратиться к следующим переменным:

document.body.scrollHeight, если скрипт выполняется в Microsoft Internet Explorer (далее сокращенно MSIE);
document.height для Netscape и Mozilla;
document.body.style.pixelHeight для Opera 6.

KLayers берет на себя эти рутинные действия. Используя ее, программист для тех же целей будет должен всего лишь вызвать функцию getDocumentHeight(), и ему будет возвращен нужный результат вне зависимости от того, в каком DHTML-браузере выполняется его скрипт.

Использование KLayers

Вставка в файл

Библиотека KLayers представляет собой JavaScript-программу, файл с которой подключается c помощью стандартных тегов

<script language="JavaScript" type="text/javascript" src="klayers.js"></script>

после чего ее функции и методы становятся доступны.

Какие браузеры поддерживаются?

В настоящий момент поддерживаются все основные DHTML-браузеры, а именно:

MSIE 4, 5, 6;
Netscape 4, 6, 7, Mozilla;
Opera 5, 6 (частично, что связано с недоработками в объектной модели этого браузера), 7 (полностью)

Другие браузеры пока официально не поддерживаются.

В случае выхода новых браузеров я добавлю их поддержку в новые версии KLayers, так что вам не придется переписывать свой код, скорее всего достаточно будет скачать новую версию KLayers.

KLayers - бесплатная?

Да. KLayers распространяется согласно GNU Lesser General Public License, что позволяет вам использовать ее в коммерческих и некоммерческих проектах, а также модифицировать.

Описание функций и методов KLayers

Флаги и переменные

Версия браузера

Следущие переменные содержат true, когда браузер

isDOM - поддерживает DOM1,
isMSIE - MSIE,
isNC4 - Netscape 4,
isNC6 = isMozilla - Netscape 6, 7 (Mozilla),
isNC - Netscape,
isOpera - Opera,
isOpera5 - Opera 5+,
isOpera6 - Opera 6+.
isOpera7 - Opera 7.

Начало отсчета экранных координат

Вы можете изменять переменные pageLeft и pageTop для смещения начала отсчета координат слоев. По умолчанию никакого смещения нет, в обеих переменных содержится 0.

Функции

Окно и документ

getWindowLeft([окно]) - x-координата верхнего левого угла рабочей области окна,
getWindowTop([окно]) - y-координата верхнего левого угла рабочей области окна,
getWindowWidth([окно]) - ширина окна или кадра (фрейма). Без необязательного параметра - ссылки на окно - возвращается ширина текущего окна (фрейма),
getWindowHeight([окно]) - высота окна или кадра (фрейма),
getDocumentWidth([окно]) - ширина содержимого документа,
getDocumentHeight([окно]) - высота содержимого документа,
getScrollX([окно]) - показания горизонтальной прокрутки документа,
getScrollY([окно]) - показания вертикальной прокрутки документа.

Пример - проскроллить окно до самого низа минус 100 пикселей:

S=getDocumentHeight()-getWindowHeight()-100
if(S>=0) self.scrollTo(S)

Служебные

initKLayers() - инициализация флагов и переменных. Должна вызываться автоматически, поэтому вызов этой функции имеет смысл только тогда, когда из-за багов браузера ее вызов не произошел. Возвращает true, если браузер поддерживается KLayers, и false, если нет.
KLayers - true или false в зависимости от того, поддерживается ли браузер библиотекой KLayers. Инициализируется функцией initKLayers().

Дополнительные

preloadImage(URL картинки) - загрузка картинки в кэш во избежание заторможенности при реализации mouseover'а.

Классы

Класс KLayer

Класс KLayer предназначен для инкапсуляции данных и логики для работы со свойствами слоя. Будем по историческим причинам здесь и далее именовать DHTML-объект слоем.

Имеет конструктор KLayer(), но для создания экземпляра класса лучше вызывать функцию-фабрику layer(). То есть если у нас имеется слой с именем mylayer, то для создания интерфейса к нему необходимо будет вызвать функцию layer("mylayer").

Имеется также написанная для лучшей совместимости с Netscape 4 функция layerFrom(имя слоя, адрес родительского слоя в DOM Netscape 4), предназначенная для ускоренного поиска нужного слоя в имеющейся в Netscape 4 иерархии вложенных слоев. К примеру - в слое xxx у нас есть слой yyy, а в нем, в свою очередь, есть слой zzz, тогда вызов слоя zzz будет выглядеть как

layerFrom("zzz", "document.layers.xxx.document.layers.yyy")

Если браузер - не Netscape 4, второй аргумент просто игнорируется. Просто же функция layer() ходит по всему дереву слоев, пока не найдет нужный, что иногда может занимать значительное время. Но надо отметить, что это имеет значение только тогда, когда имеются вложенные друг в друга слои.

В классе KLayer определены следующие поля и методы:

Поля:
- .object - ссылка на сам DHTML-объект (слой).
- .style, .css - ссылка на стили слоя.
- .path - строка - путь к слою в DOM текущего браузера, т. е. eval(layer.path)=layer.object
- .id - идентификатор слоя.
Чтение свойств слоя:
- .isExist(), .exists() - существует ли слой.
- .getLeft() - x-координата верхнего левого угла слоя относительно родительского элемента (если такой есть, иначе - относительно документа).
- .getTop() - y-координата верхнего левого угла слоя относительно родительского элемента.
- .getAbsoluteLeft() - x-координата верхнего левого угла слоя на странице.
- .getAbsoluteTop() - y-координата верхнего левого угла слоя на странице.
- .getWidth() - ширина содержимого слоя.
- .getHeight() - высота содержимого слоя.
- .getZIndex() - z-index слоя. Чем больше z-index, тем ближе к наблюдателю слой.
- .isVisible(), .getVisibility() - виден ли слой.
Установка свойств слоя:
- .setLeft(x), .moveX(...) - установить x-координату верхнего левого угла слоя на странице.
- .setTop(y), .moveY(...) - установить y-координату верхнего левого угла слоя на странице.
- .moveTo(x, y), .move(...) - установить координаты верхнего левого угла слоя на странице.
- .moveBy(x, y) - изменить координаты верхнего левого угла слоя на странице относительно прежних значений.
- .setZIndex(zIndex), .moveZ(...) - установить z-index слоя.
- .setVisibility(true / false) - установить видимость слоя.
- .show() - показать слой.
- .hide() - спрятать слой.
- .setBgColor(цвет) - установить цвет фона слоя (В Opera 5 какой-нибудь цвет фона, отличный от прозрачного, должен быть указан в CSS слоя, иначе цвет фона не будет устанавливаться).
- .setBgImage(url изображения) - установить фоновое изображение слоя (В Opera ниже версии 6 не работает).
- .setClip(top, right, bottom, left), .clip(...) - сделать только часть слоя видимой (напр. для прокрутки и т. д.) (не реализовано для Opera из-за отсутствия поддержки ею CSS-свойства clip)
- .scrollTo(windowLeft, windowTop, windowWidth, windowHeight, scrollX, scrollY), .scroll(...) - прокрутка слоя в прямоугольной области с координатами windowLeft, windowTop, windowWidth, windowHeight с показателями прокрутки scrollX и scrollY.
- .scrollBy(windowLeft, windowTop, windowWidth, windowHeight, scrollX, scrollY), .scrollByOffset(...) - прокрутка слоя из текущего положения с относительными отступами.
- .scrollByPercentage(windowLeft, windowTop, windowWidth, windowHeight, scrollX, scrollY) - прокрутка слоя из текущего положения с процентными отступами.
- .write(text) - запись в слой (не реализовано для Opera из-за отсутствия в ней возможности изменять содержимое слоя).
- .add(text) - дописывание к слою (тоже не реализовано для Opera).

Пример - переместить в точку с координатами 100, 200 и показать изначально невидимый слой:

<div id="mylayer" style="position: absolute; visibility: hidden; left:0px; top: 0px">LAYER</div>
<script>
var L=layer("mylayer")
L.moveTo(100,200)
L.show()
</script>

Класс KImage

Класс KImage предназначен для работы с изображениями. Он создан только для совместимости с Netscape 4, помещающего картинки из слоев (как и сами слои) в иерархическую структуру.

Есть конструктор KImage(), но для создания экземпляра класса рекомендуется вызывать функцию-фабрику image(). То есть если у нас имеется картинка с именем myimage, то для создания интерфейса к ней необходимо будет вызвать функцию image("myimage"), imageFrom("myimage", "адрес родительского слоя в DOM Netscape 4").

Поля:
- .object - ссылка на объект.
- .path - строка - адрес изображения в DOM текущего браузера, т. е. eval(image.path)=image.object
Методы:
- .isExist(), .exists() - существует ли объект.
- .getSrc(), .src() - URL изображения.
- .setSrc(URL), .load(...) - сменить URL изображения.

Примеры

Этот текст написан Кругловым С. А. Воспроизведение в сети не приветствуется. Подумайте сами - вот скопируете вы этот документ к себе на страницу, а завтра я какие-нибудь дополнения в оригинал внесу. И будет у вас старье висеть. При воспроизведении ссылка обязательна. Изложенное здесь является личным мнением либо личными наблюдениями автора. Автор не несет ответственности за возможный ущерб, вызванный применением положений данной статьи. Вместе с тем он надеется, что его труд будет для вас небесполезен. Если есть замечания или предложения - пишите.